@usions/sdk 2.1.5 → 2.10.0

package/src/modules/game-netcode.js

@@ -0,0 +1,346 @@
+/**
+ * Usion SDK Game Netcode — convenience wiring of the netcode toolkit onto the
+ * game module. These helpers ride on the existing realtime/action channels, so
+ * they work in every connection mode with no host/backend change (the one
+ * exception is RTT measurement — see game.ping below).
+ */
+import { SnapshotInterpolation } from './netcode/interpolation.js';
+import { Predictor } from './netcode/prediction.js';
+import { Coalescer } from './netcode/sender.js';
+import { PingMeter } from './netcode/ping.js';
+import { MeshConnection } from './netcode/mesh.js';
+import { MeshNetwork } from './netcode/mesh-network.js';
+import { WebTransportConnection } from './netcode/webtransport.js';
+import { NetworkSim } from './netcode/netsim.js';
+import { Lockstep } from './netcode/lockstep.js';
+import { LagCompensator } from './netcode/lagcomp.js';
+import { diff, patch, quantize } from './netcode/delta.js';
+import { encode, decode } from './netcode/binary.js';
+
+export function applyGameNetcode(game, Usion) {
+  game.diff = diff;
+  game.patch = patch;
+  game.quantize = quantize;
+  game.encode = encode;
+  game.decode = decode;
+
+  game.createInterpolation = function (opts) { return new SnapshotInterpolation(opts || {}); };
+  game.createPredictor = function (opts) { return new Predictor(opts || {}); };
+  game.createLagCompensator = function (opts) { return new LagCompensator(opts || {}); };
+  game.createLockstep = function (opts) { return new Lockstep(opts || {}); };
+
+  // ── Realtime channel router ──────────────────────────────────────────────
+  // Multiplexes realtime by action_type so replicate / mesh / mesh-network and
+  // the game's own onRealtime can coexist. Also the inject point for the
+  // network simulator's inbound side.
+  game._channels = game._channels || {};
+  game._userRealtime = game._userRealtime || null;
+  game._inboundDispatch = null;
+  function dispatchRealtime(data) {
+    const at = data && data.action_type;
+    if (at && game._channels[at]) { game._channels[at](data && (data.action_data !== undefined ? data.action_data : data), data); return; }
+    if (game._userRealtime) game._userRealtime(data);
+  }
+  game._dispatchRealtime = dispatchRealtime;
+  game._installRealtimeRouter = function () {
+    if (game._routerInstalled) return;
+    if (game._eventHandlers.realtime && game._eventHandlers.realtime !== game._router) game._userRealtime = game._eventHandlers.realtime;
+    game._router = function (data) { (game._inboundDispatch || game._dispatchRealtime)(data); };
+    game._eventHandlers.realtime = game._router;
+    game._routerInstalled = true;
+  };
+  /** Register a handler for one realtime action_type. Returns an unsubscribe fn. */
+  game._onChannel = function (type, handler) { game._channels[type] = handler; game._installRealtimeRouter(); return function () { delete game._channels[type]; }; };
+  // Route onRealtime through the router so channels keep working.
+  game.onRealtime = function (cb) { game._userRealtime = cb; game._installRealtimeRouter(); };
+
+  /** Fixed-rate outbound sender (defaults to game.realtime). */
+  game.createSender = function (opts) {
+    opts = opts || {};
+    const self = this;
+    const send = opts.send || function (type, data) { self.realtime(type, data); };
+    return new Coalescer({
+      hz: opts.hz || 20,
+      autoStart: opts.autoStart !== false,
+      onFlush: function (entries) { for (let i = 0; i < entries.length; i++) send(entries[i].type, entries[i].data); },
+    });
+  };
+
+  /**
+   * Coalesced, sequence-guarded, delta-compressed snapshot sender.
+   *
+   * Deltas are computed against the **last keyframe** (not the previous frame),
+   * so a single lost delta on an unreliable channel never desyncs — the next
+   * delta still applies to the keyframe the receiver holds. Each message
+   * carries a monotonic seq (`s`) and, for deltas, the keyframe seq it's based
+   * on (`b`); the receiver uses these to drop stale/out-of-order frames and to
+   * hold until it has the right keyframe. Optional float `precision`
+   * (quantization) and binary `encode` shrink the wire further.
+   *
+   * Pass `source` (a getter) to auto-read the state each tick — the basis for
+   * game.replicate(). Pair with game.createSnapshotReceiver().
+   */
+  game.createSnapshotSender = function (opts) {
+    opts = opts || {};
+    const self = this;
+    const channel = opts.channel || 'state';
+    const useDelta = opts.delta !== false;
+    const keyframeEvery = opts.keyframeEvery != null ? opts.keyframeEvery : 30;
+    const precision = opts.precision;
+    const enc = opts.encode === true ? encode : (typeof opts.encode === 'function' ? opts.encode : null);
+    const send = opts.send || function (type, data) { self.realtime(type, data); };
+    const source = typeof opts.source === 'function' ? opts.source : null;
+    let keyframeState = null; // an immutable clone (deltas diff against this)
+    let keyframeSeq = 0;
+    let seq = 0;
+    let sinceKey = 0;
+
+    function snapshotClone(v) { return v == null ? v : JSON.parse(JSON.stringify(v)); }
+
+    function emit(raw) {
+      if (raw === undefined || raw === null) return;
+      const state = precision != null ? quantize(raw, precision) : raw;
+      let payload;
+      const wantKey = !useDelta || keyframeState === null || sinceKey >= keyframeEvery;
+      if (wantKey) {
+        seq += 1; keyframeState = snapshotClone(state); keyframeSeq = seq; sinceKey = 0;
+        payload = { s: seq, f: state };
+      } else {
+        const d = diff(keyframeState, state);
+        if (d === undefined) return; // nothing changed — don't burn a seq
+        seq += 1; sinceKey += 1;
+        payload = { s: seq, b: keyframeSeq, d: d };
+      }
+      send(channel, enc ? enc(payload) : payload);
+    }
+
+    // Two drive modes: a `source` getter (read every tick) or queued send().
+    const hz = opts.hz || 20;
+    let queued;
+    const co = source ? null : new Coalescer({
+      hz: hz, autoStart: opts.autoStart !== false,
+      onFlush: function (entries) { for (let i = 0; i < entries.length; i++) if (entries[i].type === '__snap') queued = entries[i].data; emit(queued); },
+    });
+    let timer = null;
+    function start() {
+      if (co) { co.start(); return; }
+      if (timer || typeof setInterval === 'undefined') return;
+      timer = setInterval(function () { emit(source()); }, Math.max(1, Math.round(1000 / hz)));
+    }
+    function stop() { if (co) co.stop(); if (timer) { clearInterval(timer); timer = null; } }
+    if (source && opts.autoStart !== false) start();
+
+    return {
+      send: function (state) { if (co) co.queue('__snap', state); else emit(state); },
+      flush: function () { if (co) co.flush(); else if (source) emit(source()); },
+      start: start,
+      stop: stop,
+      reset: function () { keyframeState = null; keyframeSeq = 0; seq = 0; sinceKey = 0; },
+    };
+  };
+
+  /**
+   * Receiver for createSnapshotSender. Holds the keyframe baseline + last
+   * applied seq, so it safely drops stale/out-of-order frames and ignores
+   * deltas whose keyframe it missed (until the next keyframe arrives).
+   * @returns {{ receive:(msg:any)=>any, state:any, stats:object, reset:()=>void }}
+   */
+  game.createSnapshotReceiver = function (opts) {
+    opts = opts || {};
+    const dec = opts.decode === true ? decode : (typeof opts.decode === 'function' ? opts.decode : null);
+    let base = null, baseSeq = -1, current = null, appliedSeq = -1, dropped = 0;
+    return {
+      receive: function (msg) {
+        if (dec && (msg instanceof ArrayBuffer || ArrayBuffer.isView(msg))) msg = dec(msg);
+        if (!msg) return current;
+        if (msg.f !== undefined) {
+          if (msg.s !== undefined && msg.s <= appliedSeq) { dropped += 1; return current; }
+          base = msg.f; baseSeq = msg.s !== undefined ? msg.s : 0; current = msg.f; appliedSeq = baseSeq;
+          return current;
+        }
+        if (msg.d !== undefined) {
+          if (msg.b !== undefined && msg.b !== baseSeq) { dropped += 1; return current; } // missed keyframe
+          if (msg.s !== undefined && msg.s <= appliedSeq) { dropped += 1; return current; } // stale/dup
+          current = patch(base, msg.d);
+          if (msg.s !== undefined) appliedSeq = msg.s;
+          return current;
+        }
+        return current;
+      },
+      get state() { return current; },
+      get stats() { return { appliedSeq: appliedSeq, baseSeq: baseSeq, dropped: dropped }; },
+      reset: function () { base = null; baseSeq = -1; current = null; appliedSeq = -1; dropped = 0; },
+    };
+  };
+
+  /**
+   * Declarative state replication (host side). Mutate the plain object you pass
+   * in; the SDK auto-diffs and broadcasts it every tick (sequence-guarded,
+   * delta-compressed, optional quantize/binary). Clients read it with
+   * game.replica(). This is the ~40-lines-into-2 ergonomic.
+   * @returns {{ state:any, flush:()=>void, start:()=>void, stop:()=>void }}
+   */
+  game.replicate = function (obj, opts) {
+    opts = opts || {};
+    let state = obj != null ? obj : {};
+    const sender = this.createSnapshotSender(Object.assign({}, opts, { source: function () { return state; } }));
+    return {
+      get state() { return state; },
+      set state(v) { state = v; },
+      flush: function () { sender.flush(); },
+      start: function () { sender.start(); },
+      stop: function () { sender.stop(); },
+    };
+  };
+
+  /**
+   * Declarative state replication (client side). Receives what a host
+   * replicate()s on the same channel, drops stale/out-of-order frames, and
+   * (optionally) interpolates. Read `.state` for the latest authoritative state,
+   * or `.view()` for smoothed entities when `interpolate` keys are given.
+   * @returns {{ state:any, view:()=>any, onChange:(cb)=>void, stop:()=>void }}
+   */
+  game.replica = function (opts) {
+    opts = opts || {};
+    const channel = opts.channel || 'state';
+    const rx = this.createSnapshotReceiver({ decode: opts.decode });
+    const interp = opts.interpolate ? this.createInterpolation(typeof opts.interpolate === 'object' ? opts.interpolate : {}) : null;
+    const keys = typeof opts.interpolate === 'string' ? opts.interpolate : (opts.keys || (opts.interpolate && opts.interpolate.keys));
+    const group = opts.group || (opts.interpolate && opts.interpolate.group);
+    let onChange = null;
+    const off = this._onChannel(channel, function (data) {
+      const next = rx.receive(data);
+      if (interp && next != null) interp.add(next);
+      if (onChange) onChange(next);
+    });
+    return {
+      get state() { return rx.state; },
+      view: function () { return interp ? interp.calc(keys || 'x y', group) : rx.state; },
+      onChange: function (cb) { onChange = cb; },
+      stop: function () { off(); },
+    };
+  };
+
+  /**
+   * One-line WebRTC peer-to-peer setup (2 peers). Signaling rides the realtime
+   * channel via the router; gameplay then flows directly peer-to-peer over UDP.
+   */
+  game.createMesh = function (opts) {
+    opts = opts || {};
+    const self = this;
+    const channel = opts.signalChannel || 'signal';
+    const mesh = new MeshConnection(Object.assign({}, opts, {
+      sendSignal: function (payload) { self.realtime(channel, payload); },
+    }));
+    this._onChannel(channel, function (payload) { if (payload && payload.type) mesh.handleSignal(payload); });
+    return mesh;
+  };
+
+  /**
+   * N-peer full mesh. Signaling routed per-peer over the realtime channel (each
+   * message carries {to, from}); messages addressed to us are dispatched to the
+   * right peer connection. selfId defaults to the current user id.
+   * @returns {MeshNetwork}
+   */
+  game.createMeshNetwork = function (opts) {
+    opts = opts || {};
+    const self = this;
+    const channel = opts.signalChannel || 'mesh';
+    const selfId = opts.selfId || (Usion.user && Usion.user.getId && Usion.user.getId());
+    const net = new MeshNetwork(Object.assign({}, opts, {
+      selfId: selfId,
+      sendSignal: function (toPeerId, payload) { self.realtime(channel, { to: toPeerId, from: selfId, payload: payload }); },
+    }));
+    this._onChannel(channel, function (ad) { if (ad && ad.to === selfId && ad.from) net.handleSignal(ad.from, ad.payload); });
+    return net;
+  };
+
+  /**
+   * Inject artificial latency / jitter / packet loss locally to test how the
+   * game feels on a bad network (every studio has this). Affects both outbound
+   * realtime sends and inbound realtime dispatch. Call with null/false to turn
+   * it off. No-op safety: realtime must exist on the game module.
+   * @param {{latencyMs?:number,jitterMs?:number,lossPct?:number,dupPct?:number}|null} opts
+   */
+  game.simulateNetwork = function (opts) {
+    const self = this;
+    self._installRealtimeRouter();
+    if (!self._realtimeRaw && typeof self.realtime === 'function') self._realtimeRaw = self.realtime.bind(self);
+    if (!opts) {
+      if (self._realtimeRaw) self.realtime = self._realtimeRaw;
+      self._inboundDispatch = null;
+      if (self._sim) self._sim.flush();
+      self._sim = null;
+      return;
+    }
+    if (!self._sim) self._sim = new NetworkSim(opts);
+    else self._sim.set(opts);
+    if (self._realtimeRaw) self.realtime = self._sim.wrap(self._realtimeRaw);
+    self._inboundDispatch = self._sim.wrap(self._dispatchRealtime);
+    return self._sim;
+  };
+
+  /**
+   * Create a WebTransport (HTTP/3) connection — the lowest-latency client-server
+   * path (UDP-like datagrams, no TCP head-of-line blocking). `url` defaults to
+   * Usion.config.webTransportUrl. Call `connect()`, then `send()` (datagram) /
+   * `sendReliable()`; feed `onMessage` into a snapshot receiver. Direct/standalone
+   * games only (the iframe/WebView proxy relay can't carry datagrams).
+   * @returns {WebTransportConnection}
+   */
+  game.createWebTransport = function (opts) {
+    opts = opts || {};
+    const url = opts.url || (Usion.config && (Usion.config.webTransportUrl || Usion.config.wtUrl));
+    return new WebTransportConnection(Object.assign({}, opts, { url: url }));
+  };
+
+  /**
+   * Measure round-trip time once (single outstanding probe), updating the
+   * rolling estimate (game.getRtt). Direct mode uses the protocol ping/pong;
+   * platform mode uses a lightweight server ack. Resolves to ms, or null if
+   * unavailable (proxy mode, or not connected).
+   * @returns {Promise<number|null>}
+   */
+  game.ping = function () {
+    const self = this;
+    if (!self._pingMeter) self._pingMeter = new PingMeter();
+    if (self._pingInFlight) return self._pingInFlight; // single outstanding probe
+
+    let promise;
+    if (self.directMode) {
+      if (!self.directSocket || self.directSocket.readyState !== 1) return Promise.resolve(null);
+      promise = new Promise(function (resolve) {
+        const id = self._pingMeter.begin();
+        let done = false;
+        const finish = function () { if (done) return; done = true; resolve(self._pingMeter.end(id)); };
+        self._pongWaiters.push(finish);
+        self._sendDirect('ping', { t: Date.now() });
+        setTimeout(function () {
+          if (done) return; done = true;
+          const idx = self._pongWaiters.indexOf(finish);
+          if (idx >= 0) self._pongWaiters.splice(idx, 1);
+          delete self._pingMeter._outstanding[id];
+          resolve(null);
+        }, 3000);
+      });
+    } else if (self.socket && self.connected && !self._useProxy) {
+      promise = new Promise(function (resolve) {
+        const start = Date.now();
+        let done = false;
+        try {
+          self.socket.emit('game:ping', { t: start }, function () { if (done) return; done = true; resolve(self._pingMeter.sample(Date.now() - start)); });
+        } catch (e) { resolve(null); return; }
+        setTimeout(function () { if (done) return; done = true; resolve(null); }, 3000);
+      });
+    } else {
+      return Promise.resolve(null); // proxy mode has no point-to-point ack
+    }
+
+    self._pingInFlight = promise;
+    promise.then(function () { self._pingInFlight = null; }, function () { self._pingInFlight = null; });
+    return promise;
+  };
+
+  /** Latest smoothed round-trip time in ms (null until first ping). */
+  game.getRtt = function () { return this._pingMeter ? this._pingMeter.rtt : null; };
+}

