@phalanx-engine/server 0.1.0

package/dist/services/TokenValidator.js

@@ -0,0 +1,213 @@
+/**
+ * Phalanx Server Authentication
+ *
+ * Token validation for securing WebSocket connections.
+ */
+/**
+ * Token Validator Service
+ *
+ * Validates OAuth tokens for server-side authentication.
+ */
+export class TokenValidatorService {
+    config;
+    tokenCache = new Map();
+    googleKeysCache = null;
+    constructor(config) {
+        this.config = {
+            cacheTokens: true,
+            cacheTtlMs: 5 * 60 * 1000, // 5 minutes
+            ...config,
+        };
+    }
+    /**
+     * Validate a token
+     */
+    async validate(token) {
+        if (!token) {
+            return { valid: false, error: 'No token provided' };
+        }
+        // Check cache first
+        if (this.config.cacheTokens) {
+            const cached = this.tokenCache.get(token);
+            if (cached && cached.expiresAt > Date.now()) {
+                return cached.result;
+            }
+        }
+        let result;
+        // Use custom validator if provided
+        if (this.config.validator) {
+            result = await this.config.validator(token);
+        }
+        // Use Google validator if configured
+        else if (this.config.google) {
+            result = await this.validateGoogleToken(token);
+        }
+        // No validator configured
+        else {
+            return {
+                valid: false,
+                error: 'No token validator configured',
+            };
+        }
+        // Cache the result
+        if (this.config.cacheTokens && result.valid) {
+            const cacheTtl = this.config.cacheTtlMs || 5 * 60 * 1000;
+            this.tokenCache.set(token, {
+                result,
+                expiresAt: Date.now() + cacheTtl,
+            });
+        }
+        return result;
+    }
+    /**
+     * Validate a Google ID token
+     */
+    async validateGoogleToken(token) {
+        try {
+            // Decode the token (without verification first to get the header)
+            const parts = token.split('.');
+            if (parts.length !== 3 || !parts[0] || !parts[1]) {
+                return { valid: false, error: 'Invalid token format' };
+            }
+            // Decode payload
+            const payloadJson = this.base64UrlDecode(parts[1]);
+            const payload = JSON.parse(payloadJson);
+            // Validate issuer
+            if (payload.iss !== 'https://accounts.google.com' &&
+                payload.iss !== 'accounts.google.com') {
+                return { valid: false, error: 'Invalid issuer' };
+            }
+            // Validate audience (client ID)
+            if (payload.aud !== this.config.google.clientId) {
+                return { valid: false, error: 'Invalid audience' };
+            }
+            // Validate expiration
+            if (payload.exp * 1000 < Date.now()) {
+                return { valid: false, error: 'Token expired' };
+            }
+            // Validate hosted domain if configured
+            if (this.config.google.allowedDomains?.length) {
+                if (!payload.hd ||
+                    !this.config.google.allowedDomains.includes(payload.hd)) {
+                    return {
+                        valid: false,
+                        error: `User must be from allowed domains: ${this.config.google.allowedDomains.join(', ')}`,
+                    };
+                }
+            }
+            // TODO: For production, verify the token signature using Google's JWKS
+            // This requires fetching keys from https://www.googleapis.com/oauth2/v3/certs
+            // and verifying the RS256 signature. See user story 04-id-token-signature-verification.md
+            return {
+                valid: true,
+                userId: payload.sub,
+                username: payload.name,
+                email: payload.email,
+                expiresAt: payload.exp * 1000,
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: error instanceof Error ? error.message : 'Token validation failed',
+            };
+        }
+    }
+    /**
+     * Verify token signature using Google's JWKS (for production use)
+     * TODO: Implement full signature verification
+     */
+    async verifyGoogleSignature(_token, _kid) {
+        // This is a placeholder for full signature verification
+        // See user story 04-id-token-signature-verification.md
+        console.warn('[TokenValidator] Signature verification not implemented - using claims-only validation');
+        return true;
+    }
+    /**
+     * Base64URL decode
+     */
+    base64UrlDecode(input) {
+        let base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+        const padding = base64.length % 4;
+        if (padding) {
+            base64 += '='.repeat(4 - padding);
+        }
+        return Buffer.from(base64, 'base64').toString('utf-8');
+    }
+    /**
+     * Clear the token cache
+     */
+    clearCache() {
+        this.tokenCache.clear();
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return {
+            size: this.tokenCache.size,
+            hits: 0, // Would need to track this
+        };
+    }
+}
+/**
+ * Create a simple custom validator that accepts any non-empty token.
+ * FOR DEVELOPMENT/TESTING ONLY - DO NOT USE IN PRODUCTION!
+ */
+export function createDevValidator() {
+    console.warn('[TokenValidator] Using development validator - DO NOT USE IN PRODUCTION!');
+    return async (token) => {
+        if (!token) {
+            return { valid: false, error: 'No token' };
+        }
+        // In dev mode, extract userId from token if it looks like "dev:userId"
+        if (token.startsWith('dev:')) {
+            const userId = token.slice(4);
+            return {
+                valid: true,
+                userId,
+                username: userId,
+            };
+        }
+        // Accept any token in dev mode
+        return {
+            valid: true,
+            userId: 'dev-user',
+            username: 'Developer',
+        };
+    };
+}
+/**
+ * Create a validator that validates tokens via an external endpoint.
+ * Useful when you have a backend auth service.
+ */
+export function createEndpointValidator(endpointUrl, options) {
+    return async (token) => {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), options?.timeout || 5000);
+            const response = await fetch(endpointUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...options?.headers,
+                },
+                body: JSON.stringify({ token }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                return { valid: false, error: `Validation failed: ${response.status}` };
+            }
+            const result = await response.json();
+            return result;
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: error instanceof Error ? error.message : 'Validation request failed',
+            };
+        }
+    };
+}
+//# sourceMappingURL=TokenValidator.js.map

