@smoregg/sdk 2.2.0 → 2.3.0

package/README.md

@@ -1,6 +1,18 @@
 # @smoregg/sdk
 
-S'MORE Game SDK - Build party games with React for the S'MORE platform.
+SDK for building multiplayer party games on the S'MORE platform.
+
+**v2.3.0** | TypeScript | Zero runtime dependencies | ESM, CJS, UMD
+
+---
+
+## Overview
+
+S'MORE is a multiplayer party game platform where a shared display (the **Screen**, typically a TV or computer) runs the game while each player uses their phone as a **Controller** -- an input device and personal display. Think Jackbox-style games with full developer control.
+
+This SDK provides type-safe APIs for communication between the Screen and Controllers. Define your game's event types once in a shared interface, and get full compile-time checking on every `send()`, `broadcast()`, and `on()` call. The SDK handles connection management, reconnection, lifecycle events, and message delivery.
+
+The core architectural principle is the **Stateless Controller Pattern**: Controllers are display + input devices only. The Screen holds all game state and is the single source of truth. When a player reconnects, the Screen simply re-pushes the current view -- no state synchronization needed.
 
 ## Installation
 
@@ -14,177 +26,415 @@ yarn add @smoregg/sdk
 
 ## Quick Start
 
-### Screen Game (TV/Display)
+### 1. Define Your Events
+
+Create a shared event map that both Screen and Controller will use:
+
+```typescript
+// events.ts (shared between Screen and Controller)
+interface GameEvents {
+  // Screen -> Controller (view state)
+  'game-state': { phase: string; score: number };
+  // Controller -> Screen (input)
+  'tap': { timestamp: number };
+}
+```
+
+### 2. Screen (TV / Shared Display)
 
-```tsx
+```typescript
 import { createScreen } from '@smoregg/sdk';
 
-function MyGame() {
-  const screen = createScreen({
-    gameId: 'my-game',
-    listeners: {
-      tap: (playerIndex, data) => {
-        console.log(`Player ${playerIndex} tapped!`);
-        screen.broadcast('score-update', { playerIndex, score: 10 });
-      }
-    }
-  });
+const screen = createScreen<GameEvents>();
 
-  return <div>Game UI</div>;
-}
+// Listen for player input
+screen.on('tap', (playerIndex, data) => {
+  console.log(`Player ${playerIndex} tapped at ${data.timestamp}`);
+  // Update game state and push to all controllers
+  screen.broadcast('game-state', { phase: 'playing', score: 10 });
+});
+
+// Re-push view to reconnecting players
+screen.onControllerReconnect((playerIndex) => {
+  screen.sendToController(playerIndex, 'game-state', getCurrentState());
+});
+
+await screen.ready;
 ```
 
-### Controller App (Mobile)
+### 3. Controller (Phone)
 
-```tsx
+```typescript
 import { createController } from '@smoregg/sdk';
 
-function MyController() {
-  const controller = createController({
-    gameId: 'my-game',
-    listeners: {
-      'state-update': (state) => {
-        console.log('Game state:', state);
-      }
-    }
-  });
+const controller = createController<GameEvents>();
 
-  return (
-    <button onClick={() => controller.send('tap', {})}>
-      TAP
-    </button>
-  );
+// Render what Screen sends (stateless -- no local game state)
+controller.on('game-state', (data) => {
+  renderUI(data.phase, data.score);
+});
+
+// Send input to Screen
+function handleTap() {
+  controller.send('tap', { timestamp: Date.now() });
 }
+
+await controller.ready;
 ```
 
-## Features
+## Architecture
 
