@loro-dev/streams-crdt 0.11.1 → 0.12.0

package/README.md

@@ -54,6 +54,7 @@ if (!result.ok) {
       break;
     case "network_error":
     case "timeout":
+    case "initial_sync_timeout":
       // Transient — safe to retry.
       break;
     case "protocol_error":
@@ -101,6 +102,7 @@ if (err.code === "server_error") {
 | `gone`                 | 410      | yes       | yes    | —                              |
 | `server_error`         | 5xx      | yes       | yes    | `requestId?`, `retryAfterMs?`  |
 | `timeout`              | —        | yes       | —      | `phase: "connect" \| "poll"`   |
+| `initial_sync_timeout` | —        | yes       | —      | `operation`, `timeoutMs`, `elapsedMs` |
 | `network_error`        | —        | yes       | —      | —                              |
 | `auth_provider_error`  | —        | yes       | —      | `cause?` (original thrown value) |
 | `internal_error`       | —        | yes       | —      | —                              |
@@ -120,6 +122,33 @@ if (err.code === "server_error") {
   call `transport.rejoin()` after fixing the cause (e.g., refreshing the auth
   token) to reset retry state and reconnect.
 
+#### Initial sync deadlines
+
+Initial bootstrap/catch-up work is allowed to run longer than ordinary request
+connect and poll deadlines. The transport uses `reconnectConfig` for this:
+
+```ts
+const transport = new StreamsCrdt({
+  streamUrl,
+  adapter,
+  auth,
+  reconnectConfig: {
+    // Logs a debug diagnostic when initial sync is still pending; does not abort.
+    initialSyncSlowAfterMs: 30_000,
+    // Aborts initial bootstrap/catch-up with `initial_sync_timeout`.
+    initialSyncHardTimeoutMs: 120_000,
+  },
+});
+```
+
+`join()`, `sync()`, pull-only `catchup()`, and 410 bootstrap recovery all use
+the initial-sync deadline path when they need to bootstrap or catch up from a
+stored cursor. In `StreamsCrdt` constructor options, set
+`initialSyncHardTimeoutMs` to `0` or `Infinity` to disable the hard cap. Because
+constructor `reconnectConfig` is merged over defaults, omitting the field keeps
+the default hard cap. Set `initialSyncSlowAfterMs` the same way to disable the
+slow diagnostic.
+
 > **Why `Result` instead of `throw`?** Transport failures (network errors,
 > auth expiry, missing streams) are expected at runtime, not exceptional.
 > Wrapping them in `Result` makes the error path explicit in the type system
@@ -141,8 +170,8 @@ Only adjust if any of these apply:
   `stream_not_found` now requires `status: 404` + `message`; `gone` now
   requires `status: 410`. TypeScript will flag these.
 - **You exhaustively switch on `code` with a `: never` default.** Add a case
-  for `auth_provider_error` (and optionally `server_error` if you handled
-  5xx via `unknown`/`internal_error` before).
+  for `auth_provider_error` and `initial_sync_timeout` (and optionally
+  `server_error` if you handled 5xx via `unknown`/`internal_error` before).
 - **You used `"message" in error` to defensively narrow.** All variants now
   carry `message`; the guard is no longer needed.
 
@@ -164,6 +193,8 @@ const transport = new StreamsCrdt({
   }),
   auth: async () => "<gateway-jwt>",
   adapter: createLoroDocAdapter(doc),
+  // Optional TTL applied when the stream is created.
+  streamTtlSeconds: 60 * 60 * 24 * 30,
   // Enable automatic snapshot upload so new readers bootstrap faster.
   snapshotUpload: { canUpload: async () => true },
 });
@@ -205,16 +236,20 @@ const transport = new StreamsCrdt({
   adapter: createLoroDocAdapter(doc),
   shardUrls: {
     bootstrap: [
-      "https://control-a.streams-api-proxy.loro.dev",
-      "https://control-b.streams-api-proxy.loro.dev",
+      "https://control-a.api.streams-api-x.loro.dev",
+      "https://control-b.api.streams-api-x.loro.dev",
     ],
     catchup: [
-      "https://control-a.streams-api-proxy.loro.dev",
-      "https://control-b.streams-api-proxy.loro.dev",
+      "https://control-a.api.streams-api-x.loro.dev",
+      "https://control-b.api.streams-api-x.loro.dev",
     ],
     largePost: [
-      "https://write-a.streams-api-proxy.loro.dev",
-      "https://write-b.streams-api-proxy.loro.dev",
+      "https://write-a.api.streams-api-x.loro.dev",
+      "https://write-b.api.streams-api-x.loro.dev",
+    ],
+    other: [
+      "https://live-a.api.streams-api-x.loro.dev",
+      "https://live-b.api.streams-api-x.loro.dev",
     ],
     largePostMinBytes: 64 * 1024,
   },
@@ -225,12 +260,14 @@ 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.
+offset reads, including long-poll fallback. `largePost` applies to non-empty
+append POST bodies at or above `largePostMinBytes` bytes. `other` applies when
+no operation-specific pool routes the request, covering live SSE, create/delete,
+head, snapshot upload, and append POSTs not routed by `largePost`. 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
 
@@ -1050,6 +1087,7 @@ const transport = new StreamsCrdt({
   result types used to report incomplete imports such as Loro pending updates
 - `Result` — Rust-style `Ok | Err` result
 - `StreamsAuthProvider` — auth callback type
+- `StreamsCrdtShardUrlsOptions` — optional origin pools for request routing
 - `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.
@@ -1105,6 +1143,9 @@ const transport = new StreamsCrdt({
 ## Notes
 
 - `createStreamIfMissing` defaults to `false` and only affects the initial sync/join bootstrap
+- `streamTtlSeconds` is a non-negative safe integer in seconds. It is sent only
+  when the transport creates the stream, either through `createStream()` or
+  automatic creation with `createStreamIfMissing`.
 - `deleteStream()` returns `{ deleted: false }` when the target stream is already missing
 - `sync()` and `join()` return `Result` objects instead of implicitly creating missing streams
 - `join()` resolves only after the initial replay has succeeded; without a stored remote cursor it bootstraps once, then prefers ordinary live SSE and falls back sticky to long-poll

package/dist/flock.d.ts

@@ -1,4 +1,4 @@
-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 { $ 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-DJYQlTE2.js";
 import { ExportBundle, Flock, VersionVector, VersionVector as VersionVector$1 } from "@loro-dev/flock-wasm";
 
 //#region src/flock.d.ts

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-fOF9ZqCH.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-DVVP3k7V.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 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 { $ 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-DJYQlTE2.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-fOF9ZqCH.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-DVVP3k7V.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 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 { $ 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-DJYQlTE2.js";
 import { LoroDoc } from "loro-crdt";
 
 //#region src/loro.d.ts

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-fOF9ZqCH.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-DVVP3k7V.js";
 import { LoroDoc, VersionVector, decodeImportBlobMeta } from "loro-crdt";
 //#region src/loro.ts
 function batchImportUpdates(doc, updates) {

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

@@ -104,10 +104,29 @@ declare function createInitialRemoteCursor<TVersion extends JsonObject = JsonObj
  * Retry and timeout settings used by `StreamsCrdt`.
  */
 interface ReconnectConfig {
+  /** Retry delay schedule in milliseconds, indexed by retry attempt and clamped at the last entry. */
   readonly delays: readonly number[];
+  /** Fractional +/- jitter applied to scheduled retry delays. */
   readonly jitterFraction: number;
+  /** Maximum retry attempts for background live loops. Use `Infinity` to retry forever. */
   readonly maxAttempts: number;
+  /** Connect deadline for ordinary transport requests. */
   readonly connectTimeoutMs: number;
+  /**
+   * Soft diagnostic threshold for initial bootstrap/catch-up.
+   *
+   * Crossing this threshold does not abort or reject the in-flight request.
+   * Set to 0 or `Infinity` to disable it.
+   */
+  readonly initialSyncSlowAfterMs?: number;
+  /**
+   * Hard cap for initial bootstrap/catch-up before aborting with
+   * `initial_sync_timeout`.
+   *
+   * Set to 0 or `Infinity` to disable it.
+   */
+  readonly initialSyncHardTimeoutMs?: number;
+  /** Poll deadline for ordinary long-poll/read requests. */
   readonly pollTimeoutMs: number;
   /** SSE inactivity timeout. Aborts and reconnects if no event arrives within this period. */
   readonly liveInactivityTimeoutMs?: number;
@@ -186,6 +205,7 @@ type TransportRoomStatus = "joined" | "reconnecting" | "disconnected" | "error";
  * - `protocol_error` — 400/405/409 or malformed response; treat as a bug.
  * - `network_error` — fetch-level failure (DNS, connection refused). Retry.
  * - `timeout` — connect or poll deadline exceeded. Retry.
+ * - `initial_sync_timeout` — initial bootstrap/catch-up exceeded its hard cap.
  * - `gone` — 410; persisted cursor is no longer valid. Bootstrap from scratch.
  * - `apply_incomplete` — a CRDT adapter could not fully apply remote data.
  * - `server_error` — 5xx; transient backend failure, retry with backoff.
@@ -272,6 +292,18 @@ type TransportError =
   readonly phase: "connect" | "poll";
   readonly message: string;
 }
+/**
+ * Initial bootstrap/catch-up exceeded its hard timeout. The request was allowed
+ * past the slow diagnostic threshold first; this only fires at the hard cap.
+ */
+| {
+  readonly code: "initial_sync_timeout";
+  readonly retryable: true;
+  readonly operation: string;
+  readonly timeoutMs: number;
+  readonly elapsedMs: number;
+  readonly message: string;
+}
 /**
  * The server indicated the persisted cursor is no longer valid (410). The
  * runtime will bootstrap from scratch on the next `join()`/`sync()` —
@@ -418,19 +450,32 @@ 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
+   * `https://control-a.api.streams-api-x.loro.dev`. The transport keeps the
    * stream path and query from `streamUrl` and only replaces the request origin.
+   * If omitted, `other` is used as the fallback pool for bootstrap requests.
    */
   readonly bootstrap?: readonly string[];
   /**
    * Origin URLs used for non-SSE catch-up reads:
    * `GET <stream>?offset=...` and long-poll fallback reads.
+   *
+   * If omitted, `other` is used as the fallback pool for catch-up requests.
    */
   readonly catchup?: readonly string[];
   /**
    * Origin URLs used for large `POST <stream>` append requests.
+   *
+   * If omitted, `other` is used as the fallback pool for large append requests.
    */
   readonly largePost?: readonly string[];
+  /**
+   * Origin URLs used when no operation-specific shard pool routes the request.
+   *
+   * This covers live SSE reads, create/delete/head requests, snapshot uploads,
+   * append POSTs not routed by `largePost`, and any future request shape not
+   * listed above.
+   */
+  readonly other?: readonly string[];
   /**
    * Minimum request body size before `largePost` routing applies.
    *
@@ -670,6 +715,8 @@ interface EphemeralStreamCrdtOptions {
   readonly auth?: StreamsAuthProvider;
   /** Optional fetch implementation for tests, workers, or custom runtimes. */
   readonly fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+  /** Optional origin pools for routing ephemeral POST/SSE requests. */
+  readonly shardUrls?: StreamsCrdtShardUrlsOptions;
   /** Reconnect policy for the SSE read loop and local POST retry loop. */
   readonly reconnectConfig?: Partial<ReconnectConfig>;
   /** Enables diagnostic console logging for terminal read/write failures. */
@@ -690,6 +737,15 @@ interface StreamsCrdtOptions<TVersion extends JsonObject> {
    * Defaults to false so missing streams are surfaced explicitly.
    */
   readonly createStreamIfMissing?: boolean;
+  /**
+   * Optional stream time-to-live in seconds used when creating the stream.
+   *
+   * Applies to both explicit `createStream()` calls and automatic stream
+   * creation through `createStreamIfMissing`. The value must be a non-negative
+   * safe integer. Updating this option on an existing stream has no effect
+   * until the transport creates that stream again.
+   */
+  readonly streamTtlSeconds?: number;
   /**
    * Auth token source.
    *
@@ -741,8 +797,16 @@ interface StreamsCrdtOptions<TVersion extends JsonObject> {
    */
   readonly payloadProtection?: PayloadProtectionOptions;
   readonly snapshotUpload?: SnapshotUploadOptions;
-  /** Optional origin pools for routing bootstrap/catch-up and large append requests. */
+  /** Optional origin pools for routing transport requests. */
   readonly shardUrls?: StreamsCrdtShardUrlsOptions;
+  /**
+   * Partial override for retry, ordinary request timeout, live SSE inactivity,
+   * and initial bootstrap/catch-up deadline behavior.
+   *
+   * The runtime merges this with its defaults. `initialSyncSlowAfterMs` is only
+   * a diagnostic threshold; it does not abort the request. `initialSyncHardTimeoutMs`
+   * aborts initial bootstrap/catch-up and returns `initial_sync_timeout`.
+   */
   readonly reconnectConfig?: Partial<ReconnectConfig>;
   readonly debug?: boolean;
 }
@@ -897,6 +961,7 @@ declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLik
   join(params?: TransportJoinParams): Promise<Result<TransportSubscription, TransportError>>;
   private createSubscription;
   private disposeJoinState;
+  private runInitialSyncWithDeadline;
   private startJoin;
   private syncOnce;
   private performInitialJoinSync;
@@ -1051,4 +1116,4 @@ declare function createStreamUrl(input: {
 }): string;
 //#endregion
 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
+//# sourceMappingURL=stream-id-DJYQlTE2.d.ts.map