@usions/sdk 2.1.5 → 2.10.0

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;
@@ -213,6 +215,16 @@ export interface GameModule {
   requestRematch(): void;
   forfeit(): Promise<{ success: boolean; error?: string }>;
 
+  // Persisted state — survives iframe unmount/remount.
+  // Keyed by (player_id, room_id) in localStorage. Schema is up to the game.
+  saveState<T = any>(state: T): boolean;
+  loadState<T = any>(): T | null;
+  clearState(): void;
+
+  // Forward a debug snapshot to the parent. Rendered as a top-right
+  // overlay over the iframe when the host page is opened with `?debug=1`.
+  debug(payload: Record<string, any>): void;
+
   // Event handlers
   onJoined(callback: (data: GameJoinResult) => void): void;
   onPlayerJoined(callback: (data: PlayerJoinedData) => void): void;
@@ -231,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 ────────────────────────────────────────────────────
@@ -306,6 +712,10 @@ export interface UsionSDK {
 
   // Sharing
   share(contentType: 'audio' | 'image' | 'video' | 'text' | 'mixed', data: ShareData): void;
+  shareToFeed(contentType: 'text' | 'image' | 'video' | 'audio' | 'mixed', data: {
+    text?: string;
+    media?: Array<{ type: 'image' | 'video' | 'audio'; url: string; thumbnailUrl?: string; width?: number; height?: number; duration?: number }>;
+  }): Promise<{ success: boolean; postId?: string; shareUrl?: string }>;
 
   // Logging
   log(msg: string): void;
@@ -332,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;