-- **Screen/Controller Communication**: Simple event-based messaging
-- **TypeScript Support**: Full type definitions included
-- **Testing Utilities**: Mock Screen and Controller for unit testing
-- **Multiple Formats**: ESM, CJS, and UMD builds
-- **Zero Dependencies**: Peer dependencies only (React, Socket.IO)
+```
+┌─────────┐    events     ┌─────────┐    relay    ┌──────────────┐
+│  Screen  │ <----------> │  Server  │ <--------> │  Controller  │
+│  (TV)    │              │  (relay) │            │  (Phone)     │
+│          │              │          │            │              │
+│ Game     │  broadcast   │ No game  │   on()     │ Display only │
+│ Logic    │ -----------> │ logic    │ ---------> │ + Input      │
+│ State    │              │          │            │              │
+│ Source   │ sendToCtrl   │          │   send()   │ No game      │
+│ of Truth │ -----------> │          │ <--------- │ state        │
+└─────────┘              └─────────┘            └──────────────┘
+```
+
+**Data flow:**
+
+- **Controller to Screen:** Input only via `controller.send()`
+- **Screen to all Controllers:** View state via `screen.broadcast()`
+- **Screen to one Controller:** Targeted view state via `screen.sendToController()`
+- **Reconnection:** Screen re-pushes view in `onControllerReconnect` callback
+
+The server is a stateless relay -- it forwards messages without game logic. All game state lives on the Screen.
 
 ## API Reference
 
-### createScreen()
+### Screen
 
-Create a screen-side game instance.
+#### Creating a Screen
 
 ```typescript
 import { createScreen } from '@smoregg/sdk';
 
-const screen = createScreen({
-  gameId: string;
-  listeners?: Record<string, (playerIndex: number, data: any) => void>;
-});
+const screen = createScreen<MyEvents>(config?);
+```
 
-// Methods
-screen.broadcast(event: string, data: any): void
-screen.sendToController(playerIndex: number, event: string, data: any): void
-screen.gameOver(results: GameResults): void
-screen.on(event: string, callback: Function): void
-screen.off(event: string, callback: Function): void
+#### Config Options
 
-// Properties
-screen.controllers: Array<{ playerIndex: number; nickname: string; connected: boolean }>
-screen.myIndex: number
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `debug` | `boolean \| DebugOptions` | `false` | Enable debug logging |
+| `parentOrigin` | `string` | `'*'` | Parent window origin for message validation |
+| `timeout` | `number` | `10000` | Connection timeout in milliseconds |
+| `autoReady` | `boolean` | `true` | Automatically signal ready after initialization |
 
-### createController()
+#### Properties
 
-Create a controller-side game instance.
+| Property | Type | Description |
+|----------|------|-------------|
+| `controllers` | `readonly ControllerInfo[]` | All connected controllers (shallow copy per access) |
+| `roomCode` | `string` | Room code for this game session |
+| `isReady` | `boolean` | Whether the screen is initialized |
+| `isDestroyed` | `boolean` | Whether the screen has been destroyed |
+| `isConnected` | `boolean` | Whether the connection is active |
+| `ready` | `Promise<void>` | Resolves when the screen is ready |
 
-```typescript
-import { createController } from '@smoregg/sdk';
+#### Communication
 
-const controller = createController({
-  gameId: string;
-  listeners?: Record<string, (data: any) => void>;
-});
+| Method | Description |
+|--------|-------------|
+| `broadcast(event, data)` | Send to all controllers. Rate limit: 60/sec (shared with `sendToController`). Max payload: 64KB. |
+| `sendToController(playerIndex, event, data)` | Send to one controller. Shares the 60/sec rate limit with `broadcast`. |
+| `gameOver(results?)` | End the game. Accepts optional `GameResults` with scores, winner, rankings. |
+| `signalReady()` | Signal ready to the server. Auto-called if `autoReady` is `true`. |
 
-// Methods
-controller.send(event: string, data: any): void
-controller.on(event: string, callback: Function): void
-controller.off(event: string, callback: Function): void
+#### Lifecycle Callbacks
 
-// Properties
-controller.myIndex: number
-controller.isLeader: boolean
-```
+All lifecycle methods return an unsubscribe function.
 
