@loro-dev/streams-crdt 0.1.0

package/dist/loro.js

@@ -0,0 +1,108 @@
+import { a as InMemoryRemoteCursorStore, i as StreamsCrdt, n as isValidBucketId, o as IndexedDbRemoteCursorStore, r as isValidRillId, s as createInitialRemoteCursor, t as createStreamUrl } from "./stream-id-CIhmveJD.js";
+import { VersionVector, decodeImportBlobMeta } from "loro-crdt";
+//#region src/loro.ts
+function toDocVersionRecord(version) {
+	const out = {};
+	for (const [peer, counter] of version.toJSON()) out[peer] = counter;
+	return out;
+}
+function toDocVersionMap(version) {
+	const out = /* @__PURE__ */ new Map();
+	for (const [peer, counter] of Object.entries(version)) if (typeof counter === "number" && Number.isFinite(counter)) out.set(peer, counter);
+	return out;
+}
+function mergeDocVersions(base, incoming) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const [peer, counter] of Object.entries(base)) merged.set(peer, counter);
+	for (const [peer, counter] of Object.entries(incoming)) {
+		const peerId = peer;
+		merged.set(peerId, Math.max(merged.get(peerId) ?? 0, counter));
+	}
+	return toDocVersionRecord(VersionVector.parseJSON(merged));
+}
+function hasUpdatesSince(fromVersion, currentVersion) {
+	for (const [peer, counter] of Object.entries(currentVersion)) if (counter > (fromVersion[peer] ?? 0)) return true;
+	return false;
+}
+function extractVersionFromUpdate(update) {
+	try {
+		return toDocVersionRecord(decodeImportBlobMeta(update, false).partialEndVersionVector);
+	} catch {
+		return null;
+	}
+}
+function assertDocAttached(doc) {
+	if (!doc.isDetached()) return;
+	throw new Error("LoroDoc must be attached before using streams-crdt; call checkoutToLatest() or attach() first");
+}
+/**
+* Creates a `CrdtAdapter` for one `LoroDoc`.
+*
+* The `LoroDoc` must be attached (not detached or checked out to a historical
+* version). If the document is detached, call `doc.checkoutToLatest()` or
+* `doc.attach()` before passing it here.
+*
+* @example
+* ```ts
+* const doc = new LoroDoc();
+* const adapter = createLoroDocAdapter(doc);
+* const transport = new StreamsCrdt({ streamUrl, adapter, auth });
+* ```
+*/
+function createLoroDocAdapter(doc) {
+	return {
+		emptyVersion: () => ({}),
+		mergeVersions: (base, incoming) => mergeDocVersions(base, incoming),
+		exportSnapshot: () => {
+			assertDocAttached(doc);
+			return doc.export({ mode: "snapshot" });
+		},
+		applySnapshot: (snapshot) => {
+			assertDocAttached(doc);
+			doc.import(snapshot);
+			return toDocVersionRecord(doc.version());
+		},
+		exportUpdates: (fromVersion) => {
+			assertDocAttached(doc);
+			if (!hasUpdatesSince(fromVersion, toDocVersionRecord(doc.version()))) return;
+			const updates = [doc.export({
+				mode: "update",
+				from: VersionVector.parseJSON(toDocVersionMap(fromVersion))
+			})].filter((update) => update.byteLength > 0);
+			if (updates.length === 0) return;
+			let version = {};
+			for (const update of updates) {
+				const next = extractVersionFromUpdate(update);
+				if (next != null) version = mergeDocVersions(version, next);
+			}
+			return {
+				updates,
+				version
+			};
+		},
+		applyRemoteUpdates: (updates, remoterVersion) => {
+			assertDocAttached(doc);
+			if (updates.length > 0) doc.importBatch(updates);
+			let version = remoterVersion;
+			for (const update of updates) {
+				const next = extractVersionFromUpdate(update);
+				if (next != null) version = mergeDocVersions(version, next);
+			}
+			return version;
+		},
+		subscribeLocalUpdates: (listener) => {
+			assertDocAttached(doc);
+			return doc.subscribeLocalUpdates((update) => {
+				const version = extractVersionFromUpdate(update) ?? {};
+				listener({
+					updates: [update],
+					version
+				});
+			});
+		}
+	};
+}
+//#endregion
+export { InMemoryRemoteCursorStore, IndexedDbRemoteCursorStore, StreamsCrdt, createInitialRemoteCursor, createLoroDocAdapter, createStreamUrl, isValidBucketId, isValidRillId };
+
+//# sourceMappingURL=loro.js.map

