@voidhash/mimic 0.0.1 → 0.0.3

package/dist/client/StateMonitor.mjs

@@ -0,0 +1,129 @@
+import { __export } from "../_virtual/rolldown_runtime.mjs";
+
+//#region src/client/StateMonitor.ts
+var StateMonitor_exports = /* @__PURE__ */ __export({
+	determineRecoveryAction: () => determineRecoveryAction,
+	make: () => make
+});
+/**
+* Creates a new StateMonitor.
+*/
+const make = (options = {}) => {
+	const { onEvent, healthCheckInterval = 5e3, stalePendingThreshold = 1e4, maxVersionGap = 10 } = options;
+	let _expectedVersion = 0;
+	let _pendingMap = /* @__PURE__ */ new Map();
+	let _isRecovering = false;
+	let _healthCheckHandle = null;
+	/**
+	* Emits an event if handler is provided.
+	*/
+	const emit = (event) => {
+		onEvent === null || onEvent === void 0 || onEvent(event);
+	};
+	/**
+	* Checks if there's a version gap indicating drift.
+	*/
+	const checkVersionGap = (receivedVersion) => {
+		const expectedNext = _expectedVersion + 1;
+		if (receivedVersion < expectedNext) return true;
+		if (receivedVersion > expectedNext + maxVersionGap) {
+			emit({
+				type: "drift_detected",
+				expectedVersion: expectedNext,
+				receivedVersion
+			});
+			return false;
+		}
+		return true;
+	};
+	/**
+	* Runs a health check.
+	*/
+	const runHealthCheck = () => {
+		const now = Date.now();
+		let oldestPendingMs = null;
+		for (const [id, info] of _pendingMap) {
+			const elapsed = now - info.sentAt;
+			if (oldestPendingMs === null || elapsed > oldestPendingMs) oldestPendingMs = elapsed;
+			if (elapsed > stalePendingThreshold) emit({
+				type: "pending_timeout",
+				transactionId: id,
+				elapsedMs: elapsed
+			});
+		}
+		emit({
+			type: "health_check",
+			pendingCount: _pendingMap.size,
+			oldestPendingMs
+		});
+	};
+	return {
+		onServerVersion: (version) => {
+			const isValid = checkVersionGap(version);
+			if (isValid) _expectedVersion = Math.max(_expectedVersion, version);
+			return isValid;
+		},
+		trackPending: (info) => {
+			_pendingMap.set(info.id, info);
+		},
+		untrackPending: (id) => {
+			_pendingMap.delete(id);
+		},
+		getStalePending: () => {
+			const now = Date.now();
+			const stale = [];
+			for (const info of _pendingMap.values()) if (now - info.sentAt > stalePendingThreshold) stale.push(info);
+			return stale;
+		},
+		getStatus: () => {
+			const now = Date.now();
+			let oldestPendingMs = null;
+			for (const info of _pendingMap.values()) {
+				const elapsed = now - info.sentAt;
+				if (oldestPendingMs === null || elapsed > oldestPendingMs) oldestPendingMs = elapsed;
+			}
+			const isHealthy = !_isRecovering && (oldestPendingMs === null || oldestPendingMs < stalePendingThreshold * 2);
+			return {
+				expectedVersion: _expectedVersion,
+				pendingCount: _pendingMap.size,
+				oldestPendingMs,
+				isHealthy,
+				isRecovering: _isRecovering
+			};
+		},
+		start: () => {
+			if (_healthCheckHandle !== null) return;
+			_healthCheckHandle = setInterval(runHealthCheck, healthCheckInterval);
+		},
+		stop: () => {
+			if (_healthCheckHandle !== null) {
+				clearInterval(_healthCheckHandle);
+				_healthCheckHandle = null;
+			}
+		},
+		reset: (newVersion) => {
+			_expectedVersion = newVersion;
+			_pendingMap.clear();
+			_isRecovering = false;
+			emit({
+				type: "recovery_completed",
+				version: newVersion
+			});
+		}
+	};
+};
+/**
+* Determines the appropriate recovery action based on current state.
+*/
+const determineRecoveryAction = (status, stalePending) => {
+	if (!status.isHealthy || stalePending.length > 3) return { type: "request_snapshot" };
+	if (stalePending.length > 0) return {
+		type: "drop_pending",
+		transactionIds: stalePending.map((p) => p.id)
+	};
+	return { type: "request_snapshot" };
+};
+
+//#endregion
+export { StateMonitor_exports };
+//# sourceMappingURL=StateMonitor.mjs.map

