react-websocket 3.1.0 → 3.3.0

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+
+//#region src/types.d.ts
 /**
  * Where to connect: a URL, or a function that returns one (sync or async).
  *
@@ -24,90 +26,111 @@ type UrlSource = string | (() => string | Promise<string>);
 type Status = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed';
 /** The client's state as seen by React. A new object is created on every change. */
 interface Snapshot<In> {
-    /** Connection state. */
-    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. */
-    readonly attempt: number;
+  /** Connection state. */
+  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. */
+  readonly attempt: number;
 }
 /** Details of a closed connection, from the browser's `CloseEvent`. */
 interface CloseInfo {
-    /** Close code: `1000` is a normal close, `1006` an abnormal one (e.g. network loss), `4000`–`4999` are yours. */
-    readonly code: number;
-    /** Close reason sent by the side that closed the connection. Often empty. */
-    readonly reason: string;
-    /** Whether the closing handshake completed. */
-    readonly wasClean: boolean;
+  /** Close code: `1000` is a normal close, `1006` an abnormal one (e.g. network loss), `4000`–`4999` are yours. */
+  readonly code: number;
+  /** Close reason sent by the side that closed the connection. Often empty. */
+  readonly reason: string;
+  /** Whether the closing handshake completed. */
+  readonly wasClean: boolean;
 }
 /** Anything `WebSocket.prototype.send` accepts: a string, `Blob`, `ArrayBuffer` or typed array. */
 type SendData = Parameters<WebSocket['send']>[0];
 /** Reconnect timing. Delay before attempt `n` = `min(maxDelay, minDelay * factor ** (n - 1))`, minus jitter. */
 interface ReconnectOptions {
-    /**
-     * Maximum consecutive reconnect attempts. When the last one fails too, the client
-     * gives up: the status becomes `closed` and `ready` rejects. `0` never retries.
-     * @default Infinity
-     */
-    maxAttempts?: number;
-    /**
-     * Delay before the first retry, in ms.
-     * @default 1000
-     */
-    minDelay?: number;
-    /**
-     * Upper bound for the delay, in ms.
-     * @default 30000
-     */
-    maxDelay?: number;
-    /**
-     * Backoff multiplier applied per attempt.
-     * @default 2
-     */
-    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
-     */
-    jitter?: number;
-    /**
-     * Called on every unexpected close. Return `false` to stop reconnecting.
-     *
-     * @example
-     * ```ts
-     * // Don't retry when the server rejects our credentials.
-     * shouldReconnect: close => close.code !== 4001
-     * ```
-     * @default () => true
-     */
-    shouldReconnect?: (close: CloseInfo) => boolean;
+  /**
+   * Maximum consecutive reconnect attempts. When the last one fails too, the client
+   * gives up: the status becomes `closed` and `ready` rejects. `0` never retries.
+   * @default Infinity
+   */
+  maxAttempts?: number;
+  /**
+   * Delay before the first retry, in ms.
+   * @default 1000
+   */
+  minDelay?: number;
+  /**
+   * Upper bound for the delay, in ms.
+   * @default 30000
+   */
+  maxDelay?: number;
+  /**
+   * Backoff multiplier applied per attempt.
+   * @default 2
+   */
+  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
+   */
+  jitter?: number;
+  /**
+   * Called on every unexpected close. Return `false` to stop reconnecting.
+   *
+   * @example
+   * ```ts
+   * // Don't retry when the server rejects our credentials.
+   * shouldReconnect: close => close.code !== 4001
+   * ```
+   * @default () => true
+   */
+  shouldReconnect?: (close: CloseInfo) => boolean;
 }
 /** Application-level keep-alive. Useful behind proxies that drop idle connections. */
 interface HeartbeatOptions {
-    /** Send `message` every `interval` ms while open. */
-    interval: number;
-    /**
-     * Sent as-is (it is not passed through `serialize` or `json`).
-     * @default 'ping'
-     */
-    message?: string;
-    /** Incoming data equal to this string is swallowed instead of being delivered as a message. */
-    pong?: string;
-    /**
-     * If nothing at all arrives within this many ms after a ping, the connection is
-     * treated as dead: it closes with code `4000` and reconnects.
-     */
-    timeout?: number;
+  /** Send `message` every `interval` ms while open. */
+  interval: number;
+  /**
+   * Sent as-is (it is not passed through `serialize` or `json`).
+   * @default 'ping'
+   */
+  message?: string;
+  /** Incoming data equal to this string is swallowed instead of being delivered as a message. */
+  pong?: string;
+  /**
+   * If nothing at all arrives within this many ms after a ping, the connection is
+   * treated as dead: it closes with code `4000` and reconnects.
+   */
+  timeout?: number;
+}
+/** Per-message options for `send()`. */
+interface SendOptions {
+  /**
+   * Drop the message instead of queueing it when the socket isn't open. For data that
+   * is stale by the time a reconnect finishes, such as player input or cursor positions.
+   * @default false
+   */
+  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.
+   * For state where only the latest value matters, such as "my position is now (x, y)".
+   */
+  key?: string;
+  /**
+   * 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.
+   */
+  onDrop?: () => void;
 }
 /** Bounds for the send queue. */
 interface QueueOptions {
-    /**
-     * Maximum number of messages held while not connected. When full, the oldest
-     * message is dropped.
-     * @default Infinity
-     */
-    limit?: number;
+  /**
+   * Maximum number of messages held while not connected. When full, the oldest
+   * message is dropped.
+   * @default Infinity
+   */
+  limit?: number;
 }
 /**
  * The minimal [Standard Schema v1](https://standardschema.dev) interface, implemented
@@ -115,24 +138,24 @@ interface QueueOptions {
  * import this; pass your schema object directly.
  */
 interface StandardSchemaV1<Input = unknown, Output = Input> {
-    readonly '~standard': {
-        readonly version: 1;
-        readonly vendor: string;
-        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
-        readonly types?: {
-            readonly input: Input;
-            readonly output: Output;
-        } | undefined;
-    };
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    } | undefined;
+  };
 }
 /** The result of a Standard Schema `validate` call. */
 type StandardSchemaResult<Output> = {
-    readonly value: Output;
-    readonly issues?: undefined;
+  readonly value: Output;
+  readonly issues?: undefined;
 } | {
-    readonly issues: ReadonlyArray<{
-        readonly message: string;
-    }>;
+  readonly issues: ReadonlyArray<{
+    readonly message: string;
+  }>;
 };
 /**
  * Connection options, shared by `createWebSocket(url, options)` and `useWebSocket(url, options)`.
@@ -141,66 +164,66 @@ type StandardSchemaResult<Output> = {
  * @typeParam Out - Type accepted by `send()`.
  */
 interface WebSocketOptions<In = unknown, Out = unknown> {
-    /** Sub-protocol(s) passed to the `WebSocket` constructor. */
-    protocols?: string | string[];
-    /**
-     * How binary messages are exposed.
-     * @default 'blob'
-     */
-    binaryType?: BinaryType;
-    /**
-     * `JSON.parse` incoming and `JSON.stringify` outgoing messages. Messages that fail
-     * to parse are reported to `onError` as a {@link MessageError} and not delivered.
-     * @default false
-     */
-    json?: boolean;
-    /**
-     * Custom decoder for incoming `event.data`. Takes precedence over `json`.
-     * Throwing reports a {@link MessageError} and drops the message.
-     */
-    parse?: (data: unknown) => unknown;
-    /** Custom encoder for outgoing messages. Takes precedence over `json`. */
-    serialize?: (message: Out) => SendData;
-    /**
-     * Validate incoming messages (after parsing) with any Standard Schema library.
-     * Invalid messages are reported to `onError` as a {@link MessageError} and not delivered.
-     * The message type `In` is inferred from it.
-     *
-     * @example
-     * ```ts
-     * createWebSocket(url, { json: true, schema: z.object({ price: z.number() }) });
-     * ```
-     */
-    schema?: StandardSchemaV1<unknown, In>;
-    /**
-     * Reconnect with exponential backoff after an unexpected close. `false` disables it.
-     * @default true
-     */
-    reconnect?: boolean | ReconnectOptions;
-    /** Send a ping on an interval and, optionally, reconnect when the server goes quiet. */
-    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.
-     * The queue is cleared by `close()` or when the client gives up.
-     * @default true
-     */
-    queue?: boolean | QueueOptions;
-    /**
-     * Receives debug messages about connection attempts, retries and dropped messages.
-     * @example
-     * ```ts
-     * logger: console.debug
-     * ```
-     */
-    logger?: (message: string, ...details: unknown[]) => void;
-    /**
-     * `WebSocket` implementation to use, e.g. a mock in tests or the `ws` package in Node.
-     * When omitted, the global `WebSocket` is used in browsers. During a server render
-     * (no `window`), nothing connects unless an implementation is passed.
-     */
-    WebSocket?: typeof WebSocket;
+  /** Sub-protocol(s) passed to the `WebSocket` constructor. */
+  protocols?: string | string[];
+  /**
+   * How binary messages are exposed.
+   * @default 'blob'
+   */
+  binaryType?: BinaryType;
+  /**
+   * `JSON.parse` incoming and `JSON.stringify` outgoing messages. Messages that fail
+   * to parse are reported to `onError` as a {@link MessageError} and not delivered.
+   * @default false
+   */
+  json?: boolean;
+  /**
+   * Custom decoder for incoming `event.data`. Takes precedence over `json`.
+   * Throwing reports a {@link MessageError} and drops the message.
+   */
+  parse?: (data: unknown) => unknown;
+  /** Custom encoder for outgoing messages. Takes precedence over `json`. */
+  serialize?: (message: Out) => SendData;
+  /**
+   * Validate incoming messages (after parsing) with any Standard Schema library.
+   * Invalid messages are reported to `onError` as a {@link MessageError} and not delivered.
+   * The message type `In` is inferred from it.
+   *
+   * @example
+   * ```ts
+   * createWebSocket(url, { json: true, schema: z.object({ price: z.number() }) });
+   * ```
+   */
+  schema?: StandardSchemaV1<unknown, In>;
+  /**
+   * Reconnect with exponential backoff after an unexpected close. `false` disables it.
+   * @default true
+   */
+  reconnect?: boolean | ReconnectOptions;
+  /** Send a ping on an interval and, optionally, reconnect when the server goes quiet. */
+  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.
+   * The queue is cleared by `close()` or when the client gives up.
+   * @default true
+   */
+  queue?: boolean | QueueOptions;
+  /**
+   * Receives debug messages about connection attempts, retries and dropped messages.
+   * @example
+   * ```ts
+   * logger: console.debug
+   * ```
+   */
+  logger?: (message: string, ...details: unknown[]) => void;
+  /**
+   * `WebSocket` implementation to use, e.g. a mock in tests or the `ws` package in Node.
+   * When omitted, the global `WebSocket` is used in browsers. During a server render
+   * (no `window`), nothing connects unless an implementation is passed.
+   */
+  WebSocket?: typeof WebSocket;
 }
 /**
  * Reported via the `error` event (and `onError`) when an incoming message can't be
@@ -213,36 +236,36 @@ interface WebSocketOptions<In = unknown, Out = unknown> {
  * }
  * ```
  */