package/src/modules/game-proxy.js

@@ -2,6 +2,8 @@
  * Usion SDK Game Proxy — postMessage relay through parent app
  */
 
+import { isTrustedMessageSource } from './core.js';
+
 /**
  * Add proxy connection methods to game module
  * @param {object} game - The game module object
@@ -58,6 +60,8 @@ export function applyGameProxy(game, Usion) {
     self._proxyListenerSetup = true;
 
     window.addEventListener('message', function(event) {
+      if (!isTrustedMessageSource(event)) return;
+
       var data;
       try {
         data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;

package/src/modules/game-socket.js

@@ -40,6 +40,10 @@ export function applyGameSocket(game, Usion) {
         reconnectionDelayMax: 10000
       });
 
+      // Route allow-listed backend server events (lobby, etc.) to the unified
+      // backend channel — robust to listener registration order.
+      if (Usion._bindBackendSocket) Usion._bindBackendSocket(self.socket);
+
       self.socket.on('connect', function() {
         self.connected = true;
         self._connecting = false;

package/src/modules/index.js

@@ -25,6 +25,11 @@ import { uiMethods } from './ui.js';
 import { miscMethods } from './misc.js';
 import { createFileStorageModule } from './file-storage.js';
 import { createGameModule } from './game-core.js';
+import { createLobbyModule } from './lobby.js';
+import { createLeaderboardModule } from './leaderboard.js';
+import { createMatchmakingModule } from './matchmaking.js';
+import { applyBackendChannel } from './backend-channel.js';
+import { netcode } from './netcode/index.js';
 
 // Build the Usion object from core
 const Usion = Object.assign({}, core);
@@ -38,6 +43,14 @@ Usion.chat = createChatModule(Usion);
 Usion.bot = createBotModule(Usion);
 Usion.fileStorage = createFileStorageModule(Usion);
 Usion.game = createGameModule(Usion);
+// Unified backend channel (used by lobby etc.; works standalone + embedded).
+applyBackendChannel(Usion);
+Usion.lobby = createLobbyModule(Usion);
+Usion.leaderboard = createLeaderboardModule(Usion);
+Usion.matchmaking = createMatchmakingModule(Usion);
+
+// Netcode toolkit (transport-agnostic, zero-dependency).
+Usion.netcode = netcode;
 
 // Attach results methods directly on Usion
 Object.assign(Usion, createResultsMethods(Usion));

package/src/modules/leaderboard.js

@@ -0,0 +1,46 @@
+/**
+ * Usion SDK Leaderboard — scores for mini-games.
+ *
+ * Opt-in per game (the service must have `leaderboard.enabled`). Rides the
+ * unified backend channel, so it works in standalone AND embedded games.
+ *
+ *   await Usion.leaderboard.submit(1500);              // your score
+ *   const friends = await Usion.leaderboard.friends();  // people you've messaged + you
+ *   const top = await Usion.leaderboard.top();          // global top N
+ *   const me = await Usion.leaderboard.me();            // { score, rank, total }
+ *
+ * The **friends** board is scoped to users you've messaged (your conversations)
+ * plus yourself — that's the "see the scores of people I've chatted with" view.
+ * Entries: { user_id, name, avatar, score, rank, is_me, metadata }.
+ */
+export function createLeaderboardModule(Usion) {
+  function serviceId(opts) {
+    return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+  }
+
+  return {
+    /** Submit a score (best score is kept, per the service's order config). */
+    submit: function (score, metadata, opts) {
+      return Usion._backendEmit('lb:submit', { service_id: serviceId(opts), score: score, metadata: metadata != null ? metadata : null });
+    },
+
+    /** Leaderboard of people you've messaged (plus you). Returns entries[]. */
+    friends: function (opts) {
+      opts = opts || {};
+      return Usion._backendEmit('lb:friends', { service_id: serviceId(opts), limit: opts.limit || 50 })
+        .then(function (r) { return (r && r.entries) || []; });
+    },
+
+    /** Global top N. Returns entries[]. */
+    top: function (opts) {
+      opts = opts || {};
+      return Usion._backendEmit('lb:top', { service_id: serviceId(opts), limit: opts.limit || 20 })
+        .then(function (r) { return (r && r.entries) || []; });
+    },
+
+    /** Your own score + global rank: { score, rank, total }. */
+    me: function (opts) {
+      return Usion._backendEmit('lb:me', { service_id: serviceId(opts) });
+    },
+  };
+}