package/dist/client/StateMonitor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateMonitor.mjs","names":["_healthCheckHandle: ReturnType<typeof setInterval> | null","oldestPendingMs: number | null","stale: PendingInfo[]"],"sources":["../../src/client/StateMonitor.ts"],"sourcesContent":["import { StateDriftError } from \"./errors\";\n\n// =============================================================================\n// State Monitor Types\n// =============================================================================\n\n/**\n * Events emitted by the state monitor.\n */\nexport type StateMonitorEvent =\n  | { type: \"drift_detected\"; expectedVersion: number; receivedVersion: number }\n  | { type: \"recovery_started\" }\n  | { type: \"recovery_completed\"; version: number }\n  | { type: \"recovery_failed\"; error: Error }\n  | { type: \"pending_timeout\"; transactionId: string; elapsedMs: number }\n  | { type: \"health_check\"; pendingCount: number; oldestPendingMs: number | null };\n\n/**\n * Handler for state monitor events.\n */\nexport type StateMonitorEventHandler = (event: StateMonitorEvent) => void;\n\n/**\n * Options for creating a StateMonitor.\n */\nexport interface StateMonitorOptions {\n  /** Handler for monitor events */\n  readonly onEvent?: StateMonitorEventHandler;\n  /** Interval for health checks in ms (default: 5000) */\n  readonly healthCheckInterval?: number;\n  /** Threshold for considering a pending transaction \"stale\" in ms (default: 10000) */\n  readonly stalePendingThreshold?: number;\n  /** Maximum allowed version gap before triggering recovery (default: 10) */\n  readonly maxVersionGap?: number;\n}\n\n/**\n * Pending transaction info for monitoring.\n */\nexport interface PendingInfo {\n  readonly id: string;\n  readonly sentAt: number;\n}\n\n/**\n * A StateMonitor watches for state drift and triggers recovery.\n */\nexport interface StateMonitor {\n  /**\n   * Called when a server transaction is received.\n   * Returns true if the version is valid, false if drift is detected.\n   */\n  readonly onServerVersion: (version: number) => boolean;\n\n  /**\n   * Called when a pending transaction is added.\n   */\n  readonly trackPending: (info: PendingInfo) => void;\n\n  /**\n   * Called when a pending transaction is confirmed or rejected.\n   */\n  readonly untrackPending: (id: string) => void;\n\n  /**\n   * Returns pending transactions that have exceeded the stale threshold.\n   */\n  readonly getStalePending: () => PendingInfo[];\n\n  /**\n   * Returns current monitoring status.\n   */\n  readonly getStatus: () => StateMonitorStatus;\n\n  /**\n   * Starts the health check loop.\n   */\n  readonly start: () => void;\n\n  /**\n   * Stops the health check loop.\n   */\n  readonly stop: () => void;\n\n  /**\n   * Resets the monitor state (called after recovery).\n   */\n  readonly reset: (newVersion: number) => void;\n}\n\n/**\n * Current monitoring status.\n */\nexport interface StateMonitorStatus {\n  readonly expectedVersion: number;\n  readonly pendingCount: number;\n  readonly oldestPendingMs: number | null;\n  readonly isHealthy: boolean;\n  readonly isRecovering: boolean;\n}\n\n// =============================================================================\n// State Monitor Implementation\n// =============================================================================\n\n/**\n * Creates a new StateMonitor.\n */\nexport const make = (options: StateMonitorOptions = {}): StateMonitor => {\n  const {\n    onEvent,\n    healthCheckInterval = 5000,\n    stalePendingThreshold = 10000,\n    maxVersionGap = 10,\n  } = options;\n\n  // Internal state\n  let _expectedVersion = 0;\n  let _pendingMap = new Map<string, PendingInfo>();\n  let _isRecovering = false;\n  let _healthCheckHandle: ReturnType<typeof setInterval> | null = null;\n\n  /**\n   * Emits an event if handler is provided.\n   */\n  const emit = (event: StateMonitorEvent): void => {\n    onEvent?.(event);\n  };\n\n  /**\n   * Checks if there's a version gap indicating drift.\n   */\n  const checkVersionGap = (receivedVersion: number): boolean => {\n    // Expected next version is current + 1\n    const expectedNext = _expectedVersion + 1;\n\n    if (receivedVersion < expectedNext) {\n      // Duplicate or out-of-order - might be OK\n      return true;\n    }\n\n    if (receivedVersion > expectedNext + maxVersionGap) {\n      // Large gap - drift detected\n      emit({\n        type: \"drift_detected\",\n        expectedVersion: expectedNext,\n        receivedVersion,\n      });\n      return false;\n    }\n\n    // Small gap - could be network reordering, allow it\n    return true;\n  };\n\n  /**\n   * Runs a health check.\n   */\n  const runHealthCheck = (): void => {\n    const now = Date.now();\n    let oldestPendingMs: number | null = null;\n\n    // Find stale pending transactions\n    for (const [id, info] of _pendingMap) {\n      const elapsed = now - info.sentAt;\n\n      if (oldestPendingMs === null || elapsed > oldestPendingMs) {\n        oldestPendingMs = elapsed;\n      }\n\n      if (elapsed > stalePendingThreshold) {\n        emit({\n          type: \"pending_timeout\",\n          transactionId: id,\n          elapsedMs: elapsed,\n        });\n      }\n    }\n\n    emit({\n      type: \"health_check\",\n      pendingCount: _pendingMap.size,\n      oldestPendingMs,\n    });\n  };\n\n  const monitor: StateMonitor = {\n    onServerVersion: (version: number): boolean => {\n      const isValid = checkVersionGap(version);\n\n      if (isValid) {\n        // Update expected version\n        _expectedVersion = Math.max(_expectedVersion, version);\n      }\n\n      return isValid;\n    },\n\n    trackPending: (info: PendingInfo): void => {\n      _pendingMap.set(info.id, info);\n    },\n\n    untrackPending: (id: string): void => {\n      _pendingMap.delete(id);\n    },\n\n    getStalePending: (): PendingInfo[] => {\n      const now = Date.now();\n      const stale: PendingInfo[] = [];\n\n      for (const info of _pendingMap.values()) {\n        if (now - info.sentAt > stalePendingThreshold) {\n          stale.push(info);\n        }\n      }\n\n      return stale;\n    },\n\n    getStatus: (): StateMonitorStatus => {\n      const now = Date.now();\n      let oldestPendingMs: number | null = null;\n\n      for (const info of _pendingMap.values()) {\n        const elapsed = now - info.sentAt;\n        if (oldestPendingMs === null || elapsed > oldestPendingMs) {\n          oldestPendingMs = elapsed;\n        }\n      }\n\n      // Consider unhealthy if recovering or has very stale pending\n      const isHealthy =\n        !_isRecovering &&\n        (oldestPendingMs === null || oldestPendingMs < stalePendingThreshold * 2);\n\n      return {\n        expectedVersion: _expectedVersion,\n        pendingCount: _pendingMap.size,\n        oldestPendingMs,\n        isHealthy,\n        isRecovering: _isRecovering,\n      };\n    },\n\n    start: (): void => {\n      if (_healthCheckHandle !== null) return;\n\n      _healthCheckHandle = setInterval(runHealthCheck, healthCheckInterval);\n    },\n\n    stop: (): void => {\n      if (_healthCheckHandle !== null) {\n        clearInterval(_healthCheckHandle);\n        _healthCheckHandle = null;\n      }\n    },\n\n    reset: (newVersion: number): void => {\n      _expectedVersion = newVersion;\n      _pendingMap.clear();\n      _isRecovering = false;\n\n      emit({\n        type: \"recovery_completed\",\n        version: newVersion,\n      });\n    },\n  };\n\n  return monitor;\n};\n\n// =============================================================================\n// Recovery Strategy\n// =============================================================================\n\n/**\n * Recovery actions that can be taken.\n */\nexport type RecoveryAction =\n  | { type: \"request_snapshot\" }\n  | { type: \"retry_pending\"; transactionIds: string[] }\n  | { type: \"drop_pending\"; transactionIds: string[] };\n\n/**\n * Determines the appropriate recovery action based on current state.\n */\nexport const determineRecoveryAction = (\n  status: StateMonitorStatus,\n  stalePending: PendingInfo[]\n): RecoveryAction => {\n  // If recovering or unhealthy with stale pending, request full snapshot\n  if (!status.isHealthy || stalePending.length > 3) {\n    return { type: \"request_snapshot\" };\n  }\n\n  // If just a few stale pending, drop them\n  if (stalePending.length > 0) {\n    return {\n      type: \"drop_pending\",\n      transactionIds: stalePending.map((p) => p.id),\n    };\n  }\n\n  // Default: request snapshot for safety\n  return { type: \"request_snapshot\" };\n};\n"],"mappings":";;;;;;;;;;AA4GA,MAAa,QAAQ,UAA+B,EAAE,KAAmB;CACvE,MAAM,EACJ,SACA,sBAAsB,KACtB,wBAAwB,KACxB,gBAAgB,OACd;CAGJ,IAAI,mBAAmB;CACvB,IAAI,8BAAc,IAAI,KAA0B;CAChD,IAAI,gBAAgB;CACpB,IAAIA,qBAA4D;;;;CAKhE,MAAM,QAAQ,UAAmC;AAC/C,oDAAU,MAAM;;;;;CAMlB,MAAM,mBAAmB,oBAAqC;EAE5D,MAAM,eAAe,mBAAmB;AAExC,MAAI,kBAAkB,aAEpB,QAAO;AAGT,MAAI,kBAAkB,eAAe,eAAe;AAElD,QAAK;IACH,MAAM;IACN,iBAAiB;IACjB;IACD,CAAC;AACF,UAAO;;AAIT,SAAO;;;;;CAMT,MAAM,uBAA6B;EACjC,MAAM,MAAM,KAAK,KAAK;EACtB,IAAIC,kBAAiC;AAGrC,OAAK,MAAM,CAAC,IAAI,SAAS,aAAa;GACpC,MAAM,UAAU,MAAM,KAAK;AAE3B,OAAI,oBAAoB,QAAQ,UAAU,gBACxC,mBAAkB;AAGpB,OAAI,UAAU,sBACZ,MAAK;IACH,MAAM;IACN,eAAe;IACf,WAAW;IACZ,CAAC;;AAIN,OAAK;GACH,MAAM;GACN,cAAc,YAAY;GAC1B;GACD,CAAC;;AAsFJ,QAnF8B;EAC5B,kBAAkB,YAA6B;GAC7C,MAAM,UAAU,gBAAgB,QAAQ;AAExC,OAAI,QAEF,oBAAmB,KAAK,IAAI,kBAAkB,QAAQ;AAGxD,UAAO;;EAGT,eAAe,SAA4B;AACzC,eAAY,IAAI,KAAK,IAAI,KAAK;;EAGhC,iBAAiB,OAAqB;AACpC,eAAY,OAAO,GAAG;;EAGxB,uBAAsC;GACpC,MAAM,MAAM,KAAK,KAAK;GACtB,MAAMC,QAAuB,EAAE;AAE/B,QAAK,MAAM,QAAQ,YAAY,QAAQ,CACrC,KAAI,MAAM,KAAK,SAAS,sBACtB,OAAM,KAAK,KAAK;AAIpB,UAAO;;EAGT,iBAAqC;GACnC,MAAM,MAAM,KAAK,KAAK;GACtB,IAAID,kBAAiC;AAErC,QAAK,MAAM,QAAQ,YAAY,QAAQ,EAAE;IACvC,MAAM,UAAU,MAAM,KAAK;AAC3B,QAAI,oBAAoB,QAAQ,UAAU,gBACxC,mBAAkB;;GAKtB,MAAM,YACJ,CAAC,kBACA,oBAAoB,QAAQ,kBAAkB,wBAAwB;AAEzE,UAAO;IACL,iBAAiB;IACjB,cAAc,YAAY;IAC1B;IACA;IACA,cAAc;IACf;;EAGH,aAAmB;AACjB,OAAI,uBAAuB,KAAM;AAEjC,wBAAqB,YAAY,gBAAgB,oBAAoB;;EAGvE,YAAkB;AAChB,OAAI,uBAAuB,MAAM;AAC/B,kBAAc,mBAAmB;AACjC,yBAAqB;;;EAIzB,QAAQ,eAA6B;AACnC,sBAAmB;AACnB,eAAY,OAAO;AACnB,mBAAgB;AAEhB,QAAK;IACH,MAAM;IACN,SAAS;IACV,CAAC;;EAEL;;;;;AAoBH,MAAa,2BACX,QACA,iBACmB;AAEnB,KAAI,CAAC,OAAO,aAAa,aAAa,SAAS,EAC7C,QAAO,EAAE,MAAM,oBAAoB;AAIrC,KAAI,aAAa,SAAS,EACxB,QAAO;EACL,MAAM;EACN,gBAAgB,aAAa,KAAK,MAAM,EAAE,GAAG;EAC9C;AAIH,QAAO,EAAE,MAAM,oBAAoB"}

