@loro-dev/streams-crdt 0.7.1 → 0.8.1

package/dist/{stream-id-D0qcbI5c.js → stream-id-CCPEBb6G.js}

@@ -1,211 +1,4 @@
-import { StreamsClient } from "@loro-dev/streams-client";
-//#region src/checkpoint.ts
-function composeBeforeRemoteCursorSaveHooks(...hooks) {
-	const active = hooks.filter((hook) => hook != null);
-	if (active.length === 0) return;
-	return async (context) => {
-		for (const hook of active) await hook(context);
-	};
-}
-async function persistRemoteCursor(input) {
-	const next = {
-		...input.cursor,
-		updatedAtMs: (input.now ?? Date.now)()
-	};
-	if (input.beforeRemoteCursorSave != null) await input.beforeRemoteCursorSave({
-		cursor: next,
-		source: input.source
-	});
-	await input.remoteCursorStore.save(next);
-	return next;
-}
-function key(streamUrl) {
-	return streamUrl;
-}
-function isJsonObject(value) {
-	return typeof value === "object" && value != null && !Array.isArray(value);
-}
-function cloneJsonValue(value) {
-	return structuredClone(value);
-}
-function cloneRemoteCursor(cursor) {
-	return {
-		...cursor,
-		serverLowerBoundVersion: cloneJsonValue(cursor.serverLowerBoundVersion)
-	};
-}
-function fromStoredRemoteCursor(record) {
-	if (!isJsonObject(record.serverLowerBoundVersion)) throw new Error("invalid remote cursor record: serverLowerBoundVersion is not a JSON object");
-	return {
-		streamUrl: record.streamUrl,
-		nextOffset: record.nextOffset,
-		serverLowerBoundVersion: cloneJsonValue(record.serverLowerBoundVersion),
-		updatedAtMs: record.updatedAtMs
-	};
-}
-function toStoredRemoteCursor(cursor) {
-	return {
-		streamUrl: cursor.streamUrl,
-		nextOffset: cursor.nextOffset,
-		serverLowerBoundVersion: cloneJsonValue(cursor.serverLowerBoundVersion),
-		updatedAtMs: cursor.updatedAtMs
-	};
-}
-/**
-* In-memory cursor store useful for tests or ephemeral runtimes.
-*/
-var InMemoryRemoteCursorStore = class {
-	data = /* @__PURE__ */ new Map();
-	async load(streamUrl) {
-		const value = this.data.get(key(streamUrl));
-		return value == null ? null : cloneRemoteCursor(value);
-	}
-	async save(cursor) {
-		this.data.set(key(cursor.streamUrl), cloneRemoteCursor(cursor));
-	}
-	async delete(streamUrl) {
-		this.data.delete(key(streamUrl));
-	}
-};
-const DEFAULT_DB_NAME = "streams-crdt";
-const DEFAULT_STORE_NAME = "remote-cursors";
-const DEFAULT_DB_VERSION = 1;
-/**
-* 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.
-*/
-var IndexedDbRemoteCursorStore = class {
-	dbName;
-	storeName;
-	dbVersion;
-	indexedDb;
-	db = null;
-	initPromise = null;
-	constructor(options) {
-		this.dbName = options?.dbName ?? DEFAULT_DB_NAME;
-		this.storeName = options?.storeName ?? DEFAULT_STORE_NAME;
-		this.dbVersion = options?.dbVersion ?? DEFAULT_DB_VERSION;
-		this.indexedDb = options?.indexedDb ?? globalThis.indexedDB;
-	}
-	async load(streamUrl) {
-		const db = await this.ensureDb();
-		const record = await new Promise((resolve, reject) => {
-			const request = db.transaction([this.storeName], "readonly").objectStore(this.storeName).get(key(streamUrl));
-			request.onsuccess = () => {
-				resolve(request.result ?? null);
-			};
-			request.onerror = () => {
-				reject(request.error ?? /* @__PURE__ */ new Error("indexeddb load failed"));
-			};
-		});
-		return record == null ? null : fromStoredRemoteCursor(record);
-	}
-	async save(cursor) {
-		const db = await this.ensureDb();
-		const record = toStoredRemoteCursor(cursor);
-		await new Promise((resolve, reject) => {
-			const tx = db.transaction([this.storeName], "readwrite");
-			const request = tx.objectStore(this.storeName).put(record, key(cursor.streamUrl));
-			tx.oncomplete = () => resolve();
-			tx.onerror = () => reject(tx.error ?? request.error ?? /* @__PURE__ */ new Error("indexeddb save failed"));
-			tx.onabort = () => reject(tx.error ?? request.error ?? /* @__PURE__ */ new Error("indexeddb save transaction aborted"));
-			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexeddb save failed"));
-		});
-	}
-	async delete(streamUrl) {
-		const db = await this.ensureDb();
-		await new Promise((resolve, reject) => {
-			const tx = db.transaction([this.storeName], "readwrite");
-			const request = tx.objectStore(this.storeName).delete(key(streamUrl));
-			tx.oncomplete = () => resolve();
-			tx.onerror = () => reject(tx.error ?? request.error ?? /* @__PURE__ */ new Error("indexeddb delete failed"));
-			tx.onabort = () => reject(tx.error ?? request.error ?? /* @__PURE__ */ new Error("indexeddb delete transaction aborted"));
-			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexeddb delete failed"));
-		});
-	}
-	async ensureDb() {
-		if (this.db != null) return this.db;
-		if (this.initPromise != null) {
-			await this.initPromise;
-			if (this.db == null) throw new Error("indexeddb is not available");
-			return this.db;
-		}
-		if (this.indexedDb == null) throw new Error("indexeddb is not available in this environment");
-		this.initPromise = new Promise((resolve, reject) => {
-			const request = this.indexedDb.open(this.dbName, this.dbVersion);
-			request.onupgradeneeded = () => {
-				const db = request.result;
-				if (!db.objectStoreNames.contains(this.storeName)) db.createObjectStore(this.storeName);
-			};
-			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexeddb open failed"));
-			request.onsuccess = () => {
-				this.db = request.result;
-				this.db.onversionchange = () => {
-					this.db?.close();
-					this.db = null;
-				};
-				resolve();
-			};
-		}).finally(() => {
-			this.initPromise = null;
-		});
-		await this.initPromise;
-		if (this.db == null) throw new Error("indexeddb open succeeded without a database handle");
-		return this.db;
-	}
-};
-/**
-* Creates a cursor value suitable for seeding a `RemoteCursorStore`.
-*/
-function createInitialRemoteCursor(input) {
-	return {
-		streamUrl: input.streamUrl,
-		nextOffset: input.nextOffset,
-		serverLowerBoundVersion: cloneJsonValue(input.serverLowerBoundVersion),
-		updatedAtMs: Date.now()
-	};
-}
-//#endregion
-//#region src/reconnect.ts
-const DEFAULT_RECONNECT_CONFIG = {
-	delays: [
-		0,
-		500,
-		1e3,
-		2e3,
-		4e3,
-		8e3,
-		15e3
-	],
-	jitterFraction: .2,
-	maxAttempts: Infinity,
-	connectTimeoutMs: 1e4,
-	pollTimeoutMs: 3e4,
-	liveInactivityTimeoutMs: 45e3
-};
-/**
-* Apply jitter of +/- fraction to a base delay.
-* E.g. applyJitter(1000, 0.2) returns a value in [800, 1200].
-*/
-function applyJitter(baseMs, fraction) {
-	if (baseMs === 0) return 0;
-	const jitter = baseMs * fraction * (2 * Math.random() - 1);
-	return Math.max(0, Math.round(baseMs + jitter));
-}
-/**
-* Compute the retry delay for a given attempt number.
-* Uses the delays table from config, clamping at the last entry.
-*/
-function computeRetryDelay(attempt, config = DEFAULT_RECONNECT_CONFIG) {
-	const { delays, jitterFraction } = config;
-	const base = delays[Math.min(attempt, delays.length - 1)];
-	return applyJitter(base, jitterFraction);
-}
-//#endregion
+import { StreamsClient, decodeSsePayload, readSseEvents } from "@loro-dev/streams-client";
 //#region src/deque.ts
 const DEFAULT_COMPACT_THRESHOLD = 64;
 const DEFAULT_MIN_CAPACITY = 16;
