@usions/sdk 2.2.0 → 2.11.0

package/src/modules/netcode/webtransport.js

@@ -0,0 +1,195 @@
+/**
+ * Usion SDK Netcode — WebTransport (HTTP/3 / QUIC) client transport.
+ *
+ * The lowest-latency *client-server* path for browser games (Baseline across
+ * major browsers since 2026). Unlike WebSocket (TCP → head-of-line blocking)
+ * it offers UDP-like unreliable **datagrams** — the newest snapshot always
+ * gets through — plus reliable **streams** for must-arrive events, over a
+ * single QUIC connection, without WebRTC's ICE/STUN/TURN/SDP complexity.
+ *
+ * Uses the native `WebTransport` API (zero dependency). On the server, pair
+ * with an HTTP/3 server such as the open-source `@fails-components/webtransport`
+ * (Node). Same interface shape as MeshConnection so it drops into the same
+ * snapshot sender/receiver + interpolation pipeline.
+ *
+ * Framing:
+ *   - datagram = [seq:uint32 BE][type:uint8][payload]  (one datagram = one msg)
+ *   - stream   = [len:uint32 BE][type:uint8][payload]  (len = 1 + payload bytes)
+ *   - type 0 = binary (Uint8Array), 1 = JSON (utf8). Sequenced datagrams drop
+ *     stale/out-of-order frames (receiver only advances).
+ */
+const _enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
+const _dec = typeof TextDecoder !== 'undefined' ? new TextDecoder() : null;
+
+function toBytes(s) { return _enc ? _enc.encode(s) : Uint8Array.from(Buffer.from(s, 'utf8')); }
+function fromBytes(b) { return _dec ? _dec.decode(b) : Buffer.from(b).toString('utf8'); }
+function isBinary(d) { return d instanceof ArrayBuffer || ArrayBuffer.isView(d); }
+
+/** Encode a value to { type, bytes }: binary passthrough or JSON utf8. */
+function encodePayload(data) {
+  if (isBinary(data)) return { type: 0, bytes: data instanceof Uint8Array ? data : new Uint8Array(data.buffer || data) };
+  return { type: 1, bytes: toBytes(JSON.stringify(data)) };
+}
+function decodePayload(type, bytes) {
+  if (type === 1) { try { return JSON.parse(fromBytes(bytes)); } catch (_) { return null; } }
+  return bytes;
+}
+
+/** datagram frame: [seq:4][type:1][payload] */
+export function encodeDatagram(seq, data) {
+  const { type, bytes } = encodePayload(data);
+  const out = new Uint8Array(5 + bytes.length);
+  new DataView(out.buffer).setUint32(0, seq >>> 0, false);
+  out[4] = type;
+  out.set(bytes, 5);
+  return out;
+}
+export function decodeDatagram(frame) {
+  const b = frame instanceof Uint8Array ? frame : new Uint8Array(frame);
+  if (b.length < 5) return null;
+  const seq = new DataView(b.buffer, b.byteOffset, b.byteLength).getUint32(0, false);
+  return { seq: seq, value: decodePayload(b[4], b.subarray(5)) };
+}
+
+/** stream frame: [len:4][type:1][payload], len = 1 + payload length */
+export function encodeStreamFrame(data) {
+  const { type, bytes } = encodePayload(data);
+  const out = new Uint8Array(4 + 1 + bytes.length);
+  new DataView(out.buffer).setUint32(0, 1 + bytes.length, false);
+  out[4] = type;
+  out.set(bytes, 5);
+  return out;
+}
+
+/** Stateful deframer for the reliable byte stream. push(bytes) → [values]. */
+export class StreamDeframer {
+  constructor() { this._buf = new Uint8Array(0); }
+  push(chunk) {
+    const c = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+    const merged = new Uint8Array(this._buf.length + c.length);
+    merged.set(this._buf, 0); merged.set(c, this._buf.length);
+    this._buf = merged;
+    const out = [];
+    while (this._buf.length >= 4) {
+      const len = new DataView(this._buf.buffer, this._buf.byteOffset, 4).getUint32(0, false);
+      if (this._buf.length < 4 + len) break;
+      const type = this._buf[4];
+      const payload = this._buf.subarray(5, 4 + len);
+      out.push(decodePayload(type, payload.slice()));
+      this._buf = this._buf.subarray(4 + len);
+    }
+    return out;
+  }
+}
+
+export class WebTransportConnection {
+  /**
+   * @param {object} opts
+   * @param {string} opts.url                          https:// HTTP/3 endpoint
+   * @param {Array}  [opts.serverCertificateHashes]    for self-signed dev certs
+   * @param {boolean}[opts.sequenced=true]             drop stale datagrams
+   * @param {Function}[opts.WebTransport]              injectable for tests
+   */
+  constructor(opts = {}) {
+    if (!opts.url) throw new Error('WebTransportConnection requires a url');
+    this._url = opts.url;
+    this._opts = opts;
+    this._sequenced = opts.sequenced !== false;
+    this._WT = opts.WebTransport || (typeof WebTransport !== 'undefined' ? WebTransport : null);
+
+    this.connected = false;
+    this._t = null;
+    this._dgWriter = null;
+    this._streamWriter = null;
+    this._deframer = new StreamDeframer();
+    this._sendSeq = 0;
+    this._recvSeq = 0;
+
+    this.onOpen = null;        // () => void
+    this.onMessage = null;     // (data, channel:'datagram'|'reliable') => void
+    this.onClose = null;       // () => void
+    this.onError = null;       // (err) => void
+  }
+
+  async connect() {
+    if (!this._WT) throw new Error('WebTransport unavailable in this environment');
+    const init = {};
+    if (this._opts.serverCertificateHashes) init.serverCertificateHashes = this._opts.serverCertificateHashes;
+    const t = new this._WT(this._url, init);
+    this._t = t;
+    if (t.ready && typeof t.ready.then === 'function') await t.ready;
+
+    if (t.datagrams && t.datagrams.writable) this._dgWriter = t.datagrams.writable.getWriter();
+    if (typeof t.createBidirectionalStream === 'function') {
+      try {
+        const s = await t.createBidirectionalStream();
+        this._streamWriter = s.writable.getWriter();
+        this._pumpReadable(s.readable, 'reliable');
+      } catch (e) { /* reliable stream optional */ }
+    }
+    if (t.datagrams && t.datagrams.readable) this._pumpDatagrams(t.datagrams.readable);
+    if (t.closed && typeof t.closed.then === 'function') t.closed.then(() => this._onClosed(), () => this._onClosed());
+
+    this.connected = true;
+    if (this.onOpen) this.onOpen();
+  }
+
+  async _pumpDatagrams(readable) {
+    try {
+      const reader = readable.getReader();
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) this._onDatagramBytes(value);
+      }
+    } catch (e) { if (this.onError) this.onError(e); }
+  }
+
+  async _pumpReadable(readable, channel) {
+    try {
+      const reader = readable.getReader();
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) { const msgs = this._deframer.push(value); for (let i = 0; i < msgs.length; i++) if (this.onMessage) this.onMessage(msgs[i], channel); }
+      }
+    } catch (e) { if (this.onError) this.onError(e); }
+  }
+
+  /** Handle one inbound datagram frame (also the test entry point). */
+  _onDatagramBytes(frame) {
+    const parsed = decodeDatagram(frame);
+    if (!parsed) return;
+    if (this._sequenced) {
+      if (parsed.seq <= this._recvSeq) return; // stale / out-of-order
+      this._recvSeq = parsed.seq;
+    }
+    if (this.onMessage) this.onMessage(parsed.value, 'datagram');
+  }
+
+  /** Send over the unreliable datagram channel (sequenced). */
+  send(data) {
+    if (!this._dgWriter) return false;
+    this._sendSeq += 1;
+    try { this._dgWriter.write(encodeDatagram(this._sendSeq, data)); return true; }
+    catch (e) { return false; }
+  }
+
+  /** Send over the reliable ordered stream. */
+  sendReliable(data) {
+    if (!this._streamWriter) return false;
+    try { this._streamWriter.write(encodeStreamFrame(data)); return true; }
+    catch (e) { return false; }
+  }
+
+  _onClosed() {
+    if (this.connected) { this.connected = false; if (this.onClose) this.onClose(); }
+  }
+
+  close() {
+    try { if (this._dgWriter) this._dgWriter.releaseLock && this._dgWriter.releaseLock(); } catch (_) {}
+    try { if (this._t) this._t.close(); } catch (_) {}
+    this._t = this._dgWriter = this._streamWriter = null;
+    this.connected = false;
+  }
+}

