@smoregg/sdk 2.0.0 → 2.1.0

package/dist/types/types.d.ts

@@ -26,6 +26,11 @@ export type RoomCode = string;
  * is enforced by the server's genericRelay handler. Payloads exceeding this
  * limit will be silently dropped by the server without error notification.
  *
+ * **Reserved Fields:** The field names `playerIndex` and `targetPlayerIndex` are reserved
+ * by the SDK for internal routing. Using these as custom data field names will cause
+ * a compile-time error. The SDK automatically extracts `playerIndex` to identify the sender
+ * and uses `targetPlayerIndex` for targeted message delivery.
+ *
  * **Type Safety Note:** Without providing an explicit generic type parameter,
  * `createScreen()` and `createController()` default to the empty `EventMap`,
  * which means `send()`, `broadcast()`, and `on()` accept any string as an event
@@ -46,7 +51,7 @@ export type RoomCode = string;
  *
  * // With explicit generic -- full type safety
  * const screen = createScreen<MyGameEvents>({ debug: true });
- * screen.on('tap', (pi, data) => { ... });
+ * screen.on('tap', (playerIndex, data) => { ... });
  * await screen.ready;
  *
  * // Without generic -- no type safety (not recommended)
@@ -64,7 +69,10 @@ export type RoomCode = string;
  * ```
  */
 export interface EventMap {
-    [key: string]: unknown;
+    [key: string]: Record<string, unknown> & {
+        playerIndex?: never;
+        targetPlayerIndex?: never;
+    };
 }
 /**
  * Extract event names from an event map.
@@ -93,7 +101,7 @@ export interface CharacterAppearance {
     /** Character style preset identifier */
     style: string;
     /** Additional character customization options */
-    options: Record<string, any>;
+    options: Record<string, unknown>;
 }
 /**
  * Information about a connected controller (player).
@@ -124,6 +132,99 @@ export interface ControllerInfo {
      */
     readonly appearance?: CharacterAppearance | null;
 }
+/**
+ * Transport interface for custom communication implementations.
+ * Implement this to use a custom transport instead of the default PostMessageTransport.
+ */
+export interface Transport {
+    emit(event: string, ...args: unknown[]): void;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler?: (...args: unknown[]) => void): void;
+    destroy(): void;
+}
+/**
+ * Error codes for SDK errors.
+ */
+export type SmoreErrorCode = 'TIMEOUT' | 'NOT_READY' | 'DESTROYED' | 'INVALID_EVENT' | 'INVALID_PLAYER' | 'CONNECTION_LOST' | 'INIT_FAILED' | 'RATE_LIMITED' | 'PAYLOAD_TOO_LARGE' | 'UNKNOWN';
+/**
+ * Structured error type for SDK errors.
+ */
+export interface SmoreError {
+    /** Error code for programmatic handling */
+    code: SmoreErrorCode;
+    /** Human-readable error message */
+    message: string;
+    /** Original error if available */
+    cause?: Error;
+    /** Additional context */
+    details?: Record<string, unknown>;
+}
+/**
+ * Game results structure for gameOver().
+ * Flexible to accommodate different game types.
+ */
+export interface GameResults {
+    /** Player scores indexed by player index */
+    scores?: Record<PlayerIndex, number>;
+    /** Winner's player index (or -1 for no winner/tie) */
+    winner?: PlayerIndex;
+    /** Ranked player indices from first to last */
+    rankings?: PlayerIndex[];
+    /** Additional custom game-specific data */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Lifecycle event names for subscribing via `on()`.
+ *
+ * These `$`-prefixed event names allow lifecycle events to be registered
+ * through the same `on()` method used for game events. The `$` prefix is
+ * reserved by the SDK and cannot be used for user-defined events.
+ *
+ * @example
+ * ```ts
+ * // These are equivalent:
+ * screen.onControllerJoin((pi, info) => { ... });
+ * screen.on(LifecycleEvent.CONTROLLER_JOIN, (pi, info) => { ... });
+ * ```
+ */
+export declare const LifecycleEvent: {
+    readonly ALL_READY: "$all-ready";
+    readonly CONTROLLER_JOIN: "$controller-join";
+    readonly CONTROLLER_LEAVE: "$controller-leave";
+    readonly CONTROLLER_DISCONNECT: "$controller-disconnect";
+    readonly CONTROLLER_RECONNECT: "$controller-reconnect";
+    readonly CHARACTER_UPDATED: "$character-updated";
+    readonly ERROR: "$error";
+    readonly GAME_OVER: "$game-over";
+    readonly CONNECTION_CHANGE: "$connection-change";
+};
+/** Union of all lifecycle event name strings. */
+export type LifecycleEventName = typeof LifecycleEvent[keyof typeof LifecycleEvent];
+/**
+ * Handler signatures for Screen lifecycle events.
+ * Used by `on()` overloads to provide type-safe lifecycle event subscription.
+ */
+export interface ScreenLifecycleHandlers {
+    '$all-ready': () => void;
+    '$controller-join': (playerIndex: PlayerIndex, info: ControllerInfo) => void;
+    '$controller-leave': (playerIndex: PlayerIndex) => void;
+    '$controller-disconnect': (playerIndex: PlayerIndex) => void;
+    '$controller-reconnect': (playerIndex: PlayerIndex, info: ControllerInfo) => void;
+    '$character-updated': (playerIndex: PlayerIndex, appearance: CharacterAppearance | null) => void;
+    '$error': (error: SmoreError) => void;
+    '$connection-change': (connected: boolean) => void;
+}
+/** Screen lifecycle event name union. */
+export type ScreenLifecycleEvent = keyof ScreenLifecycleHandlers;
+/**
+ * Handler signatures for Controller lifecycle events.
+ * Extends Screen lifecycle events with Controller-specific events.
+ */
+export interface ControllerLifecycleHandlers extends ScreenLifecycleHandlers {
+    '$game-over': (results?: GameResults) => void;
+}
+/** Controller lifecycle event name union. */
+export type ControllerLifecycleEvent = keyof ControllerLifecycleHandlers;
 /**
  * Handler for events received from controllers.
  * Receives the player index and event data.
@@ -144,12 +245,12 @@ export type ScreenEventHandler<TData = unknown> = (playerIndex: PlayerIndex, dat
  *
  * screen.on('tap', (playerIndex, data) => handleTap(playerIndex, data));
  * screen.onAllReady(() => startCountdown());
- * screen.onControllerJoin((pi, info) => console.log('Joined:', pi));
+ * screen.onControllerJoin((playerIndex, info) => console.log('Joined:', playerIndex));
  *
  * await screen.ready;
  * ```
  */
-export interface ScreenConfig<_TEvents extends EventMap = EventMap> {
+export interface ScreenConfig {
     /**
      * Enable debug mode for verbose logging.
      * @default false
@@ -166,6 +267,19 @@ export interface ScreenConfig<_TEvents extends EventMap = EventMap> {
      * @default 10000
      */
     timeout?: number;
+    /**
+     * Automatically signal ready after initialization.
+     * When true (default), the SDK calls signalReady() automatically after init completes.
+     * Set to false if your game needs to load resources before signaling ready.
+     * @default true
+     */
+    autoReady?: boolean;
+    /**
+     * Custom transport implementation.
+     * If provided, uses this instead of the default PostMessageTransport.
+     * The bridge handshake (_bridge:init) still occurs via postMessage.
+     */
+    transport?: Transport;
 }
 /**
  * Screen instance - the main interface for the host/TV side of your game.
@@ -179,9 +293,9 @@ export interface ScreenConfig<_TEvents extends EventMap = EventMap> {
  * ```ts
  * const screen = createScreen<MyEvents>({ debug: true });
  *
- * screen.on('tap', (pi, data) => handleTap(pi, data));
+ * screen.on('tap', (playerIndex, data) => handleTap(playerIndex, data));
  * screen.onAllReady(() => startGame());
- * screen.onControllerJoin((pi, info) => addPlayer(pi, info));
+ * screen.onControllerJoin((playerIndex, info) => addPlayer(playerIndex, info));
  *
  * await screen.ready;
  * screen.broadcast('phase-update', { phase: 'playing' });
@@ -203,6 +317,10 @@ export interface Screen<TEvents extends EventMap = EventMap> {
     readonly isReady: boolean;
     /** Whether the screen has been destroyed. */
     readonly isDestroyed: boolean;
+    /** Whether the connection to the server is active. */
+    readonly isConnected: boolean;
+    /** Protocol version negotiated with the parent frame. */
+    readonly protocolVersion: number;
     /**
      * A Promise that resolves when the screen is initialized and ready.
      * Use this to await readiness after creating a screen synchronously.
@@ -259,13 +377,6 @@ export interface Screen<TEvents extends EventMap = EventMap> {
      * @returns Unsubscribe function to remove the callback
      */
     onCharacterUpdated(callback: (playerIndex: PlayerIndex, appearance: CharacterAppearance | null) => void): () => void;
-    /**
-     * Register a callback for when the server rate-limits an event.
-     *
-     * @param callback - Called with the rate-limited event name
-     * @returns Unsubscribe function to remove the callback
-     */
-    onRateLimited(callback: (event: string) => void): () => void;
     /**
      * Register a callback for when an error occurs.
      * If no error callback is registered, errors are logged to console in debug mode.
@@ -274,6 +385,14 @@ export interface Screen<TEvents extends EventMap = EventMap> {
      * @returns Unsubscribe function to remove the callback
      */
     onError(callback: (error: SmoreError) => void): () => void;
+    /**
+     * Register a callback for when the connection status changes.
+     * Called when the connection to the server is lost or restored.
+     *
+     * @param callback - Called with true (connected) or false (disconnected)
+     * @returns Unsubscribe function to remove the callback
+     */
+    onConnectionChange(callback: (connected: boolean) => void): () => void;
     /**
      * Broadcast an event to all connected controllers.
      *
@@ -288,11 +407,6 @@ export interface Screen<TEvents extends EventMap = EventMap> {
      * ```
      */
     broadcast<K extends EventNames<TEvents>>(event: K, data: EventData<TEvents, K>): void;
-    /**
-     * Broadcast an event with any data (bypasses type checking).
-     * Use sparingly - prefer the typed broadcast() method.
-     */
-    broadcastRaw(event: string, data?: unknown): void;
     /**
      * Send an event to a specific controller.
      *
@@ -310,11 +424,6 @@ export interface Screen<TEvents extends EventMap = EventMap> {
      * ```
      */
     sendToController<K extends EventNames<TEvents>>(playerIndex: PlayerIndex, event: K, data: EventData<TEvents, K>): void;
-    /**
-     * Send to controller with any data (bypasses type checking).
-     * Use sparingly - prefer the typed sendToController() method.
-     */
-    sendToControllerRaw(playerIndex: PlayerIndex, event: string, data?: unknown): void;
     /**
      * Signal that the game is over and send results.
      * This will broadcast a game-over event to all controllers.
@@ -345,6 +454,17 @@ export interface Screen<TEvents extends EventMap = EventMap> {
      * ```
      */
     signalReady(): void;
+    /**
+     * Subscribe to a lifecycle event or a user-defined game event.
+     *
+     * Lifecycle events use `$`-prefixed names. Use `LifecycleEvent` constants
+     * for type-safe subscription:
+     * ```ts
+     * screen.on(LifecycleEvent.CONTROLLER_JOIN, (pi, info) => { ... });
+     * screen.on('tap', (pi, data) => { ... }); // user event
+     * ```
+     */
+    on<K extends ScreenLifecycleEvent>(event: K, handler: ScreenLifecycleHandlers[K]): () => void;
     /**
      * Add a listener for a specific event after construction.
      * Can be called before the screen is ready -- handlers are queued
@@ -365,6 +485,7 @@ export interface Screen<TEvents extends EventMap = EventMap> {
      * ```
      */
     on<K extends EventNames<TEvents>>(event: K, handler: ScreenEventHandler<EventData<TEvents, K>>): () => void;
+    once<K extends ScreenLifecycleEvent>(event: K, handler: ScreenLifecycleHandlers[K]): () => void;
     /**
      * Add a one-time listener that auto-removes after first call.
      *
@@ -372,10 +493,19 @@ export interface Screen<TEvents extends EventMap = EventMap> {
      * `off(event, originalHandler)`. Use the returned unsubscribe function instead.
      */
     once<K extends EventNames<TEvents>>(event: K, handler: ScreenEventHandler<EventData<TEvents, K>>): () => void;
+    off<K extends ScreenLifecycleEvent>(event: K, handler?: ScreenLifecycleHandlers[K]): void;
     /**
      * Remove a specific listener or all listeners for an event.
      */
     off<K extends EventNames<TEvents>>(event: K, handler?: ScreenEventHandler<EventData<TEvents, K>>): void;
+    /**
+     * Remove all event listeners, or all listeners for a specific event.
+     * Only removes user event listeners registered via on()/once().
+     * Lifecycle callbacks (onControllerJoin, onAllReady, etc.) are not affected.
+     *
+     * @param event - Optional event name. If omitted, removes ALL user event listeners.
+     */
+    removeAllListeners(event?: string): void;
     /**
      * Get a specific controller by player index.
      * Returns undefined if not found.
@@ -385,14 +515,6 @@ export interface Screen<TEvents extends EventMap = EventMap> {
      * Get the number of connected controllers.
      */
     getControllerCount(): number;
-    /**
-     * Check if there is at least one connected controller.
-     * Useful for detecting when all players have disconnected
-     * (e.g., to pause the game or show a waiting screen).
-     *
-     * Screen-only method. Controller instances can check their own connection status directly.
-     */
-    hasAnyConnectedControllers(): boolean;
     /**
      * Clean up all resources and disconnect.
      * Call this when unmounting/destroying your game.
@@ -424,7 +546,7 @@ export type ControllerEventHandler<TData = unknown> = (data: TData) => void;
  * controller.send('tap', { x: 100, y: 200 });
  * ```
  */
-export interface ControllerConfig<_TEvents extends EventMap = EventMap> {
+export interface ControllerConfig {
     /**
      * Enable debug mode for verbose logging.
      * @default false
@@ -440,6 +562,19 @@ export interface ControllerConfig<_TEvents extends EventMap = EventMap> {
      * @default 10000
      */
     timeout?: number;
+    /**
+     * Automatically signal ready after initialization.
+     * When true (default), the SDK calls signalReady() automatically after init completes.
+     * Set to false if your game needs to load resources before signaling ready.
+     * @default true
+     */
+    autoReady?: boolean;
+    /**
+     * Custom transport implementation.
+     * If provided, uses this instead of the default PostMessageTransport.
+     * The bridge handshake (_bridge:init) still occurs via postMessage.
+     */
+    transport?: Transport;
 }
 /**
  * Controller instance - the main interface for the player/phone side.
@@ -470,13 +605,17 @@ export interface ControllerConfig<_TEvents extends EventMap = EventMap> {
  */
 export interface Controller<TEvents extends EventMap = EventMap> {
     /** My player index (0, 1, 2, ...). */
-    readonly myIndex: PlayerIndex;
+    readonly myPlayerIndex: PlayerIndex;
     /** The room code for this game session. */
     readonly roomCode: RoomCode;
     /** Whether the controller is initialized and ready. */
     readonly isReady: boolean;
     /** Whether the controller has been destroyed. */
     readonly isDestroyed: boolean;
+    /** Whether the connection to the server is active. */
+    readonly isConnected: boolean;
+    /** Protocol version negotiated with the parent frame. */
+    readonly protocolVersion: number;
     /**
      * Read-only list of all known controllers (players) in the room.
      * Returns full ControllerInfo including playerIndex, nickname, connected status, and appearance.
@@ -542,13 +681,6 @@ export interface Controller<TEvents extends EventMap = EventMap> {
      * @returns Unsubscribe function to remove the callback
      */
     onCharacterUpdated(callback: (playerIndex: PlayerIndex, appearance: CharacterAppearance | null) => void): () => void;
-    /**
-     * Register a callback for when the server rate-limits an event.
-     *
-     * @param callback - Called with the rate-limited event name
-     * @returns Unsubscribe function to remove the callback
-     */
-    onRateLimited(callback: (event: string) => void): () => void;
     /**
      * Register a callback for when an error occurs.
      * If no error callback is registered, errors are logged to console in debug mode.
@@ -557,10 +689,31 @@ export interface Controller<TEvents extends EventMap = EventMap> {
      * @returns Unsubscribe function to remove the callback
      */
     onError(callback: (error: SmoreError) => void): () => void;
+    /**
+     * Register a callback for when the game ends.
+     * Called when the Screen calls gameOver().
+     *
+     * @param callback - Called with optional game results
+     * @returns Unsubscribe function to remove the callback
+     */
+    onGameOver(callback: (results?: GameResults) => void): () => void;
+    /**
+     * Register a callback for when the connection status changes.
+     * Called when the connection to the server is lost or restored.
+     *
+     * @param callback - Called with true (connected) or false (disconnected)
+     * @returns Unsubscribe function to remove the callback
+     */
+    onConnectionChange(callback: (connected: boolean) => void): () => void;
     /**
      * Returns the number of currently connected players.
      */
     getControllerCount(): number;
+    /**
+     * Get a specific controller by player index.
+     * Returns undefined if not found.
+     */
+    getController(playerIndex: PlayerIndex): ControllerInfo | undefined;
     /**
      * Send an event to the screen.
      *
@@ -577,11 +730,6 @@ export interface Controller<TEvents extends EventMap = EventMap> {
      * ```
      */
     send<K extends EventNames<TEvents>>(event: K, data: EventData<TEvents, K>): void;
-    /**
-     * Send with any data (bypasses type checking).
-     * Use sparingly - prefer the typed send() method.
-     */
-    sendRaw(event: string, data?: unknown): void;
     /**
      * Signal that this controller has finished loading resources and is ready to start.
      *
@@ -596,6 +744,17 @@ export interface Controller<TEvents extends EventMap = EventMap> {
      * ```
      */
     signalReady(): void;
+    /**
+     * Subscribe to a lifecycle event or a user-defined game event.
+     *
+     * Lifecycle events use `$`-prefixed names. Use `LifecycleEvent` constants
+     * for type-safe subscription:
+     * ```ts
+     * controller.on(LifecycleEvent.CONTROLLER_JOIN, (pi, info) => { ... });
+     * controller.on('phase-update', (data) => { ... }); // user event
+     * ```
+     */
+    on<K extends ControllerLifecycleEvent>(event: K, handler: ControllerLifecycleHandlers[K]): () => void;
     /**
      * Add a listener for a specific event after construction.
      * Can be called before the controller is ready -- handlers are queued
@@ -621,6 +780,7 @@ export interface Controller<TEvents extends EventMap = EventMap> {
      * ```
      */
     on<K extends EventNames<TEvents>>(event: K, handler: ControllerEventHandler<EventData<TEvents, K>>): () => void;
+    once<K extends ControllerLifecycleEvent>(event: K, handler: ControllerLifecycleHandlers[K]): () => void;
     /**
      * Add a one-time listener that auto-removes after first call.
      *
@@ -628,47 +788,25 @@ export interface Controller<TEvents extends EventMap = EventMap> {
      * `off(event, originalHandler)`. Use the returned unsubscribe function instead.
      */
     once<K extends EventNames<TEvents>>(event: K, handler: ControllerEventHandler<EventData<TEvents, K>>): () => void;
+    off<K extends ControllerLifecycleEvent>(event: K, handler?: ControllerLifecycleHandlers[K]): void;
     /**
      * Remove a specific listener or all listeners for an event.
      */
     off<K extends EventNames<TEvents>>(event: K, handler?: ControllerEventHandler<EventData<TEvents, K>>): void;
+    /**
+     * Remove all event listeners, or all listeners for a specific event.
+     * Only removes user event listeners registered via on()/once().
+     * Lifecycle callbacks (onControllerJoin, onAllReady, etc.) are not affected.
+     *
+     * @param event - Optional event name. If omitted, removes ALL user event listeners.
+     */
+    removeAllListeners(event?: string): void;
     /**
      * Clean up all resources and disconnect.
      * Call this when unmounting/destroying your game.
      */
     destroy(): void;
 }
-/**
- * Game results structure for gameOver().
- * Flexible to accommodate different game types.
- */
-export interface GameResults {
-    /** Player scores indexed by player index */
-    scores?: Record<PlayerIndex, number>;
-    /** Winner's player index (or -1 for no winner/tie) */
-    winner?: PlayerIndex;
-    /** Ranked player indices from first to last */
-    rankings?: PlayerIndex[];
-    /** Additional custom data */
-    [key: string]: unknown;
-}
-/**
- * Error codes for SDK errors.
- */
-export type SmoreErrorCode = 'TIMEOUT' | 'NOT_READY' | 'DESTROYED' | 'INVALID_EVENT' | 'INVALID_PLAYER' | 'CONNECTION_LOST' | 'INIT_FAILED' | 'UNKNOWN';
-/**
- * Structured error type for SDK errors.
- */
-export interface SmoreError {
-    /** Error code for programmatic handling */
-    code: SmoreErrorCode;
-    /** Human-readable error message */
-    message: string;
-    /** Original error if available */
-    cause?: Error;
-    /** Additional context */
-    details?: Record<string, unknown>;
-}
 /**
  * Log levels for debug output.
  */
@@ -692,274 +830,4 @@ export interface DebugOptions {
     /** Custom logger function */
     logger?: (level: LogLevel, message: string, data?: unknown) => void;
 }
-/**
- * Create a Screen instance for the host/TV side of your game.
- *
- * Returns a Screen instance synchronously. The screen begins listening
- * for the bridge init message immediately. Use the `.ready` promise
- * to await full initialization.
- *
- * @template TEvents - Event map type for type-safe events
- * @param config - Screen configuration (debug, parentOrigin, timeout)
- * @returns Screen instance (synchronous)
- *
- * @example
- * ```ts
- * const screen = createScreen<MyEvents>({ debug: true });
- *
- * screen.on('tap', (playerIndex, data) => {
- *   screen.broadcast('round-result', { ... });
- * });
- *
- * screen.onAllReady(() => startGame());
- * screen.onControllerJoin((pi, info) => addPlayer(pi, info));
- *
- * await screen.ready;
- * ```
- */
-export declare function createScreen<TEvents extends EventMap = EventMap>(config?: ScreenConfig<TEvents>): Screen<TEvents>;
-/**
- * Create a Controller instance for the player/phone side of your game.
- *
- * Returns a Controller instance synchronously. The controller begins listening
- * for the bridge init message immediately. Use the `.ready` promise
- * to await full initialization.
- *
- * @template TEvents - Event map type for type-safe events
- * @param config - Controller configuration (debug, parentOrigin, timeout)
- * @returns Controller instance (synchronous)
- *
- * @example
- * ```ts
- * const controller = createController<MyEvents>({ debug: true });
- *
- * controller.on('phase-update', (data) => setPhase(data.phase));
- * controller.onAllReady(() => console.log('Ready!'));
- *
- * await controller.ready;
- * controller.send('tap', { x: 100, y: 200 });
- * ```
- */
-export declare function createController<TEvents extends EventMap = EventMap>(config?: ControllerConfig<TEvents>): Controller<TEvents>;
-/**
- * Options for creating mock instances.
- */
-export interface MockOptions {
-    /** Initial room code */
-    roomCode?: RoomCode;
-    /** Initial controllers for Screen mock */
-    controllers?: ControllerInfo[];
-    /** My index for Controller mock */
-    myIndex?: PlayerIndex;
-    /** Auto-trigger ready state */
-    autoReady?: boolean;
-}
-/**
- * Mock Screen for testing.
- * Extends Screen with additional test utilities.
- */
-export interface MockScreen<TEvents extends EventMap = EventMap> extends Screen<TEvents> {
-    /**
-     * Simulate receiving an event from a controller.
-     * Triggers the corresponding listener.
-     */
-    simulateEvent<K extends EventNames<TEvents>>(playerIndex: PlayerIndex, event: K, data: EventData<TEvents, K>): void;
-    /**
-     * Simulate a controller joining.
-     * Triggers onControllerJoin callbacks.
-     */
-    simulateControllerJoin(info: ControllerInfo): void;
-    /**
-     * Simulate a controller leaving.
-     * Triggers onControllerLeave callbacks.
-     */
-    simulateControllerLeave(playerIndex: PlayerIndex): void;
-    /**
-     * Simulate a controller disconnecting temporarily.
-     * Triggers onControllerDisconnect callbacks and marks player as disconnected.
-     */
-    simulateControllerDisconnect(playerIndex: PlayerIndex): void;
-    /**
-     * Simulate a controller reconnecting after a disconnect.
-     * Triggers onControllerReconnect callbacks and marks player as connected.
-     */
-    simulateControllerReconnect(playerIndex: PlayerIndex): void;
-    /**
-     * Get all events that were broadcast.
-     * Returns array of { event, data } objects.
-     */
-    getBroadcasts(): Array<{
-        event: string;
-        data: unknown;
-    }>;
-    /**
-     * Get all events sent to a specific controller.
-     */
-    getSentToController(playerIndex: PlayerIndex): Array<{
-        event: string;
-        data: unknown;
-    }>;
-    /**
-     * Clear recorded events.
-     */
-    clearRecordedEvents(): void;
-    /**
-     * Manually trigger the ready state.
-     */
-    triggerReady(): void;
-    /**
-     * Simulate a player's character appearance being updated.
-     * Triggers onCharacterUpdated callbacks and updates the controller's appearance.
-     */
-    simulateCharacterUpdate(playerIndex: PlayerIndex, appearance: CharacterAppearance | null): void;
-    /**
-     * Simulate the server rate-limiting an event.
-     * Triggers onRateLimited callbacks.
-     */
-    simulateRateLimited(event: string): void;
-    /**
-     * Simulate the all-ready event (all participants signaled ready).
-     * Triggers onAllReady callbacks.
-     */
-    simulateAllReady(): void;
-    /** Simulate an error. Triggers onError callbacks. */
-    simulateError(error: any): void;
-}
-/**
- * Mock Controller for testing.
- * Extends Controller with additional test utilities.
- */
-export interface MockController<TEvents extends EventMap = EventMap> extends Controller<TEvents> {
-    /**
-     * Simulate receiving an event from the screen.
-     * Triggers the corresponding listener.
-     */
-    simulateEvent<K extends EventNames<TEvents>>(event: K, data: EventData<TEvents, K>): void;
-    /**
-     * Get all events that were sent to the screen.
-     * Returns array of { event, data } objects.
-     */
-    getSentEvents(): Array<{
-        event: string;
-        data: unknown;
-    }>;
-    /**
-     * Clear recorded events.
-     */
-    clearRecordedEvents(): void;
-    /**
-     * Manually trigger the ready state.
-     */
-    triggerReady(): void;
-    /**
-     * Simulate another player joining the room.
-     * Triggers onControllerJoin callbacks.
-     */
-    simulatePlayerJoin(playerIndex: PlayerIndex, info: ControllerInfo): void;
-    /**
-     * Simulate another player leaving the room.
-     * Triggers onControllerLeave callbacks.
-     */
-    simulatePlayerLeave(playerIndex: PlayerIndex): void;
-    /**
-     * Simulate another player disconnecting temporarily.
-     * Triggers onControllerDisconnect callbacks.
-     */
-    simulatePlayerDisconnect(playerIndex: PlayerIndex): void;
-    /**
-     * Simulate another player reconnecting after a disconnect.
-     * Triggers onControllerReconnect callbacks.
-     */
-    simulatePlayerReconnect(playerIndex: PlayerIndex, info: ControllerInfo): void;
-    /**
-     * Simulate a player's character appearance being updated.
-     * Triggers onCharacterUpdated callbacks and updates the controller's appearance.
-     */
-    simulateCharacterUpdate(playerIndex: PlayerIndex, appearance: CharacterAppearance | null): void;
-    /**
-     * Simulate the server rate-limiting an event.
-     * Triggers onRateLimited callbacks.
-     */
-    simulateRateLimited(event: string): void;
-    /**
-     * Simulate the all-ready event (all participants signaled ready).
-     * Triggers onAllReady callbacks.
-     */
-    simulateAllReady(): void;
-    /** Simulate an error. Triggers onError callbacks. */
-    simulateError(error: any): void;
-}
-/**
- * Create a mock Screen for testing.
- *
- * @example
- * ```ts
- * const mockScreen = createMockScreen<MyEvents>({
- *   controllers: [
- *     { playerIndex: 0, nickname: 'Player 1', connected: true },
- *     { playerIndex: 1, nickname: 'Player 2', connected: true },
- *   ],
- * });
- *
- * mockScreen.on('tap', (pi, data) => handleTap(pi, data));
- * mockScreen.onAllReady(() => startGame());
- *
- * // Simulate player input
- * mockScreen.simulateEvent(0, 'tap', { x: 100, y: 200 });
- *
- * // Check what was broadcast
- * expect(mockScreen.getBroadcasts()).toContainEqual({
- *   event: 'score-update',
- *   data: { scores: { 0: 10 } },
- * });
- * ```
- */
-export declare function createMockScreen<TEvents extends EventMap = EventMap>(options?: MockOptions): MockScreen<TEvents>;
-/**
- * Create a mock Controller for testing.
- *
- * @example
- * ```ts
- * const mockController = createMockController<MyEvents>({
- *   myIndex: 0,
- * });
- *
- * mockController.on('your-turn', (data) => handleTurn(data));
- * mockController.onAllReady(() => console.log('Ready!'));
- *
- * // Simulate receiving from screen
- * mockController.simulateEvent('your-turn', { timeLimit: 30 });
- *
- * // Check what was sent
- * expect(mockController.getSentEvents()).toContainEqual({
- *   event: 'answer',
- *   data: { choice: 2 },
- * });
- * ```
- */
-export declare function createMockController<TEvents extends EventMap = EventMap>(options?: MockOptions): MockController<TEvents>;
-/**
- * Game metadata from game.json manifest.
- * SYNC: Also defined in game-project/types/src/types.ts - keep in sync.
- */
-export interface GameMetadata {
-    /** Unique game identifier */
-    id: string;
-    /** Display title */
-    title: string;
-    /** Game description */
-    description: string;
-    /** Minimum players required */
-    minPlayers: number;
-    /** Maximum players supported */
-    maxPlayers: number;
-    /** Game categories/tags */
-    categories: string[];
-    /** Thumbnail image URL */
-    thumbnail?: string;
-    /** Author/developer name */
-    author?: string;
-    /** Game version */
-    version?: string;
-}
 //# sourceMappingURL=types.d.ts.map