-declare class MessageError extends Error {
-    /** The raw `event.data` that failed. */
-    readonly data: unknown;
-    /** Schema validation issues, when the message failed `schema`. */
-    readonly issues: ReadonlyArray<{
-        readonly message: string;
-    }> | undefined;
-    constructor(message: string, data: unknown, options?: {
-        cause?: unknown;
-        issues?: ReadonlyArray<{
-            readonly message: string;
-        }>;
-    });
+export declare class MessageError extends Error {
+  /** The raw `event.data` that failed. */
+  readonly data: unknown;
+  /** Schema validation issues, when the message failed `schema`. */
+  readonly issues: ReadonlyArray<{
+    readonly message: string;
+  }> | undefined;
+  constructor(message: string, data: unknown, options?: {
+    cause?: unknown;
+    issues?: ReadonlyArray<{
+      readonly message: string;
+    }>;
+  });
 }
 /** Events emitted by a client. Subscribe with `client.on(type, listener)` or `useWebSocketEvent`. */
 interface EventMap<In> {
-    /**
-     * The socket opened (initially or after a reconnect). Listeners run before queued
-     * messages are sent, so a handshake sent from here goes out first.
-     */
-    open: (event: Event) => void;
-    /** A message arrived and passed `parse` and `schema`. */
-    message: (message: In, event: MessageEvent) => void;
-    /** A socket closed, whether it will be retried or not. */
-    close: (close: CloseInfo) => void;
-    /**
-     * A socket error `Event`, a {@link MessageError} for an undecodable or invalid message,
-     * or the `Error` thrown by the `WebSocket` constructor or a `url` function.
-     */
-    error: (error: Event | MessageError | Error) => void;
+  /**
+   * The socket opened (initially or after a reconnect). Listeners run before queued
+   * messages are sent, so a handshake sent from here goes out first.
+   */
+  open: (event: Event) => void;
+  /** A message arrived and passed `parse` and `schema`. */
+  message: (message: In, event: MessageEvent) => void;
+  /** A socket closed, whether it will be retried or not. */
+  close: (close: CloseInfo) => void;
+  /**
+   * A socket error `Event`, a {@link MessageError} for an undecodable or invalid message,
+   * or the `Error` thrown by the `WebSocket` constructor or a `url` function.
+   */
+  error: (error: Event | MessageError | Error) => void;
 }
 /**
  * A WebSocket connection that reconnects, queues, decodes and can be shared.
@@ -256,64 +279,72 @@ interface EventMap<In> {
  * @typeParam Out - Type accepted by `send()`.
  */
 interface WebSocketClient<In = unknown, Out = unknown> {
-    /** The URL (or URL function) the client was created with. */
-    readonly url: UrlSource;
-    /**
-     * A promise that resolves once the socket has opened. Reading it starts an idle client.
-     *
-     * It stays resolved through automatic reconnects, so `use(client.ready)` shows a
-     * Suspense fallback only for the first connection, never on a network blip; use
-     * `status` to show reconnects. It rejects when the client gives up reconnecting, when
-     * `close()` is called, and during a server render. After that, `connect()` or
-     * `reconnect()` make it a new pending promise.
-     *
-     * It is safe to pass to React 19's `use()`: the same promise is returned until its state
-     * changes, and it carries `status`/`value`/`reason` so `use()` doesn't suspend when it is
-     * already settled.
-     */
-    readonly ready: Promise<void>;
-    /** The current underlying `WebSocket`, if any. An escape hatch; prefer the client's methods. */
-    readonly socket: WebSocket | null;
-    /** Subscribe to snapshot changes. Compatible with `useSyncExternalStore`. Returns an unsubscribe function. */
-    subscribe(listener: () => void): () => void;
-    /** The current {@link Snapshot}. Returns the same object until something changes. */
-    getSnapshot(): Snapshot<In>;
-    /**
-     * Listen to an event. Returns an unsubscribe function. Listener errors are re-thrown
-     * asynchronously, so one failing listener doesn't break the others.
-     */
-    on<K extends keyof EventMap<In>>(type: K, listener: EventMap<In>[K]): () => void;
-    /**
-     * 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).
-     * @returns `true` if it was sent immediately, `false` if it was queued or dropped.
-     */
-    send(message: Out): boolean;
-    /**
-     * Start connecting, and keep the connection open even when no hook is using the
-     * client, until `close()` is called. Does nothing if already connecting or open.
-     */
-    connect(): void;
-    /**
-     * Close the connection and stop reconnecting. The status becomes `closed` and the
-     * send queue is cleared. Mounted hooks stay mounted; call `connect()` or `reconnect()`
-     * to start again.
-     * @param code - Close code. @default 1000
-     */
-    close(code?: number, reason?: string): void;
-    /**
-     * Drop the current socket (if any) and connect again immediately, resetting the
-     * backoff. Also restarts a `closed` client.
-     */
-    reconnect(): void;
-    /**
-     * Hold the connection open until the returned function is called. This is what the
-     * hooks use; call it yourself to integrate with non-React code.
-     * @returns A release function (safe to call more than once).
-     */
-    acquire(): () => void;
+  /** The URL (or URL function) the client was created with. */
+  readonly url: UrlSource;
+  /**
+   * A promise that resolves once the socket has opened. Reading it starts an idle client.
+   *
+   * It stays resolved through automatic reconnects, so `use(client.ready)` shows a
+   * Suspense fallback only for the first connection, never on a network blip; use
+   * `status` to show reconnects. It rejects when the client gives up reconnecting, when
+   * `close()` is called, and during a server render. After that, `connect()` or
+   * `reconnect()` make it a new pending promise.
+   *
+   * It is safe to pass to React 19's `use()`: the same promise is returned until its state
+   * changes, and it carries `status`/`value`/`reason` so `use()` doesn't suspend when it is
+   * already settled.
+   */
+  readonly ready: Promise<void>;
+  /** The current underlying `WebSocket`, if any. An escape hatch; prefer the client's methods. */
+  readonly socket: WebSocket | null;
+  /** Subscribe to snapshot changes. Compatible with `useSyncExternalStore`. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+  /** The current {@link Snapshot}. Returns the same object until something changes. */
+  getSnapshot(): Snapshot<In>;
+  /**
+   * Listen to an event. Returns an unsubscribe function. Listener errors are re-thrown
+   * asynchronously, so one failing listener doesn't break the others.
+   */
+  on<K extends keyof EventMap<In>>(type: K, listener: EventMap<In>[K]): () => void;
+  /**
+   * 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.
+   *
+   * @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
+   * ```
+   */
+  send(message: Out, options?: SendOptions): boolean;
+  /**
+   * Start connecting, and keep the connection open even when no hook is using the
+   * client, until `close()` is called. Does nothing if already connecting or open.
+   */
+  connect(): void;
+  /**
+   * Close the connection and stop reconnecting. The status becomes `closed` and the
+   * send queue is cleared. Mounted hooks stay mounted; call `connect()` or `reconnect()`
+   * to start again.
+   * @param code - Close code. @default 1000
+   */
+  close(code?: number, reason?: string): void;
+  /**
+   * Drop the current socket (if any) and connect again immediately, resetting the
+   * backoff. Also restarts a `closed` client.
+   */
+  reconnect(): void;
+  /**
+   * Hold the connection open until the returned function is called. This is what the
+   * hooks use; call it yourself to integrate with non-React code.
+   * @returns A release function (safe to call more than once).
+   */
+  acquire(): () => void;
 }
-
+//#endregion
+//#region src/client.d.ts
 /**
  * Create a WebSocket client, usually at module level, to share across components.
  *
@@ -333,17 +364,302 @@ interface WebSocketClient<In = unknown, Out = unknown> {
  * export const chat = createWebSocket<ChatIn, ChatOut>('wss://api.example.com/chat', { json: true });
  * ```
  */
-declare function createWebSocket<In = unknown, Out = unknown>(url: UrlSource, options?: WebSocketOptions<In, Out>): WebSocketClient<In, Out>;
-
+export declare function createWebSocket<In = unknown, Out = unknown>(url: UrlSource, options?: WebSocketOptions<In, Out>): WebSocketClient<In, Out>;
+//#endregion
+//#region src/latency.d.ts
+/** Options for {@link createWebSocketLatency}: how pings and pongs look on the wire. */
+interface WebSocketLatencyOptions<In, Out> {
+  /** The ping message, tagged with `id`. Sent with `volatile`, so pings are never queued. */
+  ping: (id: number) => Out;
+  /**
+   * Recognize a pong: return the `id` of the ping it answers, and the server's clock
+   * (`Date.now()` on the server, in ms) when it replied. Return `undefined` (or `null`)
+   * for any other message. Without `time`, only the round-trip time is measured.
+   */
+  pong: (message: In) => {
+    id: number | string;
+    time?: number;
+  } | null | undefined;
+  /**
+   * How often to ping while open, in ms. The first ping goes out as soon as the socket opens.
+   * @default 2000
+   */
+  interval?: number;
+  /**
+   * How many recent measurements to keep. `rtt` is their median, and `offset` comes from
+   * the one with the lowest round trip, the most accurate estimate.
+   * @default 5
+   */
+  samples?: number;
+}
+/** Latest latency measurements. A new object is created on every change. */
+interface Latency {
+  /** Round-trip time in ms: the median of recent pings. `undefined` until the first pong. */
+  readonly rtt: number | undefined;
+  /**
+   * Estimated server clock minus local clock, in ms. Add it to `Date.now()` for server time.
+   * `undefined` until a pong carries `time`.
+   */
+  readonly offset: number | undefined;
+}
+/** Round-trip time and server clock offset for one client. Create with {@link createWebSocketLatency}. */
+interface WebSocketLatency {
+  /** The client being measured. Hooks reading the latency keep it connected. */
+  readonly client: WebSocketClient<any, any>;
+  /** The current {@link Latency}. Returns the same object until it changes. */
+  getSnapshot(): Latency;
+  /** Called whenever a measurement changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** The estimated server time: `Date.now() + offset`, or `Date.now()` before any estimate. */
+  serverNow(): number;
+  /** Ping now instead of waiting for the next interval. Does nothing unless the socket is open. */
+  ping(): void;
+  /** Stop pinging and listening. Only needed for instances created dynamically. */
+  dispose(): void;
+}
+/**
+ * Measure round-trip time and estimate the server's clock, for ping displays, countdowns
+ * and timestamps that must agree across players.
+ *
+ * Pings are sent on an interval while the socket is open, and paused otherwise. Measurements
+ * from a previous connection are discarded on reconnect, but the last values stay readable
+ * until new ones arrive. It doesn't open the connection by itself.
+ *
+ * Pongs are ordinary messages: they also reach `onMessage`, `lastMessage` and state stores.
+ *
+ * @example
+ * ```ts
+ * export const latency = createWebSocketLatency(game, {
+ *   ping: id => ({ type: 'ping', id }),
+ *   pong: message => (message.type === 'pong' ? { id: message.id, time: message.time } : undefined)
+ * });
+ *
+ * // In a component:
+ * const { rtt } = useWebSocketLatency(latency);
+ *
+ * // Anywhere: seconds left in a round that ends at the server's `endsAt`.
+ * const left = (endsAt - latency.serverNow()) / 1000;
+ * ```
+ */
+export declare function createWebSocketLatency<In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketLatencyOptions<NoInfer<In>, NoInfer<Out>>): WebSocketLatency;
+//#endregion
+//#region src/requests.d.ts
+/** Options for {@link createWebSocketRequests}: how requests and replies look on the wire. */
+interface WebSocketRequestsOptions<Req, In, Out> {
+  /**
+   * Build the outgoing message for `request(message)`, tagged with `id`. Annotate `message`
+   * to type what `request()` accepts.
+   */
+  send: (message: Req, id: number) => Out;
+  /**
+   * The id an incoming message replies to, or `undefined` (or `null`) if it isn't a reply.
+   * A string id matches the number it was sent as, so either echo works.
+   */
+  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.
+   */
+  error?: (message: In) => unknown;
+  /**
+   * Default time to wait for a reply, in ms. `Infinity` waits forever.
+   * @default 10000
+   */
+  timeout?: number;
+}
+/** Per-call options for {@link WebSocketRequests.request}. */
+interface RequestOptions extends SendOptions {
+  /** Time to wait for a reply, in ms. Overrides the manager's `timeout`. */
+  timeout?: number;
+  /** Abort the request. It rejects 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>;
+  /** Number of requests waiting for a reply. */
+  pending(): number;
+  /** Reject every pending request and stop listening. Only needed for managers created dynamically. */
+  dispose(): void;
+}
+/**
+ * Send requests and await their replies, matched by an id the library generates.
+ *
+ * Replies are ordinary messages: they also reach `onMessage`, `lastMessage` and state stores.
+ *
+ * @example
+ * ```ts
+ * type Request = { type: 'join'; room: string } | { type: 'leave' };
+ *
+ * export const rpc = createWebSocketRequests(game, {
+ *   send: (message: Request, id) => ({ ...message, id }),
+ *   reply: message => (message.type === 'reply' ? message.id : undefined),
+ *   error: message => (message.type === 'reply' && message.error ? new Error(message.error) : undefined)
+ * });
+ *
+ * const reply = await rpc.request({ type: 'join', room: 'lobby' }, { timeout: 5000 });
+ * ```
+ */
+export declare function createWebSocketRequests<Req, In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketRequestsOptions<Req, NoInfer<In>, NoInfer<Out>>): WebSocketRequests<Req, In>;
+//#endregion
+//#region src/responder.d.ts
+/** What `request` returns for a request: any object with these fields, such as the message itself. */
+type RequestFields = {
+  id: number | string;
+  method: string;
+  params?: unknown;
+  timeout?: number;
+};
+/**
+ * The type of `params` in `Q`, keeping `undefined` when they're optional and giving `undefined`
+ * when there are none. (Inferring `params?: P` directly would drop the `undefined`.)
+ */
+type ParamsOf<Q> = Q extends unknown ? 'params' extends keyof Q ? Q['params' & keyof Q] : undefined : never;
+/**
+ * Options for {@link createWebSocketResponder}: how the server's requests and your replies look
+ * on the wire.
+ *
+ * @typeParam Q - What `request` returns. Handlers receive its `params`.
+ * @typeParam R - What handlers return, from the annotation on `respond`'s `result`.
+ */
+interface WebSocketResponderOptions<Q extends RequestFields, R, In, Out> {
+  /**
+   * Recognize a request from the server: its `id`, the `method` handlers are registered for,
+   * and the `params` they receive. Return `undefined` (or `null`) for any other message.
+   * A `timeout` (in ms) overrides the manager's for this request.
+   *
+   * `params` come from the server, so validate them before acting on them.
+   */
+  request: (message: In) => Q | null | undefined;
+  /** Build the reply to request `id`. Annotate `result` to type what handlers return. */
+  respond: (id: number | string, result: R) => Out;
+  /**
+   * Build the error reply to request `id`: what a handler threw, a `NotFoundError` `DOMException`
+   * when nothing is registered for the method, a `TimeoutError` after `timeout`, or an
+   * `AbortError` from `dispose()`.
+   */
+  error: (id: number | string, error: unknown) => Out;
+  /**
+   * The id of a request the server withdrew, or `undefined` (or `null`) if the message isn't a
+   * cancellation. The request's `signal` aborts and nothing is sent.
+   */
+  cancel?: (message: In) => number | string | null | undefined;
+  /**
+   * Time to answer a request, in ms. When it runs out, the `error` reply (a `TimeoutError`)
+   * is sent and the request's `signal` aborts.
+   * @default Infinity
+   */
+  timeout?: number;
+}
+/** A request from the server that hasn't been answered yet. */
+interface IncomingRequest<P = unknown, R = unknown> {
+  /** The id the server sent. Replies carry it back. */
+  readonly id: number | string;
+  /** The method it was sent for. */
+  readonly method: string;
+  /** The `params` from `request`. They come from the server, so validate them. */
+  readonly params: P;
+  /**
+   * Aborts when the answer is no longer wanted: the server cancelled the request, it timed out,
+   * the connection it arrived on closed, the responder was disposed, or it was answered with
+   * `respond` or `reject` while its handler was still running.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Reply with `result`. Only the first answer counts.
+   * @returns `true` if the reply was sent, `false` if the request was already answered or is gone.
+   */
+  respond(result: R): boolean;
+  /**
+   * Reply with an error, built by the `error` option. Only the first answer counts.
+   * @returns `true` if the reply was sent, `false` if the request was already answered or is gone.
+   */
+  reject(error: unknown): boolean;
+}
+/**
+ * Answers a request in code. Return (or resolve) the result to reply with it; throw (or reject)
+ * to send the `error` reply instead.
+ */
+type RequestHandler<P = unknown, R = unknown> = (params: P, request: IncomingRequest<P, R>) => R | PromiseLike<R>;
+/** Answers the server's requests on one client. Create with {@link createWebSocketResponder}. */
+interface WebSocketResponder<P = unknown, R = unknown> {
+  /** The client requests arrive on. Hooks reading the responder keep it connected. */
+  readonly client: WebSocketClient<any, any>;
+  /**
+   * Answer requests for `method` until the returned function is called.
+   *
+   * With a `handler`, requests are answered in code. Without one, they wait in
+   * {@link getSnapshot} until something calls `respond` or `reject` on them, e.g. a dialog
+   * that asks the user. When several registrations exist for one method, the newest one takes
+   * new requests, and unregistering it hands them back to the previous one. Requests for a
+   * method with no registration get a `NotFoundError` reply.
+   *
+   * @returns An unregister function (safe to call more than once). Requests already waiting stay.
+   */
+  onRequest(method: string, handler?: RequestHandler<P, R>): () => void;
+  /**
+   * Requests waiting for an answer from outside a handler, oldest first. Returns the same array
+   * until it changes.
+   */
+  getSnapshot(): readonly IncomingRequest<P, R>[];
+  /** Called whenever {@link getSnapshot} changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /**
+   * Stop answering: send an `AbortError` reply to every request in flight and stop listening.
+   * Only needed for responders created dynamically.
+   */
+  dispose(): void;
+}
+/**
+ * Answer requests the server sends: run a handler for tools that only exist in the browser
+ * (selection, clipboard, geolocation), or let a person answer, e.g. to approve an agent's action.
+ * The reverse of `createWebSocketRequests`.
+ *
+ * Every request gets exactly one reply while its connection lives: the handler's result, an
+ * `error` reply when it throws, has no registration or times out. When the connection a request
+ * arrived on closes, the request is dropped and nothing is sent, since the server can't match a
+ * reply on a new connection. Replies are never queued.
+ *
+ * Requests are ordinary messages: they also reach `onMessage`, `lastMessage` and state stores.
+ *
+ * @example
+ * ```ts
+ * export const tools = createWebSocketResponder(agent, {
+ *   request: message => (message.type === 'call' ? message : undefined),
+ *   respond: (id, result: unknown) => ({ type: 'result', id, result }),
+ *   error: (id, error) => ({ type: 'result', id, error: String(error) })
+ * });
+ *
+ * tools.onRequest('get_selection', () => window.getSelection()?.toString() ?? '');
+ *
+ * // In a component: requests a person answers.
+ * const approvals = useAgentApproval(tools, 'approve');
+ * approvals[0]?.respond({ approved: true });
+ * ```
+ */
+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/state.d.ts
 /** Options for {@link createWebSocketState}. */
 interface WebSocketStateOptions<S, In> {
-    /** The state before any message arrives, and what `reset()` returns to. */
-    initialState: S;
-    /**
-     * Fold one incoming message into the state. Must be pure: return a new object for a
-     * change, or the same `state` to ignore the message (subscribers aren't notified).
-     */
-    reduce: (state: S, message: In) => S;
+  /** The state before any message arrives, and what `reset()` returns to. */
+  initialState: S;
+  /**
+   * Fold one incoming message into the state. Must be pure: return a new object for a
+   * change, or the same `state` to ignore the message (subscribers aren't notified).
+   */
+  reduce: (state: S, message: In) => S;
 }
 /**
  * State derived from a client's messages. Read it with `useWebSocketState(store, selector)`,
@@ -352,20 +668,20 @@ interface WebSocketStateOptions<S, In> {
  * @typeParam S - The state type. Don't use a function type: `setState` treats functions as updaters.
  */
 interface WebSocketState<S> {
-    /** The client whose messages this store reduces. Hooks reading the store keep it connected. */
-    readonly client: WebSocketClient<any, any>;
-    /** The `initialState` it was created with. Used for server rendering and hydration. */
-    readonly initialState: S;
-    /** The current state. Returns the same object until it changes. */
-    getState(): S;
-    /** Called whenever the state changes. Compatible with `useSyncExternalStore`. */
-    subscribe(listener: () => void): () => void;
-    /** Replace the state, or update it from the current one, e.g. for optimistic updates. */
-    setState(update: S | ((state: S) => S)): void;
-    /** Go back to `initialState`. */
-    reset(): void;
-    /** Stop reducing messages. Only needed for stores created dynamically rather than at module level. */
-    dispose(): void;
+  /** The client whose messages this store reduces. Hooks reading the store keep it connected. */
+  readonly client: WebSocketClient<any, any>;
+  /** The `initialState` it was created with. Used for server rendering and hydration. */
+  readonly initialState: S;
+  /** The current state. Returns the same object until it changes. */
+  getState(): S;
+  /** Called whenever the state changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Replace the state, or update it from the current one, e.g. for optimistic updates. */
+  setState(update: S | ((state: S) => S)): void;
+  /** Go back to `initialState`. */
+  reset(): void;
+  /** Stop reducing messages. Only needed for stores created dynamically rather than at module level. */
+  dispose(): void;
 }
 /**
  * Keep state derived from a client's messages, like a reducer that runs on every message.
@@ -385,28 +701,29 @@ interface WebSocketState<S> {
  * const acme = useWebSocketState(priceState, state => state.ACME);
  * ```
  */
