@loro-dev/streams-crdt 0.9.1 → 0.11.0

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
@@ -189,6 +191,47 @@ const sub = joined.value;
 checked out or detached, call `checkoutToLatest()` or `attach()` before passing
 it to `StreamsCrdt`.
 
+### Request shard origins
+
+Browsers can still show head-of-line blocking symptoms when large
+bootstrap/catch-up downloads and normal app requests contend on the same
+connection. `shardUrls` lets the transport replace only the request origin for
+selected operations while preserving the stream path and query:
+
+```ts
+const transport = new StreamsCrdt({
+  streamUrl,
+  auth: async () => "<gateway-jwt>",
+  adapter: createLoroDocAdapter(doc),
+  shardUrls: {
+    bootstrap: [
+      "https://control-a.streams-api-proxy.loro.dev",
+      "https://control-b.streams-api-proxy.loro.dev",
+    ],
+    catchup: [
+      "https://control-a.streams-api-proxy.loro.dev",
+      "https://control-b.streams-api-proxy.loro.dev",
+    ],
+    largePost: [
+      "https://write-a.streams-api-proxy.loro.dev",
+      "https://write-b.streams-api-proxy.loro.dev",
+    ],
+    largePostMinBytes: 64 * 1024,
+  },
+});
+```
+
+Shard entries must be origin URLs with no path, query, or hash. Each transport
+instance rotates through the configured origins per operation, with a randomized
+starting point so multiple tabs are less likely to all begin on the same shard.
+Bootstrap applies to `GET <stream>/bootstrap`; catch-up applies to non-SSE
+offset reads, including long-poll fallback; SSE live reads stay on the original
+`streamUrl`. `largePost` applies to non-empty append POST bodies at or above
+`largePostMinBytes` bytes. The default threshold is `0`, so every non-empty
+append POST can use `largePost` when that pool is configured. Verify actual
+connection separation with browser NetLog: browsers may coalesce compatible
+HTTP/2 or HTTP/3 origins when DNS, certificate, and transport settings allow it.
+
 ### Loro pending imports and cursor safety
 
 Loro can accept an update whose dependencies are missing and keep it as a
@@ -330,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 **`catchup()`** when you only want to pull remote updates into the local
+CRDT:
+
+```ts
+// 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.
+```
 
