@phalanx-engine/client 0.1.0

package/dist/auth/storage.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Phalanx Auth Storage
+ *
+ * Storage interface and implementations for persisting auth data.
+ */
+import type { StoredAuthData } from './types.js';
+/**
+ * Interface for auth data storage.
+ * Implement this interface to provide custom storage (e.g., React Native SecureStore).
+ */
+export interface AuthStorage {
+    /**
+     * Retrieve stored auth data.
+     * @returns Stored data or null if not found
+     */
+    get(): Promise<StoredAuthData | null>;
+    /**
+     * Store auth data.
+     * @param data - Auth data to store
+     */
+    set(data: StoredAuthData): Promise<void>;
+    /**
+     * Clear stored auth data.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Default storage implementation using localStorage.
+ * Suitable for web browsers.
+ *
+ * Note: For production, consider using httpOnly cookies for refresh tokens
+ * or a custom storage implementation with encryption.
+ */
+export declare class LocalStorageAdapter implements AuthStorage {
+    private key;
+    /**
+     * Create a new LocalStorageAdapter.
+     * @param key - Storage key prefix (default: 'phalanx_auth')
+     */
+    constructor(key?: string);
+    get(): Promise<StoredAuthData | null>;
+    set(data: StoredAuthData): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * In-memory storage implementation.
+ * Useful for testing or environments without persistent storage.
+ * Data is lost on page refresh.
+ */
+export declare class MemoryStorageAdapter implements AuthStorage {
+    private data;
+    get(): Promise<StoredAuthData | null>;
+    set(data: StoredAuthData): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/auth/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/auth/storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,GAAG,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEtC;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,GAAG,CAAS;IAEpB;;;OAGG;gBACS,GAAG,GAAE,MAAuB;IAIlC,GAAG,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAYrC,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAM7B;AAMD;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,WAAW;IACtD,OAAO,CAAC,IAAI,CAA+B;IAErC,GAAG,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAIrC,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/auth/storage.js

@@ -0,0 +1,78 @@
+/**
+ * Phalanx Auth Storage
+ *
+ * Storage interface and implementations for persisting auth data.
+ */
+// ============================================
+// LocalStorage Implementation
+// ============================================
+/**
+ * Default storage implementation using localStorage.
+ * Suitable for web browsers.
+ *
+ * Note: For production, consider using httpOnly cookies for refresh tokens
+ * or a custom storage implementation with encryption.
+ */
+export class LocalStorageAdapter {
+    key;
+    /**
+     * Create a new LocalStorageAdapter.
+     * @param key - Storage key prefix (default: 'phalanx_auth')
+     */
+    constructor(key = 'phalanx_auth') {
+        this.key = key;
+    }
+    async get() {
+        try {
+            if (typeof localStorage === 'undefined') {
+                return null;
+            }
+            const data = localStorage.getItem(this.key);
+            return data ? JSON.parse(data) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(data) {
+        if (typeof localStorage === 'undefined') {
+            console.warn('[AuthStorage] localStorage is not available');
+            return;
+        }
+        // Security warning for production
+        if (typeof process !== 'undefined' &&
+            process.env?.NODE_ENV === 'production' &&
+            data.refreshToken) {
+            console.warn('[AuthStorage] Storing refresh token in localStorage is not recommended for production. ' +
+                'Consider using httpOnly cookies or a custom storage implementation.');
+        }
+        localStorage.setItem(this.key, JSON.stringify(data));
+    }
+    async clear() {
+        if (typeof localStorage === 'undefined') {
+            return;
+        }
+        localStorage.removeItem(this.key);
+    }
+}
+// ============================================
+// Memory Storage Implementation
+// ============================================
+/**
+ * In-memory storage implementation.
+ * Useful for testing or environments without persistent storage.
+ * Data is lost on page refresh.
+ */
+export class MemoryStorageAdapter {
+    data = null;
+    async get() {
+        return this.data;
+    }
+    async set(data) {
+        this.data = data;
+    }
+    async clear() {
+        this.data = null;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/auth/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/auth/storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA+BH,+CAA+C;AAC/C,8BAA8B;AAC9B,+CAA+C;AAE/C;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IACtB,GAAG,CAAS;IAEpB;;;OAGG;IACH,YAAY,MAAc,cAAc;QACtC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,GAAG;QACP,IAAI,CAAC;YACH,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5C,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAoB;QAC5B,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;YAC5D,OAAO;QACT,CAAC;QAED,kCAAkC;QAClC,IACE,OAAO,OAAO,KAAK,WAAW;YAC9B,OAAO,CAAC,GAAG,EAAE,QAAQ,KAAK,YAAY;YACtC,IAAI,CAAC,YAAY,EACjB,CAAC;YACD,OAAO,CAAC,IAAI,CACV,yFAAyF;gBACvF,qEAAqE,CACxE,CAAC;QACJ,CAAC;QAED,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;YACxC,OAAO;QACT,CAAC;QACD,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;CACF;AAED,+CAA+C;AAC/C,gCAAgC;AAChC,+CAA+C;AAE/C;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IACvB,IAAI,GAA0B,IAAI,CAAC;IAE3C,KAAK,CAAC,GAAG;QACP,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAoB;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/auth/types.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Phalanx Auth Types
+ *
+ * Type definitions for the managed OAuth authentication system.
+ */
+/**
+ * Interface that all OAuth adapters must implement.
+ * Provides a consistent API for different OAuth providers.
+ */
+export interface AuthAdapter {
+    /** The provider name (e.g., 'google', 'discord', 'steam') */
+    readonly provider: string;
+    /**
+     * Generate the OAuth authorization URL.
+     * User will be redirected to this URL to authenticate.
+     */
+    getLoginUrl(options?: LoginOptions): string;
+    /**
+     * Handle the OAuth callback.
+     * Called when user is redirected back from OAuth provider.
+     */
+    handleCallback(params: CallbackParams): Promise<AuthResult>;
+    /**
+     * Refresh an expired token.
+     * Returns null if refresh is not supported or refresh token is invalid.
+     */
+    refreshToken(refreshToken: string): Promise<AuthResult | null>;
+    /**
+     * Revoke the token (logout from provider).
+     * Optional - not all providers support token revocation.
+     */
+    revokeToken?(token: string): Promise<void>;
+    /**
+     * Check if this adapter supports the given token.
+     * Used for multi-provider setups to route tokens to correct adapter.
+     */
+    canHandle?(token: string): boolean;
+}
+/**
+ * Options for initiating the login flow.
+ */
+export interface LoginOptions {
+    /** Override the redirect URI */
+    redirectUri?: string;
+    /** Additional OAuth scopes */
+    scopes?: string[];
+    /** Login hint (email) to pre-fill */
+    loginHint?: string;
+    /** Force account selection even if already logged in */
+    prompt?: 'none' | 'consent' | 'select_account';
+    /** Custom state parameter (default: random) */
+    state?: string;
+    /** Nonce for ID token validation */
+    nonce?: string;
+}
+/**
+ * Parameters received from OAuth provider callback.
+ */
+export interface CallbackParams {
+    /** Authorization code from OAuth provider */
+    code?: string;
+    /** State parameter for CSRF validation */
+    state?: string;
+    /** Error code if auth failed */
+    error?: string;
+    /** Error description */
+    errorDescription?: string;
+    /** Full URL (for parsing) */
+    url?: string;
+}
+/**
+ * Result of an authentication attempt.
+ */
+export interface AuthResult {
+    /** Whether authentication was successful */
+    valid: boolean;
+    /** Unique player ID from the provider */
+    playerId?: string;
+    /** Display username */
+    username?: string;
+    /** Email address */
+    email?: string;
+    /** URL to user's avatar image */
+    avatarUrl?: string;
+    /** Provider name */
+    provider?: string;
+    /** ID token or access token (main token for auth) */
+    token?: string;
+    /** Access token for API calls */
+    accessToken?: string;
+    /** Refresh token for token refresh */
+    refreshToken?: string;
+    /** Token expiration timestamp in milliseconds */
+    expiresAt?: number;
+    /** Human-readable error message */
+    error?: string;
+    /** Error code */
+    errorCode?: string;
+}
+/**
+ * Authenticated user information.
+ */
+export interface AuthUser {
+    /** Unique user ID from the provider */
+    id: string;
+    /** Display username */
+    username?: string;
+    /** Email address */
+    email?: string;
+    /** URL to user's avatar image */
+    avatarUrl?: string;
+    /** OAuth provider name */
+    provider: string;
+}
+/**
+ * Current authentication state.
+ */
+export interface AuthState {
+    /** Whether user is currently authenticated */
+    isAuthenticated: boolean;
+    /** Whether auth check is in progress */
+    isLoading: boolean;
+    /** Authenticated user info (null if not authenticated) */
+    user: AuthUser | null;
+    /** Current auth token (null if not authenticated) */
+    token: string | null;
+    /** Token expiration timestamp in milliseconds */
+    expiresAt: number | null;
+    /** OAuth provider name */
+    provider: string | null;
+}
+/**
+ * Data persisted to storage.
+ */
+export interface StoredAuthData {
+    /** User information */
+    user: AuthUser;
+    /** Auth token (ID token) */
+    token: string;
+    /** Access token (for API calls and revocation) */
+    accessToken?: string;
+    /** Refresh token (if available) */
+    refreshToken?: string;
+    /** Token expiration timestamp */
+    expiresAt?: number;
+    /** OAuth provider name */
+    provider: string;
+}
+/**
+ * Authentication error with additional context.
+ */
+export interface AuthError extends Error {
+    /** Error code */
+    code: string;
+    /** OAuth provider (if applicable) */
+    provider?: string;
+}
+/**
+ * Google OAuth configuration.
+ */
+export interface GoogleOAuthConfig {
+    /** Google OAuth 2.0 Client ID */
+    clientId: string;
+    /** OAuth scopes (default: ['openid', 'profile', 'email']) */
+    scopes?: string[];
+    /** Redirect URI after auth (default: window.location.origin + '/auth/callback') */
+    redirectUri?: string;
+    /** Google Workspace domain to restrict to */
+    hostedDomain?: string;
+    /**
+     * Backend endpoint URL for token exchange.
+     * The server exchanges the auth code for tokens using client_secret.
+     * This keeps the client_secret secure on the server.
+     *
+     * Example: 'https://your-game-server.com/auth/token'
+     *
+     * If not provided, the adapter will try to exchange directly with Google
+     * (which will fail for Web application clients that require client_secret).
+     */
+    tokenExchangeUrl?: string;
+}
+/**
+ * Discord OAuth configuration.
+ */
+export interface DiscordOAuthConfig {
+    /** Discord OAuth Client ID */
+    clientId: string;
+    /** OAuth scopes (default: ['identify', 'email']) */
+    scopes?: string[];
+    /** Redirect URI after auth */
+    redirectUri?: string;
+    /**
+     * Discord OAuth requires client_secret for token exchange.
+     * This MUST be done server-side. Provide your backend endpoint.
+     */
+    tokenExchangeEndpoint: string;
+}
+/**
+ * Steam OpenID configuration.
+ */
+export interface SteamAuthConfig {
+    /** Your domain (realm) - e.g., 'https://mygame.com' */
+    realm: string;
+    /** Return URL after Steam authentication */
+    returnUrl: string;
+    /**
+     * Backend endpoint to validate Steam OpenID response.
+     * Steam validation MUST be done server-side.
+     */
+    validationEndpoint: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

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

package/dist/auth/types.js

@@ -0,0 +1,7 @@
+/**
+ * Phalanx Auth Types
+ *
+ * Type definitions for the managed OAuth authentication system.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Phalanx Client Library
+ *
+ * Client-side library for connecting to Phalanx Engine servers.
+ * Provides a type-safe API for matchmaking, game synchronization,
+ * command submission, and reconnection handling.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { PhalanxClient } from '@phalanx-engine/client';
+ *
+ * // Create and connect
+ * const client = await PhalanxClient.create({
+ *   serverUrl: 'http://localhost:3000',
+ *   playerId: 'player-123',
+ *   username: 'MyPlayer',
+ * });
+ *
+ * // Matchmaking
+ * client.onMatchFound((data) => console.log('Match found!', data));
+ * client.joinQueue();
+ *
+ * // Game loop - just two callbacks!
+ * client.onTick((tick, commands) => {
+ *   // Process commands from all players
+ *   for (const [playerId, playerCommands] of Object.entries(commands.commands)) {
+ *     for (const cmd of playerCommands) {
+ *       handleCommand(playerId, cmd);
+ *     }
+ *   }
+ *   // Run simulation
+ *   world.simulate();
+ * });
+ *
+ * client.onFrame((alpha, dt) => {
+ *   // Interpolate positions for smooth rendering
+ *   interpolate(alpha);
+ *   // Render
+ *   scene.render();
+ * });
+ *
+ * // Send commands
+ * client.sendCommand('move', { targetX: 10, targetZ: 20 });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { PhalanxClient } from './PhalanxClient.js';
+export { EventEmitter } from './EventEmitter.js';
+export { RenderLoop } from './RenderLoop.js';
+export type { RenderLoopConfig, CommandFlushCallback } from './RenderLoop.js';
+export { SocketManager } from './SocketManager.js';
+export type { SocketManagerConfig, SocketManagerCallbacks, } from './SocketManager.js';
+export { DeterministicRandom } from './DeterministicRandom.js';
+export { FP, FPVector2, FPVector3, FixedPoint } from './FixedMath.js';
+export type { FPVector2Interface, FPVector3Interface } from './FixedMath.js';
+export { StateHasher } from './StateHasher.js';
+export { DesyncDetector } from './DesyncDetector.js';
+export type { DesyncConfig, DesyncEvent } from './DesyncDetector.js';
+export { RoomRecoveryController, RoomPersistence, isMobileBrowser, pickMobileFriendlyTransports, loadOrCreateGuestPlayerId, MemoryKeyValueStorage, defaultKeyValueStorage, getRecoverTimeoutMs, DEFAULT_RECOVER_TIMEOUT_BUDGET, armBrowserLifecycle, } from './recovery/index.js';
+export type { RoomRecoveryConfig, RoomRecoveryStatusEvent, RoomRecoveryPhase, RoomTerminatedEvent, RoomRecoveryControllerEvents, RecoveryClientPort, RoomPersistenceConfig, PersistedRoom, RoomRole, KeyValueStorage, RecoverTimeoutBudget, BrowserLifecycleHandle, BrowserLifecycleHandlers, } from './recovery/index.js';
+export { AuthManager } from './auth/AuthManager.js';
+export type { AuthManagerConfig } from './auth/AuthManager.js';
+export { GoogleOAuthAdapter } from './auth/adapters/GoogleOAuthAdapter.js';
+export { LocalStorageAdapter, MemoryStorageAdapter } from './auth/storage.js';
+export type { AuthStorage } from './auth/storage.js';
+export type { AuthAdapter, AuthResult, AuthState, AuthUser, AuthError, CallbackParams, LoginOptions, GoogleOAuthConfig, DiscordOAuthConfig, SteamAuthConfig, StoredAuthData, } from './auth/types.js';
+export type { PhalanxClientConfig, PhalanxAuthConfig, PhalanxRoomRecoveryConfig, PauseConfig, SocketTransport, PhalanxAuthState, PhalanxAuthUser, PlayerCommand, CommandsBatch, TickHandler, FrameHandler, Unsubscribe, PauseHandler, MatchPlayerInfo, MatchFoundEvent, CountdownEvent, GameStartEvent, MatchEndEvent, GamePausedEvent, GameResumedEvent, TickSyncEvent, CommandsBatchEvent, QueueStatusEvent, PlayerDisconnectedEvent, PlayerReconnectedEvent, PlayerReadyEvent, ReconnectStateEvent, TickCommandsHistory, ReconnectStatusEvent, SubmitCommandsAck, PhalanxError, ConnectionState, ClientState, HashComparisonEvent, RoomCreatedEvent, RoomErrorEvent, RoomExpiredEvent, RoomCancelledEvent, RoomRecoveredEvent, PhalanxClientEvents, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAMH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAOnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG9E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EACV,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAG7E,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAMrE,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,4BAA4B,EAC5B,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,8BAA8B,EAC9B,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,EAC5B,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,EACb,QAAQ,EACR,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAG3E,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EACV,WAAW,EACX,UAAU,EACV,SAAS,EACT,QAAQ,EACR,SAAS,EACT,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,cAAc,GACf,MAAM,iBAAiB,CAAC;AAMzB,YAAY,EAEV,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EACzB,WAAW,EACX,eAAe,EAGf,gBAAgB,EAChB,eAAe,EAGf,aAAa,EACb,aAAa,EAGb,WAAW,EACX,YAAY,EACZ,WAAW,EACX,YAAY,EAGZ,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EAGb,eAAe,EACf,gBAAgB,EAGhB,aAAa,EACb,kBAAkB,EAGlB,gBAAgB,EAGhB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAGhB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EAGpB,iBAAiB,EAGjB,YAAY,EAGZ,eAAe,EACf,WAAW,EAGX,mBAAmB,EAGnB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,EAGlB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,83 @@
+/**
+ * Phalanx Client Library
+ *
+ * Client-side library for connecting to Phalanx Engine servers.
+ * Provides a type-safe API for matchmaking, game synchronization,
+ * command submission, and reconnection handling.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { PhalanxClient } from '@phalanx-engine/client';
+ *
+ * // Create and connect
+ * const client = await PhalanxClient.create({
+ *   serverUrl: 'http://localhost:3000',
+ *   playerId: 'player-123',
+ *   username: 'MyPlayer',
+ * });
+ *
+ * // Matchmaking
+ * client.onMatchFound((data) => console.log('Match found!', data));
+ * client.joinQueue();
+ *
+ * // Game loop - just two callbacks!
+ * client.onTick((tick, commands) => {
+ *   // Process commands from all players
+ *   for (const [playerId, playerCommands] of Object.entries(commands.commands)) {
+ *     for (const cmd of playerCommands) {
+ *       handleCommand(playerId, cmd);
+ *     }
+ *   }
+ *   // Run simulation
+ *   world.simulate();
+ * });
+ *
+ * client.onFrame((alpha, dt) => {
+ *   // Interpolate positions for smooth rendering
+ *   interpolate(alpha);
+ *   // Render
+ *   scene.render();
+ * });
+ *
+ * // Send commands
+ * client.sendCommand('move', { targetX: 10, targetZ: 20 });
+ * ```
+ *
+ * @packageDocumentation
+ */
+// ============================================
+// Main Client
+// ============================================
+export { PhalanxClient } from './PhalanxClient.js';
+// ============================================
+// Utilities
+// ============================================
+// Event emitter (for building custom clients or extensions)
+export { EventEmitter } from './EventEmitter.js';
+// Render loop (for custom rendering setups)
+export { RenderLoop } from './RenderLoop.js';
+// Socket manager (for custom networking setups)
+export { SocketManager } from './SocketManager.js';
+// Deterministic random number generator
+export { DeterministicRandom } from './DeterministicRandom.js';
+// Fixed-point math (deterministic across all platforms)
+export { FP, FPVector2, FPVector3, FixedPoint } from './FixedMath.js';
+// State hasher utility for desync detection
+export { StateHasher } from './StateHasher.js';
+// Desync detector (advanced usage - for custom desync handling)
+export { DesyncDetector } from './DesyncDetector.js';
+// ============================================
+// Room Recovery (mobile-friendly reconnection)
+// ============================================
+export { RoomRecoveryController, RoomPersistence, isMobileBrowser, pickMobileFriendlyTransports, loadOrCreateGuestPlayerId, MemoryKeyValueStorage, defaultKeyValueStorage, getRecoverTimeoutMs, DEFAULT_RECOVER_TIMEOUT_BUDGET, armBrowserLifecycle, } from './recovery/index.js';
+// ============================================
+// Authentication
+// ============================================
+// Auth manager (managed OAuth for Google, Discord, Steam)
+export { AuthManager } from './auth/AuthManager.js';
+// Google OAuth adapter
+export { GoogleOAuthAdapter } from './auth/adapters/GoogleOAuthAdapter.js';
+// Storage adapters
+export { LocalStorageAdapter, MemoryStorageAdapter } from './auth/storage.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,+CAA+C;AAC/C,cAAc;AACd,+CAA+C;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,+CAA+C;AAC/C,YAAY;AACZ,+CAA+C;AAE/C,4DAA4D;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,4CAA4C;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG7C,gDAAgD;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAOnD,wCAAwC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,wDAAwD;AACxD,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGtE,4CAA4C;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,gEAAgE;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,+CAA+C;AAC/C,+CAA+C;AAC/C,+CAA+C;AAE/C,OAAO,EACL,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,4BAA4B,EAC5B,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACnB,8BAA8B,EAC9B,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAiB7B,+CAA+C;AAC/C,iBAAiB;AACjB,+CAA+C;AAE/C,0DAA0D;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGpD,uBAAuB;AACvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAE3E,mBAAmB;AACnB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/recovery/BrowserLifecycle.d.ts

@@ -0,0 +1,33 @@
+/**
+ * BrowserLifecycle — wires the small bag of DOM listeners every
+ * mobile-friendly recovery flow needs:
+ *
+ *  - `visibilitychange` — fires when the user returns to the tab from
+ *    another app or another tab (most reliable signal on Android).
+ *  - `pageshow` — fires when iOS Safari restores the page from
+ *    bfcache (in some cases `visibilitychange` does not fire).
+ *  - `online`  — the OS reports the network came back; useful for the
+ *    "wait for network to stabilize" portion of recovery.
+ *
+ * Idempotent and SSR-safe (no-ops when `document`/`window` are
+ * unavailable). Returned object exposes `dispose()` for clean unwiring.
+ */
+export interface BrowserLifecycleHandle {
+    dispose(): void;
+}
+export interface BrowserLifecycleHandlers {
+    /** Called on visibilitychange→visible and on pageshow. */
+    onVisible?: () => void;
+    /** Called on `window` `online` event. */
+    onOnline?: () => void;
+}
+export declare function armBrowserLifecycle(handlers: BrowserLifecycleHandlers): BrowserLifecycleHandle;
+/** True if the OS reports the device is currently online. */
+export declare function isOnline(): boolean;
+/**
+ * Resolve when the next `online` event fires, or after `timeoutMs`,
+ * whichever comes first. Used to gate recovery attempts behind a fresh
+ * network signal so we don't burn retries while the radio is still off.
+ */
+export declare function waitForOnlineEvent(timeoutMs: number): Promise<void>;
+//# sourceMappingURL=BrowserLifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserLifecycle.d.ts","sourceRoot":"","sources":["../../src/recovery/BrowserLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,wBAAwB,GACjC,sBAAsB,CAmCxB;AAED,6DAA6D;AAC7D,wBAAgB,QAAQ,IAAI,OAAO,CAGlC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAcnE"}

package/dist/recovery/BrowserLifecycle.js

@@ -0,0 +1,62 @@
+export function armBrowserLifecycle(handlers) {
+    if (typeof document === 'undefined' || typeof window === 'undefined') {
+        return { dispose: () => { } };
+    }
+    const visibilityHandler = () => {
+        if (document.visibilityState !== 'visible')
+            return;
+        handlers.onVisible?.();
+    };
+    const pageShowHandler = () => {
+        handlers.onVisible?.();
+    };
+    const onlineHandler = () => {
+        handlers.onOnline?.();
+    };
+    if (handlers.onVisible) {
+        document.addEventListener('visibilitychange', visibilityHandler);
+        window.addEventListener('pageshow', pageShowHandler);
+    }
+    if (handlers.onOnline) {
+        window.addEventListener('online', onlineHandler);
+    }
+    return {
+        dispose() {
+            if (handlers.onVisible) {
+                document.removeEventListener('visibilitychange', visibilityHandler);
+                window.removeEventListener('pageshow', pageShowHandler);
+            }
+            if (handlers.onOnline) {
+                window.removeEventListener('online', onlineHandler);
+            }
+        },
+    };
+}
+/** True if the OS reports the device is currently online. */
+export function isOnline() {
+    if (typeof navigator === 'undefined')
+        return true;
+    return navigator.onLine !== false;
+}
+/**
+ * Resolve when the next `online` event fires, or after `timeoutMs`,
+ * whichever comes first. Used to gate recovery attempts behind a fresh
+ * network signal so we don't burn retries while the radio is still off.
+ */
+export function waitForOnlineEvent(timeoutMs) {
+    if (typeof window === 'undefined')
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const onOnline = () => {
+            window.removeEventListener('online', onOnline);
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            window.removeEventListener('online', onOnline);
+            resolve();
+        }, timeoutMs);
+        window.addEventListener('online', onOnline);
+    });
+}
+//# sourceMappingURL=BrowserLifecycle.js.map

package/dist/recovery/BrowserLifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserLifecycle.js","sourceRoot":"","sources":["../../src/recovery/BrowserLifecycle.ts"],"names":[],"mappings":"AAyBA,MAAM,UAAU,mBAAmB,CACjC,QAAkC;IAElC,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QACrE,OAAO,EAAE,OAAO,EAAE,GAAS,EAAE,GAAE,CAAC,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,iBAAiB,GAAG,GAAS,EAAE;QACnC,IAAI,QAAQ,CAAC,eAAe,KAAK,SAAS;YAAE,OAAO;QACnD,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;IACzB,CAAC,CAAC;IACF,MAAM,eAAe,GAAG,GAAS,EAAE;QACjC,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;IACzB,CAAC,CAAC;IACF,MAAM,aAAa,GAAG,GAAS,EAAE;QAC/B,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;IACxB,CAAC,CAAC;IAEF,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;QACvB,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;QACjE,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACtB,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IACnD,CAAC;IAED,OAAO;QACL,OAAO;YACL,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;gBACvB,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;gBACpE,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;YAC1D,CAAC;YACD,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBACtB,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,QAAQ;IACtB,IAAI,OAAO,SAAS,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAClD,OAAO,SAAS,CAAC,MAAM,KAAK,KAAK,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5D,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,QAAQ,GAAG,GAAS,EAAE;YAC1B,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC/C,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC/C,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/recovery/GuestPlayerIdStore.d.ts

@@ -0,0 +1,17 @@
+import { type KeyValueStorage } from './KeyValueStorage.js';
+/**
+ * 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 declare function loadOrCreateGuestPlayerId(storageKey: string, storage?: KeyValueStorage): string;
+//# sourceMappingURL=GuestPlayerIdStore.d.ts.map