@korajs/sync 1.0.0-beta.0 → 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-BMesMB6s.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-BMesMB6s.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';
@@ -470,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.
  */
@@ -850,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;
@@ -864,6 +930,7 @@ declare class SyncEngine {
     private schemaBlocked;
     private clockBlocked;
     private clockSkewMs;
+    private blobStorageEnabled;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -998,6 +1065,22 @@ 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;
@@ -1292,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-BMesMB6s.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-BMesMB6s.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';
@@ -470,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.
  */
@@ -850,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;
@@ -864,6 +930,7 @@ declare class SyncEngine {
     private schemaBlocked;
     private clockBlocked;
     private clockSkewMs;
+    private blobStorageEnabled;
     private deltaBatchesReceived;
     private deltaReceiveComplete;
     private deltaSendComplete;
@@ -998,6 +1065,22 @@ 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;
@@ -1292,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.js

@@ -222,6 +222,12 @@ function isSyncMessage(value) {
       return isAwarenessUpdateMessage(value);
     case "yjs-doc-update":
       return isYjsDocUpdateMessage(value);
+    case "blob-chunk-request":
+      return isBlobChunkRequestMessage(value);
+    case "blob-chunk-response":
+      return isBlobChunkResponseMessage(value);
+    case "blob-chunk-push":
+      return isBlobChunkPushMessage(value);
     default:
       return false;
   }
@@ -261,6 +267,21 @@ function isYjsDocUpdateMessage(value) {
   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";
 }
+function isBlobChunkRequestMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-request" && typeof msg.messageId === "string" && typeof msg.requestId === "string" && typeof msg.hash === "string";
+}
+function isBlobChunkResponseMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-response" && typeof msg.messageId === "string" && typeof msg.requestId === "string" && (typeof msg.bytes === "string" || msg.bytes === null);
+}
+function isBlobChunkPushMessage(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const msg = value;
+  return msg.type === "blob-chunk-push" && typeof msg.messageId === "string" && typeof msg.hash === "string" && typeof msg.bytes === "string";
+}
 
 // src/protocol/serializer.ts
 import { SyncError } from "@korajs/core";