-Use **`sync()`** when you need a one-shot catch-up without entering live mode:
+`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
-// Offline-first: catch up on app start, then work offline.
+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:
 
@@ -980,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 IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-JuJ1JqCX.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, 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-2eJsM9CJ.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 IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-JuJ1JqCX.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, 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-2eJsM9CJ.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 IndexedDbRemoteCursorStoreOptions, A as PayloadProtectionReadPolicy, B as TransportCreateStreamSuccess, C as IsolatedCrdtAdapter, D as PayloadProtectionKey, E as PayloadProtectionEncryptionOptions, F as SnapshotTransformHook, G as TransportSnapshotUploadSuccess, H as TransportError, I as SnapshotUploadOptions, J as WriteOnlyAppendResult, K as TransportSubscription, L as StreamsAuthContext, M as PayloadProtectionWritePolicy, N as Result, O as PayloadProtectionKeyProvider, P as SnapshotCodec, Q as IndexedDbRemoteCursorStore, R as StreamsAuthProvider, S as EphemeralStreamSubscription, T as JsonValue, U as TransportJoinParams, V as TransportDeleteStreamSuccess, W as TransportRoomStatus, X as BeforeRemoteCursorSaveHook, Y as BeforeRemoteCursorSaveContext, Z as InMemoryRemoteCursorStore, _ as E2eeScope, a as EphemeralStreamCrdt, b as EphemeralStreamCrdtOptions, c as CrdtApplyOutcome, d as CrdtUpdateBatch, et as RemoteCursor, f as E2eeEncryptionOptions, g as E2eeReadPolicy, h as E2eeOptions, i as PayloadProtectionError, j as PayloadProtectionScope, k as PayloadProtectionOptions, l as CrdtApplyReturn, m as E2eeKeyProvider, n as isValidBucketId, nt as RemoteCursorStore, o as StreamsCrdt, p as E2eeKey, q as TransportSyncSuccess, r as isValidRillId, rt as createInitialRemoteCursor, s as CrdtAdapter, t as createStreamUrl, tt as RemoteCursorSaveSource, u as CrdtUnresolvedSpan, v as E2eeWritePolicy, w as JsonObject, x as EphemeralStreamJoinParams, y as EphemeralStreamAdaptor, z as StreamsCrdtOptions } from "./stream-id-JuJ1JqCX.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, 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-2eJsM9CJ.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-JuJ1JqCX.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.
  */
@@ -395,6 +413,32 @@ interface SnapshotUploadOptions {
   /** Minimum byte delta since the last remote snapshot before uploading. */
   readonly minBytesSinceRemoteSnapshot?: number;
 }
+interface StreamsCrdtShardUrlsOptions {
+  /**
+   * Origin URLs used for `GET <stream>/bootstrap`.
+   *
+   * Each entry should be an origin URL such as
+   * `https://control-a.streams-api-proxy.loro.dev`. The transport keeps the
+   * stream path and query from `streamUrl` and only replaces the request origin.
+   */
+  readonly bootstrap?: readonly string[];
+  /**
+   * Origin URLs used for non-SSE catch-up reads:
+   * `GET <stream>?offset=...` and long-poll fallback reads.
+   */
+  readonly catchup?: readonly string[];
+  /**
+   * Origin URLs used for large `POST <stream>` append requests.
+   */
+  readonly largePost?: readonly string[];
+  /**
+   * Minimum request body size before `largePost` routing applies.
+   *
+   * Defaults to 0, meaning every non-empty append POST can use `largePost`
+   * when that shard pool is configured.
+   */
+  readonly largePostMinBytes?: number;
+}
 /**
  * Transforms a remote snapshot payload during upload or bootstrap.
  */
@@ -697,6 +741,8 @@ interface StreamsCrdtOptions<TVersion extends JsonObject> {
    */
   readonly payloadProtection?: PayloadProtectionOptions;
   readonly snapshotUpload?: SnapshotUploadOptions;
+  /** Optional origin pools for routing bootstrap/catch-up and large append requests. */
+  readonly shardUrls?: StreamsCrdtShardUrlsOptions;
   readonly reconnectConfig?: Partial<ReconnectConfig>;
   readonly debug?: boolean;
 }
@@ -704,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.
    *
@@ -812,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.
    *
@@ -831,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;
@@ -977,5 +1050,5 @@ declare function createStreamUrl(input: {
   baseUrl?: string;
 }): string;
 //#endregion
-export { IndexedDbRemoteCursorStoreOptions as $, PayloadProtectionReadPolicy as A, TransportCreateStreamSuccess as B, IsolatedCrdtAdapter as C, PayloadProtectionKey as D, PayloadProtectionEncryptionOptions as E, SnapshotTransformHook as F, TransportSnapshotUploadSuccess as G, TransportError as H, SnapshotUploadOptions as I, WriteOnlyAppendResult as J, TransportSubscription as K, StreamsAuthContext as L, PayloadProtectionWritePolicy as M, Result as N, PayloadProtectionKeyProvider as O, SnapshotCodec as P, IndexedDbRemoteCursorStore as Q, StreamsAuthProvider as R, EphemeralStreamSubscription as S, JsonValue as T, TransportJoinParams as U, TransportDeleteStreamSuccess as V, TransportRoomStatus as W, BeforeRemoteCursorSaveHook as X, BeforeRemoteCursorSaveContext as Y, InMemoryRemoteCursorStore as Z, E2eeScope as _, EphemeralStreamCrdt as a, EphemeralStreamCrdtOptions as b, CrdtApplyOutcome as c, CrdtUpdateBatch as d, RemoteCursor as et, E2eeEncryptionOptions as f, E2eeReadPolicy as g, E2eeOptions as h, PayloadProtectionError as i, PayloadProtectionScope as j, PayloadProtectionOptions as k, CrdtApplyReturn as l, E2eeKeyProvider as m, isValidBucketId as n, RemoteCursorStore as nt, StreamsCrdt as o, E2eeKey as p, TransportSyncSuccess as q, isValidRillId as r, createInitialRemoteCursor as rt, CrdtAdapter as s, createStreamUrl as t, RemoteCursorSaveSource as tt, CrdtUnresolvedSpan as u, E2eeWritePolicy as v, JsonObject as w, EphemeralStreamJoinParams as x, EphemeralStreamAdaptor as y, StreamsCrdtOptions as z };
-//# sourceMappingURL=stream-id-JuJ1JqCX.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-2eJsM9CJ.js → stream-id-fOF9ZqCH.js}

