experimental-a2 0.3.0 → 0.5.0

package/dist/client-BKlyLiOU.js

@@ -0,0 +1,1008 @@
+import { n as validateSync } from "./validate-XKT4FSNn.js";
+import { t as A2Error } from "./errors-BQuJpe82.js";
+import { a as PRESENCE_TIMINGS, c as STREAM_TIMINGS, g as nullProtoRecord } from "./internal-DstsI6Re.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-BFQmSJ-9.js";
+//#region src/client.ts
+/**
+* experimental-a2/client — the framework-agnostic session client.
+*
+* Everything the browser needs to read a session live and push
+* optimistically, with no framework attached: the SSE subscription with
+* frontier resume and reconnection, the optimistic push queue with
+* ack/rollback, and the local fold through the same reducer the server
+* uses. `experimental-a2/react`'s `createReact` is a thin binding over it, and the
+* store contract (`subscribe`/`getSnapshot`) is exactly what
+* `useSyncExternalStore` wants.
+*
+* The client is a replica, never an access path — the routes it talks
+* to authorize every read and write.
+*/
+const PUSH_ATTEMPTS = 3;
+const DEFAULT_GC_TIME_MS = 3e5;
+const DEFAULT_HISTORY_LIMIT = 50;
+const httpTransport = (routes, fetchImpl, presence) => ({
+	async *connect({ sessionId, startAfter, signal }) {
+		const sep = routes.stream.includes("?") ? "&" : "?";
+		const res = await fetchImpl(`${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&index=${startAfter}`, {
+			headers: { accept: "text/event-stream" },
+			signal
+		});
+		if (!res.ok || !res.body) throw new Error(`stream failed with ${res.status}`);
+		yield { kind: "ping" };
+		const decoder = new TextDecoder();
+		const reader = res.body.getReader();
+		let buffer = "";
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) return;
+				yield { kind: "ping" };
+				buffer += decoder.decode(value, { stream: true });
+				for (;;) {
+					const boundary = buffer.indexOf("\n\n");
+					if (boundary === -1) break;
+					const frame = buffer.slice(0, boundary);
+					buffer = buffer.slice(boundary + 2);
+					let eventName;
+					const dataLines = [];
+					for (const line of frame.split("\n")) if (line.startsWith("data:")) dataLines.push(line.slice(5).trimStart());
+					else if (line.startsWith("event:")) eventName = line.slice(6).trim();
+					const data = dataLines.join("\n");
+					if (!data) continue;
+					if (eventName === void 0) {
+						const parsed = JSON.parse(data);
+						if (isWireEvent(parsed)) yield {
+							kind: "event",
+							event: parsed
+						};
+					} else if (presence && eventName === "presence-snapshot") {
+						const parsed = JSON.parse(data);
+						if (isWirePresenceSnapshot(parsed)) yield {
+							kind: "presence-snapshot",
+							snapshot: parsed
+						};
+					} else if (presence && eventName === "presence") {
+						const parsed = JSON.parse(data);
+						if (isWirePresencePatch(parsed)) yield {
+							kind: "presence",
+							patch: parsed
+						};
+					}
+				}
+			}
+		} finally {
+			reader.cancel().catch(() => {});
+		}
+	},
+	async push(body) {
+		const res = await fetchImpl(routes.push, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body)
+		});
+		if (res.ok) {
+			const rows = await res.json();
+			if (!Array.isArray(rows) || !rows.every(isWireEvent)) throw new A2Error("STORE_UNAVAILABLE", "push ack was not a list of events");
+			return rows;
+		}
+		throw errorFromWire(await res.json().catch(() => null)) ?? new A2Error("STORE_UNAVAILABLE", `push failed with ${res.status}`);
+	},
+	async history({ sessionId, gte, lte }) {
+		const sep = routes.stream.includes("?") ? "&" : "?";
+		const res = await fetchImpl(`${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&gte=${gte}&lte=${lte}`, { headers: { accept: "application/json" } });
+		if (!res.ok) throw errorFromWire(await res.json().catch(() => null)) ?? new A2Error("STORE_UNAVAILABLE", `history failed with ${res.status}`);
+		const rows = await res.json();
+		if (!Array.isArray(rows) || !rows.every(isWireEvent)) throw new A2Error("STORE_UNAVAILABLE", "history response was not a list of events");
+		return rows;
+	},
+	sendPresence(envelope) {
+		(async () => {
+			try {
+				await (await fetchImpl(routes.push, {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify(envelope)
+				})).arrayBuffer();
+			} catch {}
+		})();
+	}
+});
+/** `WebSocket.OPEN` — fixed by the spec, identical in every runtime. */
+const WS_OPEN = 1;
+const wakeChannel = (channel) => {
+	channel.wake?.();
+	channel.wake = null;
+};
+const subscribeFrame = (sessions) => {
+	return JSON.stringify({
+		kind: "subscribe",
+		sessions
+	});
+};
+const wsTransport = (url, webSocketImpl, presence) => {
+	const channels = /* @__PURE__ */ new Map();
+	const pending = /* @__PURE__ */ new Map();
+	/** Push retries parked in `awaitReady`, flushed per session on its
+	* subscribe confirmation. */
+	const readyWaiters = /* @__PURE__ */ new Map();
+	let socket = null;
+	let socketOpen = false;
+	let watchdog;
+	let nextReq = 1;
+	const flushReadyWaiters = (sessionId) => {
+		const waiters = readyWaiters.get(sessionId);
+		if (!waiters) return;
+		readyWaiters.delete(sessionId);
+		for (const waiter of waiters) waiter();
+	};
+	const socketUrl = () => {
+		let resolved;
+		if (/^(https?|wss?):\/\//i.test(url)) resolved = new URL(url);
+		else {
+			const base = globalThis.location?.href;
+			if (base === void 0) throw new TypeError(`cannot resolve the relative ws url '${url}' without a browser location — pass an absolute ws:// or wss:// url`);
+			resolved = new URL(url, base);
+		}
+		if (resolved.protocol === "http:") resolved.protocol = "ws:";
+		else if (resolved.protocol === "https:") resolved.protocol = "wss:";
+		return resolved.href;
+	};
+	const trySend = (data) => {
+		if (socket === null || !socketOpen) return;
+		try {
+			socket.send(data);
+		} catch {}
+	};
+	const deliver = (channel, frame) => {
+		channel.queue.push(frame);
+		wakeChannel(channel);
+	};
+	const settleChannel = (channel, failure) => {
+		if (channel.ended) return;
+		channel.ended = true;
+		channel.failure = failure;
+		wakeChannel(channel);
+	};
+	const releaseSocket = () => {
+		const current = socket;
+		socket = null;
+		socketOpen = false;
+		clearTimeout(watchdog);
+		watchdog = void 0;
+		if (pending.size > 0) {
+			const rejection = new A2Error("STORE_UNAVAILABLE", "socket closed with the ack outstanding");
+			for (const waiter of pending.values()) waiter.reject(rejection);
+			pending.clear();
+		}
+		return current;
+	};
+	const failSocket = (failure) => {
+		const current = releaseSocket();
+		for (const channel of channels.values()) settleChannel(channel, failure);
+		try {
+			current?.close(1e3);
+		} catch {}
+	};
+	const detach = (channel) => {
+		if (channels.get(channel.sessionId) !== channel) return;
+		channels.delete(channel.sessionId);
+		if (!channel.dropped) {
+			const frame = {
+				kind: "unsubscribe",
+				sessions: [channel.sessionId]
+			};
+			trySend(JSON.stringify(frame));
+		}
+		if (channels.size === 0) {
+			const current = releaseSocket();
+			try {
+				current?.close(1e3);
+			} catch {}
+		}
+	};
+	const armWatchdog = (created) => {
+		clearTimeout(watchdog);
+		watchdog = setTimeout(() => {
+			if (socket !== created) return;
+			failSocket(/* @__PURE__ */ new Error(`socket stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`));
+		}, STREAM_TIMINGS.stallTimeoutMs);
+		watchdog.unref?.();
+	};
+	const route = (frame) => {
+		switch (frame.kind) {
+			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;
+				channel.live = true;
+				deliver(channel, { kind: "ping" });
+				flushReadyWaiters(frame.sessionId);
+				return;
+			}
+			case "unsubscribed": {
+				const channel = channels.get(frame.sessionId);
+				if (channel === void 0) return;
+				channel.dropped = true;
+				settleChannel(channel, frame.reason === void 0 ? null : new Error(frame.reason));
+				return;
+			}
+			case "ack": {
+				const waiter = pending.get(frame.req);
+				if (waiter === void 0) return;
+				pending.delete(frame.req);
+				if ("events" in frame) waiter.resolve(frame.events);
+				else waiter.reject(frame.error);
+				return;
+			}
+			case "event": {
+				const channel = channels.get(frame.event.sessionId);
+				if (channel !== void 0 && channel.live && !channel.ended) deliver(channel, {
+					kind: "event",
+					event: frame.event
+				});
+				return;
+			}
+			case "presence": {
+				if (!presence || frame.sessionId === void 0) return;
+				const channel = channels.get(frame.sessionId);
+				if (channel !== void 0 && channel.live && !channel.ended) deliver(channel, {
+					kind: "presence",
+					patch: frame.patch
+				});
+				return;
+			}
+			case "presence-snapshot": {
+				if (!presence || frame.sessionId === void 0) return;
+				const channel = channels.get(frame.sessionId);
+				if (channel !== void 0 && channel.live && !channel.ended) deliver(channel, {
+					kind: "presence-snapshot",
+					snapshot: frame.snapshot
+				});
+				return;
+			}
+		}
+	};
+	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(socketUrl());
+		socket = created;
+		socketOpen = false;
+		armWatchdog(created);
+		created.addEventListener("open", () => {
+			if (socket !== created) return;
+			socketOpen = true;
+			armWatchdog(created);
+			const sessions = [...channels.values()].filter((channel) => !channel.ended).map((channel) => ({
+				id: channel.sessionId,
+				index: channel.startAfter
+			}));
+			if (sessions.length > 0) trySend(subscribeFrame(sessions));
+		});
+		created.addEventListener("message", (event) => {
+			if (socket !== created) return;
+			if (typeof event.data !== "string") return;
+			armWatchdog(created);
+			const frame = parseSocketFrame(event.data);
+			if (frame === null) return;
+			route(frame);
+		});
+		created.addEventListener("close", (event) => {
+			if (socket !== created) return;
+			failSocket(event.code === 1e3 ? null : /* @__PURE__ */ new Error(`socket closed (${event.code}${event.reason ? `: ${event.reason}` : ""})`));
+		});
+		created.addEventListener("error", () => {
+			if (socket !== created) return;
+			failSocket(/* @__PURE__ */ new Error("socket error"));
+		});
+	};
+	return {
+		async *connect({ sessionId, startAfter, signal }) {
+			const channel = {
+				sessionId,
+				startAfter,
+				queue: [],
+				live: false,
+				dropped: false,
+				ended: false,
+				failure: null,
+				wake: null
+			};
+			channels.set(sessionId, channel);
+			try {
+				ensureSocket();
+				if (socketOpen) trySend(subscribeFrame([{
+					id: sessionId,
+					index: startAfter
+				}]));
+			} catch (error) {
+				if (channels.get(sessionId) === channel) channels.delete(sessionId);
+				throw error;
+			}
+			const onAbort = () => {
+				settleChannel(channel, signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("stream aborted"));
+				detach(channel);
+			};
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+			const pendingSubscribe = setTimeout(() => {
+				if (channel.live) return;
+				settleChannel(channel, /* @__PURE__ */ new Error("subscribe not confirmed: is the ws route serving the multiplexed socket (handle with options.upgrade)?"));
+			}, STREAM_TIMINGS.stallTimeoutMs);
+			pendingSubscribe.unref?.();
+			try {
+				for (;;) {
+					while (channel.queue.length > 0) yield channel.queue.shift();
+					if (channel.ended) {
+						if (channel.failure) throw channel.failure;
+						return;
+					}
+					await new Promise((resolve) => {
+						channel.wake = resolve;
+					});
+				}
+			} finally {
+				clearTimeout(pendingSubscribe);
+				signal.removeEventListener("abort", onAbort);
+				settleChannel(channel, null);
+				detach(channel);
+			}
+		},
+		async push(body) {
+			const channel = channels.get(body.sessionId);
+			const target = socket;
+			if (channel === void 0 || !channel.live || channel.ended || target === null || !socketOpen || target.readyState !== WS_OPEN) throw new A2Error("STORE_UNAVAILABLE", "no open socket for the session");
+			const req = nextReq;
+			nextReq += 1;
+			return await new Promise((resolve, reject) => {
+				pending.set(req, {
+					resolve,
+					reject
+				});
+				const frame = {
+					kind: "push",
+					req,
+					sessionId: body.sessionId,
+					events: body.events
+				};
+				try {
+					target.send(JSON.stringify(frame));
+				} catch (cause) {
+					pending.delete(req);
+					reject(new A2Error("STORE_UNAVAILABLE", "socket send failed", { cause }));
+				}
+			});
+		},
+		awaitReady(sessionId, maxWaitMs) {
+			const channel = channels.get(sessionId);
+			if (channel !== void 0 && channel.live && !channel.ended && socketOpen) return Promise.resolve();
+			return new Promise((resolve) => {
+				let waiters = readyWaiters.get(sessionId);
+				if (!waiters) {
+					waiters = /* @__PURE__ */ new Set();
+					readyWaiters.set(sessionId, waiters);
+				}
+				let settled = false;
+				const done = () => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timer);
+					waiters.delete(done);
+					if (waiters.size === 0) readyWaiters.delete(sessionId);
+					resolve();
+				};
+				const timer = setTimeout(done, maxWaitMs);
+				timer.unref?.();
+				waiters.add(done);
+			});
+		},
+		sendPresence(envelope) {
+			const channel = channels.get(envelope.sessionId);
+			if (channel === void 0 || !channel.live || channel.ended) return;
+			const frame = {
+				kind: "presence",
+				sessionId: envelope.sessionId,
+				...envelope.presence
+			};
+			trySend(JSON.stringify(frame));
+		}
+	};
+};
+const transportFor = (api, fetchImpl, webSocketImpl, presence) => {
+	if (typeof api === "string") return httpTransport({
+		push: api,
+		stream: api
+	}, fetchImpl, presence);
+	if (api.type === "http") return httpTransport({
+		push: api.push,
+		stream: api.stream
+	}, fetchImpl, presence);
+	return wsTransport(api.url, webSocketImpl, presence);
+};
+function createClient(options) {
+	const { reducer, api } = options;
+	const presenceDefs = reducer.presence;
+	const declaresPresence = Object.keys(presenceDefs).length > 0;
+	const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const webSocketImpl = options.webSocket ?? globalThis.WebSocket;
+	const transport = transportFor(api, fetchImpl, webSocketImpl, declaresPresence);
+	const gcTime = options.gcTime ?? DEFAULT_GC_TIME_MS;
+	if (Number.isNaN(gcTime) || gcTime < 0) throw new RangeError("gcTime must be a non-negative number or Infinity");
+	const sessions = /* @__PURE__ */ new Map();
+	const scheduleGc = (sessionId, delay = gcTime) => {
+		const entry = sessions.get(sessionId);
+		if (!entry) return;
+		clearTimeout(entry.timer);
+		if (gcTime === Infinity) return;
+		entry.timer = setTimeout(() => {
+			if (sessions.get(sessionId) !== entry) return;
+			if (entry.runtime.canEvict()) {
+				sessions.delete(sessionId);
+				return;
+			}
+			scheduleGc(sessionId, Math.max(gcTime, 1e3));
+		}, delay);
+		entry.timer.unref?.();
+	};
+	const touch = (sessionId) => {
+		scheduleGc(sessionId);
+	};
+	const makeSession = (sessionId, sessionOptions) => {
+		let frontier = sessionOptions?.initialIndex ?? 0;
+		let foldedState = sessionOptions?.initialState !== void 0 ? sessionOptions.initialState : reducer.initialState;
+		const serverEvents = (sessionOptions?.initialEvents ?? []).filter((event) => event.index <= frontier).toSorted((a, b) => a.index - b.index);
+		let pending = [];
+		let participant = sessionOptions?.participant;
+		let presenceState = nullProtoRecord();
+		let presenceLastSentAt = 0;
+		/** The last LWW stamp issued — see `nextPresenceAt`. */
+		let presenceLastAt = 0;
+		/** Values awaiting the trailing send — non-null exactly while
+		* `presenceTimer` is armed. */
+		let presenceBuffer = null;
+		let presenceTimer;
+		/** Own fields set while the stream was down — re-sent once on
+		* reconnect (their POSTs may have been lost with the network). */
+		let presenceResend = null;
+		const listeners = /* @__PURE__ */ new Set();
+		let snapshot = null;
+		let status = "idle";
+		let reconnects = 0;
+		let lastError = null;
+		let inFlightPushes = 0;
+		let pushWireTail = Promise.resolve();
+		let deferredHydration;
+		let hydrationNotification;
+		const emit = () => {
+			for (const listener of [...listeners]) listener();
+		};
+		const notify = () => {
+			snapshot = null;
+			emit();
+		};
+		const notifyHydrated = () => {
+			snapshot = null;
+			clearTimeout(hydrationNotification);
+			hydrationNotification = setTimeout(emit, 0);
+			hydrationNotification.unref?.();
+		};
+		const mergeServerEvents = (events, throughIndex) => {
+			if (!events || events.length === 0) return false;
+			const byIndex = new Map(serverEvents.map((event) => [event.index, event]));
+			let changed = false;
+			for (const event of events) {
+				if (event.index > throughIndex) continue;
+				if (byIndex.get(event.index)?.id === event.id) continue;
+				byIndex.set(event.index, event);
+				changed = true;
+			}
+			if (!changed) return false;
+			serverEvents.splice(0, serverEvents.length, ...[...byIndex.values()].toSorted((a, b) => a.index - b.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 = acked.at(-1)?.index ?? frontier;
+			const unacked = pending.filter((p) => !p.acked).map((p, i) => ({
+				id: p.id,
+				type: p.type,
+				payload: p.payload,
+				index: maxKnown + 1 + i,
+				sessionId,
+				createdAt: p.createdAt
+			}));
+			return [...acked, ...unacked];
+		};
+		const connection = () => {
+			switch (status) {
+				case "idle": return { status: "idle" };
+				case "closed": return { status: "closed" };
+				case "live": return {
+					status: "live",
+					reconnects
+				};
+				case "connecting": return {
+					status: "connecting",
+					reconnects,
+					error: lastError
+				};
+			}
+		};
+		const historyState = () => {
+			const oldestLoaded = serverEvents[0]?.index ?? null;
+			return {
+				loading: historyLoads > 0,
+				complete: oldestLoaded === 1 || frontier === 0,
+				oldestLoaded
+			};
+		};
+		const buildSnapshot = () => {
+			const overlay = overlayEvents();
+			let state = foldedState;
+			for (const event of overlay) state = reducer.fold(state, event);
+			return {
+				state,
+				events: [...serverEvents, ...overlay],
+				index: frontier,
+				history: historyState(),
+				connection: connection(),
+				...declaresPresence ? { presence: presenceState } : {}
+			};
+		};
+		/**
+		* The per-session monotonic LWW stamp: wall-seeded, guarded
+		* `max(now, last + 1)`, so overlapping sends can never invert —
+		* the wall clock seeds it because it is the only monotonic state
+		* that survives a reload without A2 owning persistence.
+		*/
+		const nextPresenceAt = () => {
+			presenceLastAt = Math.max(Date.now(), presenceLastAt + 1);
+			return presenceLastAt;
+		};
+		const applyPresencePatch = (patch) => {
+			if (patch.participant === participant) return;
+			const entry = Object.assign(nullProtoRecord(), presenceState[patch.participant]);
+			let changed = false;
+			for (const [field, value] of Object.entries(patch.values)) {
+				if (value === void 0) continue;
+				const existing = entry[field];
+				if (existing && existing.at.getTime() > patch.at.getTime()) continue;
+				if (value === null) {
+					if (existing) {
+						delete entry[field];
+						changed = true;
+					}
+				} else {
+					entry[field] = {
+						value,
+						seen: patch.seen,
+						at: patch.at
+					};
+					changed = true;
+				}
+			}
+			if (!changed) return;
+			const next = Object.assign(nullProtoRecord(), presenceState);
+			if (Object.keys(entry).length === 0) delete next[patch.participant];
+			else next[patch.participant] = entry;
+			presenceState = next;
+			notify();
+		};
+		const applyPresenceSnapshot = (incoming) => {
+			const next = nullProtoRecord();
+			for (const [id, fields] of Object.entries(incoming)) {
+				if (id === participant) continue;
+				next[id] = fields;
+			}
+			const own = participant === void 0 ? void 0 : presenceState[participant];
+			if (participant !== void 0 && own !== void 0) next[participant] = own;
+			presenceState = next;
+			notify();
+		};
+		const echoPresence = (id, values, atMs) => {
+			const entry = Object.assign(nullProtoRecord(), presenceState[id]);
+			const at = new Date(atMs);
+			for (const [field, value] of Object.entries(values)) if (value === null) delete entry[field];
+			else entry[field] = {
+				value,
+				seen: frontier,
+				at
+			};
+			const next = Object.assign(nullProtoRecord(), presenceState);
+			if (Object.keys(entry).length === 0) delete next[id];
+			else next[id] = entry;
+			presenceState = next;
+			notify();
+		};
+		const sendPresence = (values, at) => {
+			presenceLastSentAt = Date.now();
+			transport.sendPresence({
+				sessionId,
+				presence: {
+					participant,
+					values,
+					seen: frontier,
+					at
+				}
+			});
+			touch(sessionId);
+		};
+		const queuePresenceSend = (values, at) => {
+			if (presenceTimer !== void 0) {
+				presenceBuffer = {
+					...presenceBuffer,
+					...values
+				};
+				return;
+			}
+			const wait = presenceLastSentAt + PRESENCE_TIMINGS.sendIntervalMs - Date.now();
+			if (wait <= 0) {
+				sendPresence(values, at ?? nextPresenceAt());
+				return;
+			}
+			presenceBuffer = {
+				...presenceBuffer,
+				...values
+			};
+			presenceTimer = setTimeout(() => {
+				presenceTimer = void 0;
+				const buffered = presenceBuffer;
+				presenceBuffer = null;
+				if (buffered) sendPresence(buffered, nextPresenceAt());
+			}, wait);
+			presenceTimer.unref?.();
+		};
+		const setPresence = (values) => {
+			if (participant === void 0) throw new TypeError("setPresence requires a participant — pass one in the session options (the SessionProvider participant prop)");
+			const validated = nullProtoRecord();
+			for (const [field, value] of Object.entries(values)) {
+				if (value === void 0) continue;
+				const schema = Object.hasOwn(presenceDefs, field) ? presenceDefs[field] : void 0;
+				if (!schema) throw new A2Error("UNKNOWN_PRESENCE_FIELD", `no presence field '${field}' in the reducer's vocabulary`);
+				if (value === null) {
+					validated[field] = null;
+					continue;
+				}
+				const result = validateSync(schema, value, `presence field '${field}'`);
+				if (result.issues) throw new A2Error("INVALID_PAYLOAD", `invalid value for presence field '${field}'`, { details: result.issues });
+				validated[field] = result.value;
+			}
+			if (Object.keys(validated).length === 0) return;
+			const at = nextPresenceAt();
+			echoPresence(participant, validated, at);
+			if (status !== "live") presenceResend = {
+				...presenceResend,
+				...validated
+			};
+			queuePresenceSend(validated, at);
+			touch(sessionId);
+		};
+		/** Pushes awaiting stream confirmation — resolved by `ingest` the
+		* moment the frontier passes their batch. */
+		let confirmWatchers = [];
+		/** The single ingest point: every server-confirmed event, in log
+		* order, from the stream. */
+		const ingest = (event) => {
+			if (event.index <= frontier) return;
+			frontier = event.index;
+			serverEvents.push(event);
+			foldedState = reducer.fold(foldedState, event);
+			pending = pending.filter((p) => p.id !== event.id);
+			if (confirmWatchers.some((w) => w.index <= frontier)) {
+				const due = confirmWatchers.filter((w) => w.index <= frontier);
+				confirmWatchers = confirmWatchers.filter((w) => w.index > frontier);
+				for (const watcher of due) watcher.resolve();
+			}
+			notify();
+			touch(sessionId);
+		};
+		const validated = (events) => events.map((event) => {
+			const schema = Object.hasOwn(reducer.events, event.type) ? reducer.events[event.type] : void 0;
+			if (!schema) throw new A2Error("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 A2Error("INVALID_PAYLOAD", `invalid payload for event '${String(event.type)}'`, { details: result.issues });
+			return {
+				id: event.id ?? crypto.randomUUID(),
+				type: event.type,
+				payload: result.value
+			};
+		});
+		const post = async (body) => {
+			let lastPushError = new A2Error("STORE_UNAVAILABLE", "push failed");
+			for (let attempt = 1; attempt <= PUSH_ATTEMPTS; attempt += 1) {
+				try {
+					return (await transport.push(body)).map((row) => eventFromWire(row));
+				} catch (err) {
+					lastPushError = err instanceof A2Error ? err : new A2Error("STORE_UNAVAILABLE", "push request failed", { cause: err });
+				}
+				if (lastPushError.code !== "STORE_UNAVAILABLE") throw lastPushError;
+				if (attempt < PUSH_ATTEMPTS) {
+					const sleepMs = 250 * attempt;
+					await Promise.all([new Promise((resolve) => setTimeout(resolve, sleepMs)), transport.awaitReady?.(sessionId, sleepMs + STREAM_TIMINGS.reconnectBaseMs * attempt)]);
+				}
+			}
+			throw lastPushError;
+		};
+		/**
+		* Decorate the ack promise into a PushResult. `confirmed` is a
+		* lazy getter — materialized on first access, so callers that
+		* ignore it can't leak an unhandled rejection.
+		*/
+		const withConfirmed = (ack) => {
+			let confirmed;
+			return Object.defineProperty(ack, "confirmed", { get() {
+				confirmed ??= ack.then((acked) => new Promise((resolve) => {
+					const last = acked.at(-1)?.index ?? 0;
+					if (frontier >= last) {
+						resolve(acked);
+						return;
+					}
+					confirmWatchers.push({
+						index: last,
+						resolve: () => resolve(acked)
+					});
+				}));
+				return confirmed;
+			} });
+		};
+		const push = (...events) => {
+			touch(sessionId);
+			return withConfirmed((async () => {
+				if (events.length === 0) throw new TypeError("push requires at least one event");
+				const entries = validated(events).map((e) => ({
+					id: e.id,
+					type: e.type,
+					payload: e.payload,
+					createdAt: /* @__PURE__ */ new Date()
+				}));
+				const waitForPriorPush = pushWireTail;
+				let releasePush;
+				pushWireTail = new Promise((resolve) => {
+					releasePush = resolve;
+				});
+				pending.push(...entries);
+				inFlightPushes += 1;
+				try {
+					notify();
+					await waitForPriorPush;
+					const acked = await post({
+						sessionId,
+						events: entries.map(({ id, type, payload }) => ({
+							id,
+							type,
+							payload
+						}))
+					});
+					for (const event of acked) {
+						const entry = pending.find((p) => p.id === event.id);
+						if (entry) entry.acked = event;
+					}
+					notify();
+					return acked;
+				} catch (err) {
+					const ids = new Set(entries.map((e) => e.id));
+					pending = pending.filter((p) => !ids.has(p.id));
+					notify();
+					throw err;
+				} finally {
+					releasePush();
+					inFlightPushes -= 1;
+					if (inFlightPushes === 0 && deferredHydration) {
+						const next = deferredHydration;
+						deferredHydration = void 0;
+						runtime.hydrate(next);
+					}
+					touch(sessionId);
+				}
+			})());
+		};
+		let historyLoads = 0;
+		/** Calls chain per session: each resolves its bounds after the
+		* prior call's merge, so overlapping backscrolls page backward
+		* instead of re-fetching the same range. */
+		let historyTail = Promise.resolve();
+		const eventsBetween = (gte, lte) => serverEvents.filter((event) => event.index >= gte && event.index <= lte);
+		/** The narrowest sub-range of [gte, lte] missing from the feed, or
+		* null when the range is fully loaded (nothing to fetch). */
+		const missingBetween = (gte, lte) => {
+			const present = new Set(eventsBetween(gte, lte).map((e) => e.index));
+			let lo = gte;
+			while (lo <= lte && present.has(lo)) lo += 1;
+			if (lo > lte) return null;
+			let hi = lte;
+			while (hi > lo && present.has(hi)) hi -= 1;
+			return {
+				gte: lo,
+				lte: hi
+			};
+		};
+		const loadHistory = (loadOptions) => {
+			const readHistory = transport.history;
+			if (readHistory === void 0) throw new TypeError("loadHistory requires an http api — the ws transport has no history lane; serve the session over handle() and pass its route url as the string or { type: \"http\" } api");
+			const before = loadOptions?.before;
+			const limit = loadOptions?.limit;
+			if (before !== void 0 && (!Number.isSafeInteger(before) || before < 1)) throw new TypeError("loadHistory before must be a positive safe integer");
+			if (limit !== void 0 && (!Number.isSafeInteger(limit) || limit < 1)) throw new TypeError("loadHistory limit must be a positive safe integer");
+			touch(sessionId);
+			const run = historyTail.then(async () => {
+				const upper = before ?? serverEvents[0]?.index ?? frontier + 1;
+				const lte = Math.min(upper - 1, frontier);
+				const gte = Math.max(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({
+						sessionId,
+						...missing
+					});
+					mergeServerEvents(rows.map((row) => eventFromWire(row)), frontier);
+					return eventsBetween(gte, lte);
+				} finally {
+					historyLoads -= 1;
+					notify();
+					touch(sessionId);
+				}
+			});
+			historyTail = run.catch(() => {});
+			return run;
+		};
+		let generation = 0;
+		let active = false;
+		let abort = null;
+		const runStream = async (run) => {
+			let backoff = STREAM_TIMINGS.reconnectBaseMs;
+			while (generation === run) {
+				const controller = new AbortController();
+				abort = controller;
+				let stall;
+				let stalled = false;
+				const armStall = () => {
+					clearTimeout(stall);
+					stall = setTimeout(() => {
+						stalled = true;
+						controller.abort();
+					}, STREAM_TIMINGS.stallTimeoutMs);
+					stall.unref?.();
+				};
+				let wasLive = false;
+				try {
+					const frames = transport.connect({
+						sessionId,
+						startAfter: frontier,
+						signal: controller.signal
+					});
+					for await (const frame of frames) {
+						if (generation !== run) break;
+						armStall();
+						if (!wasLive) {
+							backoff = STREAM_TIMINGS.reconnectBaseMs;
+							wasLive = true;
+							status = "live";
+							lastError = null;
+							notify();
+							if (presenceResend) {
+								const values = presenceResend;
+								presenceResend = null;
+								queuePresenceSend(values);
+							}
+						}
+						if (frame.kind === "event") ingest(eventFromWire(frame.event));
+						else if (frame.kind === "presence") applyPresencePatch(presencePatchFromWire(frame.patch));
+						else if (frame.kind === "presence-snapshot") applyPresenceSnapshot(presenceSnapshotFromWire(frame.snapshot).snapshot);
+					}
+					if (generation === run) lastError = null;
+				} catch (err) {
+					if (generation === run) lastError = stalled ? /* @__PURE__ */ new Error(`stream stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`) : err instanceof Error ? err : new Error(String(err));
+				} finally {
+					clearTimeout(stall);
+				}
+				if (generation !== run) break;
+				if (wasLive) reconnects += 1;
+				status = "connecting";
+				notify();
+				await new Promise((resolve) => {
+					let settled = false;
+					const finish = () => {
+						if (settled) return;
+						settled = true;
+						clearTimeout(timer);
+						resolve();
+					};
+					const timer = setTimeout(finish, backoff);
+					timer.unref?.();
+					abort?.signal.addEventListener("abort", finish);
+				});
+				backoff = Math.min(backoff * 2, STREAM_TIMINGS.reconnectMaxMs);
+			}
+		};
+		const runtime = {
+			sessionId,
+			...declaresPresence ? { setPresence } : {},
+			subscribe(listener) {
+				touch(sessionId);
+				listeners.add(listener);
+				return () => {
+					listeners.delete(listener);
+					touch(sessionId);
+				};
+			},
+			getSnapshot() {
+				snapshot ??= buildSnapshot();
+				return snapshot;
+			},
+			push,
+			loadHistory,
+			connect() {
+				touch(sessionId);
+				if (active) return;
+				active = true;
+				status = "connecting";
+				notify();
+				runStream(generation);
+			},
+			close() {
+				touch(sessionId);
+				if (!active) return;
+				active = false;
+				generation += 1;
+				abort?.abort();
+				abort = null;
+				clearTimeout(presenceTimer);
+				presenceTimer = void 0;
+				presenceBuffer = null;
+				status = "closed";
+				notify();
+			},
+			hydrate(next) {
+				touch(sessionId);
+				if (!next) return;
+				participant ??= next.participant;
+				const nextIndex = next.initialIndex ?? 0;
+				if (nextIndex > frontier && inFlightPushes > 0) {
+					if (!deferredHydration || nextIndex > (deferredHydration.initialIndex ?? 0)) deferredHydration = next;
+					return;
+				}
+				const historyChanged = mergeServerEvents(next.initialEvents, Math.min(nextIndex, frontier));
+				if (next.initialState === void 0 || nextIndex <= frontier) {
+					if (historyChanged) notifyHydrated();
+					return;
+				}
+				frontier = nextIndex;
+				foldedState = next.initialState;
+				mergeServerEvents(next.initialEvents, frontier);
+				pending = pending.filter((entry) => !entry.acked || entry.acked.index > frontier);
+				if (confirmWatchers.some((watcher) => watcher.index <= frontier)) {
+					const due = confirmWatchers.filter((watcher) => watcher.index <= frontier);
+					confirmWatchers = confirmWatchers.filter((watcher) => watcher.index > frontier);
+					for (const watcher of due) watcher.resolve();
+				}
+				notifyHydrated();
+			},
+			canEvict() {
+				return listeners.size === 0 && !active && inFlightPushes === 0 && historyLoads === 0 && confirmWatchers.length === 0 && presenceTimer === void 0;
+			}
+		};
+		return runtime;
+	};
+	return { session(sessionId, sessionOptions) {
+		const existing = sessions.get(sessionId);
+		if (existing) {
+			existing.runtime.hydrate(sessionOptions);
+			touch(sessionId);
+			return existing.runtime;
+		}
+		const runtime = makeSession(sessionId, sessionOptions);
+		sessions.set(sessionId, { runtime });
+		touch(sessionId);
+		return runtime;
+	} };
+}
+//#endregion
+export { createClient as t };
+
+//# sourceMappingURL=client-BKlyLiOU.js.map