-declare function createWebSocketState<S, In>(client: WebSocketClient<In, any>, options: WebSocketStateOptions<S, NoInfer<In>>): WebSocketState<S>;
-
+export declare function createWebSocketState<S, In>(client: WebSocketClient<In, any>, options: WebSocketStateOptions<S, NoInfer<In>>): WebSocketState<S>;
+//#endregion
+//#region src/topics.d.ts
 /** Options for {@link createWebSocketTopics}: the messages your server expects. */
 interface WebSocketTopicsOptions<Out> {
-    /** The message that subscribes to `topic`. */
-    subscribe: (topic: string) => Out;
-    /** The message that unsubscribes from `topic`. Omit it if your server has none. */
-    unsubscribe?: (topic: string) => Out;
+  /** The message that subscribes to `topic`. */
+  subscribe: (topic: string) => Out;
+  /** The message that unsubscribes from `topic`. Omit it if your server has none. */
+  unsubscribe?: (topic: string) => Out;
 }
 /** Reference-counted topic subscriptions on one client. Create with {@link createWebSocketTopics}. */
 interface WebSocketTopics {
-    /** The client the subscription messages are sent on. */
-    readonly client: WebSocketClient<any, any>;
-    /**
-     * Hold a subscription to `topic`, and the client's connection, until the returned
-     * function is called. The release function is safe to call more than once.
-     */
-    acquire(topic: string): () => void;
-    /** The topics currently held, in the order they were first acquired. */
-    active(): string[];
-    /** Stop managing subscriptions. Only needed for managers created dynamically. */
-    dispose(): void;
+  /** The client the subscription messages are sent on. */
+  readonly client: WebSocketClient<any, any>;
+  /**
+   * Hold a subscription to `topic`, and the client's connection, until the returned
+   * function is called. The release function is safe to call more than once.
+   */
+  acquire(topic: string): () => void;
+  /** The topics currently held, in the order they were first acquired. */
+  active(): string[];
+  /** Stop managing subscriptions. Only needed for managers created dynamically. */
+  dispose(): void;
 }
 /**
  * Manage topic subscriptions that survive reconnects.
@@ -430,41 +747,44 @@ interface WebSocketTopics {
  * useWebSocketTopic(topics, `prices:${symbol}`);
  * ```
  */
