react-websocket 3.6.0 → 4.18.0

package/dist/index.d.ts

@@ -1,5 +1,93 @@
 
+import { RunPolicy, WebSocketClient, WebSocketRuns } from "./core.js";
+import { RefObject } from "react";
 export * from "./core.js";
+//#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;
+  };
+}
+/** 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/types.d.ts
 /**
  * Where to connect: a URL, or a function that returns one (sync or async).
@@ -22,7 +110,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. */
@@ -31,7 +120,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`. */
@@ -53,6 +145,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
@@ -70,21 +170,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 {
@@ -100,6 +246,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;
 }
@@ -144,11 +294,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;
 }
@@ -157,9 +315,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
@@ -233,8 +399,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
    */
@@ -307,7 +473,7 @@ interface EventMap<In> {
  * @typeParam In - Type of incoming messages.
  * @typeParam Out - Type accepted by `send()`.
  */
-interface WebSocketClient<In = unknown, Out = unknown> {
+interface WebSocketClient$1<In = unknown, Out = unknown> {
   /** The URL (or URL function) the client was created with. */
   readonly url: UrlSource;
   /**
@@ -358,7 +524,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;
@@ -367,6 +536,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.
@@ -389,7 +580,7 @@ interface Latency {
 /** 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>;
+  readonly client: WebSocketClient$1<any, any>;
   /** The current {@link Latency}. Returns the same object until it changes. */
   getSnapshot(): Latency;
   /** Called whenever a measurement changes. Compatible with `useSyncExternalStore`. */
@@ -402,6 +593,83 @@ interface WebSocketLatency {
   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>;
+  /**
+   * 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.
+   */
+  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;
+}
+//#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;
+}
+/** Shared per-peer state that expires. Create with {@link createWebSocketPresence}. */
+interface WebSocketPresence<P> {
+  /** The client the state is shared on. */
+  readonly client: WebSocketClient$1<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;
+}
+//#endregion
 //#region src/requests.d.ts
 /** Per-call options for {@link WebSocketRequests.request} and {@link WebSocketRequests.stream}. */
 interface RequestOptions extends SendOptions {
@@ -416,7 +684,7 @@ interface RequestOptions extends SendOptions {
 /** Request/response over one client. Create with {@link createWebSocketRequests}. */
 interface WebSocketRequests<Req, In> {
   /** The client requests are sent on. */
-  readonly client: WebSocketClient<any, any>;
+  readonly client: WebSocketClient$1<any, any>;
   /**
    * Send a request and resolve with its reply. Holds the connection until it settles.
    *
@@ -486,7 +754,7 @@ type RequestHandler<P = unknown, R = unknown> = (params: P, request: IncomingReq
 /** 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>;
+  readonly client: WebSocketClient$1<any, any>;
   /**
    * Answer requests for `method` until the returned function is called.
    *
@@ -513,16 +781,65 @@ interface WebSocketResponder<P = unknown, R = unknown> {
   dispose(): void;
 }
 //#endregion
-//#region src/state.d.ts
+//#region src/runs.d.ts
 /**
- * State derived from a client's messages. Read it with `useWebSocketState(store, selector)`,
- * or with `getState`/`subscribe` outside React.
- *
- * @typeParam S - The state type. Don't use a function type: `setState` treats functions as updaters.
+ * 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$1 = '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;
+}
+/** Runs that stream events and survive reconnects and reloads. Create with {@link createWebSocketRuns}. */
+interface WebSocketRuns$1<Req, T> {
+  /** The client the runs stream on. */
+  readonly client: WebSocketClient$1<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$1;
+    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$1;
+    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;
+}
+//#endregion
+//#region src/state.d.ts
 interface WebSocketState<S> {
   /** The client whose messages this store reduces. Hooks reading the store keep it connected. */
-  readonly client: WebSocketClient<any, any>;
+  readonly client: WebSocketClient$1<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. */
@@ -541,7 +858,7 @@ interface WebSocketState<S> {
 /** 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>;
+  readonly client: WebSocketClient$1<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.
@@ -588,13 +905,15 @@ interface UseWebSocketResult<In, Out> extends Snapshot<In> {
   /** 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;
+  client: WebSocketClient$1<In, Out> | null;
 }
 /**
  * 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`.
@@ -614,7 +933,7 @@ interface UseWebSocketResult<In, Out> extends Snapshot<In> {
  * ```
  */
 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>;
+export declare function useWebSocket<In, Out>(client: WebSocketClient$1<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.
@@ -624,7 +943,7 @@ export declare function useWebSocket<In, Out>(client: WebSocketClient<In, Out> |
  * useWebSocketEvent(chat, 'message', message => setMessages(list => [...list, message]));
  * ```
  */
-export 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$1<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.
@@ -634,7 +953,7 @@ export declare function useWebSocketEvent<In, K extends keyof EventMap<In>>(clie
  * const status = useWebSocketStatus(chat); // 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed'
  * ```
  */
-export declare function useWebSocketStatus(client: WebSocketClient<any, any> | null | undefined): Status;
+export declare function useWebSocketStatus(client: WebSocketClient$1<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
@@ -673,6 +992,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$1<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