@@ -327,6 +120,42 @@ var Deque = class {
 	}
 };
 //#endregion
+//#region src/reconnect.ts
+const DEFAULT_RECONNECT_CONFIG = {
+	delays: [
+		0,
+		500,
+		1e3,
+		2e3,
+		4e3,
+		8e3,
+		15e3
+	],
+	jitterFraction: .2,
+	maxAttempts: Infinity,
+	connectTimeoutMs: 1e4,
+	pollTimeoutMs: 3e4,
+	liveInactivityTimeoutMs: 45e3
+};
+/**
+* Apply jitter of +/- fraction to a base delay.
+* E.g. applyJitter(1000, 0.2) returns a value in [800, 1200].
+*/
+function applyJitter(baseMs, fraction) {
+	if (baseMs === 0) return 0;
+	const jitter = baseMs * fraction * (2 * Math.random() - 1);
+	return Math.max(0, Math.round(baseMs + jitter));
+}
+/**
+* Compute the retry delay for a given attempt number.
+* Uses the delays table from config, clamping at the last entry.
+*/
+function computeRetryDelay(attempt, config = DEFAULT_RECONNECT_CONFIG) {
+	const { delays, jitterFraction } = config;
+	const base = delays[Math.min(attempt, delays.length - 1)];
+	return applyJitter(base, jitterFraction);
+}
+//#endregion
 //#region src/items.ts
 const BINARY_CONTENT_TYPE = "application/octet-stream";
 function encodeItems(items) {
@@ -748,6 +577,23 @@ function sleep(ms, signal) {
 		}, { once: true });
 	});
 }