package/src/modules/lobby.js

@@ -0,0 +1,103 @@
+/**
+ * Usion SDK Lobby — parties, ready-up, and matchmaking.
+ *
+ * The social rendezvous layer that game rooms can't provide: form a party by
+ * code, ready up together, and start as a group — plus a thin wrapper over the
+ * platform's stranger matchmaking. Rides the platform Socket.IO connection
+ * (Usion.game.socket), so connect first with Usion.game.connect().
+ *
+ *   const { code } = await Usion.lobby.create({ maxPlayers: 4 });
+ *   Usion.lobby.onUpdate(({ members }) => renderLobby(members));
+ *   await Usion.lobby.setReady(true);
+ *   // host, once everyone's ready: create a room then start the party in it
+ *   const room = await Usion.lobby.queue(serviceId);     // or your own room API
+ *   await Usion.lobby.start(room.id);
+ *   Usion.lobby.onStarted(({ room_id }) => Usion.game.join(room_id));
+ *
+ * Works in every mode: it rides the unified backend channel (Usion._backendEmit
+ * / _backendOn), which uses the SDK's own socket when standalone and relays
+ * through the parent app when embedded (iframe/WebView).
+ */
+export function createLobbyModule(Usion) {
+  const state = { code: null, host: null, status: null, members: [] };
+  const handlers = {};
+  let bound = false;
+
+  function bind() {
+    if (bound) return;
+    bound = true;
+    Usion._backendOn('lobby:update', function (d) {
+      state.code = d.code; state.host = d.host; state.status = d.status; state.members = d.members || [];
+      if (handlers.update) handlers.update(d);
+    });
+    Usion._backendOn('lobby:started', function (d) {
+      state.status = 'started';
+      if (handlers.started) handlers.started(d);
+    });
+  }
+
+  function ack(event, data) {
+    bind();
+    return Usion._backendEmit(event, data);
+  }
+
+  return {
+    get state() { return state; },
+
+    /** Register a handler for lobby membership/ready changes. */
+    onUpdate: function (cb) { handlers.update = cb; bind(); },
+    /** Register a handler for when the host starts the party. */
+    onStarted: function (cb) { handlers.started = cb; bind(); },
+
+    /** Create a party. Resolves with { code }. You become the host. */
+    create: async function (opts) {
+      opts = opts || {};
+      const r = await ack('lobby:create', { max_players: opts.maxPlayers || 8, public: !!opts.public });
+      if (r && r.code) state.code = r.code;
+      return r;
+    },
+
+    /** Join a party by code. */
+    join: async function (code) {
+      const r = await ack('lobby:join', { code: String(code || '').toUpperCase() });
+      if (r && r.code) state.code = r.code;
+      return r;
+    },
+
+    /** Leave the current party. */
+    leave: function () { state.code = null; return ack('lobby:leave', {}).catch(function () {}); },
+
+    /** Set your ready state. */
+    setReady: function (ready) { return ack('lobby:ready', { ready: ready !== false }); },
+
+    /** True when every member is ready. */
+    allReady: function () { return state.members.length > 0 && state.members.every(function (m) { return m.ready; }); },
+
+    /** Whether the current user is the party host. */
+    isHost: function () {
+      const id = Usion.user && Usion.user.getId && Usion.user.getId();
+      return !!(state.host && id && state.host === id);
+    },
+
+    /** Host: start the party in an already-created game room. */
+    start: function (roomId) { return ack('lobby:start', { room_id: roomId }); },
+
+    /**
+     * Stranger matchmaking — find or create a game room for a service via the
+     * platform's REST matchmaker. Resolves with the room.
+     */
+    queue: async function (serviceId, opts) {
+      opts = opts || {};
+      const apiUrl = (Usion.config && Usion.config.apiUrl) || '';
+      const token = Usion.user && Usion.user.getToken && Usion.user.getToken();
+      if (!apiUrl) throw new Error('No apiUrl configured');
+      const res = await fetch(apiUrl.replace(/\/$/, '') + '/games/matchmake', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token },
+        body: JSON.stringify({ service_id: serviceId, conversation_id: opts.conversationId || ('standalone_' + serviceId) }),
+      });
+      if (!res.ok) throw new Error('Matchmake failed: HTTP ' + res.status);
+      return res.json();
+    },
+  };
+}

