@unboxy/phaser-sdk 0.2.6 → 0.2.7

package/SDK-GUIDE.md

@@ -314,6 +314,7 @@ Rules of thumb:
 
 ## Changelog
 
+- **0.2.7** — fixed handshake race on slow-mounting hosts. `PostMessageTransport.connect` now retries `unboxy:hello` every 200 ms until `unboxy:init` arrives (previously one-shot → lost on Android/mobile where React mounted after the iframe first fired hello). Default handshake timeout bumped from 2 s → 5 s.
 - **0.2.6** — redesigned `unboxy.rooms` around two generic primitives: delta-synced KV state (`room.player.set/get/delete`, `room.data.set/get/delete`) + transient relay (`room.send` / `room.on`). Server no longer bakes in game-specific fields like x/y/color/ready or a `move` handler — games define their own shapes via opaque JSON values, same contract as `gameData` / `saves`.
 - **0.2.5** — added `unboxy.rooms` module (server-authoritative multiplayer rooms backed by Colyseus on unboxy-realtime-service). Requires sign-in. Host must advertise `realtime` capability. Colyseus client loaded lazily — single-player games do not pay for the dependency.
 - **0.2.4** — added `unboxy.gameData` module (game-scope key-value store for scoreboards, shared state)

package/dist/core/Unboxy.d.ts

@@ -4,7 +4,7 @@ import { GameDataModule } from '../gamedata/GameDataModule.js';
 import { RealtimeModule } from '../realtime/RealtimeModule.js';
 import type { UnboxyUser } from '../protocol.js';
 export interface UnboxyInitOptions {
-    /** Handshake timeout in ms when running inside a host. Default 2000. */
+    /** Handshake timeout in ms when running inside a host. Default 5000. */
     handshakeTimeoutMs?: number;
     /**
      * Game ID used for the localStorage fallback. Ignored when connected to a

package/dist/core/Unboxy.js

@@ -4,7 +4,7 @@ import { SavesModule } from '../saves/SavesModule.js';
 import { GameDataModule } from '../gamedata/GameDataModule.js';
 import { RealtimeModule } from '../realtime/RealtimeModule.js';
 // Kept in sync with package.json on each publish.
-const SDK_VERSION = '0.2.6';
+const SDK_VERSION = '0.2.7';
 /**
  * Unboxy platform services bound to the current (game, user).
  *
@@ -50,7 +50,7 @@ export class Unboxy {
      * Discord Activity support is designed for but not shipped in this version.
      */
     static async init(options = {}) {
-        const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 2000;
+        const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5000;
         const standaloneGameId = options.standaloneGameId ?? 'standalone';
         const pm = await PostMessageTransport.connect(handshakeTimeoutMs, SDK_VERSION);
         if (pm)

package/dist/core/transports/PostMessageTransport.d.ts

@@ -15,9 +15,14 @@ export declare class PostMessageTransport implements Transport {
     private constructor();
     /**
      * Perform the handshake. Resolves once parent has replied with `unboxy:init`.
-     * Rejects if no response within `timeoutMs`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
      */
-    static connect(timeoutMs?: number, sdkVersion?: string): Promise<PostMessageTransport | null>;
+    static connect(timeoutMs?: number, sdkVersion?: string, helloRetryMs?: number): Promise<PostMessageTransport | null>;
     private installResultListener;
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
 }

package/dist/core/transports/PostMessageTransport.js

@@ -15,35 +15,51 @@ export class PostMessageTransport {
     }
     /**
      * Perform the handshake. Resolves once parent has replied with `unboxy:init`.
-     * Rejects if no response within `timeoutMs`.
+     * Resolves to null if no response within `timeoutMs`.
+     *
+     * The hello is retried at `helloRetryMs` intervals because the parent's
+     * RPC-host message listener may not be mounted yet when the iframe first
+     * fires hello — especially on slower mobile devices where React takes
+     * longer to boot. One-shot hello was losing the handshake on Android.
      */
-    static async connect(timeoutMs = 2000, sdkVersion = '0.0.0') {
+    static async connect(timeoutMs = 5000, sdkVersion = '0.0.0', helloRetryMs = 200) {
         if (typeof window === 'undefined' || window.parent === window)
             return null;
         const transport = new PostMessageTransport(window.parent);
-        const initPromise = new Promise((resolve) => {
+        const hello = {
+            type: 'unboxy:hello',
+            protocolVersion: PROTOCOL_VERSION,
+            sdkVersion,
+        };
+        const init = await new Promise((resolve) => {
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                window.removeEventListener('message', onMessage);
+                clearInterval(helloInterval);
+                clearTimeout(timeoutHandle);
+                resolve(value);
+            };
             const onMessage = (event) => {
                 if (event.source !== window.parent)
                     return;
                 const data = event.data;
                 if (!data || data.type !== 'unboxy:init')
                     return;
-                window.removeEventListener('message', onMessage);
-                resolve(data);
+                finish(data);
             };
             window.addEventListener('message', onMessage);
-            setTimeout(() => {
-                window.removeEventListener('message', onMessage);
-                resolve(null);
-            }, timeoutMs);
+            // Fire the first hello immediately, then keep retrying until init
+            // arrives or timeout fires. Retries are cheap (a postMessage with a
+            // small payload); the parent's RPC host replies on first valid hello.
+            transport.parent.postMessage(hello, '*');
+            const helloInterval = setInterval(() => {
+                transport.parent.postMessage(hello, '*');
+            }, helloRetryMs);
+            const timeoutHandle = setTimeout(() => finish(null), timeoutMs);
         });
-        const hello = {
-            type: 'unboxy:hello',
-            protocolVersion: PROTOCOL_VERSION,
-            sdkVersion,
-        };
-        transport.parent.postMessage(hello, '*');
-        const init = await initPromise;
         if (!init)
             return null;
         if (init.protocolVersion !== PROTOCOL_VERSION) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",