react-websocket 3.6.0 → 4.18.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 
+import { RefObject } from "react";
 //#region src/types.d.ts
 /**
  * Where to connect: a URL, or a function that returns one (sync or async).
@@ -21,7 +22,8 @@ type UrlSource = string | (() => string | Promise<string>);
  * - `open`: connected. `send()` goes out immediately.
  * - `reconnecting`: the connection dropped (or an attempt failed) and a retry is scheduled or in progress.
  * - `closed`: stopped for good, by `close()` or after giving up on reconnecting.
- *   It stays closed until `connect()` or `reconnect()` is called, or every hook unmounts.
+ *   It stays closed until `connect()` or `reconnect()` is called, or every hook unmounts. If
+ *   nothing held it when it stopped, the next hook to mount starts it again.
  */
 type Status = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed';
 /** The client's state as seen by React. A new object is created on every change. */
@@ -30,7 +32,10 @@ interface Snapshot<In> {
   readonly status: Status;
   /** Most recent message (after `parse`/`json` and `schema`), kept across reconnects. */
   readonly lastMessage: In | undefined;
-  /** Consecutive failed attempts since the last successful open. `0` while open. */
+  /**
+   * Consecutive failed attempts since the last stable connection. A connection that closes
+   * within `reconnect.minUptime` of opening counts as failed. `0` while open.
+   */
   readonly attempt: number;
 }
 /** Details of a closed connection, from the browser's `CloseEvent`. */
@@ -52,6 +57,14 @@ interface ReconnectOptions {
    * @default Infinity
    */
   maxAttempts?: number;
+  /**
+   * How long a connection must stay open, in ms, before the backoff resets. One that closes
+   * sooner counts as a failed attempt, so a server that accepts and then closes right away
+   * (e.g. rejecting the credentials sent on open) is retried with a growing delay, and
+   * `maxAttempts` still applies. `0` resets on every open.
+   * @default 5000
+   */
+  minUptime?: number;
   /**
    * Delay before the first retry, in ms.
    * @default 1000
@@ -69,21 +82,67 @@ interface ReconnectOptions {
   factor?: number;
   /**
    * Randomly shave up to this fraction (0–1) off each delay, so that many clients
-   * dropped at once don't all reconnect at the same moment.
-   * @default 0.5
+   * dropped at once don't all reconnect at the same moment. The default `1` picks each
+   * delay at random between 0 and the backoff ("full jitter").
+   * @default 1
    */
   jitter?: number;
   /**
    * Called on every unexpected close. Return `false` to stop reconnecting.
    *
+   * The default, `retryableClose`, retries everything except `1002` (protocol error), `1003`
+   * (unsupported data) and `1008` (policy violation). Your own function replaces it; call
+   * `retryableClose` from it to keep that rule, or return `true` to retry every close.
+   *
    * @example
    * ```ts
-   * // Don't retry when the server rejects our credentials.
-   * shouldReconnect: close => close.code !== 4001
+   * import { retryableClose } from 'react-websocket';
+   *
+   * // Also stop when our server rejects the credentials.
+   * shouldReconnect: close => close.code !== 4001 && retryableClose(close)
    * ```
-   * @default () => true
+   * @default retryableClose
    */
   shouldReconnect?: (close: CloseInfo) => boolean;
+  /**
+   * How long the server asked the client to wait before trying again, in ms, read from the
+   * close. Return `undefined` when it didn't ask. The client waits that long plus the usual
+   * backoff, so clients told the same delay still spread out, and the `online` and
+   * `visibilitychange` events don't cut the wait short.
+   *
+   * The default, `retryAfter`, reads a `1012` (Service Restart) or `1013` (Try Again Later)
+   * close whose reason is a number of seconds, like an HTTP `Retry-After` header. Your own
+   * function replaces it.
+   *
+   * A `1013` close that names no delay still waits longer than other closes: its backoff starts
+   * at `maxDelay`.
+   *
+   * @example
+   * ```ts
+   * import { retryAfter } from 'react-websocket';
+   *
+   * // Our server also closes with 4429 and the delay in ms as the reason.
+   * retryAfter: close => (close.code === 4429 ? Number(close.reason) : retryAfter(close))
+   * ```
+   * @default retryAfter
+   */
+  retryAfter?: (close: CloseInfo) => number | undefined;
+}
+/** Options for `client.migrate()`. */
+interface MigrateOptions {
+  /**
+   * Where to connect instead: a URL, or a function called before the connection, like the
+   * client's own `url`. Later reconnects go there too, until the client is closed, gives up or
+   * is torn down.
+   * @default the client's current URL
+   */
+  url?: UrlSource;
+  /**
+   * Move at a random moment within this many ms, so that clients asked to move together don't
+   * all reconnect at once.
+   * @default 0
+   */
+  within?: number;
 }
 /** Application-level keep-alive. Useful behind proxies that drop idle connections. */
 interface HeartbeatOptions {
@@ -99,6 +158,10 @@ interface HeartbeatOptions {
   /**
    * 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.
+   *
+   * A ping also goes out right away when the browser comes back online or the tab becomes
+   * visible, so a connection that died during sleep is found within `timeout`, not after up
+   * to `interval` more.
    */
   timeout?: number;
 }
@@ -143,11 +206,19 @@ interface SendOptions {
    * ```
    */
   maxBuffered?: number;
+  /**
+   * Drop the message instead of sending it if it has been queued for longer than this many
+   * ms, for messages that go stale during a long outage, such as "typing" or a price quote.
+   * Overrides `queue.maxAge`. Checked when the socket opens and whenever another message is
+   * queued; `onDrop` is called then.
+   */
+  maxAge?: 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, or when `send()` drops the
-   * message right away (`volatile` while not open, or `maxBuffered`) and returns `false`.
+   * newer message with the same `key`, evicted by `queue.limit`, or older than `maxAge`. Not
+   * called when the 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;
 }
@@ -156,9 +227,17 @@ interface QueueOptions {
   /**
    * Maximum number of messages held while not connected. When full, the oldest
    * message is dropped, skipping `priority` messages unless nothing else is queued.
-   * @default Infinity
+   * `Infinity` keeps every message.
+   * @default 100
    */
   limit?: number;
+  /**
+   * Drop a queued message instead of sending it once it has waited longer than this many ms,
+   * calling its `onDrop`. A message's own `maxAge` overrides it. Checked when the socket opens
+   * and whenever another message is queued.
+   * @default Infinity
+   */
+  maxAge?: number;
 }
 /**
  * The minimal [Standard Schema v1](https://standardschema.dev) interface, implemented
@@ -232,8 +311,8 @@ interface WebSocketOptions<In = unknown, Out = unknown> {
   heartbeat?: HeartbeatOptions;
   /**
    * Buffer `send()` calls made while not connected and send them, in order, on open
-   * (right after `open` listeners run).
-   * `false` drops them instead. `{ limit }` caps the buffer, dropping the oldest.
+   * (right after `open` listeners run). It holds up to 100 messages, dropping the oldest;
+   * `{ limit }` changes that. `false` drops messages instead of queueing them.
    * The queue is cleared by `close()` or when the client gives up.
    * @default true
    */
@@ -357,7 +436,10 @@ interface WebSocketClient<In = unknown, Out = unknown> {
   /**
    * 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.
+   * to start again. Closed while no hook holds it, the next hook to mount starts it again.
+   *
+   * Like `WebSocket.close()`, it throws for a code or reason the socket rejects (browsers take
+   * `1000` or `3000`–`4999`, and a reason up to 123 bytes), and then nothing has changed.
    * @param code - Close code. @default 1000
    */
   close(code?: number, reason?: string): void;
@@ -366,6 +448,28 @@ interface WebSocketClient<In = unknown, Out = unknown> {
    * backoff. Also restarts a `closed` client.
    */
   reconnect(): void;
+  /**
+   * Move to a new connection without a gap, for example when the server asks its clients to
+   * before a deploy. At a random moment within `options.within` ms, it opens a new connection
+   * (to `options.url`, if given) and, once that one is open, closes the current one with code
+   * `1000`. Until then the current connection keeps working, so the status stays `open` and
+   * `send()` doesn't queue.
+   *
+   * `open` listeners run for the new connection, as after any reconnect, so handshakes and
+   * topic subscriptions are sent again. Requests the old connection hadn't answered fail as on
+   * a lost connection. If the new connection fails before opening, the current one stays. If
+   * the client isn't open when the moment comes, only the URL changes, for the next attempt.
+   * A later call replaces one that hasn't moved yet.
+   *
+   * @example
+   * ```ts
+   * // The server sends { type: 'reconnect', within: 30000 } before it shuts down.
+   * live.on('message', message => {
+   *   if (message.type === 'reconnect') live.migrate({ within: message.within, url: message.url });
+   * });
+   * ```
+   */
+  migrate(options?: MigrateOptions): 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.
@@ -375,6 +479,34 @@ interface WebSocketClient<In = unknown, Out = unknown> {
 }
 //#endregion
 //#region src/client.d.ts
+/**
+ * The default `reconnect.shouldReconnect`: retry every close except `1002` (protocol error),
+ * `1003` (unsupported data) and `1008` (policy violation, often a rejected login), which
+ * retrying the same way can't fix. Call it from your own `shouldReconnect` to keep that rule.
+ *
+ * @example
+ * ```ts
+ * createWebSocket(url, {
+ *   // Also stop on our server's "invalid token" code.
+ *   reconnect: { shouldReconnect: close => close.code !== 4001 && retryableClose(close) }
+ * });
+ * ```
+ */
+export declare function retryableClose(close: CloseInfo): boolean;
+/**
+ * The default `reconnect.retryAfter`: for a `1012` (Service Restart) or `1013` (Try Again Later)
+ * close whose reason is a number of seconds, like an HTTP `Retry-After` header, that delay in ms.
+ * Call it from your own `retryAfter` to keep reading it.
+ *
+ * @example
+ * ```ts
+ * createWebSocket(url, {
+ *   // Our server also closes with 4429 and the delay in ms as the reason.
+ *   reconnect: { retryAfter: close => (close.code === 4429 ? Number(close.reason) : retryAfter(close)) }
+ * });
+ * ```
+ */
+export declare function retryAfter(close: CloseInfo): number | undefined;
 /**
  * Create a WebSocket client, usually at module level, to share across components.
  *
@@ -396,6 +528,131 @@ interface WebSocketClient<In = unknown, Out = unknown> {
  */
 export declare function createWebSocket<In = unknown, Out = unknown>(url: UrlSource, options?: WebSocketOptions<In, Out>): WebSocketClient<In, Out>;
 //#endregion
+//#region src/topics.d.ts
+/** @internal Option key for a callback run when nothing holds a topic anymore. Used by feeds. */
+declare const ON_RELEASE: unique symbol;
+/** 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;
+}
+/** 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;
+}
+/**
+ * Manage topic subscriptions that survive reconnects.
+ *
+ * - The first holder of a topic sends `subscribe(topic)`. Later holders share it.
+ * - A tick after the last holder releases it, `unsubscribe(topic)` is sent, so StrictMode
+ *   and route transitions don't churn subscriptions.
+ * - After every reconnect, every held topic is subscribed again on the new socket, before
+ *   messages queued while disconnected are sent.
+ *
+ * Subscriptions are only sent while the socket is open; nothing is queued for them.
+ *
+ * @example
+ * ```ts
+ * export const topics = createWebSocketTopics(live, {
+ *   subscribe: topic => ({ type: 'subscribe', topic }),
+ *   unsubscribe: topic => ({ type: 'unsubscribe', topic })
+ * });
+ *
+ * // In a component:
+ * useWebSocketTopic(topics, `prices:${symbol}`);
+ * ```
+ */
+export declare function createWebSocketTopics<const Out>(client: WebSocketClient<any, Out>, options: WebSocketTopicsOptions<NoInfer<Out>> & {
+  [ON_RELEASE]?: (topic: string) => void;
+}): WebSocketTopics;
+//#endregion
+//#region src/feeds.d.ts
+/** Where a numbered message belongs: its topic, and its sequence number in that topic. */
+interface FeedPosition {
+  readonly topic: string;
+  /** One more than the message before it on the same topic. */
+  readonly seq: number;
+}
+/** Options for {@link createWebSocketFeeds}: the messages your server expects and sends. */
+interface WebSocketFeedsOptions<In, Out> {
+  /**
+   * The message that subscribes to `topic`. `after` is the sequence number of the last message
+   * received on it, so the server can send the ones after it, or `undefined` the first time.
+   * Sent on every new connection too.
+   */
+  subscribe: (topic: string, after: number | undefined) => Out;
+  /** The message that unsubscribes from `topic`. Omit it if your server has none. */
+  unsubscribe?: (topic: string) => Out;
+  /**
+   * The message that asks for what came after `after` when messages went missing on an open
+   * connection. Defaults to `subscribe(topic, after)`.
+   */
+  resume?: (topic: string, after: number) => Out;
+  /** Recognize a numbered message: its topic and sequence number. `undefined` for any other. */
+  sequence: (message: In) => FeedPosition | null | undefined;
+  /**
+   * Recognize a snapshot: a topic's whole state as of `seq`, which the server sends when it
+   * can't replay the messages after `after`. It's always delivered, and the numbering goes on
+   * from it.
+   */
+  snapshot?: (message: In) => FeedPosition | null | undefined;
+  /** Called when a message arrives after a gap, before the missing ones are asked for. */
+  onGap?: (topic: string, after: number, received: number) => void;
+}
+/**
+ * Topic subscriptions whose messages are numbered. A {@link WebSocketTopics}, so
+ * `useWebSocketTopic` takes it, and a message source for `createWebSocketState`.
+ * Create with {@link createWebSocketFeeds}.
+ */
+interface WebSocketFeeds<In> extends WebSocketTopics {
+  /**
+   * Listen to messages in order: numbered ones once each and without gaps, others as they
+   * arrive. Returns an unsubscribe function.
+   */
+  on(type: 'message', listener: (message: In, event: MessageEvent) => void): () => void;
+  /** The sequence number of the last message delivered on `topic`, while it's held. */
+  position(topic: string): number | undefined;
+}
+/**
+ * Subscribe to topics whose messages carry a sequence number, and get each message once, in
+ * order, across reconnects:
+ *
+ * - On every new connection, each held topic is subscribed again with `after`, the last
+ *   number received, so the server sends what was missed instead of everything.
+ * - A message numbered at or below the last one is a duplicate and is dropped.
+ * - A message that skips numbers is held back, and the topic asks for what's missing (`resume`)
+ *   once, so nothing is delivered out of order.
+ * - A server that can't replay sends a `snapshot`, and the numbering goes on from it.
+ *
+ * Listen with `feeds.on('message', …)`, or pass `feeds` to `createWebSocketState` in place of
+ * the client. Hold topics with `useWebSocketTopic(feeds, topic)` or `feeds.acquire(topic)`.
+ *
+ * @example
+ * ```ts
+ * export const feeds = createWebSocketFeeds(live, {
+ *   subscribe: (topic, after) => ({ type: 'subscribe', topic, after }),
+ *   unsubscribe: topic => ({ type: 'unsubscribe', topic }),
+ *   sequence: message => (message.type === 'event' ? message : undefined),
+ *   snapshot: message => (message.type === 'snapshot' ? message : undefined)
+ * });
+ *
+ * export const chat = createWebSocketState(feeds, { initialState: [], reduce: addMessage });
+ * ```
+ */
+export declare function createWebSocketFeeds<In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketFeedsOptions<NoInfer<In>, NoInfer<Out>>): WebSocketFeeds<In>;
+//#endregion
 //#region src/latency.d.ts
 /** Options for {@link createWebSocketLatency}: how pings and pongs look on the wire. */
 interface WebSocketLatencyOptions<In, Out> {
@@ -473,6 +730,91 @@ interface WebSocketLatency {
  */
 export declare function createWebSocketLatency<In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketLatencyOptions<NoInfer<In>, NoInfer<Out>>): WebSocketLatency;
 //#endregion
+//#region src/presence.d.ts
+/** Another client's shared state, such as its cursor or what it's selected. */
+interface PresencePeer<P> {
+  /** The peer's id, as the server reports it. */
+  readonly peer: string;
+  readonly state: P;
+  /** When its state last arrived, from `Date.now()`. */
+  readonly updatedAt: number;
+}
+/** Options for {@link createWebSocketPresence}: the messages your server relays. */
+interface WebSocketPresenceOptions<P, In, Out> {
+  /** The message that shares this client's state with the others. Annotate `state`. */
+  send: (state: P) => Out;
+  /** The message that says this client left, sent by `leave()`. Omit it if the server has none. */
+  leave?: () => Out;
+  /**
+   * Recognize another peer's state: its id and state, or `state: null` when it left. `undefined`
+   * for any other message.
+   */
+  receive: (message: In) => {
+    readonly peer: string;
+    readonly state: P | null;
+  } | null | undefined;
+  /**
+   * Forget a peer that hasn't sent its state for this long, in ms, as if it had left. Covers
+   * peers whose connection died without the server noticing.
+   * @default 30000
+   */
+  timeout?: number;
+  /**
+   * Send this client's state again this often while it doesn't change, in ms, so the others
+   * don't forget it.
+   * @default timeout / 3
+   */
+  refresh?: number;
+  /**
+   * How many times per second this client's state may be sent. Changes in between are
+   * coalesced: the newest goes out at the end of the interval.
+   * @default 20
+   */
+  maxRate?: number;
+}
+/** Shared per-peer state that expires. Create with {@link createWebSocketPresence}. */
+interface WebSocketPresence<P> {
+  /** The client the state is shared on. */
+  readonly client: WebSocketClient<any, any>;
+  /**
+   * Share this client's state, e.g. on every pointer move. It's sent at most `maxRate` times per
+   * second, the newest only, and again on every new connection and every `refresh`.
+   */
+  set(state: P): void;
+  /** Stop sharing, and send `leave`. `set()` shares again. */
+  leave(): void;
+  /** The other peers, in the order they first appeared. A new array on every change. */
+  getSnapshot(): readonly PresencePeer<P>[];
+  /** Get notified when the peers change. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Stop sharing and listening. */
+  dispose(): void;
+}
+/**
+ * Share per-peer state that expires, for presence, live cursors and selections.
+ *
+ * - `set(state)` shares this client's state, throttled to `maxRate` sends per second with the
+ *   newest winning, and sent again on every new connection and every `refresh`, so it's never
+ *   queued stale while disconnected.
+ * - Other peers' states come from `receive`. A peer is forgotten when it leaves (`state: null`)
+ *   or when nothing has arrived from it for `timeout`.
+ *
+ * The server relays each client's state to the others, tagged with a peer id, and says
+ * `state: null` when a client disconnects.
+ *
+ * @example
+ * ```ts
+ * export const cursors = createWebSocketPresence(room, {
+ *   send: (cursor: { x: number; y: number }) => ({ type: 'cursor', cursor }),
+ *   leave: () => ({ type: 'leave' }),
+ *   receive: message => (message.type === 'cursor' ? { peer: message.peer, state: message.cursor } : undefined)
+ * });
+ *
+ * window.addEventListener('pointermove', event => cursors.set({ x: event.clientX, y: event.clientY }));
+ * ```
+ */
+export declare function createWebSocketPresence<P, In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketPresenceOptions<P, NoInfer<In>, NoInfer<Out>>): WebSocketPresence<P>;
+//#endregion
 //#region src/requests.d.ts
 /** Options for {@link createWebSocketRequests}: how requests and replies look on the wire. */
 interface WebSocketRequestsOptions<Req, In, Out> {
@@ -715,6 +1057,138 @@ 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/runs.d.ts
+/**
+ * What happens to a run when its connection drops: `keep` resumes it on the next connection,
+ * for agents that keep working in the background; `cancel` aborts it and tells the server, for
+ * a chat answer nobody may be waiting for.
+ */
+type RunPolicy = 'keep' | 'cancel';
+/** Where a run is: streaming events, or ended. */
+type RunStatus = 'streaming' | 'done' | 'error' | 'aborted';
+/** A run's state, reduced from its events. A new object on every change. */
+interface AgentRun<T> {
+  readonly runId: string;
+  readonly status: RunStatus;
+  /** Reduced from the run's events with `reduce`, starting from `initial`. */
+  readonly value: T;
+  /** What `error` returned for the event that ended the run, when `status` is `'error'`. */
+  readonly error: unknown;
+}
+/** The subset of `Storage` that runs use, so `sessionStorage`, `localStorage` or your own fits. */
+type RunStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/** Options for {@link createWebSocketRuns}: the messages your server expects and sends. */
+interface WebSocketRunsOptions<Req, T, In, Out> {
+  /** Names the runs' entry in `storage`, `react-websocket-runs:<name>`. */
+  name: string;
+  /**
+   * The message that starts a run, with its `runId`. Sent again on a new connection until the
+   * run's first event arrives, so the server should start a run only once per `runId`.
+   * Annotate `request`: that's what `runs.start()` accepts.
+   */
+  start: (request: Req, runId: string) => Out;
+  /**
+   * The message that asks for a run's events after `after`, its last event received, or from
+   * the beginning when `after` is `undefined` (after a reload, or for `attach()`). Sent on every
+   * new connection while the run is streaming.
+   */
+  resume: (runId: string, after: number | undefined) => Out;
+  /** The message that stops a run, sent by `abort()` and for runs whose policy is `cancel`. */
+  cancel?: (runId: string) => Out;
+  /**
+   * Recognize a run's event: its `runId`, and its `offset`, one more than the event before it.
+   * `undefined` for any other message.
+   */
+  event: (message: In) => {
+    readonly runId: string;
+    readonly offset: number;
+  } | null | undefined;
+  /** Whether an event is the run's last. The run is `'done'` after reducing it. */
+  done?: (message: In) => boolean;
+  /** Recognize an event that ends the run with an error: return it, or `undefined`. */
+  error?: (message: In) => unknown;
+  /** A run's value before its first event. */
+  initial: T;
+  /** Fold an event into a run's value. Pure. */
+  reduce: (value: T, message: In) => T;
+  /** @default 'keep' */
+  policy?: RunPolicy;
+  /**
+   * Where to remember streaming runs, so a reload resumes them.
+   * @default sessionStorage, where it exists. `null` remembers nothing.
+   */
+  storage?: RunStorage | null;
+}
+/** Runs that stream events and survive reconnects and reloads. Create with {@link createWebSocketRuns}. */
+interface WebSocketRuns<Req, T> {
+  /** The client the runs stream on. */
+  readonly client: WebSocketClient<any, any>;
+  /**
+   * Start a run and return its `runId`. The start message is sent as soon as the socket is
+   * open, and the run is remembered until it ends. `initial` overrides the `initial` option for
+   * this run. A `runId` it already knows, streaming or ended, starts nothing: the server starts
+   * a run only once per id. `delete()` it first to use the id again.
+   */
+  start(request: Req, options?: {
+    runId?: string;
+    policy?: RunPolicy;
+    initial?: T;
+  }): string;
+  /**
+   * Follow a run started elsewhere, such as in another tab or before a reload, from its first
+   * event. Does nothing for a run it already knows.
+   */
+  attach(runId: string, options?: {
+    policy?: RunPolicy;
+    initial?: T;
+  }): void;
+  /** Stop a streaming run: send `cancel`, and make it `'aborted'`. */
+  abort(runId: string): void;
+  /** A run's state, or `undefined` for one it doesn't know. The same object until it changes. */
+  get(runId: string): AgentRun<T> | undefined;
+  /** Every run it knows, oldest first. A new array on every change. */
+  list(): readonly AgentRun<T>[];
+  /** Get notified when a run changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Forget a run, aborting it first if it's streaming. */
+  delete(runId: string): void;
+  /** Stop following runs, and release the connection. Remembered runs stay remembered. */
+  dispose(): void;
+}
+/**
+ * Stream runs, such as an AI agent's answer, that survive reconnects and page reloads.
+ *
+ * - `start(request)` sends `start(request, runId)` and follows the run's events, folding them
+ *   into its value with `reduce`.
+ * - Each event carries an `offset`. On a new connection, a streaming run sends
+ *   `resume(runId, after)` with the last offset received, so the server sends what was missed,
+ *   and duplicates are dropped.
+ * - Streaming runs are remembered in `sessionStorage`. After a reload they're followed again from
+ *   their first event, rebuilding the value, so `list()` or `useAgentRun` can show them.
+ * - A run whose policy is `cancel` is aborted when its connection drops, and `cancel` is sent
+ *   first thing on the next one.
+ *
+ * Built on `createWebSocketFeeds`, with each run a topic. While runs are streaming, it holds
+ * the client's connection.
+ *
+ * @example
+ * ```ts
+ * export const runs = createWebSocketRuns(agent, {
+ *   name: 'chat',
+ *   start: (prompt: string, runId) => ({ type: 'run', runId, prompt }),
+ *   resume: (runId, after) => ({ type: 'resume', runId, after }),
+ *   cancel: runId => ({ type: 'cancel', runId }),
+ *   event: message => (message.type === 'token' || message.type === 'done' ? message : undefined),
+ *   done: message => message.type === 'done',
+ *   initial: '',
+ *   reduce: (text, message) => text + message.text
+ * });
+ *
+ * const runId = runs.start('Summarize this thread');
+ * ```
+ */
+export declare function createWebSocketRuns<Req, T, In, const Out>(client: WebSocketClient<In, Out>, options: WebSocketRunsOptions<Req, T, NoInfer<In>, NoInfer<Out>>): WebSocketRuns<Req, T>;
+//#endregion
 //#region src/sendrate.d.ts
 /** Options for {@link createWebSocketSendRate}. */
 interface WebSocketSendRateOptions {
@@ -822,6 +1296,15 @@ interface WebSocketStateOptions<S, In> {
  *
  * @typeParam S - The state type. Don't use a function type: `setState` treats functions as updaters.
  */
+/**
+ * Messages from somewhere other than the client itself, such as the in-order messages of
+ * `createWebSocketFeeds`, for `createWebSocketState`.
+ */
+interface MessageSource<In> {
+  /** The client the messages come from. */
+  readonly client: WebSocketClient<any, any>;
+  on(type: 'message', listener: (message: In, event: MessageEvent) => void): () => void;
+}
 interface WebSocketState<S> {
   /** The client whose messages this store reduces. Hooks reading the store keep it connected. */
   readonly client: WebSocketClient<any, any>;
@@ -843,6 +1326,9 @@ interface WebSocketState<S> {
  * It starts listening immediately and keeps the state across reconnects; it doesn't open
  * the connection by itself.
  *
+ * Pass feeds from `createWebSocketFeeds` in place of the client to reduce their messages
+ * instead: numbered ones once each and in order.
+ *
  * @example
  * ```ts
  * const prices = createWebSocket<Tick>('wss://api.example.com/prices', { json: true });
@@ -856,53 +1342,142 @@ interface WebSocketState<S> {
  * const acme = useWebSocketState(priceState, state => state.ACME);
  * ```
  */
-export declare function createWebSocketState<S, In>(client: WebSocketClient<In, any>, options: WebSocketStateOptions<S, NoInfer<In>>): WebSocketState<S>;
+export declare function createWebSocketState<S, In>(source: WebSocketClient<In, any> | MessageSource<In>, 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;
+//#region src/ag-ui.d.ts
+/** A tool call on an assistant message, as in AG-UI. */
+interface AgUiToolCall {
+  readonly id: string;
+  readonly type: 'function';
+  readonly function: {
+    readonly name: string;
+    readonly arguments: string;
+  };
 }
-/** Reference-counted topic subscriptions on one client. Create with {@link createWebSocketTopics}. */
-interface WebSocketTopics {
-  /** The client the subscription messages are sent on. */
+/** A message in an AG-UI thread. */
+interface AgUiMessage {
+  readonly id: string;
+  readonly role: 'developer' | 'system' | 'assistant' | 'user' | 'tool' | 'reasoning' | 'activity';
+  readonly content?: unknown;
+  readonly toolCalls?: readonly AgUiToolCall[];
+  /** For a `tool` message, the call it answers. */
+  readonly toolCallId?: string;
+  /** For an `activity` message. */
+  readonly activityType?: string;
+  readonly [field: string]: unknown;
+}
+/** AG-UI's `RunAgentInput`: what a run starts from. */
+interface RunAgentInput {
+  readonly threadId: string;
+  readonly runId: string;
+  readonly parentRunId?: string;
+  readonly state?: unknown;
+  readonly messages: readonly AgUiMessage[];
+  readonly tools: readonly unknown[];
+  readonly context: readonly unknown[];
+  readonly forwardedProps: unknown;
+}
+/** A thread's messages and shared state, reduced from AG-UI events. */
+interface AgUiThread<S = unknown> {
+  readonly messages: readonly AgUiMessage[];
+  /** The shared state, from `STATE_SNAPSHOT` and `STATE_DELTA`. */
+  readonly state: S;
+  /**
+   * `'running'` from `RUN_STARTED`, `'finished'` after `RUN_FINISHED`, `'error'` after
+   * `RUN_ERROR`, `'aborted'` when the run was stopped from this side.
+   */
+  readonly status: 'idle' | 'running' | 'finished' | 'error' | 'aborted';
+  /** The step in progress, between `STEP_STARTED` and `STEP_FINISHED`. */
+  readonly step?: string;
+  /** From `RUN_ERROR`. */
+  readonly error?: {
+    readonly message: string;
+    readonly code?: string;
+  };
+  /** From `RUN_FINISHED`. */
+  readonly result?: unknown;
+  /**
+   * A `STATE_DELTA` couldn't be applied. `state` is the last good one, and later deltas are
+   * skipped until a `STATE_SNAPSHOT` arrives.
+   */
+  readonly stale: boolean;
+}
+/** An AG-UI agent over a WebSocket. Create with {@link createAgUiAgent}. */
+interface AgUiAgent<S> {
+  /** The client the runs stream on. */
+  readonly client: WebSocketClient<any, any>;
+  /** The runs underneath, from `createWebSocketRuns`. */
+  readonly runs: WebSocketRuns<RunAgentInput, AgUiThread<S>>;
+  /**
+   * Start a run with the thread so far plus `input.messages`, which show up in the thread right
+   * away. A run that's still streaming is aborted first. Returns the run's id.
+   */
+  run(input?: {
+    messages?: readonly AgUiMessage[];
+    tools?: readonly unknown[];
+    context?: readonly unknown[];
+    forwardedProps?: unknown;
+  }, options?: {
+    policy?: RunPolicy;
+  }): string;
+  /** Stop the run that's streaming, if any. */
+  abort(): void;
+  /** The thread as of the latest run. The same object until it changes. */
+  getSnapshot(): AgUiThread<S>;
+  /** Get notified when the thread changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Stop following runs, and release the connection. */
+  dispose(): void;
+}
+//#endregion
+//#region src/outbox.d.ts
+/** What an outbox stores for each message. */
+interface OutboxRecord<M = unknown> {
+  /** The message's idempotency key, sent with it every time. */
+  readonly id: string;
+  /** The message, as passed to `add()`. */
+  readonly message: M;
+  /** When it was added, from `Date.now()`. Entries are sent in this order. */
+  readonly createdAt: number;
+}
+/** A message waiting in the outbox. */
+interface OutboxEntry<M = unknown> extends OutboxRecord<M> {
+  /** Sent on the current connection, and waiting for the server's ack. */
+  readonly sent: boolean;
+}
+/** A persistent outbox on one client. Create with {@link createWebSocketOutbox}. */
+interface WebSocketOutbox<M> {
+  /** The client the entries 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.
+   * Resolves once the entries stored by an earlier page load are back in the outbox, and
+   * rejects if they couldn't be loaded. Nothing is sent before.
    */
-  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. */
+  readonly ready: Promise<void>;
+  /**
+   * Add a message and send it as soon as the socket is open. Resolves with its id once it's
+   * stored, and rejects if storing failed; the entry is still sent from memory then, but won't
+   * survive a reload. Without `ack`, one sent right away isn't stored, and resolves at once.
+   * @param id - The idempotency key, e.g. an order number. A new random one by default.
+   */
+  add(message: M, id?: string): Promise<string>;
+  /**
+   * Remove an entry without sending it again, e.g. when the user cancels it. Other tabs using
+   * the same `name` drop it too.
+   */
+  remove(id: string): Promise<void>;
+  /**
+   * Remove every entry at once, including ones other tabs stored, e.g. on logout. Other tabs
+   * using the same `name` drop theirs too. Resolves once they're deleted from storage.
+   */
+  clear(): Promise<void>;
+  /** The waiting entries, oldest first. A new array on every change. */
+  getSnapshot(): readonly OutboxEntry<M>[];
+  /** Get notified when the entries change. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** Stop sending and listening, and release the connection. Stored entries stay stored. */
   dispose(): void;
 }
-/**
- * Manage topic subscriptions that survive reconnects.
- *
- * - The first holder of a topic sends `subscribe(topic)`. Later holders share it.
- * - A tick after the last holder releases it, `unsubscribe(topic)` is sent, so StrictMode
- *   and route transitions don't churn subscriptions.
- * - After every reconnect, every held topic is subscribed again on the new socket, before
- *   messages queued while disconnected are sent.
- *
- * Subscriptions are only sent while the socket is open; nothing is queued for them.
- *
- * @example
- * ```ts
- * export const topics = createWebSocketTopics(live, {
- *   subscribe: topic => ({ type: 'subscribe', topic }),
- *   unsubscribe: topic => ({ type: 'unsubscribe', topic })
- * });
- *
- * // In a component:
- * useWebSocketTopic(topics, `prices:${symbol}`);
- * ```
- */
-export declare function createWebSocketTopics<const Out>(client: WebSocketClient<any, Out>, options: WebSocketTopicsOptions<NoInfer<Out>>): WebSocketTopics;
 //#endregion
 //#region src/react.d.ts
 /**
@@ -945,7 +1520,9 @@ interface UseWebSocketResult<In, Out> extends Snapshot<In> {
  * Connect to a WebSocket and re-render with its status and latest message.
  *
  * - With a URL, every component using the same URL (and `protocols`) shares one
- *   connection. Its options come from whichever component created it first.
+ *   connection. Its options come from the first of them to mount; in development, a
+ *   component passing different ones gets a console warning. A render React throws away
+ *   never decides them.
  * - With a client from `createWebSocket()`, options are the client's; only handlers
  *   and `enabled` apply here.
  * - With `null` or `undefined`, nothing connects and the status stays `idle`.
@@ -1024,6 +1601,78 @@ export declare function useWebSocketTopic(topics: WebSocketTopics | null | undef
  * ```
  */
 export declare function useWebSocketLatency(latency: WebSocketLatency): Latency;
+/**
+ * The messages waiting in an outbox from `react-websocket/outbox`, oldest first, for a "3 orders
+ * waiting to sync" banner. Re-renders when they change. `null` lists nothing. On the server the
+ * list is empty.
+ *
+ * @example
+ * ```tsx
+ * const waiting = useWebSocketOutbox(orders);
+ * if (!waiting.length) return null;
+ * return <p role="status">{waiting.length} orders waiting to sync</p>;
+ * ```
+ */
+export declare function useWebSocketOutbox<M>(outbox: WebSocketOutbox<M> | null | undefined): readonly OutboxEntry<M>[];
+/**
+ * Whether an element is on screen, from an `IntersectionObserver`, for dashboards that stream
+ * full detail only for what's visible: pick a topic with it and pass it to `useWebSocketTopic`,
+ * which switches subscriptions when it changes. `initial` until the first observation, on the
+ * server, and where `IntersectionObserver` doesn't exist.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLElement>(null);
+ * useWebSocketTopic(feeds, useInView(ref) ? `run:${id}:tokens` : `run:${id}:status`);
+ * return <article ref={ref}>…</article>;
+ * ```
+ */
+export declare function useInView(ref: RefObject<Element | null>, options?: {
+  rootMargin?: string;
+  threshold?: number;
+  initial?: boolean;
+}): boolean;
+/**
+ * The other peers' shared state from `createWebSocketPresence`, such as their cursors.
+ * Re-renders when a peer's state arrives, it leaves, or it times out. Keeps the connection open
+ * while mounted. On the server the list is empty.
+ *
+ * @example
+ * ```tsx
+ * const peers = useWebSocketPresence(cursors);
+ * return peers.map(({ peer, state }) => <Cursor key={peer} x={state.x} y={state.y} />);
+ * ```
+ */
+export declare function useWebSocketPresence<P>(presence: WebSocketPresence<P> | null | undefined): readonly PresencePeer<P>[];
+/**
+ * The thread of an AG-UI agent from `react-websocket/ag-ui`: its messages, shared state and
+ * status, re-rendering on every event.
+ *
+ * @example
+ * ```tsx
+ * const thread = useAgUiAgent(agent);
+ * return thread.messages.map(message => <Message key={message.id} message={message} />);
+ * ```
+ */
+export declare function useAgUiAgent<S>(agent: AgUiAgent<S>): AgUiThread<S>;
+/**
+ * A run from `createWebSocketRuns`, such as an agent's answer: its `value` reduced from the
+ * events so far, and its `status`. Re-renders on every event. A run it doesn't know, such as one
+ * started in another tab, is attached and followed from its first event. `undefined` while the
+ * run is unknown, for a `null` id, and on the server.
+ *
+ * @example
+ * ```tsx
+ * const run = useAgentRun(runs, runId);
+ * return (
+ *   <>
+ *     <Markdown>{run?.value ?? ''}</Markdown>
+ *     {run?.status === 'streaming' && <button onClick={() => runs.abort(runId)}>Stop</button>}
+ *   </>
+ * );
+ * ```
+ */
+export declare function useAgentRun<T>(runs: WebSocketRuns<any, T> | null | undefined, runId: string | null | undefined): AgentRun<T> | undefined;
 /**
  * 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
@@ -1103,5 +1752,5 @@ export declare function useWebSocketStream<Req, In>(rpc: WebSocketRequests<Req,
   batch?: 'frame';
 }): UseWebSocketStreamResult<Req, readonly In[]>;
 //#endregion
-export type { CloseInfo, EventMap, HeartbeatOptions, IncomingRequest, Latency, QueueOptions, ReconnectOptions, RequestHandler, RequestOptions, SendData, SendOptions, SendRate, Snapshot, StandardSchemaV1, Status, UrlSource, UseWebSocketOptions, UseWebSocketResult, UseWebSocketStreamOptions, UseWebSocketStreamResult, WebSocketClient, WebSocketHandlers, WebSocketLatency, WebSocketLatencyOptions, WebSocketOptions, WebSocketRequests, WebSocketRequestsOptions, WebSocketResponder, WebSocketResponderOptions, WebSocketSendRate, WebSocketSendRateOptions, WebSocketState, WebSocketStateOptions, WebSocketTopics, WebSocketTopicsOptions };
+export type { AgentRun, CloseInfo, EventMap, FeedPosition, HeartbeatOptions, IncomingRequest, Latency, MessageSource, MigrateOptions, PresencePeer, QueueOptions, ReconnectOptions, RequestHandler, RequestOptions, RunPolicy, RunStatus, RunStorage, SendData, SendOptions, SendRate, Snapshot, StandardSchemaV1, Status, UrlSource, UseWebSocketOptions, UseWebSocketResult, UseWebSocketStreamOptions, UseWebSocketStreamResult, WebSocketClient, WebSocketFeeds, WebSocketFeedsOptions, WebSocketHandlers, WebSocketLatency, WebSocketLatencyOptions, WebSocketOptions, WebSocketPresence, WebSocketPresenceOptions, WebSocketRequests, WebSocketRequestsOptions, WebSocketResponder, WebSocketResponderOptions, WebSocketRuns, WebSocketRunsOptions, WebSocketSendRate, WebSocketSendRateOptions, WebSocketState, WebSocketStateOptions, WebSocketTopics, WebSocketTopicsOptions };
 //# sourceMappingURL=index.d.cts.map