-## Backward Compatibility
+| Method | Callback Signature | Description |
+|--------|--------------------|-------------|
+| `onAllReady(cb)` | `() => void` | All participants are ready. Fires immediately if already ready. |
+| `onControllerJoin(cb)` | `(playerIndex, info) => void` | A player joined the room |
+| `onControllerLeave(cb)` | `(playerIndex) => void` | A player left the room |
+| `onControllerDisconnect(cb)` | `(playerIndex) => void` | A player temporarily disconnected |
+| `onControllerReconnect(cb)` | `(playerIndex, info) => void` | A player reconnected |
+| `onCharacterUpdated(cb)` | `(playerIndex, appearance) => void` | A player's character appearance changed |
+| `onError(cb)` | `(error: SmoreError) => void` | An SDK error occurred |
+| `onConnectionChange(cb)` | `(connected: boolean) => void` | Connection status changed |
 
-The old type aliases are still available:
+#### Event Subscription
+
+| Method | Description |
+|--------|-------------|
+| `on(event, handler)` | Subscribe to an event. Handler receives `(playerIndex, data)`. Returns unsubscribe function. |
+| `once(event, handler)` | Subscribe once. Auto-removes after first call. |
+| `off(event, handler?)` | Remove a specific handler, or all handlers for an event. |
+| `removeAllListeners(event?)` | Remove all user event listeners, or all for a specific event. |
+
+#### Utilities
+
+| Method | Description |
+|--------|-------------|
+| `getController(playerIndex)` | Get a `ControllerInfo` by player index, or `undefined` |
+| `getControllerCount()` | Number of currently connected controllers |
+| `destroy()` | Clean up all resources and disconnect |
+
+---
+
+### Controller
+
+#### Creating a Controller
 
 ```typescript
-// Old names (deprecated)
-import type { SmoreHost, SmorePlayer } from '@smoregg/sdk';
+import { createController } from '@smoregg/sdk';
 
-// New names (preferred)
-import type { SmoreScreen, SmoreController } from '@smoregg/sdk';
+const controller = createController<MyEvents>(config?);
 ```
 
-## Testing
+Config options are the same as Screen.
 
-The SDK provides comprehensive testing utilities for unit testing your game logic:
+#### Properties
 
-```typescript
-import { createMockScreen, createMockController } from '@smoregg/sdk';
+| Property | Type | Description |
+|----------|------|-------------|
+| `myPlayerIndex` | `number` | This player's index (0, 1, 2, ...) |
+| `me` | `ControllerInfo \| undefined` | This player's info |
+| `roomCode` | `string` | Room code for this game session |
+| `controllers` | `readonly ControllerInfo[]` | All known controllers in the room |
+| `isReady` | `boolean` | Whether the controller is initialized |
+| `isDestroyed` | `boolean` | Whether the controller has been destroyed |
+| `isConnected` | `boolean` | Whether the connection is active |
+| `ready` | `Promise<void>` | Resolves when the controller is ready |
 
-// Create mock screen with players
-const screen = createMockScreen<MyEvents>({
-  controllers: [
-    { playerIndex: 0, nickname: 'Player 1', connected: true },
-  ],
-});
+#### Communication
+
+| Method | Description |
+|--------|-------------|
+| `send(event, data)` | Send to Screen. Rate limit: 60/sec. Max payload: 64KB. |
+| `signalReady()` | Signal ready to the server. Auto-called if `autoReady` is `true`. |
+
+Controller has no `broadcast()` -- all communication goes through Screen. Controller-to-Controller messaging is not supported; route through Screen instead.
 
-// Simulate player input
-screen.simulateEvent(0, 'tap', { x: 100, y: 200 });
+#### Lifecycle Callbacks
 
-// Check what was broadcast
-expect(screen.getBroadcasts()).toContainEqual({
-  event: 'score-update',
-  data: { scores: { 0: 10 } },
+Same as Screen, plus:
+
+| Method | Callback Signature | Description |
+|--------|--------------------|-------------|
+| `onGameOver(cb)` | `(results?) => void` | The game has ended (Screen called `gameOver()`) |
+
+#### Event Subscription
+
+Same API as Screen. Handler receives `(data)` only -- no `playerIndex` parameter.
+
+```typescript
+controller.on('game-state', (data) => {
+  // data is type-safe: { phase: string; score: number }
+  renderUI(data.phase, data.score);
 });
 ```
 
-See [docs/testing.md](./docs/testing.md) for the full testing guide.
+#### Utilities
+
+| Method | Description |
+|--------|-------------|
+| `getController(playerIndex)` | Get a `ControllerInfo` by player index, or `undefined` |
+| `getControllerCount()` | Number of currently connected controllers |
+| `destroy()` | Clean up all resources and disconnect |
 
-## Types
+---
 
-All types are exported from the main package:
+### Types
 
 ```typescript
 import type {
-  Player,
-  PlayerDTO,
+  EventMap,
+  ControllerInfo,
+  GameResults,
+  SmoreError,
+  SmoreErrorCode,
   CharacterAppearance,
-  GameMetadata,
-  GameState,
-  InputCallback
+  PlayerIndex,
+  Screen,
+  Controller,
 } from '@smoregg/sdk';
