react-websocket 3.5.0 → 4.0.0

package/dist/index.cjs

@@ -22,7 +22,38 @@ const noopSend = () => false;
 const noop = () => {};
 const ON_TEARDOWN = Symbol.for("react-websocket.onTeardown");
 const registry = /* @__PURE__ */ new Map();
-function sharedClient(url, options) {
+const origins = /* @__PURE__ */ new WeakMap();
+const warned = /* @__PURE__ */ new Set();
+const CONNECTION_OPTIONS = {
+	protocols: void 0,
+	binaryType: "blob",
+	json: false,
+	parse: void 0,
+	serialize: void 0,
+	schema: void 0,
+	reconnect: true,
+	heartbeat: void 0,
+	queue: true,
+	logger: void 0,
+	WebSocket: void 0
+};
+const IGNORED_OPTIONS = /* @__PURE__ */ new Set(["protocols", "logger"]);
+const sameValue = (a, b) => Object.is(a, b) || typeof a === "function" && typeof b === "function" && String(a) === String(b);
+const isPlainObject = (value) => typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+function sameOption(a, b) {
+	if (sameValue(a, b)) return true;
+	if (!isPlainObject(a) || !isPlainObject(b)) return false;
+	return [...Object.keys(a), ...Object.keys(b)].every((key) => sameValue(a[key], b[key]));
+}
+function warnOnConflict(url, key, client, options, id) {
+	const origin = origins.get(client);
+	if (!origin || origin.id === id || warned.has(`${key}\u0000${id}`)) return;
+	const differing = Object.keys(CONNECTION_OPTIONS).filter((name) => !IGNORED_OPTIONS.has(name) && !sameOption(origin.options[name] ?? CONNECTION_OPTIONS[name], options[name] ?? CONNECTION_OPTIONS[name]));
+	if (!differing.length) return;
+	warned.add(`${key}\u0000${id}`);
+	console.warn(`react-websocket: useWebSocket("${url}") was given different ${differing.join(", ")} than the component that opened this shared connection. They are ignored: every component using the URL gets the first one's options. Pass the same options, or define the connection once with createWebSocket().`);
+}
+function sharedClient(url, options, id) {
 	if (typeof window === "undefined") return (0, __core_cjs.createWebSocket)(url, options);
 	const key = `${url}\u0000${JSON.stringify(options.protocols ?? null)}`;
 	let client = registry.get(key);
@@ -35,7 +66,11 @@ function sharedClient(url, options) {
 		});
 		registry.set(key, created);
 		client = created;
-	}
+		if (process.env.NODE_ENV !== "production") origins.set(created, {
+			options,
+			id
+		});
+	} else if (process.env.NODE_ENV !== "production") warnOnConflict(url, key, client, options, id);
 	return client;
 }
 /** Always-current value for use inside effects and event listeners (a `useEffectEvent` stand-in). */
@@ -52,7 +87,8 @@ function useHold(client, enabled) {
 	}, [client, enabled]);
 }
 function useWebSocket(target, options = {}) {
-	const client = target == null ? null : typeof target === "string" ? sharedClient(target, options) : target;
+	const id = (0, react.useId)();
+	const client = target == null ? null : typeof target === "string" ? sharedClient(target, options, id) : target;
 	const enabled = options.enabled ?? true;
 	const snapshot = (0, react.useSyncExternalStore)(client ? client.subscribe : noopSubscribe, client ? client.getSnapshot : idleSnapshot, idleSnapshot);
 	const handlers = useLatest(options);
@@ -219,6 +255,69 @@ function useAgentApproval(responder, method) {
 		return mine.length ? mine : NO_REQUESTS;
 	}, [waiting, method]);
 }
+const append = (list, reply) => [...list, reply];
+function nextFrame(callback) {
+	if (typeof requestAnimationFrame === "function") requestAnimationFrame(callback);
+	else setTimeout(callback, 16);
+}
+function useWebSocketStream(rpc, options = {}) {
+	const [state, setState] = (0, react.useState)(() => ({
+		value: options.reduce ? options.initial : NO_REQUESTS,
+		status: "idle",
+		error: void 0
+	}));
+	const latest = useLatest({
+		rpc,
+		options
+	});
+	const running = (0, react.useRef)(null);
+	const actions = (0, react.useMemo)(() => ({
+		abort: () => running.current?.abort(),
+		start(message, requestOptions) {
+			running.current?.abort();
+			const controller = running.current = new AbortController();
+			const { reduce, initial, batch } = latest.current.options;
+			const fold = reduce ?? append;
+			let value = reduce ? initial : NO_REQUESTS;
+			let frame = false;
+			const show = (status, error) => {
+				frame = false;
+				if (running.current === controller) setState({
+					value,
+					status,
+					error
+				});
+			};
+			show("streaming");
+			(async () => {
+				try {
+					const replies = latest.current.rpc.stream(message, {
+						...requestOptions,
+						signal: controller.signal
+					});
+					for await (const reply of replies) {
+						value = fold(value, reply);
+						if (batch !== "frame") show("streaming");
+						else if (!frame) {
+							frame = true;
+							nextFrame(() => frame && show("streaming"));
+						}
+					}
+					show("done");
+				} catch (error) {
+					if (controller.signal.aborted) show("aborted");
+					else show("error", error);
+				}
+			})();
+		}
+	}), [latest]);
+	(0, react.useEffect)(() => actions.abort, [actions, rpc]);
+	useHold(rpc?.client ?? null, true);
+	return {
+		...state,
+		...actions
+	};
+}
 //#endregion
 exports.useAgentApproval = useAgentApproval;
 exports.useWebSocket = useWebSocket;
@@ -226,6 +325,7 @@ exports.useWebSocketEvent = useWebSocketEvent;
 exports.useWebSocketLatency = useWebSocketLatency;
 exports.useWebSocketState = useWebSocketState;
 exports.useWebSocketStatus = useWebSocketStatus;
