@korajs/sync 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   AwarenessManager: () => AwarenessManager,
   ChaosTransport: () => ChaosTransport,
   ConnectionMonitor: () => ConnectionMonitor,
+  DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD: () => DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
   DecryptionError: () => DecryptionError,
   EncryptionError: () => EncryptionError,
   HttpLongPollingTransport: () => HttpLongPollingTransport,
@@ -40,28 +41,46 @@ __export(index_exports, {
   JsonMessageSerializer: () => JsonMessageSerializer,
   KeyDerivationError: () => KeyDerivationError,
   NegotiatedMessageSerializer: () => NegotiatedMessageSerializer,
+  OFFLINE_SYNC_STATUS: () => OFFLINE_SYNC_STATUS,
   OutboundQueue: () => OutboundQueue,
   ProtobufMessageSerializer: () => ProtobufMessageSerializer,
   ReconnectionManager: () => ReconnectionManager,
+  RichtextDocChannel: () => RichtextDocChannel,
+  SCHEMA_MISMATCH_PREFIX: () => SCHEMA_MISMATCH_PREFIX,
   SYNC_STATES: () => SYNC_STATES,
   SYNC_STATUSES: () => SYNC_STATUSES,
   ScopeViolationError: () => ScopeViolationError,
   SyncEncryptor: () => SyncEncryptor,
   SyncEngine: () => SyncEngine,
   WebSocketTransport: () => WebSocketTransport,
+  createDeltaCursorFromBatch: () => createDeltaCursorFromBatch,
+  createSyncStatusController: () => createSyncStatusController,
+  decodeDeltaCursor: () => decodeDeltaCursor,
+  decodeYjsUpdate: () => decodeYjsUpdate,
+  dedupeQuerySubsets: () => dedupeQuerySubsets,
   deriveKey: () => deriveKey,
   deriveVersionedKey: () => deriveVersionedKey,
+  encodeDeltaCursor: () => encodeDeltaCursor,
+  encodeYjsUpdate: () => encodeYjsUpdate,
   filterOperationsByScope: () => filterOperationsByScope,
   generateSalt: () => generateSalt,
+  getRemoteAwarenessStates: () => getRemoteAwarenessStates,
   isAcknowledgmentMessage: () => isAcknowledgmentMessage,
   isAwarenessUpdateMessage: () => isAwarenessUpdateMessage,
+  isClientSchemaVersionSupported: () => isClientSchemaVersionSupported,
   isEncryptedPayload: () => isEncryptedPayload,
   isErrorMessage: () => isErrorMessage,
   isHandshakeMessage: () => isHandshakeMessage,
   isHandshakeResponseMessage: () => isHandshakeResponseMessage,
   isOperationBatchMessage: () => isOperationBatchMessage,
+  isSchemaMismatchReject: () => isSchemaMismatchReject,
   isSyncMessage: () => isSyncMessage,
+  isYjsDocUpdateMessage: () => isYjsDocUpdateMessage,
+  operationMatchesQuerySubsets: () => operationMatchesQuerySubsets,
   operationMatchesScope: () => operationMatchesScope,
+  richtextDocKey: () => richtextDocKey,
+  sliceOperationsAfterCursor: () => sliceOperationsAfterCursor,
+  subscribeRemoteAwarenessStates: () => subscribeRemoteAwarenessStates,
   versionVectorToWire: () => versionVectorToWire,
   wireToVersionVector: () => wireToVersionVector
 });