+
+import { SmoreSDKError, LifecycleEvent } from '@smoregg/sdk';
 ```
 
-## Building
+#### ControllerInfo
 
-```bash
-# Development
-pnpm typecheck
+```typescript
+interface ControllerInfo {
+  readonly playerIndex: number;
+  readonly nickname: string;
+  readonly connected: boolean;
+  readonly appearance?: CharacterAppearance | null;
+}
+```
+
+#### GameResults
 
-# Build all formats (ESM, CJS, UMD)
-pnpm build
+```typescript
+interface GameResults {
+  scores?: Record<number, number>;
+  winner?: number;
+  rankings?: number[];
+  custom?: Record<string, unknown>;
+}
+```
 
-# Clean
-pnpm clean
+#### SmoreSDKError
+
+```typescript
+class SmoreSDKError extends Error {
+  readonly code: SmoreErrorCode;
+  readonly cause?: Error;
+  readonly details?: Record<string, unknown>;
+}
 ```
 
-## Publishing
+**Error codes:** `TIMEOUT`, `NOT_READY`, `DESTROYED`, `INVALID_EVENT`, `INVALID_PLAYER`, `CONNECTION_LOST`, `INIT_FAILED`, `RATE_LIMITED`, `PAYLOAD_TOO_LARGE`, `UNKNOWN`
 
-```bash
-pnpm publish:npm
+#### LifecycleEvent Constants
+
+Subscribe to lifecycle events via `on()` using `$`-prefixed constants:
+
+```typescript
+import { LifecycleEvent } from '@smoregg/sdk';
+
+// These are equivalent:
+screen.onControllerJoin((playerIndex, info) => { /* ... */ });
+screen.on(LifecycleEvent.CONTROLLER_JOIN, (playerIndex, info) => { /* ... */ });
+```
+
+Available constants: `ALL_READY`, `CONTROLLER_JOIN`, `CONTROLLER_LEAVE`, `CONTROLLER_DISCONNECT`, `CONTROLLER_RECONNECT`, `CHARACTER_UPDATED`, `ERROR`, `GAME_OVER`, `CONNECTION_CHANGE`
+
+#### EventMap
+
+Event data values must be plain objects, not primitives. The fields `playerIndex` and `targetPlayerIndex` are reserved by the SDK.
+
+```typescript
+// Good
+interface MyEvents {
+  'tap': { x: number; y: number };
+  'answer': { choice: number };
+}
+
+// Bad -- primitives are not allowed
+interface MyEvents {
+  'tap': number;        // Will break type safety
+  'answer': string;     // Use { value: string } instead
+}
+```
+
+## Testing
+
+Import test utilities from `@smoregg/sdk/testing`:
+
+```typescript
+import { createMockScreen, createMockController } from '@smoregg/sdk/testing';
+```
+
+### Example Test
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createMockScreen } from '@smoregg/sdk/testing';
+
+interface GameEvents {
+  'tap': { x: number; y: number };
+  'score-update': { scores: Record<number, number> };
+}
+
+describe('My Game', () => {
+  it('broadcasts score on tap', () => {
+    const screen = createMockScreen<GameEvents>({
+      controllers: [
+        { playerIndex: 0, nickname: 'Alice', connected: true },
+      ],
+    });
+    screen.triggerReady();
+
+    // Register game logic
+    screen.on('tap', (playerIndex, data) => {
+      screen.broadcast('score-update', { scores: { [playerIndex]: 10 } });
+    });
+
+    // Simulate player input
+    screen.simulateEvent(0, 'tap', { x: 100, y: 200 });
+
+    // Assert game logic response
+    const broadcasts = screen.getBroadcasts();
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]).toEqual({
+      event: 'score-update',
+      data: { scores: { 0: 10 } },
+    });
+  });
+});
 ```
 
+### MockScreen Methods
+
+| Method | Description |
+|--------|-------------|
+| `triggerReady()` | Manually trigger the ready state (synchronous) |
+| `simulateEvent(playerIndex, event, data)` | Simulate a controller sending an event |
+| `simulateControllerJoin(info)` | Simulate a player joining |
+| `simulateControllerLeave(playerIndex)` | Simulate a player leaving |
+| `simulateControllerDisconnect(playerIndex)` | Simulate a player disconnecting |
+| `simulateControllerReconnect(playerIndex)` | Simulate a player reconnecting |
+| `simulateAllReady()` | Trigger the all-ready event |
+| `simulateCharacterUpdate(playerIndex, appearance)` | Simulate a character appearance change |
+| `simulateConnectionChange(connected)` | Simulate connection status change |
+| `simulateError(error)` | Simulate an error event |
+| `getBroadcasts()` | Get all recorded `broadcast()` calls |
+| `getSentToController(playerIndex)` | Get recorded `sendToController()` calls for a player |
+| `getAllSentToController()` | Get all recorded `sendToController()` calls |
+| `clearRecordedEvents()` | Clear all recorded broadcasts and sends |
+
+### MockController Methods
+
+| Method | Description |
+|--------|-------------|
+| `triggerReady()` | Manually trigger the ready state (synchronous) |
+| `simulateEvent(event, data)` | Simulate the Screen sending an event |
+| `simulateGameOver(results?)` | Simulate the game ending |
+| `simulatePlayerJoin(playerIndex, info)` | Simulate a player joining |
+| `simulatePlayerLeave(playerIndex)` | Simulate a player leaving |
+| `simulatePlayerDisconnect(playerIndex)` | Simulate a player disconnecting |
+| `simulatePlayerReconnect(playerIndex, info)` | Simulate a player reconnecting |
+| `simulateAllReady()` | Trigger the all-ready event |
+| `simulateCharacterUpdate(playerIndex, appearance)` | Simulate a character appearance change |
+| `simulateConnectionChange(connected)` | Simulate connection status change |
+| `simulateError(error)` | Simulate an error event |
+| `getSentEvents()` | Get all recorded `send()` calls |
+| `clearRecordedEvents()` | Clear all recorded sends |
+
+**Note:** Default `autoReady` is `false` in mocks. Use `triggerReady()` for synchronous test control. If you pass `autoReady: true`, ready fires asynchronously on the next tick.
+
+## Event Naming Rules
+
+| Rule | Example |
+|------|---------|
+| Must start with a letter | `tap` (valid), `123tap` (invalid) |
+| Letters, numbers, hyphens, underscores only | `player-move` (valid), `player.move` (invalid) |
+| No colons | `my-event` (valid), `my:event` (invalid, reserved for platform) |
+| Max 128 characters | - |
+
+## Limits and Constraints
+
+| Constraint | Value |
+|------------|-------|
+| Rate limit | 60 events/sec per socket (shared across all send methods) |
+| Max payload | 64KB per event |
+| Message ordering | Guaranteed for a single sender |
+| Event data | Must be objects, not primitives |
+| Reserved fields | `playerIndex` and `targetPlayerIndex` in event data |
+
+Events exceeding the rate limit or payload size are silently dropped by the server.
+
 ## License
 