-declare function createWebSocketTopics<const Out>(client: WebSocketClient<any, Out>, options: WebSocketTopicsOptions<NoInfer<Out>>): WebSocketTopics;
-
+export declare function createWebSocketTopics<const Out>(client: WebSocketClient<any, Out>, options: WebSocketTopicsOptions<NoInfer<Out>>): WebSocketTopics;
+//#endregion
+//#region src/react.d.ts
 /**
  * Per-component event handlers. They always see the component's latest props and
  * state, and changing them never reconnects.
  */
 interface WebSocketHandlers<In> {
-    /** The socket opened (initially or after a reconnect). */
-    onOpen?: (event: Event) => void;
-    /** A message arrived and passed `parse`/`json` and `schema`. */
-    onMessage?: (message: In, event: MessageEvent) => void;
-    /** A socket closed. Called whether or not it will be retried. */
-    onClose?: (close: CloseInfo) => void;
-    /** A socket error `Event`, a `MessageError`, or an `Error` from the constructor or `url` function. */
-    onError?: (error: Event | Error) => void;
-    /**
-     * `false` releases this component's hold on the connection and stops its handlers.
-     * The connection closes once nothing else holds it.
-     * @default true
-     */
-    enabled?: boolean;
+  /** The socket opened (initially or after a reconnect). */
+  onOpen?: (event: Event) => void;
+  /** A message arrived and passed `parse`/`json` and `schema`. */
+  onMessage?: (message: In, event: MessageEvent) => void;
+  /** A socket closed. Called whether or not it will be retried. */
+  onClose?: (close: CloseInfo) => void;
+  /** A socket error `Event`, a `MessageError`, or an `Error` from the constructor or `url` function. */
+  onError?: (error: Event | Error) => void;
+  /**
+   * `false` releases this component's hold on the connection and stops its handlers.
+   * The connection closes once nothing else holds it.
+   * @default true
+   */
+  enabled?: boolean;
 }
 /** Options for `useWebSocket(url, options)`: connection options plus handlers. */
