react-websocket 3.6.0 → 4.18.0

package/dist/core.cjs

@@ -31,8 +31,43 @@ const RECONNECT_DEFAULTS = {
 	minDelay: 1e3,
 	maxDelay: 3e4,
 	factor: 2,
-	jitter: .5
+	jitter: 1,
+	minUptime: 5e3
 };
+const QUEUE_LIMIT = 100;
+const MAX_TIMEOUT = 2 ** 31 - 1;
+/**
+* The default `reconnect.shouldReconnect`: retry every close except `1002` (protocol error),
+* `1003` (unsupported data) and `1008` (policy violation, often a rejected login), which
+* retrying the same way can't fix. Call it from your own `shouldReconnect` to keep that rule.
+*
+* @example
+* ```ts
+* createWebSocket(url, {
+*   // Also stop on our server's "invalid token" code.
+*   reconnect: { shouldReconnect: close => close.code !== 4001 && retryableClose(close) }
+* });
+* ```
+*/
+function retryableClose(close) {
+	return close.code !== 1002 && close.code !== 1003 && close.code !== 1008;
+}
+/**
+* The default `reconnect.retryAfter`: for a `1012` (Service Restart) or `1013` (Try Again Later)
+* close whose reason is a number of seconds, like an HTTP `Retry-After` header, that delay in ms.
+* Call it from your own `retryAfter` to keep reading it.
+*
+* @example
+* ```ts
+* createWebSocket(url, {
+*   // Our server also closes with 4429 and the delay in ms as the reason.
+*   reconnect: { retryAfter: close => (close.code === 4429 ? Number(close.reason) : retryAfter(close)) }
+* });
+* ```
+*/
+function retryAfter(close) {
+	return (close.code === 1012 || close.code === 1013) && /^\s*\d+(\.\d+)?\s*$/.test(close.reason) ? Number(close.reason) * 1e3 : void 0;
+}
 const READY_GRACE = 5e3;
 function createDeferred() {
 	let resolve;
@@ -77,6 +112,10 @@ function isThenable(value) {
 * because the hooks entry imports the client from the `core` entry at runtime.
 */
 const ON_TEARDOWN = Symbol.for("react-websocket.onTeardown");
+/** @internal Method key on a socket that sends `volatile` messages as datagrams (WebTransport). */
+const DATAGRAM = Symbol.for("react-websocket.datagram");
+/** @internal Method key for what `react-websocket/devtools` shows that the snapshot doesn't. */
+const INSPECT = Symbol.for("react-websocket.inspect");
 function createClient(url, options = {}) {
 	const onTeardown = options[ON_TEARDOWN];
 	const log = options.logger ?? (() => {});
@@ -84,7 +123,9 @@ function createClient(url, options = {}) {
 		...RECONNECT_DEFAULTS,
 		...typeof options.reconnect === "object" ? options.reconnect : {}
 	};
-	const queueLimit = options.queue === false ? 0 : typeof options.queue === "object" ? Math.max(0, options.queue.limit ?? Infinity) : Infinity;
+	const queue = typeof options.queue === "object" ? options.queue : {};
+	const queueLimit = options.queue === false ? 0 : Math.max(0, queue.limit ?? QUEUE_LIMIT);
+	const queueMaxAge = queue.maxAge ?? Infinity;
 	let snapshot = {
 		status: "idle",
 		lastMessage: void 0,
@@ -98,9 +139,13 @@ function createClient(url, options = {}) {
 		error: /* @__PURE__ */ new Set()
 	};
 	let ws = null;
+	let incoming = null;
+	let replaced = null;
+	let moved;
 	let wanted = false;
 	let refs = 0;
 	let pinned = false;
+	let unheldStop = false;
 	let pending = [];
 	let ready = null;
 	let opened = false;
@@ -109,8 +154,12 @@ function createClient(url, options = {}) {
 	let inbox = null;
 	let generation = 0;
 	let windowBound = false;
+	let failures = 0;
+	let serverWait = false;
 	let retryTimer;
+	let migrateTimer;
 	let teardownTimer;
+	let stableTimer;
 	let heartbeatTimer;
 	let pongTimer;
 	function set(patch) {
@@ -133,54 +182,62 @@ function createClient(url, options = {}) {
 	}
 	function getImpl() {
 		if (options.WebSocket) return options.WebSocket;
-		return typeof window === "undefined" ? void 0 : globalThis.WebSocket;
+		return typeof window === "undefined" && typeof WorkerGlobalScope === "undefined" ? void 0 : globalThis.WebSocket;
 	}
 	function rejectReady(reason) {
 		if (!ready || ready.settled) ready = createDeferred();
 		ready.reject(reason);
 	}
-	function retryNow() {
+	/** The network or the tab came back: retry now, or check that an open connection still works. */
+	function wake() {
 		if (retryTimer !== void 0) {
+			if (serverWait) return;
 			log("network or visibility change, retrying now");
 			open();
+		} else if (heartbeatTimer !== void 0 && pongTimer === void 0) {
+			log("network or visibility change, checking the connection");
+			ping(ws);
 		}
 	}
 	function onVisibilityChange() {
-		if (document.visibilityState === "visible") retryNow();
+		if (document.visibilityState === "visible") wake();
 	}
 	function bindWindow() {
-		if (windowBound || typeof window === "undefined") return;
+		if (windowBound || typeof addEventListener !== "function") return;
 		windowBound = true;
-		window.addEventListener("online", retryNow);
-		document.addEventListener("visibilitychange", onVisibilityChange);
+		addEventListener("online", wake);
+		if (typeof document !== "undefined") document.addEventListener("visibilitychange", onVisibilityChange);
 	}
 	function unbindWindow() {
 		if (!windowBound) return;
 		windowBound = false;
-		window.removeEventListener("online", retryNow);
-		document.removeEventListener("visibilitychange", onVisibilityChange);
+		removeEventListener("online", wake);
+		if (typeof document !== "undefined") document.removeEventListener("visibilitychange", onVisibilityChange);
 	}
-	function startHeartbeat(socket) {
+	/** Send a heartbeat ping and, with a `timeout`, close the socket if nothing comes back. */
+	function ping(socket) {
 		const heartbeat = options.heartbeat;
-		if (!heartbeat) return;
-		heartbeatTimer = setInterval(() => {
-			socket.send(heartbeat.message ?? "ping");
-			if (heartbeat.timeout && pongTimer === void 0) pongTimer = setTimeout(() => {
-				log("heartbeat timeout");
-				detach(socket, false);
-				socket.close(4e3, "heartbeat timeout");
-				handleClose({
-					code: 4e3,
-					reason: "heartbeat timeout",
-					wasClean: false
-				});
-			}, heartbeat.timeout);
-		}, heartbeat.interval);
+		socket.send(heartbeat.message ?? "ping");
+		if (heartbeat.timeout && pongTimer === void 0) pongTimer = setTimeout(() => {
+			log("heartbeat timeout");
+			detach(socket, false);
+			socket.close(4e3, "heartbeat timeout");
+			handleClose({
+				code: 4e3,
+				reason: "heartbeat timeout",
+				wasClean: false
+			});
+		}, heartbeat.timeout);
+	}
+	function startHeartbeat(socket) {
+		if (options.heartbeat) heartbeatTimer = setInterval(ping, options.heartbeat.interval, socket);
 	}
-	function stopHeartbeat() {
+	/** Stop the timers that belong to the current open socket. */
+	function stopSocketTimers() {
 		clearInterval(heartbeatTimer);
 		clearTimeout(pongTimer);
-		heartbeatTimer = pongTimer = void 0;
+		clearTimeout(stableTimer);
+		heartbeatTimer = pongTimer = stableTimer = void 0;
 	}
 	/** Stop tracking `socket`. Its eventual close event is still reported unless `reportClose` is false. */
 	function detach(socket, reportClose) {
@@ -192,65 +249,100 @@ function createClient(url, options = {}) {
 			wasClean: event.wasClean
 		}) : null;
 	}
-	function backoff(attempt) {
+	/** The delay before attempt `n`; `slow` starts at `maxDelay`, for a server shedding load. */
+	function backoff(attempt, slow) {
 		const { minDelay, maxDelay, factor, jitter } = retry;
-		const base = Math.min(maxDelay, minDelay * factor ** (attempt - 1));
+		const base = slow ? maxDelay : Math.min(maxDelay, minDelay * factor ** (attempt - 1));
 		return Math.round(base * (1 - jitter * Math.random()));
 	}
-	function open() {
-		clearTimeout(retryTimer);
-		retryTimer = void 0;
+	/** Stop a `migrate()` that hasn't switched yet. */
+	function dropIncoming() {
+		if (incoming) {
+			detach(incoming, false);
+			incoming.close();
+			incoming = null;
+		}
+	}
+	/**
+	* Start a connection attempt. A `handoff` (from `migrate()`) opens beside the current
+	* connection, which keeps working until the new one opens.
+	*/
+	function open(handoff) {
+		if (!handoff) {
+			clearTimeout(retryTimer);
+			retryTimer = void 0;
+			serverWait = false;
+			dropIncoming();
+		}
 		const Impl = getImpl();
 		if (!Impl) return;
 		const id = ++generation;
-		set({ status: snapshot.attempt === 0 ? "connecting" : "reconnecting" });
+		if (!handoff) set({ status: snapshot.attempt === 0 ? "connecting" : "reconnecting" });
+		const source = moved ?? url;
 		let target;
 		try {
-			target = typeof url === "string" ? url : url();
+			target = typeof source === "string" ? source : source();
 		} catch (error) {
-			urlFailed(error);
+			urlFailed(error, handoff);
 			return;
 		}
 		if (typeof target === "string") {
-			start(Impl, target);
+			start(Impl, target, handoff);
 			return;
 		}
 		Promise.resolve(target).then((resolved) => {
-			if (id === generation && wanted) start(Impl, resolved);
+			if (id === generation && wanted) start(Impl, resolved, handoff);
 		}, (error) => {
-			if (id === generation && wanted) urlFailed(error);
+			if (id === generation && wanted) urlFailed(error, handoff);
 		});
 	}
-	/** `url()` threw or rejected (e.g. a token refresh failed): count it as a failed attempt. */
-	function urlFailed(error) {
+	/**
+	* `url()` threw or rejected (e.g. a token refresh failed): count it as a failed attempt,
+	* unless it was for a handoff, which leaves the current connection in place.
+	*/
+	function urlFailed(error, handoff) {
 		const reason = error instanceof Error ? error : new Error(String(error));
 		log("url() failed", reason);
 		emit("error", reason);
-		retryOrFail({
+		if (!handoff) retryOrFail({
 			code: 1006,
 			reason: "url() failed",
 			wasClean: false
 		}, reason);
 	}
-	function start(Impl, target) {
+	function start(Impl, target, handoff) {
 		let socket;
 		try {
 			socket = new Impl(target, options.protocols);
 		} catch (error) {
 			emit("error", error);
-			fail(error);
+			if (!handoff) fail(error);
 			return;
 		}
 		if (options.binaryType) socket.binaryType = options.binaryType;
-		ws = socket;
+		if (handoff) incoming = socket;
+		else ws = socket;
 		log("connecting", target);
 		socket.onopen = (event) => {
+			if (handoff) {
+				incoming = null;
+				clearTimeout(retryTimer);
+				retryTimer = void 0;
+				stopSocketTimers();
+				if (ws) {
+					const old = replaced = ws;
+					detach(old, true);
+					old.close(1e3, "migrated");
+				}
+				ws = socket;
+			}
 			log("open");
 			opened = true;
 			set({
 				status: "open",
 				attempt: 0
 			});
+			if (retry) stableTimer = setTimeout(() => failures = 0, retry.minUptime);
 			startHeartbeat(socket);
 			ready?.resolve();
 			if (refs === 0 && !pinned) {
@@ -261,11 +353,20 @@ function createClient(url, options = {}) {
 			if (ws !== socket) return;
 			const queued = pending;
 			pending = [];
-			for (const { data } of queued) socket.send(data);
+			const now = Date.now();
+			for (const entry of queued) if (entry.expires >= now) socket.send(entry.data);
+			for (const entry of queued) if (entry.expires < now) expired(entry);
 		};
 		socket.onmessage = (event) => receive(event, socket);
-		socket.onerror = (event) => emit("error", event);
+		socket.onerror = (event) => {
+			if (ws === socket) emit("error", event);
+		};
 		socket.onclose = (event) => {
+			if (ws !== socket) {
+				incoming = null;
+				log("migrate() failed", event.code);
+				return;
+			}
 			detach(socket, false);
 			handleClose({
 				code: event.code,
@@ -275,15 +376,19 @@ function createClient(url, options = {}) {
 		};
 	}
 	function handleClose(info) {
-		stopHeartbeat();
+		replaced = null;
+		stopSocketTimers();
 		log("closed", info);
 		retryOrFail(info);
 		emit("close", info);
 	}
 	function retryOrFail(info, error) {
-		if (wanted && retry && snapshot.attempt < retry.maxAttempts && (retry.shouldReconnect?.(info) ?? true)) {
-			const attempt = snapshot.attempt + 1;
-			const delay = backoff(attempt);
+		if (wanted && retry && failures < retry.maxAttempts && (retry.shouldReconnect ?? retryableClose)(info)) {
+			const attempt = ++failures;
+			const asked = (retry.retryAfter ?? retryAfter)(info);
+			const named = asked >= 0;
+			const delay = Math.min(MAX_TIMEOUT, named ? asked + backoff(attempt, false) : backoff(attempt, info.code === 1013));
+			serverWait = named || info.code === 1013;
 			set({
 				status: "reconnecting",
 				attempt
@@ -292,12 +397,34 @@ function createClient(url, options = {}) {
 			retryTimer = setTimeout(open, delay);
 		} else fail(error ?? /* @__PURE__ */ new Error(`WebSocket closed (code ${info.code}${info.reason ? `: ${info.reason}` : ""})`));
 	}
+	/** Forget `migrate()`: its timer, its connection and the URL it moved to. */
+	function stopMigrating() {
+		clearTimeout(migrateTimer);
+		migrateTimer = void 0;
+		dropIncoming();
+		moved = void 0;
+	}
+	function migrate({ url: to, within } = {}) {
+		clearTimeout(migrateTimer);
+		dropIncoming();
+		migrateTimer = setTimeout(() => {
+			migrateTimer = void 0;
+			if (!wanted) return;
+			if (to !== void 0) moved = to;
+			if (snapshot.status === "open") open(true);
+		}, Math.min(MAX_TIMEOUT, Math.random() * (within ?? 0)));
+	}
 	function fail(reason) {
 		wanted = false;
 		opened = false;
+		unheldStop = refs === 0;
 		unbindWindow();
+		stopMigrating();
 		pending = [];
-		set({ status: "closed" });
+		set({
+			status: "closed",
+			attempt: failures
+		});
 		rejectReady(reason);
 	}
 	function receive(event, socket) {
@@ -345,7 +472,7 @@ function createClient(url, options = {}) {
 		else deliver(result.value, event, socket);
 	}
 	function deliver(message, event, socket) {
-		if (ws !== socket) return;
+		if (ws !== socket && replaced !== socket) return;
 		set({ lastMessage: message });
 		emit("message", message, event);
 	}
@@ -357,7 +484,9 @@ function createClient(url, options = {}) {
 				log("dropped message: send buffer above maxBuffered");
 				return false;
 			}
-			ws.send(data);
+			const datagram = sendOptions.volatile ? ws[DATAGRAM] : void 0;
+			if (datagram) datagram.call(ws, data);
+			else ws.send(data);
 			return true;
 		}
 		if (queueLimit === 0 || sendOptions.volatile) {
@@ -368,18 +497,18 @@ function createClient(url, options = {}) {
 			log("dropped message: no WebSocket implementation available");
 			return false;
 		}
-		if (key !== void 0) pending = pending.filter((entry) => {
-			if (entry.key !== key) return true;
-			dropped(entry);
-			return false;
-		});
+		const now = Date.now();
+		const before = pending;
+		pending = before.filter((entry) => entry.expires >= now && (key === void 0 || entry.key !== key));
+		for (const entry of before) if (!pending.includes(entry)) (entry.expires < now ? expired : dropped)(entry);
 		let head = pending.findIndex((entry) => !entry.priority);
 		if (head < 0) head = pending.length;
 		const entry = {
 			data,
 			key,
 			priority,
-			onDrop: sendOptions.onDrop
+			onDrop: sendOptions.onDrop,
+			expires: now + (sendOptions.maxAge ?? queueMaxAge)
 		};
 		if (priority) pending.splice(head++, 0, entry);
 		else pending.push(entry);
@@ -389,6 +518,10 @@ function createClient(url, options = {}) {
 		}
 		return false;
 	}
+	function expired(entry) {
+		log("dropped queued message: older than maxAge");
+		dropped(entry);
+	}
 	function dropped(entry) {
 		try {
 			entry.onDrop?.();
@@ -398,10 +531,12 @@ function createClient(url, options = {}) {
 	}
 	function begin() {
 		wanted = true;
+		unheldStop = false;
 		if (snapshot.status === "idle" || snapshot.status === "closed") {
 			opened = false;
 			if (ready?.settled) ready = null;
 		}
+		failures = 0;
 		snapshot = {
 			...snapshot,
 			attempt: 0
@@ -419,23 +554,25 @@ function createClient(url, options = {}) {
 		ensureConnecting();
 	}
 	function stop(code, reason) {
+		const socket = ws;
+		socket?.close(code, reason);
 		wanted = false;
 		generation++;
 		clearTimeout(retryTimer);
 		retryTimer = void 0;
-		stopHeartbeat();
+		failures = 0;
+		stopSocketTimers();
 		unbindWindow();
+		stopMigrating();
 		pending = [];
-		if (ws) {
-			const socket = ws;
-			detach(socket, true);
-			socket.close(code, reason);
-		}
+		replaced = null;
+		if (socket) detach(socket, true);
 	}
 	function close(code = 1e3, reason) {
+		stop(code, reason);
 		pinned = false;
 		opened = false;
-		stop(code, reason);
+		unheldStop = refs === 0;
 		set({
 			status: "closed",
 			attempt: 0
@@ -446,7 +583,7 @@ function createClient(url, options = {}) {
 		if (!getImpl()) return;
 		clearTimeout(retryTimer);
 		retryTimer = void 0;
-		stopHeartbeat();
+		stopSocketTimers();
 		if (ws) {
 			const socket = ws;
 			detach(socket, true);
@@ -469,7 +606,7 @@ function createClient(url, options = {}) {
 	function acquire() {
 		refs++;
 		clearTimeout(teardownTimer);
-		if (snapshot.status === "idle") ensureConnecting();
+		if (snapshot.status === "idle" || snapshot.status === "closed" && unheldStop) ensureConnecting();
 		let released = false;
 		return () => {
 			if (released) return;
@@ -523,7 +660,9 @@ function createClient(url, options = {}) {
 		connect,
 		close,
 		reconnect,
-		acquire
+		migrate,
+		acquire,
+		[INSPECT]: () => ({ queued: pending.length })
 	};
 }
 /**
@@ -549,6 +688,175 @@ function createWebSocket(url, options) {
 	return createClient(url, options);
 }
 //#endregion
+//#region src/topics.ts
+/** @internal Option key for a callback run when nothing holds a topic anymore. Used by feeds. */
+const ON_RELEASE = Symbol("react-websocket.onRelease");
+/**
+* Manage topic subscriptions that survive reconnects.
+*
+* - The first holder of a topic sends `subscribe(topic)`. Later holders share it.
+* - A tick after the last holder releases it, `unsubscribe(topic)` is sent, so StrictMode
+*   and route transitions don't churn subscriptions.
+* - After every reconnect, every held topic is subscribed again on the new socket, before
+*   messages queued while disconnected are sent.
+*
+* Subscriptions are only sent while the socket is open; nothing is queued for them.
+*
+* @example
+* ```ts
+* export const topics = createWebSocketTopics(live, {
+*   subscribe: topic => ({ type: 'subscribe', topic }),
+*   unsubscribe: topic => ({ type: 'unsubscribe', topic })
+* });
+*
+* // In a component:
+* useWebSocketTopic(topics, `prices:${symbol}`);
+* ```
+*/
+function createWebSocketTopics(client, options) {
+	const counts = /* @__PURE__ */ new Map();
+	const pendingRemoval = /* @__PURE__ */ new Map();
+	let sentOn = null;
+	let sent = /* @__PURE__ */ new Set();
+	function isOpen() {
+		return client.socket?.readyState === 1;
+	}
+	function subscribe(topic) {
+		if (!isOpen()) return;
+		if (client.socket !== sentOn) {
+			sentOn = client.socket;
+			sent = /* @__PURE__ */ new Set();
+		}
+		if (sent.has(topic)) return;
+		sent.add(topic);
+		client.send(options.subscribe(topic));
+	}
+	function unsubscribe(topic) {
+		if (!isOpen() || client.socket !== sentOn || !sent.delete(topic)) return;
+		if (options.unsubscribe) client.send(options.unsubscribe(topic));
+	}
+	const off = client.on("open", () => {
+		sentOn = client.socket;
+		sent = /* @__PURE__ */ new Set();
+		for (const topic of counts.keys()) subscribe(topic);
+	});
+	return {
+		client,
+		acquire(topic) {
+			const releaseConnection = client.acquire();
+			clearTimeout(pendingRemoval.get(topic));
+			pendingRemoval.delete(topic);
+			counts.set(topic, (counts.get(topic) ?? 0) + 1);
+			subscribe(topic);
+			let released = false;
+			return () => {
+				if (released) return;
+				released = true;
+				const remaining = (counts.get(topic) ?? 1) - 1;
+				if (remaining > 0) counts.set(topic, remaining);
+				else {
+					counts.delete(topic);
+					pendingRemoval.set(topic, setTimeout(() => {
+						pendingRemoval.delete(topic);
+						if (!counts.has(topic)) {
+							unsubscribe(topic);
+							options[ON_RELEASE]?.(topic);
+						}
+					}, 0));
+				}
+				releaseConnection();
+			};
+		},
+		active: () => [...counts.keys()],
+		dispose() {
+			off();
+			for (const timer of pendingRemoval.values()) clearTimeout(timer);
+			pendingRemoval.clear();
+		}
+	};
+}
+//#endregion
+//#region src/feeds.ts
+/**
+* Subscribe to topics whose messages carry a sequence number, and get each message once, in
+* order, across reconnects:
+*
+* - On every new connection, each held topic is subscribed again with `after`, the last
+*   number received, so the server sends what was missed instead of everything.
+* - A message numbered at or below the last one is a duplicate and is dropped.
+* - A message that skips numbers is held back, and the topic asks for what's missing (`resume`)
+*   once, so nothing is delivered out of order.
+* - A server that can't replay sends a `snapshot`, and the numbering goes on from it.
+*
+* Listen with `feeds.on('message', …)`, or pass `feeds` to `createWebSocketState` in place of
+* the client. Hold topics with `useWebSocketTopic(feeds, topic)` or `feeds.acquire(topic)`.
+*
+* @example
+* ```ts
+* export const feeds = createWebSocketFeeds(live, {
+*   subscribe: (topic, after) => ({ type: 'subscribe', topic, after }),
+*   unsubscribe: topic => ({ type: 'unsubscribe', topic }),
+*   sequence: message => (message.type === 'event' ? message : undefined),
+*   snapshot: message => (message.type === 'snapshot' ? message : undefined)
+* });
+*
+* export const chat = createWebSocketState(feeds, { initialState: [], reduce: addMessage });
+* ```
+*/
+function createWebSocketFeeds(client, options) {
+	const last = /* @__PURE__ */ new Map();
+	const resuming = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	const topics = createWebSocketTopics(client, {
+		subscribe: (topic) => options.subscribe(topic, last.get(topic)),
+		unsubscribe: options.unsubscribe,
+		[ON_RELEASE]: (topic) => {
+			last.delete(topic);
+			resuming.delete(topic);
+		}
+	});
+	const offs = [client.on("open", () => resuming.clear()), client.on("message", (message, event) => {
+		const snapshot = options.snapshot?.(message);
+		const position = snapshot ?? options.sequence(message);
+		if (position) {
+			const { topic, seq } = position;
+			const prev = last.get(topic);
+			if (prev !== void 0 && !snapshot && seq !== prev + 1) {
+				if (seq > prev && !resuming.has(topic)) {
+					resuming.add(topic);
+					options.onGap?.(topic, prev, seq);
+					if (client.socket?.readyState === 1) client.send((options.resume ?? options.subscribe)(topic, prev));
+				}
+				return;
+			}
+			if (prev !== void 0 || topics.active().includes(topic)) last.set(topic, seq);
+			resuming.delete(topic);
+		}
+		for (const listener of [...listeners]) try {
+			listener(message, event);
+		} catch (error) {
+			queueMicrotask(() => {
+				throw error;
+			});
+		}
+	})];
+	return {
+		...topics,
+		on(_type, listener) {
+			const entry = (message, event) => listener(message, event);
+			listeners.add(entry);
+			return () => {
+				listeners.delete(entry);
+			};
+		},
+		position: (topic) => last.get(topic),
+		dispose() {
+			topics.dispose();
+			for (const off of offs) off();
+		}
+	};
+}
+//#endregion
 //#region src/latency.ts
 const EMPTY = Object.freeze({
 	rtt: void 0,
@@ -658,9 +966,118 @@ function createWebSocketLatency(client, options) {
 	};
 }
 //#endregion
+//#region src/presence.ts
+const VOLATILE$1 = { volatile: true };
+/**
+* Share per-peer state that expires, for presence, live cursors and selections.
+*
+* - `set(state)` shares this client's state, throttled to `maxRate` sends per second with the
+*   newest winning, and sent again on every new connection and every `refresh`, so it's never
+*   queued stale while disconnected.
+* - Other peers' states come from `receive`. A peer is forgotten when it leaves (`state: null`)
+*   or when nothing has arrived from it for `timeout`.
+*
+* The server relays each client's state to the others, tagged with a peer id, and says
+* `state: null` when a client disconnects.
+*
+* @example
+* ```ts
+* export const cursors = createWebSocketPresence(room, {
+*   send: (cursor: { x: number; y: number }) => ({ type: 'cursor', cursor }),
+*   leave: () => ({ type: 'leave' }),
+*   receive: message => (message.type === 'cursor' ? { peer: message.peer, state: message.cursor } : undefined)
+* });
+*
+* window.addEventListener('pointermove', event => cursors.set({ x: event.clientX, y: event.clientY }));
+* ```
+*/
+function createWebSocketPresence(client, options) {
+	const timeout = options.timeout ?? 3e4;
+	const interval = 1e3 / (options.maxRate ?? 20);
+	const peers = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	let snapshot = [];
+	let own;
+	let lastSent = -Infinity;
+	let sendTimer;
+	let refreshTimer;
+	let expiryTimer;
+	function changed() {
+		snapshot = [...peers.values()];
+		for (const listener of [...listeners]) listener();
+	}
+	function sendNow() {
+		clearTimeout(sendTimer);
+		sendTimer = void 0;
+		if (!own) return;
+		lastSent = Date.now();
+		client.send(options.send(own.state), VOLATILE$1);
+	}
+	function expire() {
+		expiryTimer = void 0;
+		const now = Date.now();
+		let next = Infinity;
+		let removed = false;
+		for (const [peer, entry] of peers) {
+			const at = entry.updatedAt + timeout;
+			if (at <= now) removed = peers.delete(peer);
+			else next = Math.min(next, at);
+		}
+		if (next < Infinity) expiryTimer = setTimeout(expire, next - now);
+		if (removed) changed();
+	}
+	const offs = [client.on("open", sendNow), client.on("message", (message) => {
+		const update = options.receive(message);
+		if (!update) return;
+		if (update.state === null) {
+			if (!peers.delete(update.peer)) return;
+		} else {
+			peers.set(update.peer, {
+				peer: update.peer,
+				state: update.state,
+				updatedAt: Date.now()
+			});
+			expiryTimer ??= setTimeout(expire, timeout);
+		}
+		changed();
+	})];
+	return {
+		client,
+		set(state) {
+			own = { state };
+			refreshTimer ??= setInterval(sendNow, options.refresh ?? timeout / 3);
+			if (sendTimer !== void 0) return;
+			const wait = lastSent + interval - Date.now();
+			if (wait <= 0) sendNow();
+			else sendTimer = setTimeout(sendNow, wait);
+		},
+		leave() {
+			own = void 0;
+			clearTimeout(sendTimer);
+			sendTimer = void 0;
+			clearInterval(refreshTimer);
+			refreshTimer = void 0;
+			if (options.leave) client.send(options.leave(), VOLATILE$1);
+		},
+		getSnapshot: () => snapshot,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		dispose() {
+			own = void 0;
+			clearTimeout(sendTimer);
+			clearInterval(refreshTimer);
+			clearTimeout(expiryTimer);
+			for (const off of offs) off();
+		}
+	};
+}
+//#endregion
 //#region src/requests.ts
 const lastIds = /* @__PURE__ */ new WeakMap();
-const VOLATILE$2 = { volatile: true };
 const noop = () => {};
 /**
 * Send requests and await their replies, matched by an id the library generates.
@@ -714,6 +1131,10 @@ function createWebSocketRequests(client, options) {
 			done(true, signal.reason);
 			return noop;
 		}
+		if (client.getSnapshot().status === "closed") {
+			done(true, /* @__PURE__ */ new Error("WebSocket is closed: request not sent"));
+			return noop;
+		}
 		const id = (lastIds.get(client) ?? 0) + 1;
 		lastIds.set(client, id);
 		const key = String(id);
@@ -738,7 +1159,8 @@ function createWebSocketRequests(client, options) {
 				release();
 				done(failed, reason);
 				if (cancel && options.cancel) try {
-					client.send(options.cancel(id), entry.socket ? VOLATILE$2 : { priority });
+					if (!entry.socket) client.send(options.cancel(id), { priority });
+					else if (entry.socket === client.socket && entry.socket.readyState === 1) client.send(options.cancel(id));
 				} catch (error) {
 					queueMicrotask(() => {
 						throw error;
@@ -749,8 +1171,7 @@ function createWebSocketRequests(client, options) {
 		waiting.set(key, entry);
 		signal?.addEventListener("abort", onAbort, { once: true });
 		arm();
-		const { status } = client.getSnapshot();
-		if (status === "closed" || status === "idle") entry.end(true, /* @__PURE__ */ new Error(`WebSocket is ${status}: request not sent`));
+		if (client.getSnapshot().status === "idle") entry.end(true, /* @__PURE__ */ new Error("WebSocket is idle: request not sent"));
 		else try {
 			if (client.send(options.send(message, id), {
 				...requestOptions,
@@ -821,7 +1242,6 @@ function createWebSocketRequests(client, options) {
 }
 //#endregion
 //#region src/responder.ts
-const VOLATILE$1 = { volatile: true };
 const abortError = (message) => new DOMException(message, "AbortError");
 /**
 * Answer requests the server sends: run a handler for tools that only exist in the browser
@@ -859,12 +1279,16 @@ function createWebSocketResponder(client, options) {
 		waiting = next;
 		for (const listener of [...listeners]) listener();
 	}
-	/** Send a reply, or an `error` reply if building or encoding it throws. */
+	/**
+	* Send a reply, or an `error` reply if building or encoding it throws. Only while open: never
+	* queued, and not `volatile`, which can be a datagram that never arrives.
+	*/
 	function reply(id, build) {
+		if (client.socket?.readyState !== 1) return false;
 		try {
-			return client.send(build(), VOLATILE$1);
+			return client.send(build());
 		} catch (error) {
-			return client.send(options.error(id, error), VOLATILE$1);
+			return client.send(options.error(id, error));
 		}
 	}
 	function receive(incoming) {
@@ -963,6 +1387,221 @@ function createWebSocketResponder(client, options) {
 	};
 }
 //#endregion
+//#region src/runs.ts
+function randomId() {
+	return globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+const CLAIM_WAIT = 200;
+function defaultStorage() {
+	try {
+		return typeof sessionStorage === "undefined" ? null : sessionStorage;
+	} catch {
+		return null;
+	}
+}
+/**
+* Stream runs, such as an AI agent's answer, that survive reconnects and page reloads.
+*
+* - `start(request)` sends `start(request, runId)` and follows the run's events, folding them
+*   into its value with `reduce`.
+* - Each event carries an `offset`. On a new connection, a streaming run sends
+*   `resume(runId, after)` with the last offset received, so the server sends what was missed,
+*   and duplicates are dropped.
+* - Streaming runs are remembered in `sessionStorage`. After a reload they're followed again from
+*   their first event, rebuilding the value, so `list()` or `useAgentRun` can show them.
+* - A run whose policy is `cancel` is aborted when its connection drops, and `cancel` is sent
+*   first thing on the next one.
+*
+* Built on `createWebSocketFeeds`, with each run a topic. While runs are streaming, it holds
+* the client's connection.
+*
+* @example
+* ```ts
+* export const runs = createWebSocketRuns(agent, {
+*   name: 'chat',
+*   start: (prompt: string, runId) => ({ type: 'run', runId, prompt }),
+*   resume: (runId, after) => ({ type: 'resume', runId, after }),
+*   cancel: runId => ({ type: 'cancel', runId }),
+*   event: message => (message.type === 'token' || message.type === 'done' ? message : undefined),
+*   done: message => message.type === 'done',
+*   initial: '',
+*   reduce: (text, message) => text + message.text
+* });
+*
+* const runId = runs.start('Summarize this thread');
+* ```
+*/
+function createWebSocketRuns(client, options) {
+	const storage = options.storage === void 0 ? defaultStorage() : options.storage;
+	const key = `react-websocket-runs:${options.name}`;
+	const runs = /* @__PURE__ */ new Map();
+	const starting = /* @__PURE__ */ new Map();
+	const policies = /* @__PURE__ */ new Map();
+	const releases = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	let list = [];
+	const feeds = createWebSocketFeeds(client, {
+		subscribe: (runId, after) => after === void 0 && starting.has(runId) ? options.start(starting.get(runId), runId) : options.resume(runId, after),
+		sequence: (message) => {
+			const event = options.event(message);
+			return event && {
+				topic: event.runId,
+				seq: event.offset
+			};
+		}
+	});
+	function read() {
+		try {
+			return JSON.parse(storage?.getItem(key) ?? "{}");
+		} catch {
+			return {};
+		}
+	}
+	function remember(runId, policy) {
+		if (!storage) return;
+		const stored = read();
+		if (policy) stored[runId] = policy;
+		else delete stored[runId];
+		try {
+			if (Object.keys(stored).length) storage.setItem(key, JSON.stringify(stored));
+			else storage.removeItem(key);
+		} catch {}
+	}
+	function set(runId, patch) {
+		const run = runs.get(runId);
+		runs.set(runId, {
+			...run ?? {
+				runId,
+				status: "streaming",
+				value: options.initial,
+				error: void 0
+			},
+			...patch
+		});
+		list = [...runs.values()];
+		for (const listener of [...listeners]) listener();
+	}
+	/** Stop following a run that ended. */
+	function end(runId, patch) {
+		releases.get(runId)?.();
+		releases.delete(runId);
+		starting.delete(runId);
+		policies.delete(runId);
+		remember(runId, void 0);
+		set(runId, patch);
+	}
+	function follow(runId, policy, value = options.initial) {
+		policies.set(runId, policy);
+		remember(runId, policy);
+		set(runId, { value });
+		releases.set(runId, feeds.acquire(runId));
+	}
+	function cancel(runId) {
+		const message = options.cancel;
+		if (!message) return;
+		if (client.socket?.readyState === 1) return void client.send(message(runId));
+		const release = client.acquire();
+		const off = client.on("open", () => {
+			off();
+			client.send(message(runId));
+			release();
+		});
+	}
+	function abort(runId) {
+		if (runs.get(runId)?.status !== "streaming") return;
+		cancel(runId);
+		end(runId, { status: "aborted" });
+	}
+	let status = client.getSnapshot().status;
+	const offs = [
+		feeds.on("message", (message) => {
+			const event = options.event(message);
+			if (!event || runs.get(event.runId)?.status !== "streaming") return;
+			const { runId } = event;
+			starting.delete(runId);
+			const error = options.error?.(message);
+			if (error !== void 0) return end(runId, {
+				status: "error",
+				error
+			});
+			const value = options.reduce(runs.get(runId).value, message);
+			if (options.done?.(message)) end(runId, {
+				status: "done",
+				value
+			});
+			else set(runId, { value });
+		}),
+		client.subscribe(() => {
+			const previous = status;
+			status = client.getSnapshot().status;
+			if (previous !== "open" || status === "open") return;
+			for (const [runId, policy] of policies) if (policy === "cancel") abort(runId);
+		}),
+		feeds.dispose
+	];
+	const channel = storage && typeof window !== "undefined" && typeof BroadcastChannel === "function" ? new BroadcastChannel(key) : void 0;
+	const claimed = /* @__PURE__ */ new Set();
+	if (channel) {
+		channel.onmessage = ({ data }) => {
+			if (data?.mine) claimed.add(data.mine);
+			else if (data?.who && policies.has(data.who)) channel.postMessage({ mine: data.who });
+		};
+		offs.push(() => channel.close());
+	}
+	const stale = [];
+	for (const [runId, policy] of Object.entries(read())) if (policy !== "cancel") follow(runId, policy);
+	else if (channel) {
+		stale.push(runId);
+		channel.postMessage({ who: runId });
+	} else {
+		cancel(runId);
+		remember(runId, void 0);
+	}
+	if (stale.length) {
+		const timer = setTimeout(() => {
+			for (const runId of stale) {
+				if (claimed.has(runId) || policies.has(runId)) continue;
+				cancel(runId);
+				remember(runId, void 0);
+			}
+		}, CLAIM_WAIT);
+		offs.push(() => clearTimeout(timer));
+	}
+	return {
+		client,
+		start(request, { runId = randomId(), policy = options.policy ?? "keep", initial } = {}) {
+			if (runs.has(runId)) return runId;
+			starting.set(runId, request);
+			follow(runId, policy, initial);
+			return runId;
+		},
+		attach(runId, { policy = options.policy ?? "keep", initial } = {}) {
+			if (!runs.has(runId)) follow(runId, policy, initial);
+		},
+		abort,
+		get: (runId) => runs.get(runId),
+		list: () => list,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		delete(runId) {
+			abort(runId);
+			if (runs.delete(runId)) {
+				list = [...runs.values()];
+				for (const listener of [...listeners]) listener();
+			}
+		},
+		dispose() {
+			for (const release of releases.values()) release();
+			releases.clear();
+			for (const off of offs) off();
+		}
+	};
+}
+//#endregion
 //#region src/sendrate.ts
 const VOLATILE = { volatile: true };
 /**
@@ -1086,6 +1725,9 @@ function createWebSocketSendRate(client, options = {}) {
 * It starts listening immediately and keeps the state across reconnects; it doesn't open
 * the connection by itself.
 *
+* Pass feeds from `createWebSocketFeeds` in place of the client to reduce their messages
+* instead: numbered ones once each and in order.
+*
 * @example
 * ```ts
 * const prices = createWebSocket<Tick>('wss://api.example.com/prices', { json: true });
@@ -1099,7 +1741,8 @@ function createWebSocketSendRate(client, options = {}) {
 * const acme = useWebSocketState(priceState, state => state.ACME);
 * ```
 */
-function createWebSocketState(client, options) {
+function createWebSocketState(source, options) {
+	const client = "client" in source ? source.client : source;
 	const { initialState, reduce, batch } = options;
 	let state = initialState;
 	let notified = state;
@@ -1137,100 +1780,22 @@ function createWebSocketState(client, options) {
 		},
 		setState: (change) => update(change),
 		reset: () => update(initialState),
-		dispose: client.on("message", (message) => update((current) => reduce(current, message), batch === "frame"))
-	};
-}
-//#endregion
-//#region src/topics.ts
-/**
-* Manage topic subscriptions that survive reconnects.
-*
-* - The first holder of a topic sends `subscribe(topic)`. Later holders share it.
-* - A tick after the last holder releases it, `unsubscribe(topic)` is sent, so StrictMode
-*   and route transitions don't churn subscriptions.
-* - After every reconnect, every held topic is subscribed again on the new socket, before
-*   messages queued while disconnected are sent.
-*
-* Subscriptions are only sent while the socket is open; nothing is queued for them.
-*
-* @example
-* ```ts
-* export const topics = createWebSocketTopics(live, {
-*   subscribe: topic => ({ type: 'subscribe', topic }),
-*   unsubscribe: topic => ({ type: 'unsubscribe', topic })
-* });
-*
-* // In a component:
-* useWebSocketTopic(topics, `prices:${symbol}`);
-* ```
-*/
-function createWebSocketTopics(client, options) {
-	const counts = /* @__PURE__ */ new Map();
-	const pendingRemoval = /* @__PURE__ */ new Map();
-	let sentOn = null;
-	let sent = /* @__PURE__ */ new Set();
-	function isOpen() {
-		return client.getSnapshot().status === "open" && client.socket !== null;
-	}
-	function subscribe(topic) {
-		if (!isOpen()) return;
-		if (client.socket !== sentOn) {
-			sentOn = client.socket;
-			sent = /* @__PURE__ */ new Set();
-		}
-		if (sent.has(topic)) return;
-		sent.add(topic);
-		client.send(options.subscribe(topic));
-	}
-	function unsubscribe(topic) {
-		if (!isOpen() || client.socket !== sentOn || !sent.delete(topic)) return;
-		if (options.unsubscribe) client.send(options.unsubscribe(topic));
-	}
-	const off = client.on("open", () => {
-		sentOn = client.socket;
-		sent = /* @__PURE__ */ new Set();
-		for (const topic of counts.keys()) subscribe(topic);
-	});
-	return {
-		client,
-		acquire(topic) {
-			const releaseConnection = client.acquire();
-			clearTimeout(pendingRemoval.get(topic));
-			pendingRemoval.delete(topic);
-			counts.set(topic, (counts.get(topic) ?? 0) + 1);
-			subscribe(topic);
-			let released = false;
-			return () => {
-				if (released) return;
-				released = true;
-				const remaining = (counts.get(topic) ?? 1) - 1;
-				if (remaining > 0) counts.set(topic, remaining);
-				else {
-					counts.delete(topic);
-					pendingRemoval.set(topic, setTimeout(() => {
-						pendingRemoval.delete(topic);
-						if (!counts.has(topic)) unsubscribe(topic);
-					}, 0));
-				}
-				releaseConnection();
-			};
-		},
-		active: () => [...counts.keys()],
-		dispose() {
-			off();
-			for (const timer of pendingRemoval.values()) clearTimeout(timer);
-			pendingRemoval.clear();
-		}
+		dispose: source.on("message", (message) => update((current) => reduce(current, message), batch === "frame"))
 	};
 }
 //#endregion
 exports.MessageError = MessageError;
 exports.createWebSocket = createWebSocket;
+exports.createWebSocketFeeds = createWebSocketFeeds;
 exports.createWebSocketLatency = createWebSocketLatency;
+exports.createWebSocketPresence = createWebSocketPresence;
 exports.createWebSocketRequests = createWebSocketRequests;
 exports.createWebSocketResponder = createWebSocketResponder;
+exports.createWebSocketRuns = createWebSocketRuns;
 exports.createWebSocketSendRate = createWebSocketSendRate;
 exports.createWebSocketState = createWebSocketState;
 exports.createWebSocketTopics = createWebSocketTopics;
+exports.retryAfter = retryAfter;
+exports.retryableClose = retryableClose;
 
 //# sourceMappingURL=core.cjs.map