@loro-dev/streams-crdt 0.10.0 → 0.11.1

package/README.md

@@ -19,6 +19,7 @@ Transport layer for synchronizing CRDT state over
 | `createStream()` | Creates the stream on the server. Returns `{ created: true }` on first call, `{ created: false }` if it already exists. |
 | `deleteStream()` | Deletes the stream. Closes any active `join()` first. |
 | `sync()` | One-shot bootstrap/catch-up cycle. Syncs remote state into local CRDT and pushes any local changes to the server. Does **not** enter live mode. |
+| `catchup()` | Pull-only remote catch-up. Applies remote stream updates to the local CRDT but does not intentionally append new local updates. If live reads from `join()` are already healthy, returns immediately unless `{ force: true }` is passed. |
 | `join()` | Initial sync **plus** live subscription. Internally performs the same sync as `sync()`, then enters a persistent SSE/long-poll read loop and starts forwarding local writes. No need to call `sync()` before `join()`. |
 | `close()` | Closes any active join and releases resources. If this instance was using `appendWriteOnly()`, that write-only path is also torn down and cannot be used again on the same instance. |
 
@@ -107,7 +108,8 @@ if (err.code === "server_error") {
 
 #### Operation-level retries vs. live-mode retries
 
-- `sync()`, `createStream()`, `deleteStream()`, `appendWriteOnly()` return
+- `sync()`, `catchup()`, `createStream()`, `deleteStream()`,
+  `appendWriteOnly()` return
   after a **single** attempt. The application is responsible for retrying
   `retryable` errors.
 - After `join()` succeeds, the live read/write loops automatically reconnect
@@ -371,17 +373,47 @@ if (!joined.ok) throw joined.error;
 const sub = joined.value;
 ```
 
-## When to Use `sync()` vs `join()`
+## When to Use `catchup()`, `sync()`, and `join()`
 
-Use **`sync()`** when you need a one-shot catch-up without entering live mode:
+Use **`catchup()`** when you only want to pull remote updates into the local
+CRDT:
 
 ```ts
-// Offline-first: catch up on app start, then work offline.
+// Pull remote changes without uploading local pending changes.
+const caughtUp = await transport.catchup();
+if (!caughtUp.ok) throw caughtUp.error;
+// caughtUp.value.cursor contains the replay progress after the pull.
+```
+
+`catchup()` is safe to call while a room is live. When `join()` has a healthy
+SSE/long-poll read loop, `catchup()` returns immediately because the live loop
+is already catching up continuously. Pass `{ force: true }` to issue one
+explicit non-SSE offset read anyway, for example after app foreground or device
+wake:
+
+```ts
+await transport.catchup({ force: true });
+```
+
+If the live read side of the room is reconnecting, disconnected, or in error,
+`catchup()` skips the live backoff path and tries one immediate non-SSE
+catch-up read from the room's current cursor. A successful call updates the
+local cursor and nudges the live loops to reconnect, but it does not by itself
+guarantee that local pending writes have reached the server.
+
+Use **`sync()`** when you need a one-shot bidirectional sync without entering
+live mode:
+
+```ts
+// Offline-first: pull remote changes, upload local changes, then work offline.
 const synced = await transport.sync();
 if (!synced.ok) throw synced.error;
 // synced.value.cursor contains the replay progress after sync.
 ```
 
+Use `sync()` or `subscription.waitUntilSynced()` when the caller needs local
+pending changes uploaded to the server.
+
 Use **`join()`** for real-time collaboration. It does everything `sync()` does
 and then keeps the connection alive for continuous bidirectional sync:
 
@@ -1021,7 +1053,9 @@ const transport = new StreamsCrdt({
 - `TransportError` — discriminated error union
   `apply_incomplete` is returned when remote data was read but the CRDT adapter
   still has unresolved dependencies and the cursor cannot be saved.
-- `TransportCreateStreamSuccess`, `TransportDeleteStreamSuccess`, `TransportSyncSuccess` — result payloads
+- `TransportCatchupParams` — `catchup()` options
+- `TransportCreateStreamSuccess`, `TransportDeleteStreamSuccess`,
+  `TransportCatchupSuccess`, `TransportSyncSuccess` — result payloads
 - `TransportJoinParams` — `join()` options
 - `TransportSubscription` — active live subscription handle
 - `TransportRoomStatus` — `"joined" | "reconnecting" | "disconnected" | "error"`

package/dist/flock.d.ts

@@ -1,4 +1,4 @@
-import { $ as IndexedDbRemoteCursorStore, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportRoomStatus, H as TransportDeleteStreamSuccess, I as SnapshotUploadOptions, J as TransportSyncSuccess, K as TransportSnapshotUploadSuccess, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as InMemoryRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportError, V as TransportCreateStreamSuccess, W as TransportJoinParams, X as BeforeRemoteCursorSaveContext, Y as WriteOnlyAppendResult, Z as BeforeRemoteCursorSaveHook, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as IndexedDbRemoteCursorStoreOptions, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as createInitialRemoteCursor, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorSaveSource, o as StreamsCrdt, p as E2eeKey, q as TransportSubscription, r as isValidRillId, rt as RemoteCursorStore, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursor, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-BP6BR7jn.js";
+import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DAAMJlvT.js";
 import { ExportBundle, Flock, VersionVector, VersionVector as VersionVector$1 } from "@loro-dev/flock-wasm";
 
 //#region src/flock.d.ts
@@ -7,5 +7,5 @@ import { ExportBundle, Flock, VersionVector, VersionVector as VersionVector$1 }
  */
 declare function createFlockAdapter(flock: Flock): CrdtAdapter<VersionVector$1>;
 //#endregion
-export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, E2eeEncryptionOptions, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeKey, E2eeKeyProvider, E2eeOptions, E2eeReadPolicy, E2eeScope, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, type ExportBundle, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, PayloadProtectionEncryptionOptions, PayloadProtectionKey, PayloadProtectionKeyProvider, PayloadProtectionOptions, PayloadProtectionReadPolicy, PayloadProtectionScope, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, type VersionVector, WriteOnlyAppendResult, createFlockAdapter, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, E2eeEncryptionOptions, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeKey, E2eeKeyProvider, E2eeOptions, E2eeReadPolicy, E2eeScope, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, type ExportBundle, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, PayloadProtectionEncryptionOptions, PayloadProtectionKey, PayloadProtectionKeyProvider, PayloadProtectionOptions, PayloadProtectionReadPolicy, PayloadProtectionScope, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, type VersionVector, WriteOnlyAppendResult, createFlockAdapter, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };
 //# sourceMappingURL=flock.d.ts.map

package/dist/flock.js

@@ -1,4 +1,4 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-AfFikxB2.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-fOF9ZqCH.js";
 import { Flock } from "@loro-dev/flock-wasm";
 //#region src/flock.ts
 function isAfter(entry, current) {

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { $ as IndexedDbRemoteCursorStore, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportRoomStatus, H as TransportDeleteStreamSuccess, I as SnapshotUploadOptions, J as TransportSyncSuccess, K as TransportSnapshotUploadSuccess, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as InMemoryRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportError, V as TransportCreateStreamSuccess, W as TransportJoinParams, X as BeforeRemoteCursorSaveContext, Y as WriteOnlyAppendResult, Z as BeforeRemoteCursorSaveHook, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as IndexedDbRemoteCursorStoreOptions, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as createInitialRemoteCursor, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorSaveSource, o as StreamsCrdt, p as E2eeKey, q as TransportSubscription, r as isValidRillId, rt as RemoteCursorStore, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursor, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-BP6BR7jn.js";
-export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, E2eeEncryptionOptions, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeKey, E2eeKeyProvider, E2eeOptions, E2eeReadPolicy, E2eeScope, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, PayloadProtectionEncryptionOptions, PayloadProtectionKey, PayloadProtectionKeyProvider, PayloadProtectionOptions, PayloadProtectionReadPolicy, PayloadProtectionScope, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };
+import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DAAMJlvT.js";
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, E2eeEncryptionOptions, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeKey, E2eeKeyProvider, E2eeOptions, E2eeReadPolicy, E2eeScope, E2eeWritePolicy, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, PayloadProtectionEncryptionOptions, PayloadProtectionKey, PayloadProtectionKeyProvider, PayloadProtectionOptions, PayloadProtectionReadPolicy, PayloadProtectionScope, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-AfFikxB2.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-fOF9ZqCH.js";
 export { PayloadProtectionError as E2eeError, PayloadProtectionError, EphemeralStreamCrdt, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, StreamsCrdt, createInitialRemoteCursor, createStreamUrl, isValidBucketId, isValidRillId };

package/dist/loro.d.ts

@@ -1,4 +1,4 @@
-import { $ as IndexedDbRemoteCursorStore, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportRoomStatus, H as TransportDeleteStreamSuccess, I as SnapshotUploadOptions, J as TransportSyncSuccess, K as TransportSnapshotUploadSuccess, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as InMemoryRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportError, V as TransportCreateStreamSuccess, W as TransportJoinParams, X as BeforeRemoteCursorSaveContext, Y as WriteOnlyAppendResult, Z as BeforeRemoteCursorSaveHook, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as IndexedDbRemoteCursorStoreOptions, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as createInitialRemoteCursor, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorSaveSource, o as StreamsCrdt, p as E2eeKey, q as TransportSubscription, r as isValidRillId, rt as RemoteCursorStore, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursor, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-BP6BR7jn.js";
+import { $ as BeforeRemoteCursorSaveHook, A as PayloadProtectionReadPolicy, B as StreamsCrdtShardUrlsOptions, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportError, H as TransportCatchupSuccess, I as SnapshotUploadOptions, J as TransportSnapshotUploadSuccess, K as TransportJoinParams, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as BeforeRemoteCursorSaveContext, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportCreateStreamSuccess, V as TransportCatchupParams, W as TransportDeleteStreamSuccess, X as TransportSyncSuccess, Y as TransportSubscription, Z as WriteOnlyAppendResult, _ as E2eeScope, a as EphemeralStreamCrdt, at as RemoteCursorStore, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as InMemoryRemoteCursorStore, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, it as RemoteCursorSaveSource, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as IndexedDbRemoteCursorStoreOptions, o as StreamsCrdt, ot as createInitialRemoteCursor, p as E2eeKey, q as TransportRoomStatus, r as isValidRillId, rt as RemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as IndexedDbRemoteCursorStore, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-DAAMJlvT.js";
 import { LoroDoc } from "loro-crdt";
 
 //#region src/loro.d.ts
@@ -41,5 +41,5 @@ interface LoroEphemeralStoreLike {
 declare function EphemeralStoreAdaptor(store: LoroEphemeralStoreLike): EphemeralStreamAdaptor;
 declare const createLoroEphemeralStoreAdaptor: typeof EphemeralStoreAdaptor;
 //#endregion
-export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, E2eeEncryptionOptions, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeKey, E2eeKeyProvider, E2eeOptions, E2eeReadPolicy, E2eeScope, E2eeWritePolicy, EphemeralStoreAdaptor, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, LoroEphemeralStoreLike, PayloadProtectionEncryptionOptions, PayloadProtectionKey, PayloadProtectionKeyProvider, PayloadProtectionOptions, PayloadProtectionReadPolicy, PayloadProtectionScope, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, createLoroDocAdapter, createLoroEphemeralStoreAdaptor, createStreamUrl, isValidBucketId, isValidRillId };
+export { BeforeRemoteCursorSaveContext, BeforeRemoteCursorSaveHook, CrdtAdapter, CrdtApplyOutcome, CrdtApplyReturn, CrdtUnresolvedSpan, CrdtUpdateBatch, E2eeEncryptionOptions, PayloadProtectionError as E2eeError, PayloadProtectionError, E2eeKey, E2eeKeyProvider, E2eeOptions, E2eeReadPolicy, E2eeScope, E2eeWritePolicy, EphemeralStoreAdaptor, EphemeralStreamAdaptor, EphemeralStreamCrdt, EphemeralStreamCrdtOptions, EphemeralStreamJoinParams, EphemeralStreamSubscription, InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, IndexedDbRemoteCursorStoreOptions, IsolatedCrdtAdapter, JsonObject, JsonValue, LoroEphemeralStoreLike, PayloadProtectionEncryptionOptions, PayloadProtectionKey, PayloadProtectionKeyProvider, PayloadProtectionOptions, PayloadProtectionReadPolicy, PayloadProtectionScope, PayloadProtectionWritePolicy, RemoteCursor, RemoteCursorSaveSource, RemoteCursorStore, Result, SnapshotCodec, SnapshotTransformHook, SnapshotUploadOptions, StreamsAuthContext, StreamsAuthProvider, StreamsCrdt, StreamsCrdtOptions, StreamsCrdtShardUrlsOptions, TransportCatchupParams, TransportCatchupSuccess, TransportCreateStreamSuccess, TransportDeleteStreamSuccess, TransportError, TransportJoinParams, TransportRoomStatus, TransportSnapshotUploadSuccess, TransportSubscription, TransportSyncSuccess, WriteOnlyAppendResult, createInitialRemoteCursor, createLoroDocAdapter, createLoroEphemeralStoreAdaptor, createStreamUrl, isValidBucketId, isValidRillId };
 //# sourceMappingURL=loro.d.ts.map

package/dist/loro.js

@@ -1,4 +1,4 @@
-import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-AfFikxB2.js";
+import { a as InMemoryRemoteCursorStore, c as EphemeralStreamCrdt, i as StreamsCrdt, l as PayloadProtectionError, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-fOF9ZqCH.js";
 import { LoroDoc, VersionVector, decodeImportBlobMeta } from "loro-crdt";
 //#region src/loro.ts
 function batchImportUpdates(doc, updates) {

package/dist/{stream-id-BP6BR7jn.d.ts → stream-id-DAAMJlvT.d.ts}

@@ -356,6 +356,24 @@ interface TransportDeleteStreamSuccess {
 interface TransportSyncSuccess<TVersion extends JsonObject = JsonObject> {
   readonly cursor: RemoteCursor<TVersion>;
 }
+/**
+ * Optional parameters for a `catchup()` call.
+ */
+interface TransportCatchupParams {
+  /**
+   * When `false` or omitted, an active healthy live read loop is treated as
+   * already catching up and `catchup()` returns immediately with the current
+   * cursor. When `true`, the transport performs one non-SSE offset read even
+   * if live SSE/long-poll is currently healthy.
+   */
+  readonly force?: boolean;
+}
+/**
+ * Result payload returned by `catchup()`.
+ */
+interface TransportCatchupSuccess<TVersion extends JsonObject = JsonObject> {
+  readonly cursor: RemoteCursor<TVersion>;
+}
 /**
  * Result payload returned by the internal snapshot upload test hook.
  */
@@ -732,6 +750,21 @@ interface StreamsCrdtLike<TVersion extends JsonObject> {
   createStream(): Promise<Result<TransportCreateStreamSuccess, TransportError>>;
   deleteStream(): Promise<Result<TransportDeleteStreamSuccess, TransportError>>;
   sync(): Promise<Result<TransportSyncSuccess<TVersion>, TransportError>>;
+  /**
+   * Pulls remote stream updates into the local CRDT without intentionally
+   * appending new local updates.
+   *
+   * If a healthy `join()` live read loop is active, this is a fast no-op by
+   * default because the loop is already catching up continuously. Pass
+   * `{ force: true }` to issue one explicit non-SSE offset read anyway.
+   *
+   * If the live read side of a join is reconnecting, disconnected, or in
+   * error, `catchup()` attempts one immediate non-SSE offset read from the
+   * room's current cursor and then nudges the live loops to reconnect. Use
+   * `sync()` or `subscription.waitUntilSynced()` when the caller also needs
+   * local pending changes uploaded to the server.
+   */
+  catchup(params?: TransportCatchupParams): Promise<Result<TransportCatchupSuccess<TVersion>, TransportError>>;
   /**
    * Appends only locally observed batches without reading remote state first.
    *
@@ -840,6 +873,16 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
    * Runs one bootstrap/catch-up cycle without entering live mode.
    */
   sync(): Promise<Result<TransportSyncSuccess<TVersion>, TransportError>>;
+  /**
+   * Pulls remote updates into the local CRDT without intentionally appending
+   * new local updates.
+   *
+   * Healthy live reads already catch up continuously, so an active `join()`
+   * returns immediately unless `force: true` is passed. Reconnecting or
+   * terminal live reads perform one immediate non-SSE offset read and then
+   * nudge the room to reconnect.
+   */
+  catchup(params?: TransportCatchupParams): Promise<Result<TransportCatchupSuccess<TVersion>, TransportError>>;
   /**
    * Appends local CRDT updates without reading the stream first.
    *
@@ -859,8 +902,10 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
   private performInitialJoinSync;
   private createInitialCursor;
   private resolveInitialRemoteState;
+  private resolvePullOnlyRemoteState;
+  private catchupJoinState;
   private bootstrapState;
-  private catchup;
+  private catchupFromCursor;
   private catchupOrGone;
   private recoverLiveIncompleteRemoteApply;
   private appendLocalBatch;
@@ -1005,5 +1050,5 @@ declare function createStreamUrl(input: {
   baseUrl?: string;
 }): string;
 //#endregion
-export { IndexedDbRemoteCursorStore as $, PayloadProtectionReadPolicy as A, StreamsCrdtShardUrlsOptions as B, IsolatedCrdtAdapter as C, PayloadProtectionKey as D, PayloadProtectionEncryptionOptions as E, SnapshotTransformHook as F, TransportRoomStatus as G, TransportDeleteStreamSuccess as H, SnapshotUploadOptions as I, TransportSyncSuccess as J, TransportSnapshotUploadSuccess as K, StreamsAuthContext as L, PayloadProtectionWritePolicy as M, Result as N, PayloadProtectionKeyProvider as O, SnapshotCodec as P, InMemoryRemoteCursorStore as Q, StreamsAuthProvider as R, EphemeralStreamSubscription as S, JsonValue as T, TransportError as U, TransportCreateStreamSuccess as V, TransportJoinParams as W, BeforeRemoteCursorSaveContext as X, WriteOnlyAppendResult as Y, BeforeRemoteCursorSaveHook as Z, E2eeScope as _, EphemeralStreamCrdt as a, EphemeralStreamCrdtOptions as b, CrdtApplyOutcome as c, CrdtUpdateBatch as d, IndexedDbRemoteCursorStoreOptions as et, E2eeEncryptionOptions as f, E2eeReadPolicy as g, E2eeOptions as h, PayloadProtectionError as i, createInitialRemoteCursor as it, PayloadProtectionScope as j, PayloadProtectionOptions as k, CrdtApplyReturn as l, E2eeKeyProvider as m, isValidBucketId as n, RemoteCursorSaveSource as nt, StreamsCrdt as o, E2eeKey as p, TransportSubscription as q, isValidRillId as r, RemoteCursorStore as rt, CrdtAdapter as s, createStreamUrl as t, RemoteCursor as tt, CrdtUnresolvedSpan as u, E2eeWritePolicy as v, JsonObject as w, EphemeralStreamJoinParams as x, EphemeralStreamAdaptor as y, StreamsCrdtOptions as z };
-//# sourceMappingURL=stream-id-BP6BR7jn.d.ts.map
+export { BeforeRemoteCursorSaveHook as $, PayloadProtectionReadPolicy as A, StreamsCrdtShardUrlsOptions as B, IsolatedCrdtAdapter as C, PayloadProtectionKey as D, PayloadProtectionEncryptionOptions as E, SnapshotTransformHook as F, TransportError as G, TransportCatchupSuccess as H, SnapshotUploadOptions as I, TransportSnapshotUploadSuccess as J, TransportJoinParams as K, StreamsAuthContext as L, PayloadProtectionWritePolicy as M, Result as N, PayloadProtectionKeyProvider as O, SnapshotCodec as P, BeforeRemoteCursorSaveContext as Q, StreamsAuthProvider as R, EphemeralStreamSubscription as S, JsonValue as T, TransportCreateStreamSuccess as U, TransportCatchupParams as V, TransportDeleteStreamSuccess as W, TransportSyncSuccess as X, TransportSubscription as Y, WriteOnlyAppendResult as Z, E2eeScope as _, EphemeralStreamCrdt as a, RemoteCursorStore as at, EphemeralStreamCrdtOptions as b, CrdtApplyOutcome as c, CrdtUpdateBatch as d, InMemoryRemoteCursorStore as et, E2eeEncryptionOptions as f, E2eeReadPolicy as g, E2eeOptions as h, PayloadProtectionError as i, RemoteCursorSaveSource as it, PayloadProtectionScope as j, PayloadProtectionOptions as k, CrdtApplyReturn as l, E2eeKeyProvider as m, isValidBucketId as n, IndexedDbRemoteCursorStoreOptions as nt, StreamsCrdt as o, createInitialRemoteCursor as ot, E2eeKey as p, TransportRoomStatus as q, isValidRillId as r, RemoteCursor as rt, CrdtAdapter as s, createStreamUrl as t, IndexedDbRemoteCursorStore as tt, CrdtUnresolvedSpan as u, E2eeWritePolicy as v, JsonObject as w, EphemeralStreamJoinParams as x, EphemeralStreamAdaptor as y, StreamsCrdtOptions as z };
+//# sourceMappingURL=stream-id-DAAMJlvT.d.ts.map

package/dist/{stream-id-AfFikxB2.js → stream-id-fOF9ZqCH.js}

@@ -2495,6 +2495,34 @@ var StreamsCrdt = class StreamsCrdt {
 		}
 	}
 	/**
+	* Pulls remote updates into the local CRDT without intentionally appending
+	* new local updates.
+	*
+	* Healthy live reads already catch up continuously, so an active `join()`
+	* returns immediately unless `force: true` is passed. Reconnecting or
+	* terminal live reads perform one immediate non-SSE offset read and then
+	* nudge the room to reconnect.
+	*/
+	async catchup(params = {}) {
+		try {
+			this.disableWriteOnlyMode("appendWriteOnly cannot be used after catchup() on the same transport");
+			const state = this.joinState;
+			if (state != null && !state.closed) return {
+				ok: true,
+				value: { cursor: await this.catchupJoinState(state, params) }
+			};
+			return {
+				ok: true,
+				value: { cursor: (await this.resolvePullOnlyRemoteState()).cursor }
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: toTransportError(error)
+			};
+		}
+	}
+	/**
 	* Appends local CRDT updates without reading the stream first.
 	*
 	* Use this for write-only actors whose auth token may POST to the stream but
@@ -2747,6 +2775,40 @@ var StreamsCrdt = class StreamsCrdt {
 			return await this.bootstrapState(this.createInitialCursor());
 		}
 	}
+	async resolvePullOnlyRemoteState() {
+		const loaded = await this.remoteCursorStore.load(this.streamUrl);
+		const cursor = loaded ?? this.createInitialCursor();
+		try {
+			if (loaded == null) return await this.bootstrapState(cursor);
+			return await this.catchupFromCursor(cursor);
+		} catch (error) {
+			if (!isStreamNotFoundError(error) || !this.createStreamIfMissing) throw error;
+			await this.ensureStreamExists();
+			return await this.bootstrapState(this.createInitialCursor());
+		}
+	}
+	async catchupJoinState(state, params) {
+		if (state.readSubStatus === "connecting") {
+			await state.started;
+			return state.cursor;
+		}
+		if (state.readSubStatus === "ok" && params.force !== true) return state.cursor;
+		const cursor = await this.enqueueExclusive(async () => {
+			if (state.closed) throw new Error("subscription closed");
+			const caughtUp = await this.catchupFromCursor(state.cursor, void 0, state.streamCursor, (previousVersion, nextVersion) => {
+				this.snapshotManager.observeRemoteVersion(state, previousVersion, nextVersion);
+			});
+			state.cursor = caughtUp.cursor;
+			state.streamCursor = caughtUp.streamCursor;
+			return state.cursor;
+		});
+		if (state.closed) return cursor;
+		state.retryAttempt = 0;
+		state.lastError = void 0;
+		if (state.readSubStatus !== "ok" || state.writeSubStatus === "error") this.rejoin();
+		else if (state.pendingLocal.length > 0) this.flushPendingLocal(state);
+		return cursor;
+	}
 	async bootstrapState(cursor, options = {}) {
 		const cursorManager = options.cursorManager ?? this.cursorManager;
 		const result = await this.client.bootstrap();
@@ -2766,7 +2828,7 @@ var StreamsCrdt = class StreamsCrdt {
 			streamCursor: bootstrapCursor
 		};
 	}
-	async catchup(cursor, live, streamCursor, onRemoteVersionApplied) {
+	async catchupFromCursor(cursor, live, streamCursor, onRemoteVersionApplied) {
 		const result = await this.catchupOrGone(cursor, {
 			live,
 			streamCursor,
@@ -3482,4 +3544,4 @@ function createStreamUrl(input) {
 //#endregion
 export { InMemoryRemoteCursorStore as a, EphemeralStreamCrdt as c, StreamsCrdt as i, PayloadProtectionError as l, isValidBucketId as n, IndexedDbRemoteCursorStore as o, isValidRillId as r, createInitialRemoteCursor as s, createStreamUrl as t };
 
-//# sourceMappingURL=stream-id-AfFikxB2.js.map
+//# sourceMappingURL=stream-id-fOF9ZqCH.js.map