-interface UseWebSocketOptions<In, Out> extends WebSocketOptions<In, Out>, WebSocketHandlers<In> {
-}
+interface UseWebSocketOptions<In, Out> extends WebSocketOptions<In, Out>, WebSocketHandlers<In> {}
 /** What `useWebSocket` returns: the current {@link Snapshot} plus stable actions. */
 interface UseWebSocketResult<In, Out> extends Snapshot<In> {
-    /** Send now, or queue until open. Returns `true` if sent immediately. Stable identity. */
-    send: (message: Out) => boolean;
-    /** Close and stop reconnecting (for every component sharing the connection). Stable identity. */
-    close: (code?: number, reason?: string) => void;
-    /** Drop the socket and connect again right away. Stable identity. */
-    reconnect: () => void;
-    /** The underlying client, or `null` when the URL is `null`/`undefined`. */
-    client: WebSocketClient<In, Out> | null;
+  /**
+   * Send now, or queue until open (see {@link SendOptions} for volatile and keyed sends).
+   * Returns `true` if sent immediately. Stable identity.
+   */
+  send: (message: Out, options?: SendOptions) => boolean;
+  /** Close and stop reconnecting (for every component sharing the connection). Stable identity. */
+  close: (code?: number, reason?: string) => void;
+  /** Drop the socket and connect again right away. Stable identity. */
+  reconnect: () => void;
+  /** The underlying client, or `null` when the URL is `null`/`undefined`. */
+  client: WebSocketClient<In, Out> | null;
 }
 /**
  * Connect to a WebSocket and re-render with its status and latest message.
@@ -489,8 +809,8 @@ interface UseWebSocketResult<In, Out> extends Snapshot<In> {
  * });
  * ```
  */