+exports.useWebSocketStream = useWebSocketStream;
 exports.useWebSocketTopic = useWebSocketTopic;
 Object.keys(__core_cjs).forEach(function(k) {
 	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["createWebSocket","useRef","useSyncExternalStore","useMemo"],"sources":["../src/react.ts"],"sourcesContent":["import { useEffect, useInsertionEffect, useMemo, useRef, useSyncExternalStore } from 'react';\n// Import the client through the `core` entry: the build keeps it external, so both entries\n// share one copy of it (and of `MessageError`).\nimport { createWebSocket } from './core';\nimport type { Latency, WebSocketLatency } from './latency';\n// Types only: a value import from anything but `./core` would bundle a second copy into this entry.\nimport type { IncomingRequest, WebSocketResponder } from './responder';\nimport type { WebSocketState } from './state';\nimport type { WebSocketTopics } from './topics';\nimport type {\n  CloseInfo,\n  EventMap,\n  SendOptions,\n  Snapshot,\n  Status,\n  WebSocketClient,\n  WebSocketOptions\n} from './types';\n\n/**\n * Per-component event handlers. They always see the component's latest props and\n * state, and changing them never reconnects.\n */\nexport interface WebSocketHandlers<In> {\n  /** The socket opened (initially or after a reconnect). */\n  onOpen?: (event: Event) => void;\n  /** A message arrived and passed `parse`/`json` and `schema`. */\n  onMessage?: (message: In, event: MessageEvent) => void;\n  /** A socket closed. Called whether or not it will be retried. */\n  onClose?: (close: CloseInfo) => void;\n  /** A socket error `Event`, a `MessageError`, or an `Error` from the constructor or `url` function. */\n  onError?: (error: Event | Error) => void;\n  /**\n   * `false` releases this component's hold on the connection and stops its handlers.\n   * The connection closes once nothing else holds it.\n   * @default true\n   */\n  enabled?: boolean;\n}\n\n/** Options for `useWebSocket(url, options)`: connection options plus handlers. */\nexport interface UseWebSocketOptions<In, Out>\n  extends WebSocketOptions<In, Out>, WebSocketHandlers<In> {}\n\n/** What `useWebSocket` returns: the current {@link Snapshot} plus stable actions. */\nexport interface UseWebSocketResult<In, Out> extends Snapshot<In> {\n  /**\n   * Send now, or queue until open (see {@link SendOptions} for volatile and keyed sends).\n   * Returns `true` if sent immediately. Stable identity.\n   */\n  send: (message: Out, options?: SendOptions) => boolean;\n  /** Close and stop reconnecting (for every component sharing the connection). Stable identity. */\n  close: (code?: number, reason?: string) => void;\n  /** Drop the socket and connect again right away. Stable identity. */\n  reconnect: () => void;\n  /** The underlying client, or `null` when the URL is `null`/`undefined`. */\n  client: WebSocketClient<In, Out> | null;\n}\n\nconst IDLE: Snapshot<never> = Object.freeze({ status: 'idle', lastMessage: undefined, attempt: 0 });\nconst idleSnapshot = () => IDLE;\nconst idleStatus = (): Status => 'idle';\nconst NO_LATENCY: Latency = Object.freeze({ rtt: undefined, offset: undefined });\nconst noLatency = () => NO_LATENCY;\n// Not frozen: a call would keep it in bundles that never use the hook.\nconst NO_REQUESTS: readonly never[] = [];\nconst noRequests = () => NO_REQUESTS;\nconst noopSubscribe = () => () => {};\nconst noopSend = () => false;\nconst noop = () => {};\n\n// Same key as `ON_TEARDOWN` in ./client, which this entry must not import directly.\nconst ON_TEARDOWN = Symbol.for('react-websocket.onTeardown');\n\n// Hooks given the same URL (and protocols) share one connection.\nconst registry = new Map<string, WebSocketClient<any, any>>();\n\nfunction sharedClient<In, Out>(url: string, options: WebSocketOptions<In, Out>) {\n  // Don't let server renders accumulate clients that can never be torn down.\n  if (typeof window === 'undefined') return createWebSocket(url, options);\n  const key = `${url}\\u0000${JSON.stringify(options.protocols ?? null)}`;\n  let client = registry.get(key) as WebSocketClient<In, Out> | undefined;\n  if (!client) {\n    const created: WebSocketClient<In, Out> = createWebSocket(url, {\n      ...options,\n      [ON_TEARDOWN]: () => {\n        if (registry.get(key) === created) registry.delete(key);\n      }\n    } as WebSocketOptions<In, Out>);\n    registry.set(key, created);\n    client = created;\n  }\n  return client;\n}\n\n/** Always-current value for use inside effects and event listeners (a `useEffectEvent` stand-in). */\nfunction useLatest<T>(value: T) {\n  const ref = useRef(value);\n  useInsertionEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n\nfunction useHold(client: WebSocketClient<any, any> | null, enabled: boolean) {\n  useEffect(() => {\n    if (client && enabled) return client.acquire();\n  }, [client, enabled]);\n}\n\n/**\n * Connect to a WebSocket and re-render with its status and latest message.\n *\n * - With a URL, every component using the same URL (and `protocols`) shares one\n *   connection. Its options come from whichever component created it first.\n * - With a client from `createWebSocket()`, options are the client's; only handlers\n *   and `enabled` apply here.\n * - With `null` or `undefined`, nothing connects and the status stays `idle`.\n *\n * The connection opens on mount and closes one tick after the last component using it\n * unmounts, so StrictMode and `<Activity>` don't open duplicate sockets.\n *\n * Re-renders on status changes and on every message. For high-frequency streams use\n * `useWebSocketEvent` and `useWebSocketStatus` instead.\n *\n * @example\n * ```tsx\n * const { status, lastMessage, send } = useWebSocket<Price, Order>('wss://api.example.com/prices', {\n *   json: true,\n *   onMessage: price => console.log(price)\n * });\n * ```\n */\nexport function useWebSocket<In = unknown, Out = unknown>(\n  url: string | null | undefined,\n  options?: UseWebSocketOptions<In, Out>\n): UseWebSocketResult<In, Out>;\nexport function useWebSocket<In, Out>(\n  client: WebSocketClient<In, Out> | null | undefined,\n  options?: WebSocketHandlers<In>\n): UseWebSocketResult<In, Out>;\nexport function useWebSocket<In, Out>(\n  target: string | WebSocketClient<In, Out> | null | undefined,\n  options: UseWebSocketOptions<In, Out> = {}\n): UseWebSocketResult<In, Out> {\n  const client =\n    target == null ? null : typeof target === 'string' ? sharedClient(target, options) : target;\n  const enabled = options.enabled ?? true;\n\n  const snapshot = useSyncExternalStore<Snapshot<In>>(\n    client ? client.subscribe : noopSubscribe,\n    client ? client.getSnapshot : idleSnapshot,\n    idleSnapshot\n  );\n\n  const handlers = useLatest(options);\n  useEffect(() => {\n    if (!client || !enabled) return;\n    const offs = [\n      client.on('open', event => handlers.current.onOpen?.(event)),\n      client.on('message', (message, event) => handlers.current.onMessage?.(message, event)),\n      client.on('close', info => handlers.current.onClose?.(info)),\n      client.on('error', error => handlers.current.onError?.(error))\n    ];\n    return () => offs.forEach(off => off());\n  }, [client, enabled, handlers]);\n  useHold(client, enabled);\n\n  return {\n    ...snapshot,\n    send: client ? client.send : noopSend,\n    close: client ? client.close : noop,\n    reconnect: client ? client.reconnect : noop,\n    client\n  };\n}\n\n/**\n * Listen to a client's events without re-rendering the component. The listener always\n * sees the latest props and state. Keeps the connection open while mounted.\n *\n * @example\n * ```tsx\n * useWebSocketEvent(chat, 'message', message => setMessages(list => [...list, message]));\n * ```\n */\nexport function useWebSocketEvent<In, K extends keyof EventMap<In>>(\n  client: WebSocketClient<In, any> | null | undefined,\n  type: K,\n  listener: EventMap<In>[K]\n): void {\n  const latest = useLatest(listener);\n  useEffect(() => {\n    if (!client) return;\n    const off = client.on(type, ((...args: unknown[]) =>\n      (latest.current as (...a: unknown[]) => void)(...args)) as EventMap<In>[K]);\n    const release = client.acquire();\n    return () => {\n      off();\n      release();\n    };\n  }, [client, type, latest]);\n}\n\n/**\n * The connection status of a client. Re-renders only when the status changes, not on\n * messages. Keeps the connection open while mounted.\n *\n * @example\n * ```tsx\n * const status = useWebSocketStatus(chat); // 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed'\n * ```\n */\nexport function useWebSocketStatus(client: WebSocketClient<any, any> | null | undefined): Status {\n  const status = useSyncExternalStore(\n    client ? client.subscribe : noopSubscribe,\n    client ? () => client.getSnapshot().status : idleStatus,\n    idleStatus\n  );\n  useHold(client ?? null, true);\n  return status;\n}\n\nconst identity = <T>(value: T) => value;\n\n/**\n * Read state built from messages by `createWebSocketState`. Re-renders only when the\n * selected value changes (by `isEqual`, default `Object.is`), however often messages\n * arrive. Keeps the connection open while mounted.\n *\n * On the server, and during hydration, it reads from `initialState`.\n *\n * @example\n * ```tsx\n * const acme = useWebSocketState(priceState, state => state.ACME);\n * ```\n */\nexport function useWebSocketState<S>(store: WebSocketState<S>): S;\nexport function useWebSocketState<S, T>(\n  store: WebSocketState<S>,\n  selector: (state: S) => T,\n  isEqual?: (a: T, b: T) => boolean\n): T;\nexport function useWebSocketState<S, T>(\n  store: WebSocketState<S>,\n  selector: (state: S) => T = identity as (state: S) => T,\n  isEqual: (a: T, b: T) => boolean = Object.is\n): T {\n  const [getSelection, getServerSelection] = useMemo(() => {\n    // Return the previous selection while the state is unchanged or the result is equal,\n    // so inline selectors that build objects don't re-render (or loop) on every message.\n    const memoized = (read: () => S) => {\n      let memo: { state: S; selection: T } | undefined;\n      return () => {\n        const state = read();\n        if (memo && Object.is(memo.state, state)) return memo.selection;\n        const selection = selector(state);\n        if (memo && isEqual(memo.selection, selection)) {\n          memo = { state, selection: memo.selection };\n          return memo.selection;\n        }\n        memo = { state, selection };\n        return selection;\n      };\n    };\n    return [memoized(store.getState), memoized(() => store.initialState)] as const;\n  }, [store, selector, isEqual]);\n\n  const selection = useSyncExternalStore(store.subscribe, getSelection, getServerSelection);\n  useHold(store.client, true);\n  return selection;\n}\n\n/**\n * Subscribe to one topic (or several) while mounted, through a `createWebSocketTopics`\n * manager. Components holding the same topic share one subscription, and it is sent again\n * after every reconnect. Keeps the connection open while mounted. `null` holds nothing.\n *\n * @example\n * ```tsx\n * useWebSocketTopic(topics, `prices:${symbol}`);\n * useWebSocketTopic(topics, watchlist.map(symbol => `prices:${symbol}`));\n * ```\n */\nexport function useWebSocketTopic(\n  topics: WebSocketTopics | null | undefined,\n  topic: string | readonly string[] | null | undefined\n): void {\n  // A stable key, so a new array with the same topics doesn't resubscribe.\n  const key = topic == null ? null : JSON.stringify(typeof topic === 'string' ? [topic] : topic);\n  useEffect(() => {\n    if (!topics || key === null) return;\n    const releases = (JSON.parse(key) as string[]).map(t => topics.acquire(t));\n    return () => releases.forEach(release => release());\n  }, [topics, key]);\n}\n\n/**\n * Read round-trip time and server clock offset from a `createWebSocketLatency` instance.\n * Re-renders when a measurement changes, about once per ping interval. Keeps the connection\n * open while mounted. On the server, and during hydration, both values are `undefined`.\n *\n * @example\n * ```tsx\n * const { rtt } = useWebSocketLatency(latency);\n * return <span>{rtt === undefined ? '–' : `${Math.round(rtt)} ms`}</span>;\n * ```\n */\nexport function useWebSocketLatency(latency: WebSocketLatency): Latency {\n  const snapshot = useSyncExternalStore(latency.subscribe, latency.getSnapshot, noLatency);\n  useHold(latency.client, true);\n  return snapshot;\n}\n\n/**\n * Requests for `method` that a person answers, e.g. an agent asking to run a tool. While mounted,\n * it registers `method` on the responder without a handler, so new requests wait here instead of\n * getting a `NotFoundError` reply. Call `respond` or `reject` on one to answer it. Re-renders\n * when the list changes. Keeps the connection open while mounted. `null` holds nothing.\n *\n * Requests stay listed after unmount until they are answered, time out, are cancelled or lose\n * their connection, so a remounted dialog shows them again. On the server the list is empty.\n *\n * @example\n * ```tsx\n * const [request] = useAgentApproval(tools, 'approve');\n * if (!request) return null;\n * return (\n *   <dialog open>\n *     {request.params.summary}\n *     <button onClick={() => request.respond({ approved: true })}>Approve</button>\n *     <button onClick={() => request.respond({ approved: false })}>Deny</button>\n *   </dialog>\n * );\n * ```\n */\nexport function useAgentApproval<P, R>(\n  responder: WebSocketResponder<P, R> | null | undefined,\n  method: string | null | undefined\n): readonly IncomingRequest<P, R>[] {\n  const waiting = useSyncExternalStore(\n    responder ? responder.subscribe : noopSubscribe,\n    responder ? responder.getSnapshot : noRequests,\n    noRequests\n  );\n  useEffect(() => {\n    if (responder && method != null) return responder.onRequest(method);\n  }, [responder, method]);\n  useHold(responder?.client ?? null, method != null);\n  return useMemo(() => {\n    const mine = waiting.filter(request => request.method === method);\n    return mine.length ? mine : NO_REQUESTS;\n  }, [waiting, method]);\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["createWebSocket","useRef","useId","useSyncExternalStore","useMemo","useState"],"sources":["../src/react.ts"],"sourcesContent":["import {\n  useEffect,\n  useId,\n  useInsertionEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore\n} from 'react';\n// Import the client through the `core` entry: the build keeps it external, so both entries\n// share one copy of it (and of `MessageError`).\nimport { createWebSocket } from './core';\nimport type { Latency, WebSocketLatency } from './latency';\n// Types only: a value import from anything but `./core` would bundle a second copy into this entry.\nimport type { RequestOptions, WebSocketRequests } from './requests';\nimport type { IncomingRequest, WebSocketResponder } from './responder';\nimport type { WebSocketState } from './state';\nimport type { WebSocketTopics } from './topics';\nimport type {\n  CloseInfo,\n  EventMap,\n  SendOptions,\n  Snapshot,\n  Status,\n  WebSocketClient,\n  WebSocketOptions\n} from './types';\n\n/**\n * Per-component event handlers. They always see the component's latest props and\n * state, and changing them never reconnects.\n */\nexport interface WebSocketHandlers<In> {\n  /** The socket opened (initially or after a reconnect). */\n  onOpen?: (event: Event) => void;\n  /** A message arrived and passed `parse`/`json` and `schema`. */\n  onMessage?: (message: In, event: MessageEvent) => void;\n  /** A socket closed. Called whether or not it will be retried. */\n  onClose?: (close: CloseInfo) => void;\n  /** A socket error `Event`, a `MessageError`, or an `Error` from the constructor or `url` function. */\n  onError?: (error: Event | Error) => void;\n  /**\n   * `false` releases this component's hold on the connection and stops its handlers.\n   * The connection closes once nothing else holds it.\n   * @default true\n   */\n  enabled?: boolean;\n}\n\n/** Options for `useWebSocket(url, options)`: connection options plus handlers. */\nexport interface UseWebSocketOptions<In, Out>\n  extends WebSocketOptions<In, Out>, WebSocketHandlers<In> {}\n\n/** What `useWebSocket` returns: the current {@link Snapshot} plus stable actions. */\nexport interface UseWebSocketResult<In, Out> extends Snapshot<In> {\n  /**\n   * Send now, or queue until open (see {@link SendOptions} for volatile and keyed sends).\n   * Returns `true` if sent immediately. Stable identity.\n   */\n  send: (message: Out, options?: SendOptions) => boolean;\n  /** Close and stop reconnecting (for every component sharing the connection). Stable identity. */\n  close: (code?: number, reason?: string) => void;\n  /** Drop the socket and connect again right away. Stable identity. */\n  reconnect: () => void;\n  /** The underlying client, or `null` when the URL is `null`/`undefined`. */\n  client: WebSocketClient<In, Out> | null;\n}\n\nconst IDLE: Snapshot<never> = Object.freeze({ status: 'idle', lastMessage: undefined, attempt: 0 });\nconst idleSnapshot = () => IDLE;\nconst idleStatus = (): Status => 'idle';\nconst NO_LATENCY: Latency = Object.freeze({ rtt: undefined, offset: undefined });\nconst noLatency = () => NO_LATENCY;\n// Not frozen: a call would keep it in bundles that never use the hook.\nconst NO_REQUESTS: readonly never[] = [];\nconst noRequests = () => NO_REQUESTS;\nconst noopSubscribe = () => () => {};\nconst noopSend = () => false;\nconst noop = () => {};\n\n// Same key as `ON_TEARDOWN` in ./client, which this entry must not import directly.\nconst ON_TEARDOWN = Symbol.for('react-websocket.onTeardown');\n\n// Hooks given the same URL (and protocols) share one connection.\nconst registry = new Map<string, WebSocketClient<any, any>>();\n\n// Development only: the options (and `useId` of the component) each URL client was created with,\n// to warn when another component passes different ones for the same URL.\nconst origins = new WeakMap<\n  WebSocketClient<any, any>,\n  { options: WebSocketOptions<any, any>; id: string }\n>();\nconst warned = new Set<string>();\n\n// The options that shape a shared connection, with what leaving one out means.\nconst CONNECTION_OPTIONS: { [K in keyof WebSocketOptions]-?: unknown } = {\n  protocols: undefined, // part of the registry key\n  binaryType: 'blob',\n  json: false,\n  parse: undefined,\n  serialize: undefined,\n  schema: undefined,\n  reconnect: true,\n  heartbeat: undefined,\n  queue: true,\n  logger: undefined, // debugging only\n  WebSocket: undefined\n};\nconst IGNORED_OPTIONS = new Set(['protocols', 'logger']);\n\n// Inline functions and objects are new on every render: compare them by source and by field.\nconst sameValue = (a: unknown, b: unknown) =>\n  Object.is(a, b) ||\n  (typeof a === 'function' && typeof b === 'function' && String(a) === String(b));\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && Object.getPrototypeOf(value) === Object.prototype;\n\nfunction sameOption(a: unknown, b: unknown) {\n  if (sameValue(a, b)) return true;\n  if (!isPlainObject(a) || !isPlainObject(b)) return false;\n  return [...Object.keys(a), ...Object.keys(b)].every(key => sameValue(a[key], b[key]));\n}\n\nfunction warnOnConflict(\n  url: string,\n  key: string,\n  client: WebSocketClient<any, any>,\n  options: WebSocketOptions<any, any>,\n  id: string\n) {\n  const origin = origins.get(client);\n  if (!origin || origin.id === id || warned.has(`${key}\\u0000${id}`)) return;\n  const differing = (Object.keys(CONNECTION_OPTIONS) as (keyof WebSocketOptions)[]).filter(\n    name =>\n      !IGNORED_OPTIONS.has(name) &&\n      !sameOption(\n        origin.options[name] ?? CONNECTION_OPTIONS[name],\n        options[name] ?? CONNECTION_OPTIONS[name]\n      )\n  );\n  if (!differing.length) return;\n  warned.add(`${key}\\u0000${id}`);\n  console.warn(\n    `react-websocket: useWebSocket(\"${url}\") was given different ${differing.join(', ')} than ` +\n      `the component that opened this shared connection. They are ignored: every component ` +\n      `using the URL gets the first one's options. Pass the same options, or define the ` +\n      `connection once with createWebSocket().`\n  );\n}\n\nfunction sharedClient<In, Out>(url: string, options: WebSocketOptions<In, Out>, id: string) {\n  // Don't let server renders accumulate clients that can never be torn down.\n  if (typeof window === 'undefined') return createWebSocket(url, options);\n  const key = `${url}\\u0000${JSON.stringify(options.protocols ?? null)}`;\n  let client = registry.get(key) as WebSocketClient<In, Out> | undefined;\n  if (!client) {\n    const created: WebSocketClient<In, Out> = createWebSocket(url, {\n      ...options,\n      [ON_TEARDOWN]: () => {\n        if (registry.get(key) === created) registry.delete(key);\n      }\n    } as WebSocketOptions<In, Out>);\n    registry.set(key, created);\n    client = created;\n    if (process.env.NODE_ENV !== 'production') origins.set(created, { options, id });\n  } else if (process.env.NODE_ENV !== 'production') {\n    warnOnConflict(url, key, client, options, id);\n  }\n  return client;\n}\n\n/** Always-current value for use inside effects and event listeners (a `useEffectEvent` stand-in). */\nfunction useLatest<T>(value: T) {\n  const ref = useRef(value);\n  useInsertionEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n\nfunction useHold(client: WebSocketClient<any, any> | null, enabled: boolean) {\n  useEffect(() => {\n    if (client && enabled) return client.acquire();\n  }, [client, enabled]);\n}\n\n/**\n * Connect to a WebSocket and re-render with its status and latest message.\n *\n * - With a URL, every component using the same URL (and `protocols`) shares one\n *   connection. Its options come from whichever component created it first; in\n *   development, a component passing different ones gets a console warning.\n * - With a client from `createWebSocket()`, options are the client's; only handlers\n *   and `enabled` apply here.\n * - With `null` or `undefined`, nothing connects and the status stays `idle`.\n *\n * The connection opens on mount and closes one tick after the last component using it\n * unmounts, so StrictMode and `<Activity>` don't open duplicate sockets.\n *\n * Re-renders on status changes and on every message. For high-frequency streams use\n * `useWebSocketEvent` and `useWebSocketStatus` instead.\n *\n * @example\n * ```tsx\n * const { status, lastMessage, send } = useWebSocket<Price, Order>('wss://api.example.com/prices', {\n *   json: true,\n *   onMessage: price => console.log(price)\n * });\n * ```\n */\nexport function useWebSocket<In = unknown, Out = unknown>(\n  url: string | null | undefined,\n  options?: UseWebSocketOptions<In, Out>\n): UseWebSocketResult<In, Out>;\nexport function useWebSocket<In, Out>(\n  client: WebSocketClient<In, Out> | null | undefined,\n  options?: WebSocketHandlers<In>\n): UseWebSocketResult<In, Out>;\nexport function useWebSocket<In, Out>(\n  target: string | WebSocketClient<In, Out> | null | undefined,\n  options: UseWebSocketOptions<In, Out> = {}\n): UseWebSocketResult<In, Out> {\n  const id = useId();\n  const client =\n    target == null ? null : typeof target === 'string' ? sharedClient(target, options, id) : target;\n  const enabled = options.enabled ?? true;\n\n  const snapshot = useSyncExternalStore<Snapshot<In>>(\n    client ? client.subscribe : noopSubscribe,\n    client ? client.getSnapshot : idleSnapshot,\n    idleSnapshot\n  );\n\n  const handlers = useLatest(options);\n  useEffect(() => {\n    if (!client || !enabled) return;\n    const offs = [\n      client.on('open', event => handlers.current.onOpen?.(event)),\n      client.on('message', (message, event) => handlers.current.onMessage?.(message, event)),\n      client.on('close', info => handlers.current.onClose?.(info)),\n      client.on('error', error => handlers.current.onError?.(error))\n    ];\n    return () => offs.forEach(off => off());\n  }, [client, enabled, handlers]);\n  useHold(client, enabled);\n\n  return {\n    ...snapshot,\n    send: client ? client.send : noopSend,\n    close: client ? client.close : noop,\n    reconnect: client ? client.reconnect : noop,\n    client\n  };\n}\n\n/**\n * Listen to a client's events without re-rendering the component. The listener always\n * sees the latest props and state. Keeps the connection open while mounted.\n *\n * @example\n * ```tsx\n * useWebSocketEvent(chat, 'message', message => setMessages(list => [...list, message]));\n * ```\n */\nexport function useWebSocketEvent<In, K extends keyof EventMap<In>>(\n  client: WebSocketClient<In, any> | null | undefined,\n  type: K,\n  listener: EventMap<In>[K]\n): void {\n  const latest = useLatest(listener);\n  useEffect(() => {\n    if (!client) return;\n    const off = client.on(type, ((...args: unknown[]) =>\n      (latest.current as (...a: unknown[]) => void)(...args)) as EventMap<In>[K]);\n    const release = client.acquire();\n    return () => {\n      off();\n      release();\n    };\n  }, [client, type, latest]);\n}\n\n/**\n * The connection status of a client. Re-renders only when the status changes, not on\n * messages. Keeps the connection open while mounted.\n *\n * @example\n * ```tsx\n * const status = useWebSocketStatus(chat); // 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed'\n * ```\n */\nexport function useWebSocketStatus(client: WebSocketClient<any, any> | null | undefined): Status {\n  const status = useSyncExternalStore(\n    client ? client.subscribe : noopSubscribe,\n    client ? () => client.getSnapshot().status : idleStatus,\n    idleStatus\n  );\n  useHold(client ?? null, true);\n  return status;\n}\n\nconst identity = <T>(value: T) => value;\n\n/**\n * Read state built from messages by `createWebSocketState`. Re-renders only when the\n * selected value changes (by `isEqual`, default `Object.is`), however often messages\n * arrive. Keeps the connection open while mounted.\n *\n * On the server, and during hydration, it reads from `initialState`.\n *\n * @example\n * ```tsx\n * const acme = useWebSocketState(priceState, state => state.ACME);\n * ```\n */\nexport function useWebSocketState<S>(store: WebSocketState<S>): S;\nexport function useWebSocketState<S, T>(\n  store: WebSocketState<S>,\n  selector: (state: S) => T,\n  isEqual?: (a: T, b: T) => boolean\n): T;\nexport function useWebSocketState<S, T>(\n  store: WebSocketState<S>,\n  selector: (state: S) => T = identity as (state: S) => T,\n  isEqual: (a: T, b: T) => boolean = Object.is\n): T {\n  const [getSelection, getServerSelection] = useMemo(() => {\n    // Return the previous selection while the state is unchanged or the result is equal,\n    // so inline selectors that build objects don't re-render (or loop) on every message.\n    const memoized = (read: () => S) => {\n      let memo: { state: S; selection: T } | undefined;\n      return () => {\n        const state = read();\n        if (memo && Object.is(memo.state, state)) return memo.selection;\n        const selection = selector(state);\n        if (memo && isEqual(memo.selection, selection)) {\n          memo = { state, selection: memo.selection };\n          return memo.selection;\n        }\n        memo = { state, selection };\n        return selection;\n      };\n    };\n    return [memoized(store.getState), memoized(() => store.initialState)] as const;\n  }, [store, selector, isEqual]);\n\n  const selection = useSyncExternalStore(store.subscribe, getSelection, getServerSelection);\n  useHold(store.client, true);\n  return selection;\n}\n\n/**\n * Subscribe to one topic (or several) while mounted, through a `createWebSocketTopics`\n * manager. Components holding the same topic share one subscription, and it is sent again\n * after every reconnect. Keeps the connection open while mounted. `null` holds nothing.\n *\n * @example\n * ```tsx\n * useWebSocketTopic(topics, `prices:${symbol}`);\n * useWebSocketTopic(topics, watchlist.map(symbol => `prices:${symbol}`));\n * ```\n */\nexport function useWebSocketTopic(\n  topics: WebSocketTopics | null | undefined,\n  topic: string | readonly string[] | null | undefined\n): void {\n  // A stable key, so a new array with the same topics doesn't resubscribe.\n  const key = topic == null ? null : JSON.stringify(typeof topic === 'string' ? [topic] : topic);\n  useEffect(() => {\n    if (!topics || key === null) return;\n    const releases = (JSON.parse(key) as string[]).map(t => topics.acquire(t));\n    return () => releases.forEach(release => release());\n  }, [topics, key]);\n}\n\n/**\n * Read round-trip time and server clock offset from a `createWebSocketLatency` instance.\n * Re-renders when a measurement changes, about once per ping interval. Keeps the connection\n * open while mounted. On the server, and during hydration, both values are `undefined`.\n *\n * @example\n * ```tsx\n * const { rtt } = useWebSocketLatency(latency);\n * return <span>{rtt === undefined ? '–' : `${Math.round(rtt)} ms`}</span>;\n * ```\n */\nexport function useWebSocketLatency(latency: WebSocketLatency): Latency {\n  const snapshot = useSyncExternalStore(latency.subscribe, latency.getSnapshot, noLatency);\n  useHold(latency.client, true);\n  return snapshot;\n}\n\n/**\n * Requests for `method` that a person answers, e.g. an agent asking to run a tool. While mounted,\n * it registers `method` on the responder without a handler, so new requests wait here instead of\n * getting a `NotFoundError` reply. Call `respond` or `reject` on one to answer it. Re-renders\n * when the list changes. Keeps the connection open while mounted. `null` holds nothing.\n *\n * Requests stay listed after unmount until they are answered, time out, are cancelled or lose\n * their connection, so a remounted dialog shows them again. On the server the list is empty.\n *\n * @example\n * ```tsx\n * const [request] = useAgentApproval(tools, 'approve');\n * if (!request) return null;\n * return (\n *   <dialog open>\n *     {request.params.summary}\n *     <button onClick={() => request.respond({ approved: true })}>Approve</button>\n *     <button onClick={() => request.respond({ approved: false })}>Deny</button>\n *   </dialog>\n * );\n * ```\n */\nexport function useAgentApproval<P, R>(\n  responder: WebSocketResponder<P, R> | null | undefined,\n  method: string | null | undefined\n): readonly IncomingRequest<P, R>[] {\n  const waiting = useSyncExternalStore(\n    responder ? responder.subscribe : noopSubscribe,\n    responder ? responder.getSnapshot : noRequests,\n    noRequests\n  );\n  useEffect(() => {\n    if (responder && method != null) return responder.onRequest(method);\n  }, [responder, method]);\n  useHold(responder?.client ?? null, method != null);\n  return useMemo(() => {\n    const mine = waiting.filter(request => request.method === method);\n    return mine.length ? mine : NO_REQUESTS;\n  }, [waiting, method]);\n}\n\n/** Options for `useWebSocketStream` that fold replies into one value, e.g. tokens into text. */\nexport interface UseWebSocketStreamOptions<In, T> {\n  /** The value before the first reply. `start()` resets to it. */\n  initial: T;\n  /** Fold a reply into the value. Return a new value instead of changing the old one. */\n  reduce: (value: T, reply: In) => T;\n  /**\n   * `'frame'`: re-render at most once per animation frame instead of once per reply. Browsers\n   * pause frames in background tabs; the value catches up when the tab is visible again.\n   */\n  batch?: 'frame';\n}\n\n/** What `useWebSocketStream` returns: the stream's progress plus stable actions. */\nexport interface UseWebSocketStreamResult<Req, T> {\n  /** The replies so far, folded with `reduce`, or as an array without it. */\n  readonly value: T;\n  /**\n   * `idle` until `start()`. `done` after the last reply, `error` when the stream failed (see\n   * `error`), `aborted` after `abort()`. The value stays as it was when the stream ended.\n   */\n  readonly status: 'idle' | 'streaming' | 'done' | 'error' | 'aborted';\n  /** Why the stream failed, while `status` is `error`. */\n  readonly error: unknown;\n  /** Reset the value and stream the replies to `message`, aborting the stream before. Stable identity. */\n  start: (message: Req, options?: Omit<RequestOptions, 'signal'>) => void;\n  /** Stop the stream and send the manager's `cancel`. Stable identity. */\n  abort: () => void;\n}\n\nconst append = <T>(list: readonly T[], reply: T): readonly T[] => [...list, reply];\n\n// Node and some workers have no animation frames: wait about one instead.\nfunction nextFrame(callback: () => void) {\n  if (typeof requestAnimationFrame === 'function') requestAnimationFrame(callback);\n  else setTimeout(callback, 16);\n}\n\n/**\n * Stream the replies to a request into a value, e.g. a model's tokens into its answer.\n * `start(message)` sends it with `rpc.stream()` and folds each reply in with `reduce`, or\n * collects the replies without it. Starting again aborts the stream before; so do `abort()`,\n * unmounting and a new `rpc`, and each sends the manager's `cancel`. Re-renders on every\n * reply, or once per frame with `batch: 'frame'`. Keeps the connection open while mounted.\n *\n * @example\n * ```tsx\n * const answer = useWebSocketStream(ask, {\n *   initial: '',\n *   reduce: (text, reply) => text + reply.delta,\n *   batch: 'frame'\n * });\n * return (\n *   <>\n *     <button onClick={() => answer.start({ prompt })}>Ask</button>\n *     <button onClick={answer.abort} disabled={answer.status !== 'streaming'}>Stop</button>\n *     <p>{answer.value}</p>\n *   </>\n * );\n * ```\n */\nexport function useWebSocketStream<Req, In, T>(\n  rpc: WebSocketRequests<Req, In> | null | undefined,\n  options: UseWebSocketStreamOptions<NoInfer<In>, T>\n): UseWebSocketStreamResult<Req, T>;\nexport function useWebSocketStream<Req, In>(\n  rpc: WebSocketRequests<Req, In> | null | undefined,\n  options?: { batch?: 'frame' }\n): UseWebSocketStreamResult<Req, readonly In[]>;\nexport function useWebSocketStream<Req, In>(\n  rpc: WebSocketRequests<Req, In> | null | undefined,\n  options: Partial<UseWebSocketStreamOptions<In, any>> = {}\n): UseWebSocketStreamResult<Req, unknown> {\n  type Status = UseWebSocketStreamResult<Req, unknown>['status'];\n  const [state, setState] = useState<{ value: unknown; status: Status; error: unknown }>(() => ({\n    value: options.reduce ? options.initial : NO_REQUESTS,\n    status: 'idle',\n    error: undefined\n  }));\n  const latest = useLatest({ rpc, options });\n  const running = useRef<AbortController | null>(null);\n\n  const actions = useMemo(\n    () => ({\n      abort: () => running.current?.abort(),\n      start(message: Req, requestOptions?: Omit<RequestOptions, 'signal'>) {\n        running.current?.abort();\n        const controller = (running.current = new AbortController());\n        const { reduce, initial, batch } = latest.current.options;\n        const fold = reduce ?? append;\n        let value: unknown = reduce ? initial : NO_REQUESTS;\n        let frame = false;\n        // A stream that was started over no longer shows; ending also skips a pending frame.\n        const show = (status: Status, error?: unknown) => {\n          frame = false;\n          if (running.current === controller) setState({ value, status, error });\n        };\n        show('streaming');\n        void (async () => {\n          try {\n            const replies = latest.current.rpc!.stream(message, {\n              ...requestOptions,\n              signal: controller.signal\n            });\n            for await (const reply of replies) {\n              value = fold(value, reply);\n              if (batch !== 'frame') show('streaming');\n              else if (!frame) {\n                frame = true;\n                nextFrame(() => frame && show('streaming'));\n              }\n            }\n            show('done');\n          } catch (error) {\n            if (controller.signal.aborted) show('aborted');\n            else show('error', error);\n          }\n        })();\n      }\n    }),\n    [latest]\n  );\n  // Unmounting, or replies from another manager: stop this one's stream.\n  useEffect(() => actions.abort, [actions, rpc]);\n  useHold(rpc?.client ?? null, true);\n\n  return { ...state, ...actions };\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -30,7 +30,10 @@ interface Snapshot<In> {
   readonly status: Status;
   /** Most recent message (after `parse`/`json` and `schema`), kept across reconnects. */
   readonly lastMessage: In | undefined;
-  /** Consecutive failed attempts since the last successful open. `0` while open. */
+  /**
+   * Consecutive failed attempts since the last stable connection. A connection that closes
+   * within `reconnect.minUptime` of opening counts as failed. `0` while open.
+   */
   readonly attempt: number;
 }
 /** Details of a closed connection, from the browser's `CloseEvent`. */
@@ -52,6 +55,14 @@ interface ReconnectOptions {
    * @default Infinity
    */
   maxAttempts?: number;
+  /**
+   * How long a connection must stay open, in ms, before the backoff resets. One that closes
+   * sooner counts as a failed attempt, so a server that accepts and then closes right away
+   * (e.g. rejecting the credentials sent on open) is retried with a growing delay, and
+   * `maxAttempts` still applies. `0` resets on every open.
+   * @default 5000
+   */
+  minUptime?: number;
   /**
    * Delay before the first retry, in ms.
    * @default 1000
@@ -69,19 +80,26 @@ interface ReconnectOptions {
   factor?: number;
   /**
    * Randomly shave up to this fraction (0–1) off each delay, so that many clients
-   * dropped at once don't all reconnect at the same moment.
-   * @default 0.5
+   * dropped at once don't all reconnect at the same moment. The default `1` picks each
+   * delay at random between 0 and the backoff ("full jitter").
+   * @default 1
    */
   jitter?: number;
   /**
    * Called on every unexpected close. Return `false` to stop reconnecting.
    *
+   * The default, `retryableClose`, retries everything except `1002` (protocol error), `1003`
+   * (unsupported data) and `1008` (policy violation). Your own function replaces it; call
+   * `retryableClose` from it to keep that rule, or return `true` to retry every close.
+   *
    * @example
    * ```ts
-   * // Don't retry when the server rejects our credentials.
-   * shouldReconnect: close => close.code !== 4001
+   * import { retryableClose } from 'react-websocket';
+   *
+   * // Also stop when our server rejects the credentials.
+   * shouldReconnect: close => close.code !== 4001 && retryableClose(close)
    * ```
-   * @default () => true
+   * @default retryableClose
    */
   shouldReconnect?: (close: CloseInfo) => boolean;
 }
@@ -156,7 +174,8 @@ interface QueueOptions {
   /**
    * Maximum number of messages held while not connected. When full, the oldest
    * message is dropped, skipping `priority` messages unless nothing else is queued.
-   * @default Infinity
+   * `Infinity` keeps every message.
+   * @default 100
    */
   limit?: number;
 }
@@ -232,8 +251,8 @@ interface WebSocketOptions<In = unknown, Out = unknown> {
   heartbeat?: HeartbeatOptions;
   /**
    * Buffer `send()` calls made while not connected and send them, in order, on open
-   * (right after `open` listeners run).
-   * `false` drops them instead. `{ limit }` caps the buffer, dropping the oldest.
+   * (right after `open` listeners run). It holds up to 100 messages, dropping the oldest;
+   * `{ limit }` changes that. `false` drops messages instead of queueing them.
    * The queue is cleared by `close()` or when the client gives up.
    * @default true
    */
@@ -375,6 +394,20 @@ interface WebSocketClient<In = unknown, Out = unknown> {
 }
 //#endregion
 //#region src/client.d.ts
+/**
+ * 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) }
+ * });
+ * ```
+ */
+export declare function retryableClose(close: CloseInfo): boolean;
 /**
  * Create a WebSocket client, usually at module level, to share across components.
  *
@@ -488,20 +521,36 @@ interface WebSocketRequestsOptions<Req, In, Out> {
   reply: (message: In) => number | string | null | undefined;
   /**
    * Called on a reply. Return something other than `undefined` to reject the request with
-   * it instead of resolving, e.g. for a server-side error reply.
+   * it instead of resolving, e.g. for a server-side error reply. A stream throws it.
    */
   error?: (message: In) => unknown;
   /**
-   * Default time to wait for a reply, in ms. `Infinity` waits forever.
+   * Whether a reply is the last one of a stream. `stream()` needs it. That reply is yielded
+   * too, then the stream ends.
+   */
+  done?: (message: In) => boolean;
+  /**
+   * Build the message that tells the server to stop working on request `id`. Sent when this
+   * side gives up: the request's `signal` aborts, it times out, a loop over a stream exits
+   * early, or the manager is disposed. Not sent after the last reply, an error reply, a lost
+   * connection or `close()`.
+   */
+  cancel?: (id: number) => Out;
+  /**
+   * Default time to wait for a reply, in ms. For a stream, the time to wait for each reply,
+   * including the first. `Infinity` waits forever.
    * @default 10000
    */
   timeout?: number;
 }
-/** Per-call options for {@link WebSocketRequests.request}. */
+/** Per-call options for {@link WebSocketRequests.request} and {@link WebSocketRequests.stream}. */
 interface RequestOptions extends SendOptions {
-  /** Time to wait for a reply, in ms. Overrides the manager's `timeout`. */
+  /**
+   * Time to wait for a reply (for a stream, for each reply), in ms. Overrides the manager's
+   * `timeout`.
+   */
   timeout?: number;
-  /** Abort the request. It rejects with `signal.reason`. A late reply is ignored. */
+  /** Abort the request. It rejects (a stream throws) with `signal.reason`. A late reply is ignored. */
   signal?: AbortSignal;
 }
 /** Request/response over one client. Create with {@link createWebSocketRequests}. */
@@ -518,7 +567,26 @@ interface WebSocketRequests<Req, In> {
    * queue (replaced by a newer request with the same `key`, or evicted by `queue.limit`).
    */
   request(message: Req, options?: RequestOptions): Promise<In>;
-  /** Number of requests waiting for a reply. */
+  /**
+   * Send a request and iterate over its replies, up to and including the one `done` matches.
+   * Holds the connection until the stream ends. Needs the `done` option.
+   *
+   * `timeout` is the time to wait for each reply. Replies that arrive before the loop reads
+   * them are buffered. The stream is one-shot: iterate it once.
+   *
+   * Fails where `request()` rejects, with the same errors, after yielding the replies already
+   * received. Aborting `signal` throws `signal.reason` right away and discards them. Leaving
+   * the loop early, aborting and timing out send `cancel`.
+   *
+   * @example
+   * ```ts
+   * for await (const reply of rpc.stream({ type: 'ask', prompt }, { signal })) {
+   *   text += reply.delta;
+   * }
+   * ```
+   */
+  stream(message: Req, options?: RequestOptions): AsyncIterableIterator<In>;
+  /** Number of requests and streams waiting for a reply. */
   pending(): number;
   /** Reject every pending request and stop listening. Only needed for managers created dynamically. */
   dispose(): void;
@@ -910,7 +978,8 @@ interface UseWebSocketResult<In, Out> extends Snapshot<In> {
  * Connect to a WebSocket and re-render with its status and latest message.
  *
  * - With a URL, every component using the same URL (and `protocols`) shares one
- *   connection. Its options come from whichever component created it first.
+ *   connection. Its options come from whichever component created it first; in
+ *   development, a component passing different ones gets a console warning.
  * - With a client from `createWebSocket()`, options are the client's; only handlers
  *   and `enabled` apply here.
  * - With `null` or `undefined`, nothing connects and the status stays `idle`.
@@ -1012,6 +1081,61 @@ export declare function useWebSocketLatency(latency: WebSocketLatency): Latency;
  * ```
  */
 export declare function useAgentApproval<P, R>(responder: WebSocketResponder<P, R> | null | undefined, method: string | null | undefined): readonly IncomingRequest<P, R>[];
+/** Options for `useWebSocketStream` that fold replies into one value, e.g. tokens into text. */
+interface UseWebSocketStreamOptions<In, T> {
+  /** The value before the first reply. `start()` resets to it. */
+  initial: T;
+  /** Fold a reply into the value. Return a new value instead of changing the old one. */
+  reduce: (value: T, reply: In) => T;
+  /**
+   * `'frame'`: re-render at most once per animation frame instead of once per reply. Browsers
+   * pause frames in background tabs; the value catches up when the tab is visible again.
+   */
+  batch?: 'frame';
+}
+/** What `useWebSocketStream` returns: the stream's progress plus stable actions. */
+interface UseWebSocketStreamResult<Req, T> {
+  /** The replies so far, folded with `reduce`, or as an array without it. */
+  readonly value: T;
+  /**
+   * `idle` until `start()`. `done` after the last reply, `error` when the stream failed (see
+   * `error`), `aborted` after `abort()`. The value stays as it was when the stream ended.
+   */
+  readonly status: 'idle' | 'streaming' | 'done' | 'error' | 'aborted';
+  /** Why the stream failed, while `status` is `error`. */
+  readonly error: unknown;
+  /** Reset the value and stream the replies to `message`, aborting the stream before. Stable identity. */
+  start: (message: Req, options?: Omit<RequestOptions, 'signal'>) => void;
+  /** Stop the stream and send the manager's `cancel`. Stable identity. */
+  abort: () => void;
+}
+/**
+ * Stream the replies to a request into a value, e.g. a model's tokens into its answer.
+ * `start(message)` sends it with `rpc.stream()` and folds each reply in with `reduce`, or
+ * collects the replies without it. Starting again aborts the stream before; so do `abort()`,
+ * unmounting and a new `rpc`, and each sends the manager's `cancel`. Re-renders on every
+ * reply, or once per frame with `batch: 'frame'`. Keeps the connection open while mounted.
+ *
+ * @example
+ * ```tsx
+ * const answer = useWebSocketStream(ask, {
+ *   initial: '',
+ *   reduce: (text, reply) => text + reply.delta,
+ *   batch: 'frame'
+ * });
+ * return (
+ *   <>
+ *     <button onClick={() => answer.start({ prompt })}>Ask</button>
+ *     <button onClick={answer.abort} disabled={answer.status !== 'streaming'}>Stop</button>
+ *     <p>{answer.value}</p>
+ *   </>
+ * );
+ * ```
+ */
+export declare function useWebSocketStream<Req, In, T>(rpc: WebSocketRequests<Req, In> | null | undefined, options: UseWebSocketStreamOptions<NoInfer<In>, T>): UseWebSocketStreamResult<Req, T>;
+export declare function useWebSocketStream<Req, In>(rpc: WebSocketRequests<Req, In> | null | undefined, options?: {
+  batch?: 'frame';
+}): UseWebSocketStreamResult<Req, readonly In[]>;
 //#endregion
-export type { CloseInfo, EventMap, HeartbeatOptions, IncomingRequest, Latency, QueueOptions, ReconnectOptions, RequestHandler, RequestOptions, SendData, SendOptions, SendRate, Snapshot, StandardSchemaV1, Status, UrlSource, UseWebSocketOptions, UseWebSocketResult, WebSocketClient, WebSocketHandlers, WebSocketLatency, WebSocketLatencyOptions, WebSocketOptions, WebSocketRequests, WebSocketRequestsOptions, WebSocketResponder, WebSocketResponderOptions, WebSocketSendRate, WebSocketSendRateOptions, WebSocketState, WebSocketStateOptions, WebSocketTopics, WebSocketTopicsOptions };
+export type { CloseInfo, EventMap, HeartbeatOptions, IncomingRequest, Latency, QueueOptions, ReconnectOptions, RequestHandler, RequestOptions, SendData, SendOptions, SendRate, Snapshot, StandardSchemaV1, Status, UrlSource, UseWebSocketOptions, UseWebSocketResult, UseWebSocketStreamOptions, UseWebSocketStreamResult, WebSocketClient, WebSocketHandlers, WebSocketLatency, WebSocketLatencyOptions, WebSocketOptions, WebSocketRequests, WebSocketRequestsOptions, WebSocketResponder, WebSocketResponderOptions, WebSocketSendRate, WebSocketSendRateOptions, WebSocketState, WebSocketStateOptions, WebSocketTopics, WebSocketTopicsOptions };
 //# sourceMappingURL=index.d.cts.map