package/dist/client/Transport.cjs

@@ -0,0 +1,11 @@
+
+//#region src/client/Transport.ts
+var Transport_exports = {};
+
+//#endregion
+Object.defineProperty(exports, 'Transport_exports', {
+  enumerable: true,
+  get: function () {
+    return Transport_exports;
+  }
+});

package/dist/client/Transport.d.cts

@@ -0,0 +1,237 @@
+import { EncodedTransaction, Transaction } from "../Transaction.cjs";
+
+//#region src/client/Transport.d.ts
+declare namespace Transport_d_exports {
+  export { AuthMessage, AuthResultMessage, ClientMessage, EncodedClientMessage, EncodedServerMessage, EncodedSubmitTransactionMessage, EncodedTransactionMessage, ErrorMessage, PingMessage, PongMessage, PresenceClearMessage, PresenceEntry, PresenceRemoveMessage, PresenceSetMessage, PresenceSnapshotMessage, PresenceUpdateMessage, RequestSnapshotMessage, ServerMessage, SnapshotMessage, SubmitTransactionMessage, TransactionMessage, Transport, TransportEvent, TransportEventHandler, TransportOptions };
+}
+/**
+ * Message received when the server broadcasts a committed transaction.
+ */
+interface TransactionMessage {
+  readonly type: "transaction";
+  readonly transaction: Transaction;
+  /** Server-assigned version number for ordering */
+  readonly version: number;
+}
+/**
+ * Message received when requesting or receiving a full state snapshot.
+ */
+interface SnapshotMessage {
+  readonly type: "snapshot";
+  readonly state: unknown;
+  readonly version: number;
+}
+/**
+ * Message received when the server rejects a transaction.
+ */
+interface ErrorMessage {
+  readonly type: "error";
+  readonly transactionId: string;
+  readonly reason: string;
+}
+/**
+ * Message received in response to a ping (heartbeat).
+ */
+interface PongMessage {
+  readonly type: "pong";
+}
+/**
+ * Message received after authentication attempt.
+ */
+interface AuthResultMessage {
+  readonly type: "auth_result";
+  readonly success: boolean;
+  readonly error?: string;
+}
+/**
+ * A presence entry as transmitted.
+ */
+interface PresenceEntry {
+  /** The presence data */
+  readonly data: unknown;
+  /** Optional user ID from authentication */
+  readonly userId?: string;
+}
+/**
+ * Message received with initial presence state after authentication.
+ */
+interface PresenceSnapshotMessage {
+  readonly type: "presence_snapshot";
+  /** This connection's ID (used to identify self) */
+  readonly selfId: string;
+  /** Map of connectionId to presence entry */
+  readonly presences: Record<string, PresenceEntry>;
+}
+/**
+ * Message received when another user updates their presence.
+ */
+interface PresenceUpdateMessage {
+  readonly type: "presence_update";
+  /** The connection ID of the user who updated */
+  readonly id: string;
+  /** The presence data */
+  readonly data: unknown;
+  /** Optional user ID from authentication */
+  readonly userId?: string;
+}
+/**
+ * Message received when another user's presence is removed (disconnect).
+ */
+interface PresenceRemoveMessage {
+  readonly type: "presence_remove";
+  /** The connection ID of the user who disconnected */
+  readonly id: string;
+}
+/**
+ * Union of all possible server messages.
+ */
+type ServerMessage = TransactionMessage | SnapshotMessage | ErrorMessage | PongMessage | AuthResultMessage | PresenceSnapshotMessage | PresenceUpdateMessage | PresenceRemoveMessage;
+/**
+ * Message sent to submit a transaction to the server.
+ */
+interface SubmitTransactionMessage {
+  readonly type: "submit";
+  readonly transaction: Transaction;
+}
+/**
+ * Message sent to request a full state snapshot.
+ */
+interface RequestSnapshotMessage {
+  readonly type: "request_snapshot";
+}
+/**
+ * Message sent as heartbeat ping.
+ */
+interface PingMessage {
+  readonly type: "ping";
+}
+/**
+ * Message sent to authenticate with the server.
+ */
+interface AuthMessage {
+  readonly type: "auth";
+  readonly token: string;
+}
+/**
+ * Message sent to set/update this client's presence.
+ */
+interface PresenceSetMessage {
+  readonly type: "presence_set";
+  /** The presence data (validated against schema on client before sending) */
+  readonly data: unknown;
+}
+/**
+ * Message sent to clear this client's presence.
+ */
+interface PresenceClearMessage {
+  readonly type: "presence_clear";
+}
+/**
+ * Union of all possible client messages.
+ */
+type ClientMessage = SubmitTransactionMessage | RequestSnapshotMessage | PingMessage | AuthMessage | PresenceSetMessage | PresenceClearMessage;
+/**
+ * Encoded transaction message for network transport.
+ */
+interface EncodedTransactionMessage {
+  readonly type: "transaction";
+  readonly transaction: EncodedTransaction;
+  readonly version: number;
+}
+/**
+ * Encoded submit message for network transport.
+ */
+interface EncodedSubmitTransactionMessage {
+  readonly type: "submit";
+  readonly transaction: EncodedTransaction;
+}
+/**
+ * Union of all possible encoded server messages (for network transport).
+ */
+type EncodedServerMessage = EncodedTransactionMessage | SnapshotMessage | ErrorMessage | PongMessage | AuthResultMessage | PresenceSnapshotMessage | PresenceUpdateMessage | PresenceRemoveMessage;
+/**
+ * Union of all possible encoded client messages (for network transport).
+ */
+type EncodedClientMessage = EncodedSubmitTransactionMessage | RequestSnapshotMessage | PingMessage | AuthMessage | PresenceSetMessage | PresenceClearMessage;
+/**
+ * Abstract transport interface for server communication.
+ * Implementations can use WebSocket, HTTP, or any other protocol.
+ */
+interface Transport {
+  /**
+   * Sends a transaction to the server for processing.
+   * @param transaction - The transaction to submit
+   */
+  readonly send: (transaction: Transaction) => void;
+  /**
+   * Requests a full state snapshot from the server.
+   * Used for initial sync or recovery from drift.
+   */
+  readonly requestSnapshot: () => void;
+  /**
+   * Subscribes to messages from the server.
+   * @param handler - Callback invoked for each server message
+   * @returns Unsubscribe function
+   */
+  readonly subscribe: (handler: (message: ServerMessage) => void) => () => void;
+  /**
+   * Establishes connection to the server.
+   * @returns Promise that resolves when connected
+   */
+  readonly connect: () => Promise<void>;
+  /**
+   * Disconnects from the server.
+   */
+  readonly disconnect: () => void;
+  /**
+   * Returns whether the transport is currently connected.
+   */
+  readonly isConnected: () => boolean;
+  /**
+   * Sends presence data to the server.
+   * The data should be validated against the presence schema before calling.
+   * @param data - The presence data to set
+   */
+  readonly sendPresenceSet: (data: unknown) => void;
+  /**
+   * Clears this client's presence on the server.
+   */
+  readonly sendPresenceClear: () => void;
+}
+/**
+ * Events emitted by the transport for connection status.
+ */
+type TransportEvent = {
+  type: "connected";
+} | {
+  type: "disconnected";
+  reason?: string;
+} | {
+  type: "reconnecting";
+  attempt: number;
+} | {
+  type: "error";
+  error: Error;
+};
+/**
+ * Handler for transport events.
+ */
+type TransportEventHandler = (event: TransportEvent) => void;
+/**
+ * Options for creating a transport.
+ */
+interface TransportOptions {
+  /** Handler for transport lifecycle events */
+  readonly onEvent?: TransportEventHandler;
+  /** Timeout in milliseconds for connection attempts */
+  readonly connectionTimeout?: number;
+  /** Whether to automatically reconnect on disconnect */
+  readonly autoReconnect?: boolean;
+  /** Maximum number of reconnection attempts */
+  readonly maxReconnectAttempts?: number;
+  /** Base delay between reconnection attempts (ms) */
+  readonly reconnectDelay?: number;
+}
+//#endregion
+export { Transport, TransportOptions, Transport_d_exports };
+//# sourceMappingURL=Transport.d.cts.map