-declare function useWebSocket<In = unknown, Out = unknown>(url: string | null | undefined, options?: UseWebSocketOptions<In, Out>): UseWebSocketResult<In, Out>;
-declare function useWebSocket<In, Out>(client: WebSocketClient<In, Out> | null | undefined, options?: WebSocketHandlers<In>): UseWebSocketResult<In, Out>;
+export declare function useWebSocket<In = unknown, Out = unknown>(url: string | null | undefined, options?: UseWebSocketOptions<In, Out>): UseWebSocketResult<In, Out>;
+export declare function useWebSocket<In, Out>(client: WebSocketClient<In, Out> | null | undefined, options?: WebSocketHandlers<In>): UseWebSocketResult<In, Out>;
 /**
  * Listen to a client's events without re-rendering the component. The listener always
  * sees the latest props and state. Keeps the connection open while mounted.
@@ -500,7 +820,7 @@ declare function useWebSocket<In, Out>(client: WebSocketClient<In, Out> | null |
  * useWebSocketEvent(chat, 'message', message => setMessages(list => [...list, message]));
  * ```
  */
-declare function useWebSocketEvent<In, K extends keyof EventMap<In>>(client: WebSocketClient<In, any> | null | undefined, type: K, listener: EventMap<In>[K]): void;
+export declare function useWebSocketEvent<In, K extends keyof EventMap<In>>(client: WebSocketClient<In, any> | null | undefined, type: K, listener: EventMap<In>[K]): void;
 /**
  * The connection status of a client. Re-renders only when the status changes, not on
  * messages. Keeps the connection open while mounted.
@@ -510,7 +830,7 @@ declare function useWebSocketEvent<In, K extends keyof EventMap<In>>(client: Web
  * const status = useWebSocketStatus(chat); // 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed'
  * ```
  */
