experimental-a2 0.16.1 → 0.18.0

package/dist/{client-BYzHjkwU.js → client-BReKqwZC.js}

@@ -1,8 +1,8 @@
-import { n as validateSync } from "./validate-XKT4FSNn.js";
-import { t as clientStateProjection } from "./reducer-DEMjEY_O.js";
-import { t as A2Error } from "./errors-DCk6ch5n.js";
-import { a as PRESENCE_TIMINGS, c as STREAM_TIMINGS, h as nullProtoRecord, o as RESERVED_PARTICIPANT_IDS } from "./internal-Dq2qYxou.js";
-import { c as isWireEvent, d as parseSocketFrame, f as presencePatchFromWire, l as isWirePresencePatch, m as presenceSnapshotFromWire, o as eventFromWire, r as errorFromWire, u as isWirePresenceSnapshot } from "./wire-BO5wWCb1.js";
+import { i as A2Error, n as isSessionCleared } from "./session-clear-DGI4jTQ5.js";
+import { n as foldEvent, s as validateSync } from "./reducer-BAXc8JyF.js";
+import { r as projectClientState, t as decodeState } from "./reducer-runtime-DQwz_J59.js";
+import { _ as nullProtoRecord, a as PRESENCE_TIMINGS, l as STREAM_TIMINGS, o as RESERVED_PARTICIPANT_IDS } from "./internal-B2T3U4Rq.js";
+import { _ as isWirePresenceSnapshot, a as errorFromWire, c as eventFromCompactWire, f as isCompactWireEvent, g as isWirePresencePatch, h as isWireEvent, l as eventFromWire, p as isStateSnapshotFrame, v as parseSocketFrame, x as presenceSnapshotFromWire, y as presencePatchFromWire } from "./wire-rSUglYo8.js";
 //#region src/client-errors.ts
 var A2ClientError = class extends A2Error {
 	status;
@@ -29,6 +29,37 @@ function asClientError(error, options) {
 	return new A2ClientError(options?.code ?? "UNKNOWN", error instanceof Error ? error.message : "client operation failed", { cause: error });
 }
 //#endregion
+//#region src/initial-snapshot.ts
+function isInitialPromise(initial) {
+	return initial !== null && typeof initial === "object" && "then" in initial && typeof initial.then === "function";
+}
+function observeInitial(options) {
+	let listener = options.settled;
+	const deliver = (result) => {
+		const current = listener;
+		listener = void 0;
+		current?.(result);
+	};
+	Promise.resolve(options.promise).then((value) => deliver({ value }), (error) => deliver({ error }));
+	return () => {
+		listener = void 0;
+	};
+}
+//#endregion
+//#region src/client-render-session.ts
+const factories = /* @__PURE__ */ new WeakMap();
+function registerRenderSessionFactory(options) {
+	factories.set(options.client, options);
+}
+function resolveInitialForReact(options) {
+	factories.get(options.client)?.resolveInitial(options);
+}
+function createRenderSession(options) {
+	const factory = factories.get(options.client);
+	if (!factory) throw new TypeError("React requires a client returned by createClient");
+	return factory.factory(options.sessionId, options.settings);
+}
+//#endregion
 //#region src/client.ts
 /**
 * experimental-a2/client — the framework-agnostic session client.
@@ -44,6 +75,13 @@ function asClientError(error, options) {
 * The client is a replica, never an access path — the routes it talks
 * to authorize every read and write.
 */
+function assertSessionSeed(options) {
+	const initial = options?.initial;
+	if (initial == null || isInitialPromise(initial)) return;
+	if (initial === null || typeof initial !== "object" || !Object.hasOwn(initial, "state") || !Object.hasOwn(initial, "index") || !("index" in initial) || typeof initial.index !== "number" || !Number.isSafeInteger(initial.index) || initial.index < 0) throw new TypeError("initial must contain state and a non-negative safe integer index");
+	const clearIndex = initial.clearIndex;
+	if (clearIndex !== void 0 && (typeof clearIndex !== "number" || !Number.isSafeInteger(clearIndex) || clearIndex < 0 || clearIndex > initial.index)) throw new TypeError("initial.clearIndex must be a non-negative safe integer no greater than its index");
+}
 const PUSH_ATTEMPTS = 3;
 const RETRYABLE_PUSH_CODES = /* @__PURE__ */ new Set([
 	"STORE_UNAVAILABLE",
@@ -68,9 +106,14 @@ const httpError = async (response) => {
 	});
 };
 const httpTransport = (routes, fetchImpl, presence) => ({
-	async *connect({ sessionId, startAfter, signal }) {
+	async *connect({ sessionId, startAfter, reducer: reducerName, signal }) {
 		const streamUrl = sessionUrl(routes.stream, sessionId);
-		const res = await fetchImpl(`${streamUrl}${streamUrl.includes("?") ? "&" : "?"}sessionId=${encodeURIComponent(sessionId)}&index=${startAfter}`, {
+		const res = await fetchImpl(`${streamUrl}${streamUrl.includes("?") ? "&" : "?"}${new URLSearchParams({
+			sessionId,
+			reducer: reducerName,
+			wire: "2",
+			...startAfter === void 0 ? { bootstrap: "1" } : { index: String(startAfter) }
+		})}`, {
 			headers: { accept: "text/event-stream" },
 			signal
 		});
@@ -99,10 +142,20 @@ const httpTransport = (routes, fetchImpl, presence) => ({
 					if (!data) continue;
 					if (eventName === void 0) {
 						const parsed = JSON.parse(data);
-						if (isWireEvent(parsed)) yield {
+						if (Array.isArray(parsed)) {
+							if (!parsed.every(isCompactWireEvent)) throw new A2ClientError("INVALID_PAYLOAD", "invalid event batch");
+							yield {
+								kind: "events",
+								events: parsed.map((row) => eventFromCompactWire(row, sessionId))
+							};
+						} else if (isWireEvent(parsed)) yield {
 							kind: "event",
 							event: parsed
 						};
+					} else if (eventName === "a2-snapshot") {
+						const parsed = JSON.parse(data);
+						if (!isStateSnapshotFrame(parsed)) throw new A2ClientError("INVALID_PAYLOAD", "invalid bootstrap snapshot");
+						yield parsed;
 					} else if (presence && eventName === "presence-snapshot") {
 						const parsed = JSON.parse(data);
 						if (isWirePresenceSnapshot(parsed)) yield {
@@ -144,7 +197,11 @@ const httpTransport = (routes, fetchImpl, presence) => ({
 		if (!res.ok) throw await httpError(res);
 		const rows = await res.json();
 		if (!Array.isArray(rows) || !rows.every(isWireEvent)) throw new A2ClientError("STORE_UNAVAILABLE", "history response was not a list of events");
-		return rows;
+		const clearIndex = Number(res.headers.get("a2-clear-index") ?? NaN);
+		return Number.isSafeInteger(clearIndex) && clearIndex > 0 ? {
+			events: rows,
+			clearIndex
+		} : { events: rows };
 	},
 	sendPresence(envelope) {
 		(async () => {
@@ -214,16 +271,21 @@ const sessionWsTransport = (url, webSocketImpl, presence) => {
 	const connections = /* @__PURE__ */ new Map();
 	const ready = socketReadyWaiters();
 	let nextReq = 1;
-	const socketUrl = (sessionId, startAfter) => {
+	const socketUrl = (sessionId, startAfter, reducerName) => {
 		const resolved = webSocketUrl(sessionUrl(url, sessionId));
 		resolved.searchParams.set("sessionId", sessionId);
-		resolved.searchParams.set("index", String(startAfter));
+		resolved.searchParams.delete("index");
+		resolved.searchParams.delete("bootstrap");
+		resolved.searchParams.set("reducer", reducerName);
+		resolved.searchParams.set("wire", "2");
+		if (startAfter === void 0) resolved.searchParams.set("bootstrap", "1");
+		else resolved.searchParams.set("index", String(startAfter));
 		return resolved.href;
 	};
 	return {
-		async *connect({ sessionId, startAfter, signal }) {
+		async *connect({ sessionId, startAfter, reducer: reducerName, signal }) {
 			if (webSocketImpl === void 0) throw new TypeError("no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing");
-			const socket = new webSocketImpl(socketUrl(sessionId, startAfter));
+			const socket = new webSocketImpl(socketUrl(sessionId, startAfter, reducerName));
 			const connection = {
 				socket,
 				pending: /* @__PURE__ */ new Map()
@@ -241,7 +303,10 @@ const sessionWsTransport = (url, webSocketImpl, presence) => {
 				if (ended) return;
 				ended = true;
 				failure = error;
-				if (connections.get(sessionId) === connection) connections.delete(sessionId);
+				if (connections.get(sessionId) === connection) {
+					connections.delete(sessionId);
+					ready.notify(sessionId);
+				}
 				rejectPendingAcks(connection.pending);
 				notify();
 			};
@@ -254,9 +319,18 @@ const sessionWsTransport = (url, webSocketImpl, presence) => {
 			socket.addEventListener("message", (event) => {
 				if (connections.get(sessionId) !== connection || ended) return;
 				if (typeof event.data !== "string") return;
-				const frame = parseSocketFrame(event.data);
+				let frame;
+				try {
+					frame = parseSocketFrame(event.data);
+				} catch (error) {
+					finish(asClientError(error));
+					return;
+				}
 				if (frame === null) return;
 				switch (frame.kind) {
+					case "snapshot":
+						queue.push(frame);
+						break;
 					case "ack": {
 						const waiter = connection.pending.get(frame.req);
 						if (waiter === void 0) return;
@@ -276,6 +350,13 @@ const sessionWsTransport = (url, webSocketImpl, presence) => {
 							event: frame.event
 						});
 						break;
+					case "events":
+						if (frame.sessionId !== void 0) return;
+						queue.push({
+							kind: "events",
+							events: frame.events.map((row) => eventFromCompactWire(row, sessionId))
+						});
+						break;
 					case "presence":
 						if (presence && frame.sessionId === void 0) queue.push({
 							kind: "presence",
@@ -378,6 +459,14 @@ const wakeChannel = (channel) => {
 	channel.wake?.();
 	channel.wake = null;
 };
+const answersAttempt = (frame, channel) => frame.attempt === void 0 || frame.attempt === channel.attempt;
+const subscriptionStart = (index, reducer) => index === void 0 ? {
+	bootstrap: true,
+	reducer
+} : {
+	index,
+	reducer
+};
 const subscribeFrame = (sessions) => {
 	return JSON.stringify({
 		kind: "subscribe",
@@ -394,6 +483,7 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 	let socketOpen = false;
 	let watchdog;
 	let nextReq = 1;
+	let nextAttempt = 1;
 	const trySend = (data) => {
 		if (socket === null || !socketOpen) return;
 		try {
@@ -429,6 +519,7 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 	const detach = (channel) => {
 		if (channels.get(channel.sessionId) !== channel) return;
 		channels.delete(channel.sessionId);
+		ready.notify(channel.sessionId);
 		if (!channel.dropped) {
 			const frame = {
 				kind: "unsubscribe",
@@ -456,12 +547,17 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 	};
 	const route = (frame) => {
 		switch (frame.kind) {
+			case "snapshot": {
+				const channel = channels.get(frame.sessionId);
+				if (channel && channel.live && !channel.ended) deliver(channel, frame);
+				return;
+			}
 			case "ping":
 				for (const channel of channels.values()) if (channel.live && !channel.ended) deliver(channel, { kind: "ping" });
 				return;
 			case "subscribed": {
 				const channel = channels.get(frame.sessionId);
-				if (channel === void 0 || channel.ended || channel.live) return;
+				if (channel === void 0 || channel.ended || channel.live || !answersAttempt(frame, channel)) return;
 				channel.live = true;
 				deliver(channel, { kind: "ping" });
 				ready.notify(frame.sessionId);
@@ -469,7 +565,7 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 			}
 			case "unsubscribed": {
 				const channel = channels.get(frame.sessionId);
-				if (channel === void 0) return;
+				if (channel === void 0 || !answersAttempt(frame, channel)) return;
 				channel.dropped = true;
 				settleChannel(channel, frame.error ? asClientError(frame.error) : frame.reason === void 0 ? null : new A2ClientError("CONNECTION_FAILED", frame.reason));
 				return;
@@ -490,6 +586,16 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 				});
 				return;
 			}
+			case "events": {
+				const { sessionId } = frame;
+				if (sessionId === void 0) return;
+				const channel = channels.get(sessionId);
+				if (channel !== void 0 && channel.live && !channel.ended) deliver(channel, {
+					kind: "events",
+					events: frame.events.map((row) => eventFromCompactWire(row, sessionId))
+				});
+				return;
+			}
 			case "presence": {
 				if (!presence || frame.sessionId === void 0) return;
 				const channel = channels.get(frame.sessionId);
@@ -513,7 +619,9 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 	const ensureSocket = () => {
 		if (socket !== null) return;
 		if (webSocketImpl === void 0) throw new TypeError("no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing");
-		const created = new webSocketImpl(webSocketUrl(url).href);
+		const target = webSocketUrl(url);
+		target.searchParams.set("wire", "2");
+		const created = new webSocketImpl(target.href);
 		socket = created;
 		socketOpen = false;
 		armWatchdog(created);
@@ -523,7 +631,8 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 			armWatchdog(created);
 			const sessions = [...channels.values()].filter((channel) => !channel.ended).map((channel) => ({
 				id: channel.sessionId,
-				index: channel.startAfter
+				attempt: channel.attempt,
+				...subscriptionStart(channel.startAfter, channel.reducer)
 			}));
 			if (sessions.length > 0) trySend(subscribeFrame(sessions));
 		});
@@ -531,7 +640,13 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 			if (socket !== created) return;
 			if (typeof event.data !== "string") return;
 			armWatchdog(created);
-			const frame = parseSocketFrame(event.data);
+			let frame;
+			try {
+				frame = parseSocketFrame(event.data);
+			} catch (error) {
+				failSocket(asClientError(error));
+				return;
+			}
 			if (frame === null) return;
 			route(frame);
 		});
@@ -548,10 +663,12 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 		});
 	};
 	return {
-		async *connect({ sessionId, startAfter, signal }) {
+		async *connect({ sessionId, startAfter, reducer: reducerName, signal }) {
 			const channel = {
 				sessionId,
+				attempt: nextAttempt++,
 				startAfter,
+				reducer: reducerName,
 				queue: [],
 				live: false,
 				dropped: false,
@@ -564,7 +681,8 @@ const multiplexedWsTransport = (url, webSocketImpl, presence) => {
 				ensureSocket();
 				if (socketOpen) trySend(subscribeFrame([{
 					id: sessionId,
-					index: startAfter
+					attempt: channel.attempt,
+					...subscriptionStart(startAfter, reducerName)
 				}]));
 			} catch (error) {
 				if (channels.get(sessionId) === channel) channels.delete(sessionId);
@@ -660,8 +778,10 @@ const transportFor = (api, fetchImpl, webSocketImpl, presence) => {
 	return sessionWsTransport(api.url, webSocketImpl, presence);
 };
 function createClient(options) {
-	const { reducer, api } = options;
-	const presenceDefs = reducer.presence;
+	const { contract, api } = options;
+	const reducer = contract?.reducer;
+	if (!reducer) throw new TypeError("createClient requires a contract with a public reducer");
+	const presenceDefs = contract.presence;
 	const declaresPresence = Object.keys(presenceDefs).length > 0;
 	const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
 	const clientFetch = async (input, init) => {
@@ -684,6 +804,8 @@ function createClient(options) {
 		entry.timer = setTimeout(() => {
 			if (sessions.get(sessionId) !== entry) return;
 			if (entry.runtime.canEvict()) {
+				entry.runtime.close();
+				clearTimeout(entry.timer);
 				sessions.delete(sessionId);
 				return;
 			}
@@ -695,10 +817,21 @@ function createClient(options) {
 		scheduleGc(sessionId);
 	};
 	const makeSession = (sessionId, sessionOptions) => {
-		let stateIndex = sessionOptions?.initialIndex ?? 0;
-		let streamIndex = sessionOptions?.initialState === void 0 ? sessionOptions?.initialIndex : stateIndex;
-		let foldedState = sessionOptions?.initialState !== void 0 ? sessionOptions.initialState : reducer.initialState;
-		const serverEvents = (sessionOptions?.initialEvents ?? []).filter((event) => event.index <= stateIndex).toSorted((a, b) => a.index - b.index);
+		assertSessionSeed(sessionOptions);
+		const supplied = sessionOptions?.initial;
+		const initial = isInitialPromise(supplied) ? void 0 : supplied;
+		let hydrated = initial != null;
+		let bootstrapGeneration;
+		let stateIndex = initial?.index ?? 0;
+		let streamIndex = initial?.index;
+		let foldedState = initial == null ? reducer.initialState : initial.state;
+		/** The latest clear marker this session has learned of, or 0. */
+		let clearIndex = initial?.clearIndex ?? 0;
+		let initialVersion = 0;
+		const seenInitials = /* @__PURE__ */ new WeakSet();
+		if (initial != null) seenInitials.add(initial);
+		let preload;
+		const serverEvents = (sessionOptions?.initialEvents ?? []).filter((event) => event.index <= stateIndex && event.index > clearIndex).toSorted((a, b) => a.index - b.index);
 		let pending = [];
 		let participant = sessionOptions?.participant ?? options.participant;
 		let presenceState = nullProtoRecord();
@@ -720,6 +853,7 @@ function createClient(options) {
 		let inFlightPushes = 0;
 		let pushWireTail = Promise.resolve();
 		let deferredHydration;
+		let resumeInitialError;
 		let hydrationNotification;
 		const emit = () => {
 			for (const listener of [...listeners]) listener();
@@ -728,10 +862,16 @@ function createClient(options) {
 			snapshot = null;
 			emit();
 		};
-		const notifyHydrated = () => {
+		const notifyHydrated = (resume) => {
+			resumeInitialError ??= resume;
 			snapshot = null;
 			clearTimeout(hydrationNotification);
-			hydrationNotification = setTimeout(emit, 0);
+			hydrationNotification = setTimeout(() => {
+				const failure = resumeInitialError;
+				resumeInitialError = void 0;
+				if (failure && active && status === "paused" && lastError === failure) reconnectStream();
+				else emit();
+			}, 0);
 			hydrationNotification.unref?.();
 		};
 		const mergeServerEvents = (events, throughIndex) => {
@@ -739,7 +879,7 @@ function createClient(options) {
 			const byIndex = new Map(serverEvents.map((event) => [event.index, event]));
 			let changed = false;
 			for (const event of events) {
-				if (event.index > throughIndex) continue;
+				if (event.index > throughIndex || event.index <= clearIndex) continue;
 				if (byIndex.get(event.index)?.id === event.id) continue;
 				byIndex.set(event.index, event);
 				changed = true;
@@ -748,10 +888,25 @@ function createClient(options) {
 			serverEvents.splice(0, serverEvents.length, ...[...byIndex.values()].toSorted((a, b) => a.index - b.index));
 			return true;
 		};
+		/**
+		* Raise the latest known clear marker (a2-implementation.md §17.4):
+		* drop the served history it ended and every push acked below it.
+		* The boundary never moves backward.
+		*/
+		const applyClearBoundary = (index) => {
+			if (index <= clearIndex) return false;
+			clearIndex = index;
+			const kept = serverEvents.filter((event) => event.index > index);
+			serverEvents.splice(0, serverEvents.length, ...kept);
+			pending = pending.filter((entry) => entry.acked === void 0 || entry.acked.index > index);
+			return true;
+		};
 		const overlayEvents = () => {
 			const acked = pending.filter((p) => p.acked).map((p) => p.acked).toSorted((a, b) => a.index - b.index);
 			const maxKnown = Math.max(stateIndex, acked.at(-1)?.index ?? stateIndex);
-			const unacked = pending.filter((p) => !p.acked).map((p, i) => ({
+			const waiting = pending.filter((p) => !p.acked);
+			const held = waiting.findIndex((p) => p.heldUntilAck);
+			const unacked = (held === -1 ? waiting : waiting.slice(0, held)).map((p, i) => ({
 				id: p.id,
 				type: p.type,
 				payload: p.payload,
@@ -781,14 +936,14 @@ function createClient(options) {
 			const oldestLoaded = serverEvents[0]?.index ?? null;
 			return {
 				loading: historyLoads > 0,
-				complete: oldestLoaded === 1 || stateIndex === 0,
+				complete: hydrated && (oldestLoaded === clearIndex + 1 || stateIndex === clearIndex),
 				oldestLoaded
 			};
 		};
 		const buildSnapshot = () => {
 			const overlay = overlayEvents();
 			let state = foldedState;
-			for (const event of overlay) if (event.index > stateIndex) state = reducer.fold(state, event);
+			for (const event of hydrated ? overlay : []) if (event.index > stateIndex) state = reducer.fold(state, event);
 			const displayedOverlay = overlay.filter((event) => {
 				if (event.index > stateIndex) return true;
 				let low = 0;
@@ -803,7 +958,11 @@ function createClient(options) {
 				return true;
 			});
 			return {
-				state: reducer[clientStateProjection]?.(state) ?? state,
+				state: projectClientState({
+					reducer,
+					state
+				}),
+				hydrated,
 				events: [...serverEvents, ...displayedOverlay],
 				index: stateIndex,
 				history: historyState(),
@@ -939,30 +1098,65 @@ function createClient(options) {
 			queuePresenceSend(validated, at);
 			touch(sessionId);
 		};
-		/** Pushes awaiting stream confirmation — resolved by `ingest` the
-		* moment the state index passes their batch. */
+		/** Pushes awaiting stream confirmation — resolved the moment the
+		* stream, by event or bootstrap snapshot, passes their batch. */
 		let confirmWatchers = [];
+		const resolveConfirmed = () => {
+			const delivered = streamIndex ?? 0;
+			const due = confirmWatchers.filter((watcher) => watcher.index <= delivered);
+			if (due.length === 0) return;
+			confirmWatchers = confirmWatchers.filter((watcher) => watcher.index > delivered);
+			for (const watcher of due) watcher.resolve();
+		};
+		const retireCoveredPending = () => {
+			pending = pending.filter((entry) => !entry.acked || entry.acked.index > Math.min(stateIndex, streamIndex ?? stateIndex));
+		};
+		const adoptBaseline = (baseline) => {
+			hydrated = true;
+			stateIndex = baseline.index;
+			foldedState = baseline.state;
+			for (const entry of pending) if (entry.sent && !entry.acked) entry.heldUntilAck = true;
+			retireCoveredPending();
+		};
+		const bootstrapState = (frame) => {
+			let state;
+			try {
+				state = decodeState({
+					reducer,
+					state: frame.stateUndefined ? void 0 : frame.state
+				});
+			} catch (error) {
+				throw asClientError(error, { code: "INVALID_PAYLOAD" });
+			}
+			if (!reducer.stateSchema) return state;
+			const result = validateSync(reducer.stateSchema, state, "bootstrap stateSchema");
+			if (result.issues) throw new A2ClientError("INVALID_PAYLOAD", "bootstrap state failed stateSchema", { details: result.issues });
+			return result.value;
+		};
 		/** The single ingest point: every server-confirmed event, in log
 		* order, from the stream. */
-		const ingest = (event) => {
-			if (event.index <= (streamIndex ?? 0)) return;
-			streamIndex = event.index;
-			if (event.index > stateIndex) {
-				stateIndex = event.index;
-				serverEvents.push(event);
-				foldedState = reducer.fold(foldedState, event);
-			} else mergeServerEvents([event], stateIndex);
-			pending = pending.filter((p) => p.id !== event.id);
-			if (confirmWatchers.some((w) => w.index <= stateIndex)) {
-				const due = confirmWatchers.filter((w) => w.index <= stateIndex);
-				confirmWatchers = confirmWatchers.filter((w) => w.index > stateIndex);
-				for (const watcher of due) watcher.resolve();
+		const ingest = (events) => {
+			let delivered = false;
+			for (const event of events) {
+				if (event.index <= (streamIndex ?? 0)) continue;
+				delivered = true;
+				streamIndex = event.index;
+				const cleared = isSessionCleared(event);
+				if (event.index > stateIndex) {
+					stateIndex = event.index;
+					if (!cleared) serverEvents.push(event);
+					foldedState = foldEvent(reducer, foldedState, event);
+				} else if (!cleared) mergeServerEvents([event], stateIndex);
+				if (cleared) applyClearBoundary(event.index);
+				pending = pending.filter((p) => p.id !== event.id);
 			}
+			if (!delivered) return;
+			resolveConfirmed();
 			notify();
 			touch(sessionId);
 		};
 		const validated = (events) => events.map((event) => {
-			const schema = Object.hasOwn(reducer.events, event.type) ? reducer.events[event.type] : void 0;
+			const schema = Object.hasOwn(contract.events, event.type) ? contract.events[event.type] : void 0;
 			if (!schema) throw new A2ClientError("UNKNOWN_EVENT_TYPE", `no event type '${String(event.type)}' in the reducer's vocabulary`);
 			const result = validateSync(schema, event.payload, `event '${String(event.type)}'`);
 			if (result.issues) throw new A2ClientError("INVALID_PAYLOAD", `invalid payload for event '${String(event.type)}'`, { details: result.issues });
@@ -998,7 +1192,7 @@ function createClient(options) {
 			return Object.defineProperty(ack, "confirmed", { get() {
 				confirmed ??= ack.then((acked) => new Promise((resolve) => {
 					const last = acked.at(-1)?.index ?? 0;
-					if (stateIndex >= last) {
+					if ((streamIndex ?? 0) >= last) {
 						resolve(acked);
 						return;
 					}
@@ -1010,6 +1204,20 @@ function createClient(options) {
 				return confirmed;
 			} });
 		};
+		const initialSettled = (epoch) => new Promise((resolve, reject) => {
+			const check = () => {
+				const failure = leaseEpoch !== epoch || status === "closed" ? new DOMException("session closed", "AbortError") : !hydrated && preload?.error;
+				if (failure) {
+					listeners.delete(check);
+					reject(failure);
+				} else if (hydrated || !preload) {
+					listeners.delete(check);
+					resolve();
+				}
+			};
+			listeners.add(check);
+			check();
+		});
 		const push = (...events) => {
 			touch(sessionId);
 			return withConfirmed((async () => {
@@ -1027,10 +1235,19 @@ function createClient(options) {
 				});
 				pending.push(...entries);
 				inFlightPushes += 1;
+				let acknowledgedIndex;
+				const pushEpoch = leaseEpoch;
+				const releaseConnection = !hydrated || transport.awaitReady || active ? runtime.connect() : void 0;
 				try {
 					refreshIdleStream();
 					notify();
 					await waitForPriorPush;
+					if (transport.awaitReady) {
+						await initialSettled(pushEpoch);
+						await transport.awaitReady(sessionId, STREAM_TIMINGS.stallTimeoutMs);
+					}
+					if (leaseEpoch !== pushEpoch) throw new DOMException("session closed", "AbortError");
+					for (const entry of entries) entry.sent = true;
 					const acked = await post({
 						sessionId,
 						events: entries.map(({ id, type, payload }) => ({
@@ -1039,11 +1256,12 @@ function createClient(options) {
 							payload
 						}))
 					});
+					acknowledgedIndex = acked.at(-1)?.index;
 					for (const event of acked) {
 						const entry = pending.find((p) => p.id === event.id);
 						if (entry) entry.acked = event;
 					}
-					pending = pending.filter((entry) => entry.acked === void 0 || entry.acked.index > Math.min(stateIndex, streamIndex ?? stateIndex));
+					retireCoveredPending();
 					if ((acked.at(-1)?.index ?? 0) > (streamIndex ?? stateIndex)) refreshIdleStream();
 					notify();
 					return acked;
@@ -1053,12 +1271,20 @@ function createClient(options) {
 					notify();
 					throw err;
 				} finally {
+					if (releaseConnection && pushEpoch === leaseEpoch && acknowledgedIndex !== void 0 && acknowledgedIndex > (streamIndex ?? 0)) confirmWatchers.push({
+						index: acknowledgedIndex,
+						resolve: releaseConnection,
+						lease: true
+					});
+					else releaseConnection?.();
 					releasePush();
 					inFlightPushes -= 1;
 					if (inFlightPushes === 0 && deferredHydration) {
 						const next = deferredHydration;
 						deferredHydration = void 0;
-						runtime.hydrate(next);
+						if (next.version === void 0 || next.version === initialVersion) {
+							if (applyInitial(next)) notifyHydrated();
+						}
 					}
 					touch(sessionId);
 				}
@@ -1095,18 +1321,19 @@ function createClient(options) {
 			const run = historyTail.then(async () => {
 				const upper = before ?? serverEvents[0]?.index ?? stateIndex + 1;
 				const lte = Math.min(upper - 1, stateIndex);
-				const gte = Math.max(1, upper - (limit ?? DEFAULT_HISTORY_LIMIT));
+				const gte = Math.max(clearIndex + 1, upper - (limit ?? DEFAULT_HISTORY_LIMIT));
 				if (gte > lte) return [];
 				const missing = missingBetween(gte, lte);
 				if (missing === null) return eventsBetween(gte, lte);
 				historyLoads += 1;
 				notify();
 				try {
-					const rows = await readHistory({
+					const page = await readHistory({
 						sessionId,
 						...missing
 					});
-					mergeServerEvents(rows.map((row) => eventFromWire(row)), stateIndex);
+					if (page.clearIndex !== void 0) applyClearBoundary(page.clearIndex);
+					mergeServerEvents(page.events.map((row) => eventFromWire(row)), stateIndex);
 					return eventsBetween(gte, lte);
 				} catch (error) {
 					throw asClientError(error);
@@ -1158,14 +1385,46 @@ function createClient(options) {
 				};
 				let wasLive = false;
 				try {
+					while (!hydrated && preload && !preload.error) await waitForInitial(controller.signal);
+					if (generation !== run || controller.signal.aborted) break;
+					if (!hydrated && preload?.error) {
+						lastError = preload.error;
+						status = "paused";
+						notify();
+						return;
+					}
+					if (hydrated && streamIndex === void 0) streamIndex = stateIndex;
+					resolveConfirmed();
+					if (generation !== run) break;
+					bootstrapGeneration = streamIndex === void 0 ? run : void 0;
 					const frames = transport.connect({
 						sessionId,
-						startAfter: streamIndex ??= stateIndex,
+						startAfter: streamIndex,
+						reducer: reducer.name,
 						signal: controller.signal
 					});
 					for await (const frame of frames) {
 						if (generation !== run) break;
 						armStall();
+						if (frame.kind === "snapshot") {
+							if (frame.sessionId !== sessionId || frame.name !== reducer.name || !isStateSnapshotFrame(frame)) throw new A2ClientError("INVALID_PAYLOAD", "bootstrap snapshot belongs to another session or reducer");
+							if (bootstrapGeneration !== run) throw new A2ClientError("INVALID_PAYLOAD", "unexpected bootstrap snapshot");
+							const baseline = !hydrated || frame.index >= stateIndex ? {
+								state: bootstrapState(frame),
+								index: frame.index
+							} : void 0;
+							streamIndex = frame.index;
+							bootstrapGeneration = void 0;
+							applyClearBoundary(frame.clearIndex ?? 0);
+							if (baseline) adoptBaseline(baseline);
+							resolveConfirmed();
+							notify();
+							if (generation !== run) break;
+						}
+						if (!hydrated || streamIndex === void 0) {
+							if (frame.kind === "event" || frame.kind === "events") throw new A2ClientError("INVALID_PAYLOAD", "received an event before the bootstrap snapshot");
+							continue;
+						}
 						if (!wasLive) {
 							backoff = STREAM_TIMINGS.reconnectBaseMs;
 							attempt = 0;
@@ -1182,7 +1441,10 @@ function createClient(options) {
 						}
 						if (frame.kind === "event") {
 							streamIdle = false;
-							ingest(eventFromWire(frame.event));
+							ingest([eventFromWire(frame.event)]);
+						} else if (frame.kind === "events") {
+							streamIdle = false;
+							ingest(frame.events);
 						} else if (frame.kind === "activity") {
 							streamIdle = frame.idle;
 							if (streamIdle && (inFlightPushes > 0 || pending.some((entry) => (entry.acked?.index ?? 0) > (streamIndex ?? stateIndex)))) refreshIdleStream();
@@ -1196,6 +1458,7 @@ function createClient(options) {
 						timeoutMs: STREAM_TIMINGS.stallTimeoutMs
 					}) : asClientError(err);
 				} finally {
+					if (bootstrapGeneration === run) bootstrapGeneration = void 0;
 					clearTimeout(stall);
 				}
 				if (generation !== run) break;
@@ -1262,6 +1525,71 @@ function createClient(options) {
 			if (active && generation === run) runStream(run);
 			previous?.abort();
 		};
+		const applyInitial = ({ settings: next, version }) => {
+			const nextIndex = next.initial?.index ?? 0;
+			if (hydrated && nextIndex > stateIndex && inFlightPushes > 0) {
+				if (!deferredHydration || nextIndex > (deferredHydration.settings.initial?.index ?? 0)) deferredHydration = {
+					settings: next,
+					...version === void 0 ? {} : { version }
+				};
+				return false;
+			}
+			const boundaryChanged = applyClearBoundary(next.initial?.clearIndex ?? 0);
+			const historyChanged = mergeServerEvents(next.initialEvents, Math.min(nextIndex, stateIndex)) || boundaryChanged;
+			if (next.initial != null && bootstrapGeneration === void 0) streamIndex ??= nextIndex;
+			if (next.initial == null || hydrated && nextIndex <= stateIndex) return historyChanged;
+			adoptBaseline(next.initial);
+			mergeServerEvents(next.initialEvents, stateIndex);
+			return true;
+		};
+		const invalidateInitial = () => {
+			initialVersion++;
+			preload?.cancel();
+			preload = void 0;
+			if (deferredHydration?.version !== void 0) deferredHydration = void 0;
+		};
+		const settleInitial = (result) => {
+			const entry = preload;
+			if (!entry || entry.source !== result.source || entry.version !== initialVersion) return;
+			entry.cancel();
+			const cold = !hydrated;
+			let changed = false;
+			if ("error" in result) {
+				if (cold) entry.error = asClientError(result.error);
+				else preload = void 0;
+			} else try {
+				assertSessionSeed({ initial: result.value });
+				if (isInitialPromise(result.value)) throw new TypeError("an initial Promise must resolve to a snapshot");
+				preload = void 0;
+				changed = applyInitial({
+					settings: {
+						...entry.settings,
+						initial: result.value
+					},
+					version: entry.version
+				});
+			} catch (error) {
+				if (cold) {
+					preload = entry;
+					entry.error = asClientError(error, { code: "INVALID_PAYLOAD" });
+				} else preload = void 0;
+			}
+			if (cold || changed) notifyHydrated();
+		};
+		const waitForInitial = (signal) => new Promise((resolve, reject) => {
+			let settled = false;
+			const finish = () => {
+				if (settled || !signal.aborted && !hydrated && preload && !preload.error) return;
+				settled = true;
+				listeners.delete(finish);
+				signal.removeEventListener("abort", finish);
+				if (signal.aborted) reject(signal.reason);
+				else resolve();
+			};
+			listeners.add(finish);
+			signal.addEventListener("abort", finish, { once: true });
+			finish();
+		});
 		const runtime = {
 			sessionId,
 			...declaresPresence ? { setPresence } : {},
@@ -1302,43 +1630,71 @@ function createClient(options) {
 				};
 			},
 			close() {
+				invalidateInitial();
+				resumeInitialError = void 0;
 				leases = 0;
 				leaseEpoch += 1;
+				confirmWatchers = confirmWatchers.filter((watcher) => !watcher.lease);
 				stopStream();
 			},
+			resolveInitial: settleInitial,
 			hydrate(next) {
+				assertSessionSeed(next);
 				touch(sessionId);
 				if (!next) return;
 				participant ??= next.participant;
-				const nextIndex = next.initialIndex ?? 0;
-				if (nextIndex > stateIndex && inFlightPushes > 0) {
-					if (!deferredHydration || nextIndex > (deferredHydration.initialIndex ?? 0)) deferredHydration = next;
-					return;
-				}
-				const historyChanged = mergeServerEvents(next.initialEvents, Math.min(nextIndex, stateIndex));
-				if (next.initialState !== void 0) streamIndex ??= nextIndex;
-				if (next.initialState === void 0 || nextIndex <= stateIndex) {
-					if (historyChanged) notifyHydrated();
+				const input = next.initial;
+				const resume = !hydrated && status === "paused" && preload?.error === lastError ? preload.error : void 0;
+				if (isInitialPromise(input)) {
+					if (seenInitials.has(input)) {
+						if (preload?.source === input && next.initialEvents !== void 0) preload.settings.initialEvents = next.initialEvents;
+						if (mergeServerEvents(next.initialEvents, stateIndex)) notifyHydrated();
+						return;
+					}
+					invalidateInitial();
+					seenInitials.add(input);
+					const { initial: _initial, ...settings } = next;
+					const entry = {
+						source: input,
+						version: initialVersion,
+						settings,
+						cancel() {}
+					};
+					preload = entry;
+					entry.cancel = observeInitial({
+						promise: input,
+						settled: (result) => settleInitial({
+							source: input,
+							...result
+						})
+					});
+					if (resume) notifyHydrated(resume);
 					return;
 				}
-				stateIndex = nextIndex;
-				foldedState = next.initialState;
-				mergeServerEvents(next.initialEvents, stateIndex);
-				pending = pending.filter((entry) => !entry.acked || entry.acked.index > Math.min(stateIndex, streamIndex ?? stateIndex));
-				if (confirmWatchers.some((watcher) => watcher.index <= stateIndex)) {
-					const due = confirmWatchers.filter((watcher) => watcher.index <= stateIndex);
-					confirmWatchers = confirmWatchers.filter((watcher) => watcher.index > stateIndex);
-					for (const watcher of due) watcher.resolve();
+				if (input != null) {
+					const repeated = seenInitials.has(input);
+					seenInitials.add(input);
+					if (repeated || hydrated && input.index <= stateIndex) {
+						if (deferredHydration?.settings.initial === input && next.initialEvents !== void 0) deferredHydration.settings.initialEvents = next.initialEvents;
+						const boundaryChanged = applyClearBoundary(input.clearIndex ?? 0);
+						if (mergeServerEvents(next.initialEvents, Math.min(input.index, stateIndex)) || boundaryChanged) notifyHydrated();
+						return;
+					}
 				}
-				notifyHydrated();
+				if (input !== void 0) invalidateInitial();
+				if (applyInitial({ settings: {
+					...next,
+					initial: input
+				} }) || resume || input === null) notifyHydrated(resume);
 			},
 			canEvict() {
 				return listeners.size === 0 && !active && inFlightPushes === 0 && historyLoads === 0 && confirmWatchers.length === 0 && presenceTimer === void 0;
 			}
 		};
+		if (isInitialPromise(supplied)) runtime.hydrate(sessionOptions);
 		return runtime;
 	};
-	return { session(sessionId, sessionOptions) {
+	const client = { session(sessionId, sessionOptions) {
 		const existing = sessions.get(sessionId);
 		if (existing) {
 			existing.runtime.hydrate(sessionOptions);
@@ -1350,8 +1706,19 @@ function createClient(options) {
 		touch(sessionId);
 		return runtime;
 	} };
+	registerRenderSessionFactory({
+		client,
+		factory: (sessionId, settings) => makeSession(sessionId, settings),
+		resolveInitial: ({ session, source, value }) => {
+			session.resolveInitial({
+				source,
+				value
+			});
+		}
+	});
+	return client;
 }
 //#endregion
-export { A2ClientError as n, createClient as t };
+export { A2ClientError as a, isInitialPromise as i, createRenderSession as n, resolveInitialForReact as r, createClient as t };
 
-//# sourceMappingURL=client-BYzHjkwU.js.map
+//# sourceMappingURL=client-BReKqwZC.js.map