react-websocket 3.3.0 → 3.5.0

package/dist/index.d.cts

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

package/dist/index.d.ts

@@ -113,14 +113,42 @@ interface SendOptions {
   volatile?: boolean;
   /**
    * Keep only the newest queued message with this key. Sending again with the same key
-   * while disconnected replaces the earlier one, which moves to the back of the queue.
+   * while disconnected replaces the earlier one, which moves to the back of the queue
+   * (or of the `priority` messages, for a priority one).
    * For state where only the latest value matters, such as "my position is now (x, y)".
    */
   key?: string;
+  /**
+   * Queue this message ahead of every message queued without `priority`, after earlier
+   * priority messages. For control messages that must not wait behind a backlog, such as
+   * cancel, interrupt or a token refresh. Messages sent from `open` listeners still go first.
+   *
+   * It only matters while the socket isn't open: once a message is handed to the browser,
+   * nothing can overtake it. To keep that buffer short, send bulky streams with `maxBuffered`.
+   * @default false
+   */
+  priority?: boolean;
+  /**
+   * Drop the message instead of sending it while more than this many bytes are already
+   * waiting in the browser's send buffer (`socket.bufferedAmount`). For high-rate streams on
+   * a slow link, such as audio frames or per-tick input, where a late message is worse than
+   * none. `send()` returns `false`, and `onDrop` isn't called.
+   *
+   * Only checked while the socket is open: a message queued while disconnected is sent on
+   * open regardless. `bufferedAmount` includes what you sent earlier in the same task, so set
+   * it well above one burst of messages.
+   *
+   * @example
+   * ```ts
+   * voice.send(frame, { volatile: true, maxBuffered: 64 * 1024 });
+   * ```
+   */
+  maxBuffered?: number;
   /**
    * Called if the message is dropped from the queue without being sent: replaced by a
    * newer message with the same `key`, or evicted by `queue.limit`. Not called when the
-   * queue is cleared because the client closed or gave up.
+   * queue is cleared because the client closed or gave up, or when `send()` drops the
+   * message right away (`volatile` while not open, or `maxBuffered`) and returns `false`.
    */
   onDrop?: () => void;
 }
