@korajs/sync 0.6.1 → 1.0.0-beta.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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.cjs';
-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.cjs';
+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, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, m as SyncStatePersistence, n as SyncQuerySubset } from './transport-CZLMdZ0k.cjs';
+export { A as AcknowledgmentMessage, o as AwarenessStateWire, p as AwarenessUpdateMessage, E as EncryptedPayload, q as ErrorMessage, H as HandshakeMessage, r as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, s as SYNC_STATES, t as SYNC_STATUSES, u as ScopeViolationError, v as SyncEncryptionAlgorithm, w as SyncScopeContext, x as SyncStatus, y as dedupeQuerySubsets, z as isAcknowledgmentMessage, C as isAwarenessUpdateMessage, F as isBlobChunkPushMessage, G as isBlobChunkRequestMessage, J as isBlobChunkResponseMessage, K as isErrorMessage, L as isHandshakeMessage, M as isHandshakeResponseMessage, N as isOperationBatchMessage, P as isSyncMessage, R as isYjsDocUpdateMessage, U as operationMatchesQuerySubsets } from './transport-CZLMdZ0k.cjs';
 import * as _korajs_core from '@korajs/core';
 import { Operation, VersionVector, ApplyResult, KoraEventEmitter, TimeSource, SyncError, ConnectionQuality } from '@korajs/core';
 export { ApplyFailureReason, ApplyResult } from '@korajs/core';
@@ -81,6 +81,20 @@ interface SyncStore {
      * @param toSeq - End sequence number (inclusive)
      */
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    /**
+     * Optional: re-stamp never-acknowledged local operations after a fast device
+     * clock was corrected (timestamp rebase). Optional so hand-rolled SyncStore
+     * implementations keep working; when absent the engine simply skips the
+     * rebase and falls back to the clock-block behavior.
+     *
+     * @param ids - Operation ids that are candidates for re-stamping
+     * @param correctedNowMs - Trusted "now" (server time at handshake) in ms
+     */
+    rebaseUnsyncedOperations?(ids: string[], correctedNowMs: number): Promise<{
+        operations: Operation[];
+        idMapping: Record<string, string>;
+        rebasedCount: number;
+    }>;
 }
 
 /** Prefix for handshake rejection when client schema version is unsupported. */