package/dist/loro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loro.js","names":[],"sources":["../src/loro.ts"],"sourcesContent":["import {\n  decodeImportBlobMeta,\n  type LoroDoc,\n  VersionVector,\n} from \"loro-crdt\";\n\nimport type { CrdtAdapter, JsonObject } from \"./types\";\n\nexport { StreamsCrdt } from \"./transport\";\nexport * from \"./shared\";\n\ntype PeerId = `${number}`;\ntype DocVersionRecord = Record<PeerId, number>;\n\nfunction toDocVersionRecord(version: VersionVector): DocVersionRecord {\n  const out = {} as DocVersionRecord;\n  for (const [peer, counter] of version.toJSON()) {\n    out[peer as PeerId] = counter;\n  }\n  return out;\n}\n\nfunction toDocVersionMap(version: JsonObject): Map<PeerId, number> {\n  const out = new Map<PeerId, number>();\n  for (const [peer, counter] of Object.entries(version)) {\n    if (typeof counter === \"number\" && Number.isFinite(counter)) {\n      out.set(peer as PeerId, counter);\n    }\n  }\n  return out;\n}\n\nfunction mergeDocVersions(\n  base: DocVersionRecord,\n  incoming: DocVersionRecord,\n): DocVersionRecord {\n  const merged = new Map<PeerId, number>();\n  for (const [peer, counter] of Object.entries(base)) {\n    merged.set(peer as PeerId, counter);\n  }\n  for (const [peer, counter] of Object.entries(incoming)) {\n    const peerId = peer as PeerId;\n    merged.set(peerId, Math.max(merged.get(peerId) ?? 0, counter));\n  }\n  return toDocVersionRecord(VersionVector.parseJSON(merged));\n}\n\nfunction hasUpdatesSince(\n  fromVersion: DocVersionRecord,\n  currentVersion: DocVersionRecord,\n): boolean {\n  for (const [peer, counter] of Object.entries(currentVersion)) {\n    if (counter > (fromVersion[peer as PeerId] ?? 0)) {\n      return true;\n    }\n  }\n  return false;\n}\n\nfunction extractVersionFromUpdate(update: Uint8Array): DocVersionRecord | null {\n  try {\n    const meta = decodeImportBlobMeta(update, false);\n    return toDocVersionRecord(meta.partialEndVersionVector);\n  } catch {\n    return null;\n  }\n}\n\nfunction assertDocAttached(doc: LoroDoc): void {\n  if (!doc.isDetached()) {\n    return;\n  }\n  throw new Error(\n    \"LoroDoc must be attached before using streams-crdt; \" +\n      \"call checkoutToLatest() or attach() first\",\n  );\n}\n\n/**\n * Creates a `CrdtAdapter` for one `LoroDoc`.\n *\n * The `LoroDoc` must be attached (not detached or checked out to a historical\n * version). If the document is detached, call `doc.checkoutToLatest()` or\n * `doc.attach()` before passing it here.\n *\n * @example\n * ```ts\n * const doc = new LoroDoc();\n * const adapter = createLoroDocAdapter(doc);\n * const transport = new StreamsCrdt({ streamUrl, adapter, auth });\n * ```\n */\nexport function createLoroDocAdapter(\n  doc: LoroDoc,\n): CrdtAdapter<JsonObject> {\n  return {\n    emptyVersion: () => ({}),\n    mergeVersions: (base, incoming) =>\n      mergeDocVersions(base as DocVersionRecord, incoming as DocVersionRecord),\n    exportSnapshot: () => {\n      assertDocAttached(doc);\n      return doc.export({ mode: \"snapshot\" });\n    },\n    applySnapshot: (snapshot) => {\n      assertDocAttached(doc);\n      doc.import(snapshot);\n      return toDocVersionRecord(doc.version());\n    },\n    exportUpdates: (fromVersion) => {\n      assertDocAttached(doc);\n      const currentVersion = toDocVersionRecord(doc.version());\n      if (\n        !hasUpdatesSince(\n          fromVersion as DocVersionRecord,\n          currentVersion,\n        )\n      ) {\n        return undefined;\n      }\n      const updates = [\n        doc.export({\n          mode: \"update\",\n          from: VersionVector.parseJSON(toDocVersionMap(fromVersion)),\n        }),\n      ].filter((update) => update.byteLength > 0);\n      if (updates.length === 0) {\n        return undefined;\n      }\n      let version: DocVersionRecord = {};\n      for (const update of updates) {\n        const next = extractVersionFromUpdate(update);\n        if (next != null) {\n          version = mergeDocVersions(version, next);\n        }\n      }\n      return {\n        updates,\n        version,\n      };\n    },\n    applyRemoteUpdates: (updates, remoterVersion) => {\n      assertDocAttached(doc);\n      if (updates.length > 0) {\n        doc.importBatch(updates);\n      }\n      let version = remoterVersion as DocVersionRecord;\n      for (const update of updates) {\n        const next = extractVersionFromUpdate(update);\n        if (next != null) {\n          version = mergeDocVersions(version, next);\n        }\n      }\n      return version;\n    },\n    subscribeLocalUpdates: (listener) => {\n      assertDocAttached(doc);\n      return doc.subscribeLocalUpdates((update) => {\n        const version = extractVersionFromUpdate(update) ?? {};\n        listener({ updates: [update], version });\n      });\n    },\n  };\n}\n"],"mappings":";;;AAcA,SAAS,mBAAmB,SAA0C;CACpE,MAAM,MAAM,EAAE;AACd,MAAK,MAAM,CAAC,MAAM,YAAY,QAAQ,QAAQ,CAC5C,KAAI,QAAkB;AAExB,QAAO;;AAGT,SAAS,gBAAgB,SAA0C;CACjE,MAAM,sBAAM,IAAI,KAAqB;AACrC,MAAK,MAAM,CAAC,MAAM,YAAY,OAAO,QAAQ,QAAQ,CACnD,KAAI,OAAO,YAAY,YAAY,OAAO,SAAS,QAAQ,CACzD,KAAI,IAAI,MAAgB,QAAQ;AAGpC,QAAO;;AAGT,SAAS,iBACP,MACA,UACkB;CAClB,MAAM,yBAAS,IAAI,KAAqB;AACxC,MAAK,MAAM,CAAC,MAAM,YAAY,OAAO,QAAQ,KAAK,CAChD,QAAO,IAAI,MAAgB,QAAQ;AAErC,MAAK,MAAM,CAAC,MAAM,YAAY,OAAO,QAAQ,SAAS,EAAE;EACtD,MAAM,SAAS;AACf,SAAO,IAAI,QAAQ,KAAK,IAAI,OAAO,IAAI,OAAO,IAAI,GAAG,QAAQ,CAAC;;AAEhE,QAAO,mBAAmB,cAAc,UAAU,OAAO,CAAC;;AAG5D,SAAS,gBACP,aACA,gBACS;AACT,MAAK,MAAM,CAAC,MAAM,YAAY,OAAO,QAAQ,eAAe,CAC1D,KAAI,WAAW,YAAY,SAAmB,GAC5C,QAAO;AAGX,QAAO;;AAGT,SAAS,yBAAyB,QAA6C;AAC7E,KAAI;AAEF,SAAO,mBADM,qBAAqB,QAAQ,MAAM,CACjB,wBAAwB;SACjD;AACN,SAAO;;;AAIX,SAAS,kBAAkB,KAAoB;AAC7C,KAAI,CAAC,IAAI,YAAY,CACnB;AAEF,OAAM,IAAI,MACR,gGAED;;;;;;;;;;;;;;;;AAiBH,SAAgB,qBACd,KACyB;AACzB,QAAO;EACL,qBAAqB,EAAE;EACvB,gBAAgB,MAAM,aACpB,iBAAiB,MAA0B,SAA6B;EAC1E,sBAAsB;AACpB,qBAAkB,IAAI;AACtB,UAAO,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC;;EAEzC,gBAAgB,aAAa;AAC3B,qBAAkB,IAAI;AACtB,OAAI,OAAO,SAAS;AACpB,UAAO,mBAAmB,IAAI,SAAS,CAAC;;EAE1C,gBAAgB,gBAAgB;AAC9B,qBAAkB,IAAI;AAEtB,OACE,CAAC,gBACC,aAHmB,mBAAmB,IAAI,SAAS,CAAC,CAKrD,CAED;GAEF,MAAM,UAAU,CACd,IAAI,OAAO;IACT,MAAM;IACN,MAAM,cAAc,UAAU,gBAAgB,YAAY,CAAC;IAC5D,CAAC,CACH,CAAC,QAAQ,WAAW,OAAO,aAAa,EAAE;AAC3C,OAAI,QAAQ,WAAW,EACrB;GAEF,IAAI,UAA4B,EAAE;AAClC,QAAK,MAAM,UAAU,SAAS;IAC5B,MAAM,OAAO,yBAAyB,OAAO;AAC7C,QAAI,QAAQ,KACV,WAAU,iBAAiB,SAAS,KAAK;;AAG7C,UAAO;IACL;IACA;IACD;;EAEH,qBAAqB,SAAS,mBAAmB;AAC/C,qBAAkB,IAAI;AACtB,OAAI,QAAQ,SAAS,EACnB,KAAI,YAAY,QAAQ;GAE1B,IAAI,UAAU;AACd,QAAK,MAAM,UAAU,SAAS;IAC5B,MAAM,OAAO,yBAAyB,OAAO;AAC7C,QAAI,QAAQ,KACV,WAAU,iBAAiB,SAAS,KAAK;;AAG7C,UAAO;;EAET,wBAAwB,aAAa;AACnC,qBAAkB,IAAI;AACtB,UAAO,IAAI,uBAAuB,WAAW;IAC3C,MAAM,UAAU,yBAAyB,OAAO,IAAI,EAAE;AACtD,aAAS;KAAE,SAAS,CAAC,OAAO;KAAE;KAAS,CAAC;KACxC;;EAEL"}