+function mergeAbortSignals(...signals) {
+	const active = signals.filter((signal) => signal != null);
+	if (active.length === 0) return;
+	if (active.length === 1) return active[0];
+	if (typeof AbortSignal.any === "function") return AbortSignal.any(active);
+	const controller = new AbortController();
+	for (const signal of active) {
+		if (signal.aborted) {
+			controller.abort(signal.reason);
+			break;
+		}
+		signal.addEventListener("abort", () => {
+			controller.abort(signal.reason);
+		}, { once: true });
+	}
+	return controller.signal;
+}
 function classifyFetchError(err) {
 	const message = err instanceof Error ? err.message : String(err);
 	const status = err instanceof HttpError ? err.status : void 0;
@@ -959,7 +805,10 @@ var StreamsTransportClient = class {
 	streamUrl;
 	adapter;
 	client;
+	fetchImpl;
+	authProvider;
 	reconnectConfig;
+	authRefreshInFlight;
 	constructor(options) {
 		this.streamUrl = options.streamUrl;
 		this.adapter = options.adapter;
@@ -973,6 +822,8 @@ var StreamsTransportClient = class {
 				pollTimeoutMs: options.reconnectConfig.pollTimeoutMs
 			}
 		});
+		this.fetchImpl = options.fetchImpl;
+		this.authProvider = options.authProvider;
 		this.reconnectConfig = options.reconnectConfig;
 	}
 	async createStreamRequest() {
@@ -1031,171 +882,836 @@ var StreamsTransportClient = class {
 		const snapshotOffset = result.result.snapshotOffset;
 		return snapshotOffset == null || snapshotOffset.length === 0 ? null : snapshotOffset;
 	}
-	async putSnapshotAt(snapshotOffset, snapshot) {
-		const result = await this.client.putSnapshot({
-			offset: snapshotOffset,
-			part: {
-				contentType: "application/octet-stream",
-				body: snapshot
-			}
+	async putSnapshotAt(snapshotOffset, snapshot) {
+		const result = await this.client.putSnapshot({
+			offset: snapshotOffset,
+			part: {
+				contentType: "application/octet-stream",
+				body: snapshot
+			}
+		});
+		if (!result.ok) throw this.toTransportFailure(result.result);
+	}
+	async appendUpdates(updates, producerSession) {
+		const result = await this.client.append({
+			part: {
+				contentType: BINARY_CONTENT_TYPE,
+				body: encodeItems(updates)
+			},
+			producer: {
+				producerId: producerSession.producerId,
+				epoch: producerSession.producerEpoch,
+				seq: producerSession.nextProducerSeq
+			}
+		});
+		if (result.ok) return {
+			kind: "ok",
+			ackEpoch: result.result.producer?.epoch ?? producerSession.producerEpoch,
+			ackSeq: result.result.producer?.seq ?? producerSession.nextProducerSeq,
+			nextOffset: result.result.nextOffset
+		};
+		const error = result.result;
+		if (error.code === "conflict" && error.detail?.kind === "producer_seq_gap") return {
+			kind: "seq-gap",
+			expectedSeq: error.detail.expectedSeq
+		};
+		if (error.code === "forbidden" && error.detail?.kind === "stale_producer_epoch") return {
+			kind: "stale-epoch",
+			serverEpoch: error.detail.serverEpoch
+		};
+		throw this.toTransportFailure(error);
+	}
+	async appendItems(updates) {
+		const result = await this.client.append({ part: {
+			contentType: BINARY_CONTENT_TYPE,
+			body: encodeItems(updates)
+		} });
+		if (result.ok) return result.result.nextOffset;
+		throw this.toTransportFailure(result.result);
+	}
+	async appendEphemeralUpdate(update, signal) {
+		if (update.byteLength === 0) return;
+		const response = await this.fetchAuthorized(this.streamUrl, {
+			method: "POST",
+			headers: { "Content-Type": BINARY_CONTENT_TYPE },
+			body: update,
+			signal
+		}, this.reconnectConfig.connectTimeoutMs, "connect");
+		if (response.status === 200 || response.status === 204) return;
+		throw await this.responseToEphemeralFailure(response, "ephemeral append");
+	}
+	/**
+	* Opens one bootstrap-first ephemeral SSE session.
+	*
+	* Ephemeral channels intentionally do not expose offsets or control events:
+	* the first event must be `bootstrap`, and all following events must be live
+	* `data` updates.
+	*/
+	async readEphemeralSse(onBootstrap, onData, signal) {
+		const requestUrl = this.ephemeralReadEndpoint();
+		const response = await this.fetchAuthorized(requestUrl, {
+			method: "GET",
+			headers: { Accept: "text/event-stream" },
+			signal
+		}, this.reconnectConfig.connectTimeoutMs, "connect");
+		if (response.status === 404) return { kind: "not-found" };
+		if (!response.ok) {
+			if (response.status === 400) {
+				const message = await response.text();
+				if (isSseUnsupportedErrorText(message)) return { kind: "unsupported" };
+				throw new HttpError(message.length > 0 ? `ephemeral live read failed: ${message}` : "ephemeral live read failed", response.status);
+			}
+			throw await this.responseToEphemeralFailure(response, "ephemeral live read");
+		}
+		if (response.body == null) throw new ProtocolError("ephemeral sse response missing body");
+		if (!(response.headers.get("Content-Type") ?? "").toLowerCase().includes("text/event-stream")) throw new ProtocolError("ephemeral sse response must use text/event-stream content type");
+		const dataEncoding = response.headers.get("Stream-SSE-Data-Encoding") ?? void 0;
+		const consume = async () => {
+			let sawBootstrap = false;
+			for await (const event of readSseEvents(response.body)) {
+				if (!sawBootstrap) {
+					if (event.event !== "bootstrap") throw new ProtocolError(`ephemeral sse must start with bootstrap, got '${event.event}'`);
+					await onBootstrap(decodeSsePayload(event.data, dataEncoding));
+					sawBootstrap = true;
+					continue;
+				}
+				if (event.event === "data") {
+					await onData(decodeSsePayload(event.data, dataEncoding));
+					continue;
+				}
+				throw new ProtocolError(`unexpected ephemeral sse event '${event.event}'`);
+			}
+			if (!sawBootstrap) throw new ProtocolError("ephemeral sse ended before bootstrap");
+			return { kind: "ok" };
+		};
+		let abortHandler;
+		const abortRace = signal != null && !signal.aborted ? new Promise((_, reject) => {
+			abortHandler = () => {
+				response.body?.cancel().catch(() => {});
+				reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+			};
+			signal.addEventListener("abort", abortHandler, { once: true });
+		}) : null;
+		try {
+			if (signal?.aborted) {
+				await response.body.cancel().catch(() => {});
+				throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+			}
+			return abortRace == null ? await consume() : await Promise.race([consume(), abortRace]);
+		} finally {
+			if (abortHandler != null && signal != null) signal.removeEventListener("abort", abortHandler);
+		}
+	}
+	async fetchAuthorized(input, init, timeoutMs, phase) {
+		const firstToken = await this.resolveToken({ reason: "request" });
+		const firstResponse = await this.fetchWithTimeout(input, {
+			...init,
+			headers: this.attachAuthorization(init.headers, firstToken)
+		}, timeoutMs, phase);
+		if (this.authProvider == null || firstResponse.status !== 401 && firstResponse.status !== 403) return firstResponse;
+		await firstResponse.body?.cancel().catch(() => {});
+		const refreshedToken = await this.refreshTokenAfterFailure(firstResponse.status, firstToken);
+		return this.fetchWithTimeout(input, {
+			...init,
+			headers: this.attachAuthorization(init.headers, refreshedToken)
+		}, timeoutMs, phase);
+	}
+	async fetchWithTimeout(input, init, timeoutMs, phase) {
+		const controller = new AbortController();
+		const signal = mergeAbortSignals(init.signal, controller.signal);
+		const timer = setTimeout(() => {
+			controller.abort(new TimeoutError(phase, timeoutMs));
+		}, timeoutMs);
+		try {
+			return await this.fetchImpl(input, {
+				...init,
+				signal
+			});
+		} catch (error) {
+			if (controller.signal.aborted && controller.signal.reason instanceof TimeoutError) throw controller.signal.reason;
+			throw error;
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	async resolveToken(context) {
+		return await this.authProvider?.(context);
+	}
+	async refreshTokenAfterFailure(status, previousToken) {
+		if (this.authProvider == null) return;
+		if (this.authRefreshInFlight == null) this.authRefreshInFlight = this.resolveToken({
+			reason: "unauthorized",
+			status,
+			previousToken
+		}).finally(() => {
+			this.authRefreshInFlight = void 0;
+		});
+		return await this.authRefreshInFlight;
+	}
+	attachAuthorization(base, token) {
+		const headers = new Headers(base);
+		if (token == null || token.length === 0) {
+			headers.delete("Authorization");
+			return headers;
+		}
+		headers.set("Authorization", `Bearer ${token}`);
+		return headers;
+	}
+	async responseToEphemeralFailure(response, context) {
+		const message = await response.text().catch(() => "");
+		return new HttpError(message.length > 0 ? `${context} failed: ${message}` : `${context} failed with status ${response.status}`, response.status);
+	}
+	ephemeralReadEndpoint() {
+		const target = new URL(this.streamUrl);
+		target.searchParams.set("live", "sse");
+		return target.toString();
+	}
+	toTransportFailure(error) {
+		switch (error.code) {
+			case "bad_request":
+			case "unauthorized":
+			case "forbidden":
+			case "not_found":
+			case "conflict":
+			case "gone":
+			case "rate_limited": return new HttpError(error.message, error.status);
+			case "timeout": return new TimeoutError(error.phase, error.phase === "poll" ? this.reconnectConfig.pollTimeoutMs : this.reconnectConfig.connectTimeoutMs);
+			case "network_error": return error.cause instanceof TypeError ? error.cause : new TypeError(error.message);
+			case "protocol_error": return new ProtocolError(error.message, error.status);
+			case "unknown":
+				if (typeof error.status === "number") return new HttpError(error.message, error.status);
+				if (error.cause instanceof TypeError) return error.cause;
+				if (error.cause instanceof Error) return error.cause;
+				return new Error(error.message);
+			default: {
+				const exhaustive = error;
+				return new Error(String(exhaustive));
+			}
+		}
+	}
+	async readItemsSse(initialOffset, cursor, onControl, onOpen, signal, onActivity) {
+		const opened = await this.openItemsSseSession(initialOffset, cursor, onOpen, signal, onActivity);
+		if (opened.kind !== "ok") return opened;
+		let abortHandler;
+		const abortRace = signal != null && !signal.aborted ? new Promise((_, reject) => {
+			abortHandler = () => {
+				opened.session.cancel();
+				reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+			};
+			signal.addEventListener("abort", abortHandler, { once: true });
+		}) : null;
+		try {
+			if (signal?.aborted) {
+				await opened.session.cancel();
+				throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
+			}
+			const result = abortRace != null ? await Promise.race([opened.session.continue(onControl), abortRace]) : await opened.session.continue(onControl);
+			if (result.paused) await opened.session.cancel();
+			return {
+				kind: "ok",
+				latestOffset: result.latestOffset,
+				latestCursor: result.latestCursor
+			};
+		} finally {
+			if (abortHandler != null && signal != null) signal.removeEventListener("abort", abortHandler);
+		}
+	}
+	async openItemsSseSession(initialOffset, cursor, onOpen, signal, onActivity) {
+		const result = await this.client.openSseSession({
+			offset: initialOffset,
+			cursor,
+			signal,
+			onActivity
+		});
+		if (!result.ok) {
+			if (result.result.code === "gone") return { kind: "gone" };
+			if (result.result.code === "not_found") return { kind: "not-found" };
+			if (result.result.code === "bad_request" && isSseUnsupportedErrorText(result.result.message)) return { kind: "unsupported" };
+			throw this.toTransportFailure(result.result);
+		}
+		const session = result.result;
+		onOpen?.();
+		let pendingDataEvents = [];
+		let latestOffset = session.nextOffset ?? initialOffset;
+		let latestCursor = session.cursor;
+		let exhausted = false;
+		return {
+			kind: "ok",
+			session: {
+				continue: async (nextOnControl) => {
+					if (exhausted) return {
+						kind: "ok",
+						latestOffset,
+						latestCursor,
+						paused: false
+					};
+					for await (const event of session.events) {
+						if (event.event === "data") {
+							pendingDataEvents.push(event.data);
+							continue;
+						}
+						if (event.event !== "control") continue;
+						const control = parseSseControlData(event.data);
+						const updates = [];
+						for (const eventData of pendingDataEvents) updates.push(...decodeSseItemPayloads(eventData, session.dataEncoding));
+						pendingDataEvents = [];
+						const handlerResult = await nextOnControl(updates, control.nextOffset, control.upToDate, control.streamCursor);
+						latestOffset = control.nextOffset;
+						if (control.streamCursor != null) latestCursor = control.streamCursor;
+						if (handlerResult === "stop") {
+							exhausted = true;
+							await session.cancel();
+							return {
+								kind: "ok",
+								latestOffset,
+								latestCursor,
+								paused: false
+							};
+						}
+						if (handlerResult === "pause") return {
+							kind: "ok",
+							latestOffset,
+							latestCursor,
+							paused: true
+						};
+					}
+					exhausted = true;
+					return {
+						kind: "ok",
+						latestOffset,
+						latestCursor,
+						paused: false
+					};
+				},
+				cancel: async () => {
+					if (exhausted) return;
+					exhausted = true;
+					await session.cancel();
+				}
+			}
+		};
+	}
+};
+//#endregion
+//#region src/ephemeral-runtime.ts
+function createNoopAdapter() {
+	return {
+		emptyVersion: () => ({}),
+		mergeVersions: (base) => base,
+		exportSnapshot: () => new Uint8Array(),
+		applySnapshot: () => ({}),
+		exportUpdates: () => void 0,
+		applyRemoteUpdates: () => ({}),
+		subscribeLocalUpdates: () => () => void 0
+	};
+}
+function normalizeEphemeralUpdate(update) {
+	if (update == null || update.byteLength === 0) return null;
+	return update;
+}
+function toError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+function closedSubscriptionError() {
+	return /* @__PURE__ */ new Error("subscription closed");
+}
+/**
+* Realtime transport for one ephemeral CRDT stream.
+*
+* This is intentionally separate from `StreamsCrdt`: it bootstraps through
+* the first SSE event, then tails live deltas, and never stores a replay
+* offset, snapshot checkpoint, or remote cursor.
+*/
+var EphemeralStreamCrdt = class {
+	/** Full ephemeral stream URL, including `?ephemeral=` or `?awareness=`. */
+	streamUrl;
+	/** Store-specific adapter used to encode local state and apply remote bytes. */
+	adaptor;
+	/** Low-level HTTP/SSE transport. It is reused only for auth, fetch, and parsing helpers. */
+	client;
+	/** Retry policy shared by the read loop and local write queue. */
+	reconnectConfig;
+	/** Enables diagnostic console errors for failed read/write loops. */
+	debug;
+	/** Current shared subscription state, if the stream is joined. */
+	joinState;
+	constructor(options) {
+		this.streamUrl = options.streamUrl;
+		this.adaptor = options.adaptor;
+		this.reconnectConfig = {
+			...DEFAULT_RECONNECT_CONFIG,
+			...options.reconnectConfig
+		};
+		this.debug = options.debug ?? false;
+		this.client = new StreamsTransportClient({
+			streamUrl: options.streamUrl,
+			adapter: createNoopAdapter(),
+			authProvider: normalizeAuthProvider(options.auth),
+			fetchImpl: options.fetch ?? globalThis.fetch.bind(globalThis),
+			reconnectConfig: this.reconnectConfig
+		});
+	}
+	async join(params) {
+		const existing = this.joinState;
+		if (existing != null) try {
+			await existing.started;
+			return {
+				ok: true,
+				value: this.createSubscription(existing, params)
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: toTransportError(error)
+			};
+		}
+		const state = this.createJoinState();
+		state.started = this.startJoin(state);
+		this.joinState = state;
+		try {
+			await state.started;
+			return {
+				ok: true,
+				value: this.createSubscription(state, params)
+			};
+		} catch (error) {
+			await this.disposeJoinState(state);
+			return {
+				ok: false,
+				error: toTransportError(error)
+			};
+		}
+	}
+	rejoin() {
+		const state = this.joinState;
+		if (state == null || state.closed) return;
+		state.retryAttempt = 0;
+		state.retrySleepController.abort();
+		state.retrySleepController = new AbortController();
+		const previousController = state.requestController;
+		state.requestController = new AbortController();
+		previousController?.abort();
+		if (state.readStatus === "disconnected" || state.readStatus === "error") {
+			this.setReadStatus(state, "reconnecting");
+			this.runReadLoop(state);
+		}
+		if (state.writeStatus === "error") {
+			this.setWriteStatus(state, "reconnecting");
+			this.flushPendingLocal(state);
+		}
+	}
+	async close() {
+		const state = this.joinState;
+		if (state != null) await this.disposeJoinState(state);
+	}
+	createJoinState() {
+		return {
+			refCount: 0,
+			closed: false,
+			status: "connecting",
+			readStatus: "connecting",
+			writeStatus: "connecting",
+			statusListeners: /* @__PURE__ */ new Set(),
+			pendingLocal: new Deque(),
+			syncWaiters: [],
+			flushingLocal: false,
+			retryAttempt: 0,
+			retrySleepController: new AbortController(),
+			firstOpenSettled: false,
+			started: Promise.resolve()
+		};
+	}
+	async startJoin(state) {
+		state.unsubscribeLocal = this.adaptor.subscribeLocalUpdates((update) => {
+			this.enqueueLocal(state, normalizeEphemeralUpdate(update));
+		});
+		state.requestController = new AbortController();
+		const firstOpen = this.waitForFirstOpen(state);
+		this.runReadLoop(state);
+		await firstOpen;
+		if (state.closed) return;
+		this.setWriteStatus(state, "ok");
+		await this.flushPendingLocal(state);
+		if (state.status === "error" || state.status === "disconnected") throw new Error(`ephemeral stream failed to join: ${state.status}`);
+	}
+	waitForFirstOpen(state) {
+		return new Promise((resolve, reject) => {
+			state.firstOpenResolve = resolve;
+			state.firstOpenReject = reject;
+		});
+	}
+	createSubscription(state, params) {
+		state.refCount += 1;
+		const statusListener = params?.onStatusChange;
+		if (statusListener != null) {
+			state.statusListeners.add(statusListener);
+			statusListener(state.status);
+		}
+		let unsubscribed = false;
+		return {
+			unsubscribe: () => {
+				if (unsubscribed) return;
+				unsubscribed = true;
+				if (statusListener != null) state.statusListeners.delete(statusListener);
+				state.refCount = Math.max(0, state.refCount - 1);
+				if (state.refCount === 0 && !state.closed) this.disposeJoinState(state);
+			},
+			get connected() {
+				return state.status === "joined";
+			},
+			get status() {
+				return state.status;
+			},
+			onStatusChange: (listener) => this.onStatusChange(state, listener),
+			waitUntilSynced: async () => {
+				if (state.closed) throw closedSubscriptionError();
+				const remaining = state.pendingLocal.length;
+				if (remaining === 0) return;
+				return new Promise((resolve, reject) => {
+					state.syncWaiters.push({
+						remaining,
+						resolve,
+						reject
+					});
+				});
+			}
+		};
+	}
+	onStatusChange(state, listener) {
+		state.statusListeners.add(listener);
+		listener(state.status);
+		return () => {
+			state.statusListeners.delete(listener);
+		};
+	}
+	async disposeJoinState(state) {
+		if (state.closed) return;
+		state.closed = true;
+		state.unsubscribeLocal?.();
+		state.requestController?.abort();
+		state.retrySleepController.abort();
+		this.rejectFirstOpen(state, closedSubscriptionError());
+		this.rejectSyncWaiters(state, closedSubscriptionError());
+		if (this.joinState === state) this.joinState = void 0;
+	}
+	resolveFirstOpen(state) {
+		if (state.firstOpenSettled) return;
+		state.firstOpenSettled = true;
+		state.firstOpenResolve?.();
+	}
+	rejectFirstOpen(state, error) {
+		if (state.firstOpenSettled) return;
+		state.firstOpenSettled = true;
+		state.firstOpenReject?.(error);
+	}
+	async runReadLoop(state) {
+		while (!state.closed) {
+			state.requestController ??= new AbortController();
+			const capturedController = state.requestController;
+			try {
+				const result = await this.client.readEphemeralSse(async (bootstrap) => {
+					if (bootstrap.byteLength > 0) await this.adaptor.applyRemoteUpdates([bootstrap]);
+					this.setReadStatus(state, "ok");
+					this.resolveFirstOpen(state);
+				}, async (update) => {
+					if (update.byteLength > 0) await this.adaptor.applyRemoteUpdates([update]);
+				}, capturedController.signal);
+				if (state.closed) return;
+				if (result.kind === "ok") {
+					state.retryAttempt = 0;
+					this.setReadStatus(state, "reconnecting");
+					await sleep(0);
+					continue;
+				}
+				if (result.kind === "unsupported") throw new Error("ephemeral stream requires SSE support");
+				if (result.kind === "not-found") throw new HttpError("ephemeral stream not found", 404);
+			} catch (error) {
+				if (state.closed) return;
+				if (capturedController.signal.aborted) {
+					state.requestController = new AbortController();
+					this.setReadStatus(state, "reconnecting");
+					continue;
+				}
+				const classified = classifyFetchError(error);
+				if (!classified.retriable || isAuthOrProtocolError(error)) {
+					this.logError("ephemeral live read failed", error, {
+						streamUrl: this.streamUrl,
+						code: classified.code
+					});
+					this.setReadStatus(state, "error");
+					this.rejectFirstOpen(state, toError(error));
+					return;
+				}
+				this.setReadStatus(state, "reconnecting");
+				if (state.retryAttempt >= this.reconnectConfig.maxAttempts) {
+					this.logError("ephemeral live reconnect exhausted", error, {
+						streamUrl: this.streamUrl,
+						attempts: state.retryAttempt
+					});
+					this.setReadStatus(state, "disconnected");
+					this.rejectFirstOpen(state, toError(error));
+					return;
+				}
+				const delay = computeRetryDelay(state.retryAttempt, this.reconnectConfig);
+				state.retryAttempt += 1;
+				await sleep(delay, state.retrySleepController.signal);
+			}
+		}
+	}
+	enqueueLocal(state, update) {
+		if (state.closed || update == null || update.byteLength === 0) return;
+		state.pendingLocal.pushBack(update);
+		if (state.writeStatus !== "connecting") this.flushPendingLocal(state);
+	}
+	async flushPendingLocal(state) {
+		if (state.flushingLocal || state.closed) return;
+		state.flushingLocal = true;
+		try {
+			while (!state.closed) {
+				const update = state.pendingLocal.peekFront();
+				if (update == null) return;
+				let attempt = 0;
+				while (!state.closed) try {
+					await this.client.appendEphemeralUpdate(update);
+					state.pendingLocal.popFront();
+					this.notifySyncWaiters(state, 1);
+					this.setWriteStatus(state, "ok");
+					break;
+				} catch (error) {
+					const classified = classifyFetchError(error);
+					if (!classified.retriable || isAuthOrProtocolError(error)) {
+						this.rejectSyncWaiters(state, /* @__PURE__ */ new Error(`ephemeral append failed: ${classified.code}`));
+						this.setWriteStatus(state, "error");
+						return;
+					}
+					if (attempt >= this.reconnectConfig.maxAttempts) {
+						this.rejectSyncWaiters(state, /* @__PURE__ */ new Error("ephemeral append retry budget exhausted"));
+						this.setWriteStatus(state, "error");
+						return;
+					}
+					this.setWriteStatus(state, "reconnecting");
+					const delay = computeRetryDelay(attempt, this.reconnectConfig);
+					attempt += 1;
+					await sleep(delay, state.retrySleepController.signal);
+				}
+			}
+		} finally {
+			state.flushingLocal = false;
+		}
+	}
+	notifySyncWaiters(state, flushedCount) {
+		let i = 0;
+		while (i < state.syncWaiters.length) {
+			const waiter = state.syncWaiters[i];
+			waiter.remaining -= flushedCount;
+			if (waiter.remaining <= 0) {
+				state.syncWaiters.splice(i, 1);
+				waiter.resolve();
+			} else i += 1;
+		}
+	}
+	rejectSyncWaiters(state, error) {
+		for (const waiter of state.syncWaiters.splice(0)) waiter.reject(error);
+	}
+	setReadStatus(state, readStatus) {
+		if (state.readStatus === readStatus) return;
+		state.readStatus = readStatus;
+		this.recomputeStatus(state);
+	}
+	setWriteStatus(state, writeStatus) {
+		if (state.writeStatus === writeStatus) return;
+		state.writeStatus = writeStatus;
+		this.recomputeStatus(state);
+	}
+	recomputeStatus(state) {
+		const status = this.computeStatus(state);
+		if (state.status === status) return;
+		state.status = status;
+		for (const listener of state.statusListeners) listener(status);
+	}
+	computeStatus(state) {
+		if (state.readStatus === "error" || state.writeStatus === "error") return "error";
+		if (state.readStatus === "disconnected") return "disconnected";
+		if (state.readStatus === "connecting" || state.writeStatus === "connecting") return "connecting";
+		if (state.readStatus === "reconnecting" || state.writeStatus === "reconnecting") return "reconnecting";
+		return "joined";
+	}
+	logError(message, error, detail) {
+		if (!this.debug) return;
+		console.error(`[streams-crdt] ${message}`, error, detail);
+	}
+};
+//#endregion
+//#region src/checkpoint.ts
+function composeBeforeRemoteCursorSaveHooks(...hooks) {
+	const active = hooks.filter((hook) => hook != null);
+	if (active.length === 0) return;
+	return async (context) => {
+		for (const hook of active) await hook(context);
+	};
+}
+async function persistRemoteCursor(input) {
+	const next = {
+		...input.cursor,
+		updatedAtMs: (input.now ?? Date.now)()
+	};
+	if (input.beforeRemoteCursorSave != null) await input.beforeRemoteCursorSave({
+		cursor: next,
+		source: input.source
+	});
+	await input.remoteCursorStore.save(next);
+	return next;
+}
+function key(streamUrl) {
+	return streamUrl;
+}
+function isJsonObject(value) {
+	return typeof value === "object" && value != null && !Array.isArray(value);
+}
+function cloneJsonValue(value) {
+	return structuredClone(value);
+}
+function cloneRemoteCursor(cursor) {
+	return {
+		...cursor,
+		serverLowerBoundVersion: cloneJsonValue(cursor.serverLowerBoundVersion)
+	};
+}
+function fromStoredRemoteCursor(record) {
+	if (!isJsonObject(record.serverLowerBoundVersion)) throw new Error("invalid remote cursor record: serverLowerBoundVersion is not a JSON object");
+	return {
+		streamUrl: record.streamUrl,
+		nextOffset: record.nextOffset,
+		serverLowerBoundVersion: cloneJsonValue(record.serverLowerBoundVersion),
+		updatedAtMs: record.updatedAtMs
+	};
+}
+function toStoredRemoteCursor(cursor) {
+	return {
+		streamUrl: cursor.streamUrl,
+		nextOffset: cursor.nextOffset,
+		serverLowerBoundVersion: cloneJsonValue(cursor.serverLowerBoundVersion),
+		updatedAtMs: cursor.updatedAtMs
+	};
+}
+/**
+* In-memory cursor store useful for tests or ephemeral runtimes.
+*/
+var InMemoryRemoteCursorStore = class {
+	data = /* @__PURE__ */ new Map();
+	async load(streamUrl) {
+		const value = this.data.get(key(streamUrl));
+		return value == null ? null : cloneRemoteCursor(value);
+	}
+	async save(cursor) {
+		this.data.set(key(cursor.streamUrl), cloneRemoteCursor(cursor));
+	}
+	async delete(streamUrl) {
+		this.data.delete(key(streamUrl));
+	}
+};
+const DEFAULT_DB_NAME = "streams-crdt";
+const DEFAULT_STORE_NAME = "remote-cursors";
+const DEFAULT_DB_VERSION = 1;
+/**
+* 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.
+*/
+var IndexedDbRemoteCursorStore = class {
+	dbName;
+	storeName;
+	dbVersion;
+	indexedDb;
+	db = null;
+	initPromise = null;
+	constructor(options) {
+		this.dbName = options?.dbName ?? DEFAULT_DB_NAME;
+		this.storeName = options?.storeName ?? DEFAULT_STORE_NAME;
+		this.dbVersion = options?.dbVersion ?? DEFAULT_DB_VERSION;
+		this.indexedDb = options?.indexedDb ?? globalThis.indexedDB;
+	}
+	async load(streamUrl) {
+		const db = await this.ensureDb();
+		const record = await new Promise((resolve, reject) => {
+			const request = db.transaction([this.storeName], "readonly").objectStore(this.storeName).get(key(streamUrl));
+			request.onsuccess = () => {
+				resolve(request.result ?? null);
+			};
+			request.onerror = () => {
+				reject(request.error ?? /* @__PURE__ */ new Error("indexeddb load failed"));
+			};
 		});
-		if (!result.ok) throw this.toTransportFailure(result.result);
+		return record == null ? null : fromStoredRemoteCursor(record);
 	}
-	async appendUpdates(updates, producerSession) {
-		const result = await this.client.append({
-			part: {
-				contentType: BINARY_CONTENT_TYPE,
-				body: encodeItems(updates)
-			},
-			producer: {
-				producerId: producerSession.producerId,
-				epoch: producerSession.producerEpoch,
-				seq: producerSession.nextProducerSeq
-			}
+	async save(cursor) {
+		const db = await this.ensureDb();
+		const record = toStoredRemoteCursor(cursor);
+		await new Promise((resolve, reject) => {
+			const tx = db.transaction([this.storeName], "readwrite");
+			const request = tx.objectStore(this.storeName).put(record, key(cursor.streamUrl));
+			tx.oncomplete = () => resolve();
+			tx.onerror = () => reject(tx.error ?? request.error ?? /* @__PURE__ */ new Error("indexeddb save failed"));
+			tx.onabort = () => reject(tx.error ?? request.error ?? /* @__PURE__ */ new Error("indexeddb save transaction aborted"));
+			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexeddb save failed"));
 		});
-		if (result.ok) return {
-			kind: "ok",
-			ackEpoch: result.result.producer?.epoch ?? producerSession.producerEpoch,
-			ackSeq: result.result.producer?.seq ?? producerSession.nextProducerSeq,
-			nextOffset: result.result.nextOffset
-		};
-		const error = result.result;
-		if (error.code === "conflict" && error.detail?.kind === "producer_seq_gap") return {
-			kind: "seq-gap",
-			expectedSeq: error.detail.expectedSeq
-		};
-		if (error.code === "forbidden" && error.detail?.kind === "stale_producer_epoch") return {
-			kind: "stale-epoch",
-			serverEpoch: error.detail.serverEpoch
-		};
-		throw this.toTransportFailure(error);
 	}
-	toTransportFailure(error) {
-		switch (error.code) {
-			case "bad_request":
-			case "unauthorized":
-			case "forbidden":
-			case "not_found":
-			case "conflict":
-			case "gone":
-			case "rate_limited": return new HttpError(error.message, error.status);
-			case "timeout": return new TimeoutError(error.phase, error.phase === "poll" ? this.reconnectConfig.pollTimeoutMs : this.reconnectConfig.connectTimeoutMs);
-			case "network_error": return error.cause instanceof TypeError ? error.cause : new TypeError(error.message);
-			case "protocol_error": return new ProtocolError(error.message, error.status);
-			case "unknown":
-				if (typeof error.status === "number") return new HttpError(error.message, error.status);
-				if (error.cause instanceof TypeError) return error.cause;
-				if (error.cause instanceof Error) return error.cause;
-				return new Error(error.message);
-			default: {
-				const exhaustive = error;
-				return new Error(String(exhaustive));
-			}
-		}
+	async delete(streamUrl) {
+		const db = await this.ensureDb();
+		await new Promise((resolve, reject) => {
+			const tx = db.transaction([this.storeName], "readwrite");
+			const request = tx.objectStore(this.storeName).delete(key(streamUrl));
+			tx.oncomplete = () => resolve();
+			tx.onerror = () => reject(tx.error ?? request.error ?? /* @__PURE__ */ new Error("indexeddb delete failed"));
+			tx.onabort = () => reject(tx.error ?? request.error ?? /* @__PURE__ */ new Error("indexeddb delete transaction aborted"));
+			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexeddb delete failed"));
+		});
 	}
-	async readItemsSse(initialOffset, cursor, onControl, onOpen, signal, onActivity) {
-		const opened = await this.openItemsSseSession(initialOffset, cursor, onOpen, signal, onActivity);
-		if (opened.kind !== "ok") return opened;
-		let abortHandler;
-		const abortRace = signal != null && !signal.aborted ? new Promise((_, reject) => {
-			abortHandler = () => {
-				opened.session.cancel();
-				reject(signal.reason ?? new DOMException("The operation was aborted.", "AbortError"));
+	async ensureDb() {
+		if (this.db != null) return this.db;
+		if (this.initPromise != null) {
+			await this.initPromise;
+			if (this.db == null) throw new Error("indexeddb is not available");
+			return this.db;
+		}
+		if (this.indexedDb == null) throw new Error("indexeddb is not available in this environment");
+		this.initPromise = new Promise((resolve, reject) => {
+			const request = this.indexedDb.open(this.dbName, this.dbVersion);
+			request.onupgradeneeded = () => {
+				const db = request.result;
+				if (!db.objectStoreNames.contains(this.storeName)) db.createObjectStore(this.storeName);
 			};
-			signal.addEventListener("abort", abortHandler, { once: true });
-		}) : null;
-		try {
-			if (signal?.aborted) {
-				await opened.session.cancel();
-				throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
-			}
-			const result = abortRace != null ? await Promise.race([opened.session.continue(onControl), abortRace]) : await opened.session.continue(onControl);
-			if (result.paused) await opened.session.cancel();
-			return {
-				kind: "ok",
-				latestOffset: result.latestOffset,
-				latestCursor: result.latestCursor
+			request.onerror = () => reject(request.error ?? /* @__PURE__ */ new Error("indexeddb open failed"));
+			request.onsuccess = () => {
+				this.db = request.result;
+				this.db.onversionchange = () => {
+					this.db?.close();
+					this.db = null;
+				};
+				resolve();
 			};
-		} finally {
-			if (abortHandler != null && signal != null) signal.removeEventListener("abort", abortHandler);
-		}
-	}
-	async openItemsSseSession(initialOffset, cursor, onOpen, signal, onActivity) {
-		const result = await this.client.openSseSession({
-			offset: initialOffset,
-			cursor,
-			signal,
-			onActivity
+		}).finally(() => {
+			this.initPromise = null;
 		});
-		if (!result.ok) {
-			if (result.result.code === "gone") return { kind: "gone" };
-			if (result.result.code === "not_found") return { kind: "not-found" };
-			if (result.result.code === "bad_request" && isSseUnsupportedErrorText(result.result.message)) return { kind: "unsupported" };
-			throw this.toTransportFailure(result.result);
-		}
-		const session = result.result;
-		onOpen?.();
-		let pendingDataEvents = [];
-		let latestOffset = session.nextOffset ?? initialOffset;
-		let latestCursor = session.cursor;
-		let exhausted = false;
-		return {
-			kind: "ok",
-			session: {
-				continue: async (nextOnControl) => {
-					if (exhausted) return {
-						kind: "ok",
-						latestOffset,
-						latestCursor,
-						paused: false
-					};
-					for await (const event of session.events) {
-						if (event.event === "data") {
-							pendingDataEvents.push(event.data);
-							continue;
-						}
-						if (event.event !== "control") continue;
-						const control = parseSseControlData(event.data);
-						const updates = [];
-						for (const eventData of pendingDataEvents) updates.push(...decodeSseItemPayloads(eventData, session.dataEncoding));
-						pendingDataEvents = [];
-						const handlerResult = await nextOnControl(updates, control.nextOffset, control.upToDate, control.streamCursor);
-						latestOffset = control.nextOffset;
-						if (control.streamCursor != null) latestCursor = control.streamCursor;
-						if (handlerResult === "stop") {
-							exhausted = true;
-							await session.cancel();
-							return {
-								kind: "ok",
-								latestOffset,
-								latestCursor,
-								paused: false
-							};
-						}
-						if (handlerResult === "pause") return {
-							kind: "ok",
-							latestOffset,
-							latestCursor,
-							paused: true
-						};
-					}
-					exhausted = true;
-					return {
-						kind: "ok",
-						latestOffset,
-						latestCursor,
-						paused: false
-					};
-				},
-				cancel: async () => {
-					if (exhausted) return;
-					exhausted = true;
-					await session.cancel();
-				}
-			}
-		};
+		await this.initPromise;
+		if (this.db == null) throw new Error("indexeddb open succeeded without a database handle");
+		return this.db;
 	}
 };
+/**
+* Creates a cursor value suitable for seeding a `RemoteCursorStore`.
+*/
+function createInitialRemoteCursor(input) {
+	return {
+		streamUrl: input.streamUrl,
+		nextOffset: input.nextOffset,
+		serverLowerBoundVersion: cloneJsonValue(input.serverLowerBoundVersion),
+		updatedAtMs: Date.now()
+	};
+}
 //#endregion
 //#region src/transport-cursor.ts
 var TransportCursorManager = class {
@@ -1462,6 +1978,8 @@ var StreamsCrdt = class StreamsCrdt {
 	producerId = createProducerId();
 	producerEpoch = 0;
 	nextProducerSeq = 0;
+	frozenLocalAppend;
+	committedPendingCount;
 	pendingWriteOnly = new Deque();
 	writeOnlyCursor;
 	unsubscribeWriteOnlyLocal;
@@ -1671,6 +2189,8 @@ var StreamsCrdt = class StreamsCrdt {
 					await this.remoteCursorStore.delete?.(this.streamUrl);
 					this.producerEpoch = 0;
 					this.nextProducerSeq = 0;
+					this.frozenLocalAppend = void 0;
+					this.committedPendingCount = void 0;
 					return deleted;
 				}) }
 			};
@@ -1718,15 +2238,17 @@ var StreamsCrdt = class StreamsCrdt {
 						localVersion: this.writeOnlyCursor.serverLowerBoundVersion
 					}
 				};
-				const nextCursor = await this.appendLocalBatch(this.writeOnlyCursor, drained.batch, false);
-				for (let i = 0; i < drained.count; i += 1) this.pendingWriteOnly.popFront();
-				this.writeOnlyCursor = nextCursor;
+				const appended = await this.appendLocalBatchRemote(this.writeOnlyCursor, drained.batch, drained.count, "write-only");
+				const committedCount = appended.pendingCount ?? drained.count;
+				for (let i = 0; i < committedCount; i += 1) this.pendingWriteOnly.popFront();
+				this.writeOnlyCursor = appended.cursor;
+				this.commitProducerAck(appended.producerAck);
 				return {
 					ok: true,
 					value: {
 						appended: true,
-						nextOffset: nextCursor.nextOffset,
-						localVersion: nextCursor.serverLowerBoundVersion
+						nextOffset: appended.cursor.nextOffset,
+						localVersion: appended.cursor.serverLowerBoundVersion
 					}
 				};
 			} catch (error) {
@@ -1902,7 +2424,7 @@ var StreamsCrdt = class StreamsCrdt {
 		}
 	}
 	async syncOnce() {
-		let cursor = (await this.resolveInitialRemoteState()).cursor;
+		let cursor = (await this.finalizeDirectLocalAppendIfNeeded(await this.resolveInitialRemoteState())).cursor;
 		const localBatch = this.exportUpdates(cursor.serverLowerBoundVersion);
 		if (localBatch.batch != null) {
 			cursor = await this.appendLocalBatch(cursor, localBatch.batch);
@@ -1911,7 +2433,7 @@ var StreamsCrdt = class StreamsCrdt {
 		return cursor;
 	}
 	async performInitialJoinSync(preferredLiveMode) {
-		const initial = await this.resolveInitialRemoteState();
+		const initial = await this.finalizeDirectLocalAppendIfNeeded(await this.resolveInitialRemoteState());
 		let cursor = initial.cursor;
 		let localExportRefVersion = cursor.serverLowerBoundVersion;
 		let streamCursor = initial.streamCursor;
@@ -2007,17 +2529,52 @@ var StreamsCrdt = class StreamsCrdt {
 			};
 		}
 	}
-	async appendLocalBatch(cursor, batch, persist = true) {
-		let producerSession = {
-			producerId: this.producerId,
-			producerEpoch: this.producerEpoch,
-			nextProducerSeq: this.nextProducerSeq
+	async appendLocalBatch(cursor, batch, pendingCount) {
+		const source = pendingCount == null ? "direct" : "pending";
+		const committed = await this.appendLocalBatchDurably(cursor, batch, pendingCount, source);
+		this.committedPendingCount = committed.pendingCount;
+		return committed.cursor;
+	}
+	async appendLocalBatchDurably(cursor, batch, pendingCount, source = pendingCount == null ? "direct" : "pending") {
+		const frozen = await this.getOrCreateFrozenLocalAppend(cursor, batch, pendingCount, source);
+		const appended = await this.appendFrozenLocalBatchRemote(frozen);
+		const saved = await this.saveRemoteCursor(appended.cursor, "local");
+		this.commitProducerAck(appended.producerAck);
+		return {
+			cursor: saved,
+			pendingCount: frozen.pendingCount
+		};
+	}
+	async appendLocalBatchRemote(cursor, batch, pendingCount, source = pendingCount == null ? "direct" : "pending") {
+		const frozen = await this.getOrCreateFrozenLocalAppend(cursor, batch, pendingCount, source);
+		return {
+			...await this.appendFrozenLocalBatchRemote(frozen),
+			pendingCount: frozen.pendingCount
+		};
+	}
+	async getOrCreateFrozenLocalAppend(cursor, batch, pendingCount, source = pendingCount == null ? "direct" : "pending") {
+		const existing = this.frozenLocalAppend;
+		if (existing != null) {
+			if (existing.source !== source) throw new Error(`${existing.source} local append must be finalized before ${source} append`);
+			return existing;
+		}
+		const frozen = {
+			source,
+			baseCursor: cursor,
+			batch,
+			pendingCount,
+			wireUpdates: this.encodeUpdateItems == null ? batch.updates : await this.encodeUpdateItems(batch.updates),
+			producerSession: this.createCurrentProducerSession()
 		};
+		this.frozenLocalAppend = frozen;
+		return frozen;
+	}
+	async appendFrozenLocalBatchRemote(frozen) {
+		if (frozen.acknowledged != null) return frozen.acknowledged;
 		for (let attempt = 0; attempt < 3; attempt += 1) {
 			let result;
 			try {
-				const wireUpdates = this.encodeUpdateItems == null ? batch.updates : await this.encodeUpdateItems(batch.updates);
-				result = await this.client.appendUpdates(wireUpdates, producerSession);
+				result = await this.client.appendUpdates(frozen.wireUpdates, frozen.producerSession);
 			} catch (error) {
 				if (isStreamNotFoundError(error) && this.createStreamIfMissing) {
 					await this.ensureStreamExists();
@@ -2026,30 +2583,66 @@ var StreamsCrdt = class StreamsCrdt {
 				throw error;
 			}
 			if (result.kind === "ok") {
-				this.producerEpoch = result.ackEpoch;
-				this.nextProducerSeq = result.ackSeq + 1;
-				const next = {
-					...cursor,
-					nextOffset: result.nextOffset,
-					serverLowerBoundVersion: this.adapter.mergeVersions(cursor.serverLowerBoundVersion, batch.version)
+				const appended = {
+					cursor: {
+						...frozen.baseCursor,
+						nextOffset: result.nextOffset,
+						serverLowerBoundVersion: this.adapter.mergeVersions(frozen.baseCursor.serverLowerBoundVersion, frozen.batch.version)
+					},
+					producerAck: {
+						epoch: result.ackEpoch,
+						seq: result.ackSeq
+					}
 				};
-				return persist ? await this.saveRemoteCursor(next, "local") : next;
+				frozen.acknowledged = appended;
+				return appended;
 			}
 			if (result.kind === "seq-gap") {
-				producerSession = {
-					...producerSession,
+				frozen.producerSession = {
+					...frozen.producerSession,
 					nextProducerSeq: result.expectedSeq
 				};
 				continue;
 			}
-			producerSession = {
-				...producerSession,
+			frozen.producerSession = {
+				...frozen.producerSession,
 				producerEpoch: result.serverEpoch + 1,
 				nextProducerSeq: 0
 			};
 		}
 		throw new Error("append retry budget exhausted");
 	}
+	async finalizeDirectLocalAppendIfNeeded(state) {
+		const frozen = this.frozenLocalAppend;
+		if (frozen == null || frozen.pendingCount != null) return state;
+		const appended = await this.appendFrozenLocalBatchRemote(frozen);
+		const saved = await this.saveRemoteCursor(appended.cursor, "local");
+		this.commitProducerAck(appended.producerAck);
+		return await this.catchup(saved, void 0, state.streamCursor);
+	}
+	createCurrentProducerSession() {
+		return {
+			producerId: this.producerId,
+			producerEpoch: this.producerEpoch,
+			nextProducerSeq: this.nextProducerSeq
+		};
+	}
+	commitProducerAck(ack) {
+		this.producerEpoch = ack.epoch;
+		this.nextProducerSeq = ack.seq + 1;
+		this.frozenLocalAppend = void 0;
+	}
+	abandonFrozenLocalAppend(frozen) {
+		if (this.frozenLocalAppend !== frozen) return;
+		this.frozenLocalAppend = void 0;
+		this.producerEpoch = Math.max(this.producerEpoch, frozen.producerSession.producerEpoch + 1);
+		this.nextProducerSeq = 0;
+	}
+	consumeCommittedPendingCount() {
+		const count = this.committedPendingCount;
+		this.committedPendingCount = void 0;
+		return count;
+	}
 	/**
 	* Ensures the target stream exists, creating it if necessary.
 	* Tolerates 409 Conflict (stream already created concurrently).
@@ -2097,9 +2690,17 @@ var StreamsCrdt = class StreamsCrdt {
 	*/
 	async inferRemoteAndAppendLocal(bootstrapCursor, cursorManager) {
 		const inferredRemote = await this.bootstrapState(bootstrapCursor, { cursorManager });
-		const localBatch = this.exportUpdates(inferredRemote.cursor.serverLowerBoundVersion);
-		if (localBatch.batch != null) await this.appendLocalBatch(inferredRemote.cursor, localBatch.batch, false);
-		return await this.bootstrapState(bootstrapCursor);
+		let pendingAppend;
+		if (this.frozenLocalAppend != null) {
+			if (this.frozenLocalAppend.pendingCount != null) throw new Error("pending local append must be finalized by pending flush");
+			pendingAppend = await this.appendFrozenLocalBatchRemote(this.frozenLocalAppend);
+		} else {
+			const localBatch = this.exportUpdates(inferredRemote.cursor.serverLowerBoundVersion);
+			if (localBatch.batch != null) pendingAppend = await this.appendLocalBatchRemote(inferredRemote.cursor, localBatch.batch);
+		}
+		const result = await this.bootstrapState(bootstrapCursor);
+		if (pendingAppend != null) this.commitProducerAck(pendingAppend.producerAck);
+		return result;
 	}
 	async recoverFromGoneWithLocalBootstrap(cursor) {
 		const isolatedCursorManager = await this.createIsolatedCursorManager();
@@ -2115,9 +2716,17 @@ var StreamsCrdt = class StreamsCrdt {
 			const inferredRemote = await this.bootstrapState(bootstrapCursor, { cursorManager: this.volatileCursorManager });
 			await this.adapter.applySnapshot(preservedLocalSnapshot);
 			restoredLocalSnapshot = true;
-			const localBatch = this.exportUpdates(inferredRemote.cursor.serverLowerBoundVersion);
-			if (localBatch.batch != null) await this.appendLocalBatch(inferredRemote.cursor, localBatch.batch, false);
-			return await this.bootstrapState(bootstrapCursor);
+			let pendingAppend;
+			if (this.frozenLocalAppend != null) {
+				if (this.frozenLocalAppend.pendingCount != null) throw new Error("pending local append must be finalized by pending flush");
+				pendingAppend = await this.appendFrozenLocalBatchRemote(this.frozenLocalAppend);
+			} else {
+				const localBatch = this.exportUpdates(inferredRemote.cursor.serverLowerBoundVersion);
+				if (localBatch.batch != null) pendingAppend = await this.appendLocalBatchRemote(inferredRemote.cursor, localBatch.batch);
+			}
+			const result = await this.bootstrapState(bootstrapCursor);
+			if (pendingAppend != null) this.commitProducerAck(pendingAppend.producerAck);
+			return result;
 		} catch (error) {
 			if (!restoredLocalSnapshot) await this.adapter.applySnapshot(preservedLocalSnapshot);
 			throw error;
@@ -2332,7 +2941,6 @@ var StreamsCrdt = class StreamsCrdt {
 		let mergedVersion = first.version;
 		const allUpdates = Array.from(first.updates);
 		let count = 1;
-		await this.measureAppendBodyByteLength(allUpdates);
 		while (count < pendingLocal.length) {
 			const next = pendingLocal.at(count);
 			const candidateUpdates = [...allUpdates, ...next.updates];
@@ -2368,9 +2976,10 @@ var StreamsCrdt = class StreamsCrdt {
 				if (drained == null) return;
 				let attempts = 0;
 				while (!state.closed) try {
-					state.cursor = await this.enqueueExclusive(async () => this.appendLocalBatch(state.cursor, drained.batch));
-					for (let i = 0; i < drained.count; i += 1) state.pendingLocal.popFront();
-					this.notifySyncWaiters(state, drained.count);
+					state.cursor = await this.enqueueExclusive(async () => this.appendLocalBatch(state.cursor, drained.batch, drained.count));
+					const committedCount = this.consumeCommittedPendingCount() ?? drained.count;
+					for (let i = 0; i < committedCount; i += 1) state.pendingLocal.popFront();
+					this.notifySyncWaiters(state, committedCount);
 					this.setWriteSubStatus(state, "ok");
 					this.snapshotManager.schedule(state);
 					break;
@@ -2465,6 +3074,8 @@ var StreamsCrdt = class StreamsCrdt {
 		return updates.reduce((sum, update) => sum + 4 + update.byteLength, 0);
 	}
 	disableWriteOnlyMode(reason) {
+		const frozen = this.frozenLocalAppend;
+		if (frozen?.source === "write-only") this.abandonFrozenLocalAppend(frozen);
 		if (this.writeOnlyDisabledReason != null) return;
 		this.writeOnlyDisabledReason = reason;
 		this.pendingWriteOnly.clear();
@@ -2522,6 +3133,6 @@ function createStreamUrl(input) {
 	return `${baseUrl}/ds/${encodeURIComponent(input.bucketId)}/${encodeURIComponent(streamId)}`;
 }
 //#endregion
-export { PayloadProtectionError as a, createInitialRemoteCursor as c, StreamsCrdt as i, isValidBucketId as n, InMemoryRemoteCursorStore as o, isValidRillId as r, IndexedDbRemoteCursorStore as s, createStreamUrl as t };
+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-D0qcbI5c.js.map
+//# sourceMappingURL=stream-id-CCPEBb6G.js.map