package/dist/client/Transport.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transport.d.cts","names":[],"sources":["../../src/client/Transport.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UASiB,kBAAA;;wBAEO;;;;;;;UAQP,eAAA;;;;;;;;UASA,YAAA;;;;;;;;UASA,WAAA;;AA5BjB;AAUA;AASA;AASA;AAOiB,UAAA,iBAAA,CAAiB;EAajB,SAAA,IAAA,EAAA,aAAa;EAUb,SAAA,OAAA,EAAA,OAAA;EAWA,SAAA,KAAA,CAAA,EAAA,MAAA;AAajB;AASA;;;AAGI,UA9Ca,aAAA,CA8Cb;EACA;EACA,SAAA,IAAA,EAAA,OAAA;EACA;EACA,SAAA,MAAA,CAAA,EAAA,MAAA;;;AAUJ;AAQA;AAOiB,UAjEA,uBAAA,CAiEW;EAOX,SAAA,IAAA,EAAW,mBAAA;EAYX;EASA,SAAA,MAAA,EAAA,MAAoB;EAOzB;EACR,SAAA,SAAA,EAhGkB,MAgGlB,CAAA,MAAA,EAhGiC,aAgGjC,CAAA;;;;;AAKA,UA/Fa,qBAAA,CA+Fb;EAAoB,SAAA,IAAA,EAAA,iBAAA;EASP;EASA,SAAA,EAAA,EAAA,MAAA;EAQL;EACR,SAAA,IAAA,EAAA,OAAA;EACA;EACA,SAAA,MAAA,CAAA,EAAA,MAAA;;;;;AAKA,UApHa,qBAAA,CAoHb;EAAqB,SAAA,IAAA,EAAA,iBAAA;EAKb;EACR,SAAA,EAAA,EAAA,MAAA;;;;;AAKA,KAtHQ,aAAA,GACR,kBAqHA,GApHA,eAoHA,GAnHA,YAmHA,GAlHA,WAkHA,GAjHA,iBAiHA,GAhHA,uBAgHA,GA/GA,qBA+GA,GA9GA,qBA8GA;;AAUJ;;AAkB0C,UAjIzB,wBAAA,CAiIyB;EAMhB,SAAA,IAAA,EAAA,QAAA;EAAO,SAAA,WAAA,EArIT,WAqIS;AAoCjC;AASA;AASA;;UArLiB,sBAAA;;;;;;UAOA,WAAA;;;;;;UAOA,WAAA;;;;;;;UAYA,kBAAA;;;;;;;;UASA,oBAAA;;;;;;KAOL,aAAA,GACR,2BACA,yBACA,cACA,cACA,qBACA;;;;UASa,yBAAA;;wBAEO;;;;;;UAOP,+BAAA;;wBAEO;;;;;KAMZ,oBAAA,GACR,4BACA,kBACA,eACA,cACA,oBACA,0BACA,wBACA;;;;KAKQ,oBAAA,GACR,kCACA,yBACA,cACA,cACA,qBACA;;;;;UAUa,SAAA;;;;;+BAKc;;;;;;;;;;;0CAaW;;;;;0BAMhB;;;;;;;;;;;;;;;;;;;;;;;KAoCd,cAAA;;;;;;;;;;SAIgB;;;;;KAKhB,qBAAA,WAAgC;;;;UAS3B,gBAAA;;qBAEI"}