-MIT (C) S'MORE Team
+MIT

package/dist/cjs/controller.cjs

@@ -23,8 +23,6 @@ class ControllerImpl {
   // Maps user-facing handler -> transport wrappedHandler for proper cleanup in on()/off()
   handlerToTransport = /* @__PURE__ */ new Map();
   _controllers = [];
-  _customStates = /* @__PURE__ */ new Map();
-  _stateChangeListeners = /* @__PURE__ */ new Set();
   // Pending handlers registered via on() before transport is ready
   _pendingHandlers = [];
   // Unified lifecycle listener map (supports both onXxx() and on('$xxx') patterns)
@@ -183,10 +181,6 @@ class ControllerImpl {
     this._pendingHandlers = [];
     this._isConnected = true;
     this._isReady = true;
-    if (initData.gameInProgress && this.transport) {
-      this.logger.lifecycle("Game in progress detected, requesting state recovery");
-      this.transport.emit(events.SMORE_EVENTS.STATE_GET_ALL, {});
-    }
     for (const buffered of this._outboundBuffer) {
       try {
         switch (buffered.method) {
@@ -337,44 +331,6 @@ class ControllerImpl {
       this.logger.lifecycle("Connection restored");
       this._emitLifecycle("$connection-change", true);
     });
-    this.registerHandler(events.SMORE_EVENTS.STATE_CHANGED, (raw) => {
-      const data = raw;
-      if (typeof data?.playerIndex === "number" && data.state) {
-        this._customStates.set(data.playerIndex, data.state);
-        this._stateChangeListeners.forEach((cb) => {
-          try {
-            cb(data.playerIndex, data.state);
-          } catch (err) {
-            this.handleError(
-              new errors.SmoreSDKError("UNKNOWN", "Error in custom state change listener", {
-                cause: err instanceof Error ? err : void 0
-              })
-            );
-          }
-        });
-      }
-    });
-    this.registerHandler(events.SMORE_EVENTS.STATE_ALL, (raw) => {
-      const data = raw;
-      if (data?.states) {
-        for (const [key, value] of Object.entries(data.states)) {
-          const pi = Number(key);
-          this._customStates.set(pi, value);
-          this._stateChangeListeners.forEach((cb) => {
-            try {
-              cb(pi, value);
-            } catch (err) {
-              this.handleError(
-                new errors.SmoreSDKError("UNKNOWN", "Error in custom state change listener", {
-                  cause: err instanceof Error ? err : void 0
-                })
-              );
-            }
-          });
-        }
-        this._emitLifecycle("$state-recovery", data.states);
-      }
-    });
   }
   /**
    * Sets up a user event handler for controller events.
@@ -478,26 +434,6 @@ class ControllerImpl {
     return this._addLifecycleListener("$game-over", callback);
   }
   // ---------------------------------------------------------------------------
-  // Custom State Methods
-  // ---------------------------------------------------------------------------
-  setState(state) {
-    const current = this._customStates.get(this._myPlayerIndex) ?? {};
-    const merged = { ...current, ...state };
-    this._customStates.set(this._myPlayerIndex, merged);
-    if (this.transport) {
-      this.transport.emit(events.SMORE_EVENTS.STATE_SET, { state });
-    }
-  }
-  getMyState() {
-    return this._customStates.get(this._myPlayerIndex);
-  }
-  onCustomStateChange(listener) {
-    this._stateChangeListeners.add(listener);
-    return () => {
-      this._stateChangeListeners.delete(listener);
-    };
-  }
-  // ---------------------------------------------------------------------------
   // Communication Methods
   // ---------------------------------------------------------------------------
   /**
@@ -710,8 +646,6 @@ class ControllerImpl {
     this.handlerToTransport.clear();
     this._pendingHandlers = [];
     this._lifecycleListeners.clear();
-    this._customStates.clear();
-    this._stateChangeListeners.clear();
     this._isConnected = false;
     this._outboundBuffer = [];
     if (this.transport) {