@@ -128,7 +156,7 @@ interface SendOptions {
 interface QueueOptions {
   /**
    * Maximum number of messages held while not connected. When full, the oldest
-   * message is dropped.
+   * message is dropped, skipping `priority` messages unless nothing else is queued.
    * @default Infinity
    */
   limit?: number;
@@ -311,12 +339,14 @@ interface WebSocketClient<In = unknown, Out = unknown> {
    * Send a message (encoded with `serialize`/`json` if configured). If the socket isn't
    * open, the message is queued and sent on open (see the `queue` option), unless
    * `options.volatile` is set.
-   * @returns `true` if it was sent immediately, `false` if it was queued or dropped.
+   * @returns `true` if it was sent immediately, `false` if it was queued or dropped
+   *   (`volatile` while not open, or `maxBuffered` while open).
    *
    * @example
    * ```ts
    * game.send({ type: 'input', dx, dy }, { volatile: true }); // never replayed after a reconnect
    * game.send({ type: 'position', x, y }, { key: 'position' }); // only the newest is queued
+   * game.send({ type: 'leave' }, { priority: true }); // ahead of everything already queued
    * ```
    */
   send(message: Out, options?: SendOptions): boolean;

package/dist/timeline.cjs

@@ -0,0 +1,162 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/timeline.ts
+const MAX_PENDING = 1e3;
+/**
+* Keep server snapshots on a timeline for multiplayer games: render what the server moves
+* slightly in the past, interpolated between snapshots, and what your inputs move right away,
+* predicted and corrected when the server confirms them.
+*
+* Read it once per frame (in `requestAnimationFrame` or React Three Fiber's `useFrame`): `at()`
+* for everyone else, `predicted()` for you. It listens from creation, starts over on reconnect,
+* and doesn't open the connection by itself.
+*
+* @example
+* ```ts
+* import { createWebSocketTimeline } from 'react-websocket/timeline';
+*
+* export const timeline = createWebSocketTimeline(game, {
+*   snapshot: m => (m.type === 'snapshot' ? { time: m.time, ack: m.ack, state: m.world } : undefined),
+*   interpolate: (from, to, t) => lerpWorld(from, to, t),
+*   latency,
+*   input: {
+*     send: (input: Move, seq) => ({ type: 'input', seq, ...input }),
+*     predict: (world, input) => move(world, me, input)
+*   }
+* });
+*
+* // Every frame:
+* draw(timeline.at(), timeline.predicted());
+* // On a key press:
+* timeline.input({ dx: 1, dy: 0 });
+* ```
+*/
+function createWebSocketTimeline(client, options) {
+	const { interpolate, latency, input: inputs } = options;
+	const delay = options.delay ?? 100;
+	const extrapolate = options.extrapolate ?? 0;
+	const keep = Math.max(2, options.buffer ?? 30);
+	const listeners = /* @__PURE__ */ new Set();
+	let buffer = [];
+	let arrival = -Infinity;
+	let rendered = -Infinity;
+	let stale = false;
+	let seq = 0;
+	let pending = [];
+	let prediction;
+	let folded = -1;
+	function notify() {
+		for (const listener of [...listeners]) listener();
+	}
+	function clear() {
+		buffer = [];
+		arrival = rendered = -Infinity;
+		stale = false;
+	}
+	function receive(snapshot) {
+		if (stale) clear();
+		const newest = buffer.at(-1);
+		if (newest && snapshot.time <= newest.snapshot.time) return;
+		buffer.push({
+			snapshot,
+			arrived: performance.now()
+		});
+		if (buffer.length > keep) buffer.shift();
+		arrival = -Infinity;
+		for (const entry of buffer) arrival = Math.max(arrival, entry.snapshot.time - entry.arrived);
+		const { ack } = snapshot;
+		if (ack != null) pending = pending.filter((entry) => entry.seq > ack);
+		folded = -1;
+		notify();
+	}
+	function renderTime() {
+		if (!buffer.length) return;
+		const measured = latency?.getSnapshot();
+		const edge = measured?.offset !== void 0 && measured.rtt !== void 0 ? latency.serverNow() - measured.rtt / 2 : performance.now() + arrival;
+		rendered = Math.max(rendered, edge - (typeof delay === "function" ? delay() : delay));
+		return rendered;
+	}
+	function at(time) {
+		const n = buffer.length;
+		if (!n) return;
+		const t = time ?? renderTime();
+		const last = buffer[n - 1].snapshot;
+		if (t >= last.time) {
+			const previous = buffer[n - 2]?.snapshot;
+			if (!previous || !interpolate || !extrapolate || t === last.time) return last.state;
+			const capped = Math.min(t, last.time + extrapolate);
+			return interpolate(previous.state, last.state, (capped - previous.time) / (last.time - previous.time));
+		}
+		let i = n - 2;
+		while (i >= 0 && buffer[i].snapshot.time > t) i--;
+		if (i < 0) return buffer[0].snapshot.state;
+		const from = buffer[i].snapshot;
+		const to = buffer[i + 1].snapshot;
+		return !interpolate || t === from.time ? from.state : interpolate(from.state, to.state, (t - from.time) / (to.time - from.time));
+	}
+	function predicted() {
+		const newest = buffer.at(-1);
+		if (!newest) return;
+		if (folded < 0) {
+			prediction = newest.snapshot.state;
+			folded = 0;
+		}
+		while (folded < pending.length) {
+			prediction = inputs.predict(prediction, pending[folded].input);
+			folded++;
+		}
+		return prediction;
+	}
+	const offs = [client.on("open", () => {
+		pending = [];
+		folded = -1;
+		stale = true;
+	}), client.on("message", (message) => {
+		const snapshot = options.snapshot(message);
+		if (snapshot != null) receive(snapshot);
+	})];
+	return {
+		client,
+		at,
+		predicted,
+		input(value) {
+			const next = seq + 1;
+			const message = inputs.send(value, next);
+			if (!client.send(message, {
+				volatile: true,
+				maxBuffered: inputs.maxBuffered
+			})) return;
+			seq = next;
+			pending.push({
+				seq,
+				input: value
+			});
+			if (pending.length > MAX_PENDING) {
+				pending.shift();
+				folded = -1;
+			}
+			return seq;
+		},
+		latest: () => buffer.at(-1)?.snapshot,
+		renderTime,
+		pending: () => pending.length,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		reset() {
+			clear();
+			pending = [];
+			folded = -1;
+			notify();
+		},
+		dispose() {
+			offs.forEach((off) => off());
+		}
+	};
+}
+//#endregion
+exports.createWebSocketTimeline = createWebSocketTimeline;
+
+//# sourceMappingURL=timeline.cjs.map

package/dist/timeline.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.cjs","names":[],"sources":["../src/timeline.ts"],"sourcesContent":["// Types only: the built entry has no imports, and its declarations point at `core`'s.\nimport type { WebSocketClient, WebSocketLatency } from './core';\n\n/** A server snapshot, as returned by the `snapshot` option. */\nexport interface TimelineSnapshot<S> {\n  /** Server time the state is for, in ms. Must increase from one snapshot to the next. */\n  readonly time: number;\n  /** The authoritative state at `time`. */\n  readonly state: S;\n  /**\n   * `seq` of the last input from this client that the server applied before taking the\n   * snapshot. Inputs up to it are confirmed and no longer predicted. Omit it to keep the\n   * previous one.\n   */\n  readonly ack?: number;\n}\n\n/** Client-side prediction for your own inputs. See {@link WebSocketTimelineOptions.input}. */\nexport interface TimelineInputOptions<S, I, Out> {\n  /**\n   * Build the message for an input, tagged with its `seq`. Annotate `input`: that's what\n   * `timeline.input()` accepts. Sent with `volatile`, so inputs are never replayed late.\n   */\n  send: (input: I, seq: number) => Out;\n  /**\n   * Apply one input to a state, exactly as the server does. Must be pure: return a new state\n   * instead of changing `state`, which is a snapshot from the server.\n   */\n  predict: (state: S, input: I) => S;\n  /**\n   * Drop an input instead of sending it while more than this many bytes are already waiting in\n   * the browser's send buffer (see `SendOptions.maxBuffered`). For input sent every tick on a\n   * slow link. A dropped input isn't predicted.\n   */\n  maxBuffered?: number;\n}\n\n/** Options for {@link createWebSocketTimeline}. */\nexport interface WebSocketTimelineOptions<S, I, In, Out> {\n  /** Recognize a snapshot. Return `undefined` (or `null`) for any other message. */\n  snapshot: (message: In) => TimelineSnapshot<S> | null | undefined;\n  /**\n   * Blend two states. `t` runs from 0 (`from`) to 1 (`to`), and above 1 only when\n   * extrapolating. Without it, `at()` steps from one snapshot to the next.\n   */\n  interpolate?: (from: S, to: S, t: number) => S;\n  /**\n   * How far behind the newest snapshot to render, in ms: enough to cover the snapshot\n   * interval plus jitter, so there are usually two snapshots to blend between. A function is\n   * read on every call, for a delay that adapts.\n   * @default 100\n   */\n  delay?: number | (() => number);\n  /**\n   * How far past the newest snapshot `at()` may extrapolate when the next one is late, in ms.\n   * Needs `interpolate`. `0` holds the newest state instead.\n   * @default 0\n   */\n  extrapolate?: number;\n  /**\n   * How many snapshots to keep (at least 2).\n   * @default 30\n   */\n  buffer?: number;\n  /**\n   * Take the server clock from `createWebSocketLatency` on the same client. Its pongs must use\n   * the same clock as snapshot `time`. Without it, or before the first pong with a time, the\n   * server clock is estimated from when snapshots arrive.\n   */\n  latency?: Pick<WebSocketLatency, 'getSnapshot' | 'serverNow'>;\n  /** Send inputs tagged with a sequence number, and predict their effect until the server confirms them. */\n  input?: TimelineInputOptions<S, I, Out>;\n}\n\n/** Server snapshots on a timeline, with your own inputs predicted on top. Create with {@link createWebSocketTimeline}. */\nexport interface WebSocketTimeline<S, I> {\n  /** The client whose snapshots this timeline keeps. */\n  readonly client: WebSocketClient<any, any>;\n  /**\n   * The state at `time` (by default `renderTime()`), interpolated between the snapshots around\n   * it. For what the server moves, such as other players. `undefined` before any snapshot.\n   */\n  at(time?: number): S | undefined;\n  /**\n   * The newest snapshot with your unconfirmed inputs replayed on top. For what your inputs\n   * move, such as your own player. Cached, so it's cheap to call every frame.\n   */\n  predicted(): S | undefined;\n  /**\n   * Send an input and predict it. Returns its `seq`, or `undefined` if it couldn't be sent\n   * (the socket isn't open, or `maxBuffered` dropped it), in which case it isn't predicted.\n   */\n  input(input: I): number | undefined;\n  /** The newest snapshot, as `snapshot` returned it. */\n  latest(): TimelineSnapshot<S> | undefined;\n  /**\n   * The server time `at()` renders by default: the newest snapshot's time, give or take, minus\n   * `delay`. It never goes backward until the timeline starts over. `undefined` before any snapshot.\n   */\n  renderTime(): number | undefined;\n  /** How many inputs were sent but not confirmed yet. */\n  pending(): number;\n  /**\n   * Called after each new snapshot and on `reset()`. Compatible with `useSyncExternalStore` for\n   * `latest` and `pending`, but not for `at`, `predicted` or `renderTime`, which change with time.\n   */\n  subscribe(listener: () => void): () => void;\n  /** Forget all snapshots and pending inputs now. `seq` keeps counting. */\n  reset(): void;\n  /** Stop listening. Only needed for timelines created dynamically. */\n  dispose(): void;\n}\n\n// Unconfirmed inputs kept at most. A server that stops confirming would otherwise make every\n// snapshot replay a growing list.\nconst MAX_PENDING = 1000;\n\n/**\n * Keep server snapshots on a timeline for multiplayer games: render what the server moves\n * slightly in the past, interpolated between snapshots, and what your inputs move right away,\n * predicted and corrected when the server confirms them.\n *\n * Read it once per frame (in `requestAnimationFrame` or React Three Fiber's `useFrame`): `at()`\n * for everyone else, `predicted()` for you. It listens from creation, starts over on reconnect,\n * and doesn't open the connection by itself.\n *\n * @example\n * ```ts\n * import { createWebSocketTimeline } from 'react-websocket/timeline';\n *\n * export const timeline = createWebSocketTimeline(game, {\n *   snapshot: m => (m.type === 'snapshot' ? { time: m.time, ack: m.ack, state: m.world } : undefined),\n *   interpolate: (from, to, t) => lerpWorld(from, to, t),\n *   latency,\n *   input: {\n *     send: (input: Move, seq) => ({ type: 'input', seq, ...input }),\n *     predict: (world, input) => move(world, me, input)\n *   }\n * });\n *\n * // Every frame:\n * draw(timeline.at(), timeline.predicted());\n * // On a key press:\n * timeline.input({ dx: 1, dy: 0 });\n * ```\n */\n// `const` + `NoInfer`: take `In` and `Out` from the client only. `S` comes from `snapshot`, and\n// `I` from how `input.send` annotates its parameter (`never` without `input`).\nexport function createWebSocketTimeline<In, const Out, S, I = never>(\n  client: WebSocketClient<In, Out>,\n  options: WebSocketTimelineOptions<S, I, NoInfer<In>, NoInfer<Out>>\n): WebSocketTimeline<S, I> {\n  const { interpolate, latency, input: inputs } = options;\n  const delay = options.delay ?? 100;\n  const extrapolate = options.extrapolate ?? 0;\n  const keep = Math.max(2, options.buffer ?? 30);\n  const listeners = new Set<() => void>();\n\n  // Oldest first, `time` strictly increasing. `arrived` is `performance.now()` on receipt.\n  let buffer: { snapshot: TimelineSnapshot<S>; arrived: number }[] = [];\n  // Server time minus `performance.now()`, from the least delayed snapshot in the buffer.\n  let arrival = -Infinity;\n  // The last render time handed out, so that it never goes backward.\n  let rendered = -Infinity;\n  // A new connection opened: its first snapshot replaces the buffer.\n  let stale = false;\n  let seq = 0;\n  let pending: { seq: number; input: I }[] = [];\n  let prediction: S | undefined;\n  // How many pending inputs `prediction` includes. `-1`: start again from the newest snapshot.\n  let folded = -1;\n\n  function notify() {\n    for (const listener of [...listeners]) listener();\n  }\n\n  function clear() {\n    buffer = [];\n    arrival = rendered = -Infinity;\n    stale = false;\n  }\n\n  function receive(snapshot: TimelineSnapshot<S>) {\n    if (stale) clear();\n    const newest = buffer.at(-1);\n    // A WebSocket keeps order, so this is a duplicate or a server clock that stepped back.\n    if (newest && snapshot.time <= newest.snapshot.time) return;\n    buffer.push({ snapshot, arrived: performance.now() });\n    if (buffer.length > keep) buffer.shift();\n    arrival = -Infinity;\n    for (const entry of buffer) arrival = Math.max(arrival, entry.snapshot.time - entry.arrived);\n    const { ack } = snapshot;\n    if (ack != null) pending = pending.filter(entry => entry.seq > ack);\n    folded = -1;\n    notify();\n  }\n\n  function renderTime() {\n    if (!buffer.length) return;\n    const measured = latency?.getSnapshot();\n    // The server time of a snapshot arriving now: half a round trip behind the server's clock.\n    const edge =\n      measured?.offset !== undefined && measured.rtt !== undefined\n        ? latency!.serverNow() - measured.rtt / 2\n        : performance.now() + arrival;\n    rendered = Math.max(rendered, edge - (typeof delay === 'function' ? delay() : delay));\n    return rendered;\n  }\n\n  function at(time?: number): S | undefined {\n    const n = buffer.length;\n    if (!n) return;\n    const t = time ?? renderTime()!;\n    const last = buffer[n - 1]!.snapshot;\n    if (t >= last.time) {\n      const previous = buffer[n - 2]?.snapshot;\n      if (!previous || !interpolate || !extrapolate || t === last.time) return last.state;\n      const capped = Math.min(t, last.time + extrapolate);\n      return interpolate(\n        previous.state,\n        last.state,\n        (capped - previous.time) / (last.time - previous.time)\n      );\n    }\n    // Reads are usually near the newest snapshot, so search from the end.\n    let i = n - 2;\n    while (i >= 0 && buffer[i]!.snapshot.time > t) i--;\n    if (i < 0) return buffer[0]!.snapshot.state;\n    const from = buffer[i]!.snapshot;\n    const to = buffer[i + 1]!.snapshot;\n    return !interpolate || t === from.time\n      ? from.state\n      : interpolate(from.state, to.state, (t - from.time) / (to.time - from.time));\n  }\n\n  function predicted(): S | undefined {\n    const newest = buffer.at(-1);\n    if (!newest) return;\n    if (folded < 0) {\n      prediction = newest.snapshot.state;\n      folded = 0;\n    }\n    // Usually zero or one new input per frame; all of them once after each snapshot.\n    while (folded < pending.length) {\n      prediction = inputs!.predict(prediction!, pending[folded]!.input);\n      folded++; // after `predict`, so one that throws is retried rather than skipped\n    }\n    return prediction;\n  }\n\n  const offs = [\n    // Inputs on the old connection will never be confirmed. Keep showing the old snapshots\n    // until the new connection sends its first one.\n    client.on('open', () => {\n      pending = [];\n      folded = -1;\n      stale = true;\n    }),\n    // A `snapshot` that throws leaves the timeline unchanged; the client re-throws it asynchronously.\n    client.on('message', message => {\n      const snapshot = options.snapshot(message);\n      if (snapshot != null) receive(snapshot);\n    })\n  ];\n\n  return {\n    client,\n    at,\n    predicted,\n    input(value) {\n      const next = seq + 1;\n      // Recorded only once it's sent, so a dropped input never shows as a move the server didn't make.\n      const message = inputs!.send(value, next);\n      if (!client.send(message, { volatile: true, maxBuffered: inputs!.maxBuffered })) return;\n      seq = next;\n      pending.push({ seq, input: value });\n      if (pending.length > MAX_PENDING) {\n        pending.shift();\n        folded = -1;\n      }\n      return seq;\n    },\n    latest: () => buffer.at(-1)?.snapshot,\n    renderTime,\n    pending: () => pending.length,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    reset() {\n      clear();\n      pending = [];\n      folded = -1;\n      notify();\n    },\n    dispose() {\n      offs.forEach(off => off());\n    }\n  };\n}\n"],"mappings":"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"}