@phalanx-engine/client 0.1.0

package/dist/recovery/GuestPlayerIdStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuestPlayerIdStore.d.ts","sourceRoot":"","sources":["../../src/recovery/GuestPlayerIdStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAUpF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,eAA0C,GAClD,MAAM,CAMR"}

package/dist/recovery/GuestPlayerIdStore.js

@@ -0,0 +1,31 @@
+import { defaultKeyValueStorage } from './KeyValueStorage.js';
+/**
+ * Generate a fresh anonymous player id. Format mirrors the legacy
+ * `player-${ts}-${slug}` shape so server logs stay easy to read.
+ */
+function generateGuestPlayerId() {
+    return `player-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+}
+/**
+ * Load (or generate-and-persist) a stable guest player id.
+ *
+ * `PhalanxClient` generates a fresh id in its constructor when none is
+ * supplied — that id changes on every page reload, which silently
+ * breaks any server-side state keyed by playerId, most importantly the
+ * host record inside a private room. Persisting the guest id in
+ * localStorage lets cold-start recovery succeed for unauthenticated
+ * users.
+ *
+ * Falls back to an in-memory id when storage is unavailable (Safari
+ * private mode etc.) — recovery won't work in that environment, but
+ * regular play still does.
+ */
+export function loadOrCreateGuestPlayerId(storageKey, storage = defaultKeyValueStorage()) {
+    const existing = storage.getItem(storageKey);
+    if (existing && existing.length > 0)
+        return existing;
+    const fresh = generateGuestPlayerId();
+    storage.setItem(storageKey, fresh);
+    return fresh;
+}
+//# sourceMappingURL=GuestPlayerIdStore.js.map

package/dist/recovery/GuestPlayerIdStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GuestPlayerIdStore.js","sourceRoot":"","sources":["../../src/recovery/GuestPlayerIdStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAwB,MAAM,sBAAsB,CAAC;AAEpF;;;GAGG;AACH,SAAS,qBAAqB;IAC5B,OAAO,UAAU,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAAkB,EAClB,UAA2B,sBAAsB,EAAE;IAEnD,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7C,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IACrD,MAAM,KAAK,GAAG,qBAAqB,EAAE,CAAC;IACtC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACnC,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/recovery/KeyValueStorage.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Minimal sync key/value storage abstraction. `localStorage` is the
+ * default implementation; React Native / Capacitor / Electron host
+ * apps can plug in their own adapter (e.g. wrapping `Preferences`)
+ * without dragging in an async API surface.
+ */
+export interface KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * `localStorage`-backed adapter that swallows access errors (Safari
+ * private mode throws on `setItem`, some embedded WebViews disable
+ * storage entirely). Returns null when storage is unavailable so the
+ * caller can fall back gracefully.
+ */
+export declare class LocalStorageAdapter implements KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** In-memory fallback used in non-DOM environments and tests. */
+export declare class MemoryKeyValueStorage implements KeyValueStorage {
+    private readonly map;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Pick the best default storage for the current environment. */
+export declare function defaultKeyValueStorage(): KeyValueStorage;
+//# sourceMappingURL=KeyValueStorage.d.ts.map

package/dist/recovery/KeyValueStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyValueStorage.d.ts","sourceRoot":"","sources":["../../src/recovery/KeyValueStorage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IASnC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IASzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAQ9B;AAED,iEAAiE;AACjE,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IAEjD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAG9B;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,eAAe,CAGxD"}

package/dist/recovery/KeyValueStorage.js

@@ -0,0 +1,58 @@
+/**
+ * `localStorage`-backed adapter that swallows access errors (Safari
+ * private mode throws on `setItem`, some embedded WebViews disable
+ * storage entirely). Returns null when storage is unavailable so the
+ * caller can fall back gracefully.
+ */
+export class LocalStorageAdapter {
+    getItem(key) {
+        try {
+            if (typeof localStorage === 'undefined')
+                return null;
+            return localStorage.getItem(key);
+        }
+        catch {
+            return null;
+        }
+    }
+    setItem(key, value) {
+        try {
+            if (typeof localStorage === 'undefined')
+                return;
+            localStorage.setItem(key, value);
+        }
+        catch {
+            // ignore — persistence is best-effort
+        }
+    }
+    removeItem(key) {
+        try {
+            if (typeof localStorage === 'undefined')
+                return;
+            localStorage.removeItem(key);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/** In-memory fallback used in non-DOM environments and tests. */
+export class MemoryKeyValueStorage {
+    map = new Map();
+    getItem(key) {
+        return this.map.has(key) ? this.map.get(key) : null;
+    }
+    setItem(key, value) {
+        this.map.set(key, value);
+    }
+    removeItem(key) {
+        this.map.delete(key);
+    }
+}
+/** Pick the best default storage for the current environment. */
+export function defaultKeyValueStorage() {
+    if (typeof localStorage !== 'undefined')
+        return new LocalStorageAdapter();
+    return new MemoryKeyValueStorage();
+}
+//# sourceMappingURL=KeyValueStorage.js.map

package/dist/recovery/KeyValueStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyValueStorage.js","sourceRoot":"","sources":["../../src/recovery/KeyValueStorage.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IAC9B,OAAO,CAAC,GAAW;QACjB,IAAI,CAAC;YACH,IAAI,OAAO,YAAY,KAAK,WAAW;gBAAE,OAAO,IAAI,CAAC;YACrD,OAAO,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAW,EAAE,KAAa;QAChC,IAAI,CAAC;YACH,IAAI,OAAO,YAAY,KAAK,WAAW;gBAAE,OAAO;YAChD,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,sCAAsC;QACxC,CAAC;IACH,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,IAAI,CAAC;YACH,IAAI,OAAO,YAAY,KAAK,WAAW;gBAAE,OAAO;YAChD,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,OAAO,qBAAqB;IACf,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEjD,OAAO,CAAC,GAAW;QACjB,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACvD,CAAC;IAED,OAAO,CAAC,GAAW,EAAE,KAAa;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,UAAU,sBAAsB;IACpC,IAAI,OAAO,YAAY,KAAK,WAAW;QAAE,OAAO,IAAI,mBAAmB,EAAE,CAAC;IAC1E,OAAO,IAAI,qBAAqB,EAAE,CAAC;AACrC,CAAC"}

package/dist/recovery/MobileTransport.d.ts

@@ -0,0 +1,12 @@
+import type { SocketTransport } from '../types.js';
+/**
+ * Best-effort mobile-browser sniffing. Used by `PhalanxClient` to
+ * default `socketTransports` to polling when `mobileFriendlyTransports`
+ * is opted into — Telegram WebView / iOS Safari on carrier networks
+ * frequently establish a websocket and then silently stop delivering
+ * packets, while polling reconnects transparently.
+ */
+export declare function isMobileBrowser(): boolean;
+/** Resolve the auto-defaulted transport list for the current UA. */
+export declare function pickMobileFriendlyTransports(): readonly SocketTransport[];
+//# sourceMappingURL=MobileTransport.d.ts.map

package/dist/recovery/MobileTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MobileTransport.d.ts","sourceRoot":"","sources":["../../src/recovery/MobileTransport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAUzC;AAKD,oEAAoE;AACpE,wBAAgB,4BAA4B,IAAI,SAAS,eAAe,EAAE,CAEzE"}

package/dist/recovery/MobileTransport.js

@@ -0,0 +1,24 @@
+/**
+ * Best-effort mobile-browser sniffing. Used by `PhalanxClient` to
+ * default `socketTransports` to polling when `mobileFriendlyTransports`
+ * is opted into — Telegram WebView / iOS Safari on carrier networks
+ * frequently establish a websocket and then silently stop delivering
+ * packets, while polling reconnects transparently.
+ */
+export function isMobileBrowser() {
+    if (typeof navigator === 'undefined')
+        return false;
+    const userAgent = navigator.userAgent;
+    const platform = navigator.platform;
+    const hasTouchScreen = navigator.maxTouchPoints > 1;
+    const isIpadOS = platform === 'MacIntel' && hasTouchScreen;
+    return (isIpadOS ||
+        /Android|iPhone|iPad|iPod|IEMobile|Opera Mini|Mobile/i.test(userAgent));
+}
+const DESKTOP_TRANSPORTS = ['websocket'];
+const MOBILE_TRANSPORTS = ['polling'];
+/** Resolve the auto-defaulted transport list for the current UA. */
+export function pickMobileFriendlyTransports() {
+    return isMobileBrowser() ? MOBILE_TRANSPORTS : DESKTOP_TRANSPORTS;
+}
+//# sourceMappingURL=MobileTransport.js.map

package/dist/recovery/MobileTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MobileTransport.js","sourceRoot":"","sources":["../../src/recovery/MobileTransport.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,eAAe;IAC7B,IAAI,OAAO,SAAS,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IACnD,MAAM,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC;IACtC,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC;IACpC,MAAM,cAAc,GAAG,SAAS,CAAC,cAAc,GAAG,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,QAAQ,KAAK,UAAU,IAAI,cAAc,CAAC;IAC3D,OAAO,CACL,QAAQ;QACR,sDAAsD,CAAC,IAAI,CAAC,SAAS,CAAC,CACvE,CAAC;AACJ,CAAC;AAED,MAAM,kBAAkB,GAAG,CAAC,WAAW,CAA+C,CAAC;AACvF,MAAM,iBAAiB,GAAG,CAAC,SAAS,CAA+C,CAAC;AAEpF,oEAAoE;AACpE,MAAM,UAAU,4BAA4B;IAC1C,OAAO,eAAe,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,CAAC;AACpE,CAAC"}

package/dist/recovery/NetworkQuality.d.ts

@@ -0,0 +1,22 @@
+/**
+ * NetworkQuality — read `navigator.connection` (when available) to pick
+ * a sensible recover-room request timeout. Mobile carrier networks can
+ * legitimately take 15+ seconds to deliver an ack on slow-2g, so a
+ * fixed 10s timeout would prematurely fail recovery on real mobile.
+ */
+export interface RecoverTimeoutBudget {
+    /** Default timeout when the network looks healthy. */
+    defaultMs: number;
+    /** Used for 3g / 300+ms RTT. */
+    degradedMs: number;
+    /** Used for slow-2g / 2g / 600+ms RTT. */
+    slowMs: number;
+}
+export declare const DEFAULT_RECOVER_TIMEOUT_BUDGET: RecoverTimeoutBudget;
+/**
+ * Pick a recover-room ack timeout for the current network quality.
+ * Returns `budget.defaultMs` when no `navigator.connection` data is
+ * available (older Safari, non-DOM environments, …).
+ */
+export declare function getRecoverTimeoutMs(budget?: RecoverTimeoutBudget): number;
+//# sourceMappingURL=NetworkQuality.d.ts.map

package/dist/recovery/NetworkQuality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkQuality.d.ts","sourceRoot":"","sources":["../../src/recovery/NetworkQuality.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,8BAA8B,EAAE,oBAI5C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,GAAE,oBAAqD,GAC5D,MAAM,CAqBR"}

package/dist/recovery/NetworkQuality.js

@@ -0,0 +1,35 @@
+/**
+ * NetworkQuality — read `navigator.connection` (when available) to pick
+ * a sensible recover-room request timeout. Mobile carrier networks can
+ * legitimately take 15+ seconds to deliver an ack on slow-2g, so a
+ * fixed 10s timeout would prematurely fail recovery on real mobile.
+ */
+export const DEFAULT_RECOVER_TIMEOUT_BUDGET = {
+    defaultMs: 10_000,
+    degradedMs: 15_000,
+    slowMs: 25_000,
+};
+/**
+ * Pick a recover-room ack timeout for the current network quality.
+ * Returns `budget.defaultMs` when no `navigator.connection` data is
+ * available (older Safari, non-DOM environments, …).
+ */
+export function getRecoverTimeoutMs(budget = DEFAULT_RECOVER_TIMEOUT_BUDGET) {
+    if (typeof navigator === 'undefined')
+        return budget.defaultMs;
+    const nav = navigator;
+    const connection = nav.connection ?? nav.mozConnection ?? nav.webkitConnection;
+    if (connection?.effectiveType === 'slow-2g' ||
+        connection?.effectiveType === '2g') {
+        return budget.slowMs;
+    }
+    if (typeof connection?.rtt === 'number' && connection.rtt >= 600) {
+        return budget.slowMs;
+    }
+    if (connection?.effectiveType === '3g' ||
+        (typeof connection?.rtt === 'number' && connection.rtt >= 300)) {
+        return budget.degradedMs;
+    }
+    return budget.defaultMs;
+}
+//# sourceMappingURL=NetworkQuality.js.map

package/dist/recovery/NetworkQuality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NetworkQuality.js","sourceRoot":"","sources":["../../src/recovery/NetworkQuality.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsBH,MAAM,CAAC,MAAM,8BAA8B,GAAyB;IAClE,SAAS,EAAE,MAAM;IACjB,UAAU,EAAE,MAAM;IAClB,MAAM,EAAE,MAAM;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA+B,8BAA8B;IAE7D,IAAI,OAAO,SAAS,KAAK,WAAW;QAAE,OAAO,MAAM,CAAC,SAAS,CAAC;IAC9D,MAAM,GAAG,GAAG,SAAoC,CAAC;IACjD,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,aAAa,IAAI,GAAG,CAAC,gBAAgB,CAAC;IAE/E,IACE,UAAU,EAAE,aAAa,KAAK,SAAS;QACvC,UAAU,EAAE,aAAa,KAAK,IAAI,EAClC,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IACD,IAAI,OAAO,UAAU,EAAE,GAAG,KAAK,QAAQ,IAAI,UAAU,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC;QACjE,OAAO,MAAM,CAAC,MAAM,CAAC;IACvB,CAAC;IACD,IACE,UAAU,EAAE,aAAa,KAAK,IAAI;QAClC,CAAC,OAAO,UAAU,EAAE,GAAG,KAAK,QAAQ,IAAI,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,EAC9D,CAAC;QACD,OAAO,MAAM,CAAC,UAAU,CAAC;IAC3B,CAAC;IACD,OAAO,MAAM,CAAC,SAAS,CAAC;AAC1B,CAAC"}

package/dist/recovery/RoomPersistence.d.ts

@@ -0,0 +1,55 @@
+import { type KeyValueStorage } from './KeyValueStorage.js';
+/**
+ * RoomPersistence — survives an active private-room session across:
+ *   - mobile browser backgrounding (where the WebSocket dies but JS
+ *     state is usually preserved by bfcache)
+ *   - hard reloads, as long as the same `playerId` is still available
+ *     after reload (authenticated users always; guests when the
+ *     `GuestPlayerIdStore` is used)
+ *
+ * Stored in `localStorage` by default (NOT `sessionStorage`) so that
+ * iOS Safari, which discards `sessionStorage` when the tab is killed,
+ * still has the entry available the next time the app is opened.
+ *
+ * Recovery is best-effort and bounded by the room TTL: if the stored
+ * room entry has expired, or a true cold start no longer has access to
+ * the previous `playerId`, recovery is not expected to succeed.
+ */
+export type RoomRole = 'host' | 'guest';
+export interface PersistedRoom {
+    readonly code: string;
+    readonly role: RoomRole;
+    readonly playerId: string;
+    readonly createdAt: number;
+    readonly expiresAt: number;
+}
+export interface RoomPersistenceConfig {
+    /** localStorage key. */
+    storageKey: string;
+    /** TTL mirroring the server's RoomService.ROOM_TTL_MS. */
+    roomTtlMs: number;
+    /** Storage adapter; defaults to localStorage. */
+    storage?: KeyValueStorage;
+}
+export declare class RoomPersistence {
+    private readonly config;
+    private readonly storage;
+    constructor(config: RoomPersistenceConfig);
+    /**
+     * Best-effort save. Errors are logged and swallowed — losing the
+     * persistence layer should never break room creation itself.
+     */
+    save(input: {
+        code: string;
+        role: RoomRole;
+        playerId: string;
+    }): void;
+    /**
+     * Returns the stored room if it exists and is still within its TTL.
+     * Auto-evicts an expired entry so subsequent calls don't keep trying
+     * to recover something the server has long since destroyed.
+     */
+    load(): PersistedRoom | null;
+    clear(): void;
+}
+//# sourceMappingURL=RoomPersistence.d.ts.map

package/dist/recovery/RoomPersistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoomPersistence.d.ts","sourceRoot":"","sources":["../../src/recovery/RoomPersistence.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEpF;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAEb,MAAM,EAAE,qBAAqB;IAI1D;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAgBrE;;;;OAIG;IACH,IAAI,IAAI,aAAa,GAAG,IAAI;IA0B5B,KAAK,IAAI,IAAI;CAOd"}

package/dist/recovery/RoomPersistence.js

@@ -0,0 +1,68 @@
+import { defaultKeyValueStorage } from './KeyValueStorage.js';
+export class RoomPersistence {
+    config;
+    storage;
+    constructor(config) {
+        this.config = config;
+        this.storage = config.storage ?? defaultKeyValueStorage();
+    }
+    /**
+     * Best-effort save. Errors are logged and swallowed — losing the
+     * persistence layer should never break room creation itself.
+     */
+    save(input) {
+        try {
+            const now = Date.now();
+            const record = {
+                code: input.code,
+                role: input.role,
+                playerId: input.playerId,
+                createdAt: now,
+                expiresAt: now + this.config.roomTtlMs,
+            };
+            this.storage.setItem(this.config.storageKey, JSON.stringify(record));
+        }
+        catch (err) {
+            console.warn('[RoomPersistence] save failed:', err);
+        }
+    }
+    /**
+     * Returns the stored room if it exists and is still within its TTL.
+     * Auto-evicts an expired entry so subsequent calls don't keep trying
+     * to recover something the server has long since destroyed.
+     */
+    load() {
+        try {
+            const raw = this.storage.getItem(this.config.storageKey);
+            if (!raw)
+                return null;
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.code !== 'string' ||
+                (parsed.role !== 'host' && parsed.role !== 'guest') ||
+                typeof parsed.playerId !== 'string' ||
+                typeof parsed.expiresAt !== 'number' ||
+                typeof parsed.createdAt !== 'number') {
+                this.clear();
+                return null;
+            }
+            if (Date.now() > parsed.expiresAt) {
+                this.clear();
+                return null;
+            }
+            return parsed;
+        }
+        catch (err) {
+            console.warn('[RoomPersistence] load failed:', err);
+            return null;
+        }
+    }
+    clear() {
+        try {
+            this.storage.removeItem(this.config.storageKey);
+        }
+        catch (err) {
+            console.warn('[RoomPersistence] clear failed:', err);
+        }
+    }
+}
+//# sourceMappingURL=RoomPersistence.js.map

package/dist/recovery/RoomPersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoomPersistence.js","sourceRoot":"","sources":["../../src/recovery/RoomPersistence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAwB,MAAM,sBAAsB,CAAC;AAsCpF,MAAM,OAAO,eAAe;IAGG;IAFZ,OAAO,CAAkB;IAE1C,YAA6B,MAA6B;QAA7B,WAAM,GAAN,MAAM,CAAuB;QACxD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,sBAAsB,EAAE,CAAC;IAC5D,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,KAAyD;QAC5D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,MAAM,GAAkB;gBAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,SAAS,EAAE,GAAG;gBACd,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS;aACvC,CAAC;YACF,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QACvE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,gCAAgC,EAAE,GAAG,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACzD,IAAI,CAAC,GAAG;gBAAE,OAAO,IAAI,CAAC;YACtB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;YACzD,IACE,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;gBAC/B,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC;gBACnD,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;gBACnC,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;gBACpC,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,EACpC,CAAC;gBACD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;gBAClC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACb,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,MAAuB,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,gCAAgC,EAAE,GAAG,CAAC,CAAC;YACpD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;CACF"}

package/dist/recovery/RoomRecoveryController.d.ts

@@ -0,0 +1,146 @@
+import { type RecoverTimeoutBudget } from './NetworkQuality.js';
+import type { KeyValueStorage } from './KeyValueStorage.js';
+import type { PhalanxClientEvents, RoomRecoveredEvent, Unsubscribe } from '../types.js';
+/**
+ * Slim port describing the subset of `PhalanxClient` that the
+ * recovery controller actually drives. Defining it here decouples
+ * the controller from the rest of the client surface and keeps unit
+ * testing trivial.
+ */
+export interface RecoveryClientPort {
+    connect(): Promise<void>;
+    disconnect(): void;
+    isConnected(): boolean;
+    recoverRoom(code: string, timeoutMs?: number): Promise<RoomRecoveredEvent>;
+    getPlayerId(): string;
+    on<K extends keyof PhalanxClientEvents>(event: K, handler: PhalanxClientEvents[K]): Unsubscribe;
+}
+/**
+ * Phase emitted via `recoveryStatus` so games can render localized
+ * strings without re-implementing the state machine.
+ */
+export type RoomRecoveryPhase = 'idle' | 'recovering' | 'waiting-network' | 'retrying' | 'gave-up';
+export interface RoomRecoveryStatusEvent {
+    phase: RoomRecoveryPhase;
+    /** Current attempt number (1-based) when phase is 'recovering' / 'retrying'. */
+    attempt?: number;
+    /** Delay until the next automatic retry, in ms (only when phase is 'retrying'). */
+    nextRetryMs?: number;
+}
+export interface RoomTerminatedEvent {
+    reason: 'expired' | 'not-found' | 'cancelled';
+}
+export interface RoomRecoveryControllerEvents {
+    recoveryStatus: (event: RoomRecoveryStatusEvent) => void;
+    roomTerminated: (event: RoomTerminatedEvent) => void;
+}
+export interface RoomRecoveryConfig {
+    /** Storage key for the persisted active-room record. */
+    storageKey: string;
+    /** Local TTL mirroring server RoomService.ROOM_TTL_MS. */
+    roomTtlMs: number;
+    /** Storage adapter for the persistence layer. */
+    storage?: KeyValueStorage;
+    /** Per-quality recover timeouts. */
+    recoverTimeoutBudget?: RecoverTimeoutBudget;
+    /** Max recover attempts before giving up (still leaves the user on screen). */
+    maxRecoverAttempts?: number;
+    /**
+     * Auto-arm a "pre-game stall" watchdog when tracking starts. If the
+     * matchFound→countdown→gameStart sequence stalls longer than
+     * `preGameStallMs` we trigger a `forceRecover` to dodge silent
+     * mid-flow socket failures.
+     * @default true
+     */
+    preGameStallWatchdog?: boolean;
+    /** @default 4500 */
+    preGameStallMs?: number;
+}
+/**
+ * Owns the entire mobile-friendly recovery state machine for a single
+ * private room: visibility/pageshow/online listeners, socket connect/
+ * disconnect hooks, exponential-backoff retry, and the localStorage
+ * persistence record. Emits typed status events instead of touching
+ * UI directly so each game can render its own strings.
+ *
+ * Lifecycle:
+ *   client.roomRecovery.startTrackingHost(code)  // host created room
+ *   client.roomRecovery.trackGuestJoin(code)     // guest is mid-join
+ *   client.roomRecovery.resumeTrackingHost(code) // cold-start recover
+ *   client.roomRecovery.stop()                   // cancel / match started
+ *
+ * The pre-game stall watchdog is auto-armed on every matchFound and
+ * disarmed on gameStart, so games no longer need their own
+ * `armPreGameStallWatchdog` helper.
+ */
+export declare class RoomRecoveryController {
+    private readonly client;
+    private readonly persistence;
+    private readonly recoverBudget;
+    private readonly maxRecoverAttempts;
+    private readonly preGameStallEnabled;
+    private readonly preGameStallMs;
+    private readonly emit;
+    private activeRoomCode;
+    private isRecovering;
+    private pendingRecoverRequested;
+    private pendingForceReconnectRequested;
+    private recoverAttempt;
+    private recoverRetryTimer;
+    private recoverScheduleTimer;
+    private lifecycleHandle;
+    private clientEventUnsubs;
+    private preGameStallTimer;
+    private hasGameStartedSinceTracking;
+    constructor(client: RecoveryClientPort, config: RoomRecoveryConfig, emit: <K extends keyof RoomRecoveryControllerEvents>(event: K, ...args: Parameters<RoomRecoveryControllerEvents[K]>) => void);
+    hasActiveRoom(): boolean;
+    getActiveRoomCode(): string | null;
+    /**
+     * Cold-start recovery: read the persisted host record (mobile killed
+     * the tab while the user was in a messenger) and validate it against
+     * the current playerId. Returns the code to recover, or null when
+     * there's nothing to do (no record, expired, or playerId drift).
+     */
+    loadColdStartCode(): string | null;
+    /** Begin tracking `code` as the active host-side room. */
+    startTrackingHost(code: string): void;
+    /**
+     * Variant used by cold-start recover: assumes the persistence record
+     * was already written by a previous tab and just rearms the hooks.
+     */
+    resumeTrackingHost(code: string): void;
+    /** Persist a guest-side join attempt for cold-start surfacing. */
+    trackGuestJoin(code: string): void;
+    /** Stop all recovery machinery and forget the active room. Idempotent. */
+    stop(): void;
+    /**
+     * Recover through a fresh socket even if Socket.IO still reports the
+     * current one as connected. This handles mobile carrier/WebView
+     * stalls where server→client packets stop arriving but heartbeat has
+     * not fired yet, so the normal `disconnected` hook would be too late.
+     */
+    forceRecover(reason: string): void;
+    /**
+     * Attempt one recovery cycle. Idempotent against concurrent calls
+     * (the visibility and `connected` hooks may fire near-simultaneously
+     * on mobile). Schedules its own backoff retry on transient failure.
+     */
+    tryRecover(): Promise<void>;
+    /**
+     * Arm a one-shot timer: if `gameStart` doesn't arrive within
+     * `preGameStallMs` we proactively `forceRecover` because the most
+     * likely explanation is that the host's socket silently died mid-
+     * countdown. Auto-armed on `matchFound` / `countdown` events when
+     * `preGameStallWatchdog` is enabled — games rarely need to call this
+     * directly.
+     */
+    armPreGameStallWatchdog(reason: string): void;
+    clearPreGameStallWatchdog(): void;
+    private armHooks;
+    private disarmHooks;
+    private armBrowserLifecycle;
+    private armClientEventHooks;
+    private scheduleRecover;
+    private waitForOnlineAndStabilize;
+}
+//# sourceMappingURL=RoomRecoveryController.d.ts.map

package/dist/recovery/RoomRecoveryController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoomRecoveryController.d.ts","sourceRoot":"","sources":["../../src/recovery/RoomRecoveryController.ts"],"names":[],"mappings":"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"}