@usions/sdk 2.20.0 → 2.20.2

package/README.md

@@ -139,10 +139,11 @@ follow four rules so both screens always agree:
    actions automatically. Use `onPlayerConnection` for the opponent's status;
    don't end the match on `'reconnecting'` (a ~15s grace window applies),
    treat `'gone'` as the opponent having left.
-4. **Authority checkpoints with `setState`** — the room authority
-   (`player_ids[0]`) should checkpoint at meaningful transitions so a
-   rejoining client restores instantly (delivered as `game_state` in the
-   join result and `onSync`; max 64 KB):
+4. **Checkpoint with `setState`** — any participant (not just the host)
+   should checkpoint at meaningful transitions so a rejoining client restores
+   instantly (delivered as `game_state` in the join result and `onSync`; max
+   64 KB). Letting whoever made the move persist state keeps the snapshot
+   fresh even while the host is backgrounded:
    ```javascript
    await Usion.game.setState(fullGameState)
    ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.20.0",
+  "version": "2.20.2",
   "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.20.0', // injected from package.json at build
+    version: '2.20.2', // injected from package.json at build
     config: {},
     _initialized: false,
     _initCallback: null,
@@ -2220,7 +2220,10 @@ var Usion = (function () {
      * in the join ack and in game:sync — recovery becomes "load checkpoint,
      * replay the tail" instead of replaying every action from zero.
      *
-     * Only the room authority (player_ids[0] / host) may call this. The
+     * Any participant in the room may call this (not just the host) — the
+     * server only requires that you're in player_ids. This keeps the snapshot
+     * fresh even while the host is backgrounded; the host-authority pattern
+     * (only the host calls setState) still works for games that prefer it. The
      * serialized state is capped at 64 KB.
      *
      * @param {*} state - JSON-serializable authoritative game state
@@ -4851,6 +4854,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/game-core.js

@@ -242,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/src/modules/game-methods.js

@@ -248,7 +248,10 @@ export function applyGameMethods(game, Usion) {
    * in the join ack and in game:sync — recovery becomes "load checkpoint,
    * replay the tail" instead of replaying every action from zero.
    *
-   * Only the room authority (player_ids[0] / host) may call this. The
+   * Any participant in the room may call this (not just the host) — the
+   * server only requires that you're in player_ids. This keeps the snapshot
+   * fresh even while the host is backgrounded; the host-authority pattern
+   * (only the host calls setState) still works for games that prefer it. The
    * serialized state is capped at 64 KB.
    *
    * @param {*} state - JSON-serializable authoritative game state

package/types/index.d.ts

@@ -300,8 +300,9 @@ export interface GameModule {
   //   pause input and show a "reconnecting" indicator.
   // - For turn-based games, pass { nextTurn } on each move and trust
   //   current_turn from join/sync instead of deriving the turn locally.
-  // - The room authority (player_ids[0]) should checkpoint via setState()
-  //   at meaningful transitions so rejoining clients can restore instantly.
+  // - Any participant should checkpoint via setState() at meaningful
+  //   transitions so rejoining clients can restore instantly (the host
+  //   need not be the one to call it).
   join(roomId?: string): Promise<GameJoinResult>;
   leave(): void;
   action(actionType: string, actionData?: Record<string, any>, opts?: GameActionOptions): Promise<ActionResult>;
@@ -322,9 +323,11 @@ export interface GameModule {
   invite(opts?: GameInviteOptions): Promise<GameInviteResult>;
 
   /**
-   * Checkpoint authoritative game state on the server (authority only —
-   * player_ids[0]/host). (Re)joining clients receive the latest checkpoint
-   * as game_state in the join ack and in game:sync. Max 64 KB serialized.
+   * Checkpoint authoritative game state on the server. Any participant in the
+   * room may call this (not just player_ids[0]/host), so the snapshot stays
+   * fresh even while the host is backgrounded. (Re)joining clients receive the
+   * latest checkpoint as game_state in the join ack and in game:sync. Max 64 KB
+   * serialized.
    */
   setState(state: Record<string, any>): Promise<{ success: boolean; error?: string; code?: UsionErrorCode }>;