package/types/index.d.ts

@@ -16,6 +16,8 @@ export interface UsionConfig {
   theme?: 'light' | 'dark';
   language?: string;
   socketUrl?: string;
+  /** HTTP/3 WebTransport endpoint for direct-mode games (lowest latency). */
+  webTransportUrl?: string;
   roomId?: string;
   playerIds?: string[];
   serviceId?: string;
@@ -241,6 +243,400 @@ export interface GameModule {
 
   // Generic event listener
   on(event: string, callback: (data: any) => void): void;
+
+  // ─── Netcode helpers (low-latency realtime) ──────────────────
+  // JSON state delta compression.
+  diff(prev: any, next: any): any | undefined;
+  patch(base: any, delta: any): any;
+  /** Round numeric fields to a fixed precision (snapshot compression). */
+  quantize<T = any>(value: T, precision?: number): T;
+  /** Compact binary codec (use on direct/mesh transports). */
+  encode(value: any): Uint8Array;
+  decode(buf: ArrayBuffer | Uint8Array): any;
+
+  /** Snapshot interpolation buffer (adaptive buffer + capped extrapolation). */
+  createInterpolation(opts?: InterpolationOptions): SnapshotInterpolation;
+  /** Client-side prediction + reconciliation + error smoothing. */
+  createPredictor<S = any, I = any>(opts: PredictorOptions<S, I>): Predictor<S, I>;
+  /** Fixed-rate outbound coalescer (defaults to sending via game.realtime). */
+  createSender(opts?: SenderOptions): Coalescer;
+  /** Sequence-guarded, delta-compressed snapshot sender. Pair with createSnapshotReceiver. */
+  createSnapshotSender(opts?: SnapshotSenderOptions): SnapshotSender;
+  /** Receiver for createSnapshotSender (drops stale/out-of-order frames). */
+  createSnapshotReceiver(opts?: SnapshotReceiverOptions): SnapshotReceiver;
+  /** One-line WebRTC P2P (2-peer) setup; signaling over realtime. */
+  createMesh(opts: MeshOptions): MeshConnection;
+  /** N-peer full mesh; signaling routed per-peer over realtime. */
+  createMeshNetwork(opts?: MeshNetworkOptions): MeshNetwork;
+  /** WebTransport (HTTP/3) connection — lowest-latency client-server datagrams. */
+  createWebTransport(opts?: WebTransportOptions): WebTransportConnection;
+  /** Declarative replication (host): mutate the object, it auto-syncs. */
+  replicate<T = any>(obj: T, opts?: ReplicateOptions): Replicated<T>;
+  /** Declarative replication (client): receive + (optionally) interpolate. */
+  replica<S = any>(opts?: ReplicaOptions): Replica<S>;
+  /** Server-side lag compensation (history + rewind) for fair hit-resolution. */
+  createLagCompensator(opts?: LagCompensatorOptions): LagCompensator;
+  /** Deterministic lockstep (inputs-only sim + free replays). */
+  createLockstep(opts: LockstepOptions): Lockstep;
+  /** Inject latency/jitter/loss locally to test under bad networks (null = off). */
+  simulateNetwork(opts: NetworkSimOptions | null): NetworkSim | void;
+
+  /** Measure round-trip time once (single outstanding probe); ms or null. */
+  ping(): Promise<number | null>;
+  /** Latest smoothed round-trip time in ms (null until first ping). */
+  getRtt(): number | null;
+}
+
+// ─── Netcode toolkit ──────────────────────────────────────────────
+
+export interface NetcodeEntity {
+  id: string | number;
+  [key: string]: any;
+}
+
+export interface Snapshot {
+  id?: string;
+  time?: number;
+  state: NetcodeEntity[] | { [group: string]: NetcodeEntity[] };
+}
+
+export interface InterpolationOptions {
+  /** Expected snapshot rate; sets the default buffer (default 20). */
+  serverFps?: number;
+  /** Fixed interpolation delay in ms (default ≈ 3 server frames). */
+  bufferMs?: number;
+  /** Grow the buffer with measured jitter (Source cl_interp_ratio style). */
+  adaptive?: boolean;
+  /** Adaptive buffer clamps. */
+  minBufferMs?: number;
+  maxBufferMs?: number;
+  /** Max forward extrapolation on buffer underrun, ms (0 = off; Source caps ~250). */
+  extrapolationMs?: number;
+  /** Render against snapshot.time (server clock domain) instead of arrival time. */
+  serverTime?: boolean;
+  /** Snapshot history depth (default 120). */
+  maxSize?: number;
+  /** Clock source override (default Date.now). */
+  now?: () => number;
+}
+
+export class SnapshotInterpolation {
+  constructor(opts?: InterpolationOptions);
+  getBufferMs(): number;
+  setBufferMs(ms: number): void;
+  getJitter(): number;
+  add(snapshot: Snapshot | NetcodeEntity[] | { [group: string]: NetcodeEntity[] }): void;
+  /** Interpolated entities for the render instant, or null if no data yet. */
+  calc(keys: string, group?: string): NetcodeEntity[] | null;
+  vault: Vault;
+}
+
+export class Vault {
+  constructor(maxSize?: number);
+  add(snapshot: { time: number; state: any }): void;
+  readonly size: number;
+  setMaxSize(n: number): void;
+  latest(): { time: number; state: any } | null;
+  clear(): void;
+  straddle(time: number): [any, any];
+}
+
+export interface PredictorSmoothOptions {
+  keys?: string | string[];
+  rate?: number;
+  snapTo?: number;
+}
+
+export interface PredictorOptions<S = any, I = any> {
+  apply: (state: S, input: I) => S;
+  initialState?: S;
+  /** Smoothly blend correction errors instead of snapping (Overwatch style). */
+  smooth?: PredictorSmoothOptions | string;
+}
+
+export class Predictor<S = any, I = any> {
+  constructor(opts: PredictorOptions<S, I>);
+  readonly state: S;
+  readonly pending: Array<{ seq: number; input: I }>;
+  readonly lastSeq: number;
+  predict(input: I): { seq: number; state: S };
+  reconcile(serverState: S, ackedSeq: number): S;
+  /** Render state: corrected + decaying error offset. Call once per frame. */
+  view(rate?: number): S;
+  reset(state?: S): void;
+}
+
+export interface CoalescerOptions {
+  hz?: number;
+  onFlush: (entries: Array<{ type: string; data: any }>) => void;
+  autoStart?: boolean;
+  setInterval?: (fn: () => void, ms: number) => any;
+  clearInterval?: (handle: any) => void;
+}
+
+export class Coalescer {
+  constructor(opts: CoalescerOptions);
+  readonly running: boolean;
+  /** Latest-wins: only the newest data for `type` is sent next flush. */
+  queue(type: string, data: any): void;
+  /** Buffered: every value for `type` is kept and sent next flush. */
+  append(type: string, data: any): void;
+  drain(): Array<{ type: string; data: any }>;
+  flush(): void;
+  start(): void;
+  stop(): void;
+}
+
+export interface SenderOptions {
+  hz?: number;
+  autoStart?: boolean;
+  send?: (type: string, data: any) => void;
+}
+
+export interface SnapshotSenderOptions extends SenderOptions {
+  /** realtime action_type to send under (default 'state'). */
+  channel?: string;
+  /** Use delta compression with periodic keyframes (default true). */
+  delta?: boolean;
+  /** Send a full keyframe every N deltas so lost deltas self-heal (default 30). */
+  keyframeEvery?: number;
+  /** Quantize numeric fields to this many decimals before diffing. */
+  precision?: number;
+  /** Binary-encode the wire payload: true (built-in) or a custom encoder. */
+  encode?: boolean | ((payload: any) => any);
+  /** Auto-read state each tick from this getter (basis for game.replicate). */
+  source?: () => any;
+}
+
+export interface ReplicateOptions extends SnapshotSenderOptions {}
+
+export interface Replicated<T = any> {
+  state: T;
+  flush(): void;
+  start(): void;
+  stop(): void;
+}
+
+export interface ReplicaOptions {
+  channel?: string;
+  decode?: boolean | ((buf: any) => any);
+  /** Interpolation keys ('x y') or an InterpolationOptions object to smooth entities. */
+  interpolate?: string | InterpolationOptions;
+  keys?: string;
+  group?: string;
+}
+
+export interface Replica<S = any> {
+  readonly state: S;
+  view(): any;
+  onChange(cb: (state: S) => void): void;
+  stop(): void;
+}
+
+export interface NetworkSimOptions {
+  latencyMs?: number;
+  jitterMs?: number;
+  lossPct?: number;
+  dupPct?: number;
+  setTimeout?: (fn: () => void, ms: number) => any;
+  clearTimeout?: (handle: any) => void;
+  random?: () => number;
+}
+
+export class NetworkSim {
+  constructor(opts?: NetworkSimOptions);
+  latencyMs: number; jitterMs: number; lossPct: number; dupPct: number;
+  set(opts: NetworkSimOptions): NetworkSim;
+  wrap<F extends (...args: any[]) => any>(fn: F): F;
+  flush(): void;
+}
+
+export interface LockstepOptions {
+  playerId: string;
+  players: string[];
+  step: (frame: number, inputs: Record<string, any>) => void;
+  send?: (msg: { frame: number; playerId: string; input: any }) => void;
+  inputDelay?: number;
+  idleInput?: any;
+}
+
+export class Lockstep {
+  constructor(opts: LockstepOptions);
+  readonly frame: number;
+  readonly players: string[];
+  submit(input: any): number;
+  receive(msg: { frame: number; playerId: string; input: any }): void;
+  tick(): number;
+  isStalled(): boolean;
+  getReplay(): Array<{ frame: number; inputs: Record<string, any> }>;
+  static replay(log: Array<{ frame: number; inputs: Record<string, any> }>, step: (frame: number, inputs: Record<string, any>) => void): void;
+}
+
+export interface LagCompensatorOptions {
+  historyMs?: number;
+  maxSize?: number;
+  now?: () => number;
+}
+
+export class LagCompensator {
+  constructor(opts?: LagCompensatorOptions);
+  readonly size: number;
+  record(entities: Array<{ id: string | number; [k: string]: any }>, time?: number): void;
+  rewind(time: number, keys?: string[]): Record<string, any>;
+  rewindForClient(rttMs: number, interpBufferMs: number, opts?: { maxRewindMs?: number; keys?: string[] }): Record<string, any>;
+  clear(): void;
+}
+
+export interface SnapshotSender {
+  send(state: any): void;
+  flush(): void;
+  start(): void;
+  stop(): void;
+  reset(): void;
+}
+
+export interface SnapshotReceiverOptions {
+  /** Binary-decode incoming payloads: true (built-in) or a custom decoder. */
+  decode?: boolean | ((buf: any) => any);
+}
+
+export interface SnapshotReceiver {
+  /** Apply a message from the sender; returns the reconstructed state. */
+  receive<S = any>(msg: any): S;
+  readonly state: any;
+  readonly stats: { appliedSeq: number; baseSeq: number; dropped: number };
+  reset(): void;
+}
+
+export interface PingMeterOptions {
+  alpha?: number;
+  now?: () => number;
+}
+
+export class PingMeter {
+  constructor(opts?: PingMeterOptions);
+  readonly rtt: number | null;
+  readonly latency: number | null;
+  readonly jitter: number;
+  readonly last: number | null;
+  begin(): number;
+  end(id: number): number | null;
+  sample(rttMs: number): number | null;
+  reset(): void;
+}
+
+export interface IceServerConfig {
+  stun?: string;
+  turn?: string;
+  turnUsername?: string;
+  turnCredential?: string;
+}
+
+export interface MeshOptions {
+  role: 'host' | 'guest';
+  /** realtime action_type used for signaling (default 'signal'). */
+  signalChannel?: string;
+  iceServers?: RTCIceServer[];
+  /** Drop stale/out-of-order frames on the unreliable channel (default true). */
+  sequenced?: boolean;
+  /** Recover via ICE restart on connection failure (host; default true). */
+  autoReconnect?: boolean;
+  maxRestarts?: number;
+  RTCPeerConnection?: typeof RTCPeerConnection;
+  setTimeout?: (fn: () => void, ms: number) => any;
+}
+
+export class MeshConnection {
+  constructor(opts: MeshOptions & { sendSignal: (payload: any) => void });
+  /** Build an iceServers array with optional TURN relay. */
+  static iceServers(cfg?: IceServerConfig): RTCIceServer[];
+  readonly connected: boolean;
+  readonly role: 'host' | 'guest';
+  onOpen: (() => void) | null;
+  onMessage: ((data: any, channel: 'unreliable' | 'reliable') => void) | null;
+  onClose: (() => void) | null;
+  onError: ((err: any) => void) | null;
+  onStateChange: ((state: string) => void) | null;
+  start(): Promise<void>;
+  handleSignal(payload: any): Promise<void>;
+  send(data: any): boolean;
+  sendReliable(data: any): boolean;
+  close(): void;
+}
+
+export interface MeshNetworkOptions {
+  selfId?: string;
+  signalChannel?: string;
+  iceServers?: RTCIceServer[];
+  sequenced?: boolean;
+  autoReconnect?: boolean;
+  RTCPeerConnection?: typeof RTCPeerConnection;
+}
+
+export class MeshNetwork {
+  constructor(opts: MeshNetworkOptions & { selfId: string; sendSignal: (toPeerId: string, payload: any) => void });
+  readonly selfId: string;
+  readonly peerIds: string[];
+  readonly connectedCount: number;
+  peer(peerId: string): MeshConnection | null;
+  addPeer(peerId: string): Promise<MeshConnection | null>;
+  setRoster(peerIds: string[]): Promise<void>;
+  removePeer(peerId: string): void;
+  handleSignal(fromPeerId: string, payload: any): Promise<void>;
+  send(peerId: string, data: any): boolean;
+  sendReliable(peerId: string, data: any): boolean;
+  broadcast(data: any): void;
+  broadcastReliable(data: any): void;
+  onPeerOpen: ((peerId: string) => void) | null;
+  onPeerClose: ((peerId: string) => void) | null;
+  onMessage: ((peerId: string, data: any, channel: 'unreliable' | 'reliable') => void) | null;
+  onError: ((peerId: string, err: any) => void) | null;
+  close(): void;
+}
+
+export interface WebTransportOptions {
+  /** https:// HTTP/3 endpoint (defaults to Usion.config.webTransportUrl). */
+  url?: string;
+  /** For self-signed dev certificates. */
+  serverCertificateHashes?: Array<{ algorithm: string; value: BufferSource }>;
+  /** Drop stale/out-of-order datagrams (default true). */
+  sequenced?: boolean;
+  /** Injectable WebTransport constructor (tests). */
+  WebTransport?: any;
+}
+
+export class WebTransportConnection {
+  constructor(opts: WebTransportOptions & { url: string });
+  readonly connected: boolean;
+  onOpen: (() => void) | null;
+  onMessage: ((data: any, channel: 'datagram' | 'reliable') => void) | null;
+  onClose: (() => void) | null;
+  onError: ((err: any) => void) | null;
+  connect(): Promise<void>;
+  /** Send over the unreliable datagram channel (sequenced). */
+  send(data: any): boolean;
+  /** Send over the reliable ordered stream. */
+  sendReliable(data: any): boolean;
+  close(): void;
+}
+
+export interface NetcodeModule {
+  SnapshotInterpolation: typeof SnapshotInterpolation;
+  Vault: typeof Vault;
+  Predictor: typeof Predictor;
+  Coalescer: typeof Coalescer;
+  PingMeter: typeof PingMeter;
+  MeshConnection: typeof MeshConnection;
+  MeshNetwork: typeof MeshNetwork;
+  WebTransportConnection: typeof WebTransportConnection;
+  NetworkSim: typeof NetworkSim;
+  Lockstep: typeof Lockstep;
+  LagCompensator: typeof LagCompensator;
+  diff(prev: any, next: any): any | undefined;
+  patch(base: any, delta: any): any;
+  quantize<T = any>(value: T, precision?: number): T;
+  encode(value: any): Uint8Array;
+  decode(buf: ArrayBuffer | Uint8Array): any;
 }
 
 // ─── Results ────────────────────────────────────────────────────
@@ -346,6 +742,59 @@ export interface UsionSDK {
   chat: ChatModule;
   bot: BotModule;
   game: GameModule;
+  lobby: LobbyModule;
+  leaderboard: LeaderboardModule;
+  matchmaking: MatchmakingModule;
+  netcode: NetcodeModule;
+}
+
+export interface Match { roomId: string; players: string[]; serviceId?: string; }
+
+export interface MatchmakingModule {
+  /** Join the quick-match queue; resolves when paired with online strangers. */
+  find(serviceId?: string, opts?: { size?: number }): Promise<Match>;
+  /** Leave the queue / stop waiting. */
+  cancel(): Promise<any>;
+  /** Called whenever a match is found. */
+  onMatch(cb: (match: Match) => void): void;
+}
+
+export interface LeaderboardEntry {
+  user_id: string;
+  name?: string | null;
+  avatar?: string | null;
+  score: number;
+  rank: number;
+  is_me: boolean;
+  metadata?: any;
+}
+
+export interface LeaderboardModule {
+  /** Submit a score (best is kept per the service's order config). Opt-in per game. */
+  submit(score: number, metadata?: any, opts?: { serviceId?: string }): Promise<{ success: boolean; score: number; best: number; rank: number; updated: boolean }>;
+  /** Leaderboard of people you've messaged (plus you). */
+  friends(opts?: { serviceId?: string; limit?: number }): Promise<LeaderboardEntry[]>;
+  /** Global top N. */
+  top(opts?: { serviceId?: string; limit?: number }): Promise<LeaderboardEntry[]>;
+  /** Your own score + global rank. */
+  me(opts?: { serviceId?: string }): Promise<{ score: number | null; rank: number | null; total: number; metadata?: any }>;
+}
+
+export interface LobbyMember { id: string; name?: string; ready: boolean; }
+export interface LobbyState { code: string | null; host: string | null; status: string | null; members: LobbyMember[]; }
+
+export interface LobbyModule {
+  readonly state: LobbyState;
+  onUpdate(cb: (state: { code: string; host: string; status: string; members: LobbyMember[] }) => void): void;
+  onStarted(cb: (data: { room_id: string; by: string; player_ids?: string[] }) => void): void;
+  create(opts?: { maxPlayers?: number; public?: boolean }): Promise<{ code: string }>;
+  join(code: string): Promise<{ code: string }>;
+  leave(): Promise<void>;
+  setReady(ready?: boolean): Promise<any>;
+  allReady(): boolean;
+  isHost(): boolean;
+  start(roomId: string): Promise<any>;
+  queue(serviceId: string, opts?: { conversationId?: string }): Promise<any>;
 }
 
 declare const Usion: UsionSDK;