react-websocket 3.3.0 → 3.6.0

package/dist/timeline.d.cts

@@ -0,0 +1,379 @@
+//#region src/types.d.ts
+/**
+ * Where to connect: a URL, or a function that returns one (sync or async).
+ *
+ * A function is called before **every** connection attempt, including reconnects,
+ * so it can put a fresh auth token in the URL. If it throws or rejects, that counts
+ * as a failed attempt and is retried with backoff.
+ *
+ * @example
+ * ```ts
+ * createWebSocket(async () => `wss://api.example.com/live?token=${await getToken()}`);
+ * ```
+ */
+type UrlSource = string | (() => string | Promise<string>);
+/**
+ * Connection state.
+ *
+ * - `idle`: not connected and not trying to be. Nobody is using the client yet, or everyone stopped.
+ * - `connecting`: the first attempt is in progress.
+ * - `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.
+ */
+type Status = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed';
+/** The client's state as seen by React. A new object is created on every change. */
+interface Snapshot<In> {
+  /** Connection state. */
+  readonly status: Status;
+  /** Most recent message (after `parse`/`json` and `schema`), kept across reconnects. */
+  readonly lastMessage: In | undefined;
+  /** Consecutive failed attempts since the last successful open. `0` while open. */
+  readonly attempt: number;
+}
+/** Details of a closed connection, from the browser's `CloseEvent`. */
+interface CloseInfo {
+  /** Close code: `1000` is a normal close, `1006` an abnormal one (e.g. network loss), `4000`–`4999` are yours. */
+  readonly code: number;
+  /** Close reason sent by the side that closed the connection. Often empty. */
+  readonly reason: string;
+  /** Whether the closing handshake completed. */
+  readonly wasClean: boolean;
+}
+/** Per-message options for `send()`. */
+interface SendOptions {
+  /**
+   * Drop the message instead of queueing it when the socket isn't open. For data that
+   * is stale by the time a reconnect finishes, such as player input or cursor positions.
+   * @default false
+   */
+  volatile?: boolean;
+  /**
+   * Keep only the newest queued message with this key. Sending again with the same key
+   * while disconnected replaces the earlier one, which moves to the back of the queue
+   * (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, or when `send()` drops the
+   * message right away (`volatile` while not open, or `maxBuffered`) and returns `false`.
+   */
+  onDrop?: () => void;
+}
+/**
+ * Reported via the `error` event (and `onError`) when an incoming message can't be
+ * decoded by `parse`/`json` or fails `schema` validation. The message is not delivered.
+ *
+ * @example
+ * ```ts
+ * onError(error) {
+ *   if (error instanceof MessageError) report(error.data, error.issues);
+ * }
+ * ```
+ */
+declare class MessageError extends Error {
+  /** The raw `event.data` that failed. */
+  readonly data: unknown;
+  /** Schema validation issues, when the message failed `schema`. */
+  readonly issues: ReadonlyArray<{
+    readonly message: string;
+  }> | undefined;
+  constructor(message: string, data: unknown, options?: {
+    cause?: unknown;
+    issues?: ReadonlyArray<{
+      readonly message: string;
+    }>;
+  });
+}
+/** Events emitted by a client. Subscribe with `client.on(type, listener)` or `useWebSocketEvent`. */
+interface EventMap<In> {
+  /**
+   * The socket opened (initially or after a reconnect). Listeners run before queued
+   * messages are sent, so a handshake sent from here goes out first.
+   */
+  open: (event: Event) => void;
+  /** A message arrived and passed `parse` and `schema`. */
+  message: (message: In, event: MessageEvent) => void;
+  /** A socket closed, whether it will be retried or not. */
+  close: (close: CloseInfo) => void;
+  /**
+   * A socket error `Event`, a {@link MessageError} for an undecodable or invalid message,
+   * or the `Error` thrown by the `WebSocket` constructor or a `url` function.
+   */
+  error: (error: Event | MessageError | Error) => void;
+}
+/**
+ * A WebSocket connection that reconnects, queues, decodes and can be shared.
+ * Create one with `createWebSocket()`.
+ *
+ * The connection is reference-counted: it opens when the first hook mounts (or
+ * `ready` is read) and closes one tick after the last hook unmounts. Calling
+ * `connect()` keeps it open regardless, until `close()`.
+ *
+ * @typeParam In - Type of incoming messages.
+ * @typeParam Out - Type accepted by `send()`.
+ */
+interface WebSocketClient<In = unknown, Out = unknown> {
+  /** The URL (or URL function) the client was created with. */
+  readonly url: UrlSource;
+  /**
+   * A promise that resolves once the socket has opened. Reading it starts an idle client.
+   *
+   * It stays resolved through automatic reconnects, so `use(client.ready)` shows a
+   * Suspense fallback only for the first connection, never on a network blip; use
+   * `status` to show reconnects. It rejects when the client gives up reconnecting, when
+   * `close()` is called, and during a server render. After that, `connect()` or
+   * `reconnect()` make it a new pending promise.
+   *
+   * It is safe to pass to React 19's `use()`: the same promise is returned until its state
+   * changes, and it carries `status`/`value`/`reason` so `use()` doesn't suspend when it is
+   * already settled.
+   */
+  readonly ready: Promise<void>;
+  /** The current underlying `WebSocket`, if any. An escape hatch; prefer the client's methods. */
+  readonly socket: WebSocket | null;
+  /** Subscribe to snapshot changes. Compatible with `useSyncExternalStore`. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void;
+  /** The current {@link Snapshot}. Returns the same object until something changes. */
+  getSnapshot(): Snapshot<In>;
+  /**
+   * Listen to an event. Returns an unsubscribe function. Listener errors are re-thrown
+   * asynchronously, so one failing listener doesn't break the others.
+   */
+  on<K extends keyof EventMap<In>>(type: K, listener: EventMap<In>[K]): () => void;
+  /**
+   * Send a message (encoded with `serialize`/`json` if configured). If the socket isn't
+   * open, the message is queued and sent on open (see the `queue` option), unless
+   * `options.volatile` is set.
+   * @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;
+  /**
+   * Start connecting, and keep the connection open even when no hook is using the
+   * client, until `close()` is called. Does nothing if already connecting or open.
+   */
+  connect(): void;
+  /**
+   * Close the connection and stop reconnecting. The status becomes `closed` and the
+   * send queue is cleared. Mounted hooks stay mounted; call `connect()` or `reconnect()`
+   * to start again.
+   * @param code - Close code. @default 1000
+   */
+  close(code?: number, reason?: string): void;
+  /**
+   * Drop the current socket (if any) and connect again immediately, resetting the
+   * backoff. Also restarts a `closed` client.
+   */
+  reconnect(): void;
+  /**
+   * Hold the connection open until the returned function is called. This is what the
+   * hooks use; call it yourself to integrate with non-React code.
+   * @returns A release function (safe to call more than once).
+   */
+  acquire(): () => void;
+}
+//#endregion
+//#region src/latency.d.ts
+/** Latest latency measurements. A new object is created on every change. */
+interface Latency {
+  /** Round-trip time in ms: the median of recent pings. `undefined` until the first pong. */
+  readonly rtt: number | undefined;
+  /**
+   * Estimated server clock minus local clock, in ms. Add it to `Date.now()` for server time.
+   * `undefined` until a pong carries `time`.
+   */
+  readonly offset: number | undefined;
+}
+/** Round-trip time and server clock offset for one client. Create with {@link createWebSocketLatency}. */
+interface WebSocketLatency {
+  /** The client being measured. Hooks reading the latency keep it connected. */
+  readonly client: WebSocketClient<any, any>;
+  /** The current {@link Latency}. Returns the same object until it changes. */
+  getSnapshot(): Latency;
+  /** Called whenever a measurement changes. Compatible with `useSyncExternalStore`. */
+  subscribe(listener: () => void): () => void;
+  /** The estimated server time: `Date.now() + offset`, or `Date.now()` before any estimate. */
+  serverNow(): number;
+  /** Ping now instead of waiting for the next interval. Does nothing unless the socket is open. */
+  ping(): void;
+  /** Stop pinging and listening. Only needed for instances created dynamically. */
+  dispose(): void;
+}
+//#endregion
+//#region src/timeline.d.ts
+/** A server snapshot, as returned by the `snapshot` option. */
+export interface TimelineSnapshot<S> {
+  /** Server time the state is for, in ms. Must increase from one snapshot to the next. */
+  readonly time: number;
+  /** The authoritative state at `time`. */
+  readonly state: S;
+  /**
+   * `seq` of the last input from this client that the server applied before taking the
+   * snapshot. Inputs up to it are confirmed and no longer predicted. Omit it to keep the
+   * previous one.
+   */
+  readonly ack?: number;
+}
+/** Client-side prediction for your own inputs. See {@link WebSocketTimelineOptions.input}. */
+export interface TimelineInputOptions<S, I, Out> {
+  /**
+   * Build the message for an input, tagged with its `seq`. Annotate `input`: that's what
+   * `timeline.input()` accepts. Sent with `volatile`, so inputs are never replayed late.
+   */
+  send: (input: I, seq: number) => Out;
+  /**
+   * Apply one input to a state, exactly as the server does. Must be pure: return a new state
+   * instead of changing `state`, which is a snapshot from the server.
+   */
+  predict: (state: S, input: I) => S;
+  /**
+   * Drop an input instead of sending it while more than this many bytes are already waiting in
+   * the browser's send buffer (see `SendOptions.maxBuffered`). For input sent every tick on a
+   * slow link. A dropped input isn't predicted.
+   */
+  maxBuffered?: number;
+}
+/** Options for {@link createWebSocketTimeline}. */
+export interface WebSocketTimelineOptions<S, I, In, Out> {
+  /** Recognize a snapshot. Return `undefined` (or `null`) for any other message. */
+  snapshot: (message: In) => TimelineSnapshot<S> | null | undefined;
+  /**
+   * Blend two states. `t` runs from 0 (`from`) to 1 (`to`), and above 1 only when
+   * extrapolating. Without it, `at()` steps from one snapshot to the next.
+   */
+  interpolate?: (from: S, to: S, t: number) => S;
+  /**
+   * How far behind the newest snapshot to render, in ms: enough to cover the snapshot
+   * interval plus jitter, so there are usually two snapshots to blend between. A function is
+   * read on every call, for a delay that adapts.
+   * @default 100
+   */
+  delay?: number | (() => number);
+  /**
+   * How far past the newest snapshot `at()` may extrapolate when the next one is late, in ms.
+   * Needs `interpolate`. `0` holds the newest state instead.
+   * @default 0
+   */
+  extrapolate?: number;
+  /**
+   * How many snapshots to keep (at least 2).
+   * @default 30
+   */
+  buffer?: number;
+  /**
+   * Take the server clock from `createWebSocketLatency` on the same client. Its pongs must use
+   * the same clock as snapshot `time`. Without it, or before the first pong with a time, the
+   * server clock is estimated from when snapshots arrive.
+   */
+  latency?: Pick<WebSocketLatency, 'getSnapshot' | 'serverNow'>;
+  /** Send inputs tagged with a sequence number, and predict their effect until the server confirms them. */
+  input?: TimelineInputOptions<S, I, Out>;
+}
+/** Server snapshots on a timeline, with your own inputs predicted on top. Create with {@link createWebSocketTimeline}. */
+export interface WebSocketTimeline<S, I> {
+  /** The client whose snapshots this timeline keeps. */
+  readonly client: WebSocketClient<any, any>;
+  /**
+   * The state at `time` (by default `renderTime()`), interpolated between the snapshots around
+   * it. For what the server moves, such as other players. `undefined` before any snapshot.
+   */
+  at(time?: number): S | undefined;
+  /**
+   * The newest snapshot with your unconfirmed inputs replayed on top. For what your inputs
+   * move, such as your own player. Cached, so it's cheap to call every frame.
+   */
+  predicted(): S | undefined;
+  /**
+   * Send an input and predict it. Returns its `seq`, or `undefined` if it couldn't be sent
+   * (the socket isn't open, or `maxBuffered` dropped it), in which case it isn't predicted.
+   */
+  input(input: I): number | undefined;
+  /** The newest snapshot, as `snapshot` returned it. */
+  latest(): TimelineSnapshot<S> | undefined;
+  /**
+   * The server time `at()` renders by default: the newest snapshot's time, give or take, minus
+   * `delay`. It never goes backward until the timeline starts over. `undefined` before any snapshot.
+   */
+  renderTime(): number | undefined;
+  /** How many inputs were sent but not confirmed yet. */
+  pending(): number;
+  /**
+   * Called after each new snapshot and on `reset()`. Compatible with `useSyncExternalStore` for
+   * `latest` and `pending`, but not for `at`, `predicted` or `renderTime`, which change with time.
+   */
+  subscribe(listener: () => void): () => void;
+  /** Forget all snapshots and pending inputs now. `seq` keeps counting. */
+  reset(): void;
+  /** Stop listening. Only needed for timelines created dynamically. */
+  dispose(): void;
+}
+/**
+ * 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 });
+ * ```
+ */
+export declare function createWebSocketTimeline<In, const Out, S, I = never>(client: WebSocketClient<In, Out>, options: WebSocketTimelineOptions<S, I, NoInfer<In>, NoInfer<Out>>): WebSocketTimeline<S, I>;
+//#endregion
+//# sourceMappingURL=timeline.d.cts.map