@@ -501,7 +522,8 @@ function toProtoEnvelope(message) {
         accepted: message.accepted,
         rejectReason: message.rejectReason,
         selectedWireFormat: message.selectedWireFormat,
-        serverTime: message.serverTime
+        serverTime: message.serverTime,
+        blobStorageEnabled: message.blobStorageEnabled
       };
     case "operation-batch":
       return {
@@ -532,6 +554,28 @@ function toProtoEnvelope(message) {
         type: message.type,
         messageId: message.messageId
       };
+    case "blob-chunk-request":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        requestId: message.requestId,
+        hash: message.hash
+      };
+    case "blob-chunk-response":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        requestId: message.requestId,
+        hasBytes: message.bytes !== null,
+        ...message.bytes !== null ? { chunkBytes: message.bytes } : {}
+      };
+    case "blob-chunk-push":
+      return {
+        type: message.type,
+        messageId: message.messageId,
+        hash: message.hash,
+        chunkBytes: message.bytes
+      };
   }
 }
 function fromProtoEnvelope(envelope) {
@@ -564,7 +608,8 @@ function fromProtoEnvelope(envelope) {
         selectedWireFormat: envelope.selectedWireFormat === "json" || envelope.selectedWireFormat === "protobuf" ? envelope.selectedWireFormat : void 0,
         // Preserve the server's wall-clock time so clock-skew detection and
         // automatic timestamp rebase work over the protobuf wire, not just JSON.
-        ...envelope.serverTime !== void 0 ? { serverTime: envelope.serverTime } : {}
+        ...envelope.serverTime !== void 0 ? { serverTime: envelope.serverTime } : {},
+        ...envelope.blobStorageEnabled !== void 0 ? { blobStorageEnabled: envelope.blobStorageEnabled } : {}
       };
     case "operation-batch":
       return {
@@ -589,6 +634,27 @@ function fromProtoEnvelope(envelope) {
         message: envelope.errorMessage ?? "Unknown error",
         retriable: envelope.retriable ?? false
       };
+    case "blob-chunk-request":
+      return {
+        type: "blob-chunk-request",
+        messageId: envelope.messageId,
+        requestId: envelope.requestId ?? "",
+        hash: envelope.hash ?? ""
+      };
+    case "blob-chunk-response":
+      return {
+        type: "blob-chunk-response",
+        messageId: envelope.messageId,
+        requestId: envelope.requestId ?? "",
+        bytes: envelope.hasBytes ? envelope.chunkBytes ?? "" : null
+      };
+    case "blob-chunk-push":
+      return {
+        type: "blob-chunk-push",
+        messageId: envelope.messageId,
+        hash: envelope.hash ?? "",
+        bytes: envelope.chunkBytes ?? ""
+      };
     default:
       throw new SyncError("Failed to decode sync message: unknown protobuf type", {
         type: envelope.type
@@ -734,6 +800,14 @@ function encodeEnvelope(envelope) {
   }
   if (envelope.retriable !== void 0) writer.uint32(144).bool(envelope.retriable);
   if (envelope.serverTime !== void 0) writer.uint32(152).int64(envelope.serverTime);
+  if (envelope.requestId && envelope.requestId.length > 0)
+    writer.uint32(162).string(envelope.requestId);
+  if (envelope.hash && envelope.hash.length > 0) writer.uint32(170).string(envelope.hash);
+  if (envelope.chunkBytes && envelope.chunkBytes.length > 0)
+    writer.uint32(178).string(envelope.chunkBytes);
+  if (envelope.hasBytes !== void 0) writer.uint32(184).bool(envelope.hasBytes);
+  if (envelope.blobStorageEnabled !== void 0)
+    writer.uint32(200).bool(envelope.blobStorageEnabled);
   return writer.finish();
 }
 function decodeEnvelope(bytes) {
@@ -805,6 +879,21 @@ function decodeEnvelope(bytes) {
       case 19:
         envelope.serverTime = longToNumber(reader.int64());
         break;
+      case 20:
+        envelope.requestId = reader.string();
+        break;
+      case 21:
+        envelope.hash = reader.string();
+        break;
+      case 22:
+        envelope.chunkBytes = reader.string();
+        break;
+      case 23:
+        envelope.hasBytes = reader.bool();
+        break;
+      case 25:
+        envelope.blobStorageEnabled = reader.bool();
+        break;
       default:
         reader.skipType(tag & 7);
     }
@@ -1612,6 +1701,95 @@ var AwarenessManager = class {
   }
 };
 
+// src/blob/blob-chunk-channel.ts
+import { generateUUIDv7 } from "@korajs/core";
+function encodeBlobChunkBytes(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function decodeBlobChunkBytes(encoded) {
+  const binary = atob(encoded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    out[i] = binary.charCodeAt(i);
+  }
+  return out;
+}
+var BlobChunkChannel = class {
+  onSend;
+  handlers = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.onSend = options?.onSend ?? null;
+  }
+  /**
+   * Send a blob-chunk message to the peer. Response bytes are base64-encoded
+   * onto the wire here; callers pass a `Uint8Array`.
+   */
+  send(message) {
+    if (!this.onSend) {
+      return;
+    }
+    if (message.type === "blob-chunk-request") {
+      this.onSend({
+        type: "blob-chunk-request",
+        messageId: generateUUIDv7(),
+        requestId: message.requestId,
+        hash: message.hash
+      });
+      return;
+    }
+    if (message.type === "blob-chunk-push") {
+      this.onSend({
+        type: "blob-chunk-push",
+        messageId: generateUUIDv7(),
+        hash: message.hash,
+        bytes: encodeBlobChunkBytes(message.bytes)
+      });
+      return;
+    }
+    this.onSend({
+      type: "blob-chunk-response",
+      messageId: generateUUIDv7(),
+      requestId: message.requestId,
+      bytes: message.bytes === null ? null : encodeBlobChunkBytes(message.bytes)
+    });
+  }
+  /**
+   * Register a handler for inbound blob-chunk messages. Multiple handlers are
+   * allowed; each receives every delivered message.
+   */
+  onMessage(handler) {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+  /**
+   * Deliver an inbound wire message to registered handlers, decoding response
+   * bytes from base64 back to a `Uint8Array` first.
+   */
+  deliver(message) {
+    if (this.handlers.size === 0) {
+      return;
+    }
+    const decoded = message.type === "blob-chunk-request" ? { type: "blob-chunk-request", requestId: message.requestId, hash: message.hash } : message.type === "blob-chunk-push" ? {
+      type: "blob-chunk-push",
+      hash: message.hash,
+      bytes: decodeBlobChunkBytes(message.bytes)
+    } : {
+      type: "blob-chunk-response",
+      requestId: message.requestId,
+      bytes: message.bytes === null ? null : decodeBlobChunkBytes(message.bytes)
+    };
+    for (const handler of this.handlers) {
+      handler(decoded);
+    }
+  }
+};
+
 // src/diagnostics/bandwidth-estimator.ts
 var BandwidthEstimator = class {
   maxSamples;
@@ -2055,7 +2233,7 @@ var SyncMetricsCollector = class {
 };
 
 // src/richtext/richtext-doc-channel.ts
-import { generateUUIDv7 } from "@korajs/core";
+import { generateUUIDv7 as generateUUIDv72 } from "@korajs/core";
 
 // src/richtext/doc-channel-wire.ts
 function encodeYjsUpdate(update) {
@@ -2134,7 +2312,7 @@ var RichtextDocChannel = class {
     }
     this.onSend({
       type: "yjs-doc-update",
-      messageId: generateUUIDv7(),
+      messageId: generateUUIDv72(),
       collection,
       recordId,
       field,
@@ -2347,6 +2525,7 @@ var SyncEngine = class {
   encryptor;
   awarenessManager;
   richtextDocChannel;
+  blobChunkChannel;
   metricsCollector;
   syncState;
   remoteVector = /* @__PURE__ */ new Map();
@@ -2361,6 +2540,7 @@ var SyncEngine = class {
   schemaBlocked = false;
   clockBlocked = false;
   clockSkewMs = null;
+  blobStorageEnabled = false;
   // Track delta exchange state
   deltaBatchesReceived = 0;
   deltaReceiveComplete = false;
@@ -2409,6 +2589,14 @@ var SyncEngine = class {
         this.transport.send(message);
       }
     });
+    this.blobChunkChannel = new BlobChunkChannel({
+      onSend: (message) => {
+        if (this.state !== "streaming") {
+          return;
+        }
+        this.transport.send(message);
+      }
+    });
     this.awarenessManager.onSend((message) => {
       if (this.state !== "streaming") return;
       const wireMessage = {
@@ -2722,6 +2910,31 @@ var SyncEngine = class {
   getRichtextDocChannel() {
     return this.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() {
+    return this.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() {
+    return this.blobStorageEnabled;
+  }
+  /**
+   * 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, bytes) {
+    if (this.state !== "streaming" || !this.blobStorageEnabled) {
+      return;
+    }
+    this.blobChunkChannel.send({ type: "blob-chunk-push", hash, bytes });
+  }
   // --- Private methods ---
   messageChain = Promise.resolve();
   enqueueMessage(message) {
@@ -2747,6 +2960,11 @@ var SyncEngine = class {
       case "yjs-doc-update":
         this.richtextDocChannel.deliver(message);
         break;
+      case "blob-chunk-request":
+      case "blob-chunk-response":
+      case "blob-chunk-push":
+        this.blobChunkChannel.deliver(message);
+        break;
     }
   }
   handleMessageFailure(error) {
@@ -2779,6 +2997,7 @@ var SyncEngine = class {
   }
   async handleHandshakeResponse(msg) {
     if (this.state !== "handshaking") return;
+    this.blobStorageEnabled = msg.blobStorageEnabled === true;
     if (typeof msg.serverTime === "number") {
       this.evaluateClockSkew(msg.serverTime);
       if (this.clockBlocked) {
@@ -4126,6 +4345,7 @@ function subscribeRemoteAwarenessStates(awareness, listener) {
 }
 export {
   AwarenessManager,
+  BlobChunkChannel,
   ChaosTransport,
   ConnectionMonitor,
   DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD,
@@ -4150,11 +4370,13 @@ export {
   WebSocketTransport,
   createDeltaCursorFromBatch,
   createSyncStatusController,
+  decodeBlobChunkBytes,
   decodeDeltaCursor,
   decodeYjsUpdate,
   dedupeQuerySubsets,
   deriveKey,
   deriveVersionedKey,
+  encodeBlobChunkBytes,
   encodeDeltaCursor,
   encodeYjsUpdate,
   filterOperationsByScope,
@@ -4162,6 +4384,9 @@ export {
   getRemoteAwarenessStates,
   isAcknowledgmentMessage,
   isAwarenessUpdateMessage,
+  isBlobChunkPushMessage,
+  isBlobChunkRequestMessage,
+  isBlobChunkResponseMessage,
   isClientSchemaVersionSupported,
   isEncryptedPayload,
   isErrorMessage,