@korajs/sync 0.3.2 → 0.5.0

package/dist/index.js

@@ -3,6 +3,7 @@ import {
 } from "./chunk-TU345YUC.js";
 
 // src/types.ts
+import { KoraError } from "@korajs/core";
 var SYNC_STATES = [
   "disconnected",
   "connecting",
@@ -11,7 +12,194 @@ var SYNC_STATES = [
   "streaming",
   "error"
 ];
-var SYNC_STATUSES = ["connected", "syncing", "synced", "offline", "error"];
+var SYNC_STATUSES = [
+  "connected",
+  "syncing",
+  "synced",
+  "offline",
+  "error",
+  "schema-mismatch"
+];
+var ScopeViolationError = class extends KoraError {
+  constructor(operationId, collection, scope, message) {
+    super(
+      message ?? `Operation "${operationId}" in collection "${collection}" violates sync scope`,
+      "SCOPE_VIOLATION",
+      { operationId, collection, scope }
+    );
+    this.operationId = operationId;
+    this.collection = collection;
+    this.scope = scope;
+    this.name = "ScopeViolationError";
+  }
+  operationId;
+  collection;
+  scope;
+};
+var InvalidScopeError = class extends KoraError {
+  constructor(message, context) {
+    super(message, "INVALID_SCOPE", context);
+    this.name = "InvalidScopeError";
+  }
+};
+
+// src/scopes/scope-filter.ts
+function operationMatchesScope(op, scopeMap, fullRecord) {
+  if (!scopeMap) return true;
+  const collectionScope = scopeMap[op.collection];
+  if (!collectionScope) return false;
+  if (Object.keys(collectionScope).length === 0) return true;
+  const snapshot = buildSnapshot(op, fullRecord ?? void 0);
+  if (!snapshot) return false;
+  for (const [field, expected] of Object.entries(collectionScope)) {
+    if (snapshot[field] !== expected) {
+      return false;
+    }
+  }
+  return true;
+}
+function filterOperationsByScope(operations, scopeMap) {
+  if (!scopeMap) return operations;
+  return operations.filter((op) => operationMatchesScope(op, scopeMap));
+}
+function buildSnapshot(op, fullRecord) {
+  const previous = asRecord(op.previousData);
+  const next = asRecord(op.data);
+  if (!previous && !next && !fullRecord) return null;
+  return {
+    ...fullRecord ?? {},
+    ...previous ?? {},
+    ...next ?? {}
+  };
+}
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+
+// src/scopes/query-subset.ts
+function asRecord2(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function buildSnapshot2(op, fullRecord) {
+  const previous = asRecord2(op.previousData);
+  const next = asRecord2(op.data);
+  if (!previous && !next && !fullRecord) {
+    return null;
+  }
+  return {
+    ...fullRecord ?? {},
+    ...previous ?? {},
+    ...next ?? {}
+  };
+}
+function recordMatchesWhere(snapshot, where) {
+  for (const [field, expected] of Object.entries(where)) {
+    if (snapshot[field] !== expected) {
+      return false;
+    }
+  }
+  return true;
+}
+function operationMatchesQuerySubsets(op, subsets, fullRecord) {
+  if (!subsets || subsets.length === 0) {
+    return true;
+  }
+  const collectionSubsets = subsets.filter((subset) => subset.collection === op.collection);
+  if (collectionSubsets.length === 0) {
+    return true;
+  }
+  const snapshot = buildSnapshot2(op, fullRecord);
+  if (!snapshot) {
+    return false;
+  }
+  return collectionSubsets.some((subset) => recordMatchesWhere(snapshot, subset.where));
+}
+function dedupeQuerySubsets(subsets) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const subset of subsets) {
+    const key = `${subset.collection}:${JSON.stringify(subset.where)}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    result.push(subset);
+  }
+  return result;
+}
+
+// src/delta/delta-cursor.ts
+function bytesToBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlToBytes(value) {
+  const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function encodeDeltaCursor(cursor) {
+  const json = JSON.stringify(cursor);
+  return bytesToBase64Url(new TextEncoder().encode(json));
+}
+function decodeDeltaCursor(value) {
+  if (!value) {
+    return null;
+  }
+  try {
+    const json = new TextDecoder().decode(base64UrlToBytes(value));
+    const parsed = JSON.parse(json);
+    if (typeof parsed !== "object" || parsed === null || typeof parsed.lastOperationId !== "string" || typeof parsed.batchIndex !== "number") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function sliceOperationsAfterCursor(operations, cursor) {
+  if (!cursor) {
+    return operations;
+  }
+  const index = operations.findIndex((op) => op.id === cursor.lastOperationId);
+  if (index === -1) {
+    return operations;
+  }
+  return operations.slice(index + 1);
+}
+function createDeltaCursorFromBatch(operations, batchIndex) {
+  const last = operations[operations.length - 1];
+  if (!last) {
+    return null;
+  }
+  return {
+    lastOperationId: last.id,
+    batchIndex
+  };
+}
+
+// src/protocol/schema-version.ts
+var SCHEMA_MISMATCH_PREFIX = "SCHEMA_MISMATCH";
+function isSchemaMismatchReject(rejectReason) {
+  return rejectReason?.startsWith(SCHEMA_MISMATCH_PREFIX) === true;
+}
+function isClientSchemaVersionSupported(clientVersion, supported) {
+  return clientVersion >= supported.min && clientVersion <= supported.max;
+}
 
 // src/protocol/messages.ts
 function isSyncMessage(value) {
@@ -29,6 +217,10 @@ function isSyncMessage(value) {
       return isAcknowledgmentMessage(value);
     case "error":
       return isErrorMessage(value);
+    case "awareness-update":
+      return isAwarenessUpdateMessage(value);
+    case "yjs-doc-update":
+      return isYjsDocUpdateMessage(value);
     default:
       return false;
   }
@@ -58,6 +250,16 @@ function isErrorMessage(value) {
   const msg = value;
   return msg.type === "error" && typeof msg.messageId === "string" && typeof msg.code === "string" && typeof msg.message === "string" && typeof msg.retriable === "boolean";
 }
+function isAwarenessUpdateMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "awareness-update" && typeof msg.messageId === "string" && typeof msg.clientId === "number" && typeof msg.states === "object" && msg.states !== null && !Array.isArray(msg.states);
+}
+function isYjsDocUpdateMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "yjs-doc-update" && typeof msg.messageId === "string" && typeof msg.collection === "string" && typeof msg.recordId === "string" && typeof msg.field === "string" && typeof msg.update === "string";
+}
 
 // src/protocol/serializer.ts
 import { SyncError } from "@korajs/core";
@@ -73,6 +275,84 @@ function versionVectorToWire(vector) {
 function wireToVersionVector(wire) {
   return new Map(Object.entries(wire));
 }
+var WIRE_BYTES_KEY = "__kora_bytes__";
+function toBase64(bytes) {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+function fromBase64(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+function serializeWireRecord(record) {
+  if (!record) {
+    return null;
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(record)) {
+    out[key] = serializeWireValue(value);
+  }
+  return out;
+}
+function serializeWireValue(value) {
+  if (value instanceof Uint8Array) {
+    return { [WIRE_BYTES_KEY]: toBase64(value) };
+  }
+  if (value instanceof ArrayBuffer) {
+    return { [WIRE_BYTES_KEY]: toBase64(new Uint8Array(value)) };
+  }
+  return value;
+}
+function deserializeWireRecord(record) {
+  if (!record) {
+    return null;
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(record)) {
+    out[key] = deserializeWireValue(value);
+  }
+  return out;
+}
+function deserializeWireValue(value) {
+  if (typeof value === "object" && value !== null && WIRE_BYTES_KEY in value) {
+    const encoded = value[WIRE_BYTES_KEY];
+    if (typeof encoded === "string") {
+      return fromBase64(encoded);
+    }
+  }
+  if (isLegacyIndexedByteRecord(value)) {
+    return legacyIndexedByteRecordToUint8Array(value);
+  }
+  return value;
+}
+function isLegacyIndexedByteRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    return false;
+  }
+  return entries.every(([key, entryValue]) => {
+    const index = Number(key);
+    return Number.isInteger(index) && index >= 0 && typeof entryValue === "number";
+  });
+}
+function legacyIndexedByteRecordToUint8Array(value) {
+  const maxIndex = Math.max(...Object.keys(value).map((key) => Number(key)));
+  const bytes = new Uint8Array(maxIndex + 1);
+  for (const [key, entryValue] of Object.entries(value)) {
+    bytes[Number(key)] = entryValue;
+  }
+  return bytes;
+}
 var JsonMessageSerializer = class {
   encode(message) {
     return JSON.stringify(message);
@@ -101,8 +381,8 @@ var JsonMessageSerializer = class {
       type: op.type,
       collection: op.collection,
       recordId: op.recordId,
-      data: op.data,
-      previousData: op.previousData,
+      data: serializeWireRecord(op.data),
+      previousData: serializeWireRecord(op.previousData),
       timestamp: {
         wallTime: op.timestamp.wallTime,
         logical: op.timestamp.logical,
@@ -110,7 +390,10 @@ var JsonMessageSerializer = class {
       },
       sequenceNumber: op.sequenceNumber,
       causalDeps: [...op.causalDeps],
-      schemaVersion: op.schemaVersion
+      schemaVersion: op.schemaVersion,
+      ...op.atomicOps !== void 0 ? { atomicOps: op.atomicOps } : {},
+      ...op.transactionId !== void 0 ? { transactionId: op.transactionId } : {},
+      ...op.mutationName !== void 0 ? { mutationName: op.mutationName } : {}
     };
   }
   decodeOperation(serialized) {
@@ -120,8 +403,8 @@ var JsonMessageSerializer = class {
       type: serialized.type,
       collection: serialized.collection,
       recordId: serialized.recordId,
-      data: serialized.data,
-      previousData: serialized.previousData,
+      data: deserializeWireRecord(serialized.data),
+      previousData: deserializeWireRecord(serialized.previousData),
       timestamp: {
         wallTime: serialized.timestamp.wallTime,
         logical: serialized.timestamp.logical,
@@ -129,7 +412,10 @@ var JsonMessageSerializer = class {
       },
       sequenceNumber: serialized.sequenceNumber,
       causalDeps: [...serialized.causalDeps],
-      schemaVersion: serialized.schemaVersion
+      schemaVersion: serialized.schemaVersion,
+      ...serialized.atomicOps !== void 0 ? { atomicOps: serialized.atomicOps } : {},
+      ...serialized.transactionId !== void 0 ? { transactionId: serialized.transactionId } : {},
+      ...serialized.mutationName !== void 0 ? { mutationName: serialized.mutationName } : {}
     };
   }
 };
@@ -193,7 +479,10 @@ function toProtoEnvelope(message) {
         type: message.type,
         messageId: message.messageId,
         nodeId: message.nodeId,
-        versionVector: Object.entries(message.versionVector).map(([key, value]) => ({ key, value })),
+        versionVector: Object.entries(message.versionVector).map(([key, value]) => ({
+          key,
+          value
+        })),
         schemaVersion: message.schemaVersion,
         authToken: message.authToken,
         supportedWireFormats: message.supportedWireFormats
@@ -203,7 +492,10 @@ function toProtoEnvelope(message) {
         type: message.type,
         messageId: message.messageId,
         nodeId: message.nodeId,
-        versionVector: Object.entries(message.versionVector).map(([key, value]) => ({ key, value })),
+        versionVector: Object.entries(message.versionVector).map(([key, value]) => ({
+          key,
+          value
+        })),
         schemaVersion: message.schemaVersion,
         accepted: message.accepted,
         rejectReason: message.rejectReason,
@@ -232,6 +524,12 @@ function toProtoEnvelope(message) {
         errorMessage: message.message,
         retriable: message.retriable
       };
+    case "awareness-update":
+    case "yjs-doc-update":
+      return {
+        type: message.type,
+        messageId: message.messageId
+      };
   }
 }
 function fromProtoEnvelope(envelope) {
@@ -241,7 +539,9 @@ function fromProtoEnvelope(envelope) {
         type: "handshake",
         messageId: envelope.messageId,
         nodeId: envelope.nodeId ?? "",
-        versionVector: Object.fromEntries((envelope.versionVector ?? []).map((entry) => [entry.key, entry.value])),
+        versionVector: Object.fromEntries(
+          (envelope.versionVector ?? []).map((entry) => [entry.key, entry.value])
+        ),
         schemaVersion: envelope.schemaVersion ?? 0,
         authToken: envelope.authToken,
         supportedWireFormats: envelope.supportedWireFormats?.filter(
@@ -253,7 +553,9 @@ function fromProtoEnvelope(envelope) {
         type: "handshake-response",
         messageId: envelope.messageId,
         nodeId: envelope.nodeId ?? "",
-        versionVector: Object.fromEntries((envelope.versionVector ?? []).map((entry) => [entry.key, entry.value])),
+        versionVector: Object.fromEntries(
+          (envelope.versionVector ?? []).map((entry) => [entry.key, entry.value])
+        ),
         schemaVersion: envelope.schemaVersion ?? 0,
         accepted: envelope.accepted ?? false,
         rejectReason: envelope.rejectReason,
@@ -289,13 +591,33 @@ function fromProtoEnvelope(envelope) {
   }
 }
 function serializeProtoOperation(operation) {
+  const hasMetadata = operation.transactionId !== void 0 || operation.mutationName !== void 0;
+  let dataJson = "";
+  if (operation.data !== null) {
+    const dataPayload = { ...operation.data };
+    if (operation.atomicOps !== void 0 && Object.keys(operation.atomicOps).length > 0) {
+      dataPayload.__kora_atomic_ops__ = operation.atomicOps;
+    }
+    if (operation.transactionId !== void 0) {
+      dataPayload.__kora_tx_id__ = operation.transactionId;
+    }
+    if (operation.mutationName !== void 0) {
+      dataPayload.__kora_mutation__ = operation.mutationName;
+    }
+    dataJson = JSON.stringify(dataPayload);
+  } else if (hasMetadata) {
+    const meta = {};
+    if (operation.transactionId !== void 0) meta.__kora_tx_id__ = operation.transactionId;
+    if (operation.mutationName !== void 0) meta.__kora_mutation__ = operation.mutationName;
+    dataJson = JSON.stringify(meta);
+  }
   return {
     id: operation.id,
     nodeId: operation.nodeId,
     type: operation.type,
     collection: operation.collection,
     recordId: operation.recordId,
-    dataJson: operation.data === null ? "" : JSON.stringify(operation.data),
+    dataJson,
     previousDataJson: operation.previousData === null ? "" : JSON.stringify(operation.previousData),
     timestamp: {
       wallTime: operation.timestamp.wallTime,
@@ -310,13 +632,31 @@ function serializeProtoOperation(operation) {
   };
 }
 function deserializeProtoOperation(operation) {
+  let data = null;
+  let atomicOps;
+  let transactionId;
+  let mutationName;
+  if (operation.hasData || operation.dataJson.length > 0) {
+    const parsed = JSON.parse(operation.dataJson);
+    if ("__kora_atomic_ops__" in parsed) {
+      atomicOps = parsed.__kora_atomic_ops__;
+    }
+    if ("__kora_tx_id__" in parsed) {
+      transactionId = parsed.__kora_tx_id__;
+    }
+    if ("__kora_mutation__" in parsed) {
+      mutationName = parsed.__kora_mutation__;
+    }
+    const { __kora_atomic_ops__: _a, __kora_tx_id__: _t, __kora_mutation__: _m, ...rest } = parsed;
+    data = operation.hasData && Object.keys(rest).length > 0 ? rest : null;
+  }
   return {
     id: operation.id,
     nodeId: operation.nodeId,
     type: operation.type,
     collection: operation.collection,
     recordId: operation.recordId,
-    data: operation.hasData ? JSON.parse(operation.dataJson) : null,
+    data,
     previousData: operation.hasPreviousData ? JSON.parse(operation.previousDataJson) : null,
     timestamp: {
       wallTime: operation.timestamp.wallTime,
@@ -325,7 +665,10 @@ function deserializeProtoOperation(operation) {
     },
     sequenceNumber: operation.sequenceNumber,
     causalDeps: [...operation.causalDeps],
-    schemaVersion: operation.schemaVersion
+    schemaVersion: operation.schemaVersion,
+    ...atomicOps !== void 0 ? { atomicOps } : {},
+    ...transactionId !== void 0 ? { transactionId } : {},
+    ...mutationName !== void 0 ? { mutationName } : {}
   };
 }
 function decodeTextPayload(data) {
@@ -356,12 +699,14 @@ function encodeEnvelope(envelope) {
     writer.ldelim();
   }
   if (envelope.schemaVersion !== void 0) writer.uint32(40).int32(envelope.schemaVersion);
-  if (envelope.authToken && envelope.authToken.length > 0) writer.uint32(50).string(envelope.authToken);
+  if (envelope.authToken && envelope.authToken.length > 0)
+    writer.uint32(50).string(envelope.authToken);
   for (const format of envelope.supportedWireFormats ?? []) {
     writer.uint32(58).string(format);
   }
   if (envelope.accepted !== void 0) writer.uint32(64).bool(envelope.accepted);
-  if (envelope.rejectReason && envelope.rejectReason.length > 0) writer.uint32(74).string(envelope.rejectReason);
+  if (envelope.rejectReason && envelope.rejectReason.length > 0)
+    writer.uint32(74).string(envelope.rejectReason);
   if (envelope.selectedWireFormat && envelope.selectedWireFormat.length > 0) {
     writer.uint32(82).string(envelope.selectedWireFormat);
   }
@@ -375,8 +720,10 @@ function encodeEnvelope(envelope) {
   if (envelope.acknowledgedMessageId && envelope.acknowledgedMessageId.length > 0) {
     writer.uint32(114).string(envelope.acknowledgedMessageId);
   }
-  if (envelope.lastSequenceNumber !== void 0) writer.uint32(120).int64(envelope.lastSequenceNumber);
-  if (envelope.errorCode && envelope.errorCode.length > 0) writer.uint32(130).string(envelope.errorCode);
+  if (envelope.lastSequenceNumber !== void 0)
+    writer.uint32(120).int64(envelope.lastSequenceNumber);
+  if (envelope.errorCode && envelope.errorCode.length > 0)
+    writer.uint32(130).string(envelope.errorCode);
   if (envelope.errorMessage && envelope.errorMessage.length > 0) {
     writer.uint32(138).string(envelope.errorMessage);
   }
@@ -399,7 +746,10 @@ function decodeEnvelope(bytes) {
         envelope.nodeId = reader.string();
         break;
       case 4:
-        envelope.versionVector = [...envelope.versionVector ?? [], decodeVectorEntry(reader, reader.uint32())];
+        envelope.versionVector = [
+          ...envelope.versionVector ?? [],
+          decodeVectorEntry(reader, reader.uint32())
+        ];
         break;
       case 5:
         envelope.schemaVersion = reader.int32();
@@ -420,7 +770,10 @@ function decodeEnvelope(bytes) {
         envelope.selectedWireFormat = reader.string();
         break;
       case 11:
-        envelope.operations = [...envelope.operations ?? [], decodeProtoOperation(reader, reader.uint32())];
+        envelope.operations = [
+          ...envelope.operations ?? [],
+          decodeProtoOperation(reader, reader.uint32())
+        ];
         break;
       case 12:
         envelope.isFinal = reader.bool();
@@ -1029,184 +1382,1027 @@ var ChaosTransport = class {
 };
 
 // src/engine/sync-engine.ts
-import { SyncError as SyncError4 } from "@korajs/core";
+import {
+  APPLY_FAILURE_CODES,
+  ClockDriftError,
+  KoraError as KoraError2,
+  SyncError as SyncError4,
+  applyOperationTransforms,
+  defaultApplyFailureReason
+} from "@korajs/core";
 import { topologicalSort as topologicalSort2 } from "@korajs/core/internal";
 
-// src/engine/outbound-queue.ts
-import { topologicalSort } from "@korajs/core/internal";
-var OutboundQueue = class {
-  constructor(storage) {
-    this.storage = storage;
+// src/awareness/awareness-manager.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var nextLocalClientId = 1;
+var AwarenessManager = class {
+  /** Unique client ID for this instance */
+  clientId;
+  localState = null;
+  remoteStates = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  emitter;
+  timeoutMs;
+  // Track when we last received an update from each remote client.
+  // Used for timeout-based cleanup as a safety net in case the server
+  // does not send an explicit removal on disconnect.
+  lastUpdated = /* @__PURE__ */ new Map();
+  cleanupTimer = null;
+  sendHandler = null;
+  destroyed = false;
+  constructor(options) {
+    this.clientId = options?.clientId ?? nextLocalClientId++;
+    this.emitter = options?.emitter ?? null;
+    this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   }
-  storage;
-  queue = [];
-  seen = /* @__PURE__ */ new Set();
-  inFlight = /* @__PURE__ */ new Map();
-  nextBatchId = 0;
-  initialized = false;
   /**
-   * Load persisted operations from storage.
-   * Must be called before using the queue.
+   * Set the local user's awareness state and broadcast to peers.
+   *
+   * @param state - The awareness state to share. Pass null to clear presence.
    */
-  async initialize() {
-    const stored = await this.storage.load();
-    for (const op of stored) {
-      if (!this.seen.has(op.id)) {
-        this.seen.add(op.id);
-        this.queue.push(op);
-      }
+  setLocalState(state) {
+    if (this.destroyed) return;
+    this.localState = state;
+    const message = {
+      type: "awareness",
+      clientId: this.clientId,
+      states: { [this.clientId]: state }
+    };
+    this.sendHandler?.(message);
+    this.emitAwarenessEvent();
+  }
+  /**
+   * Get the local awareness state.
+   */
+  getLocalState() {
+    return this.localState;
+  }
+  /**
+   * Get all known awareness states (local + remote).
+   * Returns a new Map on each call.
+   */
+  getStates() {
+    const result = /* @__PURE__ */ new Map();
+    if (this.localState) {
+      result.set(this.clientId, this.localState);
     }
-    if (this.queue.length > 1) {
-      this.queue = topologicalSort(this.queue);
+    for (const [id, state] of this.remoteStates) {
+      result.set(id, state);
     }
-    this.initialized = true;
+    return result;
   }
   /**
-   * Add an operation to the outbound queue.
-   * Deduplicates by operation ID. Persists to storage.
+   * Handle an incoming awareness message from the transport.
+   * This processes remote state updates and notifies listeners.
    */
-  async enqueue(op) {
-    if (this.seen.has(op.id)) return;
-    this.seen.add(op.id);
-    this.queue.push(op);
-    await this.storage.enqueue(op);
-    if (this.queue.length > 1) {
-      this.queue = topologicalSort(this.queue);
+  handleRemoteMessage(message) {
+    if (this.destroyed) return;
+    const added = [];
+    const updated = [];
+    const removed = [];
+    const now = Date.now();
+    for (const [clientIdStr, state] of Object.entries(message.states)) {
+      const clientId = Number(clientIdStr);
+      if (clientId === this.clientId) continue;
+      if (state === null) {
+        if (this.remoteStates.has(clientId)) {
+          this.remoteStates.delete(clientId);
+          this.lastUpdated.delete(clientId);
+          removed.push(clientId);
+        }
+      } else {
+        if (this.remoteStates.has(clientId)) {
+          this.remoteStates.set(clientId, state);
+          this.lastUpdated.set(clientId, now);
+          updated.push(clientId);
+        } else {
+          this.remoteStates.set(clientId, state);
+          this.lastUpdated.set(clientId, now);
+          added.push(clientId);
+        }
+      }
+    }
+    if (added.length > 0 || updated.length > 0 || removed.length > 0) {
+      const change = { added, updated, removed };
+      this.notifyListeners(change);
+      this.emitAwarenessEvent();
     }
   }
   /**
-   * Take a batch of operations from the front of the queue.
-   * Moves them to in-flight status. Returns null if queue is empty.
-   *
-   * @param batchSize - Maximum number of operations in the batch
+   * Remove a specific remote client's awareness state.
+   * Called when the server notifies that a client has disconnected.
    */
-  takeBatch(batchSize) {
-    if (this.queue.length === 0) return null;
-    const ops = this.queue.splice(0, batchSize);
-    const batchId = `batch-${this.nextBatchId++}`;
-    this.inFlight.set(batchId, ops);
-    return { batchId, operations: ops };
+  removeClient(clientId) {
+    if (this.destroyed) return;
+    if (!this.remoteStates.has(clientId)) return;
+    this.remoteStates.delete(clientId);
+    this.lastUpdated.delete(clientId);
+    const change = {
+      added: [],
+      updated: [],
+      removed: [clientId]
+    };
+    this.notifyListeners(change);
+    this.emitAwarenessEvent();
   }
   /**
-   * Acknowledge a batch, removing its operations permanently.
+   * Register a handler for sending awareness messages through the transport.
+   * The sync engine calls this to wire outgoing awareness messages to the transport.
    */
-  async acknowledge(batchId) {
-    const ops = this.inFlight.get(batchId);
-    if (!ops) return;
-    this.inFlight.delete(batchId);
-    const ids = ops.map((op) => op.id);
-    await this.storage.dequeue(ids);
+  onSend(handler) {
+    this.sendHandler = handler;
   }
   /**
-   * Return a failed batch to the front of the queue for retry.
-   * Prepends the operations to maintain priority.
+   * Register a listener for awareness state changes.
+   * Returns an unsubscribe function.
    */
-  returnBatch(batchId) {
-    const ops = this.inFlight.get(batchId);
-    if (!ops) return;
-    this.inFlight.delete(batchId);
-    this.queue.unshift(...ops);
-    if (this.queue.length > 1) {
-      this.queue = topologicalSort(this.queue);
+  on(_event, listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Remove a specific change listener.
+   */
+  off(_event, listener) {
+    this.listeners.delete(listener);
+  }
+  /**
+   * Start the cleanup timer that removes stale remote states.
+   * Called when the sync engine transitions to streaming state.
+   */
+  startCleanupTimer() {
+    if (this.cleanupTimer) return;
+    this.cleanupTimer = setInterval(() => {
+      this.cleanupStaleStates();
+    }, this.timeoutMs);
+  }
+  /**
+   * Stop the cleanup timer.
+   */
+  stopCleanupTimer() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
     }
   }
   /**
-   * Number of operations waiting in the queue (not counting in-flight).
+   * Clean up all resources. After calling destroy(), the manager
+   * will no longer send or receive awareness updates.
+   * Broadcasts removal of local state before shutting down.
    */
-  get size() {
-    return this.queue.length;
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this.localState) {
+      const message = {
+        type: "awareness",
+        clientId: this.clientId,
+        states: { [this.clientId]: null }
+      };
+      this.sendHandler?.(message);
+    }
+    this.localState = null;
+    this.remoteStates.clear();
+    this.lastUpdated.clear();
+    this.listeners.clear();
+    this.sendHandler = null;
+    this.stopCleanupTimer();
+  }
+  // --- Private ---
+  cleanupStaleStates() {
+    const now = Date.now();
+    const removed = [];
+    for (const [clientId, lastTime] of this.lastUpdated) {
+      if (now - lastTime > this.timeoutMs) {
+        this.remoteStates.delete(clientId);
+        this.lastUpdated.delete(clientId);
+        removed.push(clientId);
+      }
+    }
+    if (removed.length > 0) {
+      const change = { added: [], updated: [], removed };
+      this.notifyListeners(change);
+      this.emitAwarenessEvent();
+    }
+  }
+  notifyListeners(change) {
+    for (const listener of this.listeners) {
+      listener(change);
+    }
+  }
+  emitAwarenessEvent() {
+    const states = this.getStates();
+    this.emitter?.emit({ type: "awareness:updated", states });
   }
+};
+
+// src/diagnostics/bandwidth-estimator.ts
+var BandwidthEstimator = class {
+  maxSamples;
+  timeSource;
+  samples = [];
   /**
-   * Total operations including in-flight.
+   * @param maxSamples - Maximum number of samples to retain. Defaults to 20.
+   * @param timeSource - Injectable time source for deterministic testing.
    */
-  get totalPending() {
-    let inFlightCount = 0;
-    for (const ops of this.inFlight.values()) {
-      inFlightCount += ops.length;
+  constructor(maxSamples = 20, timeSource) {
+    this.maxSamples = maxSamples;
+    this.timeSource = timeSource ?? { now: () => Date.now() };
+  }
+  /**
+   * Record a transfer of `bytes` that took `durationMs` to complete.
+   * Samples with zero or negative duration are ignored to avoid division errors.
+   */
+  recordTransfer(bytes, durationMs) {
+    if (durationMs <= 0 || bytes <= 0) return;
+    this.samples.push({
+      bytes,
+      durationMs,
+      timestamp: this.timeSource.now()
+    });
+    while (this.samples.length > this.maxSamples) {
+      this.samples.shift();
     }
-    return this.queue.length + inFlightCount;
   }
   /**
-   * Whether the queue has any operations to send.
+   * Estimate current effective bandwidth in bytes per second.
+   *
+   * Uses exponential weighting so recent samples have more influence.
+   * Returns null if fewer than 2 samples exist (not enough data).
    */
-  get hasOperations() {
-    return this.queue.length > 0;
+  estimate() {
+    if (this.samples.length < 2) return null;
+    let weightedSum = 0;
+    let totalWeight = 0;
+    const decayFactor = 0.9;
+    for (let i = this.samples.length - 1; i >= 0; i--) {
+      const sample = this.samples[i];
+      if (!sample) continue;
+      const bytesPerSec = sample.bytes / sample.durationMs * 1e3;
+      const age = this.samples.length - 1 - i;
+      const weight = decayFactor ** age;
+      weightedSum += bytesPerSec * weight;
+      totalWeight += weight;
+    }
+    if (totalWeight === 0) return null;
+    return Math.round(weightedSum / totalWeight);
   }
   /**
-   * Peek at the first `count` operations without removing them.
+   * Reset all recorded samples.
    */
-  peek(count) {
-    return this.queue.slice(0, count);
+  reset() {
+    this.samples.length = 0;
   }
   /**
-   * Whether initialize() has been called.
+   * Get the number of samples currently stored.
    */
-  get isInitialized() {
-    return this.initialized;
+  sampleCount() {
+    return this.samples.length;
   }
 };
 
-// src/engine/sync-engine.ts
-var DEFAULT_BATCH_SIZE = 100;
-var DEFAULT_SCHEMA_VERSION = 1;
-var VALID_TRANSITIONS = {
-  disconnected: ["connecting"],
-  connecting: ["handshaking", "error", "disconnected"],
-  handshaking: ["syncing", "error", "disconnected"],
-  syncing: ["streaming", "error", "disconnected"],
-  streaming: ["disconnected", "error"],
-  error: ["disconnected"]
-};
-var nextMessageId = 0;
-function generateMessageId() {
-  return `msg-${Date.now()}-${nextMessageId++}`;
-}
-var SyncEngine = class {
-  state = "disconnected";
-  transport;
-  store;
-  config;
-  serializer;
-  emitter;
-  outboundQueue;
-  batchSize;
-  remoteVector = /* @__PURE__ */ new Map();
-  lastSyncedAt = null;
-  currentBatch = null;
-  reconnecting = false;
-  // Track delta exchange state
-  deltaBatchesReceived = 0;
-  deltaReceiveComplete = false;
-  deltaSendComplete = false;
-  constructor(options) {
-    this.transport = options.transport;
-    this.store = options.store;
-    this.config = options.config;
-    this.serializer = options.serializer ?? new NegotiatedMessageSerializer("json");
-    this.emitter = options.emitter ?? null;
-    this.batchSize = options.config.batchSize ?? DEFAULT_BATCH_SIZE;
-    const queueStorage = options.queueStorage ?? new MemoryQueueStorage();
-    this.outboundQueue = new OutboundQueue(queueStorage);
-  }
+// src/diagnostics/percentile.ts
+var SlidingWindowPercentile = class {
+  samples;
+  maxSize;
+  writeIndex = 0;
+  count = 0;
   /**
-   * Start the sync engine: connect → handshake → delta exchange → streaming.
+   * @param maxSize - Maximum number of samples in the sliding window.
+   *                  Older samples are overwritten when the buffer is full.
    */
-  async start() {
-    if (this.state !== "disconnected") {
-      throw new SyncError4("Cannot start sync engine: not in disconnected state", {
-        currentState: this.state
-      });
+  constructor(maxSize) {
+    if (maxSize < 1) {
+      throw new Error(`SlidingWindowPercentile maxSize must be >= 1, got ${maxSize}`);
+    }
+    this.maxSize = maxSize;
+    this.samples = new Array(maxSize);
+  }
+  /**
+   * Add a sample to the sliding window.
+   * If the window is full, the oldest sample is overwritten.
+   */
+  addSample(value) {
+    this.samples[this.writeIndex] = value;
+    this.writeIndex = (this.writeIndex + 1) % this.maxSize;
+    if (this.count < this.maxSize) {
+      this.count++;
+    }
+  }
+  /**
+   * Compute a percentile value from the current window.
+   *
+   * Uses the nearest-rank method: the percentile value is the smallest
+   * value in the dataset such that at least p% of the data is <= that value.
+   *
+   * @param p - Percentile to compute (0-100). E.g., 50 for median, 95 for p95.
+   * @returns The percentile value, or 0 if no samples have been recorded.
+   */
+  percentile(p) {
+    if (this.count === 0) return 0;
+    const sorted = this.samples.slice(0, this.count).sort((a, b) => a - b);
+    const rank = Math.ceil(p / 100 * sorted.length) - 1;
+    const index = Math.max(0, Math.min(rank, sorted.length - 1));
+    return sorted[index] ?? 0;
+  }
+  /**
+   * Get the most recently added sample, or 0 if no samples exist.
+   */
+  latest() {
+    if (this.count === 0) return 0;
+    const lastIndex = (this.writeIndex - 1 + this.maxSize) % this.maxSize;
+    return this.samples[lastIndex] ?? 0;
+  }
+  /**
+   * Get the number of samples currently in the window.
+   */
+  size() {
+    return this.count;
+  }
+  /**
+   * Reset the sliding window, clearing all samples.
+   */
+  reset() {
+    this.writeIndex = 0;
+    this.count = 0;
+  }
+};
+
+// src/diagnostics/metrics-collector.ts
+var SyncMetricsCollector = class {
+  rttWindow;
+  inboundBandwidth;
+  outboundBandwidth;
+  timeSource;
+  diagnosticsInterval;
+  // Connection
+  connectedAt = null;
+  disconnectedAt = null;
+  reconnectAttempts = 0;
+  // Throughput
+  operationsSent = 0;
+  operationsReceived = 0;
+  bytesSent = 0;
+  bytesReceived = 0;
+  // Queue
+  pendingOperations = 0;
+  outboundQueueSize = 0;
+  // Sync progress
+  lastSyncedAt = null;
+  syncStartTime = null;
+  syncDuration = null;
+  initialSyncComplete = false;
+  initialSyncTotalBatches = 0;
+  initialSyncReceivedBatches = 0;
+  // Errors
+  lastError = null;
+  errorCount = 0;
+  // Status
+  currentStatus = "offline";
+  currentQuality = "offline";
+  // Periodic emission
+  emitter = null;
+  periodicTimer = null;
+  constructor(config) {
+    this.rttWindow = new SlidingWindowPercentile(config?.rttWindowSize ?? 100);
+    this.inboundBandwidth = new BandwidthEstimator(
+      config?.bandwidthWindowSize ?? 20,
+      config?.timeSource
+    );
+    this.outboundBandwidth = new BandwidthEstimator(
+      config?.bandwidthWindowSize ?? 20,
+      config?.timeSource
+    );
+    this.timeSource = config?.timeSource ?? { now: () => Date.now() };
+    this.diagnosticsInterval = config?.diagnosticsInterval ?? 5e3;
+  }
+  /**
+   * Attach an event emitter for periodic diagnostics emission.
+   * Starts emitting `sync:diagnostics` events at the configured interval
+   * while connected.
+   */
+  attachEmitter(emitter) {
+    this.emitter = emitter;
+  }
+  /**
+   * Record that a connection has been established.
+   */
+  recordConnected() {
+    this.connectedAt = this.timeSource.now();
+    this.reconnectAttempts = 0;
+    this.startPeriodicEmission();
+  }
+  /**
+   * Record that the connection has been lost.
+   */
+  recordDisconnected() {
+    this.disconnectedAt = this.timeSource.now();
+    this.stopPeriodicEmission();
+  }
+  /**
+   * Record a reconnection attempt.
+   */
+  recordReconnectAttempt() {
+    this.reconnectAttempts++;
+  }
+  /**
+   * Record a round-trip time measurement.
+   */
+  recordRtt(ms) {
+    this.rttWindow.addSample(ms);
+  }
+  /**
+   * Record operations sent with their serialized byte size.
+   */
+  recordSent(operationCount, byteSize, durationMs) {
+    this.operationsSent += operationCount;
+    this.bytesSent += byteSize;
+    if (durationMs > 0 && byteSize > 0) {
+      this.outboundBandwidth.recordTransfer(byteSize, durationMs);
+      this.emitBandwidthEvent("out");
+    }
+  }
+  /**
+   * Record operations received with their serialized byte size.
+   */
+  recordReceived(operationCount, byteSize, durationMs) {
+    this.operationsReceived += operationCount;
+    this.bytesReceived += byteSize;
+    if (durationMs > 0 && byteSize > 0) {
+      this.inboundBandwidth.recordTransfer(byteSize, durationMs);
+      this.emitBandwidthEvent("in");
+    }
+  }
+  /**
+   * Update the pending operations count and estimated outbound queue size.
+   */
+  updateQueue(pendingOps, estimatedBytes) {
+    this.pendingOperations = pendingOps;
+    this.outboundQueueSize = estimatedBytes;
+  }
+  /**
+   * Record that sync has started (for measuring sync duration).
+   */
+  recordSyncStarted() {
+    this.syncStartTime = this.timeSource.now();
+  }
+  /**
+   * Record that a sync cycle has completed.
+   */
+  recordSyncCompleted() {
+    if (this.syncStartTime !== null) {
+      this.syncDuration = this.timeSource.now() - this.syncStartTime;
+      this.syncStartTime = null;
+    }
+    this.lastSyncedAt = this.timeSource.now();
+    if (!this.initialSyncComplete) {
+      this.initialSyncComplete = true;
+    }
+  }
+  /**
+   * Update initial sync progress.
+   * @param receivedBatches - Number of delta batches received so far.
+   * @param totalBatches - Estimated total batches (0 if unknown).
+   */
+  updateInitialSyncProgress(receivedBatches, totalBatches) {
+    this.initialSyncReceivedBatches = receivedBatches;
+    this.initialSyncTotalBatches = totalBatches;
+    const progress = totalBatches > 0 ? Math.min(1, receivedBatches / totalBatches) : receivedBatches > 0 ? 0.5 : 0;
+    this.emitter?.emit({
+      type: "sync:initial-sync-progress",
+      progress,
+      totalBatches,
+      receivedBatches
+    });
+  }
+  /**
+   * Record an error.
+   */
+  recordError(message) {
+    this.lastError = message;
+    this.errorCount++;
+  }
+  /**
+   * Update the current developer-facing status.
+   */
+  updateStatus(status) {
+    this.currentStatus = status;
+  }
+  /**
+   * Update the connection quality.
+   */
+  updateQuality(quality) {
+    this.currentQuality = quality;
+  }
+  /**
+   * Compute and return a full diagnostics snapshot.
+   */
+  getSnapshot() {
+    return {
+      // Connection
+      status: this.currentStatus,
+      connectedAt: this.connectedAt,
+      disconnectedAt: this.disconnectedAt,
+      reconnectAttempts: this.reconnectAttempts,
+      // Latency
+      rttMs: this.rttWindow.latest(),
+      rttP50Ms: this.rttWindow.percentile(50),
+      rttP95Ms: this.rttWindow.percentile(95),
+      rttP99Ms: this.rttWindow.percentile(99),
+      // Throughput
+      operationsSent: this.operationsSent,
+      operationsReceived: this.operationsReceived,
+      bytesSent: this.bytesSent,
+      bytesReceived: this.bytesReceived,
+      // Queue
+      pendingOperations: this.pendingOperations,
+      outboundQueueSize: this.outboundQueueSize,
+      // Sync Progress
+      lastSyncedAt: this.lastSyncedAt,
+      syncDuration: this.syncDuration,
+      initialSyncComplete: this.initialSyncComplete,
+      initialSyncProgress: this.computeInitialSyncProgress(),
+      // Errors
+      lastError: this.lastError,
+      errorCount: this.errorCount,
+      // Connection Quality
+      quality: this.currentQuality,
+      effectiveBandwidth: this.computeEffectiveBandwidth()
+    };
+  }
+  /**
+   * Assess connection quality from current metrics.
+   *
+   * Quality is derived from RTT percentiles, error rate, and bandwidth:
+   * - excellent: p95 < 100ms, no errors
+   * - good: p95 < 300ms, errorCount <= 1
+   * - fair: p95 < 1000ms, errorCount <= 3
+   * - poor: p95 >= 1000ms or errorCount > 3
+   * - offline: no connection
+   */
+  assessQuality() {
+    if (this.currentStatus === "offline") return "offline";
+    const p95 = this.rttWindow.percentile(95);
+    const hasSamples = this.rttWindow.size() > 0;
+    if (!hasSamples) {
+      if (this.errorCount > 3) return "poor";
+      if (this.errorCount > 0) return "fair";
+      return "good";
+    }
+    if (this.errorCount > 3) return "poor";
+    if (p95 < 100 && this.errorCount === 0) return "excellent";
+    if (p95 < 300 && this.errorCount <= 1) return "good";
+    if (p95 < 1e3 && this.errorCount <= 3) return "fair";
+    return "poor";
+  }
+  /**
+   * Reset all collected metrics. Call when starting a new session.
+   */
+  reset() {
+    this.rttWindow.reset();
+    this.inboundBandwidth.reset();
+    this.outboundBandwidth.reset();
+    this.connectedAt = null;
+    this.disconnectedAt = null;
+    this.reconnectAttempts = 0;
+    this.operationsSent = 0;
+    this.operationsReceived = 0;
+    this.bytesSent = 0;
+    this.bytesReceived = 0;
+    this.pendingOperations = 0;
+    this.outboundQueueSize = 0;
+    this.lastSyncedAt = null;
+    this.syncStartTime = null;
+    this.syncDuration = null;
+    this.initialSyncComplete = false;
+    this.initialSyncTotalBatches = 0;
+    this.initialSyncReceivedBatches = 0;
+    this.lastError = null;
+    this.errorCount = 0;
+    this.currentStatus = "offline";
+    this.currentQuality = "offline";
+    this.stopPeriodicEmission();
+  }
+  /**
+   * Stop periodic emission and clean up resources.
+   */
+  dispose() {
+    this.stopPeriodicEmission();
+    this.emitter = null;
+  }
+  // --- Private helpers ---
+  computeInitialSyncProgress() {
+    if (this.initialSyncComplete) return 1;
+    if (this.initialSyncTotalBatches > 0) {
+      return Math.min(1, this.initialSyncReceivedBatches / this.initialSyncTotalBatches);
+    }
+    return this.initialSyncReceivedBatches > 0 ? 0.5 : 0;
+  }
+  computeEffectiveBandwidth() {
+    const inbound = this.inboundBandwidth.estimate();
+    const outbound = this.outboundBandwidth.estimate();
+    if (inbound === null && outbound === null) return null;
+    if (inbound === null) return outbound;
+    if (outbound === null) return inbound;
+    return Math.min(inbound, outbound);
+  }
+  startPeriodicEmission() {
+    if (this.periodicTimer !== null) return;
+    if (!this.emitter) return;
+    this.periodicTimer = setInterval(() => {
+      this.emitDiagnostics();
+    }, this.diagnosticsInterval);
+  }
+  stopPeriodicEmission() {
+    if (this.periodicTimer !== null) {
+      clearInterval(this.periodicTimer);
+      this.periodicTimer = null;
+    }
+  }
+  emitDiagnostics() {
+    this.emitter?.emit({
+      type: "sync:diagnostics",
+      diagnostics: this.getSnapshot()
+    });
+  }
+  emitBandwidthEvent(direction) {
+    const estimator = direction === "in" ? this.inboundBandwidth : this.outboundBandwidth;
+    const bps = estimator.estimate();
+    if (bps !== null) {
+      this.emitter?.emit({
+        type: "sync:bandwidth",
+        bytesPerSecond: bps,
+        direction
+      });
+    }
+  }
+};
+
+// src/richtext/richtext-doc-channel.ts
+import { generateUUIDv7 } from "@korajs/core";
+
+// src/richtext/doc-channel-wire.ts
+function encodeYjsUpdate(update) {
+  let binary = "";
+  for (let i = 0; i < update.length; i++) {
+    binary += String.fromCharCode(update[i]);
+  }
+  return btoa(binary);
+}
+function decodeYjsUpdate(encoded) {
+  const binary = atob(encoded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function richtextDocKey(collection, recordId, field) {
+  return `${collection}:${recordId}:${field}`;
+}
+
+// src/richtext/richtext-doc-channel.ts
+var DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD = 4096;
+var RichtextDocChannel = class {
+  threshold;
+  onSend;
+  listeners = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.threshold = options?.largeDocThreshold ?? DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD;
+    this.onSend = options?.onSend ?? null;
+  }
+  /**
+   * Whether the doc channel should be used for a field.
+   * @param preference - `true` forces on, `false` forces off, `undefined` uses size threshold
+   */
+  shouldUseChannel(snapshotByteLength, preference) {
+    if (preference === false) {
+      return false;
+    }
+    if (preference === true) {
+      return true;
+    }
+    return snapshotByteLength >= this.threshold;
+  }
+  getThreshold() {
+    return this.threshold;
+  }
+  /**
+   * Subscribe to incremental updates for a document key.
+   */
+  subscribe(collection, recordId, field, listener) {
+    const key = richtextDocKey(collection, recordId, field);
+    let set = this.listeners.get(key);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(key, set);
+    }
+    set.add(listener);
+    return () => {
+      const current = this.listeners.get(key);
+      if (!current) {
+        return;
+      }
+      current.delete(listener);
+      if (current.size === 0) {
+        this.listeners.delete(key);
+      }
+    };
+  }
+  /**
+   * Publish a local incremental update to peers.
+   */
+  send(collection, recordId, field, update) {
+    if (!this.onSend || update.length === 0) {
+      return;
+    }
+    this.onSend({
+      type: "yjs-doc-update",
+      messageId: generateUUIDv7(),
+      collection,
+      recordId,
+      field,
+      update: encodeYjsUpdate(update)
+    });
+  }
+  /**
+   * Deliver a remote incremental update to local subscribers.
+   */
+  deliver(message) {
+    const key = richtextDocKey(message.collection, message.recordId, message.field);
+    const set = this.listeners.get(key);
+    if (!set || set.size === 0) {
+      return;
+    }
+    const update = decodeYjsUpdate(message.update);
+    for (const listener of set) {
+      listener(update);
+    }
+  }
+};
+
+// src/engine/outbound-queue.ts
+import { topologicalSort } from "@korajs/core/internal";
+var OutboundQueue = class {
+  constructor(storage) {
+    this.storage = storage;
+  }
+  storage;
+  queue = [];
+  seen = /* @__PURE__ */ new Set();
+  inFlight = /* @__PURE__ */ new Map();
+  nextBatchId = 0;
+  initialized = false;
+  /**
+   * Load persisted operations from storage.
+   * Must be called before using the queue.
+   */
+  async initialize() {
+    const stored = await this.storage.load();
+    for (const op of stored) {
+      if (!this.seen.has(op.id)) {
+        this.seen.add(op.id);
+        this.queue.push(op);
+      }
+    }
+    if (this.queue.length > 1) {
+      this.queue = topologicalSort(this.queue);
+    }
+    this.initialized = true;
+  }
+  /**
+   * Add an operation to the outbound queue.
+   * Deduplicates by operation ID. Persists to storage.
+   */
+  async enqueue(op) {
+    if (this.seen.has(op.id)) return;
+    this.seen.add(op.id);
+    this.queue.push(op);
+    await this.storage.enqueue(op);
+    if (this.queue.length > 1) {
+      this.queue = topologicalSort(this.queue);
+    }
+  }
+  /**
+   * Take a batch of operations from the front of the queue.
+   * Moves them to in-flight status. Returns null if queue is empty.
+   *
+   * @param batchSize - Maximum number of operations in the batch
+   */
+  takeBatch(batchSize) {
+    if (this.queue.length === 0) return null;
+    const ops = this.queue.splice(0, batchSize);
+    const batchId = `batch-${this.nextBatchId++}`;
+    this.inFlight.set(batchId, ops);
+    return { batchId, operations: ops };
+  }
+  /**
+   * Acknowledge a batch, removing its operations permanently.
+   */
+  async acknowledge(batchId) {
+    const ops = this.inFlight.get(batchId);
+    if (!ops) return;
+    this.inFlight.delete(batchId);
+    const ids = ops.map((op) => op.id);
+    await this.storage.dequeue(ids);
+  }
+  /**
+   * Return a failed batch to the front of the queue for retry.
+   * Prepends the operations to maintain priority.
+   */
+  returnBatch(batchId) {
+    const ops = this.inFlight.get(batchId);
+    if (!ops) return;
+    this.inFlight.delete(batchId);
+    this.queue.unshift(...ops);
+    if (this.queue.length > 1) {
+      this.queue = topologicalSort(this.queue);
+    }
+  }
+  /**
+   * Number of operations waiting in the queue (not counting in-flight).
+   */
+  get size() {
+    return this.queue.length;
+  }
+  /**
+   * Total operations including in-flight.
+   */
+  get totalPending() {
+    let inFlightCount = 0;
+    for (const ops of this.inFlight.values()) {
+      inFlightCount += ops.length;
+    }
+    return this.queue.length + inFlightCount;
+  }
+  /**
+   * Whether the queue has any operations to send.
+   */
+  get hasOperations() {
+    return this.queue.length > 0;
+  }
+  /**
+   * Peek at the first `count` operations without removing them.
+   */
+  peek(count) {
+    return this.queue.slice(0, count);
+  }
+  /**
+   * Whether initialize() has been called.
+   */
+  get isInitialized() {
+    return this.initialized;
+  }
+  /**
+   * Remove operations by id from queue and persistent storage.
+   * Used when ops were already sent during handshake delta exchange.
+   */
+  async removeByIds(ids) {
+    if (ids.length === 0) return;
+    const idSet = new Set(ids);
+    this.queue = this.queue.filter((op) => !idSet.has(op.id));
+    for (const id of ids) {
+      this.seen.delete(id);
+    }
+    await this.storage.dequeue(ids);
+  }
+};
+
+// src/engine/sync-engine.ts
+var DEFAULT_BATCH_SIZE = 100;
+var DEFAULT_SCHEMA_VERSION = 1;
+var VALID_TRANSITIONS = {
+  disconnected: ["connecting"],
+  connecting: ["handshaking", "error", "disconnected"],
+  handshaking: ["syncing", "error", "disconnected"],
+  syncing: ["streaming", "error", "disconnected"],
+  streaming: ["disconnected", "error"],
+  error: ["disconnected"]
+};
+var nextMessageId = 0;
+var nextQuerySubsetId = 0;
+function generateMessageId() {
+  return `msg-${Date.now()}-${nextMessageId++}`;
+}
+var SyncEngine = class {
+  state = "disconnected";
+  transport;
+  store;
+  config;
+  serializer;
+  emitter;
+  outboundQueue;
+  batchSize;
+  encryptor;
+  awarenessManager;
+  richtextDocChannel;
+  metricsCollector;
+  syncState;
+  remoteVector = /* @__PURE__ */ new Map();
+  lastAckedServerVector = /* @__PURE__ */ new Map();
+  cachedUnsyncedCount = 0;
+  lastSyncedAt = null;
+  lastSuccessfulPush = null;
+  lastSuccessfulPull = null;
+  conflictCount = 0;
+  currentBatch = null;
+  reconnecting = false;
+  schemaBlocked = false;
+  // Track delta exchange state
+  deltaBatchesReceived = 0;
+  deltaReceiveComplete = false;
+  deltaSendComplete = false;
+  /** Op ids sent during handshake delta — removed from outbound queue to avoid duplicate send */
+  deltaSentOpIds = [];
+  /** Outbound delta batch message IDs awaiting ACK when strictHandshake is enabled */
+  pendingDeltaBatchAcks = /* @__PURE__ */ new Set();
+  /**
+   * The effective scope for this sync session.
+   * Starts as the configured scopeMap. After handshake, may be replaced
+   * with the server-accepted scope (server is authoritative).
+   */
+  activeScope;
+  /** Live query subsets registered from reactive subscriptions */
+  querySubsets = /* @__PURE__ */ new Map();
+  querySubsetReconnectTimer = null;
+  /** Resume cursor for paginated initial sync (persisted across reconnects) */
+  resumeDeltaCursor = null;
+  initialSyncTotalBatches = 0;
+  constructor(options) {
+    this.transport = options.transport;
+    this.store = options.store;
+    this.config = options.config;
+    this.serializer = options.serializer ?? new NegotiatedMessageSerializer("json");
+    this.emitter = options.emitter ?? null;
+    this.batchSize = options.config.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.encryptor = options.encryptor ?? null;
+    this.syncState = options.syncState ?? null;
+    this.activeScope = options.config.scopeMap;
+    const queueStorage = options.queueStorage ?? new MemoryQueueStorage();
+    this.outboundQueue = new OutboundQueue(queueStorage);
+    this.metricsCollector = new SyncMetricsCollector(options.metricsConfig);
+    if (this.emitter) {
+      this.metricsCollector.attachEmitter(this.emitter);
+    }
+    this.awarenessManager = new AwarenessManager({
+      emitter: this.emitter ?? void 0
+    });
+    this.richtextDocChannel = new RichtextDocChannel({
+      largeDocThreshold: options.config.richtextDocChannelThreshold,
+      onSend: (message) => {
+        if (this.state !== "streaming") {
+          return;
+        }
+        this.transport.send(message);
+      }
+    });
+    this.awarenessManager.onSend((message) => {
+      if (this.state !== "streaming") return;
+      const wireMessage = {
+        type: "awareness-update",
+        messageId: generateMessageId(),
+        clientId: message.clientId,
+        states: awarenessStatesToWire(message.states)
+      };
+      this.transport.send(wireMessage);
+    });
+  }
+  /**
+   * Start the sync engine: connect → handshake → delta exchange → streaming.
+   */
+  async start() {
+    if (this.state !== "disconnected") {
+      throw new SyncError4("Cannot start sync engine: not in disconnected state", {
+        currentState: this.state
+      });
     }
     await this.outboundQueue.initialize();
-    this.transport.onMessage((msg) => this.handleMessage(msg));
+    if (this.syncState) {
+      this.lastAckedServerVector = await this.syncState.loadLastAckedServerVector();
+      if (this.syncState.loadDeltaCursor) {
+        this.resumeDeltaCursor = await this.syncState.loadDeltaCursor();
+      }
+    }
+    await this.reconcileOutboundFromOpLog();
+    await this.refreshPendingCount();
+    this.transport.onMessage((msg) => this.enqueueMessage(msg));
     this.transport.onClose((reason) => this.handleTransportClose(reason));
     this.transport.onError((err) => this.handleTransportError(err));
+    if (this.schemaBlocked) {
+      throw new SyncError4(
+        "Sync is blocked due to schema version mismatch. Upgrade the app schema or align sync.schemaVersion with the server.",
+        { code: "SCHEMA_MISMATCH_BLOCKED" }
+      );
+    }
     this.transitionTo("connecting");
     try {
       const authToken = this.config.auth ? (await this.config.auth()).token : void 0;
       await this.transport.connect(this.config.url, { authToken });
       this.transitionTo("handshaking");
       const localVector = this.store.getVersionVector();
+      const activeQuerySubsets = this.getActiveQuerySubsets();
       const handshake = {
         type: "handshake",
         messageId: generateMessageId(),
@@ -1214,7 +2410,10 @@ var SyncEngine = class {
         versionVector: versionVectorToWire(localVector),
         schemaVersion: this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION,
         authToken,
-        supportedWireFormats: ["json", "protobuf"]
+        supportedWireFormats: ["json", "protobuf"],
+        ...this.config.scopeMap ? { syncScope: this.config.scopeMap } : {},
+        ...activeQuerySubsets.length > 0 ? { syncQueries: activeQuerySubsets } : {},
+        ...this.resumeDeltaCursor ? { deltaCursor: encodeDeltaCursor(this.resumeDeltaCursor) } : {}
       };
       this.transport.send(handshake);
     } catch (err) {
@@ -1227,6 +2426,7 @@ var SyncEngine = class {
    */
   async stop() {
     if (this.state === "disconnected") return;
+    this.awarenessManager.stopCleanupTimer();
     if (this.currentBatch) {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
       this.currentBatch = null;
@@ -1245,9 +2445,21 @@ var SyncEngine = class {
   /**
    * Push a local operation to the outbound queue.
    * If streaming, flushes immediately.
+   *
+   * Operations outside the configured sync scope are silently skipped
+   * because they should remain local-only and not be sent to the server.
    */
   async pushOperation(op) {
+    if (!this.operationAllowedForSync(op)) {
+      return;
+    }
+    if (this.syncState) {
+      this.cachedUnsyncedCount++;
+    }
     await this.outboundQueue.enqueue(op);
+    if (this.syncState) {
+      await this.refreshPendingCount();
+    }
     if (this.state === "streaming") {
       this.flushQueue();
     }
@@ -1265,48 +2477,181 @@ var SyncEngine = class {
    * Get the current developer-facing sync status.
    */
   getStatus() {
-    const pendingOperations = this.outboundQueue.totalPending;
+    const pendingOperations = this.syncState ? this.cachedUnsyncedCount : this.outboundQueue.totalPending;
+    const base = {
+      pendingOperations,
+      lastSyncedAt: this.lastSyncedAt,
+      lastSuccessfulPush: this.lastSuccessfulPush,
+      lastSuccessfulPull: this.lastSuccessfulPull,
+      conflicts: this.conflictCount
+    };
     switch (this.state) {
       case "disconnected":
-        return { status: "offline", pendingOperations, lastSyncedAt: this.lastSyncedAt };
+        return { ...base, status: "offline" };
       case "connecting":
       case "handshaking":
       case "syncing":
-        return {
-          status: this.reconnecting ? "offline" : "syncing",
-          pendingOperations,
-          lastSyncedAt: this.lastSyncedAt
-        };
+        return { ...base, status: this.reconnecting ? "offline" : "syncing" };
       case "streaming":
-        return {
-          status: pendingOperations > 0 ? "syncing" : "synced",
-          pendingOperations,
-          lastSyncedAt: this.lastSyncedAt
-        };
+        return { ...base, status: pendingOperations > 0 ? "syncing" : "synced" };
       case "error":
-        return { status: "error", pendingOperations, lastSyncedAt: this.lastSyncedAt };
+        return { ...base, status: this.schemaBlocked ? "schema-mismatch" : "error" };
     }
   }
   /**
-   * Get the current internal state (for testing).
+   * True when the server rejected the client's schema version at handshake.
+   * Sync stays blocked until the app schema is upgraded or sync config changes.
+   */
+  isSchemaBlocked() {
+    return this.schemaBlocked;
+  }
+  /**
+   * Clears schema-mismatch block after upgrading the local schema / sync config.
+   * Moves the engine back to `disconnected` so `start()` can run again.
+   */
+  clearSchemaBlock() {
+    this.schemaBlocked = false;
+    if (this.state === "error") {
+      this.transitionTo("disconnected");
+    }
+  }
+  /**
+   * Record a merge conflict. Called by the merge-aware sync store
+   * to increment the conflict counter for status reporting.
+   */
+  recordConflict() {
+    this.conflictCount++;
+  }
+  /**
+   * Count of local operations not yet covered by the last acked server vector (op-log source of truth).
+   */
+  async getUnsyncedOperationCount() {
+    await this.refreshPendingCount();
+    return this.getStatus().pendingOperations;
+  }
+  emitApplyFailure(op, result, overrides) {
+    const reason = defaultApplyFailureReason(result, overrides);
+    this.emitter?.emit({
+      type: "sync:apply-failed",
+      operationId: op.id,
+      collection: op.collection,
+      recordId: op.recordId,
+      code: reason.code,
+      message: reason.message,
+      retriable: reason.retriable
+    });
+  }
+  /**
+   * Force an immediate reconnection attempt. If the engine is disconnected
+   * or in error state, restarts the sync. If already connected, no-op.
+   */
+  async retryNow() {
+    if (this.schemaBlocked) return;
+    if (this.state === "disconnected" || this.state === "error") {
+      this.reconnecting = false;
+      await this.start();
+    }
+  }
+  /**
+   * Export a diagnostics snapshot for debugging and support tickets.
+   * Contains connection state, timing info, and queue metrics.
+   */
+  exportDiagnostics() {
+    return {
+      state: this.state,
+      status: this.getStatus(),
+      nodeId: this.store.getNodeId(),
+      url: this.config.url,
+      schemaVersion: this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION,
+      lastSyncedAt: this.lastSyncedAt,
+      lastSuccessfulPush: this.lastSuccessfulPush,
+      lastSuccessfulPull: this.lastSuccessfulPull,
+      conflicts: this.conflictCount,
+      pendingOperations: this.outboundQueue.totalPending,
+      hasInFlightBatch: this.currentBatch !== null,
+      reconnecting: this.reconnecting,
+      timestamp: Date.now()
+    };
+  }
+  /**
+   * Get the current internal state (for testing).
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Get the outbound queue (for testing).
+   */
+  getOutboundQueue() {
+    return this.outboundQueue;
+  }
+  /**
+   * Update the sync scope map. Takes effect on the next connection attempt.
+   *
+   * When the scope changes (e.g., user switches organization), call this method
+   * then reconnect. The new scope will be sent in the handshake, and the server
+   * will send back data matching the new scope.
+   *
+   * Data that no longer matches the new scope is NOT deleted locally.
+   * It simply stops being synced.
+   *
+   * @param scopeMap - New per-collection scope filters, or undefined to remove scope
+   */
+  updateScope(scopeMap) {
+    this.activeScope = scopeMap;
+    this.config.scopeMap = scopeMap;
+  }
+  /**
+   * Get the currently active scope map. Returns undefined if no scope is configured.
    */
-  getState() {
-    return this.state;
+  getActiveScope() {
+    return this.activeScope;
   }
   /**
-   * Get the outbound queue (for testing).
+   * Register a live query subset that narrows synced data for a collection.
+   * Takes effect on the next connection; reconnects when already connected.
    */
-  getOutboundQueue() {
-    return this.outboundQueue;
+  registerQuerySubset(subset) {
+    const id = `query-${nextQuerySubsetId++}`;
+    this.querySubsets.set(id, subset);
+    this.scheduleQuerySubsetReconnect();
+    return () => {
+      this.querySubsets.delete(id);
+      this.scheduleQuerySubsetReconnect();
+    };
+  }
+  /**
+   * Returns deduplicated active query subsets from registered subscriptions.
+   */
+  getActiveQuerySubsets() {
+    return dedupeQuerySubsets([...this.querySubsets.values()]);
+  }
+  /**
+   * Get the awareness manager for collaborative presence.
+   * Use this to set local presence, observe remote collaborators,
+   * and track cursor positions in richtext fields.
+   */
+  getAwarenessManager() {
+    return this.awarenessManager;
+  }
+  /**
+   * Optional side channel for incremental Yjs updates on large richtext fields.
+   */
+  getRichtextDocChannel() {
+    return this.richtextDocChannel;
   }
   // --- Private methods ---
-  handleMessage(message) {
+  messageChain = Promise.resolve();
+  enqueueMessage(message) {
+    this.messageChain = this.messageChain.then(() => this.handleMessageAsync(message)).catch((error) => this.handleMessageFailure(error));
+  }
+  async handleMessageAsync(message) {
     switch (message.type) {
       case "handshake-response":
         this.handleHandshakeResponse(message);
         break;
       case "operation-batch":
-        this.handleOperationBatch(message);
+        await this.handleOperationBatch(message);
         break;
       case "acknowledgment":
         this.handleAcknowledgment(message);
@@ -1314,58 +2659,114 @@ var SyncEngine = class {
       case "error":
         this.handleError(message);
         break;
+      case "awareness-update":
+        this.handleAwarenessUpdate(message);
+        break;
+      case "yjs-doc-update":
+        this.richtextDocChannel.deliver(message);
+        break;
     }
   }
+  handleMessageFailure(error) {
+    const reason = error instanceof Error ? error.message : "Message handling failed";
+    this.handleTransportClose(reason);
+  }
   handleHandshakeResponse(msg) {
     if (this.state !== "handshaking") return;
     if (!msg.accepted) {
+      const reason = msg.rejectReason ?? "Handshake rejected";
+      if (isSchemaMismatchReject(msg.rejectReason)) {
+        this.schemaBlocked = true;
+        const supportedMin = msg.supportedSchemaMin ?? msg.schemaVersion;
+        const supportedMax = msg.supportedSchemaMax ?? msg.schemaVersion;
+        this.emitter?.emit({
+          type: "sync:schema-mismatch",
+          clientSchemaVersion: this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION,
+          serverSchemaVersion: msg.schemaVersion,
+          supportedMin,
+          supportedMax,
+          reason
+        });
+        this.metricsCollector.updateStatus("error");
+        this.transitionTo("error");
+        void this.transport.disconnect();
+        return;
+      }
       this.transitionTo("error");
       this.emitter?.emit({
         type: "sync:disconnected",
-        reason: msg.rejectReason ?? "Handshake rejected"
+        reason
       });
       this.transitionTo("disconnected");
       return;
     }
     this.remoteVector = wireToVersionVector(msg.versionVector);
+    void this.persistLastAckedServerVector(this.remoteVector);
     if (msg.selectedWireFormat) {
       this.setSerializerWireFormat(msg.selectedWireFormat);
     }
+    if (msg.acceptedScope) {
+      this.activeScope = msg.acceptedScope;
+    }
     this.emitter?.emit({ type: "sync:connected", nodeId: this.store.getNodeId() });
+    this.metricsCollector.recordConnected();
+    this.metricsCollector.updateStatus("syncing");
+    this.metricsCollector.recordSyncStarted();
     this.transitionTo("syncing");
     this.deltaBatchesReceived = 0;
     this.deltaReceiveComplete = false;
     this.deltaSendComplete = false;
+    this.deltaSentOpIds = [];
+    this.pendingDeltaBatchAcks.clear();
+    this.initialSyncTotalBatches = 0;
     this.sendDelta();
   }
   async sendDelta() {
     const localVector = this.store.getVersionVector();
-    const missingOps = await this.collectDelta(localVector, this.remoteVector);
+    const allMissingOps = await this.collectDelta(localVector, this.remoteVector);
+    const missingOps = allMissingOps.filter((op) => this.operationAllowedForSync(op));
+    this.deltaSentOpIds = missingOps.map((op) => op.id);
     if (missingOps.length === 0) {
+      const messageId = generateMessageId();
+      if (this.config.strictHandshake) {
+        this.pendingDeltaBatchAcks.add(messageId);
+      }
       const emptyBatch = {
         type: "operation-batch",
-        messageId: generateMessageId(),
+        messageId,
         operations: [],
         isFinal: true,
-        batchIndex: 0
+        batchIndex: 0,
+        totalBatches: 1
       };
       this.transport.send(emptyBatch);
-      this.deltaSendComplete = true;
-      this.checkDeltaComplete();
+      if (!this.config.strictHandshake) {
+        this.deltaSendComplete = true;
+        void this.checkDeltaComplete();
+      }
       return;
     }
     const sorted = topologicalSort2(missingOps);
     const totalBatches = Math.ceil(sorted.length / this.batchSize);
+    this.initialSyncTotalBatches = Math.max(this.initialSyncTotalBatches, totalBatches);
     for (let i = 0; i < totalBatches; i++) {
       const start = i * this.batchSize;
       const batchOps = sorted.slice(start, start + this.batchSize);
-      const serializedOps = batchOps.map((op) => this.serializer.encodeOperation(op));
+      const batchCursor = createDeltaCursorFromBatch(batchOps, i);
+      const opsToSerialize = this.encryptor ? await this.encryptor.encryptBatch(batchOps) : batchOps;
+      const serializedOps = opsToSerialize.map((op) => this.serializer.encodeOperation(op));
+      const messageId = generateMessageId();
+      if (this.config.strictHandshake) {
+        this.pendingDeltaBatchAcks.add(messageId);
+      }
       const batchMsg = {
         type: "operation-batch",
-        messageId: generateMessageId(),
+        messageId,
         operations: serializedOps,
         isFinal: i === totalBatches - 1,
-        batchIndex: i
+        batchIndex: i,
+        totalBatches,
+        ...batchCursor ? { cursor: encodeDeltaCursor(batchCursor) } : {}
       };
       this.transport.send(batchMsg);
       this.emitter?.emit({
@@ -1374,8 +2775,17 @@ var SyncEngine = class {
         batchSize: batchOps.length
       });
     }
+    if (!this.config.strictHandshake) {
+      this.deltaSendComplete = true;
+      void this.checkDeltaComplete();
+    }
+  }
+  markDeltaSendCompleteIfReady() {
+    if (this.config.strictHandshake && this.pendingDeltaBatchAcks.size > 0) {
+      return;
+    }
     this.deltaSendComplete = true;
-    this.checkDeltaComplete();
+    void this.checkDeltaComplete();
   }
   async collectDelta(localVector, remoteVector) {
     const missing = [];
@@ -1389,15 +2799,45 @@ var SyncEngine = class {
     return missing;
   }
   async handleOperationBatch(msg) {
-    const operations = msg.operations.map((s) => this.serializer.decodeOperation(s));
-    for (const op of operations) {
-      await this.store.applyRemoteOperation(op);
+    const deserialized = msg.operations.map((s) => this.serializer.decodeOperation(s));
+    const operations = this.encryptor ? await this.encryptor.decryptBatch(deserialized) : deserialized;
+    const inScopeOps = operations.filter((op) => this.operationAllowedForSync(op));
+    const targetSchemaVersion = this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
+    const transforms = this.config.operationTransforms ?? [];
+    for (const op of inScopeOps) {
+      const transformed = transforms.length > 0 ? applyOperationTransforms(op, targetSchemaVersion, transforms) : op;
+      if (transformed === null) {
+        continue;
+      }
+      try {
+        const result = await this.store.applyRemoteOperation(transformed);
+        if (result === "skipped" || result === "rejected" || result === "deferred") {
+          this.emitApplyFailure(transformed, result);
+        }
+      } catch (error) {
+        if (error instanceof ClockDriftError) {
+          this.emitApplyFailure(transformed, "rejected", {
+            code: APPLY_FAILURE_CODES.CLOCK_DRIFT,
+            message: error.message,
+            retriable: false
+          });
+          continue;
+        }
+        const message = error instanceof Error ? error.message : "Apply failed";
+        const code = error instanceof SyncError4 ? error.code : error instanceof KoraError2 ? error.code : error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : APPLY_FAILURE_CODES.APPLY_FAILED;
+        this.emitApplyFailure(transformed, "rejected", {
+          code,
+          message,
+          retriable: code !== APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY
+        });
+      }
     }
-    if (operations.length > 0) {
+    if (inScopeOps.length > 0) {
+      this.lastSuccessfulPull = Date.now();
       this.emitter?.emit({
         type: "sync:received",
-        operations,
-        batchSize: operations.length
+        operations: inScopeOps,
+        batchSize: inScopeOps.length
       });
     }
     const lastOp = operations[operations.length - 1];
@@ -1414,18 +2854,43 @@ var SyncEngine = class {
     });
     if (this.state === "syncing") {
       this.deltaBatchesReceived++;
+      const totalBatches = msg.totalBatches ?? this.initialSyncTotalBatches;
+      if (msg.totalBatches !== void 0) {
+        this.initialSyncTotalBatches = msg.totalBatches;
+      }
+      this.metricsCollector.updateInitialSyncProgress(this.deltaBatchesReceived, totalBatches);
+      const cursorFromBatch = msg.cursor !== void 0 ? decodeDeltaCursor(msg.cursor) : createDeltaCursorFromBatch(
+        inScopeOps.length > 0 ? inScopeOps : operations,
+        msg.batchIndex
+      );
+      if (cursorFromBatch) {
+        this.resumeDeltaCursor = cursorFromBatch;
+        await this.persistDeltaCursor(cursorFromBatch);
+      }
       if (msg.isFinal) {
         this.deltaReceiveComplete = true;
-        this.checkDeltaComplete();
+        this.resumeDeltaCursor = null;
+        await this.persistDeltaCursor(null);
+        this.metricsCollector.recordSyncCompleted();
+        void this.checkDeltaComplete();
       }
     }
   }
   handleAcknowledgment(msg) {
+    if (this.state === "syncing" && this.config.strictHandshake) {
+      this.pendingDeltaBatchAcks.delete(msg.acknowledgedMessageId);
+      this.markDeltaSendCompleteIfReady();
+    }
     if (this.currentBatch) {
       this.outboundQueue.acknowledge(this.currentBatch.batchId);
       this.currentBatch = null;
-      this.lastSyncedAt = Date.now();
+      const now = Date.now();
+      this.lastSyncedAt = now;
+      this.lastSuccessfulPush = now;
     }
+    void this.advanceLastAckedForLocalNode(msg.lastSequenceNumber).then(
+      () => this.refreshPendingCount()
+    );
     if (this.state === "streaming" && this.outboundQueue.hasOperations) {
       this.flushQueue();
     }
@@ -1438,13 +2903,107 @@ var SyncEngine = class {
     this.emitter?.emit({ type: "sync:disconnected", reason: msg.message });
     this.transitionTo("disconnected");
   }
-  checkDeltaComplete() {
-    if (this.deltaSendComplete && this.deltaReceiveComplete) {
-      this.lastSyncedAt = Date.now();
-      this.transitionTo("streaming");
-      if (this.outboundQueue.hasOperations) {
-        this.flushQueue();
+  async checkDeltaComplete() {
+    if (!this.deltaSendComplete || !this.deltaReceiveComplete) {
+      return;
+    }
+    if (this.state !== "syncing") {
+      return;
+    }
+    this.lastSyncedAt = Date.now();
+    this.transitionTo("streaming");
+    this.awarenessManager.startCleanupTimer();
+    const localState = this.awarenessManager.getLocalState();
+    if (localState) {
+      this.awarenessManager.setLocalState(localState);
+    }
+    if (this.deltaSentOpIds.length > 0) {
+      await this.outboundQueue.removeByIds(this.deltaSentOpIds);
+      this.deltaSentOpIds = [];
+    }
+    if (this.syncState) {
+      const localNodeId = this.store.getNodeId();
+      const localSeq = this.store.getVersionVector().get(localNodeId) ?? 0;
+      if (localSeq > 0) {
+        await this.advanceLastAckedForLocalNode(localSeq);
+      }
+    }
+    if (this.outboundQueue.hasOperations) {
+      this.flushQueue();
+    }
+    await this.refreshPendingCount();
+  }
+  /**
+   * Effective server vector: persisted last-ack merged with live handshake remote vector.
+   */
+  getEffectiveServerVector() {
+    if (!this.syncState) {
+      return this.remoteVector;
+    }
+    return this.syncState.mergeServerVectors(this.lastAckedServerVector, this.remoteVector);
+  }
+  async persistLastAckedServerVector(vector) {
+    if (!this.syncState) {
+      return;
+    }
+    this.lastAckedServerVector = this.syncState.mergeServerVectors(
+      this.lastAckedServerVector,
+      vector
+    );
+    await this.syncState.saveLastAckedServerVector(this.lastAckedServerVector);
+  }
+  async advanceLastAckedForLocalNode(lastSequenceNumber) {
+    if (!this.syncState || lastSequenceNumber <= 0) {
+      return;
+    }
+    const nodeId = this.store.getNodeId();
+    const merged = new Map(this.lastAckedServerVector);
+    merged.set(nodeId, Math.max(merged.get(nodeId) ?? 0, lastSequenceNumber));
+    this.lastAckedServerVector = merged;
+    await this.syncState.saveLastAckedServerVector(merged);
+  }
+  /**
+   * Refresh cached unsynced count from op log vs effective server vector.
+   */
+  async refreshPendingCount() {
+    if (!this.syncState) {
+      this.cachedUnsyncedCount = this.outboundQueue.totalPending;
+      return;
+    }
+    this.cachedUnsyncedCount = await this.syncState.countUnsyncedOperations(
+      this.getEffectiveServerVector()
+    );
+  }
+  /**
+   * Returns operations the server has not yet acknowledged (op-log source of truth).
+   */
+  async getPendingSyncOperations() {
+    if (!this.syncState) {
+      return this.outboundQueue.peek(Number.MAX_SAFE_INTEGER);
+    }
+    return this.syncState.getUnsyncedOperations(this.getEffectiveServerVector());
+  }
+  /**
+   * Hydrate the outbound queue from unsynced ops in the op log (deduped by operation id).
+   */
+  async reconcileOutboundFromOpLog() {
+    if (this.syncState) {
+      const unsynced = await this.syncState.getUnsyncedOperations(this.getEffectiveServerVector());
+      for (const op of unsynced) {
+        await this.outboundQueue.enqueue(op);
       }
+      return;
+    }
+    const localNodeId = this.store.getNodeId();
+    const localVector = this.store.getVersionVector();
+    const localSeq = localVector.get(localNodeId) ?? 0;
+    if (localSeq === 0) {
+      return;
+    }
+    const ops = await this.store.getOperationRange(localNodeId, 1, localSeq);
+    const inScope = ops.filter((op) => this.operationAllowedForSync(op));
+    for (const op of inScope) {
+      await this.outboundQueue.enqueue(op);
     }
   }
   flushQueue() {
@@ -1453,26 +3012,66 @@ var SyncEngine = class {
     const batch = this.outboundQueue.takeBatch(this.batchSize);
     if (!batch) return;
     this.currentBatch = batch;
-    const serializedOps = batch.operations.map((op) => this.serializer.encodeOperation(op));
-    const batchMsg = {
-      type: "operation-batch",
-      messageId: generateMessageId(),
-      operations: serializedOps,
-      isFinal: true,
-      batchIndex: 0
+    if (this.encryptor) {
+      this.encryptor.encryptBatch(batch.operations).then(
+        (encrypted) => {
+          const serializedOps = encrypted.map((op) => this.serializer.encodeOperation(op));
+          const batchMsg = {
+            type: "operation-batch",
+            messageId: generateMessageId(),
+            operations: serializedOps,
+            isFinal: true,
+            batchIndex: 0
+          };
+          this.transport.send(batchMsg);
+          this.emitter?.emit({
+            type: "sync:sent",
+            operations: batch.operations,
+            batchSize: batch.operations.length
+          });
+        },
+        (err) => {
+          this.outboundQueue.returnBatch(batch.batchId);
+          this.currentBatch = null;
+          this.emitter?.emit({
+            type: "sync:disconnected",
+            reason: err instanceof Error ? err.message : "Encryption failed"
+          });
+        }
+      );
+    } else {
+      const serializedOps = batch.operations.map((op) => this.serializer.encodeOperation(op));
+      const batchMsg = {
+        type: "operation-batch",
+        messageId: generateMessageId(),
+        operations: serializedOps,
+        isFinal: true,
+        batchIndex: 0
+      };
+      this.transport.send(batchMsg);
+      this.emitter?.emit({
+        type: "sync:sent",
+        operations: batch.operations,
+        batchSize: batch.operations.length
+      });
+    }
+  }
+  handleAwarenessUpdate(msg) {
+    const awarenessMessage = {
+      type: "awareness",
+      clientId: msg.clientId,
+      states: wireToAwarenessStates(msg.states)
     };
-    this.transport.send(batchMsg);
-    this.emitter?.emit({
-      type: "sync:sent",
-      operations: batch.operations,
-      batchSize: batch.operations.length
-    });
+    this.awarenessManager.handleRemoteMessage(awarenessMessage);
   }
   handleTransportClose(reason) {
     if (this.currentBatch) {
       this.outboundQueue.returnBatch(this.currentBatch.batchId);
       this.currentBatch = null;
     }
+    if (this.schemaBlocked) {
+      return;
+    }
     if (this.state !== "disconnected") {
       this.emitter?.emit({ type: "sync:disconnected", reason });
       this.transitionTo("disconnected");
@@ -1500,7 +3099,68 @@ var SyncEngine = class {
       this.serializer.setWireFormat(format);
     }
   }
+  operationAllowedForSync(op) {
+    if (!operationMatchesScope(op, this.activeScope)) {
+      return false;
+    }
+    return operationMatchesQuerySubsets(op, this.getActiveQuerySubsets());
+  }
+  async persistDeltaCursor(cursor) {
+    if (!this.syncState?.saveDeltaCursor) {
+      return;
+    }
+    await this.syncState.saveDeltaCursor(cursor);
+  }
+  scheduleQuerySubsetReconnect() {
+    if (this.querySubsetReconnectTimer) {
+      clearTimeout(this.querySubsetReconnectTimer);
+    }
+    this.querySubsetReconnectTimer = setTimeout(() => {
+      this.querySubsetReconnectTimer = null;
+      if (this.state === "streaming" || this.state === "syncing" || this.state === "handshaking") {
+        void this.reconnectForQuerySubsets();
+      }
+    }, 500);
+  }
+  async reconnectForQuerySubsets() {
+    await this.stop();
+    await this.start();
+  }
 };
+function awarenessStatesToWire(states) {
+  const wire = {};
+  for (const [clientId, state] of Object.entries(states)) {
+    if (state === null) {
+      wire[clientId] = null;
+    } else {
+      const wireState = {
+        user: { ...state.user }
+      };
+      if (state.cursor) {
+        wireState.cursor = { ...state.cursor };
+      }
+      wire[clientId] = wireState;
+    }
+  }
+  return wire;
+}
+function wireToAwarenessStates(wire) {
+  const states = {};
+  for (const [clientId, wireState] of Object.entries(wire)) {
+    if (wireState === null) {
+      states[Number(clientId)] = null;
+    } else {
+      const state = {
+        user: { ...wireState.user }
+      };
+      if (wireState.cursor) {
+        state.cursor = { ...wireState.cursor };
+      }
+      states[Number(clientId)] = state;
+    }
+  }
+  return states;
+}
 
 // src/engine/connection-monitor.ts
 var ConnectionMonitor = class {
@@ -1639,6 +3299,20 @@ var ReconnectionManager = class {
       this.running = false;
     }
   }
+  /**
+   * Cancel the current backoff wait and proceed to the next reconnect attempt immediately.
+   * No-op if not waiting.
+   */
+  wake() {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.waitResolve) {
+      this.waitResolve();
+      this.waitResolve = null;
+    }
+  }
   /**
    * Stop any pending reconnection attempt.
    */
@@ -1693,25 +3367,480 @@ var ReconnectionManager = class {
     });
   }
 };
+
+// src/encryption/sync-encryptor.ts
+import { SyncError as SyncError6 } from "@korajs/core";
+
+// src/encryption/key-derivation.ts
+import { SyncError as SyncError5 } from "@korajs/core";
+var KeyDerivationError = class extends SyncError5 {
+  constructor(message, context) {
+    super(message, { ...context, errorType: "KEY_DERIVATION_ERROR" });
+    this.name = "KeyDerivationError";
+  }
+};
+var SALT_LENGTH = 32;
+var PBKDF2_ITERATIONS = 6e5;
+var DERIVED_KEY_LENGTH = 256;
+function assertCryptoAvailable() {
+  if (typeof globalThis.crypto === "undefined" || typeof globalThis.crypto.subtle === "undefined") {
+    throw new KeyDerivationError(
+      "Web Crypto API (crypto.subtle) is not available in this environment. Sync encryption requires crypto.subtle, which is available in modern browsers and Node.js 20+."
+    );
+  }
+}
+function generateSalt() {
+  if (typeof globalThis.crypto === "undefined") {
+    throw new KeyDerivationError(
+      "Web Crypto API (crypto) is not available. Cannot generate random salt."
+    );
+  }
+  return globalThis.crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
+}
+async function deriveKey(passphrase, salt) {
+  assertCryptoAvailable();
+  if (passphrase.length === 0) {
+    throw new KeyDerivationError(
+      "Passphrase must not be empty. Provide a non-empty string for encryption key derivation."
+    );
+  }
+  const usedSalt = salt ?? generateSalt();
+  try {
+    const passphraseBytes = new TextEncoder().encode(passphrase);
+    const baseKey = await globalThis.crypto.subtle.importKey(
+      "raw",
+      passphraseBytes,
+      "PBKDF2",
+      false,
+      ["deriveBits", "deriveKey"]
+    );
+    const derivedKey = await globalThis.crypto.subtle.deriveKey(
+      {
+        name: "PBKDF2",
+        salt: usedSalt,
+        iterations: PBKDF2_ITERATIONS,
+        hash: "SHA-256"
+      },
+      baseKey,
+      { name: "AES-GCM", length: DERIVED_KEY_LENGTH },
+      // extractable: true so the derived key can be exported for testing/debugging
+      true,
+      ["encrypt", "decrypt"]
+    );
+    return { key: derivedKey, salt: usedSalt };
+  } catch (cause) {
+    if (cause instanceof KeyDerivationError) {
+      throw cause;
+    }
+    throw new KeyDerivationError(
+      "Failed to derive encryption key from passphrase using PBKDF2. Ensure the runtime supports PBKDF2 with SHA-256.",
+      { cause: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function deriveVersionedKey(passphrase, version, salt) {
+  if (!Number.isInteger(version) || version < 1) {
+    throw new KeyDerivationError(`Key version must be a positive integer, received: ${version}`, {
+      version
+    });
+  }
+  const { key, salt: usedSalt } = await deriveKey(passphrase, salt);
+  return { version, key, salt: usedSalt };
+}
+
+// src/encryption/sync-encryptor.ts
+var EncryptionError = class extends SyncError6 {
+  constructor(message, context) {
+    super(message, { ...context, errorType: "ENCRYPTION_ERROR" });
+    this.name = "EncryptionError";
+  }
+};
+var DecryptionError = class extends SyncError6 {
+  constructor(message, context) {
+    super(message, { ...context, errorType: "DECRYPTION_ERROR" });
+    this.name = "DecryptionError";
+  }
+};
+var IV_LENGTH = 12;
+var ENCRYPTED_MARKER = "__kora_e2e_encrypted";
+var SyncEncryptor = class _SyncEncryptor {
+  /**
+   * Map of key version -> VersionedKey. The current (latest) version is used
+   * for encryption. All versions are available for decryption (key rotation).
+   */
+  keys;
+  /** The current key version used for encryption. */
+  currentVersion;
+  constructor(keys, currentVersion) {
+    this.keys = keys;
+    this.currentVersion = currentVersion;
+  }
+  /**
+   * Creates a SyncEncryptor from a {@link SyncEncryptionConfig}.
+   *
+   * Derives the encryption key from the passphrase using PBKDF2. The key
+   * derivation is async because it uses the Web Crypto API.
+   *
+   * @param config - Encryption configuration with passphrase
+   * @param salt - Optional salt for deterministic key derivation (mainly for testing).
+   *              If omitted, a random salt is generated.
+   * @returns A configured SyncEncryptor instance
+   * @throws {EncryptionError} If configuration is invalid
+   * @throws {KeyDerivationError} If key derivation fails
+   */
+  static async create(config, salt) {
+    if (!config.enabled) {
+      throw new EncryptionError(
+        "Cannot create SyncEncryptor with encryption disabled. Set enabled: true in the encryption config."
+      );
+    }
+    const passphrase = typeof config.key === "function" ? await config.key() : config.key;
+    if (passphrase.length === 0) {
+      throw new EncryptionError(
+        "Encryption key/passphrase must not be empty. Provide a non-empty string or key provider function."
+      );
+    }
+    const versionedKey = await deriveVersionedKey(passphrase, 1, salt);
+    const keys = /* @__PURE__ */ new Map();
+    keys.set(1, versionedKey);
+    return new _SyncEncryptor(keys, 1);
+  }
+  /**
+   * Creates a SyncEncryptor from pre-derived versioned keys.
+   *
+   * Use this when you need to support multiple key versions for key rotation,
+   * or when you have already derived the keys externally.
+   *
+   * @param versionedKeys - Array of versioned keys. The highest version is used for encryption.
+   * @returns A configured SyncEncryptor instance
+   * @throws {EncryptionError} If no keys are provided
+   */
+  static fromKeys(versionedKeys) {
+    if (versionedKeys.length === 0) {
+      throw new EncryptionError("At least one versioned key must be provided.");
+    }
+    const keys = /* @__PURE__ */ new Map();
+    let maxVersion = 0;
+    for (const vk of versionedKeys) {
+      keys.set(vk.version, vk);
+      if (vk.version > maxVersion) {
+        maxVersion = vk.version;
+      }
+    }
+    return new _SyncEncryptor(keys, maxVersion);
+  }
+  /**
+   * Add a new key version for key rotation.
+   *
+   * After adding, the new key becomes the current version used for encryption
+   * if its version number is higher than the current version. Previously-versioned
+   * keys remain available for decrypting older operations.
+   *
+   * @param key - The new versioned key to add
+   * @throws {EncryptionError} If the key version already exists
+   */
+  addKey(key) {
+    if (this.keys.has(key.version)) {
+      throw new EncryptionError(
+        `Key version ${key.version} already exists. Use a higher version number for rotation.`,
+        { existingVersion: key.version }
+      );
+    }
+    this.keys.set(key.version, key);
+    if (key.version > this.currentVersion) {
+      this.currentVersion = key.version;
+    }
+  }
+  /**
+   * Get the current encryption key version number.
+   */
+  getCurrentKeyVersion() {
+    return this.currentVersion;
+  }
+  /**
+   * Encrypt an operation's `data` and `previousData` fields.
+   *
+   * Returns a new Operation with encrypted field values. The original
+   * operation is not mutated (operations are immutable).
+   *
+   * Fields that are null (e.g., delete operations) remain null.
+   *
+   * @param operation - The operation to encrypt
+   * @returns A new operation with encrypted data fields
+   * @throws {EncryptionError} If encryption fails
+   */
+  async encryptOperation(operation) {
+    const [encryptedData, encryptedPreviousData] = await Promise.all([
+      this.encryptField(operation.data, operation.id, "data"),
+      this.encryptField(operation.previousData, operation.id, "previousData")
+    ]);
+    return {
+      ...operation,
+      data: encryptedData,
+      previousData: encryptedPreviousData
+    };
+  }
+  /**
+   * Decrypt an operation's `data` and `previousData` fields.
+   *
+   * Returns a new Operation with the original field values restored.
+   * The original operation is not mutated.
+   *
+   * If a field is null or not encrypted (no marker), it passes through unchanged.
+   * This enables mixed plaintext/encrypted operations during migration.
+   *
+   * @param operation - The operation to decrypt
+   * @returns A new operation with decrypted data fields
+   * @throws {DecryptionError} If decryption fails (wrong key, tampered data, unsupported version)
+   */
+  async decryptOperation(operation) {
+    const [decryptedData, decryptedPreviousData] = await Promise.all([
+      this.decryptField(operation.data, operation.id, "data"),
+      this.decryptField(operation.previousData, operation.id, "previousData")
+    ]);
+    return {
+      ...operation,
+      data: decryptedData,
+      previousData: decryptedPreviousData
+    };
+  }
+  /**
+   * Encrypt a serialized operation's `data` and `previousData` fields.
+   *
+   * Same as {@link encryptOperation} but works with the wire-format
+   * {@link SerializedOperation} type used by the serializer.
+   *
+   * @param serialized - The serialized operation to encrypt
+   * @returns A new serialized operation with encrypted data fields
+   * @throws {EncryptionError} If encryption fails
+   */
+  async encryptSerializedOperation(serialized) {
+    const [encryptedData, encryptedPreviousData] = await Promise.all([
+      this.encryptField(serialized.data, serialized.id, "data"),
+      this.encryptField(serialized.previousData, serialized.id, "previousData")
+    ]);
+    return {
+      ...serialized,
+      data: encryptedData,
+      previousData: encryptedPreviousData
+    };
+  }
+  /**
+   * Decrypt a serialized operation's `data` and `previousData` fields.
+   *
+   * Same as {@link decryptOperation} but works with the wire-format
+   * {@link SerializedOperation} type used by the serializer.
+   *
+   * @param serialized - The serialized operation to decrypt
+   * @returns A new serialized operation with decrypted data fields
+   * @throws {DecryptionError} If decryption fails
+   */
+  async decryptSerializedOperation(serialized) {
+    const [decryptedData, decryptedPreviousData] = await Promise.all([
+      this.decryptField(serialized.data, serialized.id, "data"),
+      this.decryptField(serialized.previousData, serialized.id, "previousData")
+    ]);
+    return {
+      ...serialized,
+      data: decryptedData,
+      previousData: decryptedPreviousData
+    };
+  }
+  /**
+   * Encrypt a batch of operations in parallel.
+   *
+   * @param operations - Operations to encrypt
+   * @returns New operations with encrypted data fields
+   */
+  async encryptBatch(operations) {
+    return Promise.all(operations.map((op) => this.encryptOperation(op)));
+  }
+  /**
+   * Decrypt a batch of operations in parallel.
+   *
+   * @param operations - Operations to decrypt
+   * @returns New operations with decrypted data fields
+   */
+  async decryptBatch(operations) {
+    return Promise.all(operations.map((op) => this.decryptOperation(op)));
+  }
+  /**
+   * Check if a field value contains an encrypted payload.
+   *
+   * @param field - An operation's `data` or `previousData` field
+   * @returns true if the field contains an encrypted payload
+   */
+  static isEncryptedPayload(field) {
+    return isEncryptedPayload(field);
+  }
+  // --- Private helpers ---
+  async encryptField(field, operationId, fieldName) {
+    if (field === null) {
+      return null;
+    }
+    const currentKey = this.keys.get(this.currentVersion);
+    if (!currentKey) {
+      throw new EncryptionError(
+        `Current encryption key version ${this.currentVersion} not found.`,
+        { operationId, fieldName }
+      );
+    }
+    try {
+      const plaintext = new TextEncoder().encode(JSON.stringify(field));
+      const iv = globalThis.crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+      const ciphertextBuffer = await globalThis.crypto.subtle.encrypt(
+        { name: "AES-GCM", iv },
+        currentKey.key,
+        plaintext
+      );
+      const payload = {
+        v: this.currentVersion,
+        iv: toBase642(iv),
+        ct: toBase642(new Uint8Array(ciphertextBuffer)),
+        alg: "aes-256-gcm"
+      };
+      return {
+        [ENCRYPTED_MARKER]: true,
+        ...payload
+      };
+    } catch (cause) {
+      if (cause instanceof EncryptionError) {
+        throw cause;
+      }
+      throw new EncryptionError(
+        `Failed to encrypt operation ${fieldName} field. Ensure the encryption key is valid and crypto.subtle is available.`,
+        {
+          operationId,
+          fieldName,
+          cause: cause instanceof Error ? cause.message : String(cause)
+        }
+      );
+    }
+  }
+  async decryptField(field, operationId, fieldName) {
+    if (field === null) {
+      return null;
+    }
+    if (!isEncryptedPayload(field)) {
+      return field;
+    }
+    const payload = field;
+    const keyVersion = payload.v;
+    const key = this.keys.get(keyVersion);
+    if (!key) {
+      throw new DecryptionError(
+        `No encryption key available for version ${keyVersion}. This operation was encrypted with a key that is not registered. If you rotated keys, ensure all previous key versions are provided.`,
+        { operationId, fieldName, keyVersion, availableVersions: [...this.keys.keys()] }
+      );
+    }
+    if (payload.alg !== "aes-256-gcm") {
+      throw new DecryptionError(
+        `Unsupported encryption algorithm: "${payload.alg}". Only "aes-256-gcm" is supported. Update your @korajs/sync package.`,
+        { operationId, fieldName, algorithm: payload.alg }
+      );
+    }
+    try {
+      const iv = fromBase642(payload.iv);
+      const ciphertext = fromBase642(payload.ct);
+      const plaintextBuffer = await globalThis.crypto.subtle.decrypt(
+        { name: "AES-GCM", iv },
+        key.key,
+        ciphertext
+      );
+      const json = new TextDecoder().decode(plaintextBuffer);
+      const parsed = JSON.parse(json);
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new DecryptionError(`Decrypted ${fieldName} is not a valid record object.`, {
+          operationId,
+          fieldName
+        });
+      }
+      return parsed;
+    } catch (cause) {
+      if (cause instanceof DecryptionError) {
+        throw cause;
+      }
+      throw new DecryptionError(
+        `Failed to decrypt operation ${fieldName} field. This may indicate a wrong encryption key, tampered ciphertext, or corrupted data.`,
+        {
+          operationId,
+          fieldName,
+          keyVersion,
+          cause: cause instanceof Error ? cause.message : String(cause)
+        }
+      );
+    }
+  }
+};
+function isEncryptedPayload(field) {
+  if (field === null || typeof field !== "object") {
+    return false;
+  }
+  return field[ENCRYPTED_MARKER] === true && typeof field.v === "number" && typeof field.iv === "string" && typeof field.ct === "string" && typeof field.alg === "string";
+}
+function toBase642(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function fromBase642(str) {
+  const binary = atob(str);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
 export {
+  AwarenessManager,
   ChaosTransport,
   ConnectionMonitor,
+  DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
+  DecryptionError,
+  EncryptionError,
   HttpLongPollingTransport,
+  InvalidScopeError,
   JsonMessageSerializer,
+  KeyDerivationError,
   NegotiatedMessageSerializer,
   OutboundQueue,
   ProtobufMessageSerializer,
   ReconnectionManager,
+  RichtextDocChannel,
+  SCHEMA_MISMATCH_PREFIX,
   SYNC_STATES,
   SYNC_STATUSES,
+  ScopeViolationError,
+  SyncEncryptor,
   SyncEngine,
   WebSocketTransport,
+  createDeltaCursorFromBatch,
+  decodeDeltaCursor,
+  decodeYjsUpdate,
+  dedupeQuerySubsets,
+  deriveKey,
+  deriveVersionedKey,
+  encodeDeltaCursor,
+  encodeYjsUpdate,
+  filterOperationsByScope,
+  generateSalt,
   isAcknowledgmentMessage,
+  isAwarenessUpdateMessage,
+  isClientSchemaVersionSupported,
+  isEncryptedPayload,
   isErrorMessage,
   isHandshakeMessage,
   isHandshakeResponseMessage,
   isOperationBatchMessage,
+  isSchemaMismatchReject,
   isSyncMessage,
+  isYjsDocUpdateMessage,
+  operationMatchesQuerySubsets,
+  operationMatchesScope,
+  richtextDocKey,
+  sliceOperationsAfterCursor,
   versionVectorToWire,
   wireToVersionVector
 };