@@ -77,7 +96,14 @@ 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 import_core.KoraError {
   constructor(operationId, collection, scope, message) {
     super(
@@ -102,12 +128,12 @@ var InvalidScopeError = class extends import_core.KoraError {
 };
 
 // src/scopes/scope-filter.ts
-function operationMatchesScope(op, scopeMap) {
+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);
+  const snapshot = buildSnapshot(op, fullRecord ?? void 0);
   if (!snapshot) return false;
   for (const [field, expected] of Object.entries(collectionScope)) {
     if (snapshot[field] !== expected) {
@@ -120,11 +146,12 @@ function filterOperationsByScope(operations, scopeMap) {
   if (!scopeMap) return operations;
   return operations.filter((op) => operationMatchesScope(op, scopeMap));
 }
-function buildSnapshot(op) {
+function buildSnapshot(op, fullRecord) {
   const previous = asRecord(op.previousData);
   const next = asRecord(op.data);
-  if (!previous && !next) return null;
+  if (!previous && !next && !fullRecord) return null;
   return {
+    ...fullRecord ?? {},
     ...previous ?? {},
     ...next ?? {}
   };
@@ -136,6 +163,128 @@ function asRecord(value) {
   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) {
   if (typeof value !== "object" || value === null) return false;
@@ -154,6 +303,8 @@ function isSyncMessage(value) {
       return isErrorMessage(value);
     case "awareness-update":
       return isAwarenessUpdateMessage(value);
+    case "yjs-doc-update":
+      return isYjsDocUpdateMessage(value);
     default:
       return false;
   }
@@ -188,6 +339,11 @@ function isAwarenessUpdateMessage(value) {
   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
 var import_core2 = require("@korajs/core");
@@ -203,6 +359,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);
@@ -231,8 +465,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,
@@ -253,8 +487,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,
@@ -375,6 +609,7 @@ function toProtoEnvelope(message) {
         retriable: message.retriable
       };
     case "awareness-update":
+    case "yjs-doc-update":
       return {
         type: message.type,
         messageId: message.messageId
@@ -1231,9 +1466,215 @@ var ChaosTransport = class {
 };
 
 // src/engine/sync-engine.ts
-var import_core5 = require("@korajs/core");
+var import_core6 = require("@korajs/core");
 var import_internal2 = require("@korajs/core/internal");
 
+// 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;
+  }
+  /**
+   * Set the local user's awareness state and broadcast to peers.
+   *
+   * @param state - The awareness state to share. Pass null to clear presence.
+   */
+  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);
+    }
+    for (const [id, state] of this.remoteStates) {
+      result.set(id, state);
+    }
+    return result;
+  }
+  /**
+   * Handle an incoming awareness message from the transport.
+   * This processes remote state updates and notifies listeners.
+   */
+  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();
+    }
+  }
+  /**
+   * Remove a specific remote client's awareness state.
+   * Called when the server notifies that a client has disconnected.
+   */
+  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();
+  }
+  /**
+   * Register a handler for sending awareness messages through the transport.
+   * The sync engine calls this to wire outgoing awareness messages to the transport.
+   */
+  onSend(handler) {
+    this.sendHandler = handler;
+  }
+  /**
+   * Register a listener for awareness state changes.
+   * Returns an unsubscribe function.
+   */
+  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;
+    }
+  }
+  /**
+   * 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.
+   */
+  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;
@@ -1275,6 +1716,7 @@ var BandwidthEstimator = class {
     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;
@@ -1340,7 +1782,7 @@ var SlidingWindowPercentile = class {
     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];
+    return sorted[index] ?? 0;
   }
   /**
    * Get the most recently added sample, or 0 if no samples exist.
@@ -1348,7 +1790,7 @@ var SlidingWindowPercentile = class {
   latest() {
     if (this.count === 0) return 0;
     const lastIndex = (this.writeIndex - 1 + this.maxSize) % this.maxSize;
-    return this.samples[lastIndex];
+    return this.samples[lastIndex] ?? 0;
   }
   /**
    * Get the number of samples currently in the window.
@@ -1675,209 +2117,106 @@ var SyncMetricsCollector = class {
   }
 };
 
-// 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;
-  }
-  /**
-   * Set the local user's awareness state and broadcast to peers.
-   *
-   * @param state - The awareness state to share. Pass null to clear presence.
-   */
-  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);
-    }
-    for (const [id, state] of this.remoteStates) {
-      result.set(id, state);
-    }
-    return result;
-  }
-  /**
-   * Handle an incoming awareness message from the transport.
-   * This processes remote state updates and notifies listeners.
-   */
-  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();
-    }
-  }
-  /**
-   * Remove a specific remote client's awareness state.
-   * Called when the server notifies that a client has disconnected.
-   */
-  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();
-  }
-  /**
-   * Register a handler for sending awareness messages through the transport.
-   * The sync engine calls this to wire outgoing awareness messages to the transport.
-   */
-  onSend(handler) {
-    this.sendHandler = handler;
-  }
-  /**
-   * Register a listener for awareness state changes.
-   * Returns an unsubscribe function.
-   */
-  on(_event, listener) {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
+// src/richtext/richtext-doc-channel.ts
+var import_core5 = require("@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]);
   }
-  /**
-   * Remove a specific change listener.
-   */
-  off(_event, listener) {
-    this.listeners.delete(listener);
+  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);
   }