package/dist/stream-id-1f2mhtmk.d.ts

@@ -0,0 +1,463 @@
+//#region src/checkpoint.d.ts
+/**
+ * Persisted replay progress for one stream.
+ *
+ * This is metadata only — it does **not** contain any CRDT update data.
+ * A persisted cursor is only valid when the caller also restores the matching
+ * local CRDT state before the next `sync()` or `join()`.
+ */
+interface RemoteCursor<TVersion extends JsonObject = JsonObject> {
+  /** Identity of the stream this cursor belongs to. */
+  readonly streamUrl: string;
+  /** The offset to resume reading from on the next sync/join. */
+  readonly nextOffset: string;
+  /** The CRDT version that the server data up to `nextOffset` represents. */
+  readonly serverLowerBoundVersion: TVersion;
+  /** Timestamp (ms) when this cursor was last persisted. */
+  readonly updatedAtMs: number;
+}
+/**
+ * Storage for replay progress metadata.
+ *
+ * A persisted cursor is only valid when the caller also restores the matching
+ * local CRDT state before the next `sync()` or `join()`. Storing only the
+ * cursor can make transport resume from `nextOffset` against an empty local
+ * document, which is not sufficient for delta-only catchup.
+ */
+interface RemoteCursorStore<TVersion extends JsonObject = JsonObject> {
+  load(streamUrl: string): Promise<RemoteCursor<TVersion> | null>;
+  save(cursor: RemoteCursor<TVersion>): Promise<void>;
+  delete?(streamUrl: string): Promise<void>;
+}
+/**
+ * Why the transport is advancing the remote cursor.
+ */
+type RemoteCursorSaveSource = "local" | "remote" | "bootstrap";
+/**
+ * Context passed to durability hooks before a remote cursor is persisted.
+ *
+ * Hooks should make local durable state correspond to `cursor` before this
+ * cursor is stored, so a future process can restore the same CRDT state before
+ * transport resumes from `cursor.nextOffset`.
+ */
+type BeforeRemoteCursorSaveContext<TVersion extends JsonObject = JsonObject> = {
+  readonly cursor: RemoteCursor<TVersion>;
+  readonly source: RemoteCursorSaveSource;
+};
+/**
+ * Hook invoked before the transport persists replay progress.
+ *
+ * This is the place to persist local CRDT payloads or snapshots. If that local
+ * durability step does not happen here, the remote cursor should not advance.
+ */
+type BeforeRemoteCursorSaveHook<TVersion extends JsonObject = JsonObject> = (context: BeforeRemoteCursorSaveContext<TVersion>) => void | Promise<void>;
+/**
+ * Construction options for `IndexedDbRemoteCursorStore`.
+ */
+interface IndexedDbRemoteCursorStoreOptions {
+  readonly dbName?: string;
+  readonly storeName?: string;
+  readonly dbVersion?: number;
+  readonly indexedDb?: IDBFactory;
+}
+/**
+ * In-memory cursor store useful for tests or ephemeral runtimes.
+ */
+declare class InMemoryRemoteCursorStore<TVersion extends JsonObject = JsonObject> implements RemoteCursorStore<TVersion> {
+  private readonly data;
+  load(streamUrl: string): Promise<RemoteCursor<TVersion> | null>;
+  save(cursor: RemoteCursor<TVersion>): Promise<void>;
+  delete(streamUrl: string): Promise<void>;
+}
+/**
+ * IndexedDB-backed cursor store for browser clients that need replay progress persistence.
+ *
+ * This store only persists `RemoteCursor` metadata. It does not persist CRDT
+ * payloads. Use it only when the application also persists the corresponding
+ * local document state and restores that state before calling `sync()` or
+ * `join()` after a reload.
+ */
+declare class IndexedDbRemoteCursorStore<TVersion extends JsonObject = JsonObject> implements RemoteCursorStore<TVersion> {
+  private readonly dbName;
+  private readonly storeName;
+  private readonly dbVersion;
+  private readonly indexedDb;
+  private db;
+  private initPromise;
+  constructor(options?: IndexedDbRemoteCursorStoreOptions);
+  load(streamUrl: string): Promise<RemoteCursor<TVersion> | null>;
+  save(cursor: RemoteCursor<TVersion>): Promise<void>;
+  delete(streamUrl: string): Promise<void>;
+  private ensureDb;
+}
+/**
+ * Creates a cursor value suitable for seeding a `RemoteCursorStore`.
+ */
+declare function createInitialRemoteCursor<TVersion extends JsonObject = JsonObject>(input: {
+  streamUrl: string;
+  nextOffset: string;
+  serverLowerBoundVersion: TVersion;
+}): RemoteCursor<TVersion>;
+//#endregion
+//#region src/reconnect.d.ts
+/**
+ * Retry and timeout settings used by `StreamsCrdt`.
+ */
+interface ReconnectConfig {
+  readonly delays: readonly number[];
+  readonly jitterFraction: number;
+  readonly maxAttempts: number;
+  readonly connectTimeoutMs: number;
+  readonly pollTimeoutMs: number;
+}
+//#endregion
+//#region src/types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type JsonPrimitive = string | number | boolean | null;
+/**
+ * JSON-compatible value type used by transport metadata such as versions and cursors.
+ */
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+/**
+ * JSON object shape used by public transport types.
+ */
+type JsonObject = {
+  readonly [key: string]: JsonValue;
+};
+/**
+ * Authorization source for gateway requests.
+ */
+type StreamsAuthProvider = string | (() => MaybePromise<string | null | undefined>);
+/**
+ * Rust-style result for transport operations that may fail for expected reasons.
+ */
+type Result<T, E> = {
+  readonly ok: true;
+  readonly value: T;
+} | {
+  readonly ok: false;
+  readonly error: E;
+};
+/**
+ * Live subscription state exposed by `join()`.
+ */
+type TransportRoomStatus = "joined" | "reconnecting" | "disconnected" | "error";
+/**
+ * Discriminated error union for `createStream()`, `deleteStream()`, `sync()`, and `join()`.
+ *
+ * - `stream_not_found` — the target stream does not exist (404).
+ * - `auth_failed` — the auth token was rejected (401/403).
+ * - `protocol_error` — unexpected server response or framing error.
+ * - `network_error` — fetch-level failure (DNS, connection refused, etc.).
+ * - `timeout` — connect or poll deadline exceeded.
+ * - `gone` — the server indicated the stream was deleted or moved (410).
+ * - `internal_error` — adapter or runtime logic failed locally.
+ * - `unknown` — catch-all for unexpected errors.
+ */
+type TransportError = {
+  readonly code: "stream_not_found";
+  readonly retryable: false;
+} | {
+  readonly code: "auth_failed";
+  readonly retryable: false;
+  readonly status?: 401 | 403;
+  readonly message: string;
+} | {
+  readonly code: "protocol_error";
+  readonly retryable: false;
+  readonly status?: number;
+  readonly message: string;
+} | {
+  readonly code: "network_error";
+  readonly retryable: true;
+  readonly message: string;
+} | {
+  readonly code: "timeout";
+  readonly retryable: true;
+  readonly phase: "connect" | "poll";
+  readonly message: string;
+} | {
+  readonly code: "gone";
+  readonly retryable: true;
+  readonly message: string;
+} | {
+  readonly code: "internal_error";
+  readonly retryable: false;
+  readonly message: string;
+} | {
+  readonly code: "unknown";
+  readonly retryable: false;
+  readonly message: string;
+};
+/**
+ * Result payload returned by `createStream()`.
+ */
+interface TransportCreateStreamSuccess {
+  readonly created: boolean;
+}
+/**
+ * Result payload returned by `deleteStream()`.
+ */
+interface TransportDeleteStreamSuccess {
+  readonly deleted: boolean;
+}
+/**
+ * Result payload returned by `sync()`.
+ */
+interface TransportSyncSuccess<TVersion extends JsonObject = JsonObject> {
+  readonly cursor: RemoteCursor<TVersion>;
+}
+/**
+ * Optional parameters for a `join()` call.
+ *
+ * `join()` performs an initial sync automatically before entering live mode.
+ * There is no need to call `sync()` before `join()`.
+ */
+interface TransportJoinParams {
+  /**
+   * Called when the live subscription status changes.
+   *
+   * Status flow: `"connecting"` → `"joined"` → (on error) `"reconnecting"` →
+   * `"joined"` or `"disconnected"` or `"error"`.
+   */
+  readonly onStatusChange?: (status: "connecting" | TransportRoomStatus) => void;
+}
+/**
+ * Controls best-effort snapshot uploads scheduled from local writes during `join()`.
+ *
+ * Snapshots are only uploaded during `join()`, never `sync()`. A debounce
+ * window (default 10 s) is refreshed on each local write. If another writer
+ * advances the remote version during that window, the upload is skipped.
+ */
+interface SnapshotUploadOptions {
+  /** Master switch. Defaults to `true` when `snapshotUpload` is provided. */
+  readonly enabled?: boolean;
+  /** Authorization gate — called before each upload attempt. */
+  readonly canUpload: () => MaybePromise<boolean>;
+  /** Debounce window in milliseconds after the last local write. Defaults to 10 000. */
+  readonly debounceMs?: number;
+  /** Minimum byte delta since the last remote snapshot before uploading. */
+  readonly minBytesSinceRemoteSnapshot?: number;
+}
+/**
+ * Active live subscription returned by `join()`.
+ *
+ * The subscription keeps the SSE/long-poll connection alive and forwards
+ * local writes to the server. Call `unsubscribe()` to leave the room.
+ */
+interface TransportSubscription {
+  /** Leaves the live room and stops all background I/O for this subscription. */
+  readonly unsubscribe: () => void;
+  /** Whether the underlying connection is currently open. */
+  readonly connected: boolean;
+  /** Current room status. */
+  readonly status: TransportRoomStatus;
+  /** Registers a status listener. Returns an unsubscribe function. */
+  readonly onStatusChange: (listener: (status: "connecting" | TransportRoomStatus) => void) => () => void;
+}
+/**
+ * Local CRDT updates ready to append to Durable Streams.
+ */
+interface CrdtUpdateBatch<TVersion extends JsonObject> {
+  readonly updates: readonly Uint8Array[];
+  readonly version: TVersion;
+}
+type ExportedCrdtUpdateBatch<TVersion extends JsonObject> = CrdtUpdateBatch<TVersion> | null | undefined;
+/**
+ * Adapter contract between `StreamsCrdt` and a concrete CRDT runtime.
+ */
+interface CrdtAdapter<TVersion extends JsonObject> {
+  /** Returns the zero/empty version for this CRDT type. */
+  emptyVersion(): TVersion;
+  /** Returns the element-wise maximum of two versions. Must be idempotent and commutative. */
+  mergeVersions(base: TVersion, incoming: TVersion): TVersion;
+  /** Exports a full snapshot of the current local CRDT state. */
+  exportSnapshot(): Uint8Array;
+  /** Imports a full snapshot, replacing local state. Returns the version after import. */
+  applySnapshot(snapshot: Uint8Array): MaybePromise<TVersion>;
+  /** Exports incremental updates since `fromVersion`. Returns `null`/`undefined` when there are no new updates. */
+  exportUpdates(fromVersion: TVersion): ExportedCrdtUpdateBatch<TVersion>;
+  /**
+   * Applies remote updates against the local CRDT state.
+   *
+   * `remoterVersion` is the current inferred remote version before applying
+   * `updates`. The return value must be the new inferred remote version after
+   * these updates have been applied.
+   *
+   * Contract: this function must be stable for self-replay. If `updates` only
+   * contain data that is already represented by `remoterVersion` (for example a
+   * transport replay of this writer's own successful append), the returned
+   * version must compare equal to `remoterVersion`. Transport relies on that
+   * invariant to distinguish self-replay from another writer advancing the
+   * remote version.
+   */
+  applyRemoteUpdates(updates: Uint8Array[], remoterVersion: TVersion): MaybePromise<TVersion>;
+  /** Subscribes to local CRDT mutations. Returns an unsubscribe function. */
+  subscribeLocalUpdates(listener: (batch: CrdtUpdateBatch<TVersion>) => void): () => void;
+  /** Optional headers to include when creating the stream (e.g. retention config). */
+  getCreateStreamHeaders?(): MaybePromise<Record<string, string>>;
+}
+/**
+ * Construction options for one `StreamsCrdt` instance.
+ *
+ * Each instance is bound to exactly one stream URL and one local CRDT adapter.
+ */
+interface StreamsCrdtOptions<TVersion extends JsonObject> {
+  /** Full stream URL, typically built with `createStreamUrl()`. */
+  readonly streamUrl: string;
+  /** CRDT adapter for the local document or replica. */
+  readonly adapter: CrdtAdapter<TVersion>;
+  /**
+   * When true, the initial sync/join bootstrap may create the stream on a 404 before retrying.
+   * Defaults to false so missing streams are surfaced explicitly.
+   */
+  readonly createStreamIfMissing?: boolean;
+  readonly auth?: StreamsAuthProvider;
+  readonly fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+  /**
+   * Stores replay progress for this stream.
+   *
+   * Persist this only when the application also persists the matching local
+   * CRDT state and restores it before the next `sync()` or `join()`. Otherwise
+   * transport may resume from deltas against an empty local document.
+   */
+  readonly remoteCursorStore?: RemoteCursorStore<TVersion>;
+  /**
+   * Runs immediately before the remote cursor is persisted.
+   *
+   * Use this to durably persist the local CRDT payload or snapshot that
+   * corresponds to the cursor being saved.
+   */
+  readonly beforeRemoteCursorSave?: BeforeRemoteCursorSaveHook<TVersion>;
+  /**
+   * Same as `beforeRemoteCursorSave`, but allows composing multiple durability
+   * hooks.
+   */
+  readonly beforeRemoteCursorSaveHooks?: ReadonlyArray<BeforeRemoteCursorSaveHook<TVersion>>;
+  readonly snapshotUpload?: SnapshotUploadOptions;
+  readonly reconnectConfig?: Partial<ReconnectConfig>;
+  readonly debug?: boolean;
+}
+interface StreamsCrdtLike<TVersion extends JsonObject> {
+  createStream(): Promise<Result<TransportCreateStreamSuccess, TransportError>>;
+  deleteStream(): Promise<Result<TransportDeleteStreamSuccess, TransportError>>;
+  sync(): Promise<Result<TransportSyncSuccess<TVersion>, TransportError>>;
+  join(params?: TransportJoinParams): Promise<Result<TransportSubscription, TransportError>>;
+  close(): Promise<void>;
+  getSnapshotOffset(): Promise<Result<string | null, TransportError>>;
+  readonly streamUrl: string;
+  readonly adapter: CrdtAdapter<TVersion>;
+  readonly remoteCursorStore: RemoteCursorStore<TVersion>;
+}
+//#endregion
+//#region src/transport-runtime.d.ts
+/**
+ * Durable Streams transport runtime bound to one stream URL and one local CRDT adapter.
+ */
+declare class StreamsCrdt<TVersion extends JsonObject> implements StreamsCrdtLike<TVersion> {
+  readonly streamUrl: string;
+  readonly adapter: CrdtAdapter<TVersion>;
+  readonly remoteCursorStore: RemoteCursorStore<TVersion>;
+  private readonly createStreamIfMissing;
+  private readonly client;
+  private readonly cursorManager;
+  private readonly reconnectConfig;
+  private readonly debug;
+  private readonly beforeRemoteCursorSave?;
+  private readonly snapshotManager;
+  private readonly producerId;
+  private producerEpoch;
+  private nextProducerSeq;
+  private joinState?;
+  private opQueue;
+  /**
+   * Creates a transport for one stream URL and one local adapter instance.
+   */
+  constructor(options: StreamsCrdtOptions<TVersion>);
+  /**
+   * Stops any active live join and releases transport-owned state.
+   */
+  close(): Promise<void>;
+  /**
+   * Reads the latest remote snapshot offset, if the server exposes one.
+   */
+  getSnapshotOffset(): Promise<Result<string | null, TransportError>>;
+  /**
+   * Explicitly creates the target stream.
+   */
+  createStream(): Promise<Result<TransportCreateStreamSuccess, TransportError>>;
+  /**
+   * Deletes the target stream and clears persisted replay state when supported by the cursor store.
+   */
+  deleteStream(): Promise<Result<TransportDeleteStreamSuccess, TransportError>>;
+  /**
+   * Runs one bootstrap/catch-up cycle without entering live mode.
+   */
+  sync(): Promise<Result<TransportSyncSuccess<TVersion>, TransportError>>;
+  /**
+   * Replays remote state, flushes queued local updates, then enters live read mode.
+   */
+  join(params?: TransportJoinParams): Promise<Result<TransportSubscription, TransportError>>;
+  private createSubscription;
+  private disposeJoinState;
+  private startJoin;
+  private syncOnce;
+  private performInitialJoinSync;
+  private bootstrapIntoState;
+  private bootstrapIntoJoinedState;
+  private bootstrapIntoJoinedStateViaSse;
+  private continueJoinedSseSessionUntilCaughtUp;
+  private bootstrapIntoJoinedStateViaLongPoll;
+  private catchup;
+  private appendLocalBatch;
+  private exportUpdates;
+  private applyBootstrapItems;
+  private applyRemoteItems;
+  private runReadLoop;
+  /** Maximum encoded size (bytes) for a single batched append. */
+  private static readonly MAX_BATCH_BYTES;
+  /**
+   * Drain up to `MAX_BATCH_BYTES` worth of queued batches from the front of
+   * `pendingLocal` and merge them into a single `CrdtUpdateBatch`.
+   *
+   * Returns `undefined` when the queue is empty.
+   */
+  private drainPendingBatch;
+  private flushPendingLocal;
+  private saveRemoteCursor;
+  private setJoinStatus;
+  private createStreamRequest;
+  private deleteStreamRequest;
+  private readFromOffsetSseItems;
+  private openBootstrapSseSession;
+  private readBootstrapLongPoll;
+  private readFromOffset;
+  private bootstrap;
+  private readSnapshotOffsetValue;
+  private putSnapshotAt;
+  private appendUpdates;
+  private enqueueExclusive;
+  private logDebug;
+  private logError;
+}
+//#endregion
+//#region src/stream-id.d.ts
+/**
+ * Validates a stream id accepted by `createStreamUrl()`.
+ */
+declare function isValidRillId(id: string): boolean;
+/**
+ * Validates a bucket id accepted by `createStreamUrl()`.
+ */
+declare function isValidBucketId(id: string): boolean;
+/**
+ * Builds a Durable Streams HTTP URL for one `(bucketId, streamId)` pair.
+ */
+declare function createStreamUrl(input: {
+  bucketId: string;
+  streamId: string;
+  baseUrl?: string;
+}): string;
+//#endregion
+export { IndexedDbRemoteCursorStore as C, RemoteCursorStore as D, RemoteCursorSaveSource as E, createInitialRemoteCursor as O, InMemoryRemoteCursorStore as S, RemoteCursor as T, TransportRoomStatus as _, CrdtAdapter as a, BeforeRemoteCursorSaveContext as b, JsonValue as c, StreamsAuthProvider as d, StreamsCrdtOptions as f, TransportJoinParams as g, TransportError as h, StreamsCrdt as i, Result as l, TransportDeleteStreamSuccess as m, isValidBucketId as n, CrdtUpdateBatch as o, TransportCreateStreamSuccess as p, isValidRillId as r, JsonObject as s, createStreamUrl as t, SnapshotUploadOptions as u, TransportSubscription as v, IndexedDbRemoteCursorStoreOptions as w, BeforeRemoteCursorSaveHook as x, TransportSyncSuccess as y };
+//# sourceMappingURL=stream-id-1f2mhtmk.d.ts.map