package/dist/timeline.d.ts

@@ -0,0 +1,140 @@
+import { WebSocketClient, WebSocketLatency } from "./core.js";
+//#region src/timeline.d.ts
+/** A server snapshot, as returned by the `snapshot` option. */
+export interface TimelineSnapshot<S> {
+  /** Server time the state is for, in ms. Must increase from one snapshot to the next. */
+  readonly time: number;
+  /** The authoritative state at `time`. */
+  readonly state: S;
+  /**
+   * `seq` of the last input from this client that the server applied before taking the
+   * snapshot. Inputs up to it are confirmed and no longer predicted. Omit it to keep the
+   * previous one.
+   */
+  readonly ack?: number;
+}
+/** Client-side prediction for your own inputs. See {@link WebSocketTimelineOptions.input}. */
+export interface TimelineInputOptions<S, I, Out> {
+  /**
+   * Build the message for an input, tagged with its `seq`. Annotate `input`: that's what
+   * `timeline.input()` accepts. Sent with `volatile`, so inputs are never replayed late.
+   */
+  send: (input: I, seq: number) => Out;
+  /**
+   * Apply one input to a state, exactly as the server does. Must be pure: return a new state
+   * instead of changing `state`, which is a snapshot from the server.
+   */
+  predict: (state: S, input: I) => S;
+  /**
+   * Drop an input instead of sending it while more than this many bytes are already waiting in
+   * the browser's send buffer (see `SendOptions.maxBuffered`). For input sent every tick on a
+   * slow link. A dropped input isn't predicted.
+   */
+  maxBuffered?: number;
+}
+/** Options for {@link createWebSocketTimeline}. */
+export interface WebSocketTimelineOptions<S, I, In, Out> {
+  /** Recognize a snapshot. Return `undefined` (or `null`) for any other message. */
+  snapshot: (message: In) => TimelineSnapshot<S> | null | undefined;
+  /**
+   * Blend two states. `t` runs from 0 (`from`) to 1 (`to`), and above 1 only when
+   * extrapolating. Without it, `at()` steps from one snapshot to the next.
+   */
+  interpolate?: (from: S, to: S, t: number) => S;
+  /**
+   * How far behind the newest snapshot to render, in ms: enough to cover the snapshot
+   * interval plus jitter, so there are usually two snapshots to blend between. A function is
+   * read on every call, for a delay that adapts.
+   * @default 100
+   */
+  delay?: number | (() => number);
+  /**
+   * How far past the newest snapshot `at()` may extrapolate when the next one is late, in ms.
+   * Needs `interpolate`. `0` holds the newest state instead.
+   * @default 0
+   */
+  extrapolate?: number;
+  /**
+   * How many snapshots to keep (at least 2).
+   * @default 30
+   */
+  buffer?: number;
+  /**
+   * Take the server clock from `createWebSocketLatency` on the same client. Its pongs must use
+   * the same clock as snapshot `time`. Without it, or before the first pong with a time, the
+   * server clock is estimated from when snapshots arrive.
+   */
+  latency?: Pick<WebSocketLatency, 'getSnapshot' | 'serverNow'>;
+  /** Send inputs tagged with a sequence number, and predict their effect until the server confirms them. */
+  input?: TimelineInputOptions<S, I, Out>;
+}
+/** Server snapshots on a timeline, with your own inputs predicted on top. Create with {@link createWebSocketTimeline}. */
+export interface WebSocketTimeline<S, I> {
+  /** The client whose snapshots this timeline keeps. */
+  readonly client: WebSocketClient<any, any>;
+  /**
+   * The state at `time` (by default `renderTime()`), interpolated between the snapshots around
+   * it. For what the server moves, such as other players. `undefined` before any snapshot.
+   */
+  at(time?: number): S | undefined;
+  /**
+   * The newest snapshot with your unconfirmed inputs replayed on top. For what your inputs
+   * move, such as your own player. Cached, so it's cheap to call every frame.
+   */
+  predicted(): S | undefined;
+  /**
+   * Send an input and predict it. Returns its `seq`, or `undefined` if it couldn't be sent
+   * (the socket isn't open, or `maxBuffered` dropped it), in which case it isn't predicted.
+   */
+  input(input: I): number | undefined;
+  /** The newest snapshot, as `snapshot` returned it. */
+  latest(): TimelineSnapshot<S> | undefined;
+  /**
+   * The server time `at()` renders by default: the newest snapshot's time, give or take, minus
+   * `delay`. It never goes backward until the timeline starts over. `undefined` before any snapshot.
+   */
+  renderTime(): number | undefined;
+  /** How many inputs were sent but not confirmed yet. */
+  pending(): number;
+  /**
+   * Called after each new snapshot and on `reset()`. Compatible with `useSyncExternalStore` for
+   * `latest` and `pending`, but not for `at`, `predicted` or `renderTime`, which change with time.
+   */
+  subscribe(listener: () => void): () => void;
+  /** Forget all snapshots and pending inputs now. `seq` keeps counting. */
+  reset(): void;
+  /** Stop listening. Only needed for timelines created dynamically. */
+  dispose(): void;
+}
+/**
+ * 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 });
+ * ```
+ */
+export declare function createWebSocketTimeline<In, const Out, S, I = never>(client: WebSocketClient<In, Out>, options: WebSocketTimelineOptions<S, I, NoInfer<In>, NoInfer<Out>>): WebSocketTimeline<S, I>;
+//#endregion
+//# sourceMappingURL=timeline.d.ts.map

package/dist/timeline.js

@@ -0,0 +1,161 @@
+//#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
+export { createWebSocketTimeline };
+
+//# sourceMappingURL=timeline.js.map