-  /**
-   * 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);
+  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;
   }
   /**
-   * Stop the cleanup timer.
+   * Whether the doc channel should be used for a field.
+   * @param preference - `true` forces on, `false` forces off, `undefined` uses size threshold
    */
-  stopCleanupTimer() {
-    if (this.cleanupTimer) {
-      clearInterval(this.cleanupTimer);
-      this.cleanupTimer = null;
+  shouldUseChannel(snapshotByteLength, preference) {
+    if (preference === false) {
+      return false;
     }
+    if (preference === true) {
+      return true;
+    }
+    return snapshotByteLength >= this.threshold;
+  }
+  getThreshold() {
+    return this.threshold;
   }
   /**
-   * 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.
+   * Subscribe to incremental updates for a document key.
    */
-  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);
+  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);
     }
-    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);
+    set.add(listener);
+    return () => {
+      const current = this.listeners.get(key);
+      if (!current) {
+        return;
       }
-    }
-    if (removed.length > 0) {
-      const change = { added: [], updated: [], removed };
-      this.notifyListeners(change);
-      this.emitAwarenessEvent();
-    }
+      current.delete(listener);
+      if (current.size === 0) {
+        this.listeners.delete(key);
+      }
+    };
   }
-  notifyListeners(change) {
-    for (const listener of this.listeners) {
-      listener(change);
+  /**
+   * 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: (0, import_core5.generateUUIDv7)(),
+      collection,
+      recordId,
+      field,
+      update: encodeYjsUpdate(update)
+    });
   }
-  emitAwarenessEvent() {
-    const states = this.getStates();
-    this.emitter?.emit({ type: "awareness:updated", states });
+  /**
+   * 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);
+    }
   }
 };
 
@@ -2012,6 +2351,19 @@ var OutboundQueue = class {
   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
@@ -2026,6 +2378,7 @@ var VALID_TRANSITIONS = {
   error: ["disconnected"]
 };
 var nextMessageId = 0;
+var nextQuerySubsetId = 0;
 function generateMessageId() {
   return `msg-${Date.now()}-${nextMessageId++}`;
 }
@@ -2040,24 +2393,39 @@ var SyncEngine = class {
   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;
@@ -2066,6 +2434,7 @@ var SyncEngine = class {
     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);
@@ -2076,6 +2445,15 @@ var SyncEngine = class {
     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 = {
@@ -2092,20 +2470,35 @@ var SyncEngine = class {
    */
   async start() {
     if (this.state !== "disconnected") {
-      throw new import_core5.SyncError("Cannot start sync engine: not in disconnected state", {
+      throw new import_core6.SyncError("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 import_core6.SyncError(
+        "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(),
@@ -2114,7 +2507,9 @@ var SyncEngine = class {
         schemaVersion: this.config.schemaVersion ?? DEFAULT_SCHEMA_VERSION,
         authToken,
         supportedWireFormats: ["json", "protobuf"],
-        ...this.config.scopeMap ? { syncScope: this.config.scopeMap } : {}
+        ...this.config.scopeMap ? { syncScope: this.config.scopeMap } : {},
+        ...activeQuerySubsets.length > 0 ? { syncQueries: activeQuerySubsets } : {},
+        ...this.resumeDeltaCursor ? { deltaCursor: encodeDeltaCursor(this.resumeDeltaCursor) } : {}
       };
       this.transport.send(handshake);
     } catch (err) {
@@ -2151,10 +2546,16 @@ var SyncEngine = class {
    * because they should remain local-only and not be sent to the server.
    */
   async pushOperation(op) {
-    if (!operationMatchesScope(op, this.activeScope)) {
+    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();
     }
@@ -2172,7 +2573,7 @@ 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,
@@ -2190,7 +2591,24 @@ var SyncEngine = class {
       case "streaming":
         return { ...base, status: pendingOperations > 0 ? "syncing" : "synced" };
       case "error":
-        return { ...base, status: "error" };
+        return { ...base, status: this.schemaBlocked ? "schema-mismatch" : "error" };
+    }
+  }
+  /**
+   * 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");
     }
   }
   /**
@@ -2200,11 +2618,31 @@ var SyncEngine = class {
   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 = (0, import_core6.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();
@@ -2265,6 +2703,25 @@ var SyncEngine = class {
   getActiveScope() {
     return this.activeScope;
   }
+  /**
+   * Register a live query subset that narrows synced data for a collection.
+   * Takes effect on the next connection; reconnects when already connected.
+   */
+  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,
@@ -2273,14 +2730,24 @@ var SyncEngine = class {
   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);
@@ -2291,20 +2758,46 @@ var SyncEngine = class {
       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);
     }
@@ -2319,38 +2812,57 @@ var SyncEngine = class {
     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 allMissingOps = await this.collectDelta(localVector, this.remoteVector);
-    const missingOps = allMissingOps.filter((op) => operationMatchesScope(op, this.activeScope));
+    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 = (0, import_internal2.topologicalSort)(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 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({
@@ -2359,8 +2871,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 = [];
@@ -2376,9 +2897,36 @@ var SyncEngine = class {
   async handleOperationBatch(msg) {
     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) => operationMatchesScope(op, this.activeScope));
+    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) {
-      await this.store.applyRemoteOperation(op);
+      const transformed = transforms.length > 0 ? (0, import_core6.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 import_core6.ClockDriftError) {
+          this.emitApplyFailure(transformed, "rejected", {
+            code: import_core6.APPLY_FAILURE_CODES.CLOCK_DRIFT,
+            message: error.message,
+            retriable: false
+          });
+          continue;
+        }
+        const message = error instanceof Error ? error.message : "Apply failed";
+        const code = error instanceof import_core6.SyncError ? error.code : error instanceof import_core6.KoraError ? error.code : error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : import_core6.APPLY_FAILURE_CODES.APPLY_FAILED;
+        this.emitApplyFailure(transformed, "rejected", {
+          code,
+          message,
+          retriable: code !== import_core6.APPLY_FAILURE_CODES.REFERENTIAL_INTEGRITY
+        });
+      }
     }
     if (inScopeOps.length > 0) {
       this.lastSuccessfulPull = Date.now();
@@ -2402,13 +2950,33 @@ 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;
@@ -2416,6 +2984,9 @@ var SyncEngine = class {
       this.lastSyncedAt = now;
       this.lastSuccessfulPush = now;
     }
+    void this.advanceLastAckedForLocalNode(msg.lastSequenceNumber).then(
+      () => this.refreshPendingCount()
+    );
     if (this.state === "streaming" && this.outboundQueue.hasOperations) {
       this.flushQueue();
     }
@@ -2428,18 +2999,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");
-      this.awarenessManager.startCleanupTimer();
-      const localState = this.awarenessManager.getLocalState();
-      if (localState) {
-        this.awarenessManager.setLocalState(localState);
+  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();
+    }
+    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() {
@@ -2505,6 +3165,9 @@ var SyncEngine = class {
       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");
@@ -2520,7 +3183,7 @@ var SyncEngine = class {
   transitionTo(newState) {
     const validTargets = VALID_TRANSITIONS[this.state];
     if (!validTargets.includes(newState)) {
-      throw new import_core5.SyncError(`Invalid sync state transition: ${this.state} \u2192 ${newState}`, {
+      throw new import_core6.SyncError(`Invalid sync state transition: ${this.state} \u2192 ${newState}`, {
         from: this.state,
         to: newState
       });
@@ -2532,6 +3195,33 @@ 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 = {};
@@ -2705,6 +3395,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.
    */
@@ -2761,11 +3465,11 @@ var ReconnectionManager = class {
 };
 
 // src/encryption/sync-encryptor.ts
-var import_core7 = require("@korajs/core");
+var import_core8 = require("@korajs/core");
 
 // src/encryption/key-derivation.ts
-var import_core6 = require("@korajs/core");
-var KeyDerivationError = class extends import_core6.SyncError {
+var import_core7 = require("@korajs/core");
+var KeyDerivationError = class extends import_core7.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "KEY_DERIVATION_ERROR" });
     this.name = "KeyDerivationError";
@@ -2841,13 +3545,13 @@ async function deriveVersionedKey(passphrase, version, salt) {
 }
 
 // src/encryption/sync-encryptor.ts
-var EncryptionError = class extends import_core7.SyncError {
+var EncryptionError = class extends import_core8.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "ENCRYPTION_ERROR" });
     this.name = "EncryptionError";
   }
 };
-var DecryptionError = class extends import_core7.SyncError {
+var DecryptionError = class extends import_core8.SyncError {
   constructor(message, context) {
     super(message, { ...context, errorType: "DECRYPTION_ERROR" });
     this.name = "DecryptionError";
@@ -3087,8 +3791,8 @@ var SyncEncryptor = class _SyncEncryptor {
       );
       const payload = {
         v: this.currentVersion,
-        iv: toBase64(iv),
-        ct: toBase64(new Uint8Array(ciphertextBuffer)),
+        iv: toBase642(iv),
+        ct: toBase642(new Uint8Array(ciphertextBuffer)),
         alg: "aes-256-gcm"
       };
       return {
@@ -3132,8 +3836,8 @@ var SyncEncryptor = class _SyncEncryptor {
       );
     }
     try {
-      const iv = fromBase64(payload.iv);
-      const ciphertext = fromBase64(payload.ct);
+      const iv = fromBase642(payload.iv);
+      const ciphertext = fromBase642(payload.ct);
       const plaintextBuffer = await globalThis.crypto.subtle.decrypt(
         { name: "AES-GCM", iv },
         key.key,
@@ -3170,14 +3874,14 @@ function isEncryptedPayload(field) {
   }
   return field[ENCRYPTED_MARKER] === true && typeof field.v === "number" && typeof field.iv === "string" && typeof field.ct === "string" && typeof field.alg === "string";
 }
-function toBase64(bytes) {
+function toBase642(bytes) {
   let binary = "";
   for (let i = 0; i < bytes.length; i++) {
     binary += String.fromCharCode(bytes[i]);
   }
   return btoa(binary);
 }
-function fromBase64(str) {
+function fromBase642(str) {
   const binary = atob(str);
   const bytes = new Uint8Array(binary.length);
   for (let i = 0; i < binary.length; i++) {
@@ -3185,11 +3889,164 @@ function fromBase64(str) {
   }
   return bytes;
 }
+
+// src/reactivity/sync-status-controller.ts
+var OFFLINE_SYNC_STATUS = Object.freeze({
+  status: "offline",
+  pendingOperations: 0,
+  lastSyncedAt: null,
+  lastSuccessfulPush: null,
+  lastSuccessfulPull: null,
+  conflicts: 0
+});
+var SYNC_STATUS_EVENT_TYPES = [
+  "sync:connected",
+  "sync:disconnected",
+  "sync:schema-mismatch",
+  "sync:auth-failed",
+  "sync:sent",
+  "sync:received",
+  "sync:acknowledged",
+  "sync:apply-failed",
+  "sync:diagnostics",
+  "sync:initial-sync-progress"
+];
+function createSyncStatusController(options) {
+  const useLiveSnapshot = options.subscribeSyncStatus === null && options.events === null;
+  let snapshot = OFFLINE_SYNC_STATUS;
+  let serialized = JSON.stringify(OFFLINE_SYNC_STATUS);
+  const listeners = /* @__PURE__ */ new Set();
+  let cleanup = null;
+  const resolveEngine = () => {
+    return options.getSyncEngine?.() ?? options.syncEngine ?? null;
+  };
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  const setSnapshot = (next) => {
+    const nextSerialized = JSON.stringify(next);
+    if (nextSerialized === serialized) {
+      return;
+    }
+    serialized = nextSerialized;
+    snapshot = next;
+    notify();
+  };
+  const refresh = () => {
+    const engine = resolveEngine();
+    const next = engine ? engine.getStatus() : OFFLINE_SYNC_STATUS;
+    setSnapshot(next);
+  };
+  const attach = () => {
+    cleanup?.();
+    if (options.subscribeSyncStatus) {
+      cleanup = options.subscribeSyncStatus(setSnapshot);
+      return;
+    }
+    if (!resolveEngine()) {
+      setSnapshot(OFFLINE_SYNC_STATUS);
+      cleanup = () => {
+      };
+      return;
+    }
+    if (options.events) {
+      const unsubs = SYNC_STATUS_EVENT_TYPES.map((type) => options.events?.on(type, refresh));
+      refresh();
+      cleanup = () => {
+        for (const unsub of unsubs) {
+          unsub?.();
+        }
+      };
+      return;
+    }
+    refresh();
+    cleanup = () => {
+    };
+  };
+  attach();
+  return {
+    getSnapshot() {
+      if (useLiveSnapshot) {
+        const engine = resolveEngine();
+        return engine ? engine.getStatus() : OFFLINE_SYNC_STATUS;
+      }
+      return snapshot;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      listener();
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    refresh,
+    destroy() {
+      cleanup?.();
+      cleanup = null;
+      listeners.clear();
+    }
+  };
+}
+
+// src/reactivity/collaborators-snapshot.ts
+var EMPTY_COLLABORATORS = [];
+function awarenessStatesEqual(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index++) {
+    const a = left[index];
+    const b = right[index];
+    if (!a || !b) {
+      return false;
+    }
+    if (a.user.name !== b.user.name || a.user.color !== b.user.color) {
+      return false;
+    }
+    const aCursor = a.cursor;
+    const bCursor = b.cursor;
+    if (aCursor === void 0 && bCursor === void 0) {
+      continue;
+    }
+    if (!aCursor || !bCursor) {
+      return false;
+    }
+    if (aCursor.collection !== bCursor.collection || aCursor.recordId !== bCursor.recordId || aCursor.field !== bCursor.field || aCursor.anchor !== bCursor.anchor || aCursor.head !== bCursor.head) {
+      return false;
+    }
+  }
+  return true;
+}
+function getRemoteAwarenessStates(awareness) {
+  const localClientId = awareness.clientId;
+  const remoteStates = [];
+  for (const [clientId, state] of awareness.getStates()) {
+    if (clientId === localClientId) continue;
+    remoteStates.push(state);
+  }
+  return remoteStates;
+}
+function subscribeRemoteAwarenessStates(awareness, listener) {
+  let snapshot = EMPTY_COLLABORATORS;
+  const emitIfChanged = () => {
+    const next = getRemoteAwarenessStates(awareness);
+    if (awarenessStatesEqual(snapshot, next)) {
+      return;
+    }
+    snapshot = next;
+    listener(snapshot);
+  };
+  emitIfChanged();
+  return awareness.on("change", emitIfChanged);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AwarenessManager,
   ChaosTransport,
   ConnectionMonitor,
+  DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
   DecryptionError,
   EncryptionError,
   HttpLongPollingTransport,
@@ -3197,28 +4054,46 @@ function fromBase64(str) {
   JsonMessageSerializer,
   KeyDerivationError,
   NegotiatedMessageSerializer,
+  OFFLINE_SYNC_STATUS,
   OutboundQueue,
   ProtobufMessageSerializer,
   ReconnectionManager,
+  RichtextDocChannel,
+  SCHEMA_MISMATCH_PREFIX,
   SYNC_STATES,
   SYNC_STATUSES,
   ScopeViolationError,
   SyncEncryptor,
   SyncEngine,
   WebSocketTransport,
+  createDeltaCursorFromBatch,
+  createSyncStatusController,
+  decodeDeltaCursor,
+  decodeYjsUpdate,
+  dedupeQuerySubsets,
   deriveKey,
   deriveVersionedKey,
+  encodeDeltaCursor,
+  encodeYjsUpdate,
   filterOperationsByScope,
   generateSalt,
+  getRemoteAwarenessStates,
   isAcknowledgmentMessage,
   isAwarenessUpdateMessage,
+  isClientSchemaVersionSupported,
   isEncryptedPayload,
   isErrorMessage,
   isHandshakeMessage,
   isHandshakeResponseMessage,
   isOperationBatchMessage,
+  isSchemaMismatchReject,
   isSyncMessage,
+  isYjsDocUpdateMessage,
+  operationMatchesQuerySubsets,
   operationMatchesScope,
+  richtextDocKey,
+  sliceOperationsAfterCursor,
+  subscribeRemoteAwarenessStates,
   versionVectorToWire,
   wireToVersionVector
 });