package/dist/client/Transport.d.mts

@@ -0,0 +1,237 @@
+import { EncodedTransaction, Transaction } from "../Transaction.mjs";
+
+//#region src/client/Transport.d.ts
+declare namespace Transport_d_exports {
+  export { AuthMessage, AuthResultMessage, ClientMessage, EncodedClientMessage, EncodedServerMessage, EncodedSubmitTransactionMessage, EncodedTransactionMessage, ErrorMessage, PingMessage, PongMessage, PresenceClearMessage, PresenceEntry, PresenceRemoveMessage, PresenceSetMessage, PresenceSnapshotMessage, PresenceUpdateMessage, RequestSnapshotMessage, ServerMessage, SnapshotMessage, SubmitTransactionMessage, TransactionMessage, Transport, TransportEvent, TransportEventHandler, TransportOptions };
+}
+/**
+ * Message received when the server broadcasts a committed transaction.
+ */
+interface TransactionMessage {
+  readonly type: "transaction";
+  readonly transaction: Transaction;
+  /** Server-assigned version number for ordering */
+  readonly version: number;
+}
+/**
+ * Message received when requesting or receiving a full state snapshot.
+ */
+interface SnapshotMessage {
+  readonly type: "snapshot";
+  readonly state: unknown;
+  readonly version: number;
+}
+/**
+ * Message received when the server rejects a transaction.
+ */
+interface ErrorMessage {
+  readonly type: "error";
+  readonly transactionId: string;
+  readonly reason: string;
+}
+/**
+ * Message received in response to a ping (heartbeat).
+ */
+interface PongMessage {
+  readonly type: "pong";
+}
+/**
+ * Message received after authentication attempt.
+ */
+interface AuthResultMessage {
+  readonly type: "auth_result";
+  readonly success: boolean;
+  readonly error?: string;
+}
+/**
+ * A presence entry as transmitted.
+ */
+interface PresenceEntry {
+  /** The presence data */
+  readonly data: unknown;
+  /** Optional user ID from authentication */
+  readonly userId?: string;
+}
+/**
+ * Message received with initial presence state after authentication.
+ */
+interface PresenceSnapshotMessage {
+  readonly type: "presence_snapshot";
+  /** This connection's ID (used to identify self) */
+  readonly selfId: string;
+  /** Map of connectionId to presence entry */
+  readonly presences: Record<string, PresenceEntry>;
+}
+/**
+ * Message received when another user updates their presence.
+ */
+interface PresenceUpdateMessage {
+  readonly type: "presence_update";
+  /** The connection ID of the user who updated */
+  readonly id: string;
+  /** The presence data */
+  readonly data: unknown;
+  /** Optional user ID from authentication */
+  readonly userId?: string;
+}
+/**
+ * Message received when another user's presence is removed (disconnect).
+ */
+interface PresenceRemoveMessage {
+  readonly type: "presence_remove";
+  /** The connection ID of the user who disconnected */
+  readonly id: string;
+}
+/**
+ * Union of all possible server messages.
+ */
+type ServerMessage = TransactionMessage | SnapshotMessage | ErrorMessage | PongMessage | AuthResultMessage | PresenceSnapshotMessage | PresenceUpdateMessage | PresenceRemoveMessage;
+/**
+ * Message sent to submit a transaction to the server.
+ */
+interface SubmitTransactionMessage {
+  readonly type: "submit";
+  readonly transaction: Transaction;
+}
+/**
+ * Message sent to request a full state snapshot.
+ */
+interface RequestSnapshotMessage {
+  readonly type: "request_snapshot";
+}
+/**
+ * Message sent as heartbeat ping.
+ */
+interface PingMessage {
+  readonly type: "ping";
+}
+/**
+ * Message sent to authenticate with the server.
+ */
+interface AuthMessage {
+  readonly type: "auth";
+  readonly token: string;
+}
+/**
+ * Message sent to set/update this client's presence.
+ */
+interface PresenceSetMessage {
+  readonly type: "presence_set";
+  /** The presence data (validated against schema on client before sending) */
+  readonly data: unknown;
+}
+/**
+ * Message sent to clear this client's presence.
+ */
+interface PresenceClearMessage {
+  readonly type: "presence_clear";
+}
+/**
+ * Union of all possible client messages.
+ */
+type ClientMessage = SubmitTransactionMessage | RequestSnapshotMessage | PingMessage | AuthMessage | PresenceSetMessage | PresenceClearMessage;
+/**
+ * Encoded transaction message for network transport.
+ */
+interface EncodedTransactionMessage {
+  readonly type: "transaction";
+  readonly transaction: EncodedTransaction;
+  readonly version: number;
+}
+/**
+ * Encoded submit message for network transport.
+ */
+interface EncodedSubmitTransactionMessage {
+  readonly type: "submit";
+  readonly transaction: EncodedTransaction;
+}
+/**
+ * Union of all possible encoded server messages (for network transport).
+ */
+type EncodedServerMessage = EncodedTransactionMessage | SnapshotMessage | ErrorMessage | PongMessage | AuthResultMessage | PresenceSnapshotMessage | PresenceUpdateMessage | PresenceRemoveMessage;
+/**
+ * Union of all possible encoded client messages (for network transport).
+ */
+type EncodedClientMessage = EncodedSubmitTransactionMessage | RequestSnapshotMessage | PingMessage | AuthMessage | PresenceSetMessage | PresenceClearMessage;
+/**
+ * Abstract transport interface for server communication.
+ * Implementations can use WebSocket, HTTP, or any other protocol.
+ */
+interface Transport {
+  /**
+   * Sends a transaction to the server for processing.
+   * @param transaction - The transaction to submit
+   */
+  readonly send: (transaction: Transaction) => void;
+  /**
+   * Requests a full state snapshot from the server.
+   * Used for initial sync or recovery from drift.
+   */
+  readonly requestSnapshot: () => void;
+  /**
+   * Subscribes to messages from the server.
+   * @param handler - Callback invoked for each server message
+   * @returns Unsubscribe function
+   */
+  readonly subscribe: (handler: (message: ServerMessage) => void) => () => void;
+  /**
+   * Establishes connection to the server.
+   * @returns Promise that resolves when connected
+   */
+  readonly connect: () => Promise<void>;
+  /**
+   * Disconnects from the server.
+   */
+  readonly disconnect: () => void;
+  /**
+   * Returns whether the transport is currently connected.
+   */
+  readonly isConnected: () => boolean;
+  /**
+   * Sends presence data to the server.
+   * The data should be validated against the presence schema before calling.
+   * @param data - The presence data to set
+   */
+  readonly sendPresenceSet: (data: unknown) => void;
+  /**
+   * Clears this client's presence on the server.
+   */
+  readonly sendPresenceClear: () => void;
+}
+/**
+ * Events emitted by the transport for connection status.
+ */
+type TransportEvent = {
+  type: "connected";
+} | {
+  type: "disconnected";
+  reason?: string;
+} | {
+  type: "reconnecting";
+  attempt: number;
+} | {
+  type: "error";
+  error: Error;
+};
+/**
+ * Handler for transport events.
+ */
+type TransportEventHandler = (event: TransportEvent) => void;
+/**
+ * Options for creating a transport.
+ */
+interface TransportOptions {
+  /** Handler for transport lifecycle events */
+  readonly onEvent?: TransportEventHandler;
+  /** Timeout in milliseconds for connection attempts */
+  readonly connectionTimeout?: number;
+  /** Whether to automatically reconnect on disconnect */
+  readonly autoReconnect?: boolean;
+  /** Maximum number of reconnection attempts */
+  readonly maxReconnectAttempts?: number;
+  /** Base delay between reconnection attempts (ms) */
+  readonly reconnectDelay?: number;
+}
+//#endregion
+export { Transport, TransportOptions, Transport_d_exports };
+//# sourceMappingURL=Transport.d.mts.map

package/dist/client/Transport.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transport.d.mts","names":[],"sources":["../../src/client/Transport.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UASiB,kBAAA;;wBAEO;;;;;;;UAQP,eAAA;;;;;;;;UASA,YAAA;;;;;;;;UASA,WAAA;;AA5BjB;AAUA;AASA;AASA;AAOiB,UAAA,iBAAA,CAAiB;EAajB,SAAA,IAAA,EAAA,aAAa;EAUb,SAAA,OAAA,EAAA,OAAA;EAWA,SAAA,KAAA,CAAA,EAAA,MAAA;AAajB;AASA;;;AAGI,UA9Ca,aAAA,CA8Cb;EACA;EACA,SAAA,IAAA,EAAA,OAAA;EACA;EACA,SAAA,MAAA,CAAA,EAAA,MAAA;;;AAUJ;AAQA;AAOiB,UAjEA,uBAAA,CAiEW;EAOX,SAAA,IAAA,EAAW,mBAAA;EAYX;EASA,SAAA,MAAA,EAAA,MAAoB;EAOzB;EACR,SAAA,SAAA,EAhGkB,MAgGlB,CAAA,MAAA,EAhGiC,aAgGjC,CAAA;;;;;AAKA,UA/Fa,qBAAA,CA+Fb;EAAoB,SAAA,IAAA,EAAA,iBAAA;EASP;EASA,SAAA,EAAA,EAAA,MAAA;EAQL;EACR,SAAA,IAAA,EAAA,OAAA;EACA;EACA,SAAA,MAAA,CAAA,EAAA,MAAA;;;;;AAKA,UApHa,qBAAA,CAoHb;EAAqB,SAAA,IAAA,EAAA,iBAAA;EAKb;EACR,SAAA,EAAA,EAAA,MAAA;;;;;AAKA,KAtHQ,aAAA,GACR,kBAqHA,GApHA,eAoHA,GAnHA,YAmHA,GAlHA,WAkHA,GAjHA,iBAiHA,GAhHA,uBAgHA,GA/GA,qBA+GA,GA9GA,qBA8GA;;AAUJ;;AAkB0C,UAjIzB,wBAAA,CAiIyB;EAMhB,SAAA,IAAA,EAAA,QAAA;EAAO,SAAA,WAAA,EArIT,WAqIS;AAoCjC;AASA;AASA;;UArLiB,sBAAA;;;;;;UAOA,WAAA;;;;;;UAOA,WAAA;;;;;;;UAYA,kBAAA;;;;;;;;UASA,oBAAA;;;;;;KAOL,aAAA,GACR,2BACA,yBACA,cACA,cACA,qBACA;;;;UASa,yBAAA;;wBAEO;;;;;;UAOP,+BAAA;;wBAEO;;;;;KAMZ,oBAAA,GACR,4BACA,kBACA,eACA,cACA,oBACA,0BACA,wBACA;;;;KAKQ,oBAAA,GACR,kCACA,yBACA,cACA,cACA,qBACA;;;;;UAUa,SAAA;;;;;+BAKc;;;;;;;;;;;0CAaW;;;;;0BAMhB;;;;;;;;;;;;;;;;;;;;;;;KAoCd,cAAA;;;;;;;;;;SAIgB;;;;;KAKhB,qBAAA,WAAgC;;;;UAS3B,gBAAA;;qBAEI"}

package/dist/client/Transport.mjs

@@ -0,0 +1,6 @@
+//#region src/client/Transport.ts
+var Transport_exports = {};
+
+//#endregion
+export { Transport_exports };
+//# sourceMappingURL=Transport.mjs.map

package/dist/client/Transport.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transport.mjs","names":[],"sources":["../../src/client/Transport.ts"],"sourcesContent":["import type * as Transaction from \"../Transaction\";\n\n// =============================================================================\n// Server Messages\n// =============================================================================\n\n/**\n * Message received when the server broadcasts a committed transaction.\n */\nexport interface TransactionMessage {\n  readonly type: \"transaction\";\n  readonly transaction: Transaction.Transaction;\n  /** Server-assigned version number for ordering */\n  readonly version: number;\n}\n\n/**\n * Message received when requesting or receiving a full state snapshot.\n */\nexport interface SnapshotMessage {\n  readonly type: \"snapshot\";\n  readonly state: unknown;\n  readonly version: number;\n}\n\n/**\n * Message received when the server rejects a transaction.\n */\nexport interface ErrorMessage {\n  readonly type: \"error\";\n  readonly transactionId: string;\n  readonly reason: string;\n}\n\n/**\n * Message received in response to a ping (heartbeat).\n */\nexport interface PongMessage {\n  readonly type: \"pong\";\n}\n\n/**\n * Message received after authentication attempt.\n */\nexport interface AuthResultMessage {\n  readonly type: \"auth_result\";\n  readonly success: boolean;\n  readonly error?: string;\n}\n\n// =============================================================================\n// Presence Server Messages\n// =============================================================================\n\n/**\n * A presence entry as transmitted.\n */\nexport interface PresenceEntry {\n  /** The presence data */\n  readonly data: unknown;\n  /** Optional user ID from authentication */\n  readonly userId?: string;\n}\n\n/**\n * Message received with initial presence state after authentication.\n */\nexport interface PresenceSnapshotMessage {\n  readonly type: \"presence_snapshot\";\n  /** This connection's ID (used to identify self) */\n  readonly selfId: string;\n  /** Map of connectionId to presence entry */\n  readonly presences: Record<string, PresenceEntry>;\n}\n\n/**\n * Message received when another user updates their presence.\n */\nexport interface PresenceUpdateMessage {\n  readonly type: \"presence_update\";\n  /** The connection ID of the user who updated */\n  readonly id: string;\n  /** The presence data */\n  readonly data: unknown;\n  /** Optional user ID from authentication */\n  readonly userId?: string;\n}\n\n/**\n * Message received when another user's presence is removed (disconnect).\n */\nexport interface PresenceRemoveMessage {\n  readonly type: \"presence_remove\";\n  /** The connection ID of the user who disconnected */\n  readonly id: string;\n}\n\n/**\n * Union of all possible server messages.\n */\nexport type ServerMessage =\n  | TransactionMessage\n  | SnapshotMessage\n  | ErrorMessage\n  | PongMessage\n  | AuthResultMessage\n  | PresenceSnapshotMessage\n  | PresenceUpdateMessage\n  | PresenceRemoveMessage;\n\n// =============================================================================\n// Client Messages\n// =============================================================================\n\n/**\n * Message sent to submit a transaction to the server.\n */\nexport interface SubmitTransactionMessage {\n  readonly type: \"submit\";\n  readonly transaction: Transaction.Transaction;\n}\n\n/**\n * Message sent to request a full state snapshot.\n */\nexport interface RequestSnapshotMessage {\n  readonly type: \"request_snapshot\";\n}\n\n/**\n * Message sent as heartbeat ping.\n */\nexport interface PingMessage {\n  readonly type: \"ping\";\n}\n\n/**\n * Message sent to authenticate with the server.\n */\nexport interface AuthMessage {\n  readonly type: \"auth\";\n  readonly token: string;\n}\n\n// =============================================================================\n// Presence Client Messages\n// =============================================================================\n\n/**\n * Message sent to set/update this client's presence.\n */\nexport interface PresenceSetMessage {\n  readonly type: \"presence_set\";\n  /** The presence data (validated against schema on client before sending) */\n  readonly data: unknown;\n}\n\n/**\n * Message sent to clear this client's presence.\n */\nexport interface PresenceClearMessage {\n  readonly type: \"presence_clear\";\n}\n\n/**\n * Union of all possible client messages.\n */\nexport type ClientMessage =\n  | SubmitTransactionMessage\n  | RequestSnapshotMessage\n  | PingMessage\n  | AuthMessage\n  | PresenceSetMessage\n  | PresenceClearMessage;\n\n// =============================================================================\n// Encoded Message Types (for network transport)\n// =============================================================================\n\n/**\n * Encoded transaction message for network transport.\n */\nexport interface EncodedTransactionMessage {\n  readonly type: \"transaction\";\n  readonly transaction: Transaction.EncodedTransaction;\n  readonly version: number;\n}\n\n/**\n * Encoded submit message for network transport.\n */\nexport interface EncodedSubmitTransactionMessage {\n  readonly type: \"submit\";\n  readonly transaction: Transaction.EncodedTransaction;\n}\n\n/**\n * Union of all possible encoded server messages (for network transport).\n */\nexport type EncodedServerMessage =\n  | EncodedTransactionMessage\n  | SnapshotMessage\n  | ErrorMessage\n  | PongMessage\n  | AuthResultMessage\n  | PresenceSnapshotMessage\n  | PresenceUpdateMessage\n  | PresenceRemoveMessage;\n\n/**\n * Union of all possible encoded client messages (for network transport).\n */\nexport type EncodedClientMessage =\n  | EncodedSubmitTransactionMessage\n  | RequestSnapshotMessage\n  | PingMessage\n  | AuthMessage\n  | PresenceSetMessage\n  | PresenceClearMessage;\n\n// =============================================================================\n// Transport Interface\n// =============================================================================\n\n/**\n * Abstract transport interface for server communication.\n * Implementations can use WebSocket, HTTP, or any other protocol.\n */\nexport interface Transport {\n  /**\n   * Sends a transaction to the server for processing.\n   * @param transaction - The transaction to submit\n   */\n  readonly send: (transaction: Transaction.Transaction) => void;\n\n  /**\n   * Requests a full state snapshot from the server.\n   * Used for initial sync or recovery from drift.\n   */\n  readonly requestSnapshot: () => void;\n\n  /**\n   * Subscribes to messages from the server.\n   * @param handler - Callback invoked for each server message\n   * @returns Unsubscribe function\n   */\n  readonly subscribe: (handler: (message: ServerMessage) => void) => () => void;\n\n  /**\n   * Establishes connection to the server.\n   * @returns Promise that resolves when connected\n   */\n  readonly connect: () => Promise<void>;\n\n  /**\n   * Disconnects from the server.\n   */\n  readonly disconnect: () => void;\n\n  /**\n   * Returns whether the transport is currently connected.\n   */\n  readonly isConnected: () => boolean;\n\n  // ===========================================================================\n  // Presence Methods\n  // ===========================================================================\n\n  /**\n   * Sends presence data to the server.\n   * The data should be validated against the presence schema before calling.\n   * @param data - The presence data to set\n   */\n  readonly sendPresenceSet: (data: unknown) => void;\n\n  /**\n   * Clears this client's presence on the server.\n   */\n  readonly sendPresenceClear: () => void;\n}\n\n// =============================================================================\n// Transport Events\n// =============================================================================\n\n/**\n * Events emitted by the transport for connection status.\n */\nexport type TransportEvent =\n  | { type: \"connected\" }\n  | { type: \"disconnected\"; reason?: string }\n  | { type: \"reconnecting\"; attempt: number }\n  | { type: \"error\"; error: Error };\n\n/**\n * Handler for transport events.\n */\nexport type TransportEventHandler = (event: TransportEvent) => void;\n\n// =============================================================================\n// Transport Options\n// =============================================================================\n\n/**\n * Options for creating a transport.\n */\nexport interface TransportOptions {\n  /** Handler for transport lifecycle events */\n  readonly onEvent?: TransportEventHandler;\n  /** Timeout in milliseconds for connection attempts */\n  readonly connectionTimeout?: number;\n  /** Whether to automatically reconnect on disconnect */\n  readonly autoReconnect?: boolean;\n  /** Maximum number of reconnection attempts */\n  readonly maxReconnectAttempts?: number;\n  /** Base delay between reconnection attempts (ms) */\n  readonly reconnectDelay?: number;\n}\n"],"mappings":""}