react-websocket 3.3.0 → 3.6.0

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","useSyncExternalStore","useMemo","useState"],"sources":["../src/react.ts"],"sourcesContent":["import {\n  useEffect,\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\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\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

@@ -112,14 +112,42 @@ interface SendOptions {
   volatile?: boolean;
   /**
    * Keep only the newest queued message with this key. Sending again with the same key
-   * while disconnected replaces the earlier one, which moves to the back of the queue.
+   * while disconnected replaces the earlier one, which moves to the back of the queue
+   * (or of the `priority` messages, for a priority one).
    * For state where only the latest value matters, such as "my position is now (x, y)".
    */
   key?: string;
+  /**
+   * Queue this message ahead of every message queued without `priority`, after earlier
+   * priority messages. For control messages that must not wait behind a backlog, such as
+   * cancel, interrupt or a token refresh. Messages sent from `open` listeners still go first.
+   *
+   * It only matters while the socket isn't open: once a message is handed to the browser,
+   * nothing can overtake it. To keep that buffer short, send bulky streams with `maxBuffered`.
+   * @default false
+   */
+  priority?: boolean;
+  /**
+   * Drop the message instead of sending it while more than this many bytes are already
+   * waiting in the browser's send buffer (`socket.bufferedAmount`). For high-rate streams on
+   * a slow link, such as audio frames or per-tick input, where a late message is worse than
+   * none. `send()` returns `false`, and `onDrop` isn't called.
+   *
+   * Only checked while the socket is open: a message queued while disconnected is sent on
+   * open regardless. `bufferedAmount` includes what you sent earlier in the same task, so set
+   * it well above one burst of messages.
+   *
+   * @example
+   * ```ts
+   * voice.send(frame, { volatile: true, maxBuffered: 64 * 1024 });
+   * ```
+   */
+  maxBuffered?: number;
   /**
    * Called if the message is dropped from the queue without being sent: replaced by a
    * newer message with the same `key`, or evicted by `queue.limit`. Not called when the
-   * queue is cleared because the client closed or gave up.
+   * queue is cleared because the client closed or gave up, or when `send()` drops the
+   * message right away (`volatile` while not open, or `maxBuffered`) and returns `false`.
    */
   onDrop?: () => void;
 }
@@ -127,7 +155,7 @@ interface SendOptions {
 interface QueueOptions {
   /**
    * Maximum number of messages held while not connected. When full, the oldest
-   * message is dropped.
+   * message is dropped, skipping `priority` messages unless nothing else is queued.
    * @default Infinity
    */
   limit?: number;
@@ -310,12 +338,14 @@ interface WebSocketClient<In = unknown, Out = unknown> {
    * Send a message (encoded with `serialize`/`json` if configured). If the socket isn't
    * open, the message is queued and sent on open (see the `queue` option), unless
    * `options.volatile` is set.
-   * @returns `true` if it was sent immediately, `false` if it was queued or dropped.
+   * @returns `true` if it was sent immediately, `false` if it was queued or dropped
+   *   (`volatile` while not open, or `maxBuffered` while open).
    *
    * @example
    * ```ts
    * game.send({ type: 'input', dx, dy }, { volatile: true }); // never replayed after a reconnect
    * game.send({ type: 'position', x, y }, { key: 'position' }); // only the newest is queued
+   * game.send({ type: 'leave' }, { priority: true }); // ahead of everything already queued
    * ```
    */
   send(message: Out, options?: SendOptions): boolean;
@@ -458,20 +488,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}. */
@@ -488,7 +534,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;
@@ -650,6 +715,85 @@ interface WebSocketResponder<P = unknown, R = unknown> {
  */
 export declare function createWebSocketResponder<Q extends RequestFields, R, In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketResponderOptions<Q, R, NoInfer<In>, NoInfer<Out>>): WebSocketResponder<ParamsOf<Q>, R>;
 //#endregion
+//#region src/sendrate.d.ts
+/** Options for {@link createWebSocketSendRate}. */
+interface WebSocketSendRateOptions {
+  /**
+   * Ticks per second while the connection keeps up.
+   * @default 30
+   */
+  maxRate?: number;
+  /**
+   * The rate never drops below this, in ticks per second.
+   * @default 5
+   */
+  minRate?: number;
+  /**
+   * Bytes waiting in the browser's send buffer (`socket.bufferedAmount`) above which a tick
+   * sends nothing and the rate halves.
+   * @default 1024
+   */
+  maxBuffered?: number;
+  /**
+   * Measurements from `createWebSocketLatency` on the same client. With them, a round-trip time
+   * that rises also lowers the rate. Without them, only the send buffer is watched.
+   */
+  latency?: Pick<WebSocketLatency, 'getSnapshot'>;
+  /**
+   * How far `rtt` may rise above the lowest one measured on this connection before the rate
+   * halves, in ms. A steady high ping keeps the full rate; only a rising one counts.
+   * @default 100
+   */
+  maxRttIncrease?: number;
+}
+/** The current send rate. A new object is created on every change. */
+interface SendRate {
+  /** Ticks per second, rounded. */
+  readonly rate: number;
+  /**
+   * Whether the last tick found the link congested: the send buffer above `maxBuffered`, or
+   * `rtt` risen more than `maxRttIncrease`.
+   */
+  readonly congested: boolean;
+}
+/** Keyed sends coalesced at a rate that adapts to the link. Create with {@link createWebSocketSendRate}. */
+interface WebSocketSendRate<Out> {
+  /** The client the messages are sent on. */
+  readonly client: WebSocketClient<any, Out>;
+  /**
+   * Send `message` at the next tick. A message with the same `key` still waiting for it is
+   * replaced, so only the newest one goes out. Sent with `volatile`.
+   */
+  send(message: Out, key: string): void;
+  /** Send everything waiting now, e.g. right before a one-shot action that must carry the latest aim. */
+  flush(): void;
+  /** The current {@link SendRate}. Returns the same object until it changes. */
+  getSnapshot(): SendRate;
+  /** Called whenever the rate or `congested` changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Stop sending and listening. Only needed for instances created dynamically. */
+  dispose(): void;
+}
+/**
+ * Send high-rate state, such as aim, cursor or position, at a rate that adapts to the
+ * connection. Messages are coalesced per key between ticks. The rate drops by half when the
+ * send buffer fills up or the round trip grows, and climbs back one tick per second at a time
+ * when the link keeps up, so players on a poor connection degrade smoothly instead of building
+ * up lag.
+ *
+ * Ticks run only while the socket is open and something is waiting. Messages waiting during a
+ * reconnect go out after it; `close()` drops them. It doesn't open the connection by itself.
+ *
+ * @example
+ * ```ts
+ * export const stream = createWebSocketSendRate(game, { latency, maxRate: 30 });
+ *
+ * // On every pointer move: at most 30 a second, fewer on a congested link.
+ * stream.send({ type: 'aim', angle }, 'aim');
+ * ```
+ */
+export declare function createWebSocketSendRate<Out>(client: WebSocketClient<any, Out>, options?: WebSocketSendRateOptions): WebSocketSendRate<Out>;
+//#endregion
 //#region src/state.d.ts
 /** Options for {@link createWebSocketState}. */
 interface WebSocketStateOptions<S, In> {
@@ -660,6 +804,17 @@ interface WebSocketStateOptions<S, In> {
    * change, or the same `state` to ignore the message (subscribers aren't notified).
    */
   reduce: (state: S, message: In) => S;
+  /**
+   * `'frame'`: notify subscribers at most once per animation frame instead of once per
+   * message, so a fast stream (tokens, tickers, game state) renders once per frame.
+   * `getState()` is always current; only notifications wait. `setState` and `reset` still
+   * notify right away.
+   *
+   * Browsers pause animation frames in background tabs: the state keeps up, and subscribers
+   * hear about it when the tab is visible again. Without `requestAnimationFrame` (Node, some
+   * workers), it waits about 16 ms instead.
+   */
+  batch?: 'frame';
 }
 /**
  * State derived from a client's messages. Read it with `useWebSocketState(store, selector)`,
@@ -892,6 +1047,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, Snapshot, StandardSchemaV1, Status, UrlSource, UseWebSocketOptions, UseWebSocketResult, WebSocketClient, WebSocketHandlers, WebSocketLatency, WebSocketLatencyOptions, WebSocketOptions, WebSocketRequests, WebSocketRequestsOptions, WebSocketResponder, WebSocketResponderOptions, 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

package/dist/index.d.ts

@@ -113,14 +113,42 @@ interface SendOptions {
   volatile?: boolean;
   /**
    * Keep only the newest queued message with this key. Sending again with the same key
-   * while disconnected replaces the earlier one, which moves to the back of the queue.
+   * while disconnected replaces the earlier one, which moves to the back of the queue
+   * (or of the `priority` messages, for a priority one).
    * For state where only the latest value matters, such as "my position is now (x, y)".
    */
   key?: string;
+  /**
+   * Queue this message ahead of every message queued without `priority`, after earlier
+   * priority messages. For control messages that must not wait behind a backlog, such as
+   * cancel, interrupt or a token refresh. Messages sent from `open` listeners still go first.
+   *
+   * It only matters while the socket isn't open: once a message is handed to the browser,
+   * nothing can overtake it. To keep that buffer short, send bulky streams with `maxBuffered`.
+   * @default false
+   */
+  priority?: boolean;
+  /**
+   * Drop the message instead of sending it while more than this many bytes are already
+   * waiting in the browser's send buffer (`socket.bufferedAmount`). For high-rate streams on
+   * a slow link, such as audio frames or per-tick input, where a late message is worse than
+   * none. `send()` returns `false`, and `onDrop` isn't called.
+   *
+   * Only checked while the socket is open: a message queued while disconnected is sent on
+   * open regardless. `bufferedAmount` includes what you sent earlier in the same task, so set
+   * it well above one burst of messages.
+   *
+   * @example
+   * ```ts
+   * voice.send(frame, { volatile: true, maxBuffered: 64 * 1024 });
+   * ```
+   */
+  maxBuffered?: number;
   /**
    * Called if the message is dropped from the queue without being sent: replaced by a
    * newer message with the same `key`, or evicted by `queue.limit`. Not called when the
-   * queue is cleared because the client closed or gave up.
+   * queue is cleared because the client closed or gave up, or when `send()` drops the
+   * message right away (`volatile` while not open, or `maxBuffered`) and returns `false`.
    */
   onDrop?: () => void;
 }
@@ -128,7 +156,7 @@ interface SendOptions {
 interface QueueOptions {
   /**
    * Maximum number of messages held while not connected. When full, the oldest
-   * message is dropped.
+   * message is dropped, skipping `priority` messages unless nothing else is queued.
    * @default Infinity
    */
   limit?: number;
@@ -311,12 +339,14 @@ interface WebSocketClient<In = unknown, Out = unknown> {
    * Send a message (encoded with `serialize`/`json` if configured). If the socket isn't
    * open, the message is queued and sent on open (see the `queue` option), unless
    * `options.volatile` is set.
-   * @returns `true` if it was sent immediately, `false` if it was queued or dropped.
+   * @returns `true` if it was sent immediately, `false` if it was queued or dropped
+   *   (`volatile` while not open, or `maxBuffered` while open).
    *
    * @example
    * ```ts
    * game.send({ type: 'input', dx, dy }, { volatile: true }); // never replayed after a reconnect
    * game.send({ type: 'position', x, y }, { key: 'position' }); // only the newest is queued
+   * game.send({ type: 'leave' }, { priority: true }); // ahead of everything already queued
    * ```
    */
   send(message: Out, options?: SendOptions): boolean;
@@ -372,6 +402,56 @@ interface WebSocketLatency {
   dispose(): void;
 }
 //#endregion
+//#region src/requests.d.ts
+/** Per-call options for {@link WebSocketRequests.request} and {@link WebSocketRequests.stream}. */
+interface RequestOptions extends SendOptions {
+  /**
+   * 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 (a stream throws) with `signal.reason`. A late reply is ignored. */
+  signal?: AbortSignal;
+}
+/** Request/response over one client. Create with {@link createWebSocketRequests}. */
+interface WebSocketRequests<Req, In> {
+  /** The client requests are sent on. */
+  readonly client: WebSocketClient<any, any>;
+  /**
+   * Send a request and resolve with its reply. Holds the connection until it settles.
+   *
+   * Rejects with a `TimeoutError` `DOMException` after `timeout`, with `signal.reason` when
+   * aborted, and with an `Error` when the connection it was sent on closes (the reply can
+   * no longer arrive) or the client stops. A request made while disconnected is queued like
+   * any other message and waits for the connection; it rejects if it is dropped from the
+   * queue (replaced by a newer request with the same `key`, or evicted by `queue.limit`).
+   */
+  request(message: Req, options?: RequestOptions): Promise<In>;
+  /**
+   * 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;
+}
+//#endregion
 //#region src/responder.d.ts
 /** A request from the server that hasn't been answered yet. */
 interface IncomingRequest<P = unknown, R = unknown> {
@@ -616,6 +696,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 { UseWebSocketOptions, UseWebSocketResult, WebSocketHandlers };
+export type { UseWebSocketOptions, UseWebSocketResult, UseWebSocketStreamOptions, UseWebSocketStreamResult, WebSocketHandlers };
 //# sourceMappingURL=index.d.ts.map