@genex-ai/multiplayer 0.17.1 → 0.17.8

package/dist/chunk-YWQ3ALYY.js

@@ -0,0 +1,69 @@
+// src/authority/fast-udp-socket.ts
+var IPV6_FAMILY = 6;
+var lookupTurns = /* @__PURE__ */ new Map();
+var UDP_SCHEME = "udp:";
+var PORT_MAX = 65535;
+var CONNECT_QUEUE_MAX = 32;
+var BARE_PATHS = ["", "/"];
+var onlyHostAndPort = (u) => u.username === "" && u.password === "" && BARE_PATHS.includes(u.pathname) && u.search === "" && u.hash === "";
+function udpEndpoint(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  const port = Number(parsed.port);
+  const portOk = Number.isInteger(port) && port >= 1 && port <= PORT_MAX;
+  if (parsed.protocol !== UDP_SCHEME || !portOk || parsed.hostname === "" || !onlyHostAndPort(parsed)) return null;
+  return { host: parsed.hostname.replace(/^\[(.*)\]$/, "$1"), port };
+}
+var udpFastOpener = ({ createSocket, lookup, isIP }) => (url, receive) => {
+  const to = udpEndpoint(url);
+  if (to === null) return null;
+  let socket = null;
+  let connected = false;
+  let closed = false;
+  let waiting = [];
+  const attach = (address, family) => {
+    if (closed) return;
+    const s = createSocket(family === IPV6_FAMILY ? "udp6" : "udp4");
+    socket = s;
+    s.on("message", (msg) => receive(new Uint8Array(msg.buffer, msg.byteOffset, msg.byteLength)));
+    s.on("error", () => {
+    });
+    s.connect(to.port, address, () => {
+      connected = true;
+      if (!closed) for (const bytes of waiting) s.send(bytes);
+      waiting = [];
+    });
+  };
+  const literal = isIP(to.host);
+  if (literal !== 0) attach(to.host, literal);
+  else {
+    lookup(to.host, { all: true, verbatim: true }, (err, found) => {
+      if (err !== null || found.length === 0) return;
+      const turn = (lookupTurns.get(to.host) ?? 0) % found.length;
+      lookupTurns.set(to.host, turn + 1);
+      attach(found[turn].address, found[turn].family);
+    });
+  }
+  const fast = {
+    send(bytes) {
+      if (closed) return;
+      if (connected) socket?.send(bytes);
+      else waiting = [...waiting, bytes].slice(-CONNECT_QUEUE_MAX);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      socket?.close();
+    }
+  };
+  return fast;
+};
+
+export {
+  udpEndpoint,
+  udpFastOpener
+};

package/dist/fast-client--A88q0kk.d.ts

@@ -0,0 +1,546 @@
+import { I as InputData } from './module-CSpXrzFc.js';
+
+/** The datagram format's version, the first byte of every datagram. */
+declare const FAST_VERSION = 1;
+/** No datagram is longer: the IPv6 minimum MTU (1280) less IP, UDP and QUIC headers. */
+declare const FAST_MAX_DATAGRAM_BYTES = 1200;
+/** The binding key's length: 8 random bytes per socket, sent on the reliable channel at join. */
+declare const FAST_KEY_BYTES = 8;
+/** The redundant window as time: the longest delay episode measured on `real-mac-wifi` (70–170 ms). */
+declare const INPUT_REDUNDANCY_MS = 170;
+/** The window's least inputs: two datagrams lost in a row are recovered at any tick rate. */
+declare const INPUT_REDUNDANCY_MIN = 3;
+/** The window's most inputs, and the most a datagram may carry: 32 full slots and
+ *  {@link FAST_MAX_ACTIONS} actions still fit {@link FAST_MAX_DATAGRAM_BYTES}. */
+declare const INPUT_REDUNDANCY_MAX = 32;
+/** Presses past the window awaiting the server's ack that one datagram carries (the oldest). */
+declare const FAST_MAX_ACTIONS = 8;
+/** The longest gap the server fills with the last input held; a longer one is skipped. */
+declare const FAST_GAP_FILL_MS = 250;
+/** A datagram whose newest seq is more than this far (as ticks) past the last accepted is dropped. */
+declare const FAST_SEQ_AHEAD_MS = 5000;
+/** Snapshots each side holds as bases: 533 ms at 60 Hz, over a 409 ms p99 round trip plus an episode. */
+declare const FAST_SNAPSHOT_HISTORY = 32;
+/** The most fragments one snapshot may have (about 37 KB); a larger body goes as a partial snapshot (the host cuts it, §17.12). */
+declare const FAST_MAX_FRAGMENTS = 32;
+/** Incomplete snapshots a client gathers at once; the oldest gives way. */
+declare const FAST_REASSEMBLY_SLOTS = 4;
+/** One record's most bytes. */
+declare const FAST_MAX_RECORD_BYTES = 1024;
+/** A client with no snapshot this long after its first datagram falls back to the WebSocket. */
+declare const FAST_HANDSHAKE_MS = 1000;
+/** A client with no snapshot for this long falls back to the WebSocket. */
+declare const FAST_STALL_FALLBACK_MS = 2000;
+/** A seat with nothing to send sends an empty uplink this often while snapshots reach it (§17.12
+ *  *Keepalive*): under {@link FAST_SNAPSHOT_HISTORY} snapshots at 120 Hz, so its deltas stay deltas, and far
+ *  under the shortest NAT timer measured, 10 s (Richter et al., IMC 2016: 74% of NATs expire idle UDP state
+ *  in 1 min or less, range 10 to 200 s; RFC 9308 §3.2: assume 30 s). */
+declare const FAST_KEEPALIVE_MS = 250;
+/** Likewise before its first snapshot: a lost first datagram or challenge costs no more than this. */
+declare const FAST_KEEPALIVE_BIND_MS = 50;
+/** A snapshot changing this many records is acknowledged as it lands by a seat with nothing else to send:
+ *  its next delta shrinks by far more than the 57 bytes. */
+declare const FAST_ACK_EAGER_RECORDS = 32;
+/** No eager ack within this long of another uplink: a seat sending inputs every frame sends none. */
+declare const FAST_ACK_EAGER_GAP_MS = 20;
+/** A snapshot id at least this far past the client's newest is a return-path challenge (§17.12 *Return
+ *  path*): the client echoes it at once, whatever the keepalive's clock says. */
+declare const FAST_CHALLENGE_JUMP = 65536;
+/** No frame for this long: the stall deadline's clock did not run, as the seat could not have read a
+ *  snapshot or sent an uplink (a background tab, a suspended app, a long hitch). */
+declare const FAST_FRAME_GAP_MS = 250;
+/** The binding's `rev` from a host that takes empty uplinks and challenges addresses (§17.12 *Keepalive*)
+ *  and offers a fresh binding to a seat that asks (*Return to the channel*). */
+declare const FAST_BIND_REV = 2;
+/** Snapshots a seat must apply on a fresh binding before its inputs and motion move to it: enough to trust
+ *  the path both ways, little enough to swap within a tenth of a second. */
+declare const FAST_RETURN_PROOF = 3;
+/** A retry's delay at attempt 0, before jitter: a dropped-out Wi-Fi is usually back. */
+declare const FAST_RETRY_BASE_MS = 1000;
+/** Its most, before jitter: a blocked network costs a few datagrams a minute, forever. */
+declare const FAST_RETRY_MAX_MS = 60000;
+/** A seat that held the channel this long starts its next backoff from attempt 0; one that lost it sooner
+ *  goes on climbing, so a flapping path does not swap back and forth. */
+declare const FAST_RETURN_STABLE_MS = 30000;
+/** The delay before retry number `attempt` (from 0), jittered by `unit` in [0, 1): doubling from
+ *  {@link FAST_RETRY_BASE_MS} to {@link FAST_RETRY_MAX_MS}, half of it random ("equal jitter"), so seats
+ *  behind one failed link do not come back as one. */
+declare function fastRetryDelayMs(attempt: number, unit: number): number;
+/** The reliable messages of the fast channel (§17.12): the server's binding at join and the client's
+ *  fallback. Reserved names (`__`), so no game event can be mistaken for one. */
+declare const FastMessage: {
+    /** Server → client: `{ sid, key, url }`, the seat's binding. */
+    readonly Bind: "__fast";
+    /** Client → server: `{ last }`, the last seq the client sent by datagram; its inputs go by
+     *  `room.input()` from now on. */
+    readonly Off: "__fast:off";
+    /** Client → server: `{}`, a seat off the channel asks for a fresh binding (§17.12 *Return to the channel*). */
+    readonly Again: "__fast:again";
+    /** Client → server: `{ last }`, the last seq it sent by WebSocket; its inputs go by datagram from now on. */
+    readonly On: "__fast:on";
+};
+type FastMessage = (typeof FastMessage)[keyof typeof FastMessage];
+/** Where a browser reaches the seat's channel (§17.12 *WebTransport*): a relay's WebTransport session
+ *  `url` (`https://host:port/w/<worker>`) and the SHA-256 hashes (64 lowercase hex digits each) of the
+ *  certificates it may serve, for `serverCertificateHashes`. The relay forwards the seat's datagrams,
+ *  byte for byte, to the endpoint `url` names; the binding (`sid`, `key`) is the same. */
+interface FastWebTransport {
+    url: string;
+    hashes: string[];
+}
+/** The `__fast` message's payload. `wt`, sent when the room's worker has a WebTransport relay, is read
+ *  only by a browser; every other client ignores it. */
+interface FastBindMessage {
+    sid: number;
+    key: string;
+    url: string;
+    wt?: FastWebTransport;
+    /** The host's revision of the channel ({@link FAST_BIND_REV}); absent from a host older than it, to which
+     *  a client sends no empty uplink and asks for no fresh binding. */
+    rev?: number;
+    /** A fresh binding for a seat on the WebSocket (§17.12 *Return to the channel*): the WebSocket carries
+     *  everything until the seat's `__fast:on`. */
+    probe?: boolean;
+}
+/** The `__fast:off` message's payload. */
+interface FastOffMessage {
+    last: number;
+}
+/** The `__fast:on` message's payload. */
+interface FastOnMessage {
+    last: number;
+}
+/** The datagram kinds, the second byte. */
+declare const FastKind: {
+    readonly Uplink: 1;
+    readonly Snapshot: 2;
+};
+type FastKind = (typeof FastKind)[keyof typeof FastKind];
+/** Why a datagram or a value was refused. */
+declare const FastFault: {
+    readonly Oversized: "oversized";
+    readonly Truncated: "truncated";
+    readonly Trailing: "trailing";
+    readonly Version: "version";
+    readonly Kind: "kind";
+    readonly Session: "session";
+    readonly Key: "key";
+    readonly Count: "count";
+    readonly Fresh: "fresh";
+    readonly Actions: "actions";
+    readonly Flags: "flags";
+    readonly Order: "order";
+    readonly Field: "field";
+    readonly Ahead: "ahead";
+    readonly Fragment: "fragment";
+    readonly Mismatch: "mismatch";
+    readonly Duplicate: "duplicate";
+    readonly Keyframe: "keyframe";
+    readonly Body: "body";
+    readonly Base: "base";
+    readonly Stale: "stale";
+};
+type FastFault = (typeof FastFault)[keyof typeof FastFault];
+/** How the server came by an accepted input. */
+declare const AcceptKind: {
+    /** First sent in the datagram that brought it. */
+    readonly Fresh: "fresh";
+    /** Sent first in an earlier datagram that was lost; carried again by redundancy or as an action. */
+    readonly Recovered: "recovered";
+    /** No datagram the server got carried it: the last input held stands in for it. */
+    readonly Fill: "fill";
+};
+type AcceptKind = (typeof AcceptKind)[keyof typeof AcceptKind];
+type FastResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    fault: FastFault;
+};
+/** One input on the wire: its client sequence, its `tick@1` field, its render time and its payload. */
+interface FastInput {
+    seq: number;
+    tick: number;
+    /** The render time its sender drew the world at when it sent it (§17.5): the room clock, whole ms,
+     *  as its WebSocket input frame's stamp would carry it; 0: not stamped (no synced clock). */
+    render: number;
+    input: InputData;
+}
+/** An uplink datagram's content. `window` is contiguous, oldest first; `actions` ascend below it. */
+interface Uplink {
+    sid: number;
+    key: string;
+    ackSnap: number;
+    fresh: number;
+    actions: FastInput[];
+    window: FastInput[];
+}
+/** A seat's fast-channel binding, from the reliable `fast` message. */
+interface FastBinding {
+    sid: number;
+    key: string;
+}
+/** The redundant window at `tickHz`: {@link INPUT_REDUNDANCY_MS} of inputs, within its bounds. */
+declare function inputRedundancyTicks(tickHz: number): number;
+/** The longest uplink a seat at `tickHz` sends: the header, {@link FAST_MAX_ACTIONS} actions and a full
+ *  window of slots, each at its largest (a socket that cannot carry it cannot carry the channel). */
+declare function uplinkMaxBytes(tickHz: number): number;
+/** The longest gap filled at `tickHz` ({@link FAST_GAP_FILL_MS} of ticks). */
+declare const gapFillMax: (tickHz: number) => number;
+/** The farthest a datagram's newest seq may be past the last accepted at `tickHz`. */
+declare const seqAheadMax: (tickHz: number) => number;
+/** Lowercase hex of `bytes`. */
+declare function toHex(bytes: Uint8Array): string;
+/** The bytes of hex text `hex` (an even count of hex digits; anything else reads as no bytes). */
+declare function fromHex(hex: string): Uint8Array;
+/** An input whose buttons gain a bit over `previous`'s. */
+declare const isPress: (previous: InputData | null, input: InputData) => boolean;
+/** Encodes uplink `u` (§17.12 *Uplink datagram*); refuses (`field`) what the wire cannot carry. */
+declare function encodeUplink(u: Uplink): FastResult<Uint8Array>;
+/** Decodes an uplink datagram for the seat bound by `binding`: checked whole, the session and key
+ *  first; any fault drops it. Payloads are as sent (the server sanitizes as it accepts). */
+declare function decodeUplink(bytes: Uint8Array, binding: FastBinding): FastResult<Uplink>;
+/** The render time a fast input carries (§17.12 *Render-time stamp*), the stamp its WebSocket input
+ *  frame would carry: `round(serverNow) − round(renderDelay + rtt/2)` whole ms, the delay clamped to
+ *  [0, 65535], 0 when that is not above 0 or the clock has not synced (`serverNow` null). */
+declare function renderStamp(serverNow: number | null, renderDelay: number, rtt: number): number;
+/** What {@link uplinkFor} needs beside the inputs. */
+interface UplinkOptions {
+    sid: number;
+    key: string;
+    /** The newest snapshot the client applied. */
+    ackSnap: number;
+    /** The server's last accepted input seq, from the newest applied snapshot's `inputAck`. */
+    inputAck: number;
+    /** How many of the newest inputs this datagram sends first. */
+    fresh: number;
+    tickHz: number;
+}
+/** The client's next uplink (§17.12 *Redundancy and one-shot inputs*): `sent` is every input it still
+ *  holds, ascending and contiguous, back past `inputAck`; the window is the newest
+ *  {@link inputRedundancyTicks}, and the oldest {@link FAST_MAX_ACTIONS} presses before it that the
+ *  server has not acked ride as actions. */
+declare function uplinkFor(sent: readonly FastInput[], o: UplinkOptions): Uplink;
+/** A seat's receive state: the last accepted seq (from `seqBase` at bind), the last accepted input
+ *  (null before the first) and the newest snapshot the seat acknowledged. */
+interface SeatRx {
+    last: number;
+    input: InputData | null;
+    ackSnap: number;
+}
+/** One input the server accepted, sanitized, in seq order, with the render time lag compensation
+ *  judges it at (0: unstamped; a filled input takes the one of the input after its gap). */
+interface AcceptedInput {
+    seq: number;
+    tick: number;
+    render: number;
+    input: InputData;
+    kind: AcceptKind;
+}
+interface AcceptOptions {
+    tickHz: number;
+    /** The newest snapshot id the server sent this seat (an `ackSnap` past it is ignored). */
+    snapSent: number;
+}
+interface AcceptResult {
+    seat: SeatRx;
+    accepted: AcceptedInput[];
+    /** Seqs consumed without a step: a gap longer than {@link gapFillMax}. */
+    skipped: number;
+    /** Set when the whole datagram was dropped; `seat` is then the very one given. */
+    fault?: FastFault;
+}
+/** The server's take of decoded uplink `u` for seat `seat` (§17.12 *Server dedup*): every held input
+ *  and slot ascending through `accept(seq)` (a seq at or below the last accepted is dropped), a gap
+ *  filled with the last input held or, past {@link gapFillMax}, skipped; `ackSnap` forward only. A
+ *  datagram whose newest seq is past {@link seqAheadMax} is dropped whole. Nothing new: the very same
+ *  seat. */
+declare function acceptUplink(seat: SeatRx, u: Uplink, o: AcceptOptions): AcceptResult;
+/** A snapshot's motion records, ascending by key; each record's bytes are the record codec's. */
+type Records = readonly {
+    key: number;
+    bytes: Uint8Array;
+}[];
+/** A snapshot body: the keys removed since the base, then the records new or changed. */
+interface SnapshotBody {
+    removed: number[];
+    records: Records;
+}
+/** The snapshot header the server writes. `base` 0 is a keyframe. */
+interface SnapshotHead {
+    sid: number;
+    snap: number;
+    base: number;
+    tick: number;
+    inputAck: number;
+    /** The room clock (ms since room start, §16.1 `sNow`, truncated to a uint32) when the server wrote
+     *  the snapshot: the value a WebSocket patch's TIMED prefix carries, so a fast seat's clock samples
+     *  exactly what a WebSocket seat's does (the tick's nominal instant is up to a step earlier). */
+    sent: number;
+}
+/** The body that turns `base` into `next` (null `base`: a keyframe, every record). */
+declare function diffSnapshot(base: Records | null, next: Records): SnapshotBody;
+/** The base the server deltas against: the seat's `ackSnap` while it still holds that snapshot
+ *  (`held`, its last {@link FAST_SNAPSHOT_HISTORY} sent ids), else 0 (a keyframe). */
+declare const deltaBase: (held: readonly number[], ackSnap: number) => number;
+/** The fragments of snapshot `head` with body `body` (§17.12 *Downlink snapshot*): `oversized` past
+ *  {@link FAST_MAX_FRAGMENTS}, `field` for a value the wire cannot carry. */
+declare function encodeSnapshot(head: SnapshotHead, body: SnapshotBody): FastResult<Uint8Array[]>;
+/** One decoded snapshot fragment. */
+interface Fragment {
+    snap: number;
+    base: number;
+    tick: number;
+    inputAck: number;
+    sent: number;
+    keyframe: boolean;
+    frag: number;
+    frags: number;
+    chunk: Uint8Array;
+}
+/** Decodes a snapshot fragment for seat `sid`; any fault drops it. */
+declare function decodeFragment(bytes: Uint8Array, sid: number): FastResult<Fragment>;
+/** Parses a reassembled body to the byte (keys ascending and unique, lengths in bounds, nothing left). */
+declare function parseBody(bytes: Uint8Array): FastResult<SnapshotBody>;
+/** `base`'s records less `body.removed`, with `body.records` written over them. */
+declare function applyBody(base: Records, body: SnapshotBody): Records;
+/** An applied snapshot the client holds as a base. */
+interface HeldSnapshot {
+    snap: number;
+    tick: number;
+    inputAck: number;
+    sent: number;
+    records: Records;
+}
+/** A snapshot being gathered: its first fragment's header and the chunks so far. */
+interface PartialSnapshot {
+    snap: number;
+    base: number;
+    tick: number;
+    inputAck: number;
+    sent: number;
+    keyframe: boolean;
+    frags: number;
+    chunks: readonly (Uint8Array | null)[];
+}
+/** The client's receive state: sets being gathered (ascending), applied snapshots held as bases
+ *  (oldest first, at most {@link FAST_SNAPSHOT_HISTORY}) and the newest applied id (0: none). */
+interface ClientRx {
+    partials: readonly PartialSnapshot[];
+    history: readonly HeldSnapshot[];
+    newest: number;
+}
+declare const emptyClientRx: () => ClientRx;
+interface ReceiveResult {
+    rx: ClientRx;
+    /** The snapshot this fragment completed and applied, else null. */
+    applied: number | null;
+    fault?: FastFault;
+}
+/** The client's take of one snapshot datagram (§17.12 *Applying a snapshot*). A fault drops the
+ *  fragment; while nothing was gathered for it, the answer is the very `rx` given. */
+declare function receiveFragment(rx: ClientRx, bytes: Uint8Array, sid: number): ReceiveResult;
+
+/** What a record describes, the first byte. */
+declare const MotionRecordKind: {
+    readonly Entity: 1;
+    readonly Seat: 2;
+};
+type MotionRecordKind = (typeof MotionRecordKind)[keyof typeof MotionRecordKind];
+/** An entity's motion fields (AuthorityEntity, §17.3, §17.7, §17.10), each at its default when absent. */
+interface EntityMotion {
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    yaw: number;
+    pitch: number;
+    duck: number;
+    spin: number;
+    fuel: number;
+    epoch: number;
+    mstate: number;
+    qx: number;
+    qy: number;
+    qz: number;
+    qw: number;
+    lvx: number;
+    lvy: number;
+    lvz: number;
+    avx: number;
+    avy: number;
+    avz: number;
+    sleep: boolean;
+    rest: number;
+}
+/** A seat's input echo and pacing counters (AuthorityPlayer `in*`, §17.11), each 0 when absent. */
+interface SeatEcho {
+    inMoveX: number;
+    inMoveY: number;
+    inMoveZ: number;
+    inYaw: number;
+    inPitch: number;
+    inButtons: number;
+    inRep: number;
+    inStarve: number;
+    inBuf: number;
+    /** The receiving seat's own record only: its last input the server consumed (stepped or skipped)
+     *  as of this snapshot, the ack its reconciler replays from (0 in every other seat's record). */
+    inAck: number;
+}
+/** One motion record: an entity's or a seat's, by its id. */
+type MotionRecord = {
+    kind: typeof MotionRecordKind.Entity;
+    id: string;
+    motion: EntityMotion;
+} | {
+    kind: typeof MotionRecordKind.Seat;
+    id: string;
+    motion: SeatEcho;
+};
+/** The longest id a record carries, in characters (AuthorityLimits MAX_ENTITY_ID_CHARS and seat ids). */
+declare const RECORD_ID_MAX_CHARS = 64;
+/** Every entity motion field at its default. */
+declare const blankEntityMotion: () => EntityMotion;
+/** Every seat motion field at its default. */
+declare const blankSeatEcho: () => SeatEcho;
+/** The schema's quantize on a symmetric clamped range of half-width `half`: the uint16 code. */
+declare function quantizeCode(half: number, value: number): number;
+/** The schema's dequantize: the float a decoder reads for `code`. */
+declare const dequantizeCode: (half: number, code: number) => number;
+/** The record's bytes (§17.12 *Motion records*); refuses (`field`) what it cannot carry. */
+declare function encodeRecord(r: MotionRecord): FastResult<Uint8Array>;
+/** Reads one record to the byte; any fault drops it (the whole snapshot it came in). Every field
+ *  left out reads as its default. */
+declare function decodeRecord(bytes: Uint8Array): FastResult<MotionRecord>;
+
+/** Round trips a socket that opens asynchronously may take to open, where that is longer than
+ *  {@link FAST_HANDSHAKE_MS}: WebTransport over QUIC and HTTP/3 took three in Safari 26 (Chromium's two
+ *  are within it), so a long route's seat is not sent back for its session's own handshake. */
+declare const FAST_OPEN_ROUND_TRIPS = 4;
+/** A datagram socket to the room's fast endpoint. `send` never throws; a lost datagram is the
+ *  channel's normal case. */
+interface FastDatagramSocket {
+    send(bytes: Uint8Array): void;
+    close(): void;
+    /** True once the socket knows it can never carry the channel (a session that opens asynchronously
+     *  and was refused): the seat falls back at once instead of waiting out a deadline. */
+    failed?(): boolean;
+    /** The longest datagram the socket can send now, where it knows one (WebTransport's
+     *  `maxDatagramSize`): below the seat's largest uplink ({@link uplinkMaxBytes}), the seat falls back
+     *  at once. */
+    maxDatagramBytes?(): number | undefined;
+    /** True while a socket that opens asynchronously is still opening (WebTransport: round trips before a
+     *  first datagram can leave). The handshake then runs twice: to the socket opening, {@link FAST_HANDSHAKE_MS}
+     *  or {@link FAST_OPEN_ROUND_TRIPS} of the seat's round trips, whichever is longer; and from then to the
+     *  first snapshot, {@link FAST_HANDSHAKE_MS}. */
+    opening?(): boolean;
+}
+/** Opens a socket to a `__fast` `url`, handing each datagram that arrives to `receive`; null when this
+ *  client cannot reach that kind of url (the seat then falls back at once). `bind` is the whole
+ *  binding (the client always passes it), for an opener that reaches the channel another way
+ *  (`bind.wt`, WebTransport). */
+type FastSocketOpener = ((url: string, receive: (bytes: Uint8Array) => void, bind?: FastBindMessage) => FastDatagramSocket | null) & {
+    /** Why this opener answers null for `bind` (default {@link FastFallbackReason.Unreachable}). */
+    whyNull?: (bind: FastBindMessage) => FastFallbackReason;
+};
+/** Why a fast seat went back to the WebSocket. */
+declare const FastFallbackReason: {
+    /** The `__fast` binding was malformed, this client cannot open its url, or its socket failed. */
+    readonly Unreachable: "unreachable";
+    /** No snapshot within {@link FAST_HANDSHAKE_MS} of the first datagram. */
+    readonly Handshake: "handshake";
+    /** No snapshot for {@link FAST_STALL_FALLBACK_MS} after the last one. */
+    readonly Stall: "stall";
+    /** The server asked for it (`__fast:off` from the server). */
+    readonly Server: "server";
+    /** A browser with no `WebTransport` (or not a secure context): the seat never asked for the channel. */
+    readonly NoWebTransport: "no-webtransport";
+    /** The binding carries no `wt` this browser can open: the room's server runs no relay. */
+    readonly NoRelay: "no-relay";
+    /** The seat asked and no binding came within {@link FAST_HANDSHAKE_MS} of its first frame: the room's
+     *  server has no channel, or is too old to offer it. The seat was on the WebSocket all along, and a
+     *  binding that comes after all still opens. */
+    readonly NotOffered: "not-offered";
+};
+type FastFallbackReason = (typeof FastFallbackReason)[keyof typeof FastFallbackReason];
+/** One applied snapshot as the session uses it: its header and the motion records that differ from the
+ *  previous applied snapshot's (a record that does not decode is left out: its id stays as it was). */
+interface FastSnapshot {
+    snap: number;
+    tick: number;
+    /** The last input seq the server accepted (the header's `inputAck`). */
+    inputAck: number;
+    /** The room clock the server wrote it at (the header's `sent`, a WebSocket patch's TIMED `sNow`). */
+    sent: number;
+    changed: readonly MotionRecord[];
+}
+/** What one received datagram did. */
+interface FastReceipt {
+    applied: FastSnapshot | null;
+    fault?: FastFault;
+}
+interface FastClientOptions {
+    bind: FastBindMessage;
+    tickHz: number;
+    open: FastSocketOpener;
+    /** The clock the deadlines run on (ms). */
+    now: () => number;
+    /** The seat's round trip as measured so far (ms; 0 or absent: not yet known). */
+    roundTripMs?: () => number;
+    /** Each applied snapshot, after the receive state took it. */
+    onSnapshot?: (s: FastSnapshot) => void;
+}
+/** One seat's fast channel on one socket. */
+interface FastClient {
+    readonly bind: FastBindMessage;
+    /** The snapshot receive state (reassembly, held bases, newest applied). */
+    readonly rx: ClientRx;
+    /** The newest input seq queued (0: none). */
+    readonly lastQueued: number;
+    /** True once closed: nothing is sent or received again. */
+    readonly closed: boolean;
+    /** True while the socket is still opening. */
+    opening(): boolean;
+    /** An input sent this frame: seqs ascend by one from the first queued. */
+    queue(input: FastInput): void;
+    /** One datagram carrying the inputs queued since the last flush and the redundant window (one more for
+     *  each further window's worth of new inputs); nothing when none was queued. */
+    flush(): void;
+    /** An empty uplink when one is due (§17.12 *Keepalive*), from a host that takes them: the seat binds with
+     *  no input, its snapshots stay acknowledged and its NAT mapping stays open. */
+    keepalive(): void;
+    /** The input of seq `seq` while it is still held. */
+    inputAt(seq: number): FastInput | undefined;
+    /** When the input of seq `seq` was first sent (by `now`), for each of the newest {@link seqAheadMax}
+     *  inputs: the server consumes an input well after it received it (its buffer, the next keyframe), and
+     *  the round trip is timed from the send of the input a snapshot acks as consumed. */
+    sentAt(seq: number): number | undefined;
+    /** The latest decoded record of `id` of `kind` (from the newest applied snapshot), else undefined. */
+    motionOf(kind: MotionRecordKind, id: string): MotionRecord | undefined;
+    /** Every record of the newest applied snapshot. */
+    records(): MotionRecord[];
+    /** A frame begins: time since the last frame past {@link FAST_FRAME_GAP_MS} is taken off both deadlines'
+     *  clocks (§17.12 *Keepalive*), so a seat whose frames stopped does not read its own stop as a dead path. */
+    framed(): void;
+    /** Whether a deadline has passed (§17.12 *Fallback*), by the injected clock. */
+    due(): FastFallbackReason | null;
+    /** One datagram from the socket. A fault, a stale or duplicate fragment or a datagram for another
+     *  seat changes nothing. */
+    receive(bytes: Uint8Array): FastReceipt;
+    close(): void;
+}
+/** A `__fast` payload this client can use: sid a uint32, key {@link FAST_KEY_BYTES} bytes of lowercase
+ *  hex, url a string. */
+declare function isFastBind(m: unknown): m is FastBindMessage;
+/** The inputs `uplinkFor` still needs once the server accepted through `inputAck`: the window's newest
+ *  inputs, every input after the ack, and the one before the oldest of those (a press is a bit its
+ *  previous input lacked). At most {@link seqAheadMax} of them. */
+declare function heldInputs(sent: readonly FastInput[], inputAck: number, tickHz: number): FastInput[];
+/** Opens a seat's fast channel on `o.bind`; null when the opener cannot reach its url. */
+declare function openFastClient(o: FastClientOptions): FastClient | null;
+
+export { MotionRecordKind as $, AcceptKind as A, FAST_SNAPSHOT_HISTORY as B, type ClientRx as C, FAST_STALL_FALLBACK_MS as D, type EntityMotion as E, type FastSocketOpener as F, FAST_VERSION as G, type FastBinding as H, type FastClient as I, type FastClientOptions as J, type FastDatagramSocket as K, FastFault as L, type FastInput as M, FastKind as N, FastMessage as O, type FastOffMessage as P, type FastOnMessage as Q, type FastReceipt as R, type FastResult as S, type FastSnapshot as T, type FastWebTransport as U, type Fragment as V, type HeldSnapshot as W, INPUT_REDUNDANCY_MAX as X, INPUT_REDUNDANCY_MIN as Y, INPUT_REDUNDANCY_MS as Z, type MotionRecord as _, FastFallbackReason as a, type PartialSnapshot as a0, RECORD_ID_MAX_CHARS as a1, type ReceiveResult as a2, type Records as a3, type SeatEcho as a4, type SeatRx as a5, type SnapshotBody as a6, type SnapshotHead as a7, type Uplink as a8, type UplinkOptions as a9, seqAheadMax as aA, toHex as aB, uplinkFor as aC, uplinkMaxBytes as aD, acceptUplink as aa, applyBody as ab, blankEntityMotion as ac, blankSeatEcho as ad, decodeFragment as ae, decodeRecord as af, decodeUplink as ag, deltaBase as ah, dequantizeCode as ai, diffSnapshot as aj, emptyClientRx as ak, encodeRecord as al, encodeSnapshot as am, encodeUplink as an, fastRetryDelayMs as ao, fromHex as ap, gapFillMax as aq, heldInputs as ar, inputRedundancyTicks as as, isFastBind as at, isPress as au, openFastClient as av, parseBody as aw, quantizeCode as ax, receiveFragment as ay, renderStamp as az, type FastBindMessage as b, type AcceptOptions as c, type AcceptResult as d, type AcceptedInput as e, FAST_ACK_EAGER_GAP_MS as f, FAST_ACK_EAGER_RECORDS as g, FAST_BIND_REV as h, FAST_CHALLENGE_JUMP as i, FAST_FRAME_GAP_MS as j, FAST_GAP_FILL_MS as k, FAST_HANDSHAKE_MS as l, FAST_KEEPALIVE_BIND_MS as m, FAST_KEEPALIVE_MS as n, FAST_KEY_BYTES as o, FAST_MAX_ACTIONS as p, FAST_MAX_DATAGRAM_BYTES as q, FAST_MAX_FRAGMENTS as r, FAST_MAX_RECORD_BYTES as s, FAST_OPEN_ROUND_TRIPS as t, FAST_REASSEMBLY_SLOTS as u, FAST_RETRY_BASE_MS as v, FAST_RETRY_MAX_MS as w, FAST_RETURN_PROOF as x, FAST_RETURN_STABLE_MS as y, FAST_SEQ_AHEAD_MS as z };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { ObjectControlOperation as ObjectControlOperation$1, ObjectControlReason as ObjectControlReason$1 } from './protocol.js';
+import { A as AuthSource } from './join-CGoInvUM.js';
+export { C as ColyseusAuth } from './join-CGoInvUM.js';
 export { ObjectState, PlayerState, RoomState } from './schema.js';
 import '@colyseus/schema';
 
@@ -39,10 +41,6 @@ type VoiceJoinOptions = {
     speakingThreshold?: number;
 };
 
-type ColyseusAuth = {
-    embedToken: string;
-};
-type AuthSource = ColyseusAuth | (() => ColyseusAuth | undefined);
 type ConnectOptions = {
     /** Regional relay urls (pass `getColyseusUrls()`) — the SDK probes each and connects to the
      *  lowest-latency one (a probe that times out falls back, it never fails the join); a single entry
@@ -562,4 +560,4 @@ declare function createPrivate<TState extends Record<string, unknown> = never>(o
  */
 declare function joinPrivate<TState extends Record<string, unknown> = never>(code: string, opts: MatchmakeOptions): Promise<Matchmaking<TState>>;
 
-export { type AuthSource, type ChatApi, type ChatMessage, type ColyseusAuth, type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PredictSmoothing, type PrivateMatch, type Session, type SessionOptions, type VoiceApi, type VoiceJoinOptions, type VoiceParticipant, connect, createPrivate, joinPrivate, matchmake };
+export { AuthSource, type ChatApi, type ChatMessage, type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PredictSmoothing, type PrivateMatch, type Session, type SessionOptions, type VoiceApi, type VoiceJoinOptions, type VoiceParticipant, connect, createPrivate, joinPrivate, matchmake };

package/dist/index.js

@@ -3,8 +3,9 @@ import {
   createPrivate,
   joinPrivate,
   matchmake
-} from "./chunk-3ZUPU3GT.js";
-import "./chunk-C52XFIB6.js";
+} from "./chunk-QY3QQNDJ.js";
+import "./chunk-FPWP22Y7.js";
+import "./chunk-CSQEEANB.js";
 export {
   connect,
   createPrivate,

package/dist/join-CGoInvUM.d.ts

@@ -0,0 +1,6 @@
+type ColyseusAuth = {
+    embedToken: string;
+};
+type AuthSource = ColyseusAuth | (() => ColyseusAuth | undefined);
+
+export type { AuthSource as A, ColyseusAuth as C };