@usions/sdk 2.19.0 → 2.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.19.0",
+  "version": "2.20.1",
   "description": "Usion Mini App SDK for iframe games and services",
   "type": "module",
   "main": "src/modules/index.js",

package/src/browser.js

@@ -69,7 +69,7 @@ var Usion = (function () {
    * Core Usion object with init, _post, _request
    */
   const core = {
-    version: '2.19.0', // injected from package.json at build
+    version: '2.20.1', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -190,6 +190,27 @@ var Usion = (function () {
           const h = self._backendHandlers[data.event];
           if (h) h(data.data);
         }
+
+        // Handle a room assigned by the host AFTER launch — the solo→host
+        // promotion path. The user opened the game solo from Explore (launch
+        // mode 'single'), then shared it; the host created a room and tells us
+        // to adopt it so invitees connect to the SAME room and the host starts
+        // receiving onPlayerJoined. No-op when there is no game module.
+        if (data.type === 'GAME_ROOM_ASSIGNED' && data.roomId && self.game) {
+          var _assignedRoom = data.roomId;
+          // Reflect the new room in launch config so getLaunchParams().roomId,
+          // .mode and game.isMultiplayer() all report multiplayer from here on.
+          self.config.roomId = _assignedRoom;
+          self.config.mode = 'multiplayer';
+          // Let a solo game flip to its multiplayer UI before peers arrive.
+          self.game._dispatch('roomAssigned', { roomId: _assignedRoom });
+          // Connect + join so the host is actually in the room. Idempotent when
+          // already connected/joined; non-fatal on failure (the game can retry).
+          Promise.resolve()
+            .then(function() { return self.game.connect(); })
+            .then(function() { return self.game.join(_assignedRoom); })
+            .catch(function() { /* non-fatal */ });
+        }
       });
 
       // Report the user's first real interaction to the host (see below).
@@ -4615,6 +4636,7 @@ var Usion = (function () {
     disconnect: 'disconnect',
     reconnect: 'reconnect',
     connection_error: 'connectionError',
+    room_assigned: 'roomAssigned',
   };
 
   function _normalizeEventName(event) {
@@ -4760,6 +4782,11 @@ var Usion = (function () {
       onReconnect: function(callback) { return this._setHandler('reconnect', callback); },
       onConnectionError: function(callback) { return this._setHandler('connectionError', callback); },
       onPlayerConnection: function(callback) { return this._setHandler('playerConnection', callback); },
+      // Fired when the host assigns this app a room AFTER launch (the user opened
+      // the game solo, then shared it — see GAME_ROOM_ASSIGNED). The SDK has
+      // already updated config.roomId and is connecting+joining; use this to flip
+      // a solo game into its multiplayer/hosting UI. onJoined fires right after.
+      onRoomAssigned: function(callback) { return this._setHandler('roomAssigned', callback); },
 
       /** @private Set the single legacy handler; returns an unsubscribe fn. */
       _setHandler: function(name, callback) {
@@ -4824,6 +4851,24 @@ var Usion = (function () {
     applyGameMethods(game, Usion);
     applyGameNetcode(game, Usion);
 
+    // Foreground catch-up safety net (generic across every transport).
+    //
+    // When a page/iframe is backgrounded its JS is suspended: timers freeze and
+    // relayed actions can be missed (postMessage to a frozen WebView). A brief
+    // app-switch may also never trip a socket disconnect/reconnect, so the game's
+    // onReconnect handler never fires and it silently misses moves made while it
+    // was away — leaving turn state behind and the table deadlocked. On every
+    // return to visibility, if we're in a room, request a sync so the game
+    // deterministically catches up. Per the action reliability contract, onSync
+    // is deduped by sequence, so an unnecessary resync is a no-op.
+    if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+      document.addEventListener('visibilitychange', function() {
+        if (document.visibilityState !== 'visible') return;
+        if (!game.roomId) return;
+        try { game.requestSync(); } catch (e) { /* non-fatal */ }
+      });
+    }
+
     return game;
   }
 

package/src/modules/core.js

@@ -187,6 +187,27 @@ export const core = {
         const h = self._backendHandlers[data.event];
         if (h) h(data.data);
       }
+
+      // Handle a room assigned by the host AFTER launch — the solo→host
+      // promotion path. The user opened the game solo from Explore (launch
+      // mode 'single'), then shared it; the host created a room and tells us
+      // to adopt it so invitees connect to the SAME room and the host starts
+      // receiving onPlayerJoined. No-op when there is no game module.
+      if (data.type === 'GAME_ROOM_ASSIGNED' && data.roomId && self.game) {
+        var _assignedRoom = data.roomId;
+        // Reflect the new room in launch config so getLaunchParams().roomId,
+        // .mode and game.isMultiplayer() all report multiplayer from here on.
+        self.config.roomId = _assignedRoom;
+        self.config.mode = 'multiplayer';
+        // Let a solo game flip to its multiplayer UI before peers arrive.
+        self.game._dispatch('roomAssigned', { roomId: _assignedRoom });
+        // Connect + join so the host is actually in the room. Idempotent when
+        // already connected/joined; non-fatal on failure (the game can retry).
+        Promise.resolve()
+          .then(function() { return self.game.connect(); })
+          .then(function() { return self.game.join(_assignedRoom); })
+          .catch(function() { /* non-fatal */ });
+      }
     });
 
     // Report the user's first real interaction to the host (see below).

package/src/modules/game-core.js

@@ -27,6 +27,7 @@ const _EVENT_ALIASES = {
   disconnect: 'disconnect',
   reconnect: 'reconnect',
   connection_error: 'connectionError',
+  room_assigned: 'roomAssigned',
 };
 
 function _normalizeEventName(event) {
@@ -172,6 +173,11 @@ export function createGameModule(Usion) {
     onReconnect: function(callback) { return this._setHandler('reconnect', callback); },
     onConnectionError: function(callback) { return this._setHandler('connectionError', callback); },
     onPlayerConnection: function(callback) { return this._setHandler('playerConnection', callback); },
+    // Fired when the host assigns this app a room AFTER launch (the user opened
+    // the game solo, then shared it — see GAME_ROOM_ASSIGNED). The SDK has
+    // already updated config.roomId and is connecting+joining; use this to flip
+    // a solo game into its multiplayer/hosting UI. onJoined fires right after.
+    onRoomAssigned: function(callback) { return this._setHandler('roomAssigned', callback); },
 
     /** @private Set the single legacy handler; returns an unsubscribe fn. */
     _setHandler: function(name, callback) {
@@ -236,5 +242,23 @@ export function createGameModule(Usion) {
   applyGameMethods(game, Usion);
   applyGameNetcode(game, Usion);
 
+  // Foreground catch-up safety net (generic across every transport).
+  //
+  // When a page/iframe is backgrounded its JS is suspended: timers freeze and
+  // relayed actions can be missed (postMessage to a frozen WebView). A brief
+  // app-switch may also never trip a socket disconnect/reconnect, so the game's
+  // onReconnect handler never fires and it silently misses moves made while it
+  // was away — leaving turn state behind and the table deadlocked. On every
+  // return to visibility, if we're in a room, request a sync so the game
+  // deterministically catches up. Per the action reliability contract, onSync
+  // is deduped by sequence, so an unnecessary resync is a no-op.
+  if (typeof document !== 'undefined' && typeof document.addEventListener === 'function') {
+    document.addEventListener('visibilitychange', function() {
+      if (document.visibilityState !== 'visible') return;
+      if (!game.roomId) return;
+      try { game.requestSync(); } catch (e) { /* non-fatal */ }
+    });
+  }
+
   return game;
 }

package/types/index.d.ts

@@ -355,6 +355,15 @@ export interface GameModule {
   onConnectionError(callback: (error: Error) => void): UnsubscribeFn;
   /** Peer connection lifecycle: connected / reconnecting (grace) / gone. */
   onPlayerConnection(callback: (data: PlayerConnectionData) => void): UnsubscribeFn;
+  /**
+   * Fired when the host assigns this app a room AFTER launch — the solo→host
+   * promotion path. The user opened the game solo (launch mode 'single'), then
+   * shared it from the host's top-bar Share button; the host created a room and
+   * the SDK has already updated `getLaunchParams().roomId`/`.mode` and is
+   * connecting+joining. Use this to flip a solo game into its multiplayer /
+   * hosting UI; `onJoined` fires right after the join completes.
+   */
+  onRoomAssigned(callback: (data: { roomId: string }) => void): UnsubscribeFn;
 
   /**
    * Register an ADDITIONAL event listener. Unlike the onX methods this