-declare function useWebSocketStatus(client: WebSocketClient<any, any> | null | undefined): Status;
+export declare function useWebSocketStatus(client: WebSocketClient<any, any> | null | undefined): Status;
 /**
  * Read state built from messages by `createWebSocketState`. Re-renders only when the
  * selected value changes (by `isEqual`, default `Object.is`), however often messages
@@ -523,8 +843,8 @@ declare function useWebSocketStatus(client: WebSocketClient<any, any> | null | u
  * const acme = useWebSocketState(priceState, state => state.ACME);
  * ```
  */
-declare function useWebSocketState<S>(store: WebSocketState<S>): S;
-declare function useWebSocketState<S, T>(store: WebSocketState<S>, selector: (state: S) => T, isEqual?: (a: T, b: T) => boolean): T;
+export declare function useWebSocketState<S>(store: WebSocketState<S>): S;
+export declare function useWebSocketState<S, T>(store: WebSocketState<S>, selector: (state: S) => T, isEqual?: (a: T, b: T) => boolean): T;
 /**
  * Subscribe to one topic (or several) while mounted, through a `createWebSocketTopics`
  * manager. Components holding the same topic share one subscription, and it is sent again
@@ -536,6 +856,42 @@ declare function useWebSocketState<S, T>(store: WebSocketState<S>, selector: (st
  * useWebSocketTopic(topics, watchlist.map(symbol => `prices:${symbol}`));
  * ```
  */