package/src/modules/matchmaking.js

@@ -0,0 +1,61 @@
+/**
+ * Usion SDK Matchmaking — pair up with online strangers ("quick match").
+ *
+ * Lets a mini-app connect players who don't know each other: join a queue, and
+ * when enough players are waiting the platform creates a room and matches you.
+ * Rides the unified backend channel, so it works standalone AND embedded.
+ *
+ *   const m = await Usion.matchmaking.find();    // resolves when matched
+ *   await Usion.game.connect(); await Usion.game.join(m.roomId);
+ *   // ...or cancel while waiting:
+ *   Usion.matchmaking.cancel();
+ *   Usion.matchmaking.onMatch(({ roomId, players }) => { ... });
+ */
+export function createMatchmakingModule(Usion) {
+  let pending = null;          // { resolve, reject } for an in-flight find()
+  let onMatchCb = null;
+  let bound = false;
+
+  function normalize(d) {
+    return { roomId: d && d.room_id, players: (d && d.player_ids) || [], serviceId: d && d.service_id };
+  }
+
+  function bind() {
+    if (bound) return;
+    bound = true;
+    Usion._backendOn('mm:matched', function (d) {
+      const r = normalize(d);
+      if (onMatchCb) onMatchCb(r);
+      if (pending) { const p = pending; pending = null; p.resolve(r); }
+    });
+  }
+
+  return {
+    /** Register a handler called whenever a match is found. */
+    onMatch: function (cb) { onMatchCb = cb; bind(); },
+
+    /**
+     * Join the queue for `serviceId` (defaults to the current game) and resolve
+     * when matched with { roomId, players, serviceId }. Stays pending until a
+     * match (use cancel() to stop waiting).
+     */
+    find: function (serviceId, opts) {
+      opts = opts || {};
+      const sid = serviceId || (Usion.config && Usion.config.serviceId);
+      bind();
+      const self = this;
+      return Usion._backendEmit('mm:join', { service_id: sid, size: opts.size || 2 }).then(function () {
+        return new Promise(function (resolve, reject) {
+          if (pending) pending.reject(new Error('superseded'));
+          pending = { resolve: resolve, reject: reject };
+        });
+      });
+    },
+
+    /** Leave the queue / stop waiting. */
+    cancel: function () {
+      if (pending) { pending.reject(new Error('cancelled')); pending = null; }
+      return Usion._backendEmit('mm:cancel', {});
+    },
+  };
+}

package/src/modules/misc.js

@@ -2,6 +2,8 @@
  * Usion SDK Misc — submit, error, exit, share, log, on, requestPayment (legacy)
  */
 
+import { isTrustedMessageSource } from './core.js';
+
 export const miscMethods = {
   /**
    * Request payment from user (legacy method)
@@ -108,6 +110,8 @@ export const miscMethods = {
    */
   on: function(type, callback) {
     window.addEventListener('message', function(event) {
+      if (!isTrustedMessageSource(event)) return;
+
       let data;
       try {
         data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;