@@ -275,7 +289,7 @@ declare class ChaosTransport implements SyncTransport {
     private readonly random;
     private messageHandler;
     private reorderBuffer;
-    private timers;
+    private pending;
     constructor(inner: SyncTransport, config?: ChaosConfig);
     connect(url: string, options?: TransportOptions): Promise<void>;
     disconnect(): Promise<void>;
@@ -456,6 +470,71 @@ declare class AwarenessManager {
     private emitAwarenessEvent;
 }
 
+/**
+ * A blob-chunk message in decoded form (chunk bytes as a `Uint8Array` rather
+ * than the base64 wire string). This is the shape callers of the channel work
+ * with; the channel handles base64 encode/decode at the wire boundary.
+ *
+ * The shape mirrors `@korajs/store`'s `ChunkMessage` so an app-layer adapter can
+ * bridge the two with no field translation.
+ */
+type BlobChunkChannelMessage = {
+    type: 'blob-chunk-request';
+    requestId: string;
+    hash: string;
+} | {
+    type: 'blob-chunk-response';
+    requestId: string;
+    bytes: Uint8Array | null;
+} | {
+    type: 'blob-chunk-push';
+    hash: string;
+    bytes: Uint8Array;
+};
+/** Encode chunk bytes to a base64 string for the JSON wire. */
+declare function encodeBlobChunkBytes(bytes: Uint8Array): string;
+/** Decode base64 chunk bytes from the wire back to a `Uint8Array`. */
+declare function decodeBlobChunkBytes(encoded: string): Uint8Array;
+interface BlobChunkChannelOptions {
+    /**
+     * Called when a local blob-chunk message should go out on the wire. The
+     * caller (the sync engine) decides whether the connection is ready to send.
+     */
+    onSend?: (message: BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage) => void;
+}
+/**
+ * Ephemeral side channel for out-of-band blob chunk transfer over the sync
+ * connection. Symmetric: a peer can both request chunks it needs and answer
+ * requests for chunks it holds. Never persisted in the operation log — durable
+ * state is the `BlobRef` inside a record's fields; this channel only moves the
+ * referenced bytes.
+ *
+ * The channel owns the base64 wire encoding so callers work purely in
+ * `Uint8Array`, and its {@link BlobChunkChannelMessage} shape mirrors
+ * `@korajs/store`'s `ChunkMessage` so the app layer can expose it as a
+ * `ChunkMessagePort` without translating fields.
+ */
+declare class BlobChunkChannel {
+    private readonly onSend;
+    private readonly handlers;
+    constructor(options?: BlobChunkChannelOptions);
+    /**
+     * Send a blob-chunk message to the peer. Response bytes are base64-encoded
+     * onto the wire here; callers pass a `Uint8Array`.
+     */
+    send(message: BlobChunkChannelMessage): void;
+    /**
+     * Register a handler for inbound blob-chunk messages. Multiple handlers are
+     * allowed; each receives every delivered message.
+     */
+    onMessage(handler: (message: BlobChunkChannelMessage) => void): () => void;
+    /**
+     * Deliver an inbound wire message to registered handlers, decoding response
+     * bytes from base64 back to a `Uint8Array` first.
+     */
+    deliver(message: BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage): void;
+}
+
 /**
  * Configuration for the SyncMetricsCollector.
  */
@@ -529,11 +608,13 @@ declare class SyncEncryptor {
      * @param config - Encryption configuration with passphrase
      * @param salt - Optional salt for deterministic key derivation (mainly for testing).
      *              If omitted, a random salt is generated.
+     * @param iterations - Optional PBKDF2 iteration count. Defaults to the
+     *              production-strength value. Lower it only in tests.
      * @returns A configured SyncEncryptor instance
      * @throws {EncryptionError} If configuration is invalid
      * @throws {KeyDerivationError} If key derivation fails
      */
-    static create(config: SyncEncryptionConfig, salt?: Uint8Array): Promise<SyncEncryptor>;
+    static create(config: SyncEncryptionConfig, salt?: Uint8Array, iterations?: number): Promise<SyncEncryptor>;
     /**
      * Creates a SyncEncryptor from pre-derived versioned keys.
      *
@@ -745,6 +826,20 @@ declare class OutboundQueue {
      * Peek at the first `count` operations without removing them.
      */
     peek(count: number): Operation[];
+    /**
+     * All queued operations (not counting in-flight), in causal order.
+     */
+    getAll(): Operation[];
+    /**
+     * Atomically replace the entire queue with a new set of operations.
+     *
+     * Used after a timestamp rebase rewrote the queued operations under new
+     * content-addressed ids: the old entries must vanish from memory AND from
+     * persistent storage in one step, or a page refresh could resurrect
+     * stale-stamped ops the server would reject. Resets the seen set to exactly
+     * the new ids so the rewritten ops are not treated as duplicates.
+     */
+    replaceAll(ops: Operation[]): Promise<void>;
     /**
      * Whether initialize() has been called.
      */
@@ -820,6 +915,7 @@ declare class SyncEngine {
     private readonly encryptor;
     private readonly awarenessManager;
     private readonly richtextDocChannel;
+    private readonly blobChunkChannel;
     private readonly metricsCollector;
     private readonly syncState;
     private remoteVector;
@@ -832,6 +928,9 @@ declare class SyncEngine {
     private currentBatch;
     private reconnecting;
     private schemaBlocked;
+    private clockBlocked;
+    private clockSkewMs;
+    private blobStorageEnabled;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -885,6 +984,18 @@ declare class SyncEngine {
      * Sync stays blocked until the app schema is upgraded or sync config changes.
      */
     isSchemaBlocked(): boolean;
+    /**
+     * True when sync is blocked because this device's clock is too far ahead.
+     * Local writes continue to work and queue; only sync is paused.
+     */
+    isClockBlocked(): boolean;
+    /** serverTime - localTime measured at the last handshake, or null before first connect. */
+    getClockSkewMs(): number | null;
+    /**
+     * Clears the clock block after the user corrects the device clock.
+     * Moves the engine back to `disconnected` so `start()` can run again.
+     */
+    clearClockBlock(): void;
     /**
      * Clears schema-mismatch block after upgrading the local schema / sync config.
      * Moves the engine back to `disconnected` so `start()` can run again.
@@ -954,11 +1065,42 @@ declare class SyncEngine {
      * Optional side channel for incremental Yjs updates on large richtext fields.
      */
     getRichtextDocChannel(): RichtextDocChannel;
+    /**
+     * Side channel for out-of-band blob chunk transfer over the sync connection.
+     * The app layer bridges this to a `ChunkMessagePort` to pull/serve blob bytes.
+     */
+    getBlobChunkChannel(): BlobChunkChannel;
+    /**
+     * Whether the connected server persists blob bytes centrally (learned from the
+     * handshake response). When true, the app uploads the bytes behind `blob`
+     * fields so they stay available after the authoring device goes offline.
+     */
+    isBlobStorageEnabled(): boolean;
+    /**
+     * Upload a blob chunk (or manifest) to the server for central persistence.
+     * A no-op unless connected and the server advertised blob storage.
+     */
+    uploadBlobChunk(hash: string, bytes: Uint8Array): void;
     private messageChain;
     private enqueueMessage;
     private handleMessageAsync;
     private handleMessageFailure;
+    /**
+     * Compares server wall-clock time from the handshake with local time.
+     * Negative skew = this device's clock is fast (dangerous for LWW and rejected
+     * by server ingest beyond 60s). Positive skew = slow (accepted but surfaced).
+     * Zero developer work required: the result flows into sync status and events.
+     */
+    private evaluateClockSkew;
     private handleHandshakeResponse;
+    /**
+     * Re-stamps queued (never-acknowledged) operations whose timestamps are far
+     * enough in the future that the server would reject them, using the server's
+     * own handshake time as the trusted "now". This is the automatic recovery
+     * path after a user corrects a fast device clock: the queue drains
+     * immediately instead of waiting for real time to catch up.
+     */
+    private maybeRebaseQueuedOperations;
     private sendDelta;
     private markDeltaSendCompleteIfReady;
     private collectDelta;
@@ -1164,6 +1306,9 @@ declare function generateSalt(): Uint8Array;
  *
  * @param passphrase - The user's passphrase (must be non-empty)
  * @param salt - Optional salt bytes. If omitted, a random 32-byte salt is generated.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests; production must
+ *   keep the default so derived keys stay brute-force resistant.
  * @returns The derived CryptoKey and the salt used
  * @throws {KeyDerivationError} If the passphrase is empty, crypto is unavailable, or derivation fails
  *
@@ -1176,7 +1321,7 @@ declare function generateSalt(): Uint8Array;
  * const { key: sameKey } = await deriveKey('my-secure-passphrase', salt)
  * ```
  */
-declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
+declare function deriveKey(passphrase: string, salt?: Uint8Array, iterations?: number): Promise<{
     key: CryptoKey;
     salt: Uint8Array;
 }>;
@@ -1190,10 +1335,12 @@ declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
  * @param passphrase - The user's passphrase
  * @param version - Key version number (must be a positive integer)
  * @param salt - Optional salt bytes. If omitted, a random salt is generated.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests.
  * @returns A {@link VersionedKey} containing the key, version, and salt
  * @throws {KeyDerivationError} If parameters are invalid or derivation fails
  */
-declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
+declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array, iterations?: number): Promise<VersionedKey>;
 
 /** Default status when sync is not configured or the engine is unavailable. */
 declare const OFFLINE_SYNC_STATUS: SyncStatusInfo;
@@ -1228,4 +1375,4 @@ declare function getRemoteAwarenessStates(awareness: AwarenessManager): Awarenes
  */
 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 };
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, BlobChunkChannel, type BlobChunkChannelMessage, type BlobChunkChannelOptions, BlobChunkPushMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, 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, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { 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, B as BlobChunkRequestMessage, g as BlobChunkResponseMessage, h as BlobChunkPushMessage, i as SyncEncryptionConfig, V as VersionedKey, Y as YjsDocUpdateMessage, Q as QueueStorage, j as SyncState, k as SyncStatusInfo, l as SyncConfig, m as SyncStatePersistence, n as SyncQuerySubset } from './transport-CZLMdZ0k.js';
+export { A as AcknowledgmentMessage, o as AwarenessStateWire, p as AwarenessUpdateMessage, E as EncryptedPayload, q as ErrorMessage, H as HandshakeMessage, r as HandshakeResponseMessage, I as InvalidScopeError, O as OperationBatchMessage, s as SYNC_STATES, t as SYNC_STATUSES, u as ScopeViolationError, v as SyncEncryptionAlgorithm, w as SyncScopeContext, x as SyncStatus, y as dedupeQuerySubsets, z as isAcknowledgmentMessage, C as isAwarenessUpdateMessage, F as isBlobChunkPushMessage, G as isBlobChunkRequestMessage, J as isBlobChunkResponseMessage, K as isErrorMessage, L as isHandshakeMessage, M as isHandshakeResponseMessage, N as isOperationBatchMessage, P as isSyncMessage, R as isYjsDocUpdateMessage, U as operationMatchesQuerySubsets } from './transport-CZLMdZ0k.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';
@@ -81,6 +81,20 @@ interface SyncStore {
      * @param toSeq - End sequence number (inclusive)
      */
     getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    /**
+     * Optional: re-stamp never-acknowledged local operations after a fast device
+     * clock was corrected (timestamp rebase). Optional so hand-rolled SyncStore
+     * implementations keep working; when absent the engine simply skips the
+     * rebase and falls back to the clock-block behavior.
+     *
+     * @param ids - Operation ids that are candidates for re-stamping
+     * @param correctedNowMs - Trusted "now" (server time at handshake) in ms
+     */
+    rebaseUnsyncedOperations?(ids: string[], correctedNowMs: number): Promise<{
+        operations: Operation[];
+        idMapping: Record<string, string>;
+        rebasedCount: number;
+    }>;
 }
 
 /** Prefix for handshake rejection when client schema version is unsupported. */
@@ -275,7 +289,7 @@ declare class ChaosTransport implements SyncTransport {
     private readonly random;
     private messageHandler;
     private reorderBuffer;
-    private timers;
+    private pending;
     constructor(inner: SyncTransport, config?: ChaosConfig);
     connect(url: string, options?: TransportOptions): Promise<void>;
     disconnect(): Promise<void>;
@@ -456,6 +470,71 @@ declare class AwarenessManager {
     private emitAwarenessEvent;
 }
 
+/**
+ * A blob-chunk message in decoded form (chunk bytes as a `Uint8Array` rather
+ * than the base64 wire string). This is the shape callers of the channel work
+ * with; the channel handles base64 encode/decode at the wire boundary.
+ *
+ * The shape mirrors `@korajs/store`'s `ChunkMessage` so an app-layer adapter can
+ * bridge the two with no field translation.
+ */
+type BlobChunkChannelMessage = {
+    type: 'blob-chunk-request';
+    requestId: string;
+    hash: string;
+} | {
+    type: 'blob-chunk-response';
+    requestId: string;
+    bytes: Uint8Array | null;
+} | {
+    type: 'blob-chunk-push';
+    hash: string;
+    bytes: Uint8Array;
+};
+/** Encode chunk bytes to a base64 string for the JSON wire. */
+declare function encodeBlobChunkBytes(bytes: Uint8Array): string;
+/** Decode base64 chunk bytes from the wire back to a `Uint8Array`. */
+declare function decodeBlobChunkBytes(encoded: string): Uint8Array;
+interface BlobChunkChannelOptions {
+    /**
+     * Called when a local blob-chunk message should go out on the wire. The
+     * caller (the sync engine) decides whether the connection is ready to send.
+     */
+    onSend?: (message: BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage) => void;
+}
+/**
+ * Ephemeral side channel for out-of-band blob chunk transfer over the sync
+ * connection. Symmetric: a peer can both request chunks it needs and answer
+ * requests for chunks it holds. Never persisted in the operation log — durable
+ * state is the `BlobRef` inside a record's fields; this channel only moves the
+ * referenced bytes.
+ *
+ * The channel owns the base64 wire encoding so callers work purely in
+ * `Uint8Array`, and its {@link BlobChunkChannelMessage} shape mirrors
+ * `@korajs/store`'s `ChunkMessage` so the app layer can expose it as a
+ * `ChunkMessagePort` without translating fields.
+ */
+declare class BlobChunkChannel {
+    private readonly onSend;
+    private readonly handlers;
+    constructor(options?: BlobChunkChannelOptions);
+    /**
+     * Send a blob-chunk message to the peer. Response bytes are base64-encoded
+     * onto the wire here; callers pass a `Uint8Array`.
+     */
+    send(message: BlobChunkChannelMessage): void;
+    /**
+     * Register a handler for inbound blob-chunk messages. Multiple handlers are
+     * allowed; each receives every delivered message.
+     */
+    onMessage(handler: (message: BlobChunkChannelMessage) => void): () => void;
+    /**
+     * Deliver an inbound wire message to registered handlers, decoding response
+     * bytes from base64 back to a `Uint8Array` first.
+     */
+    deliver(message: BlobChunkRequestMessage | BlobChunkResponseMessage | BlobChunkPushMessage): void;
+}
+
 /**
  * Configuration for the SyncMetricsCollector.
  */
@@ -529,11 +608,13 @@ declare class SyncEncryptor {
      * @param config - Encryption configuration with passphrase
      * @param salt - Optional salt for deterministic key derivation (mainly for testing).
      *              If omitted, a random salt is generated.
+     * @param iterations - Optional PBKDF2 iteration count. Defaults to the
+     *              production-strength value. Lower it only in tests.
      * @returns A configured SyncEncryptor instance
      * @throws {EncryptionError} If configuration is invalid
      * @throws {KeyDerivationError} If key derivation fails
      */
-    static create(config: SyncEncryptionConfig, salt?: Uint8Array): Promise<SyncEncryptor>;
+    static create(config: SyncEncryptionConfig, salt?: Uint8Array, iterations?: number): Promise<SyncEncryptor>;
     /**
      * Creates a SyncEncryptor from pre-derived versioned keys.
      *
@@ -745,6 +826,20 @@ declare class OutboundQueue {
      * Peek at the first `count` operations without removing them.
      */
     peek(count: number): Operation[];
+    /**
+     * All queued operations (not counting in-flight), in causal order.
+     */
+    getAll(): Operation[];
+    /**
+     * Atomically replace the entire queue with a new set of operations.
+     *
+     * Used after a timestamp rebase rewrote the queued operations under new
+     * content-addressed ids: the old entries must vanish from memory AND from
+     * persistent storage in one step, or a page refresh could resurrect
+     * stale-stamped ops the server would reject. Resets the seen set to exactly
+     * the new ids so the rewritten ops are not treated as duplicates.
+     */
+    replaceAll(ops: Operation[]): Promise<void>;
     /**
      * Whether initialize() has been called.
      */
@@ -820,6 +915,7 @@ declare class SyncEngine {
     private readonly encryptor;
     private readonly awarenessManager;
     private readonly richtextDocChannel;
+    private readonly blobChunkChannel;
     private readonly metricsCollector;
     private readonly syncState;
     private remoteVector;
@@ -832,6 +928,9 @@ declare class SyncEngine {
     private currentBatch;
     private reconnecting;
     private schemaBlocked;
+    private clockBlocked;
+    private clockSkewMs;
+    private blobStorageEnabled;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -885,6 +984,18 @@ declare class SyncEngine {
      * Sync stays blocked until the app schema is upgraded or sync config changes.
      */
     isSchemaBlocked(): boolean;
+    /**
+     * True when sync is blocked because this device's clock is too far ahead.
+     * Local writes continue to work and queue; only sync is paused.
+     */
+    isClockBlocked(): boolean;
+    /** serverTime - localTime measured at the last handshake, or null before first connect. */
+    getClockSkewMs(): number | null;
+    /**
+     * Clears the clock block after the user corrects the device clock.
+     * Moves the engine back to `disconnected` so `start()` can run again.
+     */
+    clearClockBlock(): void;
     /**
      * Clears schema-mismatch block after upgrading the local schema / sync config.
      * Moves the engine back to `disconnected` so `start()` can run again.
@@ -954,11 +1065,42 @@ declare class SyncEngine {
      * Optional side channel for incremental Yjs updates on large richtext fields.
      */
     getRichtextDocChannel(): RichtextDocChannel;
+    /**
+     * Side channel for out-of-band blob chunk transfer over the sync connection.
+     * The app layer bridges this to a `ChunkMessagePort` to pull/serve blob bytes.
+     */
+    getBlobChunkChannel(): BlobChunkChannel;
+    /**
+     * Whether the connected server persists blob bytes centrally (learned from the
+     * handshake response). When true, the app uploads the bytes behind `blob`
+     * fields so they stay available after the authoring device goes offline.
+     */
+    isBlobStorageEnabled(): boolean;
+    /**
+     * Upload a blob chunk (or manifest) to the server for central persistence.
+     * A no-op unless connected and the server advertised blob storage.
+     */
+    uploadBlobChunk(hash: string, bytes: Uint8Array): void;
     private messageChain;
     private enqueueMessage;
     private handleMessageAsync;
     private handleMessageFailure;
+    /**
+     * Compares server wall-clock time from the handshake with local time.
+     * Negative skew = this device's clock is fast (dangerous for LWW and rejected
+     * by server ingest beyond 60s). Positive skew = slow (accepted but surfaced).
+     * Zero developer work required: the result flows into sync status and events.
+     */
+    private evaluateClockSkew;
     private handleHandshakeResponse;
+    /**
+     * Re-stamps queued (never-acknowledged) operations whose timestamps are far
+     * enough in the future that the server would reject them, using the server's
+     * own handshake time as the trusted "now". This is the automatic recovery
+     * path after a user corrects a fast device clock: the queue drains
+     * immediately instead of waiting for real time to catch up.
+     */
+    private maybeRebaseQueuedOperations;
     private sendDelta;
     private markDeltaSendCompleteIfReady;
     private collectDelta;
@@ -1164,6 +1306,9 @@ declare function generateSalt(): Uint8Array;
  *
  * @param passphrase - The user's passphrase (must be non-empty)
  * @param salt - Optional salt bytes. If omitted, a random 32-byte salt is generated.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests; production must
+ *   keep the default so derived keys stay brute-force resistant.
  * @returns The derived CryptoKey and the salt used
  * @throws {KeyDerivationError} If the passphrase is empty, crypto is unavailable, or derivation fails
  *
@@ -1176,7 +1321,7 @@ declare function generateSalt(): Uint8Array;
  * const { key: sameKey } = await deriveKey('my-secure-passphrase', salt)
  * ```
  */
-declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
+declare function deriveKey(passphrase: string, salt?: Uint8Array, iterations?: number): Promise<{
     key: CryptoKey;
     salt: Uint8Array;
 }>;
@@ -1190,10 +1335,12 @@ declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
  * @param passphrase - The user's passphrase
  * @param version - Key version number (must be a positive integer)
  * @param salt - Optional salt bytes. If omitted, a random salt is generated.
+ * @param iterations - Optional PBKDF2 iteration count. Defaults to
+ *   {@link DEFAULT_PBKDF2_ITERATIONS}. Lower it only in tests.
  * @returns A {@link VersionedKey} containing the key, version, and salt
  * @throws {KeyDerivationError} If parameters are invalid or derivation fails
  */
-declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
+declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array, iterations?: number): Promise<VersionedKey>;
 
 /** Default status when sync is not configured or the engine is unavailable. */
 declare const OFFLINE_SYNC_STATUS: SyncStatusInfo;
@@ -1228,4 +1375,4 @@ declare function getRemoteAwarenessStates(awareness: AwarenessManager): Awarenes
  */
 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 };
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, BlobChunkChannel, type BlobChunkChannelMessage, type BlobChunkChannelOptions, BlobChunkPushMessage, BlobChunkRequestMessage, BlobChunkResponseMessage, 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, decodeBlobChunkBytes, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeBlobChunkBytes, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };