@korajs/sync 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { S as SyncScopeMap, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, g as SyncEncryptionConfig, V as VersionedKey, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig } from './transport-B-BIguq9.js';
-export { A as AcknowledgmentMessage, k as AwarenessStateWire, l as AwarenessUpdateMessage, E as EncryptedPayload, m as ErrorMessage, H as HandshakeMessage, n as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, o as SYNC_STATES, p as SYNC_STATUSES, q as ScopeViolationError, r as SyncEncryptionAlgorithm, s as SyncScopeContext, t as SyncStatus, u as isAcknowledgmentMessage, v as isAwarenessUpdateMessage, w as isErrorMessage, x as isHandshakeMessage, y as isHandshakeResponseMessage, z as isOperationBatchMessage, B as isSyncMessage } from './transport-B-BIguq9.js';
-import { Operation, VersionVector, TimeSource, SyncError, KoraEventEmitter, ConnectionQuality } from '@korajs/core';
+import { S as SyncScopeMap, D as DeltaCursor, a as SyncMessage, b as SerializedOperation, W as WireFormat, c as SyncTransport, T as TransportOptions, d as TransportMessageHandler, e as TransportCloseHandler, f as TransportErrorHandler, g as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, h as SyncState, i as SyncStatusInfo, j as SyncConfig, k as SyncStatePersistence, l as SyncQuerySubset } from './transport-BrdBj7rH.js';
+export { A as AcknowledgmentMessage, m as AwarenessStateWire, n as AwarenessUpdateMessage, E as EncryptedPayload, o as ErrorMessage, H as HandshakeMessage, p as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, q as SYNC_STATES, r as SYNC_STATUSES, s as ScopeViolationError, t as SyncEncryptionAlgorithm, u as SyncScopeContext, v as SyncStatus, w as dedupeQuerySubsets, x as isAcknowledgmentMessage, y as isAwarenessUpdateMessage, z as isErrorMessage, B as isHandshakeMessage, C as isHandshakeResponseMessage, F as isOperationBatchMessage, G as isSyncMessage, J as isYjsDocUpdateMessage, K as operationMatchesQuerySubsets } from './transport-BrdBj7rH.js';
+import * as _korajs_core from '@korajs/core';
+import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
+export { ApplyFailureReason, ApplyResult } from '@korajs/core';
 
 /**
  * Check whether an operation matches the given scope map.
@@ -12,13 +14,18 @@ import { Operation, VersionVector, TimeSource, SyncError, KoraEventEmitter, Conn
  * - Scope has field/value pairs: all must match in the operation's data snapshot.
  *
  * For updates, the snapshot is built by merging `previousData` and `data` (data wins),
- * which represents the record's state after the operation is applied.
+ * which represents the record's state after the operation is applied. When an optional
+ * `fullRecord` is provided (e.g., from the local store), its values fill in scope fields
+ * that weren't included in the operation's data (critical for update operations where
+ * `data` only contains changed fields).
  *
  * @param op - The operation to check
  * @param scopeMap - Per-collection scope filters, or undefined for no filtering
+ * @param fullRecord - Optional full record state from the store, used to fill in scope
+ *   fields not present in the operation's partial data
  * @returns true if the operation is within scope
  */
-declare function operationMatchesScope(op: Operation, scopeMap: SyncScopeMap | undefined): boolean;
+declare function operationMatchesScope(op: Operation, scopeMap: SyncScopeMap | undefined, fullRecord?: Record<string, unknown> | null): boolean;
 /**
  * Filter operations to only those matching the given scope map.
  *
@@ -29,9 +36,22 @@ declare function operationMatchesScope(op: Operation, scopeMap: SyncScopeMap | u
 declare function filterOperationsByScope(operations: Operation[], scopeMap: SyncScopeMap | undefined): Operation[];
 
 /**
- * Result of applying a remote operation to the store.
+ * Encode a delta cursor for wire transfer or `_kora_meta` persistence.
  */
