@smoregg/sdk 1.2.0 → 2.0.0

package/dist/types/types.d.ts

@@ -45,12 +45,12 @@ export type RoomCode = string;
  * }
  *
  * // With explicit generic -- full type safety
- * const screen = await createScreen<MyGameEvents>({ ... });
- * screen.broadcast('tap', { x: 1, y: 2 }); // Type-checked
+ * const screen = createScreen<MyGameEvents>({ debug: true });
+ * screen.on('tap', (pi, data) => { ... });
+ * await screen.ready;
  *
  * // Without generic -- no type safety (not recommended)
- * const screen = await createScreen({ ... });
- * screen.broadcastRaw('anything', 'any data'); // No checking
+ * const screen = createScreen();
  * ```
  *
  * @example Event naming conventions
@@ -64,6 +64,7 @@ export type RoomCode = string;
  * ```
  */
 export interface EventMap {
+    [key: string]: unknown;
 }
 /**
  * Extract event names from an event map.
@@ -128,124 +129,27 @@ export interface ControllerInfo {
  * Receives the player index and event data.
  */
 export type ScreenEventHandler<TData = unknown> = (playerIndex: PlayerIndex, data: TData) => void;
-/**
- * Map of event listeners for Screen.
- * Each handler receives (playerIndex, data).
- */
-export type ScreenListeners<TEvents extends EventMap> = {
-    [K in EventNames<TEvents>]?: ScreenEventHandler<EventData<TEvents, K>>;
-};
 /**
  * Configuration options for creating a Screen instance.
  *
- * @template TEvents - Event map type for type-safe events
+ * In the event emitter pattern, only static options are passed via config.
+ * All lifecycle callbacks and event listeners are registered via methods
+ * on the returned Screen instance.
  *
- * @example Callback-based (immediate)
- * ```ts
- * const screen = createScreen<MyEvents>({
- *   onReady: () => {
- *     console.log('Screen ready!');
- *   },
- *   listeners: {
- *     tap: (playerIndex, data) => handleTap(playerIndex, data),
- *   },
- * });
- * ```
+ * @template TEvents - Event map type for type-safe events
  *
- * @example Promise-based (await)
+ * @example
  * ```ts
- * const screen = await createScreen<MyEvents>({
- *   listeners: {
- *     tap: (playerIndex, data) => handleTap(playerIndex, data),
- *   },
- * });
- * // Screen is ready here
- * ```
+ * const screen = createScreen<MyEvents>({ debug: true });
  *
- * ## Best Practices: Callbacks vs Events
+ * screen.on('tap', (playerIndex, data) => handleTap(playerIndex, data));
+ * screen.onAllReady(() => startCountdown());
+ * screen.onControllerJoin((pi, info) => console.log('Joined:', pi));
  *
- * - **Config callbacks** (`onReady`, `onControllerJoin`, etc.): Use for essential lifecycle events
- *   that should always be handled. These are registered once at creation and cannot be removed.
- *
- * - **`on()`/`off()` methods**: Use for dynamic event handlers that may need to be added/removed
- *   during gameplay. These support multiple handlers per event and can be cleaned up with `off()`.
- *
- * For most games, config callbacks are sufficient. Use `on()`/`off()` only when you need
- * dynamic handler management (e.g., different handlers per game phase).
+ * await screen.ready;
+ * ```
  */
-export interface ScreenConfig<TEvents extends EventMap = EventMap> {
-    /**
-     * Called when the screen is initialized and ready.
-     * If not provided, use the Promise returned by createScreen().
-     */
-    onReady?: () => void;
-    /**
-     * Called when a new controller (player) joins the room.
-     */
-    onControllerJoin?: (playerIndex: PlayerIndex, info: ControllerInfo) => void;
-    /**
-     * Called when a controller (player) leaves the room.
-     */
-    onControllerLeave?: (playerIndex: PlayerIndex) => void;
-    /**
-     * Called when a controller temporarily disconnects (e.g., lost WiFi).
-     * The player may reconnect — see onControllerReconnect.
-     */
-    onControllerDisconnect?: (playerIndex: PlayerIndex) => void;
-    /**
-     * Called when a controller reconnects after a disconnect.
-     */
-    onControllerReconnect?: (playerIndex: PlayerIndex, info: ControllerInfo) => void;
-    /**
-     * Called when a player's character appearance is updated.
-     *
-     * @param playerIndex - The player whose character changed
-     * @param appearance - The new character appearance, or null if removed/reset
-     *
-     * @note Sending an empty/null character update from the platform resets the
-     * player's appearance to null (default state). This allows players to clear
-     * their character selection.
-     */
-    onCharacterUpdated?: (playerIndex: PlayerIndex, appearance: CharacterAppearance | null) => void;
-    /**
-     * Called when the server rate-limits an event from this client.
-     *
-     * @param event - The event name that was rate-limited
-     */
-    onRateLimited?: (event: string) => void;
-    /**
-     * Called when all participants (screen + all connected controllers) have signaled ready.
-     * Use this as the trigger to start your game's countdown or gameplay.
-     *
-     * The ready/start synchronization flow:
-     * 1. Game loads resources (Phaser assets, images, etc.)
-     * 2. Game calls `screen.signalReady()` when loading is complete
-     * 3. Each controller also calls `controller.signalReady()` when ready
-     * 4. Server broadcasts all-ready when everyone has signaled
-     * 5. This callback fires on all devices simultaneously
-     */
-    onAllReady?: () => void;
-    /**
-     * Event listeners for messages from controllers.
-     * Keys are event names, values are handler functions.
-     *
-     * **Relationship with on() method:**
-     * - Listeners passed in config are registered during initialization
-     * - Listeners added via on() are registered dynamically after initialization
-     * - Both types of listeners coexist and are called in registration order
-     *
-     * **Important:** Lifecycle listeners (onReady, onControllerJoin, etc.) passed
-     * in config are NOT removable via off(). They are permanent for the lifetime
-     * of the Screen instance. Only listeners added via on() can be removed via off().
-     *
-     * @see Best Practices section above for guidance on when to use `listeners` config vs `on()` method.
-     */
-    listeners?: ScreenListeners<TEvents>;
-    /**
-     * Called when an error occurs.
-     * If not provided, errors are logged to console in debug mode.
-     */
-    onError?: (error: SmoreError) => void;
+export interface ScreenConfig<_TEvents extends EventMap = EventMap> {
     /**
      * Enable debug mode for verbose logging.
      * @default false
@@ -262,32 +166,25 @@ 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
-     * (e.g., Phaser assets, large images, audio files).
-     *
-     * @default true
-     */
-    autoReady?: boolean;
 }
 /**
  * Screen instance - the main interface for the host/TV side of your game.
  *
+ * Uses an event emitter pattern: lifecycle callbacks and event listeners
+ * are registered via methods on the instance, not via config.
+ *
  * @template TEvents - Event map type for type-safe events
  *
  * @example
  * ```ts
- * const screen = await createScreen<MyEvents>({ ... });
+ * const screen = createScreen<MyEvents>({ debug: true });
  *
- * // Broadcast to all controllers
- * screen.broadcast('phase-update', { phase: 'playing' });
- *
- * // Send to specific controller
- * screen.sendToController(0, 'your-turn', { timeLimit: 30 });
+ * screen.on('tap', (pi, data) => handleTap(pi, data));
+ * screen.onAllReady(() => startGame());
+ * screen.onControllerJoin((pi, info) => addPlayer(pi, info));
  *
- * // End the game
+ * await screen.ready;
+ * screen.broadcast('phase-update', { phase: 'playing' });
  * screen.gameOver({ scores: { 0: 100, 1: 75 } });
  * ```
  */
@@ -306,6 +203,77 @@ export interface Screen<TEvents extends EventMap = EventMap> {
     readonly isReady: boolean;
     /** Whether the screen has been destroyed. */
     readonly isDestroyed: boolean;
+    /**
+     * A Promise that resolves when the screen is initialized and ready.
+     * Use this to await readiness after creating a screen synchronously.
+     *
+     * @example
+     * ```ts
+     * const screen = createScreen<MyEvents>();
+     * screen.on('tap', handler);
+     * await screen.ready;
+     * screen.broadcast('start', {});
+     * ```
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Register a callback for when all participants are ready (all-ready event).
+     * If the all-ready event has already fired when called, the callback fires immediately.
+     *
+     * @param callback - Called when all participants signal ready
+     * @returns Unsubscribe function to remove the callback
+     */
+    onAllReady(callback: () => void): () => void;
+    /**
+     * Register a callback for when a controller (player) joins the room.
+     *
+     * @param callback - Called with player index and controller info
+     * @returns Unsubscribe function to remove the callback
+     */
+    onControllerJoin(callback: (playerIndex: PlayerIndex, info: ControllerInfo) => void): () => void;
+    /**
+     * Register a callback for when a controller (player) leaves the room.
+     *
+     * @param callback - Called with the leaving player's index
+     * @returns Unsubscribe function to remove the callback
+     */
+    onControllerLeave(callback: (playerIndex: PlayerIndex) => void): () => void;
+    /**
+     * Register a callback for when a controller temporarily disconnects.
+     *
+     * @param callback - Called with the disconnected player's index
+     * @returns Unsubscribe function to remove the callback
+     */
+    onControllerDisconnect(callback: (playerIndex: PlayerIndex) => void): () => void;
+    /**
+     * Register a callback for when a controller reconnects after a disconnect.
+     *
+     * @param callback - Called with player index and updated controller info
+     * @returns Unsubscribe function to remove the callback
+     */
+    onControllerReconnect(callback: (playerIndex: PlayerIndex, info: ControllerInfo) => void): () => void;
+    /**
+     * Register a callback for when a player's character appearance is updated.
+     *
+     * @param callback - Called with player index and new appearance (or null if reset)
+     * @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.
+     *
+     * @param callback - Called with the error object
+     * @returns Unsubscribe function to remove the callback
+     */
+    onError(callback: (error: SmoreError) => void): () => void;
     /**
      * Broadcast an event to all connected controllers.
      *
@@ -328,7 +296,7 @@ export interface Screen<TEvents extends EventMap = EventMap> {
     /**
      * Send an event to a specific controller.
      *
-     * Screen → Controller direction only. For Controller → Screen, see `send()`.
+     * Screen -> Controller direction only. For Controller -> Screen, see `send()`.
      *
      * @param playerIndex - Target controller's player index
      * @param event - Event name (must match TEvents keys)
@@ -379,6 +347,8 @@ export interface Screen<TEvents extends EventMap = EventMap> {
     signalReady(): void;
     /**
      * Add a listener for a specific event after construction.
+     * Can be called before the screen is ready -- handlers are queued
+     * and activated when the transport becomes available.
      *
      * @param event - Event name
      * @param handler - Handler function (playerIndex, data) => void
@@ -434,122 +404,27 @@ export interface Screen<TEvents extends EventMap = EventMap> {
  * Receives only the event data (no player index needed).
  */
 export type ControllerEventHandler<TData = unknown> = (data: TData) => void;
-/**
- * Map of event listeners for Controller.
- * Each handler receives (data) only.
- */
-export type ControllerListeners<TEvents extends EventMap> = {
-    [K in EventNames<TEvents>]?: ControllerEventHandler<EventData<TEvents, K>>;
-};
 /**
  * Configuration options for creating a Controller instance.
  *
+ * In the event emitter pattern, only static options are passed via config.
+ * All lifecycle callbacks and event listeners are registered via methods
+ * on the returned Controller instance.
+ *
  * @template TEvents - Event map type for type-safe events
  *
- * @example Callback-based (immediate)
+ * @example
  * ```ts
- * const controller = createController<MyEvents>({
- *   onReady: () => {
- *     console.log(`Ready! My index: ${controller.myIndex}`);
- *   },
- *   listeners: {
- *     'phase-update': (data) => handlePhase(data.phase),
- *   },
- * });
- * ```
+ * const controller = createController<MyEvents>({ debug: true });
  *
- * @example Promise-based (await)
- * ```ts
- * const controller = await createController<MyEvents>({
- *   listeners: {
- *     'phase-update': (data) => handlePhase(data.phase),
- *   },
- * });
- * console.log(`Ready! My index: ${controller.myIndex}`);
+ * controller.on('phase-update', (data) => handlePhase(data.phase));
+ * controller.onAllReady(() => console.log('Ready!'));
+ *
+ * await controller.ready;
+ * controller.send('tap', { x: 100, y: 200 });
  * ```
  */
-export interface ControllerConfig<TEvents extends EventMap = EventMap> {
-    /**
-     * Called when the controller is initialized and ready.
-     * If not provided, use the Promise returned by createController().
-     */
-    onReady?: () => void;
-    /**
-     * Called when another player joins the room.
-     */
-    onControllerJoin?: (playerIndex: PlayerIndex, info: ControllerInfo) => void;
-    /**
-     * Called when another player leaves the room.
-     */
-    onControllerLeave?: (playerIndex: PlayerIndex) => void;
-    /**
-     * Called when another player temporarily disconnects.
-     */
-    onControllerDisconnect?: (playerIndex: PlayerIndex) => void;
-    /**
-     * Called when another player reconnects after a disconnect.
-     */
-    onControllerReconnect?: (playerIndex: PlayerIndex, info: ControllerInfo) => void;
-    /**
-     * Called when a player's character appearance is updated.
-     *
-     * @param playerIndex - The player whose character changed
-     * @param appearance - The new character appearance, or null if removed/reset
-     *
-     * @note Sending an empty/null character update from the platform resets the
-     * player's appearance to null (default state). This allows players to clear
-     * their character selection.
-     */
-    onCharacterUpdated?: (playerIndex: PlayerIndex, appearance: CharacterAppearance | null) => void;
-    /**
-     * Called when the server rate-limits an event from this client.
-     *
-     * @param event - The event name that was rate-limited
-     */
-    onRateLimited?: (event: string) => void;
-    /**
-     * Called when all participants (screen + all connected controllers) have signaled ready.
-     * Use this as the trigger to start your game's countdown or gameplay.
-     */
-    onAllReady?: () => void;
-    /**
-     * Called when the host/screen disconnects.
-     * The game may become unresponsive until the host reconnects.
-     *
-     * @experimental This callback is reserved for future use and currently non-functional.
-     * The server emits `smore:host-disconnected` but it is not yet forwarded to SDK games
-     * through the IframeGameBridge GAME_FACING_EVENTS allowlist. Setting this callback
-     * will produce a runtime warning. It will become functional in a future SDK release.
-     */
-    onHostDisconnect?: () => void;
-    /**
-     * Called when the host/screen reconnects after a disconnect.
-     *
-     * @experimental This callback is reserved for future use and currently non-functional.
-     * The server emits `smore:host-reconnected` but it is not yet forwarded to SDK games
-     * through the IframeGameBridge GAME_FACING_EVENTS allowlist. Setting this callback
-     * will produce a runtime warning. It will become functional in a future SDK release.
-     */
-    onHostReconnect?: () => void;
-    /**
-     * Event listeners for messages from the screen.
-     * Keys are event names, values are handler functions.
-     *
-     * **Relationship with on() method:**
-     * - Listeners passed in config are registered during initialization
-     * - Listeners added via on() are registered dynamically after initialization
-     * - Both types of listeners coexist and are called in registration order
-     *
-     * **Important:** Lifecycle listeners (onReady, onControllerJoin, etc.) passed
-     * in config are NOT removable via off(). They are permanent for the lifetime
-     * of the Controller instance. Only listeners added via on() can be removed via off().
-     */
-    listeners?: ControllerListeners<TEvents>;
-    /**
-     * Called when an error occurs.
-     * If not provided, errors are logged to console in debug mode.
-     */
-    onError?: (error: SmoreError) => void;
+export interface ControllerConfig<_TEvents extends EventMap = EventMap> {
     /**
      * Enable debug mode for verbose logging.
      * @default false
@@ -565,26 +440,23 @@ 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
-     * (e.g., Phaser assets, large images, audio files).
-     *
-     * @default true
-     */
-    autoReady?: boolean;
 }
 /**
  * Controller instance - the main interface for the player/phone side.
  *
+ * Uses an event emitter pattern: lifecycle callbacks and event listeners
+ * are registered via methods on the instance, not via config.
+ *
  * @template TEvents - Event map type for type-safe events
  *
  * @example
  * ```ts
- * const controller = await createController<MyEvents>({ ... });
+ * const controller = createController<MyEvents>({ debug: true });
+ *
+ * controller.on('phase-update', (data) => setPhase(data.phase));
+ * controller.onAllReady(() => console.log('Game starting!'));
  *
- * // Send input to screen
+ * await controller.ready;
  * controller.send('tap', { x: 100, y: 200 });
  * ```
  *
@@ -594,7 +466,7 @@ export interface ControllerConfig<TEvents extends EventMap = EventMap> {
  * This is intentional: Controller-to-Controller (C2C) communication is not supported.
  * All coordination between controllers must go through the Screen.
  *
- * Flow: Controller.send() → Screen receives → Screen.broadcast() or Screen.sendToController()
+ * Flow: Controller.send() -> Screen receives -> Screen.broadcast() or Screen.sendToController()
  */
 export interface Controller<TEvents extends EventMap = EventMap> {
     /** My player index (0, 1, 2, ...). */
@@ -614,6 +486,77 @@ export interface Controller<TEvents extends EventMap = EventMap> {
      * Cache the result in a local variable if you need to access it repeatedly.
      */
     readonly controllers: readonly ControllerInfo[];
+    /**
+     * A Promise that resolves when the controller is initialized and ready.
+     * Use this to await readiness after creating a controller synchronously.
+     *
+     * @example
+     * ```ts
+     * const controller = createController<MyEvents>();
+     * controller.on('phase-update', handler);
+     * await controller.ready;
+     * controller.send('tap', { x: 0, y: 0 });
+     * ```
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Register a callback for when all participants are ready (all-ready event).
+     * If the all-ready event has already fired when called, the callback fires immediately.
+     *
+     * @param callback - Called when all participants signal ready
+     * @returns Unsubscribe function to remove the callback
+     */
+    onAllReady(callback: () => void): () => void;
+    /**
+     * Register a callback for when another player joins the room.
+     *
+     * @param callback - Called with player index and controller info
+     * @returns Unsubscribe function to remove the callback
+     */
+    onControllerJoin(callback: (playerIndex: PlayerIndex, info: ControllerInfo) => void): () => void;
+    /**
+     * Register a callback for when another player leaves the room.
+     *
+     * @param callback - Called with the leaving player's index
+     * @returns Unsubscribe function to remove the callback
+     */
+    onControllerLeave(callback: (playerIndex: PlayerIndex) => void): () => void;
+    /**
+     * Register a callback for when another player temporarily disconnects.
+     *
+     * @param callback - Called with the disconnected player's index
+     * @returns Unsubscribe function to remove the callback
+     */
+    onControllerDisconnect(callback: (playerIndex: PlayerIndex) => void): () => void;
+    /**
+     * Register a callback for when another player reconnects after a disconnect.
+     *
+     * @param callback - Called with player index and updated controller info
+     * @returns Unsubscribe function to remove the callback
+     */
+    onControllerReconnect(callback: (playerIndex: PlayerIndex, info: ControllerInfo) => void): () => void;
+    /**
+     * Register a callback for when a player's character appearance is updated.
+     *
+     * @param callback - Called with player index and new appearance (or null if reset)
+     * @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.
+     *
+     * @param callback - Called with the error object
+     * @returns Unsubscribe function to remove the callback
+     */
+    onError(callback: (error: SmoreError) => void): () => void;
     /**
      * Returns the number of currently connected players.
      */
@@ -621,7 +564,7 @@ export interface Controller<TEvents extends EventMap = EventMap> {
     /**
      * Send an event to the screen.
      *
-     * Controller → Screen direction only. For Screen → Controller, see `sendToController()`.
+     * Controller -> Screen direction only. For Screen -> Controller, see `sendToController()`.
      *
      * @param event - Event name (must match TEvents keys)
      * @param data - Event data (type-safe based on event name)
@@ -655,6 +598,8 @@ export interface Controller<TEvents extends EventMap = EventMap> {
     signalReady(): void;
     /**
      * Add a listener for a specific event after construction.
+     * Can be called before the controller is ready -- handlers are queued
+     * and activated when the transport becomes available.
      *
      * @param event - Event name
      * @param handler - Handler function (data) => void
@@ -750,79 +695,52 @@ export interface DebugOptions {
 /**
  * Create a Screen instance for the host/TV side of your game.
  *
- * Returns a Promise that resolves when the screen is ready.
- * You can also use the onReady callback in config for immediate instantiation.
- *
- * The return type is a Promise with an `instance` property for dual access:
- * - Await the Promise to get the instance after initialization completes
- * - Access `instance` property for synchronous access before initialization
+ * 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
- * @returns Promise that resolves to the Screen instance when ready
+ * @param config - Screen configuration (debug, parentOrigin, timeout)
+ * @returns Screen instance (synchronous)
  *
- * @example Promise-based (recommended)
+ * @example
  * ```ts
- * const screen = await createScreen<MyEvents>({
- *   listeners: {
- *     tap: (playerIndex, data) => handleTap(playerIndex, data),
- *   },
+ * const screen = createScreen<MyEvents>({ debug: true });
+ *
+ * screen.on('tap', (playerIndex, data) => {
+ *   screen.broadcast('round-result', { ... });
  * });
  *
- * screen.broadcast('game-start', { countdown: 3 });
- * ```
+ * screen.onAllReady(() => startGame());
+ * screen.onControllerJoin((pi, info) => addPlayer(pi, info));
  *
- * @example Callback-based
- * ```ts
- * const screen = createScreen<MyEvents>({
- *   onReady: () => {
- *     screen.broadcast('game-start', { countdown: 3 });
- *   },
- *   listeners: { ... },
- * });
+ * await screen.ready;
  * ```
  */
-export declare function createScreen<TEvents extends EventMap = EventMap>(config?: ScreenConfig<TEvents>): Promise<Screen<TEvents>> & {
-    instance: Screen<TEvents>;
-};
+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 Promise that resolves when the controller is ready.
- * You can also use the onReady callback in config for immediate instantiation.
- *
- * The return type is a Promise with an `instance` property for dual access:
- * - Await the Promise to get the instance after initialization completes
- * - Access `instance` property for synchronous access before initialization
+ * 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
- * @returns Promise that resolves to the Controller instance when ready
+ * @param config - Controller configuration (debug, parentOrigin, timeout)
+ * @returns Controller instance (synchronous)
  *
- * @example Promise-based (recommended)
+ * @example
  * ```ts
- * const controller = await createController<MyEvents>({
- *   listeners: {
- *     'phase-update': (data) => setPhase(data.phase),
- *   },
- * });
+ * const controller = createController<MyEvents>({ debug: true });
  *
- * controller.send('tap', { x: 100, y: 200 });
- * ```
+ * controller.on('phase-update', (data) => setPhase(data.phase));
+ * controller.onAllReady(() => console.log('Ready!'));
  *
- * @example Callback-based
- * ```ts
- * const controller = createController<MyEvents>({
- *   onReady: () => {
- *     controller.send('ready', {});
- *   },
- *   listeners: { ... },
- * });
+ * await controller.ready;
+ * controller.send('tap', { x: 100, y: 200 });
  * ```
  */
-export declare function createController<TEvents extends EventMap = EventMap>(config?: ControllerConfig<TEvents>): Promise<Controller<TEvents>> & {
-    instance: Controller<TEvents>;
-};
+export declare function createController<TEvents extends EventMap = EventMap>(config?: ControllerConfig<TEvents>): Controller<TEvents>;
 /**
  * Options for creating mock instances.
  */
@@ -833,26 +751,8 @@ export interface MockOptions {
     controllers?: ControllerInfo[];
     /** My index for Controller mock */
     myIndex?: PlayerIndex;
-    /** Auto-trigger onReady */
+    /** Auto-trigger ready state */
     autoReady?: boolean;
-    /** Called when ready is triggered */
-    onReady?: () => void;
-    /** Called when a controller joins */
-    onControllerJoin?: (playerIndex: PlayerIndex, info: ControllerInfo) => void;
-    /** Called when a controller leaves */
-    onControllerLeave?: (playerIndex: PlayerIndex) => void;
-    /** Called when a controller disconnects */
-    onControllerDisconnect?: (playerIndex: PlayerIndex) => void;
-    /** Called when a controller reconnects */
-    onControllerReconnect?: (playerIndex: PlayerIndex, info: ControllerInfo) => void;
-    /** Called when a player's character appearance is updated */
-    onCharacterUpdated?: (playerIndex: PlayerIndex, appearance: CharacterAppearance | null) => void;
-    /** Called when the server rate-limits an event from this client */
-    onRateLimited?: (event: string) => void;
-    /** Called when all participants are ready */
-    onAllReady?: () => void;
-    /** Called when an error occurs */
-    onError?: (error: SmoreError) => void;
 }
 /**
  * Mock Screen for testing.
@@ -866,22 +766,22 @@ export interface MockScreen<TEvents extends EventMap = EventMap> extends Screen<
     simulateEvent<K extends EventNames<TEvents>>(playerIndex: PlayerIndex, event: K, data: EventData<TEvents, K>): void;
     /**
      * Simulate a controller joining.
-     * Triggers onControllerJoin callback.
+     * Triggers onControllerJoin callbacks.
      */
     simulateControllerJoin(info: ControllerInfo): void;
     /**
      * Simulate a controller leaving.
-     * Triggers onControllerLeave callback.
+     * Triggers onControllerLeave callbacks.
      */
     simulateControllerLeave(playerIndex: PlayerIndex): void;
     /**
      * Simulate a controller disconnecting temporarily.
-     * Triggers onControllerDisconnect callback and marks player as disconnected.
+     * Triggers onControllerDisconnect callbacks and marks player as disconnected.
      */
     simulateControllerDisconnect(playerIndex: PlayerIndex): void;
     /**
      * Simulate a controller reconnecting after a disconnect.
-     * Triggers onControllerReconnect callback and marks player as connected.
+     * Triggers onControllerReconnect callbacks and marks player as connected.
      */
     simulateControllerReconnect(playerIndex: PlayerIndex): void;
     /**
@@ -909,20 +809,20 @@ export interface MockScreen<TEvents extends EventMap = EventMap> extends Screen<
     triggerReady(): void;
     /**
      * Simulate a player's character appearance being updated.
-     * Triggers onCharacterUpdated callback and updates the controller's appearance.
+     * 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 callback.
+     * Triggers onRateLimited callbacks.
      */
     simulateRateLimited(event: string): void;
     /**
      * Simulate the all-ready event (all participants signaled ready).
-     * Triggers onAllReady callback.
+     * Triggers onAllReady callbacks.
      */
     simulateAllReady(): void;
-    /** Simulate an error. Triggers onError callback. */
+    /** Simulate an error. Triggers onError callbacks. */
     simulateError(error: any): void;
 }
 /**
@@ -953,40 +853,40 @@ export interface MockController<TEvents extends EventMap = EventMap> extends Con
     triggerReady(): void;
     /**
      * Simulate another player joining the room.
-     * Triggers onControllerJoin callback.
+     * Triggers onControllerJoin callbacks.
      */
     simulatePlayerJoin(playerIndex: PlayerIndex, info: ControllerInfo): void;
     /**
      * Simulate another player leaving the room.
-     * Triggers onControllerLeave callback.
+     * Triggers onControllerLeave callbacks.
      */
     simulatePlayerLeave(playerIndex: PlayerIndex): void;
     /**
      * Simulate another player disconnecting temporarily.
-     * Triggers onControllerDisconnect callback.
+     * Triggers onControllerDisconnect callbacks.
      */
     simulatePlayerDisconnect(playerIndex: PlayerIndex): void;
     /**
      * Simulate another player reconnecting after a disconnect.
-     * Triggers onControllerReconnect callback.
+     * Triggers onControllerReconnect callbacks.
      */
     simulatePlayerReconnect(playerIndex: PlayerIndex, info: ControllerInfo): void;
     /**
      * Simulate a player's character appearance being updated.
-     * Triggers onCharacterUpdated callback and updates the controller's appearance.
+     * 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 callback.
+     * Triggers onRateLimited callbacks.
      */
     simulateRateLimited(event: string): void;
     /**
      * Simulate the all-ready event (all participants signaled ready).
-     * Triggers onAllReady callback.
+     * Triggers onAllReady callbacks.
      */
     simulateAllReady(): void;
-    /** Simulate an error. Triggers onError callback. */
+    /** Simulate an error. Triggers onError callbacks. */
     simulateError(error: any): void;
 }
 /**
@@ -1001,6 +901,9 @@ export interface MockController<TEvents extends EventMap = EventMap> extends Con
  *   ],
  * });
  *
+ * mockScreen.on('tap', (pi, data) => handleTap(pi, data));
+ * mockScreen.onAllReady(() => startGame());
+ *
  * // Simulate player input
  * mockScreen.simulateEvent(0, 'tap', { x: 100, y: 200 });
  *
@@ -1021,6 +924,9 @@ export declare function createMockScreen<TEvents extends EventMap = EventMap>(op
  *   myIndex: 0,
  * });
  *
+ * mockController.on('your-turn', (data) => handleTurn(data));
+ * mockController.onAllReady(() => console.log('Ready!'));
+ *
  * // Simulate receiving from screen
  * mockController.simulateEvent('your-turn', { timeLimit: 30 });
  *