@@ -881,6 +881,56 @@ function resolveNextOffsetAfterConcurrentAdvance(requestOffset, currentOffset, r
 }
 //#endregion
 //#region src/transport-client.ts
+const bodySizeEncoder = new TextEncoder();
+function normalizeShardOrigins(urls, label) {
+	if (urls == null) return;
+	const out = [];
+	for (const raw of urls) {
+		const trimmed = raw.trim();
+		if (trimmed.length === 0) continue;
+		const url = new URL(trimmed);
+		if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`${label} shard URL must use http or https`);
+		if (url.pathname !== "/" || url.search !== "" || url.hash !== "") throw new Error(`${label} shard URL must be an origin URL`);
+		out.push(url.origin);
+	}
+	return out.length === 0 ? void 0 : out;
+}
+function normalizeShardUrlsOptions(options) {
+	if (options == null) return;
+	const largePostMinBytes = options.largePostMinBytes ?? 0;
+	if (!Number.isSafeInteger(largePostMinBytes) || largePostMinBytes < 0) throw new Error("shardUrls.largePostMinBytes must be a non-negative safe integer");
+	const normalized = {
+		bootstrap: normalizeShardOrigins(options.bootstrap, "shardUrls.bootstrap"),
+		catchup: normalizeShardOrigins(options.catchup, "shardUrls.catchup"),
+		largePost: normalizeShardOrigins(options.largePost, "shardUrls.largePost"),
+		largePostMinBytes
+	};
+	if (normalized.bootstrap == null && normalized.catchup == null && normalized.largePost == null) return;
+	return normalized;
+}
+function requestBodyByteLength(body) {
+	if (body == null) return 0;
+	if (typeof body === "string") return bodySizeEncoder.encode(body).byteLength;
+	if (body instanceof ArrayBuffer) return body.byteLength;
+	if (ArrayBuffer.isView(body)) return body.byteLength;
+	if (typeof Blob !== "undefined" && body instanceof Blob) return body.size;
+	if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) return bodySizeEncoder.encode(body.toString()).byteLength;
+}
+function createRandomShardStart(originCount) {
+	if (originCount <= 1) return 0;
+	try {
+		const crypto = globalThis.crypto;
+		if (crypto != null) {
+			const values = new Uint32Array(1);
+			crypto.getRandomValues(values);
+			return (values[0] ?? 0) % originCount;
+		}
+	} catch {}
+	return Math.floor(Math.random() * originCount);
+}
+function normalizedStreamPath(streamUrl) {
+	return streamUrl.pathname.endsWith("/") ? streamUrl.pathname.slice(0, -1) : streamUrl.pathname;
+}
 /**
 * Low-level HTTP and SSE client for one stream.
 *
@@ -894,24 +944,62 @@ var StreamsTransportClient = class {
 	fetchImpl;
 	authProvider;
 	reconnectConfig;
+	shardUrls;
+	shardCursorIndexes = {};
 	authRefreshInFlight;
 	constructor(options) {
 		this.streamUrl = options.streamUrl;
 		this.adapter = options.adapter;
+		this.fetchImpl = options.fetchImpl;
+		this.shardUrls = normalizeShardUrlsOptions(options.shardUrls);
 		this.client = new StreamsClient({
 			url: options.streamUrl,
 			auth: options.authProvider,
-			fetch: options.fetchImpl,
+			fetch: this.fetchRouted.bind(this),
 			retry: { maxAttempts: 0 },
 			timeout: {
 				connectTimeoutMs: options.reconnectConfig.connectTimeoutMs,
 				pollTimeoutMs: options.reconnectConfig.pollTimeoutMs
 			}
 		});
-		this.fetchImpl = options.fetchImpl;
 		this.authProvider = options.authProvider;
 		this.reconnectConfig = options.reconnectConfig;
 	}
+	fetchRouted(input, init) {
+		return this.fetchImpl(this.routeRequestUrl(input, init), init);
+	}
+	routeRequestUrl(input, init) {
+		const shardUrls = this.shardUrls;
+		if (shardUrls == null) return input;
+		const operation = this.classifyShardOperation(input, init, shardUrls);
+		if (operation == null) return input;
+		const origins = operation === "bootstrap" ? shardUrls.bootstrap : operation === "catchup" ? shardUrls.catchup : shardUrls.largePost;
+		if (origins == null || origins.length === 0) return input;
+		const target = new URL(input);
+		const shardOrigin = new URL(this.nextShardOrigin(operation, origins));
+		target.protocol = shardOrigin.protocol;
+		target.host = shardOrigin.host;
+		target.username = "";
+		target.password = "";
+		return target.toString();
+	}
+	nextShardOrigin(operation, origins) {
+		const currentIndex = this.shardCursorIndexes[operation] ?? createRandomShardStart(origins.length);
+		this.shardCursorIndexes[operation] = (currentIndex + 1) % origins.length;
+		return origins[currentIndex % origins.length];
+	}
+	classifyShardOperation(input, init, shardUrls) {
+		const method = (init?.method ?? "GET").toUpperCase();
+		const requestUrl = new URL(input);
+		const streamUrl = new URL(this.streamUrl);
+		const streamPath = normalizedStreamPath(streamUrl);
+		if (method === "GET" && requestUrl.pathname === `${streamPath}/bootstrap`) return "bootstrap";
+		if (method === "GET" && requestUrl.pathname === streamUrl.pathname && requestUrl.searchParams.has("offset") && requestUrl.searchParams.get("live") !== "sse") return "catchup";
+		if (method !== "POST" || requestUrl.pathname !== streamUrl.pathname) return;
+		const bodyLength = requestBodyByteLength(init?.body);
+		if (bodyLength == null || bodyLength === 0 || bodyLength < shardUrls.largePostMinBytes) return;
+		return "large-post";
+	}
 	async createStreamRequest() {
 		const adapterHeaders = this.adapter.getCreateStreamHeaders ? await this.adapter.getCreateStreamHeaders() : void 0;
 		const result = await this.client.create({ headers: adapterHeaders });
@@ -2209,7 +2297,8 @@ var StreamsCrdt = class StreamsCrdt {
 			adapter: this.adapter,
 			authProvider,
 			fetchImpl,
-			reconnectConfig: this.reconnectConfig
+			reconnectConfig: this.reconnectConfig,
+			shardUrls: options.shardUrls
 		});
 		this.cursorManager = this.createCursorManager(this.adapter, (cursor, source) => this.saveRemoteCursor(cursor, source));
 		this.volatileCursorManager = this.createCursorManager(this.adapter, async (cursor) => cursor);
@@ -2406,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
@@ -2658,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();
@@ -2677,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,
@@ -3393,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-2eJsM9CJ.js.map
+//# sourceMappingURL=stream-id-fOF9ZqCH.js.map