-declare function useWebSocketTopic(topics: WebSocketTopics | null | undefined, topic: string | readonly string[] | null | undefined): void;
-
-export { type CloseInfo, type EventMap, type HeartbeatOptions, MessageError, type QueueOptions, type ReconnectOptions, type SendData, type Snapshot, type StandardSchemaV1, type Status, type UrlSource, type UseWebSocketOptions, type UseWebSocketResult, type WebSocketClient, type WebSocketHandlers, type WebSocketOptions, type WebSocketState, type WebSocketStateOptions, type WebSocketTopics, type WebSocketTopicsOptions, createWebSocket, createWebSocketState, createWebSocketTopics, useWebSocket, useWebSocketEvent, useWebSocketState, useWebSocketStatus, useWebSocketTopic };
+export declare function useWebSocketTopic(topics: WebSocketTopics | null | undefined, topic: string | readonly string[] | null | undefined): void;
+/**
+ * Read round-trip time and server clock offset from a `createWebSocketLatency` instance.
+ * Re-renders when a measurement changes, about once per ping interval. Keeps the connection
+ * open while mounted. On the server, and during hydration, both values are `undefined`.
+ *
+ * @example
+ * ```tsx
+ * const { rtt } = useWebSocketLatency(latency);
+ * return <span>{rtt === undefined ? '–' : `${Math.round(rtt)} ms`}</span>;
+ * ```
+ */
+export declare function useWebSocketLatency(latency: WebSocketLatency): Latency;
+/**
+ * Requests for `method` that a person answers, e.g. an agent asking to run a tool. While mounted,
+ * it registers `method` on the responder without a handler, so new requests wait here instead of
+ * getting a `NotFoundError` reply. Call `respond` or `reject` on one to answer it. Re-renders
+ * when the list changes. Keeps the connection open while mounted. `null` holds nothing.
+ *
+ * Requests stay listed after unmount until they are answered, time out, are cancelled or lose
+ * their connection, so a remounted dialog shows them again. On the server the list is empty.
+ *
+ * @example
+ * ```tsx
+ * const [request] = useAgentApproval(tools, 'approve');
+ * if (!request) return null;
+ * return (
+ *   <dialog open>
+ *     {request.params.summary}
+ *     <button onClick={() => request.respond({ approved: true })}>Approve</button>
+ *     <button onClick={() => request.respond({ approved: false })}>Deny</button>
+ *   </dialog>
+ * );
+ * ```
+ */
+export declare function useAgentApproval<P, R>(responder: WebSocketResponder<P, R> | null | undefined, method: string | null | undefined): readonly IncomingRequest<P, R>[];
+//#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 };
+//# sourceMappingURL=index.d.cts.map