package/dist/services/TokenValidator.js.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Phalanx Engine Types
+ * All exported types for TypeScript users
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/**
+ * Game mode preset string
+ */
+export type GameModePreset = '1v1' | '2v2' | '3v3' | '4v4' | 'FFA4';
+/**
+ * Custom game mode configuration
+ */
+export interface CustomGameMode {
+    playersPerMatch: number;
+    teamsCount: number;
+}
+/**
+ * Game mode - either a preset string or custom configuration
+ */
+export type GameMode = GameModePreset | CustomGameMode;
+/**
+ * Tick mode: 'continuous' runs a server tick loop; 'event' is tickless (relay-only).
+ */
+export type TickMode = 'continuous' | 'event';
+/**
+ * Per-game-type configuration overrides.
+ * Fields here override the base PhalanxConfig for matches of this game type.
+ */
+export interface GameTypeConfig {
+    gameType: string;
+    tickMode?: TickMode;
+    tickRate?: number;
+    gameMode?: GameMode;
+    countdownSeconds?: number;
+    turnTimeoutMs?: number;
+}
+/**
+ * CORS configuration
+ */
+export interface CorsConfig {
+    origin: string | string[];
+    methods?: string[];
+    credentials?: boolean;
+}
+/**
+ * TLS/SSL configuration for secure WebSocket connections (WSS)
+ */
+export interface TlsConfig {
+    /** Enable TLS/SSL encryption */
+    enabled: boolean;
+    /** Path to the private key file (PEM format) */
+    keyPath: string;
+    /** Path to the certificate file (PEM format) */
+    certPath: string;
+    /** Optional path to CA certificate chain (for Let's Encrypt) */
+    caPath?: string;
+}
+/**
+ * Action to take when desync is detected
+ */
+export type DesyncAction = 'log-only' | 'end-match';
+/**
+ * Configuration for desync detection behavior
+ */
+export interface DesyncConfig {
+    /** Whether desync detection is enabled */
+    enabled: boolean;
+    /** Action to take on confirmed desync */
+    action: DesyncAction;
+    /** Number of consecutive desyncs before taking action (default: 1) */
+    gracePeriodTicks: number;
+}
+/**
+ * Configuration for pause/resume behavior
+ */
+export interface PauseConfig {
+    /**
+     * Maximum number of pauses allowed per player.
+     * Set to Infinity for unlimited pauses.
+     * @default Infinity
+     */
+    maxPausesPerPlayer: number;
+    /**
+     * Whether the game can only be resumed by the same player who paused it.
+     * If false, any player can resume the game.
+     * @default false
+     */
+    requireSamePlayerToResume: boolean;
+}
+/**
+ * Token validator function type.
+ * Implement this to validate tokens from your OAuth provider.
+ */
+export type TokenValidator = (token: string) => Promise<TokenValidationResult>;
+/**
+ * Result of token validation
+ */
+export interface TokenValidationResult {
+    /** Whether the token is valid */
+    valid: boolean;
+    /** User ID from the token (if valid) */
+    userId?: string;
+    /** Username from the token (if valid) */
+    username?: string;
+    /** Email from the token (if valid) */
+    email?: string;
+    /** Token expiration timestamp in milliseconds (if valid) */
+    expiresAt?: number;
+    /** Error message (if invalid) */
+    error?: string;
+}
+/**
+ * Authentication configuration for securing WebSocket connections
+ */
+export interface AuthConfig {
+    /** Enable authentication (default: false for development) */
+    enabled: boolean;
+    /**
+     * Custom token validator function.
+     * If not provided and enabled=true, you must configure a built-in validator.
+     */
+    validator?: TokenValidator;
+    /**
+     * Built-in Google token validation.
+     * Validates Google ID tokens.
+     */
+    google?: {
+        /** Your Google OAuth Client ID */
+        clientId: string;
+        /** Your Google OAuth Client Secret (required for token exchange) */
+        clientSecret?: string;
+        /** Allowed hosted domains (optional, for Google Workspace) */
+        allowedDomains?: string[];
+    };
+    /**
+     * Allow unauthenticated connections (for development/testing).
+     * If true, connections without tokens are allowed when auth is enabled.
+     * @default false
+     */
+    allowAnonymous?: boolean;
+    /**
+     * Cache validated tokens to reduce validation overhead.
+     * @default true
+     */
+    cacheTokens?: boolean;
+    /**
+     * Token cache TTL in milliseconds.
+     * @default 300000 (5 minutes)
+     */
+    cacheTtlMs?: number;
+}
+/**
+ * Full Phalanx configuration
+ */
+export interface PhalanxConfig {
+    port: number;
+    cors: CorsConfig;
+    tls?: TlsConfig;
+    auth?: AuthConfig;
+    tickRate: number;
+    tickDeadlineMs: number;
+    tickMode?: TickMode;
+    gameTypes?: GameTypeConfig[];
+    turnTimeoutMs?: number;
+    gameMode: GameMode;
+    matchmakingIntervalMs: number;
+    countdownSeconds: number;
+    timeoutTicks: number;
+    disconnectTicks: number;
+    reconnectGracePeriodMs: number;
+    maxTickBehind: number;
+    maxTickAhead: number;
+    commandHistoryTicks: number;
+    /** Enable input sequence validation (default: false for backward compatibility) */
+    validateInputSequence?: boolean;
+    /** Enable state hashing for desync detection (default: false) */
+    enableStateHashing?: boolean;
+    /** Interval in ticks between state hash checks (default: 60) */
+    stateHashInterval?: number;
+    /** Desync detection behavior configuration */
+    desync?: Partial<DesyncConfig>;
+    /** Timeout in milliseconds for all clients to report ready after game-start (default: 30000) */
+    readyTimeoutMs?: number;
+    /**
+     * How long `GameRoom.start()` will wait for all participants' sockets
+     * to be present before kicking off the countdown. If at least one
+     * player is offline at start time, the match enters
+     * `'waiting-for-players'` and emits `match-waiting-for-players` to
+     * whoever is online; the countdown only begins once everyone
+     * reconnects, or after this timeout the match is ended with
+     * `match-end: 'players-not-connected'`. Default: 60000.
+     */
+    playersConnectTimeoutMs?: number;
+    /** Pause/resume behavior configuration */
+    pause?: Partial<PauseConfig>;
+    /**
+     * Optional hook for mounting additional request handlers on the same HTTP
+     * server. Called after CORS preflight, before built-in routes.
+     *
+     * Return `true` to signal the request was fully handled (no further
+     * routing). Return `false` (or `undefined`) to let Phalanx continue with
+     * its own routing.
+     */
+    extraRequestHandler?: (req: IncomingMessage, res: ServerResponse) => boolean | Promise<boolean>;
+}
+/**
+ * Player command sent from client
+ */
+export interface PlayerCommand {
+    type: string;
+    tick: number;
+    playerId: string;
+    data: unknown;
+    /** Optional sequence number for input validation (monotonically increasing per player) */
+    sequence?: number;
+}
+/**
+ * Information about a player
+ */
+export interface PlayerInfo {
+    id: string;
+    teamId: number;
+    connected: boolean;
+    lastTick: number;
+}
+/**
+ * Information about an active match
+ */
+export interface MatchInfo {
+    id: string;
+    players: PlayerInfo[];
+    currentTick: number;
+    state: 'waiting-for-players' | 'countdown' | 'waiting-for-ready' | 'playing' | 'paused' | 'finished';
+    createdAt: Date;
+    gameType?: string;
+}
+/**
+ * Player info for match-found event (minimal data)
+ */
+export interface MatchPlayerInfo {
+    playerId: string;
+    username: string;
+}
+/**
+ * Match found event payload - personalized for each player
+ */
+export interface MatchFoundEvent {
+    matchId: string;
+    playerId: string;
+    teamId: number;
+    teammates: MatchPlayerInfo[];
+    opponents: MatchPlayerInfo[];
+}
+/**
+ * Countdown event payload - sent every second before game starts
+ */
+export interface CountdownEvent {
+    seconds: number;
+}
+/**
+ * Game start event payload - sent when countdown reaches 0
+ */
+export interface GameStartEvent {
+    matchId: string;
+    /** Random seed for deterministic RNG (optional for backward compatibility) */
+    randomSeed?: number;
+}
+/**
+ * Tick sync event payload - sent every tick for synchronization
+ */
+export interface TickSyncEvent {
+    tick: number;
+    timestamp: number;
+}
+/**
+ * Commands batch event payload - sent to all clients each tick
+ */
+export interface CommandsBatchEvent {
+    tick: number;
+    commands: PlayerCommand[];
+}
+/**
+ * Commands grouped by player for a specific tick
+ */
+export interface TickCommands {
+    [playerId: string]: PlayerCommand[];
+}
+/**
+ * Submit commands event payload from client
+ */
+export interface SubmitCommandsEvent {
+    tick: number;
+    commands: PlayerCommand[];
+}
+/**
+ * Player queued for matchmaking
+ */
+export interface QueuedPlayer {
+    playerId: string;
+    username: string;
+    socketId: string;
+    joinedAt: number;
+    gameType?: string;
+}
+/**
+ * Queue status response
+ */
+export interface QueueStatusEvent {
+    position: number;
+    waitTime: number;
+}
+/**
+ * Private room events — client/server wire contracts.
+ *
+ * These mirror the interfaces exported from
+ * `services/PrivateRoomService.ts` and are documented here for
+ * consistency with the rest of the public event surface.
+ *
+ * Socket events:
+ *   • server → host:  `room-created`    → `RoomCreatedEvent`
+ *   • server → host:  `room-recovered`  → `RoomRecoveredEvent`
+ *   • server → host:  `room-cancelled`  → `{ code: string }`
+ *   • server → host:  `room-expired`    → `{ code: string }`
+ *   • server → peer:  `room-error`      → `RoomErrorEvent`
+ *   • client → server: `room-create`    → `{ playerId, username?, gameType? }`
+ *   • client → server: `room-join`      → `{ playerId, username?, code }`
+ *   • client → server: `room-cancel`    → `{}`
+ *   • client → server: `room-recover`   → `{ playerId, username?, code }`
+ *
+ * The `code` on `room-recover` is required: it proves the caller is
+ * actually the host who created the room. In an unauthenticated
+ * socket environment `playerId` alone is not a credential, so the
+ * server refuses to recover without a matching code and emits
+ * `room-error: "Room expired"` instead (same message as "no such
+ * room" so we never leak whether a given playerId currently owns
+ * a room).
+ */
+/** Event sent to the host when a room is created. */
+export interface RoomCreatedEvent {
+    code: string;
+}
+/**
+ * Event sent to the host when they successfully reclaim a room
+ * via `room-recover` after a transient socket disconnect.
+ */
+export interface RoomRecoveredEvent {
+    code: string;
+}
+/** Event sent when a private-room operation fails. */
+export interface RoomErrorEvent {
+    message: string;
+}
+/**
+ * State hash event from client (2.1.3)
+ */
+export interface StateHashEvent {
+    tick: number;
+    hash: string;
+}
+/**
+ * Desync detected event (2.1.3)
+ */
+export interface DesyncDetectedEvent {
+    tick: number;
+    hashes: {
+        [playerId: string]: string;
+    };
+}
+/**
+ * Available Phalanx events
+ */
+export type PhalanxEventType = 'match-created' | 'match-started' | 'match-ended' | 'match-paused' | 'match-resumed' | 'player-command' | 'player-timeout' | 'player-reconnected' | 'player-disconnected' | 'desync-detected';
+/**
+ * Event handler types
+ */
+export interface PhalanxEventHandlers {
+    'match-created': (match: MatchInfo) => void;
+    'match-started': (match: MatchInfo) => void;
+    'match-ended': (matchId: string, reason: string) => void;
+    'match-paused': (matchId: string, requestedBy: string) => void;
+    'match-resumed': (matchId: string, requestedBy: string) => void;
+    'player-command': (playerId: string, command: PlayerCommand) => boolean | void;
+    'player-timeout': (playerId: string, matchId: string) => void;
+    'player-reconnected': (playerId: string, matchId: string) => void;
+    'player-disconnected': (playerId: string, matchId: string) => void;
+    'desync-detected': (matchId: string, tick: number, hashes: {
+        [playerId: string]: string;
+    }) => void;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,cAAc,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,WAAW,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,MAAM,EAAE,YAAY,CAAC;IACrB,sEAAsE;IACtE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IACH,yBAAyB,EAAE,OAAO,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,kCAAkC;QAClC,QAAQ,EAAE,MAAM,CAAC;QACjB,oEAAoE;QACpE,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,8DAA8D;QAC9D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC;IAEF;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAE5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IAGjB,GAAG,CAAC,EAAE,SAAS,CAAC;IAGhB,IAAI,CAAC,EAAE,UAAU,CAAC;IAGlB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAGpB,SAAS,CAAC,EAAE,cAAc,EAAE,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,QAAQ,EAAE,QAAQ,CAAC;IACnB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IAGzB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,CAAC;IAG/B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IAGrB,mBAAmB,EAAE,MAAM,CAAC;IAG5B,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAG/B,gGAAgG;IAChG,cAAc,CAAC,EAAE,MAAM,CAAC;IAGxB;;;;;;;;OAQG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAGjC,0CAA0C;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAG7B;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,CACpB,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,qBAAqB,GAAG,WAAW,GAAG,mBAAmB,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;IACrG,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,SAAS,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,eAAe,GACf,aAAa,GACb,cAAc,GACd,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,qBAAqB,GACrB,iBAAiB,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC5C,eAAe,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/D,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IAChE,gBAAgB,EAAE,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,KACnB,OAAO,GAAG,IAAI,CAAC;IACpB,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9D,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClE,qBAAqB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE,iBAAiB,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,KACnC,IAAI,CAAC;CACX"}

package/dist/types/index.js

@@ -0,0 +1,6 @@
+/**
+ * Phalanx Engine Types
+ * All exported types for TypeScript users
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

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