-type ApplyResult = 'applied' | 'duplicate' | 'skipped';
+declare function encodeDeltaCursor(cursor: DeltaCursor): string;
+/**
+ * Decode a delta cursor string. Returns null when malformed.
+ */
+declare function decodeDeltaCursor(value: string | undefined | null): DeltaCursor | null;
+/**
+ * Slice a causally sorted operation list to resume after a cursor.
+ */
+declare function sliceOperationsAfterCursor(operations: _korajs_core.Operation[], cursor: DeltaCursor | null): _korajs_core.Operation[];
+/**
+ * Build a cursor from the last operation in a delta batch.
+ */
+declare function createDeltaCursorFromBatch(operations: _korajs_core.Operation[], batchIndex: number): DeltaCursor | null;
+
 /**
  * Interface that the local store must implement for sync.
  * This decouples @korajs/sync from @korajs/store — the store satisfies this interface.
@@ -63,6 +83,20 @@ interface SyncStore {
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
 }
 
+/** Prefix for handshake rejection when client schema version is unsupported. */
+declare const SCHEMA_MISMATCH_PREFIX = "SCHEMA_MISMATCH";
+/**
+ * Returns true when a handshake `rejectReason` indicates unsupported schema version.
+ */
+declare function isSchemaMismatchReject(rejectReason: string | undefined): boolean;
+/**
+ * Returns true when the client schema version is within the inclusive supported range.
+ */
+declare function isClientSchemaVersionSupported(clientVersion: number, supported: {
+    min: number;
+    max: number;
+}): boolean;
+
 type EncodedMessage = string | Uint8Array;
 /**
  * Interface for encoding/decoding sync protocol messages.
@@ -255,6 +289,173 @@ declare class ChaosTransport implements SyncTransport {
     private flushReorderBuffer;
 }
 
+/**
+ * Cursor position within a richtext field.
+ * Uses Yjs-compatible anchor/head positions for editor interop.
+ */
+interface AwarenessCursor {
+    /** Collection containing the record being edited */
+    collection: string;
+    /** ID of the record being edited */
+    recordId: string;
+    /** Field name of the richtext field */
+    field: string;
+    /** Cursor anchor position in Y.Text (start of selection) */
+    anchor: number;
+    /** Cursor head position in Y.Text (end of selection, same as anchor if no selection) */
+    head: number;
+}
+/**
+ * User identity information for presence display.
+ */
+interface AwarenessUser {
+    /** Display name of the user */
+    name: string;
+    /** Hex color for cursor/selection rendering (e.g. '#ff0000') */
+    color: string;
+    /** Optional avatar URL */
+    avatar?: string;
+}
+/**
+ * Per-client awareness state. Ephemeral -- not persisted, only shared with connected peers.
+ * Compatible with Yjs awareness protocol format for interop with existing editors.
+ */
+interface AwarenessState {
+    /** User identity information */
+    user: AwarenessUser;
+    /** Current cursor position, if any */
+    cursor?: AwarenessCursor;
+}
+/**
+ * Internal awareness message format used between AwarenessManager and transport layer.
+ */
+interface AwarenessMessage {
+    type: 'awareness';
+    /** Client ID of the sender */
+    clientId: number;
+    /** All known awareness states. null value means removal. */
+    states: Record<number, AwarenessState | null>;
+}
+/**
+ * Describes a change in awareness states.
+ * Emitted when remote clients update or remove their presence.
+ */
+interface AwarenessChange {
+    /** Client IDs whose states were added */
+    added: number[];
+    /** Client IDs whose states were updated */
+    updated: number[];
+    /** Client IDs whose states were removed */
+    removed: number[];
+}
+/**
+ * Cursor information for rendering in editors.
+ * This is the developer-facing type -- simplified from internal awareness state.
+ * Editor-agnostic: provides data that can be rendered by TipTap, ProseMirror, Quill, etc.
+ */
+interface CursorInfo {
+    /** Unique client ID */
+    clientId: number;
+    /** User display name */
+    userName: string;
+    /** Hex color for cursor rendering */
+    color: string;
+    /** Cursor anchor position (start of selection) */
+    anchor: number;
+    /** Cursor head position (end of selection) */
+    head: number;
+}
+
+/**
+ * Callback for awareness change events.
+ */
+type AwarenessChangeListener = (change: AwarenessChange) => void;
+/**
+ * Manages collaborative awareness state (cursor positions, user presence).
+ *
+ * Awareness is ephemeral -- states are never persisted, only shared with
+ * currently connected peers via the sync transport. This implements a
+ * lightweight protocol compatible with Yjs awareness semantics.
+ *
+ * Each AwarenessManager has a unique client ID and tracks both its own
+ * local state and all remote clients' states.
+ */
+declare class AwarenessManager {
+    /** Unique client ID for this instance */
+    readonly clientId: number;
+    private localState;
+    private readonly remoteStates;
+    private readonly listeners;
+    private readonly emitter;
+    private readonly timeoutMs;
+    private readonly lastUpdated;
+    private cleanupTimer;
+    private sendHandler;
+    private destroyed;
+    constructor(options?: {
+        clientId?: number;
+        emitter?: KoraEventEmitter;
+        timeoutMs?: number;
+    });
+    /**
+     * 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: AwarenessState | null): void;
+    /**
+     * Get the local awareness state.
+     */
+    getLocalState(): AwarenessState | null;
+    /**
+     * Get all known awareness states (local + remote).
+     * Returns a new Map on each call.
+     */
+    getStates(): Map<number, AwarenessState>;
+    /**
+     * Handle an incoming awareness message from the transport.
+     * This processes remote state updates and notifies listeners.
+     */
+    handleRemoteMessage(message: AwarenessMessage): void;
+    /**
+     * Remove a specific remote client's awareness state.
+     * Called when the server notifies that a client has disconnected.
+     */
+    removeClient(clientId: number): void;
+    /**
+     * 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: (message: AwarenessMessage) => void): void;
+    /**
+     * Register a listener for awareness state changes.
+     * Returns an unsubscribe function.
+     */
+    on(_event: 'change', listener: AwarenessChangeListener): () => void;
+    /**
+     * Remove a specific change listener.
+     */
+    off(_event: 'change', listener: AwarenessChangeListener): void;
+    /**
+     * Start the cleanup timer that removes stale remote states.
+     * Called when the sync engine transitions to streaming state.
+     */
+    startCleanupTimer(): void;
+    /**
+     * Stop the cleanup timer.
+     */
+    stopCleanupTimer(): void;
+    /**
+     * 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(): void;
+    private cleanupStaleStates;
+    private notifyListeners;
+    private emitAwarenessEvent;
+}
+
 /**
  * Configuration for the SyncMetricsCollector.
  */
@@ -440,171 +641,42 @@ declare class SyncEncryptor {
  */
 declare function isEncryptedPayload(field: Record<string, unknown> | null): boolean;
 
-/**
- * Cursor position within a richtext field.
- * Uses Yjs-compatible anchor/head positions for editor interop.
- */
-interface AwarenessCursor {
-    /** Collection containing the record being edited */
-    collection: string;
-    /** ID of the record being edited */
-    recordId: string;
-    /** Field name of the richtext field */
-    field: string;
-    /** Cursor anchor position in Y.Text (start of selection) */
-    anchor: number;
-    /** Cursor head position in Y.Text (end of selection, same as anchor if no selection) */
-    head: number;
-}
-/**
- * User identity information for presence display.
- */
-interface AwarenessUser {
-    /** Display name of the user */
-    name: string;
-    /** Hex color for cursor/selection rendering (e.g. '#ff0000') */
-    color: string;
-    /** Optional avatar URL */
-    avatar?: string;
-}
-/**
- * Per-client awareness state. Ephemeral -- not persisted, only shared with connected peers.
- * Compatible with Yjs awareness protocol format for interop with existing editors.
- */
-interface AwarenessState {
-    /** User identity information */
-    user: AwarenessUser;
-    /** Current cursor position, if any */
-    cursor?: AwarenessCursor;
-}
-/**
- * Internal awareness message format used between AwarenessManager and transport layer.
- */
-interface AwarenessMessage {
-    type: 'awareness';
-    /** Client ID of the sender */
-    clientId: number;
-    /** All known awareness states. null value means removal. */
-    states: Record<number, AwarenessState | null>;
-}
-/**
- * Describes a change in awareness states.
- * Emitted when remote clients update or remove their presence.
- */
-interface AwarenessChange {
-    /** Client IDs whose states were added */
-    added: number[];
-    /** Client IDs whose states were updated */
-    updated: number[];
-    /** Client IDs whose states were removed */
-    removed: number[];
-}
-/**
- * Cursor information for rendering in editors.
- * This is the developer-facing type -- simplified from internal awareness state.
- * Editor-agnostic: provides data that can be rendered by TipTap, ProseMirror, Quill, etc.
- */
-interface CursorInfo {
-    /** Unique client ID */
-    clientId: number;
-    /** User display name */
-    userName: string;
-    /** Hex color for cursor rendering */
-    color: string;
-    /** Cursor anchor position (start of selection) */
-    anchor: number;
-    /** Cursor head position (end of selection) */
-    head: number;
+/** Default snapshot size above which the doc channel is preferred. */
+declare const DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD = 4096;
+type RichtextDocListener = (update: Uint8Array) => void;
+interface RichtextDocChannelOptions {
+    /** Snapshot byte length at which incremental channel sync is recommended. */
+    largeDocThreshold?: number;
+    /** Called when a local update should be sent on the wire. */
+    onSend?: (message: YjsDocUpdateMessage) => void;
 }
-
 /**
- * Callback for awareness change events.
+ * Side channel for incremental Yjs updates on large richtext fields.
+ * Ephemeral — not persisted in the operation log (durable state still flows via ops).
  */
-type AwarenessChangeListener = (change: AwarenessChange) => void;
-/**
- * Manages collaborative awareness state (cursor positions, user presence).
- *
- * Awareness is ephemeral -- states are never persisted, only shared with
- * currently connected peers via the sync transport. This implements a
- * lightweight protocol compatible with Yjs awareness semantics.
- *
- * Each AwarenessManager has a unique client ID and tracks both its own
- * local state and all remote clients' states.
- */
-declare class AwarenessManager {
-    /** Unique client ID for this instance */
-    readonly clientId: number;
-    private localState;
-    private readonly remoteStates;
+declare class RichtextDocChannel {
+    private readonly threshold;
+    private readonly onSend;
     private readonly listeners;
-    private readonly emitter;
-    private readonly timeoutMs;
-    private readonly lastUpdated;
-    private cleanupTimer;
-    private sendHandler;
-    private destroyed;
-    constructor(options?: {
-        clientId?: number;
-        emitter?: KoraEventEmitter;
-        timeoutMs?: number;
-    });
-    /**
-     * 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: AwarenessState | null): void;
-    /**
-     * Get the local awareness state.
-     */
-    getLocalState(): AwarenessState | null;
+    constructor(options?: RichtextDocChannelOptions);
     /**
-     * Get all known awareness states (local + remote).
-     * Returns a new Map on each call.
+     * Whether the doc channel should be used for a field.
+     * @param preference - `true` forces on, `false` forces off, `undefined` uses size threshold
      */
-    getStates(): Map<number, AwarenessState>;
+    shouldUseChannel(snapshotByteLength: number, preference?: boolean): boolean;
+    getThreshold(): number;
     /**
-     * Handle an incoming awareness message from the transport.
-     * This processes remote state updates and notifies listeners.
+     * Subscribe to incremental updates for a document key.
      */
-    handleRemoteMessage(message: AwarenessMessage): void;
+    subscribe(collection: string, recordId: string, field: string, listener: RichtextDocListener): () => void;
     /**
-     * Remove a specific remote client's awareness state.
-     * Called when the server notifies that a client has disconnected.
+     * Publish a local incremental update to peers.
      */
-    removeClient(clientId: number): void;
+    send(collection: string, recordId: string, field: string, update: Uint8Array): void;
     /**
-     * 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: (message: AwarenessMessage) => void): void;
-    /**
-     * Register a listener for awareness state changes.
-     * Returns an unsubscribe function.
-     */
-    on(_event: 'change', listener: AwarenessChangeListener): () => void;
-    /**
-     * Remove a specific change listener.
-     */
-    off(_event: 'change', listener: AwarenessChangeListener): void;
-    /**
-     * Start the cleanup timer that removes stale remote states.
-     * Called when the sync engine transitions to streaming state.
-     */
-    startCleanupTimer(): void;
-    /**
-     * Stop the cleanup timer.
-     */
-    stopCleanupTimer(): void;
-    /**
-     * 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.
+     * Deliver a remote incremental update to local subscribers.
      */
-    destroy(): void;
-    private cleanupStaleStates;
-    private notifyListeners;
-    private emitAwarenessEvent;
+    deliver(message: YjsDocUpdateMessage): void;
 }
 
 /**
@@ -677,6 +749,11 @@ declare class OutboundQueue {
      * Whether initialize() has been called.
      */
     get isInitialized(): boolean;
+    /**
+     * Remove operations by id from queue and persistent storage.
+     * Used when ops were already sent during handshake delta exchange.
+     */
+    removeByIds(ids: string[]): Promise<void>;
 }
 
 /**
@@ -703,6 +780,8 @@ interface SyncEngineOptions {
     encryptor?: SyncEncryptor;
     /** Optional configuration for the metrics collector. */
     metricsConfig?: MetricsCollectorConfig;
+    /** Op-log backed sync state (last acked server vector, unsynced counts). */
+    syncState?: SyncStatePersistence;
 }
 /**
  * Diagnostics snapshot for debugging and support.
@@ -740,23 +819,38 @@ declare class SyncEngine {
     private readonly batchSize;
     private readonly encryptor;
     private readonly awarenessManager;
+    private readonly richtextDocChannel;
     private readonly metricsCollector;
+    private readonly syncState;
     private remoteVector;
+    private lastAckedServerVector;
+    private cachedUnsyncedCount;
     private lastSyncedAt;
     private lastSuccessfulPush;
     private lastSuccessfulPull;
     private conflictCount;
     private currentBatch;
     private reconnecting;
+    private schemaBlocked;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
+    /** Op ids sent during handshake delta — removed from outbound queue to avoid duplicate send */
+    private deltaSentOpIds;
+    /** Outbound delta batch message IDs awaiting ACK when strictHandshake is enabled */
+    private pendingDeltaBatchAcks;
     /**
      * 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).
      */
     private activeScope;
+    /** Live query subsets registered from reactive subscriptions */
+    private querySubsets;
+    private querySubsetReconnectTimer;
+    /** Resume cursor for paginated initial sync (persisted across reconnects) */
+    private resumeDeltaCursor;
+    private initialSyncTotalBatches;
     constructor(options: SyncEngineOptions);
     /**
      * Start the sync engine: connect → handshake → delta exchange → streaming.
@@ -786,11 +880,26 @@ declare class SyncEngine {
      * Get the current developer-facing sync status.
      */
     getStatus(): SyncStatusInfo;
+    /**
+     * 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(): boolean;
+    /**
+     * Clears schema-mismatch block after upgrading the local schema / sync config.
+     * Moves the engine back to `disconnected` so `start()` can run again.
+     */
+    clearSchemaBlock(): void;
     /**
      * Record a merge conflict. Called by the merge-aware sync store
      * to increment the conflict counter for status reporting.
      */
     recordConflict(): void;
+    /**
+     * Count of local operations not yet covered by the last acked server vector (op-log source of truth).
+     */
+    getUnsyncedOperationCount(): Promise<number>;
+    private emitApplyFailure;
     /**
      * Force an immediate reconnection attempt. If the engine is disconnected
      * or in error state, restarts the sync. If already connected, no-op.
@@ -826,26 +935,65 @@ declare class SyncEngine {
      * Get the currently active scope map. Returns undefined if no scope is configured.
      */
     getActiveScope(): SyncScopeMap | undefined;
+    /**
+     * Register a live query subset that narrows synced data for a collection.
+     * Takes effect on the next connection; reconnects when already connected.
+     */
+    registerQuerySubset(subset: SyncQuerySubset): () => void;
+    /**
+     * Returns deduplicated active query subsets from registered subscriptions.
+     */
+    getActiveQuerySubsets(): SyncQuerySubset[];
     /**
      * Get the awareness manager for collaborative presence.
      * Use this to set local presence, observe remote collaborators,
      * and track cursor positions in richtext fields.
      */
     getAwarenessManager(): AwarenessManager;
-    private handleMessage;
+    /**
+     * Optional side channel for incremental Yjs updates on large richtext fields.
+     */
+    getRichtextDocChannel(): RichtextDocChannel;
+    private messageChain;
+    private enqueueMessage;
+    private handleMessageAsync;
+    private handleMessageFailure;
     private handleHandshakeResponse;
     private sendDelta;
+    private markDeltaSendCompleteIfReady;
     private collectDelta;
     private handleOperationBatch;
     private handleAcknowledgment;
     private handleError;
     private checkDeltaComplete;
+    /**
+     * Effective server vector: persisted last-ack merged with live handshake remote vector.
+     */
+    private getEffectiveServerVector;
+    private persistLastAckedServerVector;
+    private advanceLastAckedForLocalNode;
+    /**
+     * Refresh cached unsynced count from op log vs effective server vector.
+     */
+    refreshPendingCount(): Promise<void>;
+    /**
+     * Returns operations the server has not yet acknowledged (op-log source of truth).
+     */
+    getPendingSyncOperations(): Promise<Operation[]>;
+    /**
+     * Hydrate the outbound queue from unsynced ops in the op log (deduped by operation id).
+     */
+    private reconcileOutboundFromOpLog;
     private flushQueue;
     private handleAwarenessUpdate;
     private handleTransportClose;
     private handleTransportError;
     private transitionTo;
     private setSerializerWireFormat;
+    private operationAllowedForSync;
+    private persistDeltaCursor;
+    private scheduleQuerySubsetReconnect;
+    private reconnectForQuerySubsets;
 }
 
 /**
@@ -952,6 +1100,11 @@ declare class ReconnectionManager {
      * @returns Promise that resolves when reconnection succeeds or maxAttempts reached.
      */
     start(onReconnect: () => Promise<boolean>): Promise<boolean>;
+    /**
+     * Cancel the current backoff wait and proceed to the next reconnect attempt immediately.
+     * No-op if not waiting.
+     */
+    wake(): void;
     /**
      * Stop any pending reconnection attempt.
      */
@@ -976,6 +1129,19 @@ declare class ReconnectionManager {
     private wait;
 }
 
+/**
+ * Encode a Yjs update for the doc channel wire (base64).
+ */
+declare function encodeYjsUpdate(update: Uint8Array): string;
+/**
+ * Decode a base64 Yjs update from the doc channel wire.
+ */
+declare function decodeYjsUpdate(encoded: string): Uint8Array;
+/**
+ * Build a stable key for a richtext field document.
+ */
+declare function richtextDocKey(collection: string, recordId: string, field: string): string;
+
 /**
  * Thrown when key derivation fails.
  */
@@ -1029,4 +1195,37 @@ declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
  */
 declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
 
-export { type ApplyResult, type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DecryptionError, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncScopeMap, SyncState, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, deriveKey, deriveVersionedKey, filterOperationsByScope, generateSalt, isEncryptedPayload, operationMatchesScope, versionVectorToWire, wireToVersionVector };
+/** Default status when sync is not configured or the engine is unavailable. */
+declare const OFFLINE_SYNC_STATUS: SyncStatusInfo;
+interface SyncStatusControllerOptions {
+    syncEngine?: {
+        getStatus(): SyncStatusInfo;
+    } | null;
+    getSyncEngine?: () => {
+        getStatus(): SyncStatusInfo;
+    } | null;
+    subscribeSyncStatus: ((listener: (status: SyncStatusInfo) => void) => () => void) | null;
+    events: KoraEventEmitter | null;
+}
+interface SyncStatusController {
+    getSnapshot(): SyncStatusInfo;
+    subscribe(listener: () => void): () => void;
+    refresh(): void;
+    destroy(): void;
+}
+/**
+ * Framework-agnostic sync status subscription with live reads when no bridge exists.
+ */
+declare function createSyncStatusController(options: SyncStatusControllerOptions): SyncStatusController;
+
+/**
+ * Returns remote collaborators' awareness states (excludes the local client).
+ */
+declare function getRemoteAwarenessStates(awareness: AwarenessManager): AwarenessState[];
+/**
+ * Subscribes to awareness changes and invokes `listener` only when the remote
+ * collaborator set changes.
+ */
+declare function subscribeRemoteAwarenessStates(awareness: AwarenessManager, listener: (states: AwarenessState[]) => void): () => void;
+
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };