@genex-ai/multiplayer 0.16.2 → 0.17.1

package/dist/chunk-C52XFIB6.js

@@ -0,0 +1,312 @@
+// src/protocol.ts
+var PROTOCOL_VERSION = 3;
+var MIN_PROTOCOL_VERSION = 3;
+var RoomType = {
+  /** The plain relay room: joinOrCreate, fullest-first placement. */
+  PLAY: "play",
+  /** The matchmaking search pool. No game session — it only hands out seat reservations. */
+  QUEUE: "queue",
+  /** A capped match arena: seat reservation (matchmade), create (private lobby) or joinById (invite). */
+  MATCH: "match"
+};
+var JoinOption = {
+  /** The game's slug. Must equal the embed token's `slug` claim. */
+  GAME_ID: "gameId",
+  /** A fresh `embed:play` JWT. Required — there is no anonymous join. */
+  EMBED_TOKEN: "embedToken",
+  /** Display-name fallback when the token carries none. */
+  NAME: "name",
+  /** {@link PROTOCOL_VERSION}. Required. */
+  PROTOCOL: "protocol"
+};
+var SERVER_OWNED_JOIN_OPTIONS = ["clients", "preset", "winCondition", "config", "matchmade"];
+var JoinError = {
+  /** A server-owned option was sent. */
+  BAD_OPTION: 400,
+  /** No token, an invalid/expired token, or a revoked session. */
+  AUTH_REQUIRED: 401,
+  /** Token for another game ('wrong game'), or the room's guest cap is full. */
+  FORBIDDEN: 403,
+  /** `protocol` missing or outside [MIN_PROTOCOL_VERSION, PROTOCOL_VERSION]. Update the client. */
+  PROTOCOL_UNSUPPORTED: 426
+};
+var STAGING_ROOM_PREFIX = "preview--";
+var roomKeyFor = (slug, channel) => channel === "staging" ? `${STAGING_ROOM_PREFIX}${slug}` : slug;
+var slugOfRoomKey = (key) => key.startsWith(STAGING_ROOM_PREFIX) ? key.slice(STAGING_ROOM_PREFIX.length) : key;
+var ClientMessage = {
+  STATE: "state",
+  STATE_SNAP: "__state:snap",
+  SHARED: "shared",
+  CLAIM: "claim",
+  RELEASE: "release",
+  DESTROY: "destroy",
+  OBJECT: "obj",
+  OBJECT_SNAP: "__object:snap",
+  INPUT: "__input",
+  ROOM_OPEN: "__room:open",
+  CHAT: "__chat",
+  CHAT_HISTORY_REQUEST: "__chat:history:request",
+  VOICE_ICE_REQUEST: "__voice:ice:request",
+  VOICE_JOIN: "__voice:join",
+  VOICE_LEAVE: "__voice:leave",
+  VOICE_SIGNAL: "__voice:signal",
+  // match rooms only — self-reports, accepted only from an active seat
+  MATCH_ELIMINATED: "match:eliminated",
+  MATCH_SCORE: "match:score",
+  MATCH_FINISH: "match:finish",
+  // optional typed pose (§6.6) — appended in protocol 3
+  POSE: "__pose",
+  POSE_SNAP: "__pose:snap"
+};
+var ServerMessage = {
+  OBJECT_RESULT: "__object:result",
+  INPUT: "__input",
+  ROOM_OPEN: "__room:open",
+  CHAT: "__chat",
+  CHAT_HISTORY: "__chat:history",
+  VOICE_ICE: "__voice:ice",
+  VOICE_SIGNAL: "__voice:signal",
+  VOICE_REJECTED: "__voice:rejected",
+  RATE_DROP: "rate:drop",
+  SERVER_RESTART: "server:restart",
+  // match rooms only
+  MATCH_START: "match:start",
+  MATCH_ENDED: "match:ended",
+  MATCH_REQUEUE: "match:requeue",
+  // queue room only
+  QUEUE: "queue",
+  SEAT: "seat"
+};
+var RESERVED_EVENT_PREFIXES = ["__", "match:", "server:", "rate:"];
+var RESERVED_EVENT_TYPES = ["state", "shared", "claim", "release", "destroy", "obj", "queue", "seat"];
+function isReservedEventType(type) {
+  return RESERVED_EVENT_TYPES.includes(type) || RESERVED_EVENT_PREFIXES.some((prefix) => type.startsWith(prefix));
+}
+var RESERVED_SHARED_PREFIX = "__";
+var SEND_TIME_KEY = "__t";
+var RATE_LANES = {
+  state: { rate: 30, burst: 60, softZone: 0 },
+  control: { rate: 40, burst: 80, softZone: 0 },
+  input: { rate: 60, burst: 120, softZone: 0 },
+  bulk: { rate: 120, burst: 240, softZone: 60 },
+  chat: { rate: 2, burst: 5, softZone: 0 },
+  voice: { rate: 25, burst: 60, softZone: 0 },
+  /** `__pose` / `__pose:snap` (§6.6). Its own reserved lane, outside the global bucket like
+   *  `state`: a posed player publishes pose AND (low-rate) `data`, and neither may starve the other. */
+  pose: { rate: 30, burst: 60, softZone: 0 }
+};
+var GLOBAL_RATE = { rate: 180, burst: 360 };
+var MAX_MESSAGES_PER_SECOND = 1200;
+var MESSAGE_LANE = {
+  [ClientMessage.STATE]: "state",
+  [ClientMessage.STATE_SNAP]: "state",
+  [ClientMessage.SHARED]: "bulk",
+  [ClientMessage.CLAIM]: "control",
+  [ClientMessage.RELEASE]: "control",
+  [ClientMessage.DESTROY]: "control",
+  [ClientMessage.OBJECT]: "bulk",
+  [ClientMessage.OBJECT_SNAP]: "bulk",
+  [ClientMessage.INPUT]: "input",
+  [ClientMessage.ROOM_OPEN]: "control",
+  [ClientMessage.CHAT]: "chat",
+  [ClientMessage.CHAT_HISTORY_REQUEST]: "control",
+  [ClientMessage.VOICE_ICE_REQUEST]: "voice",
+  [ClientMessage.VOICE_JOIN]: "voice",
+  [ClientMessage.VOICE_LEAVE]: "voice",
+  [ClientMessage.VOICE_SIGNAL]: "voice",
+  [ClientMessage.MATCH_ELIMINATED]: "bulk",
+  [ClientMessage.MATCH_SCORE]: "bulk",
+  [ClientMessage.MATCH_FINISH]: "bulk",
+  [ClientMessage.POSE]: "pose",
+  [ClientMessage.POSE_SNAP]: "pose"
+};
+var CloseCode = {
+  // reconnectable (the seat is held for the grace window)
+  GOING_AWAY: 1001,
+  NO_STATUS: 1005,
+  ABNORMAL: 1006,
+  /** Colyseus: the server is going down, come back. The one ≥4000 code that is not terminal. */
+  MAY_TRY_RECONNECT: 4010,
+  // terminal
+  NORMAL: 1e3,
+  /** A deliberate leave (Colyseus CONSENTED) — and the code a match room boots a requeued player
+   *  with when it ignored `match:requeue` (Genex MATCH_BOOT). Same number, same meaning: seat gone. */
+  CONSENTED: 4e3,
+  MATCH_BOOT: 4e3,
+  SERVER_SHUTDOWN: 4001,
+  /** Colyseus: protocol error, or the socket exceeded MAX_MESSAGES_PER_SECOND. */
+  WITH_ERROR: 4002,
+  /** Colyseus SDK: every reconnection attempt failed (the grace expired). */
+  FAILED_TO_RECONNECT: 4003,
+  /** The player's session was revoked (signed out from the dashboard). Do not rejoin with it. */
+  REVOKED: 4401,
+  /** A newer session of the same player took the seat (second tab, or the page reloaded). */
+  SUPERSEDED: 4409
+};
+var Limits = {
+  ROOM_MAX_CLIENTS: 64,
+  MAX_NAME_CHARS: 64,
+  MAX_AVATAR_URL_CHARS: 512,
+  MAX_UID_CHARS: 64,
+  /** `state` / `__state:snap` payload (the JSON text). */
+  MAX_STATE_BYTES: 16 * 1024,
+  MAX_SHARED_KEY_CHARS: 256,
+  MAX_SHARED_VALUE_BYTES: 64 * 1024,
+  /** Distinct game keys a room's `shared` map may ever hold (keys are never deleted). */
+  MAX_SHARED_KEYS: 256,
+  MAX_OBJECT_ID_CHARS: 128,
+  /** An object's `d` as stored (JSON text). */
+  MAX_OBJECT_STATE_BYTES: 64 * 1024,
+  /** Live objects per room (an id counts from its first accepted claim until `destroy`). */
+  MAX_OBJECTS: 128,
+  MAX_REQUEST_ID_CHARS: 96,
+  /** Game events and `__input`: the payload's JSON encoding. */
+  MAX_EVENT_BYTES: 16 * 1024,
+  MAX_EVENT_TYPE_CHARS: 128,
+  /** JSON payload shape bounds: nesting depth and total node count. */
+  MAX_JSON_DEPTH: 32,
+  MAX_JSON_NODES: 4096,
+  /** Code points per chat line after normalization. */
+  MAX_CHAT_CHARS: 500,
+  CHAT_HISTORY_MAX: 50,
+  CHAT_HISTORY_MAX_BYTES: 8 * 1024,
+  MAX_VOICE_PARTICIPANTS: 6,
+  MAX_VOICE_SIGNAL_BYTES: 8 * 1024,
+  /** `match:score` delta is clamped to ±this. */
+  MAX_SCORE_DELTA: 1e3,
+  /** Results kept per session for request-id replay, and how long. */
+  CONTROL_RESULTS_PER_SESSION: 128,
+  CONTROL_RESULT_TTL_MS: 6e4,
+  /** Open preset `teams` knob range (0 = no teams). */
+  MAX_TEAMS: 8,
+  /** `__pose` `anim` string (§6.6). */
+  MAX_ANIM_CHARS: 64,
+  /** Every `__pose` number must be finite with |v| ≤ this (float32 holds it without overflowing to
+   *  Infinity; past ~1e7 a float32 position is coarser than a metre anyway). */
+  MAX_POSE_ABS: 1e9
+};
+var RelayTiming = {
+  /** State patch cadence: every accumulated change goes out on this tick. */
+  PATCH_INTERVAL_MS: 1e3 / 30,
+  /** Seat grace after an abnormal drop (1006 etc.). */
+  RECONNECT_GRACE_S: 30,
+  /** Seat grace after a 1001 close (reload/navigate) — long enough to rejoin and supersede. */
+  GOING_AWAY_GRACE_S: 5,
+  /** A dropped host keeps host for this long before the relay fails over. */
+  HOST_FAILOVER_GRACE_MS: 1500,
+  /** A freshly changed owner cannot be displaced by an ordinary claim for this long. */
+  MIN_OWNERSHIP_HOLD_MS: 300,
+  /** After `server:restart`, clients are dropped this much later. */
+  SHUTDOWN_DRAIN_MS: 3e3,
+  /** A requeued match player that has not left is booted (MATCH_BOOT) after this. */
+  REQUEUE_GRACE_MS: 5e3,
+  /** A seat reservation must be consumed within this. */
+  SEAT_RESERVATION_S: 15,
+  /** The queue room's matchmaking pass. */
+  QUEUE_TICK_MS: 1e3,
+  /** Embed tokens are re-checked for revocation on this cadence (REVOKED close on hit). */
+  REVOCATION_SWEEP_MS: 3e4
+};
+var ClientReconnection = {
+  enabled: true,
+  minUptime: 0,
+  delay: 125,
+  minDelay: 100,
+  maxDelay: 4e3,
+  maxRetries: 9,
+  maxEnqueuedMessages: 0,
+  /** After the SDK reports reconnected, wait at most this for the first state decode (§8). */
+  firstStateTimeoutMs: 2e3
+};
+var POSE_KEYS = ["x", "y", "z", "yaw", "vx", "vy", "vz", "anim"];
+var Interpolation = {
+  /** Render delay target = RATIO × median publish interval of that sender… */
+  RATIO: 1.5,
+  /** …but at least JITTER_SAFETY × (p90 − min) of that sender's (arrival − sendTime)… */
+  JITTER_SAFETY: 1.25,
+  /** …clamped to [MIN_MS, MAX_MS], and DEFAULT_MS before anything is measured. */
+  MIN_MS: 90,
+  MAX_MS: 300,
+  DEFAULT_MS: 100,
+  /** Per-sample fraction the delay moves toward its target (no pops). */
+  EASE: 0.1,
+  /**
+   * The min-filtered clock-offset window, kept PER SENDER: it holds at least the last CLOCK_WINDOW
+   * samples AND at least CLOCK_WINDOW_MS of them, whichever reaches further back, so a sender that
+   * owns many streams never shrinks the time the window covers. The jitter term reads each stream's
+   * own last CLOCK_WINDOW samples.
+   */
+  CLOCK_WINDOW: 80,
+  CLOCK_WINDOW_MS: 5e3,
+  /** Hard cap on one sender's window (memory bound for a sender publishing very many streams). */
+  CLOCK_WINDOW_MAX: 4096,
+  /** Publish-gap history for the median; gaps outside (MIN_GAP_MS, MAX_GAP_MS) are ignored. */
+  INTERVAL_WINDOW: 30,
+  MIN_GAP_MS: 5,
+  MAX_GAP_MS: 2e3,
+  /** Snapshot history kept per stream (never fewer than 2). */
+  HISTORY_MS: 1500,
+  /** Past the newest snapshot: dead-reckon position at most this far, rotation this far. */
+  MAX_EXTRAP_MS: 250,
+  ROT_EXTRAP_MS: 150,
+  /** Output smoothing time constants (alpha = 1 − e^(−dt/τ), dt clamped to 250 ms). */
+  SMOOTH_TAU_POS_MS: 30,
+  SMOOTH_TAU_ROT_MS: 70,
+  /** A head snapshot this far in the future of the newest is a foreign-clock poison: drop it. */
+  POISON_GUARD_MS: 2e3,
+  /** A reconnect gap longer than this discards every stream's history (one deliberate rebase). */
+  REBASE_AFTER_GAP_MS: 1e3,
+  /** Host tick dt is clamped to this (a backgrounded tab must not tunnel the simulation). */
+  MAX_HOST_TICK_DT_MS: 250
+};
+var ClockSync = {
+  /** The heartbeat rate a client SHOULD send at, from a wall-clock timer (never the render loop). */
+  HEARTBEAT_HZ: 10,
+  /** A client that sends heartbeats MUST stay within [MIN_HEARTBEAT_HZ, MAX_HEARTBEAT_HZ] while its
+   *  page is foregrounded. Below MIN the offset and RTT refresh too slowly; above MAX buys nothing,
+   *  and the relay's small buffer (RELAY_BUFFER) folds the excess away. */
+  MIN_HEARTBEAT_HZ: 5,
+  MAX_HEARTBEAT_HZ: 20,
+  /** Each interval is the nominal one × (1 ± up to this), clamped to the band above. A fixed interval
+   *  that divides the patch interval phase-locks to the patch tick (every RTT sample then carries the
+   *  same hold); the dither walks the phase so near-zero holds keep turning up. */
+  HEARTBEAT_DITHER: 0.15,
+  /** Relay `defineInput({ bufferMaxSize })`. Overflow counts as consumed, so a burst still acks. */
+  RELAY_BUFFER: 4,
+  /** Acked heartbeats (RTT-valid samples) before a client treats `serverNow` as synced and uses it
+   *  for deadlines (≈3 s at 10 Hz). The room clock seeds its offset from the first TIMED frame, which
+   *  is biased by the one-way latency, and then moves by an EMA (α = 0.1) per RTT sample, so after k
+   *  samples 0.9^k of that bias remains: ≈35% at 10, ≈4% at 30 (≈6 ms at 150 ms one way). 30 is also
+   *  where the room clock's RTT gate stops being bypassed (its warmup). */
+  WARMUP_ACKS: 30
+};
+
+export {
+  PROTOCOL_VERSION,
+  MIN_PROTOCOL_VERSION,
+  RoomType,
+  JoinOption,
+  SERVER_OWNED_JOIN_OPTIONS,
+  JoinError,
+  STAGING_ROOM_PREFIX,
+  roomKeyFor,
+  slugOfRoomKey,
+  ClientMessage,
+  ServerMessage,
+  RESERVED_EVENT_PREFIXES,
+  RESERVED_EVENT_TYPES,
+  isReservedEventType,
+  RESERVED_SHARED_PREFIX,
+  SEND_TIME_KEY,
+  RATE_LANES,
+  GLOBAL_RATE,
+  MAX_MESSAGES_PER_SECOND,
+  MESSAGE_LANE,
+  CloseCode,
+  Limits,
+  RelayTiming,
+  ClientReconnection,
+  POSE_KEYS,
+  Interpolation,
+  ClockSync
+};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { PlayerState, RoomState } from './schema.js';
+import { ObjectControlOperation as ObjectControlOperation$1, ObjectControlReason as ObjectControlReason$1 } from './protocol.js';
+export { ObjectState, PlayerState, RoomState } from './schema.js';
 import '@colyseus/schema';
 
 /** One remote participant in the voice mesh. */
@@ -43,13 +44,14 @@ type ColyseusAuth = {
 };
 type AuthSource = ColyseusAuth | (() => ColyseusAuth | undefined);
 type ConnectOptions = {
-    /** Regional relay urls (pass `getColyseusUrls()`) — the SDK pings each and connects to the
-     *  lowest-latency one; a single entry just connects. */
+    /** 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
+     *  just connects. */
     urls: string[];
-    /** Cross-region invite override: connect to THIS exact relay url, skipping latency selection. Two
-     *  players are only in the same room if they share one region's relay, so an invitee must follow the
-     *  inviter's region (carried in the invite) instead of picking its own nearest. Omit for normal
-     *  nearest-region play. */
+    /** Override: connect to THIS exact relay url, skipping latency selection. Relays that share
+     *  presence (global matchmaking) seat players together whichever relay each enters through, so
+     *  this is only needed against relays that do not — there two players meet only on one relay, and
+     *  an invitee follows the inviter's region. Omit for normal nearest-region play. */
     url?: string;
     /** Game id — everyone who passes the same id shares a room; different ids are
      * fully isolated. Use your project slug (or any stable per-game string). */
@@ -70,6 +72,16 @@ type ConnectOptions = {
     auth?: AuthSource;
     /** Extra join options passed to the room. */
     options?: Record<string, unknown>;
+} & SessionOptions;
+/** How remote posed players are smoothed (EXPERIMENTAL, see {@link SessionOptions.smoothing}). */
+type PredictSmoothing = {
+    engine: 'predict';
+    /** Colyseus `Predict` mode. Default `'lerp'`. */
+    mode?: 'lerp' | 'damped';
+    /** `lerp` render delay in ms (Predict's default 100). */
+    delay?: number;
+    /** Predict's output spring / damped chase rate in ms (Predict's defaults when omitted). */
+    smoothMs?: number;
 };
 type PlayerView<TState> = {
     id: string;
@@ -81,6 +93,14 @@ type PlayerView<TState> = {
     avatarUrl: string;
     /** Transport is live now. False while this reserved seat is inside reconnect grace. */
     connected: boolean;
+    /** This player's stable id IN THIS GAME: the same across reloads, devices and rooms of the
+     * game, different in every other game, never the account id. Key anything that outlives a
+     * session (scores, colours, saves, "is this me") by it — `id` is a session id and changes on
+     * every reload. Opaque, ≤64 chars: never parse it. Relay-stamped from the verified token. */
+    uid: string;
+    /** Team index the relay assigned, or `-1` for no team: the `open` preset's `teams: N` (kept by
+     * `uid` for the room's life, never reshuffled) or the `teams` preset's current round. */
+    team: number;
     /** RENDER ONLY — for remote players this is **auto-smoothed** (interpolated) and delayed;
      * for yourself it's live. Numeric fields are lerped; everything else snaps. Use `stateRaw`
      * for every gameplay read (hits, reach, pickups, flags, physics adoption). */
@@ -103,8 +123,12 @@ type ObjectView<TState> = {
     /** The latest raw snapshot (never smoothed/delayed) — for hit-tests / logic. */
     stateRaw: TState;
 };
-type ObjectControlOperation = 'claim' | 'release' | 'remove';
-type ObjectControlReason = 'accepted' | 'already-owner' | 'held' | 'rate-limited' | 'not-owner' | 'capacity' | 'invalid' | 'missing' | 'host-authority' | 'not-host' | 'unsupported' | 'timeout' | 'aborted' | 'disconnected';
+type ObjectControlOperation = ObjectControlOperation$1;
+/** The relay's reasons (PROTOCOL.md §7.2), plus the ones this client settles a request with
+ *  itself: `timeout`, `aborted` (your signal, or `leave()`), `disconnected` (the session ended). */
+type ObjectControlReason = ObjectControlReason$1
+/** @deprecated Never produced since protocol 3 — every relay answers control requests. */
+ | 'unsupported' | 'timeout' | 'aborted' | 'disconnected';
 type ObjectControlResult = {
     requestId: string;
     operation: ObjectControlOperation;
@@ -185,7 +209,8 @@ type Session<TState extends Record<string, unknown>> = {
     /** True if you are the elected room host — the earliest signed-in player still present
      * (guests host only while no account is in the room); can migrate on join as well as leave.
      * Settles within the first state patch after connect — read it in your loop or react to
-     * `on('host')`, not once. */
+     * `on('host')`, not once. False while the session is reconnecting (until the fresh snapshot
+     * says who the host is now) and after it ends, so a write behind `isHost` is never stale. */
     readonly isHost: boolean;
     /** Session id of the current room host, or `undefined` until the first host patch lands. */
     readonly host: string | undefined;
@@ -228,27 +253,35 @@ type Session<TState extends Record<string, unknown>> = {
         limit?: number;
     }) => void): () => void;
     /**
-     * The connection dropped unexpectedly and auto-reconnect is underway (attempts run
-     * ~0.5s→8s backoff inside the server's grace window). Show a "reconnecting…" overlay;
-     * keep your loop running — the world resumes seamlessly on `reconnected`.
+     * The connection dropped unexpectedly and auto-reconnect is underway (one event per
+     * attempt; the attempts back off ~0.25s→4s and all land inside the relay's 30s seat grace).
+     * Show a "reconnecting…" overlay; keep your loop running — the world resumes seamlessly on
+     * `reconnected`. Host ticks pause until then.
      */
     on(event: 'reconnecting', cb: (info: {
         attempt: number;
         code: number;
     }) => void): () => void;
-    /** Auto-reconnect succeeded: same session id, same seat — nothing was torn down. */
+    /** Auto-reconnect succeeded: same session id, same seat — nothing was torn down. Fires once
+     *  the room's state is current again (host, owners, players), so it is safe to read here. */
     on(event: 'reconnected', cb: () => void): () => void;
     /**
      * The connection is gone for good: the server closed it on purpose (restart, revoked
-     * session, match eviction) or every reconnect attempt failed. The session is dead —
-     * to play again, read a FRESH `getColyseusAuth()` and `connect()` anew.
+     * session 4401, a newer tab took the seat 4409, match eviction) or every reconnect attempt
+     * failed (4003). The session is dead — to play again, read a FRESH `getColyseusAuth()` and
+     * `connect()` anew (but not automatically after 4409: the player is playing elsewhere).
      */
     on(event: 'disconnect', cb: (code: number) => void): () => void;
+    /** The host opened or closed this room to new matchmaking placements (`setRoomOpen`). */
+    on(event: 'room:open', cb: (info: {
+        open: boolean;
+    }) => void): () => void;
     /** A custom event another client sent via `send(type, ...)`. */
     on(event: string & {}, cb: (payload: unknown) => void): () => void;
     /** Fire-and-forget event to all OTHER clients (not stored in state). Event names used
-     * by the relay itself (`state`, `shared`, `claim`, `obj`, `release`, `destroy`, and the
-     * `match:`/`__` prefixes) are refused with a console warning — pick another name. */
+     * by the relay itself (`state`, `shared`, `claim`, `release`, `destroy`, `obj`, `queue`,
+     * `seat`, and the `__`/`match:`/`server:`/`rate:` prefixes) and names over 128 characters
+     * are refused with a console warning — pick another name. */
     send(type: string, payload?: unknown): void;
     /** Text chat for this room. See {@link ChatApi}. */
     chat: ChatApi;
@@ -263,12 +296,56 @@ type Session<TState extends Record<string, unknown>> = {
      * keeps playing, and a reconnecting player still gets back in (reconnection uses a
      * reserved seat, not matchmaking).
      *
-     * Ignored (with no error) when called by a non-host — read `isHost` first. All
-     * clients are told either way, so you can render "closed" from the `room:open` event.
+     * Ignored (with no error) when called by a non-host — read `isHost` first. When the host
+     * calls it every client is told, so you can render "closed" from the `room:open` event.
      */
     setRoomOpen(open: boolean): void;
     /** Leave the room (deliberate — no auto-reconnect, no `disconnect` event). */
     leave(): void;
+    /**
+     * EXPERIMENTAL — the relay's server clock (PROTOCOL.md §16): milliseconds since the room was
+     * created, estimated from this client's heartbeat acks. `undefined` against a relay that does not
+     * publish its clock. For server-stamped deadlines prefer {@link timeUntil}; never use this to drive
+     * rendering (remote players stay on their senders' clocks).
+     */
+    serverNow(): number | undefined;
+    /** EXPERIMENTAL — smoothed round-trip time to the relay in ms, from heartbeat acks. `undefined`
+     *  until the first ack, and always against a relay that does not publish its clock. It includes
+     *  the relay's hold until its next patch (0 to ~33 ms), so read it as an upper bound. */
+    readonly rtt: number | undefined;
+    /** EXPERIMENTAL — true once enough heartbeats were acked (~3 s) that `serverNow()` is within a few ms of the room clock. */
+    readonly clockSynced: boolean;
+    /**
+     * Milliseconds from now until a relay deadline stamped in epoch ms (a match's `startsAt` /
+     * `endsBy`; negative once it passed). Uses the server clock once it is synced — immune to a wrong
+     * clock on the player's device — and falls back to `deadline − Date.now()` otherwise.
+     */
+    timeUntil(epochMs: number): number;
+};
+/** Session behaviour options shared by `connect()`, `matchmake()`, `createPrivate()` and
+ *  `joinPrivate()`. Every one is EXPERIMENTAL and off by default: each is an A/B arm of the
+ *  netcode bench (PROTOCOL.md §15) and stays opt-in until it wins its gate. */
+type SessionOptions = {
+    /**
+     * EXPERIMENTAL — typed pose (PROTOCOL.md §6.6). Default `false`. When `true`, the reserved keys
+     * `x y z yaw vx vy vz anim` of `me.set()` / `me.snap()` are published as typed relay fields
+     * (float32 deltas instead of a re-sent JSON blob) and everything else as `data`, which is then sent
+     * only when it changes. If you omit `vx/vy/vz` they are derived from successive positions.
+     *
+     * Opt in for EVERY client of the game at once. Receivers then interpolate only the pose — `yaw`
+     * along the shortest arc (radians), `anim` switches when the rendered pose reaches it — and SNAP
+     * everything else in your state: a rotation you sync as a quaternion is no longer smoothed, so put
+     * the heading in `yaw`. A remote posed player's `state` always carries all eight pose keys.
+     */
+    pose?: boolean;
+    /**
+     * EXPERIMENTAL — remote smoothing engine for POSED players. Default `'genex'`: the SDK's own
+     * sender-clock interpolation (PROTOCOL.md §10.1), which every other stream keeps whatever this says.
+     * `'predict'` (or a {@link PredictSmoothing}) hands posed players' `x y z vx vy vz` and `yaw` to
+     * Colyseus `Predict` instead — receive-time stamps, a fixed delay, no dead reckoning past the newest
+     * sample, and `anim`/`data` applied on arrival. It exists so the bench can A/B the two engines.
+     */
+    smoothing?: 'genex' | 'predict' | PredictSmoothing;
 };
 /** One chat line, as the relay stamped it. Only `text` came from the sender's client —
  *  `from` and `name` are filled in server-side from the verified session, so a player
@@ -397,6 +474,16 @@ type MatchmakingView = {
     /** Winner of the round shown while `status === 'ended'` (competitor id; null on a draw). */
     winnerId: string | null;
     message: string;
+    /** The relay's epoch-ms `startsAt` — when the countdown (or the result screen before the next
+     *  round) ends — else null. */
+    startsAt: number | null;
+    /** Round time limit: the relay's epoch-ms `endsBy` (presets with a round limit), else null. */
+    endsBy: number | null;
+    /** Milliseconds until `startsAt` as of this read (≥ 0), or null. Measured on the relay's server
+     *  clock once it is synced, so a wrong clock on the player's device cannot skew a countdown. */
+    startsInMs: number | null;
+    /** Milliseconds until `endsBy` as of this read (≥ 0), or null. Same clock as `startsInMs`. */
+    endsInMs: number | null;
 };
 type Matchmaking<TState extends Record<string, unknown>> = {
     /** The live game session, or null while searching for a match. */
@@ -406,11 +493,17 @@ type Matchmaking<TState extends Record<string, unknown>> = {
     /**
      * searching: (re)entered the queue. queue: your position changed ({position,size}).
      * matched: `session` is now live. matchStart: a round began ({roundId}).
-     * matchEnded: {winnerId,loserId,draw,scores}. spectate: you're watching, not playing.
+     * matchEnded: {winnerId,losers,draw,scores}. spectate: you're watching, not playing.
      * error: joining the queue failed even after the SDK's automatic retries (persistent —
      * e.g. auth is broken or the server is unreachable); fix the cause, then call `retry()`.
+     * A relay that refuses this SDK's protocol (code 426) fails at once, without retries: the
+     * game needs an SDK update.
+     * disconnect: the match seat ended with 4409 (this player opened the game in another tab or
+     * device) or 4401 (signed out). The handle stops and does NOT requeue; `session` is null. Tell
+     * the player, and call `retry()` only if they choose to play here again. Every other terminal
+     * drop requeues automatically.
      */
-    on(event: 'searching' | 'queue' | 'matched' | 'matchStart' | 'matchEnded' | 'spectate' | 'error', cb: (payload?: unknown) => void): () => void;
+    on(event: 'searching' | 'queue' | 'matched' | 'matchStart' | 'matchEnded' | 'spectate' | 'error' | 'disconnect', cb: (payload?: unknown) => void): () => void;
     /** Report your OWN elimination (the `lastStanding` win condition). */
     eliminated(): void;
     /** Report a score delta for yourself (the `firstToScore` / `highScoreInTime` conditions). */
@@ -426,8 +519,8 @@ type Matchmaking<TState extends Record<string, unknown>> = {
 type MatchmakeOptions = {
     /** Regional relay urls (pass `getColyseusUrls()`) — pings each, connects to the lowest-latency one. */
     urls: string[];
-    /** Cross-region override: matchmake on THIS exact relay url, skipping latency selection — an invitee
-     *  follows the inviter's region so both land on the same relay. Omit for normal nearest-region play. */
+    /** Override: matchmake on THIS exact relay url, skipping latency selection — only needed against
+     *  relays that do not share presence (see ConnectOptions.url). Omit for normal nearest-region play. */
     url?: string;
     /** Game id (your project slug/id) — isolates this game's matchmaking. */
     room: string;
@@ -439,7 +532,7 @@ type MatchmakeOptions = {
      * token; a static object is read only once and will be rejected once it expires.
      */
     auth?: AuthSource;
-};
+} & SessionOptions;
 /**
  * Join a game's matchmaking. Returns immediately in the SEARCHING state (`session` is null); the
  * matchmaker seats you into a match room, at which point `session` becomes a live Session and a
@@ -469,4 +562,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 PrivateMatch, type Session, type VoiceApi, type VoiceJoinOptions, type VoiceParticipant, connect, createPrivate, joinPrivate, matchmake };
+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 };