chore(release): 3.22.3 [skip ci]

## [3.22.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.2...v3.22.3) (2025-10-16) ### Bug Fixes * **number-guesser:** add turn indicators, error feedback, and fix player ordering ([9f62623](9f62623684)) ### Documentation * **arcade:** update docs for unified validator registry ([6f6cb14](6f6cb14650))
fix(number-guesser): add turn indicators, error feedback, and fix player ordering
2025-10-16 01:46:31 +00:00 · 2025-10-15 20:45:39 -05:00 · 2025-10-15 20:41:06 -05:00 · 2025-10-16 01:39:05 +00:00 · 2025-10-15 20:38:15 -05:00 · 2025-10-16 00:16:26 +00:00
44 changed files with 4198 additions and 109 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,44 @@
+## [3.22.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.2...v3.22.3) (2025-10-16)
+
+
+### Bug Fixes
+
+* **number-guesser:** add turn indicators, error feedback, and fix player ordering ([9f62623](https://github.com/antialias/soroban-abacus-flashcards/commit/9f626236845493ef68e1b3626e80efa35637b449))
+
+
+### Documentation
+
+* **arcade:** update docs for unified validator registry ([6f6cb14](https://github.com/antialias/soroban-abacus-flashcards/commit/6f6cb14650ba3636a7e2b036e2a2a9410492e7c3))
+
+## [3.22.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.1...v3.22.2) (2025-10-16)
+
+
+### Code Refactoring
+
+* **arcade:** create unified validator registry to fix dual registration ([f775fc5](https://github.com/antialias/soroban-abacus-flashcards/commit/f775fc55e50af0c3a29b3e00fc722e7d7ce90212)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)
+
+## [3.22.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.0...v3.22.1) (2025-10-16)
+
+
+### Bug Fixes
+
+* **arcade:** add Number Guesser to game config helpers ([7d1a351](https://github.com/antialias/soroban-abacus-flashcards/commit/7d1a351ed6a1442ae34f6b75d46039bfa77a921b))
+* **nav:** update types for registry games with nullable gameName ([a51e539](https://github.com/antialias/soroban-abacus-flashcards/commit/a51e539d023681daf639ec104e79079c8ceec98e))
+
+## [3.22.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.21.0...v3.22.0) (2025-10-16)
+
+
+### Features
+
+* **arcade:** add Number Guesser demo game with plugin architecture ([0e3c058](https://github.com/antialias/soroban-abacus-flashcards/commit/0e3c0587073a69574a50f05c467f2499296012bf))
+
+## [3.21.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.20.0...v3.21.0) (2025-10-15)
+
+
+### Features
+
+* **arcade:** add modular game SDK and registry system ([de30bec](https://github.com/antialias/soroban-abacus-flashcards/commit/de30bec47923565fe5d1d5a6f719f3fc4e9d1509))
+
 ## [3.20.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.19.0...v3.20.0) (2025-10-15)


--- a/apps/web/docs/AUDIT_MODULAR_GAME_SYSTEM.md
+++ b/apps/web/docs/AUDIT_MODULAR_GAME_SYSTEM.md
@@ -0,0 +1,519 @@
+# Modular Game System Audit
+
+**Date**: 2025-10-15
+**Updated**: 2025-10-15
+**Status**: ✅ CRITICAL ISSUE RESOLVED
+
+---
+
+## Executive Summary
+
+The modular game system **now meets its stated intentions** after implementing the unified validator registry. The critical dual registration issue has been resolved.
+
+**Original Issue**: Client-side implementation (SDK, registry, game definitions) was well-designed, but server-side validation used a hard-coded legacy system, breaking the core premise of modularity.
+
+**Resolution**: Created unified isomorphic validator registry (`src/lib/arcade/validators.ts`) that serves both client and server needs, with auto-derived GameName type.
+
+**Verdict**: ✅ **Production Ready** - System is now truly modular with single registration point
+
+---
+
+## Intention vs. Reality
+
+### Stated Intentions
+
+> "A modular, plugin-based architecture for building multiplayer arcade games"
+>
+> **Goals:**
+> 1. **Modularity**: Each game is self-contained and independently deployable
+> 2. Games register themselves with a central registry
+> 3. No need to modify core infrastructure when adding games
+
+### Current Reality
+
+✅ **Client-Side**: Fully modular, games use SDK and register themselves
+❌ **Server-Side**: Hard-coded validator map, requires manual code changes
+❌ **Overall**: **System is NOT modular** - adding a game requires editing 2 different registries
+
+---
+
+## Critical Issues
+
+### ✅ Issue #1: Dual Registration System (RESOLVED)
+
+**Original Problem**: Games had to register in TWO separate places:
+
+1. **Client Registry** (`src/lib/arcade/game-registry.ts`)
+2. **Server Validator Map** (`src/lib/arcade/validation/index.ts`)
+
+**Impact**:
+- ❌ Broke modularity - couldn't just drop in a new game
+- ❌ Easy to forget one registration, causing runtime errors
+- ❌ Violated DRY principle
+- ❌ Two sources of truth for "what games exist"
+
+**Resolution** (Implemented 2025-10-15):
+
+Created unified isomorphic validator registry at `src/lib/arcade/validators.ts`:
+
+```typescript
+export const validatorRegistry = {
+  matching: matchingGameValidator,
+  'memory-quiz': memoryQuizGameValidator,
+  'number-guesser': numberGuesserValidator,
+  // Add new games here - GameName type auto-updates!
+} as const
+
+// Auto-derived type - no manual updates needed!
+export type GameName = keyof typeof validatorRegistry
+```
+
+**Changes Made**:
+1. ✅ Created `src/lib/arcade/validators.ts` - Unified validator registry (isomorphic)
+2. ✅ Updated `validation/index.ts` - Now re-exports from unified registry (backwards compatible)
+3. ✅ Updated `validation/types.ts` - GameName now auto-derived (no more hard-coded union)
+4. ✅ Updated `session-manager.ts` - Imports from unified registry
+5. ✅ Updated `socket-server.ts` - Imports from unified registry
+6. ✅ Updated `route.ts` - Uses `hasValidator()` instead of hard-coded array
+7. ✅ Updated `game-config-helpers.ts` - Handles ExtendedGameName for legacy games
+8. ✅ Updated `game-registry.ts` - Added runtime validation check
+
+**Benefits**:
+- ✅ Single registration point for validators
+- ✅ Auto-derived GameName type (no manual updates)
+- ✅ Type-safe validator access
+- ✅ Backwards compatible with existing code
+- ✅ Runtime warnings for registration mismatches
+
+**Commit**: `refactor(arcade): create unified validator registry to fix dual registration` (9459f37b)
+
+---
+
+### ✅ Issue #2: Validators Not Accessible from Registry (RESOLVED)
+
+**Original Problem**: The `GameDefinition` contained validators, but server couldn't access them because `game-registry.ts` imported React components.
+
+**Resolution**: Created separate isomorphic validator registry that server can import without pulling in client-only code.
+
+**How It Works Now**:
+- `src/lib/arcade/validators.ts` - Isomorphic, server can import safely
+- `src/lib/arcade/game-registry.ts` - Client-only, imports React components
+- Both use the same validator instances (verified at runtime)
+
+**Benefits**:
+- ✅ Server has direct access to validators
+- ✅ No need for dual validator maps
+- ✅ Clear separation: validators (isomorphic) vs UI (client-only)
+
+---
+
+### ⚠️ Issue #3: Type System Fragmentation
+
+**Problem**: Multiple overlapping type definitions for same concepts:
+
+**GameValidator** has THREE definitions:
+1. `validation/types.ts` - Legacy validator interface
+2. `game-sdk/types.ts` - SDK validator interface (extends legacy)
+3. Individual game validators - Implement one or both?
+
+**GameMove** has TWO type systems:
+1. `validation/types.ts` - Legacy move types (MatchingFlipCardMove, etc.)
+2. Game-specific types in each game's `types.ts`
+
+**GameName** is hard-coded:
+```typescript
+// validation/types.ts:9
+export type GameName = 'matching' | 'memory-quiz' | 'complement-race' | 'number-guesser'
+```
+
+This must be manually updated for every new game!
+
+**Impact**:
+- Confusing which types to use
+- Easy to use wrong import
+- GameName type doesn't auto-update from registry
+
+---
+
+### ⚠️ Issue #4: Old Games Not Migrated
+
+**Problem**: Existing games (matching, memory-quiz) still use old structure:
+
+**Old Pattern** (matching, memory-quiz):
+```
+src/app/arcade/matching/
+  ├── context/           (Old pattern)
+  │   └── RoomMemoryPairsProvider.tsx
+  └── components/
+```
+
+**New Pattern** (number-guesser):
+```
+src/arcade-games/number-guesser/
+  ├── index.ts           (New pattern)
+  ├── Validator.ts
+  ├── Provider.tsx
+  └── components/
+```
+
+**Impact**:
+- Inconsistent codebase structure
+- Two different patterns developers must understand
+- Documentation shows new pattern, but most games use old pattern
+- Confusing for new developers
+
+**Evidence**:
+- `src/app/arcade/matching/` - Uses old structure
+- `src/app/arcade/memory-quiz/` - Uses old structure
+- `src/arcade-games/number-guesser/` - Uses new structure
+
+---
+
+### ✅ Issue #5: Manual GameName Type Updates (RESOLVED)
+
+**Original Problem**: `GameName` type was a hard-coded union that had to be manually updated for each new game.
+
+**Resolution**: Changed validator registry from Map to const object, enabling type derivation:
+
+```typescript
+// src/lib/arcade/validators.ts
+export const validatorRegistry = {
+  matching: matchingGameValidator,
+  'memory-quiz': memoryQuizGameValidator,
+  'number-guesser': numberGuesserValidator,
+  // Add new games here...
+} as const
+
+// Auto-derived! No manual updates needed!
+export type GameName = keyof typeof validatorRegistry
+```
+
+**Benefits**:
+- ✅ GameName type updates automatically when adding to registry
+- ✅ Impossible to forget type update (it's derived)
+- ✅ Single registration step (just add to validatorRegistry)
+- ✅ Type-safe throughout codebase
+
+---
+
+## Secondary Issues
+
+### Issue #6: No Server-Side Registry Access
+
+**Problem**: Server code cannot import `game-registry.ts` because it contains React components.
+
+**Why**:
+- `GameDefinition` includes `Provider` and `GameComponent` (React components)
+- Server-side code runs in Node.js, can't import React components
+- No way to access just the validator from registry
+
+**Potential Solutions**:
+1. Split registry into isomorphic and client-only parts
+2. Separate validator registration from game registration
+3. Use conditional exports in package.json
+
+---
+
+### Issue #7: Documentation Doesn't Match Reality
+
+**Problem**: Documentation describes a fully modular system, but reality requires manual edits in multiple places.
+
+**From README.md**:
+> "Step 7: Register Game - Add to src/lib/arcade/game-registry.ts"
+
+**Missing Steps**:
+- Also add to `validation/index.ts` validator map
+- Also add to `GameName` type union
+- Import validator in server files
+
+**Impact**: Developers follow docs, game doesn't work, confusion ensues.
+
+---
+
+### Issue #8: No Validation of Registered Games
+
+**Problem**: Registration is type-safe but has no runtime validation:
+
+```typescript
+registerGame(numberGuesserGame)  // No validation that validator works
+```
+
+**Missing Checks**:
+- Does validator implement all required methods?
+- Does manifest match expected schema?
+- Are all required fields present?
+- Does validator.getInitialState() return valid state?
+
+**Impact**: Bugs only caught at runtime when game is played.
+
+---
+
+## Proposed Solutions
+
+### Solution 1: Unified Server-Side Registry (RECOMMENDED)
+
+**Create isomorphic validator registry**:
+
+```typescript
+// src/lib/arcade/validators.ts (NEW FILE - isomorphic)
+import { numberGuesserValidator } from '@/arcade-games/number-guesser/Validator'
+import { matchingGameValidator } from '@/lib/arcade/validation/MatchingGameValidator'
+// ... other validators
+
+export const validatorRegistry = new Map([
+  ['number-guesser', numberGuesserValidator],
+  ['matching', matchingGameValidator],
+  // ...
+])
+
+export function getValidator(gameName: string) {
+  const validator = validatorRegistry.get(gameName)
+  if (!validator) throw new Error(`No validator for game: ${gameName}`)
+  return validator
+}
+
+export type GameName = keyof typeof validatorRegistry  // Auto-derived!
+```
+
+**Update game-registry.ts** to use this:
+
+```typescript
+// src/lib/arcade/game-registry.ts
+import { getValidator } from './validators'
+
+export function registerGame(game: GameDefinition) {
+  const { name } = game.manifest
+
+  // Verify validator is registered server-side
+  const validator = getValidator(name)
+  if (validator !== game.validator) {
+    console.warn(`[Registry] Validator mismatch for ${name}`)
+  }
+
+  registry.set(name, game)
+}
+```
+
+**Pros**:
+- Single source of truth for validators
+- Auto-derived GameName type
+- Client and server use same validator
+- Only one registration needed
+
+**Cons**:
+- Still requires manual import in validators.ts
+- Doesn't solve "drop in a game" fully
+
+---
+
+### Solution 2: Code Generation
+
+**Auto-generate validator registry from file system**:
+
+```typescript
+// scripts/generate-registry.ts
+// Scans src/arcade-games/**/Validator.ts
+// Generates validators.ts and game-registry imports
+```
+
+**Pros**:
+- Truly modular - just add folder, run build
+- No manual registration
+- Auto-derived types
+
+**Cons**:
+- Build-time complexity
+- Magic (harder to understand)
+- May not work with all bundlers
+
+---
+
+### Solution 3: Split GameDefinition
+
+**Separate client and server concerns**:
+
+```typescript
+// Isomorphic (client + server)
+export interface GameValidatorDefinition {
+  name: string
+  validator: GameValidator
+  defaultConfig: GameConfig
+}
+
+// Client-only
+export interface GameUIDefinition {
+  name: string
+  manifest: GameManifest
+  Provider: GameProviderComponent
+  GameComponent: GameComponent
+}
+
+// Combined (client-only)
+export interface GameDefinition extends GameValidatorDefinition, GameUIDefinition {}
+```
+
+**Pros**:
+- Clear separation of concerns
+- Server can import just validator definition
+- Type-safe
+
+**Cons**:
+- More complexity
+- Still requires two registries
+
+---
+
+## Immediate Action Items
+
+### Critical (Do Before Next Game)
+
+1. **✅ Document the dual registration requirement** (COMPLETED)
+   - ✅ Update README with both registration steps
+   - ✅ Add troubleshooting section for "game not found" errors
+   - ✅ Document unified validator registry in Step 7
+
+2. **✅ Unify validator registration** (COMPLETED 2025-10-15)
+   - ✅ Chose Solution 1 (Unified Server-Side Registry)
+   - ✅ Implemented unified registry (src/lib/arcade/validators.ts)
+   - ✅ Updated session-manager.ts and socket-server.ts
+   - ✅ Tested with number-guesser (no TypeScript errors)
+
+3. **✅ Auto-derive GameName type** (COMPLETED 2025-10-15)
+   - ✅ Removed hard-coded union
+   - ✅ Derive from validator registry using `keyof typeof`
+   - ✅ Updated all usages (backwards compatible via re-exports)
+
+### High Priority
+
+4. **🟡 Migrate old games to new pattern**
+   - Move matching to `arcade-games/matching/`
+   - Move memory-quiz to `arcade-games/memory-quiz/`
+   - Update imports and tests
+   - OR document that old games use old pattern (transitional)
+
+5. **🟡 Add validator registration validation**
+   - Runtime check in registerGame()
+   - Warn if validator missing
+   - Validate manifest schema
+
+### Medium Priority
+
+6. **🟢 Clean up type definitions**
+   - Consolidate GameValidator types
+   - Single source of truth for GameMove
+   - Clear documentation on which to use
+
+7. **🟢 Update documentation**
+   - Add "dual registry" warning
+   - Update step-by-step guide
+   - Add troubleshooting for common mistakes
+
+---
+
+## Architectural Debt
+
+### Technical Debt Accumulated
+
+1. **Old validation system** (`validation/types.ts`, `validation/index.ts`)
+   - Used by server-side code
+   - Hard-coded game list
+   - No migration path documented
+
+2. **Mixed game structures** (old in `app/arcade/`, new in `arcade-games/`)
+   - Confusing for developers
+   - Inconsistent imports
+   - Harder to maintain
+
+3. **Type fragmentation** (3 GameValidator definitions)
+   - Unclear which to use
+   - Potential for bugs
+   - Harder to refactor
+
+### Migration Path
+
+**Option A: Big Bang** (Risky)
+- Migrate all games to new structure in one PR
+- Update server to use unified registry
+- High risk of breakage
+
+**Option B: Incremental** (Safer)
+- Document dual registration as "current reality"
+- Create unified validator registry (doesn't break old games)
+- Slowly migrate old games one by one
+- Eventually deprecate old validation system
+
+**Recommendation**: Option B (Incremental)
+
+---
+
+## Compliance with Intentions
+
+| Intention | Status | Notes |
+|-----------|--------|-------|
+| Modularity | ✅ Pass | Single registration in validators.ts + game-registry.ts |
+| Self-registration | ✅ Pass | Both client and server use unified registry |
+| Type safety | ✅ Pass | Good TypeScript coverage + auto-derived GameName |
+| No core changes | ⚠️ Improved | Must edit validators.ts, but one central file |
+| Drop-in games | ⚠️ Improved | Two registration points (validator + game def) |
+| Stable SDK API | ✅ Pass | SDK is well-designed and consistent |
+| Clear patterns | ⚠️ Partial | New pattern is clear, but old games don't follow it |
+
+**Original Grade**: **D** (Failed core modularity requirement)
+**Current Grade**: **B+** (Modularity achieved, some legacy migration pending)
+
+---
+
+## Positive Aspects (What Works Well)
+
+1. **✅ SDK Design** - Clean, well-documented, type-safe
+2. **✅ Client-Side Registry** - Simple, effective pattern
+3. **✅ GameDefinition Structure** - Good separation of concerns
+4. **✅ Documentation** - Comprehensive (though doesn't match reality)
+5. **✅ defineGame() Helper** - Makes game creation easy
+6. **✅ Type Safety** - Excellent TypeScript coverage
+7. **✅ Number Guesser Example** - Good reference implementation
+
+---
+
+## Recommendations
+
+### Immediate (This Sprint)
+
+1. ✅ **Document current reality** - Update docs to show both registrations required
+2. 🔴 **Create unified validator registry** - Implement Solution 1
+3. 🔴 **Update server to use unified registry** - Modify session-manager.ts and socket-server.ts
+
+### Next Sprint
+
+4. 🟡 **Migrate one old game** - Move matching to new structure as proof of concept
+5. 🟡 **Add registration validation** - Runtime checks for validator consistency
+6. 🟡 **Auto-derive GameName** - Remove hard-coded type union
+
+### Future
+
+7. 🟢 **Code generation** - Explore automated registry generation
+8. 🟢 **Plugin system** - True drop-in games with discovery
+9. 🟢 **Deprecate old validation system** - Once all games migrated
+
+---
+
+## Conclusion
+
+The modular game system has a **solid foundation** but is **not truly modular** due to server-side technical debt. The client-side implementation is excellent, but the server still uses a legacy hard-coded validation system.
+
+**Status**: Needs significant refactoring before claiming "modular architecture"
+
+**Path Forward**: Implement unified validator registry (Solution 1), then incrementally migrate old games.
+
+**Risk**: If we add more games before fixing this, technical debt will compound.
+
+---
+
+*This audit was conducted by reviewing:*
+- `src/lib/arcade/game-registry.ts`
+- `src/lib/arcade/validation/index.ts`
+- `src/lib/arcade/session-manager.ts`
+- `src/socket-server.ts`
+- `src/lib/arcade/game-sdk/`
+- `src/arcade-games/number-guesser/`
+- Documentation in `docs/` and `src/arcade-games/README.md`
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -59,6 +59,7 @@
    "drizzle-orm": "^0.44.6",
    "emojibase-data": "^16.0.3",
    "jose": "^6.1.0",
+    "js-yaml": "^4.1.0",
    "lucide-react": "^0.294.0",
    "make-plural": "^7.4.0",
    "nanoid": "^5.1.6",
@@ -80,6 +81,7 @@
    "@testing-library/react": "^16.3.0",
    "@types/bcryptjs": "^2.4.6",
    "@types/better-sqlite3": "^7.6.13",
+    "@types/js-yaml": "^4.0.9",
    "@types/node": "^20.0.0",
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
--- a/apps/web/src/app/api/arcade/rooms/[roomId]/settings/route.ts
+++ b/apps/web/src/app/api/arcade/rooms/[roomId]/settings/route.ts
@@ -20,7 +20,7 @@ type RouteContext = {
 * Body:
 *   - accessMode?: 'open' | 'locked' | 'retired' | 'password' | 'restricted' | 'approval-only'
 *   - password?: string (plain text, will be hashed)
- *   - gameName?: 'matching' | 'memory-quiz' | 'complement-race' | null (select game for room)
+ *   - gameName?: 'matching' | 'memory-quiz' | 'complement-race' | 'number-guesser' | null (select game for room)
 *   - gameConfig?: object (game-specific settings)
 */
 export async function PATCH(req: NextRequest, context: RouteContext) {
@@ -94,7 +94,8 @@ export async function PATCH(req: NextRequest, context: RouteContext) {

    // Validate gameName if provided
    if (body.gameName !== undefined && body.gameName !== null) {
-      const validGames = ['matching', 'memory-quiz', 'complement-race']
+      // Legacy games + registry games (TODO: make this dynamic when we refactor to lazy-load registry)
+      const validGames = ['matching', 'memory-quiz', 'complement-race', 'number-guesser']
      if (!validGames.includes(body.gameName)) {
        return NextResponse.json({ error: 'Invalid game name' }, { status: 400 })
      }
--- a/apps/web/src/app/api/arcade/rooms/route.ts
+++ b/apps/web/src/app/api/arcade/rooms/route.ts
@@ -3,7 +3,7 @@ import { createRoom, listActiveRooms } from '@/lib/arcade/room-manager'
 import { addRoomMember, getRoomMembers, isMember } from '@/lib/arcade/room-membership'
 import { getRoomActivePlayers } from '@/lib/arcade/player-manager'
 import { getViewerId } from '@/lib/viewer'
-import type { GameName } from '@/lib/arcade/validation'
+import { hasValidator, type GameName } from '@/lib/arcade/validators'

 /**
 * GET /api/arcade/rooms
@@ -72,8 +72,7 @@ export async function POST(req: NextRequest) {

    // Validate game name if provided (gameName is now optional)
    if (body.gameName) {
-      const validGames: GameName[] = ['matching', 'memory-quiz', 'complement-race']
-      if (!validGames.includes(body.gameName)) {
+      if (!hasValidator(body.gameName)) {
        return NextResponse.json({ error: 'Invalid game name' }, { status: 400 })
      }
    }
--- a/apps/web/src/app/arcade/room/page.tsx
+++ b/apps/web/src/app/arcade/room/page.tsx
@@ -10,6 +10,7 @@ import { GAMES_CONFIG } from '@/components/GameSelector'
 import type { GameType } from '@/components/GameSelector'
 import { PageWithNav } from '@/components/PageWithNav'
 import { css } from '../../../../styled-system/css'
+import { getAllGames, getGame, hasGame } from '@/lib/arcade/game-registry'

 // Map GameType keys to internal game names
 const GAME_TYPE_TO_NAME: Record<GameType, string> = {
@@ -89,13 +90,35 @@ export default function RoomPage() {
    const handleGameSelect = (gameType: GameType) => {
      console.log('[RoomPage] handleGameSelect called with gameType:', gameType)

-      const gameConfig = GAMES_CONFIG[gameType]
+      // Check if it's a registry game first
+      if (hasGame(gameType)) {
+        const gameDef = getGame(gameType)
+        if (!gameDef?.manifest.available) {
+          console.log('[RoomPage] Registry game not available, blocking selection')
+          return
+        }
+
+        console.log('[RoomPage] Selecting registry game:', gameType)
+        setRoomGame({
+          roomId: roomData.id,
+          gameName: gameType, // Use the game name directly for registry games
+        })
+        return
+      }
+
+      // Legacy game handling
+      const gameConfig = GAMES_CONFIG[gameType as keyof typeof GAMES_CONFIG]
+      if (!gameConfig) {
+        console.log('[RoomPage] Unknown game type:', gameType)
+        return
+      }
+
      console.log('[RoomPage] Game config:', {
        name: gameConfig.name,
-        available: gameConfig.available,
+        available: 'available' in gameConfig ? gameConfig.available : true,
      })

-      if (gameConfig.available === false) {
+      if ('available' in gameConfig && gameConfig.available === false) {
        console.log('[RoomPage] Game not available, blocking selection')
        return // Don't allow selecting unavailable games
      }
@@ -160,64 +183,158 @@ export default function RoomPage() {
              width: '100%',
            })}
          >
-            {Object.entries(GAMES_CONFIG).map(([gameType, config]) => (
-              <button
-                key={gameType}
-                onClick={() => handleGameSelect(gameType as GameType)}
-                disabled={config.available === false}
-                className={css({
-                  background: config.gradient,
-                  border: '2px solid',
-                  borderColor: config.borderColor || 'blue.200',
-                  borderRadius: '2xl',
-                  padding: '6',
-                  cursor: config.available === false ? 'not-allowed' : 'pointer',
-                  opacity: config.available === false ? 0.5 : 1,
-                  transition: 'all 0.3s ease',
-                  _hover:
-                    config.available === false
+            {/* Legacy games */}
+            {Object.entries(GAMES_CONFIG).map(([gameType, config]) => {
+              const isAvailable = !('available' in config) || config.available !== false
+              return (
+                <button
+                  key={gameType}
+                  onClick={() => handleGameSelect(gameType as GameType)}
+                  disabled={!isAvailable}
+                  className={css({
+                    background: config.gradient,
+                    border: '2px solid',
+                    borderColor: config.borderColor || 'blue.200',
+                    borderRadius: '2xl',
+                    padding: '6',
+                    cursor: !isAvailable ? 'not-allowed' : 'pointer',
+                    opacity: !isAvailable ? 0.5 : 1,
+                    transition: 'all 0.3s ease',
+                    _hover: !isAvailable
                      ? {}
                      : {
                          transform: 'translateY(-4px) scale(1.02)',
                          boxShadow: '0 20px 40px rgba(59, 130, 246, 0.2)',
                        },
-                })}
-              >
-                <div
-                  className={css({
-                    fontSize: '4xl',
-                    mb: '2',
                  })}
                >
-                  {config.icon}
-                </div>
-                <h3
+                  <div
+                    className={css({
+                      fontSize: '4xl',
+                      mb: '2',
+                    })}
+                  >
+                    {config.icon}
+                  </div>
+                  <h3
+                    className={css({
+                      fontSize: 'xl',
+                      fontWeight: 'bold',
+                      color: 'gray.900',
+                      mb: '2',
+                    })}
+                  >
+                    {config.name}
+                  </h3>
+                  <p
+                    className={css({
+                      fontSize: 'sm',
+                      color: 'gray.600',
+                    })}
+                  >
+                    {config.description}
+                  </p>
+                </button>
+              )
+            })}
+
+            {/* Registry games */}
+            {getAllGames().map((gameDef) => {
+              const isAvailable = gameDef.manifest.available
+              return (
+                <button
+                  key={gameDef.manifest.name}
+                  onClick={() => handleGameSelect(gameDef.manifest.name)}
+                  disabled={!isAvailable}
                  className={css({
-                    fontSize: 'xl',
-                    fontWeight: 'bold',
-                    color: 'gray.900',
-                    mb: '2',
+                    background: gameDef.manifest.gradient,
+                    border: '2px solid',
+                    borderColor: gameDef.manifest.borderColor,
+                    borderRadius: '2xl',
+                    padding: '6',
+                    cursor: !isAvailable ? 'not-allowed' : 'pointer',
+                    opacity: !isAvailable ? 0.5 : 1,
+                    transition: 'all 0.3s ease',
+                    _hover: !isAvailable
+                      ? {}
+                      : {
+                          transform: 'translateY(-4px) scale(1.02)',
+                          boxShadow: '0 20px 40px rgba(59, 130, 246, 0.2)',
+                        },
                  })}
                >
-                  {config.name}
-                </h3>
-                <p
-                  className={css({
-                    fontSize: 'sm',
-                    color: 'gray.600',
-                  })}
-                >
-                  {config.description}
-                </p>
-              </button>
-            ))}
+                  <div
+                    className={css({
+                      fontSize: '4xl',
+                      mb: '2',
+                    })}
+                  >
+                    {gameDef.manifest.icon}
+                  </div>
+                  <h3
+                    className={css({
+                      fontSize: 'xl',
+                      fontWeight: 'bold',
+                      color: 'gray.900',
+                      mb: '2',
+                    })}
+                  >
+                    {gameDef.manifest.displayName}
+                  </h3>
+                  <p
+                    className={css({
+                      fontSize: 'sm',
+                      color: 'gray.600',
+                    })}
+                  >
+                    {gameDef.manifest.description}
+                  </p>
+                </button>
+              )
+            })}
          </div>
        </div>
      </PageWithNav>
    )
  }

-  // Render the appropriate game based on room's gameName
+  // Check if this is a registry game first
+  if (hasGame(roomData.gameName)) {
+    const gameDef = getGame(roomData.gameName)
+    if (!gameDef) {
+      return (
+        <PageWithNav
+          navTitle="Game Not Found"
+          navEmoji="⚠️"
+          emphasizePlayerSelection={true}
+          onExitSession={() => router.push('/arcade')}
+        >
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              height: '100vh',
+              fontSize: '18px',
+              color: '#666',
+            }}
+          >
+            Game "{roomData.gameName}" not found in registry
+          </div>
+        </PageWithNav>
+      )
+    }
+
+    // Render registry game dynamically
+    const { Provider, GameComponent } = gameDef
+    return (
+      <Provider>
+        <GameComponent />
+      </Provider>
+    )
+  }
+
+  // Render legacy games based on room's gameName
  switch (roomData.gameName) {
    case 'matching':
      return (
--- a/apps/web/src/arcade-games/README.md
+++ b/apps/web/src/arcade-games/README.md
@@ -0,0 +1,816 @@
+# Arcade Game System
+
+A modular, plugin-based architecture for building multiplayer arcade games with real-time synchronization.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Game SDK](#game-sdk)
+- [Creating a New Game](#creating-a-new-game)
+- [File Structure](#file-structure)
+- [Examples](#examples)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+### Goals
+
+1. **Modularity**: Each game is self-contained and independently deployable
+2. **Type Safety**: Full TypeScript support with compile-time validation
+3. **Real-time Sync**: Built-in multiplayer support via WebSocket
+4. **Optimistic Updates**: Instant client feedback with server validation
+5. **Consistent UX**: Shared navigation, player management, and room features
+
+### Key Features
+
+- **Plugin Architecture**: Games register themselves with a central registry
+- **Stable SDK API**: Games only import from `@/lib/arcade/game-sdk`
+- **Server-side Validation**: All moves validated server-side with client rollback
+- **Automatic State Sync**: Multi-client synchronization handled automatically
+- **Turn Indicators**: Built-in UI for showing active player
+- **Error Handling**: Standardized error feedback to users
+
+---
+
+## Architecture
+
+### System Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Game Registry                            │
+│  - Registers all available games                            │
+│  - Provides game discovery                                  │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      Game SDK                                │
+│  - Stable API surface for games                             │
+│  - React hooks (useArcadeSession, useRoomData, etc.)        │
+│  - Type definitions and utilities                           │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Individual Games                           │
+│  number-guesser/                                            │
+│    ├── index.ts          (Game definition)                  │
+│    ├── Validator.ts      (Server validation)                │
+│    ├── Provider.tsx      (Client state management)          │
+│    ├── GameComponent.tsx (Main UI)                          │
+│    ├── types.ts          (TypeScript types)                 │
+│    └── components/       (Phase UIs)                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow
+
+```
+User Action → Provider (sendMove)
+              ↓
+        useArcadeSession
+              ↓
+        Optimistic Update (instant UI feedback)
+              ↓
+        WebSocket → Server
+              ↓
+        Validator.validateMove()
+              ↓
+        ✓ Valid: State Update → Broadcast
+        ✗ Invalid: Reject → Client Rollback
+              ↓
+        Client receives validated state
+```
+
+---
+
+## Game SDK
+
+### Core API Surface
+
+```typescript
+import {
+  // Types
+  type GameDefinition,
+  type GameValidator,
+  type GameState,
+  type GameMove,
+  type GameConfig,
+  type ValidationResult,
+
+  // React Hooks
+  useArcadeSession,
+  useRoomData,
+  useGameMode,
+  useViewerId,
+  useUpdateGameConfig,
+
+  // Utilities
+  defineGame,
+  buildPlayerMetadata,
+
+} from '@/lib/arcade/game-sdk'
+```
+
+### Key Concepts
+
+#### GameDefinition
+
+Complete description of a game:
+
+```typescript
+interface GameDefinition<TConfig, TState, TMove> {
+  manifest: GameManifest          // Display info, max players, etc.
+  Provider: GameProviderComponent // React context provider
+  GameComponent: GameComponent    // Main UI component
+  validator: GameValidator        // Server-side validation
+  defaultConfig: TConfig          // Default game settings
+}
+```
+
+#### GameState
+
+The complete game state that's synchronized across all clients:
+
+```typescript
+interface GameState {
+  gamePhase: string                          // Current phase (setup, playing, results)
+  activePlayers: string[]                    // Array of player IDs
+  playerMetadata: Record<string, PlayerMeta> // Player info (name, emoji, etc.)
+  // ... game-specific state
+}
+```
+
+#### GameMove
+
+Actions that players take, validated server-side:
+
+```typescript
+interface GameMove {
+  type: string           // Move type (e.g., 'FLIP_CARD', 'MAKE_GUESS')
+  playerId: string       // Player making the move
+  userId: string         // User ID (for authentication)
+  timestamp: number      // Client timestamp
+  data: Record<string, unknown> // Move-specific payload
+}
+```
+
+#### GameValidator
+
+Server-side validation logic:
+
+```typescript
+interface GameValidator<TState, TMove> {
+  validateMove(state: TState, move: TMove): ValidationResult
+  isGameComplete(state: TState): boolean
+  getInitialState(config: unknown): TState
+}
+```
+
+---
+
+## Creating a New Game
+
+### Step 1: Create Game Directory
+
+```bash
+mkdir -p src/arcade-games/my-game/components
+```
+
+### Step 2: Define Types (`types.ts`)
+
+```typescript
+import type { GameConfig, GameMove, GameState } from '@/lib/arcade/game-sdk'
+
+// Game configuration (persisted to database)
+export interface MyGameConfig extends GameConfig {
+  difficulty: number
+  timer: number
+}
+
+// Game state (synchronized across clients)
+export interface MyGameState extends GameState {
+  gamePhase: 'setup' | 'playing' | 'results'
+  activePlayers: string[]
+  playerMetadata: Record<string, PlayerMetadata>
+  currentPlayer: string
+  score: Record<string, number>
+  // ... your game-specific state
+}
+
+// Move types
+export type MyGameMove =
+  | { type: 'START_GAME'; playerId: string; userId: string; timestamp: number; data: { activePlayers: string[] } }
+  | { type: 'MAKE_MOVE'; playerId: string; userId: string; timestamp: number; data: { /* move data */ } }
+  | { type: 'END_GAME'; playerId: string; userId: string; timestamp: number; data: {} }
+```
+
+### Step 3: Create Validator (`Validator.ts`)
+
+```typescript
+import type { GameValidator, ValidationResult } from '@/lib/arcade/game-sdk'
+import type { MyGameState, MyGameMove } from './types'
+
+export class MyGameValidator implements GameValidator<MyGameState, MyGameMove> {
+  validateMove(state: MyGameState, move: MyGameMove): ValidationResult {
+    switch (move.type) {
+      case 'START_GAME':
+        return this.validateStartGame(state, move.data.activePlayers)
+      case 'MAKE_MOVE':
+        return this.validateMakeMove(state, move.playerId, move.data)
+      default:
+        return { valid: false, error: 'Unknown move type' }
+    }
+  }
+
+  private validateStartGame(state: MyGameState, activePlayers: string[]): ValidationResult {
+    if (activePlayers.length < 2) {
+      return { valid: false, error: 'Need at least 2 players' }
+    }
+
+    const newState: MyGameState = {
+      ...state,
+      gamePhase: 'playing',
+      activePlayers,
+      currentPlayer: activePlayers[0],
+      score: activePlayers.reduce((acc, p) => ({ ...acc, [p]: 0 }), {}),
+    }
+
+    return { valid: true, newState }
+  }
+
+  // ... more validation methods
+
+  isGameComplete(state: MyGameState): boolean {
+    return state.gamePhase === 'results'
+  }
+
+  getInitialState(config: unknown): MyGameState {
+    const { difficulty, timer } = config as MyGameConfig
+    return {
+      difficulty,
+      timer,
+      gamePhase: 'setup',
+      activePlayers: [],
+      playerMetadata: {},
+      currentPlayer: '',
+      score: {},
+    }
+  }
+}
+
+export const myGameValidator = new MyGameValidator()
+```
+
+### Step 4: Create Provider (`Provider.tsx`)
+
+```typescript
+'use client'
+
+import { createContext, useCallback, useContext, useMemo } from 'react'
+import {
+  type GameMove,
+  buildPlayerMetadata,
+  useArcadeSession,
+  useGameMode,
+  useRoomData,
+  useViewerId,
+} from '@/lib/arcade/game-sdk'
+import type { MyGameState } from './types'
+
+interface MyGameContextValue {
+  state: MyGameState
+  lastError: string | null
+  startGame: () => void
+  makeMove: (data: any) => void
+  clearError: () => void
+  exitSession: () => void
+}
+
+const MyGameContext = createContext<MyGameContextValue | null>(null)
+
+export function useMyGame() {
+  const context = useContext(MyGameContext)
+  if (!context) throw new Error('useMyGame must be used within MyGameProvider')
+  return context
+}
+
+export function MyGameProvider({ children }: { children: React.ReactNode }) {
+  const { data: viewerId } = useViewerId()
+  const { roomData } = useRoomData()
+  const { activePlayers: activePlayerIds, players } = useGameMode()
+
+  // Get active players as array (keep Set iteration order to match UI display)
+  const activePlayers = Array.from(activePlayerIds)
+
+  const initialState = useMemo(() => ({
+    difficulty: 1,
+    timer: 30,
+    gamePhase: 'setup' as const,
+    activePlayers: [],
+    playerMetadata: {},
+    currentPlayer: '',
+    score: {},
+  }), [])
+
+  const { state, sendMove, exitSession, lastError, clearError } =
+    useArcadeSession<MyGameState>({
+      userId: viewerId || '',
+      roomId: roomData?.id,
+      initialState,
+      applyMove: (state, move) => state, // Server handles all updates
+    })
+
+  const startGame = useCallback(() => {
+    const playerMetadata = buildPlayerMetadata(activePlayers, {}, players, viewerId)
+
+    sendMove({
+      type: 'START_GAME',
+      playerId: activePlayers[0],
+      userId: viewerId || '',
+      data: { activePlayers, playerMetadata },
+    })
+  }, [activePlayers, players, viewerId, sendMove])
+
+  const makeMove = useCallback((data: any) => {
+    sendMove({
+      type: 'MAKE_MOVE',
+      playerId: state.currentPlayer,
+      userId: viewerId || '',
+      data,
+    })
+  }, [state.currentPlayer, viewerId, sendMove])
+
+  return (
+    <MyGameContext.Provider value={{
+      state,
+      lastError,
+      startGame,
+      makeMove,
+      clearError,
+      exitSession,
+    }}>
+      {children}
+    </MyGameContext.Provider>
+  )
+}
+```
+
+### Step 5: Create Game Component (`GameComponent.tsx`)
+
+```typescript
+'use client'
+
+import { useRouter } from 'next/navigation'
+import { PageWithNav } from '@/components/PageWithNav'
+import { useMyGame } from '../Provider'
+import { SetupPhase } from './SetupPhase'
+import { PlayingPhase } from './PlayingPhase'
+import { ResultsPhase } from './ResultsPhase'
+
+export function GameComponent() {
+  const router = useRouter()
+  const { state, exitSession } = useMyGame()
+
+  // Determine whose turn it is for the turn indicator
+  const currentPlayerId = state.gamePhase === 'playing' ? state.currentPlayer : undefined
+
+  return (
+    <PageWithNav
+      navTitle="My Game"
+      navEmoji="🎮"
+      emphasizePlayerSelection={state.gamePhase === 'setup'}
+      currentPlayerId={currentPlayerId}
+      playerScores={state.score}
+      onExitSession={() => {
+        exitSession()
+        router.push('/arcade')
+      }}
+    >
+      {state.gamePhase === 'setup' && <SetupPhase />}
+      {state.gamePhase === 'playing' && <PlayingPhase />}
+      {state.gamePhase === 'results' && <ResultsPhase />}
+    </PageWithNav>
+  )
+}
+```
+
+### Step 6: Define Game (`index.ts`)
+
+```typescript
+import { defineGame } from '@/lib/arcade/game-sdk'
+import type { GameManifest } from '@/lib/arcade/game-sdk'
+import { GameComponent } from './components/GameComponent'
+import { MyGameProvider } from './Provider'
+import type { MyGameConfig, MyGameMove, MyGameState } from './types'
+import { myGameValidator } from './Validator'
+
+const manifest: GameManifest = {
+  name: 'my-game',
+  displayName: 'My Awesome Game',
+  icon: '🎮',
+  description: 'A fun multiplayer game',
+  longDescription: 'Detailed description of gameplay...',
+  maxPlayers: 4,
+  difficulty: 'Beginner',
+  chips: ['👥 Multiplayer', '🎲 Turn-Based'],
+  color: 'blue',
+  gradient: 'linear-gradient(135deg, #bfdbfe, #93c5fd)',
+  borderColor: 'blue.200',
+  available: true,
+}
+
+const defaultConfig: MyGameConfig = {
+  difficulty: 1,
+  timer: 30,
+}
+
+export const myGame = defineGame<MyGameConfig, MyGameState, MyGameMove>({
+  manifest,
+  Provider: MyGameProvider,
+  GameComponent,
+  validator: myGameValidator,
+  defaultConfig,
+})
+```
+
+### Step 7: Register Game
+
+#### 7a. Register Validator (Server-Side)
+
+Add your validator to the unified registry in `src/lib/arcade/validators.ts`:
+
+```typescript
+import { myGameValidator } from '@/arcade-games/my-game/Validator'
+
+export const validatorRegistry = {
+  matching: matchingGameValidator,
+  'memory-quiz': memoryQuizGameValidator,
+  'number-guesser': numberGuesserValidator,
+  'my-game': myGameValidator,  // Add your game here!
+  // GameName type will auto-update from these keys
+} as const
+```
+
+**Why**: The validator registry is isomorphic (runs on both client and server) and serves as the single source of truth for all game validators. Adding your validator here automatically:
+- Makes it available for server-side move validation
+- Updates the `GameName` type (no manual type updates needed!)
+- Enables your game for multiplayer rooms
+
+#### 7b. Register Game Definition (Client-Side)
+
+Add to `src/lib/arcade/game-registry.ts`:
+
+```typescript
+import { myGame } from '@/arcade-games/my-game'
+
+registerGame(myGame)
+```
+
+**Why**: The game registry is client-only and connects your game's UI components (Provider, GameComponent) with the arcade system. Registration happens on client init and verifies that your validator is also registered server-side.
+
+**Verification**: When you register a game, the registry will warn you if:
+- ⚠️  The validator is missing from `validators.ts`
+- ⚠️  The validator instance doesn't match (different imports)
+
+**Important**: Both steps are required for a working game. The validator registry handles server logic, while the game registry handles client UI.
+
+---
+
+## File Structure
+
+```
+src/arcade-games/my-game/
+├── index.ts                 # Game definition and export
+├── Validator.ts             # Server-side move validation
+├── Provider.tsx             # Client state management
+├── GameComponent.tsx        # Main UI wrapper
+├── types.ts                 # TypeScript type definitions
+└── components/
+    ├── SetupPhase.tsx       # Setup/lobby UI
+    ├── PlayingPhase.tsx     # Main gameplay UI
+    └── ResultsPhase.tsx     # End game/scores UI
+```
+
+### File Responsibilities
+
+| File | Purpose | Runs On |
+|------|---------|---------|
+| `index.ts` | Game registration | Both |
+| `Validator.ts` | Move validation, game logic | **Server only** |
+| `Provider.tsx` | State management, API calls | Client only |
+| `GameComponent.tsx` | Navigation, phase routing | Client only |
+| `types.ts` | Shared type definitions | Both |
+| `components/*` | UI for each game phase | Client only |
+
+---
+
+## Examples
+
+### Number Guesser (Turn-Based)
+
+See `src/arcade-games/number-guesser/` for a complete example of:
+- Turn-based gameplay (chooser → guessers)
+- Player rotation logic
+- Round management
+- Score tracking
+- Hot/cold feedback system
+- Error handling and user feedback
+
+**Key Patterns:**
+- Setting `currentPlayerId` for turn indicators
+- Rotating turns in validator
+- Handling round vs. game completion
+- Type coercion for JSON-serialized numbers
+
+---
+
+## Best Practices
+
+### 1. Player Ordering Consistency
+
+**Problem**: Sets don't guarantee order, causing mismatch between UI and game logic.
+
+**Solution**: Use `Array.from(activePlayerIds)` without sorting in both UI and game logic.
+
+```typescript
+// In Provider
+const activePlayers = Array.from(activePlayerIds) // NO .sort()
+
+// In Validator
+const newState = {
+  ...state,
+  currentPlayer: activePlayers[0], // First in Set order = first in UI
+}
+```
+
+### 2. Type Coercion for Numbers
+
+**Problem**: WebSocket JSON serialization converts numbers to strings.
+
+**Solution**: Explicitly coerce in validator:
+
+```typescript
+validateMove(state: MyGameState, move: MyGameMove): ValidationResult {
+  switch (move.type) {
+    case 'MAKE_GUESS':
+      return this.validateGuess(state, Number(move.data.guess)) // Coerce!
+  }
+}
+```
+
+### 3. Error Feedback
+
+**Problem**: Users don't see why their moves were rejected.
+
+**Solution**: Use `lastError` from `useArcadeSession`:
+
+```typescript
+const { state, lastError, clearError } = useArcadeSession(...)
+
+// Auto-dismiss after 5 seconds
+useEffect(() => {
+  if (lastError) {
+    const timeout = setTimeout(() => clearError(), 5000)
+    return () => clearTimeout(timeout)
+  }
+}, [lastError, clearError])
+
+// Show in UI
+{lastError && (
+  <div className="error-banner">
+    <div>⚠️ Move Rejected</div>
+    <div>{lastError}</div>
+    <button onClick={clearError}>Dismiss</button>
+  </div>
+)}
+```
+
+### 4. Turn Indicators
+
+**Problem**: Players don't know whose turn it is.
+
+**Solution**: Pass `currentPlayerId` to `PageWithNav`:
+
+```typescript
+<PageWithNav
+  currentPlayerId={state.currentPlayer}
+  playerScores={state.scores}
+>
+```
+
+### 5. Server-Only Logic
+
+**Problem**: Client can cheat by modifying local state.
+
+**Solution**: All game logic in validator, client uses `applyMove: (state) => state`:
+
+```typescript
+// ❌ BAD: Client calculates winner
+const { state, sendMove } = useArcadeSession({
+  applyMove: (state, move) => {
+    if (move.type === 'SCORE') {
+      return { ...state, winner: calculateWinner(state) } // Cheatable!
+    }
+  }
+})
+
+// ✅ GOOD: Server calculates everything
+const { state, sendMove } = useArcadeSession({
+  applyMove: (state, move) => state // Client just waits for server
+})
+```
+
+### 6. Phase Management
+
+Use discriminated union for type-safe phase rendering:
+
+```typescript
+type GamePhase = 'setup' | 'playing' | 'results'
+
+interface MyGameState {
+  gamePhase: GamePhase
+  // ...
+}
+
+// In GameComponent
+{state.gamePhase === 'setup' && <SetupPhase />}
+{state.gamePhase === 'playing' && <PlayingPhase />}
+{state.gamePhase === 'results' && <ResultsPhase />}
+```
+
+---
+
+## Troubleshooting
+
+### "Player not found" errors
+
+**Cause**: Player IDs from `useGameMode()` don't match server state.
+
+**Fix**: Always use `buildPlayerMetadata()` helper:
+
+```typescript
+const playerMetadata = buildPlayerMetadata(activePlayers, {}, players, viewerId)
+```
+
+### Turn indicator not showing
+
+**Cause**: `currentPlayerId` not passed or doesn't match player IDs in UI.
+
+**Fix**: Verify player order matches between game state and `activePlayerIds`:
+
+```typescript
+// Both should use same source without sorting
+const activePlayers = Array.from(activePlayerIds) // Provider
+const activePlayerList = Array.from(activePlayers) // PageWithNav
+```
+
+### Moves rejected with type errors
+
+**Cause**: JSON serialization converts numbers to strings.
+
+**Fix**: Add `Number()` coercion in validator:
+
+```typescript
+case 'SET_VALUE':
+  return this.validateValue(state, Number(move.data.value))
+```
+
+### State not syncing across clients
+
+**Cause**: Not using `useArcadeSession` correctly.
+
+**Fix**: Ensure `roomId` is passed:
+
+```typescript
+const { state, sendMove } = useArcadeSession({
+  userId: viewerId || '',
+  roomId: roomData?.id, // Required for room sync!
+  initialState,
+  applyMove: (state) => state,
+})
+```
+
+### Game not appearing in selector
+
+**Cause**: Not registered or `available: false`.
+
+**Fix**:
+1. Add to `game-registry.ts`: `registerGame(myGame)`
+2. Set `available: true` in manifest
+3. Verify no console errors on import
+
+### Config changes not taking effect
+
+**Cause**: State sync timing - validator uses old state while config is being updated.
+
+**Context**: When you change game config (e.g., min/max numbers), there's a brief window where:
+1. Client updates config in database
+2. Config change hasn't propagated to server state yet
+3. Moves are validated against old state
+
+**Fix**: Ensure config changes trigger state reset or are applied atomically:
+
+```typescript
+// When changing config, also update initialState
+const setConfig = useCallback((field, value) => {
+  sendMove({ type: 'SET_CONFIG', data: { field, value } })
+
+  // Persist to database for next session
+  if (roomData?.id) {
+    updateGameConfig({
+      roomId: roomData.id,
+      gameConfig: {
+        ...roomData.gameConfig,
+        'my-game': { ...currentConfig, [field]: value }
+      }
+    })
+  }
+}, [sendMove, updateGameConfig, roomData])
+```
+
+**Best Practice**: Make config changes only during setup phase, before game starts.
+
+### Debugging validation errors
+
+**Problem**: Moves rejected but unclear why (especially type-related issues).
+
+**Solution**: Add debug logging in validator:
+
+```typescript
+private validateGuess(state: State, guess: number): ValidationResult {
+  // Debug logging
+  console.log('[MyGame] Validating guess:', {
+    guess,
+    guessType: typeof guess,           // Check if it's a string!
+    min: state.minNumber,
+    minType: typeof state.minNumber,
+    max: state.maxNumber,
+    maxType: typeof state.maxNumber,
+  })
+
+  if (guess < state.minNumber || guess > state.maxNumber) {
+    return { valid: false, error: `Guess must be between ${state.minNumber} and ${state.maxNumber}` }
+  }
+
+  // ... rest of validation
+}
+```
+
+**What to check:**
+1. **Browser console**: Look for `[ArcadeSession] Move rejected by server:` messages
+2. **Server logs**: Check validator console.log output for types and values
+3. **Type mismatches**: Numbers becoming strings is the #1 issue
+4. **State sync**: Is the validator using the state you expect?
+
+**Common debugging workflow:**
+1. Move rejected → Check browser console for error message
+2. Error unclear → Add console.log to validator
+3. Restart server → See debug output when move is made
+4. Compare expected vs. actual values/types
+5. Add `Number()` coercion if types don't match
+
+---
+
+## Resources
+
+- **Game SDK**: `src/lib/arcade/game-sdk/`
+- **Registry**: `src/lib/arcade/game-registry.ts`
+- **Example Game**: `src/arcade-games/number-guesser/`
+- **Validation Types**: `src/lib/arcade/validation/types.ts`
+
+---
+
+## FAQ
+
+**Q: Can I use external libraries in my game?**
+A: Yes, but install them in the workspace package.json. Games should be self-contained.
+
+**Q: How do I add game configuration that persists?**
+A: Use `useUpdateGameConfig()` to save to room:
+
+```typescript
+const { mutate: updateGameConfig } = useUpdateGameConfig()
+
+updateGameConfig({
+  roomId: roomData.id,
+  gameConfig: {
+    ...roomData.gameConfig,
+    'my-game': { difficulty: 5 }
+  }
+})
+```
+
+**Q: Can I have asymmetric player roles?**
+A: Yes! See Number Guesser's chooser/guesser pattern.
+
+**Q: How do I handle real-time timers?**
+A: Store `startTime` in state, use client-side countdown, server validates elapsed time.
+
+**Q: What's the difference between `playerId` and `userId`?**
+A: `userId` is the user account, `playerId` is the avatar/character in the game. One user can control multiple players.
--- a/apps/web/src/arcade-games/number-guesser/Provider.tsx
+++ b/apps/web/src/arcade-games/number-guesser/Provider.tsx
@@ -0,0 +1,215 @@
+/**
+ * Number Guesser Provider
+ * Manages game state using the Arcade SDK
+ */
+
+'use client'
+
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from 'react'
+import {
+  type GameMove,
+  buildPlayerMetadata,
+  useArcadeSession,
+  useGameMode,
+  useRoomData,
+  useUpdateGameConfig,
+  useViewerId,
+} from '@/lib/arcade/game-sdk'
+import type { NumberGuesserState } from './types'
+
+/**
+ * Context value interface
+ */
+interface NumberGuesserContextValue {
+  state: NumberGuesserState
+  lastError: string | null
+  startGame: () => void
+  chooseNumber: (number: number) => void
+  makeGuess: (guess: number) => void
+  nextRound: () => void
+  goToSetup: () => void
+  setConfig: (field: 'minNumber' | 'maxNumber' | 'roundsToWin', value: number) => void
+  clearError: () => void
+  exitSession: () => void
+}
+
+const NumberGuesserContext = createContext<NumberGuesserContextValue | null>(null)
+
+/**
+ * Hook to access Number Guesser context
+ */
+export function useNumberGuesser() {
+  const context = useContext(NumberGuesserContext)
+  if (!context) {
+    throw new Error('useNumberGuesser must be used within NumberGuesserProvider')
+  }
+  return context
+}
+
+/**
+ * Optimistic move application
+ */
+function applyMoveOptimistically(state: NumberGuesserState, move: GameMove): NumberGuesserState {
+  // For simplicity, just return current state
+  // Server will send back the validated new state
+  return state
+}
+
+/**
+ * Number Guesser Provider Component
+ */
+export function NumberGuesserProvider({ children }: { children: ReactNode }) {
+  const { data: viewerId } = useViewerId()
+  const { roomData } = useRoomData()
+  const { activePlayers: activePlayerIds, players } = useGameMode()
+  const { mutate: updateGameConfig } = useUpdateGameConfig()
+
+  // Get active players as array (keep Set iteration order to match UI display)
+  const activePlayers = Array.from(activePlayerIds)
+
+  // Merge saved config from room
+  const initialState = useMemo(() => {
+    const gameConfig = roomData?.gameConfig as Record<string, unknown> | null | undefined
+    const savedConfig = gameConfig?.['number-guesser'] as Record<string, unknown> | undefined
+
+    return {
+      minNumber: (savedConfig?.minNumber as number) || 1,
+      maxNumber: (savedConfig?.maxNumber as number) || 100,
+      roundsToWin: (savedConfig?.roundsToWin as number) || 3,
+      gamePhase: 'setup' as const,
+      activePlayers: [],
+      playerMetadata: {},
+      secretNumber: null,
+      chooser: '',
+      currentGuesser: '',
+      guesses: [],
+      roundNumber: 0,
+      scores: {},
+      gameStartTime: null,
+      gameEndTime: null,
+      winner: null,
+    }
+  }, [roomData?.gameConfig])
+
+  // Arcade session integration
+  const { state, sendMove, exitSession, lastError, clearError } =
+    useArcadeSession<NumberGuesserState>({
+      userId: viewerId || '',
+      roomId: roomData?.id,
+      initialState,
+      applyMove: applyMoveOptimistically,
+    })
+
+  // Action creators
+  const startGame = useCallback(() => {
+    if (activePlayers.length < 2) {
+      console.error('Need at least 2 players to start')
+      return
+    }
+
+    const playerMetadata = buildPlayerMetadata(activePlayers, {}, players, viewerId || undefined)
+
+    sendMove({
+      type: 'START_GAME',
+      playerId: activePlayers[0],
+      userId: viewerId || '',
+      data: {
+        activePlayers,
+        playerMetadata,
+      },
+    })
+  }, [activePlayers, players, viewerId, sendMove])
+
+  const chooseNumber = useCallback(
+    (secretNumber: number) => {
+      sendMove({
+        type: 'CHOOSE_NUMBER',
+        playerId: state.chooser,
+        userId: viewerId || '',
+        data: { secretNumber },
+      })
+    },
+    [state.chooser, viewerId, sendMove]
+  )
+
+  const makeGuess = useCallback(
+    (guess: number) => {
+      const playerName = state.playerMetadata[state.currentGuesser]?.name || 'Unknown'
+
+      sendMove({
+        type: 'MAKE_GUESS',
+        playerId: state.currentGuesser,
+        userId: viewerId || '',
+        data: { guess, playerName },
+      })
+    },
+    [state.currentGuesser, state.playerMetadata, viewerId, sendMove]
+  )
+
+  const nextRound = useCallback(() => {
+    sendMove({
+      type: 'NEXT_ROUND',
+      playerId: activePlayers[0] || '',
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [activePlayers, viewerId, sendMove])
+
+  const goToSetup = useCallback(() => {
+    sendMove({
+      type: 'GO_TO_SETUP',
+      playerId: activePlayers[0] || state.chooser || '',
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [activePlayers, state.chooser, viewerId, sendMove])
+
+  const setConfig = useCallback(
+    (field: 'minNumber' | 'maxNumber' | 'roundsToWin', value: number) => {
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId: activePlayers[0] || '',
+        userId: viewerId || '',
+        data: { field, value },
+      })
+
+      // Persist to database
+      if (roomData?.id) {
+        const currentGameConfig = (roomData.gameConfig as Record<string, unknown>) || {}
+        const currentNumberGuesserConfig =
+          (currentGameConfig['number-guesser'] as Record<string, unknown>) || {}
+
+        const updatedConfig = {
+          ...currentGameConfig,
+          'number-guesser': {
+            ...currentNumberGuesserConfig,
+            [field]: value,
+          },
+        }
+
+        updateGameConfig({
+          roomId: roomData.id,
+          gameConfig: updatedConfig,
+        })
+      }
+    },
+    [activePlayers, viewerId, sendMove, roomData?.id, roomData?.gameConfig, updateGameConfig]
+  )
+
+  const contextValue: NumberGuesserContextValue = {
+    state,
+    lastError,
+    startGame,
+    chooseNumber,
+    makeGuess,
+    nextRound,
+    goToSetup,
+    setConfig,
+    clearError,
+    exitSession,
+  }
+
+  return (
+    <NumberGuesserContext.Provider value={contextValue}>{children}</NumberGuesserContext.Provider>
+  )
+}
--- a/apps/web/src/arcade-games/number-guesser/Validator.ts
+++ b/apps/web/src/arcade-games/number-guesser/Validator.ts
@@ -0,0 +1,315 @@
+/**
+ * Server-side validator for Number Guesser game
+ */
+
+import type { GameValidator, ValidationResult } from '@/lib/arcade/game-sdk'
+import type { NumberGuesserConfig, NumberGuesserMove, NumberGuesserState } from './types'
+
+export class NumberGuesserValidator
+  implements GameValidator<NumberGuesserState, NumberGuesserMove>
+{
+  validateMove(state: NumberGuesserState, move: NumberGuesserMove): ValidationResult {
+    switch (move.type) {
+      case 'START_GAME':
+        return this.validateStartGame(state, move.data.activePlayers, move.data.playerMetadata)
+
+      case 'CHOOSE_NUMBER':
+        // Ensure secretNumber is a number (JSON deserialization can make it a string)
+        return this.validateChooseNumber(state, Number(move.data.secretNumber), move.playerId)
+
+      case 'MAKE_GUESS':
+        // Ensure guess is a number (JSON deserialization can make it a string)
+        return this.validateMakeGuess(
+          state,
+          Number(move.data.guess),
+          move.playerId,
+          move.data.playerName
+        )
+
+      case 'NEXT_ROUND':
+        return this.validateNextRound(state)
+
+      case 'GO_TO_SETUP':
+        return this.validateGoToSetup(state)
+
+      case 'SET_CONFIG':
+        // Ensure value is a number (JSON deserialization can make it a string)
+        return this.validateSetConfig(state, move.data.field, Number(move.data.value))
+
+      default:
+        return {
+          valid: false,
+          error: `Unknown move type: ${(move as { type: string }).type}`,
+        }
+    }
+  }
+
+  private validateStartGame(
+    state: NumberGuesserState,
+    activePlayers: string[],
+    playerMetadata: Record<string, unknown>
+  ): ValidationResult {
+    if (!activePlayers || activePlayers.length < 2) {
+      return { valid: false, error: 'Need at least 2 players' }
+    }
+
+    const newState: NumberGuesserState = {
+      ...state,
+      gamePhase: 'choosing',
+      activePlayers,
+      playerMetadata: playerMetadata as typeof state.playerMetadata,
+      chooser: activePlayers[0],
+      currentGuesser: '',
+      secretNumber: null,
+      guesses: [],
+      roundNumber: 1,
+      scores: activePlayers.reduce((acc, p) => ({ ...acc, [p]: 0 }), {}),
+      gameStartTime: Date.now(),
+      gameEndTime: null,
+      winner: null,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateChooseNumber(
+    state: NumberGuesserState,
+    secretNumber: number,
+    playerId: string
+  ): ValidationResult {
+    if (state.gamePhase !== 'choosing') {
+      return { valid: false, error: 'Not in choosing phase' }
+    }
+
+    if (playerId !== state.chooser) {
+      return { valid: false, error: 'Not your turn to choose' }
+    }
+
+    if (
+      secretNumber < state.minNumber ||
+      secretNumber > state.maxNumber ||
+      !Number.isInteger(secretNumber)
+    ) {
+      return {
+        valid: false,
+        error: `Number must be between ${state.minNumber} and ${state.maxNumber}`,
+      }
+    }
+
+    // Debug logging
+    console.log('[NumberGuesser] Setting secret number:', {
+      secretNumber,
+      secretNumberType: typeof secretNumber,
+    })
+
+    // First guesser is the next player after chooser
+    const chooserIndex = state.activePlayers.indexOf(state.chooser)
+    const firstGuesserIndex = (chooserIndex + 1) % state.activePlayers.length
+    const firstGuesser = state.activePlayers[firstGuesserIndex]
+
+    const newState: NumberGuesserState = {
+      ...state,
+      gamePhase: 'guessing',
+      secretNumber,
+      currentGuesser: firstGuesser,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateMakeGuess(
+    state: NumberGuesserState,
+    guess: number,
+    playerId: string,
+    playerName: string
+  ): ValidationResult {
+    if (state.gamePhase !== 'guessing') {
+      return { valid: false, error: 'Not in guessing phase' }
+    }
+
+    if (playerId !== state.currentGuesser) {
+      return { valid: false, error: 'Not your turn to guess' }
+    }
+
+    if (guess < state.minNumber || guess > state.maxNumber || !Number.isInteger(guess)) {
+      return {
+        valid: false,
+        error: `Guess must be between ${state.minNumber} and ${state.maxNumber}`,
+      }
+    }
+
+    if (!state.secretNumber) {
+      return { valid: false, error: 'No secret number set' }
+    }
+
+    // Debug logging
+    console.log('[NumberGuesser] Validating guess:', {
+      guess,
+      guessType: typeof guess,
+      secretNumber: state.secretNumber,
+      secretNumberType: typeof state.secretNumber,
+    })
+
+    const distance = Math.abs(guess - state.secretNumber)
+
+    console.log('[NumberGuesser] Calculated distance:', distance)
+    const newGuess = {
+      playerId,
+      playerName,
+      guess,
+      distance,
+      timestamp: Date.now(),
+    }
+
+    const guesses = [...state.guesses, newGuess]
+
+    // Check if guess is correct
+    if (distance === 0) {
+      // Correct guess! Award point and end round
+      const newScores = {
+        ...state.scores,
+        [playerId]: (state.scores[playerId] || 0) + 1,
+      }
+
+      // Check if player won
+      const winner = newScores[playerId] >= state.roundsToWin ? playerId : null
+
+      const newState: NumberGuesserState = {
+        ...state,
+        guesses,
+        scores: newScores,
+        gamePhase: winner ? 'results' : 'guessing',
+        gameEndTime: winner ? Date.now() : null,
+        winner,
+      }
+
+      return { valid: true, newState }
+    }
+
+    // Incorrect guess, move to next guesser
+    const guesserIndex = state.activePlayers.indexOf(state.currentGuesser)
+    let nextGuesserIndex = (guesserIndex + 1) % state.activePlayers.length
+
+    // Skip the chooser
+    if (state.activePlayers[nextGuesserIndex] === state.chooser) {
+      nextGuesserIndex = (nextGuesserIndex + 1) % state.activePlayers.length
+    }
+
+    const newState: NumberGuesserState = {
+      ...state,
+      guesses,
+      currentGuesser: state.activePlayers[nextGuesserIndex],
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateNextRound(state: NumberGuesserState): ValidationResult {
+    if (state.gamePhase !== 'guessing') {
+      return { valid: false, error: 'Not in guessing phase' }
+    }
+
+    // Check if the round is complete (someone guessed correctly)
+    const roundComplete =
+      state.guesses.length > 0 && state.guesses[state.guesses.length - 1].distance === 0
+
+    if (!roundComplete) {
+      return { valid: false, error: 'Round not complete yet - no one has guessed the number' }
+    }
+
+    // Rotate chooser to next player
+    const chooserIndex = state.activePlayers.indexOf(state.chooser)
+    const nextChooserIndex = (chooserIndex + 1) % state.activePlayers.length
+    const nextChooser = state.activePlayers[nextChooserIndex]
+
+    const newState: NumberGuesserState = {
+      ...state,
+      gamePhase: 'choosing',
+      chooser: nextChooser,
+      currentGuesser: '',
+      secretNumber: null,
+      guesses: [],
+      roundNumber: state.roundNumber + 1,
+      winner: null,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateGoToSetup(state: NumberGuesserState): ValidationResult {
+    const newState: NumberGuesserState = {
+      ...state,
+      gamePhase: 'setup',
+      secretNumber: null,
+      chooser: '',
+      currentGuesser: '',
+      guesses: [],
+      roundNumber: 0,
+      scores: {},
+      activePlayers: [],
+      playerMetadata: {},
+      gameStartTime: null,
+      gameEndTime: null,
+      winner: null,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateSetConfig(
+    state: NumberGuesserState,
+    field: 'minNumber' | 'maxNumber' | 'roundsToWin',
+    value: number
+  ): ValidationResult {
+    if (state.gamePhase !== 'setup') {
+      return { valid: false, error: 'Can only change config in setup' }
+    }
+
+    if (!Number.isInteger(value) || value < 1) {
+      return { valid: false, error: 'Value must be a positive integer' }
+    }
+
+    if (field === 'minNumber' && value >= state.maxNumber) {
+      return { valid: false, error: 'Min must be less than max' }
+    }
+
+    if (field === 'maxNumber' && value <= state.minNumber) {
+      return { valid: false, error: 'Max must be greater than min' }
+    }
+
+    const newState: NumberGuesserState = {
+      ...state,
+      [field]: value,
+    }
+
+    return { valid: true, newState }
+  }
+
+  isGameComplete(state: NumberGuesserState): boolean {
+    return state.gamePhase === 'results' && state.winner !== null
+  }
+
+  getInitialState(config: unknown): NumberGuesserState {
+    const { minNumber, maxNumber, roundsToWin } = config as NumberGuesserConfig
+
+    return {
+      minNumber: minNumber || 1,
+      maxNumber: maxNumber || 100,
+      roundsToWin: roundsToWin || 3,
+      gamePhase: 'setup',
+      activePlayers: [],
+      playerMetadata: {},
+      secretNumber: null,
+      chooser: '',
+      currentGuesser: '',
+      guesses: [],
+      roundNumber: 0,
+      scores: {},
+      gameStartTime: null,
+      gameEndTime: null,
+      winner: null,
+    }
+  }
+}
+
+export const numberGuesserValidator = new NumberGuesserValidator()
--- a/apps/web/src/arcade-games/number-guesser/components/ChoosingPhase.tsx
+++ b/apps/web/src/arcade-games/number-guesser/components/ChoosingPhase.tsx
@@ -0,0 +1,211 @@
+/**
+ * Choosing Phase - Chooser picks a secret number
+ */
+
+'use client'
+
+import { useState } from 'react'
+import { useViewerId } from '@/lib/arcade/game-sdk'
+import { css } from '../../../../styled-system/css'
+import { useNumberGuesser } from '../Provider'
+
+export function ChoosingPhase() {
+  const { state, chooseNumber } = useNumberGuesser()
+  const { data: viewerId } = useViewerId()
+  const [inputValue, setInputValue] = useState('')
+
+  const chooserMetadata = state.playerMetadata[state.chooser]
+  const isChooser = chooserMetadata?.userId === viewerId
+
+  const handleSubmit = () => {
+    const number = Number.parseInt(inputValue, 10)
+    if (Number.isNaN(number)) return
+
+    chooseNumber(number)
+  }
+
+  return (
+    <div
+      className={css({
+        padding: '32px',
+        maxWidth: '600px',
+        margin: '0 auto',
+      })}
+    >
+      <div
+        className={css({
+          textAlign: 'center',
+          marginBottom: '32px',
+        })}
+      >
+        <div
+          className={css({
+            fontSize: '64px',
+            marginBottom: '16px',
+          })}
+        >
+          {chooserMetadata?.emoji || '🤔'}
+        </div>
+        <h2
+          className={css({
+            fontSize: '2xl',
+            fontWeight: 'bold',
+            marginBottom: '8px',
+          })}
+        >
+          {isChooser ? "You're choosing!" : `${chooserMetadata?.name || 'Someone'} is choosing...`}
+        </h2>
+        <p
+          className={css({
+            color: 'gray.600',
+          })}
+        >
+          Round {state.roundNumber}
+        </p>
+      </div>
+
+      {isChooser ? (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: 'orange.200',
+            borderRadius: '12px',
+            padding: '24px',
+          })}
+        >
+          <label
+            className={css({
+              display: 'block',
+              fontSize: 'md',
+              fontWeight: '600',
+              marginBottom: '12px',
+              textAlign: 'center',
+            })}
+          >
+            Choose a secret number ({state.minNumber} - {state.maxNumber})
+          </label>
+          <input
+            type="number"
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+            min={state.minNumber}
+            max={state.maxNumber}
+            placeholder={`${state.minNumber} - ${state.maxNumber}`}
+            className={css({
+              width: '100%',
+              padding: '16px',
+              border: '2px solid',
+              borderColor: 'gray.300',
+              borderRadius: '8px',
+              fontSize: 'xl',
+              textAlign: 'center',
+              marginBottom: '16px',
+            })}
+          />
+          <button
+            onClick={handleSubmit}
+            disabled={!inputValue}
+            className={css({
+              width: '100%',
+              padding: '16px',
+              background: 'linear-gradient(135deg, #fb923c, #f97316)',
+              color: 'white',
+              border: 'none',
+              borderRadius: '8px',
+              fontSize: 'lg',
+              fontWeight: 'bold',
+              cursor: 'pointer',
+              transition: 'all 0.2s',
+              _disabled: {
+                opacity: 0.5,
+                cursor: 'not-allowed',
+              },
+              _hover: {
+                transform: 'translateY(-2px)',
+              },
+            })}
+          >
+            Confirm Choice
+          </button>
+        </div>
+      ) : (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: 'orange.200',
+            borderRadius: '12px',
+            padding: '32px',
+            textAlign: 'center',
+          })}
+        >
+          <div
+            className={css({
+              fontSize: '48px',
+              marginBottom: '16px',
+            })}
+          >
+            ⏳
+          </div>
+          <p
+            className={css({
+              fontSize: 'lg',
+              color: 'gray.600',
+            })}
+          >
+            Waiting for {chooserMetadata?.name || 'player'} to choose a number...
+          </p>
+        </div>
+      )}
+
+      {/* Scoreboard */}
+      <div
+        className={css({
+          marginTop: '32px',
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '16px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'md',
+            fontWeight: 'bold',
+            marginBottom: '12px',
+            textAlign: 'center',
+          })}
+        >
+          Scores
+        </h3>
+        <div
+          className={css({
+            display: 'flex',
+            flexWrap: 'wrap',
+            gap: '8px',
+            justifyContent: 'center',
+          })}
+        >
+          {state.activePlayers.map((playerId) => {
+            const player = state.playerMetadata[playerId]
+            return (
+              <div
+                key={playerId}
+                className={css({
+                  padding: '8px 16px',
+                  background: 'gray.100',
+                  borderRadius: '8px',
+                  fontSize: 'sm',
+                })}
+              >
+                {player?.emoji} {player?.name}: {state.scores[playerId] || 0}
+              </div>
+            )
+          })}
+        </div>
+      </div>
+    </div>
+  )
+}
--- a/apps/web/src/arcade-games/number-guesser/components/GameComponent.tsx
+++ b/apps/web/src/arcade-games/number-guesser/components/GameComponent.tsx
@@ -0,0 +1,60 @@
+/**
+ * Number Guesser Game Component
+ * Main component that switches between game phases
+ */
+
+'use client'
+
+import { useRouter } from 'next/navigation'
+import { PageWithNav } from '@/components/PageWithNav'
+import { useNumberGuesser } from '../Provider'
+import { ChoosingPhase } from './ChoosingPhase'
+import { GuessingPhase } from './GuessingPhase'
+import { ResultsPhase } from './ResultsPhase'
+import { SetupPhase } from './SetupPhase'
+
+export function GameComponent() {
+  const router = useRouter()
+  const { state, exitSession, goToSetup } = useNumberGuesser()
+
+  // Determine whose turn it is based on game phase
+  const currentPlayerId =
+    state.gamePhase === 'choosing'
+      ? state.chooser
+      : state.gamePhase === 'guessing'
+        ? state.currentGuesser
+        : undefined
+
+  return (
+    <PageWithNav
+      navTitle="Number Guesser"
+      navEmoji="🎯"
+      emphasizePlayerSelection={state.gamePhase === 'setup'}
+      currentPlayerId={currentPlayerId}
+      playerScores={state.scores}
+      onExitSession={() => {
+        exitSession?.()
+        router.push('/arcade')
+      }}
+      onNewGame={() => {
+        goToSetup?.()
+      }}
+    >
+      <div
+        style={{
+          flex: 1,
+          display: 'flex',
+          flexDirection: 'column',
+          overflow: 'auto',
+          minHeight: '100vh',
+          background: 'linear-gradient(135deg, #fff7ed, #ffedd5)',
+        }}
+      >
+        {state.gamePhase === 'setup' && <SetupPhase />}
+        {state.gamePhase === 'choosing' && <ChoosingPhase />}
+        {state.gamePhase === 'guessing' && <GuessingPhase />}
+        {state.gamePhase === 'results' && <ResultsPhase />}
+      </div>
+    </PageWithNav>
+  )
+}
--- a/apps/web/src/arcade-games/number-guesser/components/GuessingPhase.tsx
+++ b/apps/web/src/arcade-games/number-guesser/components/GuessingPhase.tsx
@@ -0,0 +1,445 @@
+/**
+ * Guessing Phase - Players take turns guessing the secret number
+ */
+
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useViewerId } from '@/lib/arcade/game-sdk'
+import { css } from '../../../../styled-system/css'
+import { useNumberGuesser } from '../Provider'
+
+export function GuessingPhase() {
+  const { state, makeGuess, nextRound, lastError, clearError } = useNumberGuesser()
+  const { data: viewerId } = useViewerId()
+  const [inputValue, setInputValue] = useState('')
+
+  const currentGuesserMetadata = state.playerMetadata[state.currentGuesser]
+  const isCurrentGuesser = currentGuesserMetadata?.userId === viewerId
+
+  // Check if someone just won the round
+  const lastGuess = state.guesses[state.guesses.length - 1]
+  const roundJustEnded = lastGuess?.distance === 0
+
+  // Auto-clear error after 5 seconds
+  useEffect(() => {
+    if (lastError) {
+      const timeout = setTimeout(() => clearError(), 5000)
+      return () => clearTimeout(timeout)
+    }
+  }, [lastError, clearError])
+
+  const handleSubmit = () => {
+    const guess = Number.parseInt(inputValue, 10)
+    if (Number.isNaN(guess)) return
+
+    makeGuess(guess)
+    setInputValue('')
+  }
+
+  const getHotColdMessage = (distance: number) => {
+    if (distance === 0) return '🎯 Correct!'
+    if (distance <= 5) return '🔥 Very Hot!'
+    if (distance <= 10) return '🌡️ Hot'
+    if (distance <= 20) return '😊 Warm'
+    if (distance <= 30) return '😐 Cool'
+    if (distance <= 50) return '❄️ Cold'
+    return '🧊 Very Cold'
+  }
+
+  return (
+    <div
+      className={css({
+        padding: '32px',
+        maxWidth: '800px',
+        margin: '0 auto',
+      })}
+    >
+      {/* Header */}
+      <div
+        className={css({
+          textAlign: 'center',
+          marginBottom: '32px',
+        })}
+      >
+        <div
+          className={css({
+            fontSize: '64px',
+            marginBottom: '16px',
+          })}
+        >
+          {roundJustEnded ? '🎉' : currentGuesserMetadata?.emoji || '🤔'}
+        </div>
+        <h2
+          className={css({
+            fontSize: '2xl',
+            fontWeight: 'bold',
+            marginBottom: '8px',
+          })}
+        >
+          {roundJustEnded
+            ? `${lastGuess.playerName} guessed it!`
+            : isCurrentGuesser
+              ? 'Your turn to guess!'
+              : `${currentGuesserMetadata?.name || 'Someone'} is guessing...`}
+        </h2>
+        <p
+          className={css({
+            color: 'gray.600',
+          })}
+        >
+          Round {state.roundNumber} • Range: {state.minNumber} - {state.maxNumber}
+        </p>
+      </div>
+
+      {/* Error Banner */}
+      {lastError && (
+        <div
+          className={css({
+            background: 'linear-gradient(135deg, #fef2f2, #fee2e2)',
+            border: '2px solid',
+            borderColor: 'red.300',
+            borderRadius: '12px',
+            padding: '16px 20px',
+            marginBottom: '24px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            animation: 'slideIn 0.3s ease',
+          })}
+        >
+          <div
+            className={css({
+              display: 'flex',
+              alignItems: 'center',
+              gap: '12px',
+            })}
+          >
+            <div
+              className={css({
+                fontSize: '24px',
+              })}
+            >
+              ⚠️
+            </div>
+            <div>
+              <div
+                className={css({
+                  fontSize: 'md',
+                  fontWeight: 'bold',
+                  color: 'red.700',
+                  marginBottom: '4px',
+                })}
+              >
+                Move Rejected
+              </div>
+              <div
+                className={css({
+                  fontSize: 'sm',
+                  color: 'red.600',
+                })}
+              >
+                {lastError}
+              </div>
+            </div>
+          </div>
+          <button
+            type="button"
+            onClick={clearError}
+            className={css({
+              padding: '8px 12px',
+              background: 'white',
+              border: '1px solid',
+              borderColor: 'red.300',
+              borderRadius: '6px',
+              fontSize: 'sm',
+              fontWeight: '600',
+              color: 'red.700',
+              cursor: 'pointer',
+              transition: 'all 0.2s',
+              _hover: {
+                background: 'red.50',
+              },
+            })}
+          >
+            Dismiss
+          </button>
+        </div>
+      )}
+
+      {/* Round ended - show next round button */}
+      {roundJustEnded && (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: 'green.200',
+            borderRadius: '12px',
+            padding: '24px',
+            marginBottom: '24px',
+            textAlign: 'center',
+          })}
+        >
+          <div
+            className={css({
+              fontSize: '48px',
+              marginBottom: '16px',
+            })}
+          >
+            🎯
+          </div>
+          <p
+            className={css({
+              fontSize: 'lg',
+              marginBottom: '16px',
+            })}
+          >
+            The secret number was <strong>{state.secretNumber}</strong>!
+          </p>
+          <button
+            type="button"
+            onClick={nextRound}
+            className={css({
+              padding: '12px 24px',
+              background: 'linear-gradient(135deg, #fb923c, #f97316)',
+              color: 'white',
+              border: 'none',
+              borderRadius: '8px',
+              fontSize: 'md',
+              fontWeight: 'bold',
+              cursor: 'pointer',
+              transition: 'all 0.2s',
+              _hover: {
+                transform: 'translateY(-2px)',
+              },
+            })}
+          >
+            Next Round
+          </button>
+        </div>
+      )}
+
+      {/* Guessing input (only if round not ended) */}
+      {!roundJustEnded && (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: 'orange.200',
+            borderRadius: '12px',
+            padding: '24px',
+            marginBottom: '24px',
+          })}
+        >
+          {isCurrentGuesser ? (
+            <>
+              <label
+                className={css({
+                  display: 'block',
+                  fontSize: 'md',
+                  fontWeight: '600',
+                  marginBottom: '12px',
+                  textAlign: 'center',
+                })}
+              >
+                Make your guess ({state.minNumber} - {state.maxNumber})
+              </label>
+              <input
+                type="number"
+                value={inputValue}
+                onChange={(e) => setInputValue(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' && inputValue) {
+                    handleSubmit()
+                  }
+                }}
+                min={state.minNumber}
+                max={state.maxNumber}
+                placeholder={`${state.minNumber} - ${state.maxNumber}`}
+                className={css({
+                  width: '100%',
+                  padding: '16px',
+                  border: '2px solid',
+                  borderColor: 'gray.300',
+                  borderRadius: '8px',
+                  fontSize: 'xl',
+                  textAlign: 'center',
+                  marginBottom: '16px',
+                })}
+              />
+              <button
+                type="button"
+                onClick={handleSubmit}
+                disabled={!inputValue}
+                className={css({
+                  width: '100%',
+                  padding: '16px',
+                  background: 'linear-gradient(135deg, #fb923c, #f97316)',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: '8px',
+                  fontSize: 'lg',
+                  fontWeight: 'bold',
+                  cursor: 'pointer',
+                  transition: 'all 0.2s',
+                  _disabled: {
+                    opacity: 0.5,
+                    cursor: 'not-allowed',
+                  },
+                  _hover: {
+                    transform: 'translateY(-2px)',
+                  },
+                })}
+              >
+                Submit Guess
+              </button>
+            </>
+          ) : (
+            <div
+              className={css({
+                textAlign: 'center',
+                padding: '16px',
+              })}
+            >
+              <div
+                className={css({
+                  fontSize: '48px',
+                  marginBottom: '16px',
+                })}
+              >
+                ⏳
+              </div>
+              <p
+                className={css({
+                  fontSize: 'lg',
+                  color: 'gray.600',
+                })}
+              >
+                Waiting for {currentGuesserMetadata?.name || 'player'} to guess...
+              </p>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Guess history */}
+      {state.guesses.length > 0 && (
+        <div
+          className={css({
+            background: 'white',
+            border: '1px solid',
+            borderColor: 'gray.200',
+            borderRadius: '12px',
+            padding: '16px',
+            marginBottom: '24px',
+          })}
+        >
+          <h3
+            className={css({
+              fontSize: 'md',
+              fontWeight: 'bold',
+              marginBottom: '12px',
+            })}
+          >
+            Guess History
+          </h3>
+          <div
+            className={css({
+              display: 'flex',
+              flexDirection: 'column',
+              gap: '8px',
+            })}
+          >
+            {state.guesses.map((guess, index) => {
+              const player = state.playerMetadata[guess.playerId]
+              return (
+                <div
+                  key={index}
+                  className={css({
+                    padding: '12px',
+                    background: guess.distance === 0 ? 'green.50' : 'gray.50',
+                    borderRadius: '8px',
+                    display: 'flex',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                  })}
+                >
+                  <div
+                    className={css({
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: '8px',
+                    })}
+                  >
+                    <span>{player?.emoji || '🎮'}</span>
+                    <span className={css({ fontWeight: '600' })}>{guess.playerName}</span>
+                    <span className={css({ color: 'gray.600' })}>guessed</span>
+                    <span className={css({ fontWeight: 'bold', fontSize: 'lg' })}>
+                      {guess.guess}
+                    </span>
+                  </div>
+                  <div
+                    className={css({
+                      fontWeight: 'bold',
+                      color: guess.distance === 0 ? 'green.700' : 'orange.700',
+                    })}
+                  >
+                    {getHotColdMessage(guess.distance)}
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+
+      {/* Scoreboard */}
+      <div
+        className={css({
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '16px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'md',
+            fontWeight: 'bold',
+            marginBottom: '12px',
+            textAlign: 'center',
+          })}
+        >
+          Scores (First to {state.roundsToWin} wins!)
+        </h3>
+        <div
+          className={css({
+            display: 'flex',
+            flexWrap: 'wrap',
+            gap: '8px',
+            justifyContent: 'center',
+          })}
+        >
+          {state.activePlayers.map((playerId) => {
+            const player = state.playerMetadata[playerId]
+            const score = state.scores[playerId] || 0
+            return (
+              <div
+                key={playerId}
+                className={css({
+                  padding: '8px 16px',
+                  background: 'gray.100',
+                  borderRadius: '8px',
+                  fontSize: 'sm',
+                })}
+              >
+                {player?.emoji} {player?.name}: {score}
+              </div>
+            )
+          })}
+        </div>
+      </div>
+    </div>
+  )
+}
--- a/apps/web/src/arcade-games/number-guesser/components/ResultsPhase.tsx
+++ b/apps/web/src/arcade-games/number-guesser/components/ResultsPhase.tsx
@@ -0,0 +1,208 @@
+/**
+ * Results Phase - Shows winner and final scores
+ */
+
+'use client'
+
+import { css } from '../../../../styled-system/css'
+import { useNumberGuesser } from '../Provider'
+
+export function ResultsPhase() {
+  const { state, goToSetup } = useNumberGuesser()
+
+  const winnerMetadata = state.winner ? state.playerMetadata[state.winner] : null
+  const winnerScore = state.winner ? state.scores[state.winner] : 0
+
+  // Sort players by score
+  const sortedPlayers = [...state.activePlayers].sort((a, b) => {
+    const scoreA = state.scores[a] || 0
+    const scoreB = state.scores[b] || 0
+    return scoreB - scoreA
+  })
+
+  return (
+    <div
+      className={css({
+        padding: '32px',
+        maxWidth: '600px',
+        margin: '0 auto',
+      })}
+    >
+      {/* Winner Celebration */}
+      <div
+        className={css({
+          textAlign: 'center',
+          marginBottom: '32px',
+        })}
+      >
+        <div
+          className={css({
+            fontSize: '96px',
+            marginBottom: '16px',
+            animation: 'bounce 1s ease-in-out infinite',
+          })}
+        >
+          {winnerMetadata?.emoji || '🏆'}
+        </div>
+        <h1
+          className={css({
+            fontSize: '3xl',
+            fontWeight: 'bold',
+            marginBottom: '8px',
+            background: 'linear-gradient(135deg, #fb923c, #f97316)',
+            backgroundClip: 'text',
+            color: 'transparent',
+          })}
+        >
+          {winnerMetadata?.name || 'Someone'} Wins!
+        </h1>
+        <p
+          className={css({
+            fontSize: 'xl',
+            color: 'gray.600',
+          })}
+        >
+          with {winnerScore} {winnerScore === 1 ? 'round' : 'rounds'} won
+        </p>
+      </div>
+
+      {/* Final Standings */}
+      <div
+        className={css({
+          background: 'white',
+          border: '2px solid',
+          borderColor: 'orange.200',
+          borderRadius: '12px',
+          padding: '24px',
+          marginBottom: '24px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'lg',
+            fontWeight: 'bold',
+            marginBottom: '16px',
+            textAlign: 'center',
+          })}
+        >
+          Final Standings
+        </h3>
+        <div
+          className={css({
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '12px',
+          })}
+        >
+          {sortedPlayers.map((playerId, index) => {
+            const player = state.playerMetadata[playerId]
+            const score = state.scores[playerId] || 0
+            const isWinner = playerId === state.winner
+
+            return (
+              <div
+                key={playerId}
+                className={css({
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'space-between',
+                  padding: '16px',
+                  background: isWinner ? 'linear-gradient(135deg, #fed7aa, #fdba74)' : 'gray.100',
+                  borderRadius: '8px',
+                  border: isWinner ? '2px solid' : 'none',
+                  borderColor: isWinner ? 'orange.300' : undefined,
+                })}
+              >
+                <div
+                  className={css({
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: '12px',
+                  })}
+                >
+                  <span
+                    className={css({
+                      fontSize: '2xl',
+                      fontWeight: 'bold',
+                      color: 'gray.400',
+                      width: '32px',
+                      textAlign: 'center',
+                    })}
+                  >
+                    {index + 1}
+                  </span>
+                  <span className={css({ fontSize: '32px' })}>{player?.emoji || '🎮'}</span>
+                  <span className={css({ fontSize: 'lg', fontWeight: '600' })}>
+                    {player?.name || 'Unknown'}
+                  </span>
+                </div>
+                <div
+                  className={css({
+                    fontSize: '2xl',
+                    fontWeight: 'bold',
+                    color: isWinner ? 'orange.700' : 'gray.700',
+                  })}
+                >
+                  {score} {isWinner && '🏆'}
+                </div>
+              </div>
+            )
+          })}
+        </div>
+      </div>
+
+      {/* Game Stats */}
+      <div
+        className={css({
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '16px',
+          marginBottom: '24px',
+          textAlign: 'center',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'md',
+            fontWeight: 'bold',
+            marginBottom: '8px',
+          })}
+        >
+          Game Stats
+        </h3>
+        <p className={css({ color: 'gray.600', fontSize: 'sm' })}>
+          {state.roundNumber} {state.roundNumber === 1 ? 'round' : 'rounds'} played
+        </p>
+        <p className={css({ color: 'gray.600', fontSize: 'sm' })}>
+          {state.guesses.length} {state.guesses.length === 1 ? 'guess' : 'guesses'} made
+        </p>
+      </div>
+
+      {/* Actions */}
+      <button
+        type="button"
+        onClick={goToSetup}
+        className={css({
+          width: '100%',
+          padding: '16px',
+          background: 'linear-gradient(135deg, #fb923c, #f97316)',
+          color: 'white',
+          border: 'none',
+          borderRadius: '12px',
+          fontSize: 'lg',
+          fontWeight: 'bold',
+          cursor: 'pointer',
+          transition: 'all 0.2s',
+          _hover: {
+            transform: 'translateY(-2px)',
+            boxShadow: '0 8px 16px rgba(249, 115, 22, 0.3)',
+          },
+        })}
+      >
+        Play Again
+      </button>
+    </div>
+  )
+}
--- a/apps/web/src/arcade-games/number-guesser/components/SetupPhase.tsx
+++ b/apps/web/src/arcade-games/number-guesser/components/SetupPhase.tsx
@@ -0,0 +1,197 @@
+/**
+ * Setup Phase - Game configuration
+ */
+
+'use client'
+
+import { css } from '../../../../styled-system/css'
+import { useNumberGuesser } from '../Provider'
+
+export function SetupPhase() {
+  const { state, startGame, setConfig } = useNumberGuesser()
+
+  return (
+    <div
+      className={css({
+        padding: '32px',
+        maxWidth: '600px',
+        margin: '0 auto',
+      })}
+    >
+      <h2
+        className={css({
+          fontSize: '2xl',
+          fontWeight: 'bold',
+          marginBottom: '24px',
+          textAlign: 'center',
+        })}
+      >
+        🎯 Number Guesser Setup
+      </h2>
+
+      <div
+        className={css({
+          background: 'white',
+          border: '2px solid',
+          borderColor: 'orange.200',
+          borderRadius: '12px',
+          padding: '24px',
+          marginBottom: '24px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'lg',
+            fontWeight: 'bold',
+            marginBottom: '16px',
+          })}
+        >
+          Game Rules
+        </h3>
+        <ul
+          className={css({
+            listStyle: 'disc',
+            paddingLeft: '24px',
+            lineHeight: '1.6',
+            color: 'gray.700',
+          })}
+        >
+          <li>One player chooses a secret number</li>
+          <li>Other players take turns guessing</li>
+          <li>Get feedback on how close your guess is</li>
+          <li>First to guess correctly wins the round!</li>
+          <li>First to {state.roundsToWin} rounds wins the game!</li>
+        </ul>
+      </div>
+
+      <div
+        className={css({
+          background: 'white',
+          border: '2px solid',
+          borderColor: 'orange.200',
+          borderRadius: '12px',
+          padding: '24px',
+          marginBottom: '24px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'lg',
+            fontWeight: 'bold',
+            marginBottom: '16px',
+          })}
+        >
+          Configuration
+        </h3>
+
+        <div
+          className={css({
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '16px',
+          })}
+        >
+          <div>
+            <label
+              className={css({
+                display: 'block',
+                fontSize: 'sm',
+                fontWeight: '600',
+                marginBottom: '4px',
+              })}
+            >
+              Minimum Number
+            </label>
+            <input
+              type="number"
+              value={state.minNumber ?? 1}
+              onChange={(e) => setConfig('minNumber', Number.parseInt(e.target.value, 10))}
+              className={css({
+                width: '100%',
+                padding: '8px 12px',
+                border: '1px solid',
+                borderColor: 'gray.300',
+                borderRadius: '6px',
+                fontSize: 'md',
+              })}
+            />
+          </div>
+
+          <div>
+            <label
+              className={css({
+                display: 'block',
+                fontSize: 'sm',
+                fontWeight: '600',
+                marginBottom: '4px',
+              })}
+            >
+              Maximum Number
+            </label>
+            <input
+              type="number"
+              value={state.maxNumber ?? 100}
+              onChange={(e) => setConfig('maxNumber', Number.parseInt(e.target.value, 10))}
+              className={css({
+                width: '100%',
+                padding: '8px 12px',
+                border: '1px solid',
+                borderColor: 'gray.300',
+                borderRadius: '6px',
+                fontSize: 'md',
+              })}
+            />
+          </div>
+
+          <div>
+            <label
+              className={css({
+                display: 'block',
+                fontSize: 'sm',
+                fontWeight: '600',
+                marginBottom: '4px',
+              })}
+            >
+              Rounds to Win
+            </label>
+            <input
+              type="number"
+              value={state.roundsToWin ?? 3}
+              onChange={(e) => setConfig('roundsToWin', Number.parseInt(e.target.value, 10))}
+              className={css({
+                width: '100%',
+                padding: '8px 12px',
+                border: '1px solid',
+                borderColor: 'gray.300',
+                borderRadius: '6px',
+                fontSize: 'md',
+              })}
+            />
+          </div>
+        </div>
+      </div>
+
+      <button
+        onClick={startGame}
+        className={css({
+          width: '100%',
+          padding: '16px',
+          background: 'linear-gradient(135deg, #fb923c, #f97316)',
+          color: 'white',
+          border: 'none',
+          borderRadius: '12px',
+          fontSize: 'lg',
+          fontWeight: 'bold',
+          cursor: 'pointer',
+          transition: 'all 0.2s',
+          _hover: {
+            transform: 'translateY(-2px)',
+            boxShadow: '0 8px 16px rgba(249, 115, 22, 0.3)',
+          },
+        })}
+      >
+        Start Game
+      </button>
+    </div>
+  )
+}
--- a/apps/web/src/arcade-games/number-guesser/game.yaml
+++ b/apps/web/src/arcade-games/number-guesser/game.yaml
@@ -0,0 +1,15 @@
+name: number-guesser
+displayName: Number Guesser
+icon: 🎯
+description: Classic turn-based number guessing game
+longDescription: One player thinks of a number, others take turns guessing. Get hot/cold feedback as you try to find the secret number. Perfect for testing your deduction skills!
+maxPlayers: 4
+difficulty: Beginner
+chips:
+  - 👥 Multiplayer
+  - 🎲 Turn-Based
+  - 🧠 Logic Puzzle
+color: orange
+gradient: linear-gradient(135deg, #fed7aa, #fdba74)
+borderColor: orange.200
+available: true
--- a/apps/web/src/arcade-games/number-guesser/index.ts
+++ b/apps/web/src/arcade-games/number-guesser/index.ts
@@ -0,0 +1,48 @@
+/**
+ * Number Guesser Game Definition
+ * Exports the complete game using the Arcade SDK
+ */
+
+import { defineGame } from '@/lib/arcade/game-sdk'
+import type { GameManifest } from '@/lib/arcade/game-sdk'
+import { GameComponent } from './components/GameComponent'
+import { NumberGuesserProvider } from './Provider'
+import type { NumberGuesserConfig, NumberGuesserMove, NumberGuesserState } from './types'
+import { numberGuesserValidator } from './Validator'
+
+// Game manifest (matches game.yaml)
+const manifest: GameManifest = {
+  name: 'number-guesser',
+  displayName: 'Number Guesser',
+  icon: '🎯',
+  description: 'Classic turn-based number guessing game',
+  longDescription:
+    'One player thinks of a number, others take turns guessing. Get hot/cold feedback to narrow down your guesses. First to guess wins the round!',
+  maxPlayers: 4,
+  difficulty: 'Beginner',
+  chips: ['👥 Multiplayer', '🎲 Turn-Based', '🧠 Logic Puzzle'],
+  color: 'orange',
+  gradient: 'linear-gradient(135deg, #fed7aa, #fdba74)',
+  borderColor: 'orange.200',
+  available: true,
+}
+
+// Default configuration
+const defaultConfig: NumberGuesserConfig = {
+  minNumber: 1,
+  maxNumber: 100,
+  roundsToWin: 3,
+}
+
+// Export game definition
+export const numberGuesserGame = defineGame<
+  NumberGuesserConfig,
+  NumberGuesserState,
+  NumberGuesserMove
+>({
+  manifest,
+  Provider: NumberGuesserProvider,
+  GameComponent,
+  validator: numberGuesserValidator,
+  defaultConfig,
+})
--- a/apps/web/src/arcade-games/number-guesser/types.ts
+++ b/apps/web/src/arcade-games/number-guesser/types.ts
@@ -0,0 +1,116 @@
+/**
+ * Type definitions for Number Guesser game
+ */
+
+import type { GameMove } from '@/lib/arcade/game-sdk'
+
+/**
+ * Game configuration
+ */
+export type NumberGuesserConfig = {
+  minNumber: number
+  maxNumber: number
+  roundsToWin: number
+}
+
+/**
+ * A single guess attempt
+ */
+export interface Guess {
+  playerId: string
+  playerName: string
+  guess: number
+  distance: number // How far from the secret number
+  timestamp: number
+}
+
+/**
+ * Game phases
+ */
+export type GamePhase = 'setup' | 'choosing' | 'guessing' | 'results'
+
+/**
+ * Game state
+ */
+export type NumberGuesserState = {
+  // Configuration
+  minNumber: number
+  maxNumber: number
+  roundsToWin: number
+
+  // Game phase
+  gamePhase: GamePhase
+
+  // Players
+  activePlayers: string[]
+  playerMetadata: Record<string, { name: string; emoji: string; color: string; userId: string }>
+
+  // Current round
+  secretNumber: number | null
+  chooser: string // Player ID who chose the number
+  currentGuesser: string // Player ID whose turn it is to guess
+
+  // Round history
+  guesses: Guess[]
+  roundNumber: number
+
+  // Scores
+  scores: Record<string, number>
+
+  // Game state
+  gameStartTime: number | null
+  gameEndTime: number | null
+  winner: string | null
+}
+
+/**
+ * Game moves
+ */
+export interface StartGameMove extends GameMove {
+  type: 'START_GAME'
+  data: {
+    activePlayers: string[]
+    playerMetadata: Record<string, unknown>
+  }
+}
+
+export interface ChooseNumberMove extends GameMove {
+  type: 'CHOOSE_NUMBER'
+  data: {
+    secretNumber: number
+  }
+}
+
+export interface MakeGuessMove extends GameMove {
+  type: 'MAKE_GUESS'
+  data: {
+    guess: number
+    playerName: string
+  }
+}
+
+export interface NextRoundMove extends GameMove {
+  type: 'NEXT_ROUND'
+  data: Record<string, never>
+}
+
+export interface GoToSetupMove extends GameMove {
+  type: 'GO_TO_SETUP'
+  data: Record<string, never>
+}
+
+export interface SetConfigMove extends GameMove {
+  type: 'SET_CONFIG'
+  data: {
+    field: 'minNumber' | 'maxNumber' | 'roundsToWin'
+    value: number
+  }
+}
+
+export type NumberGuesserMove =
+  | StartGameMove
+  | ChooseNumberMove
+  | MakeGuessMove
+  | NextRoundMove
+  | GoToSetupMove
+  | SetConfigMove
--- a/apps/web/src/components/GameSelector.tsx
+++ b/apps/web/src/components/GameSelector.tsx
@@ -1,7 +1,9 @@
 'use client'

+import { useMemo } from 'react'
 import { css } from '../../styled-system/css'
 import { useGameMode } from '../contexts/GameModeContext'
+import { getAllGames } from '../lib/arcade/game-registry'
 import { GameCard } from './GameCard'

 // Game configuration defining player limits
@@ -70,7 +72,39 @@ export const GAMES_CONFIG = {
  },
 } as const

-export type GameType = keyof typeof GAMES_CONFIG
+export type GameType = keyof typeof GAMES_CONFIG | string
+
+/**
+ * Get all games from both legacy config and new registry
+ */
+function getAllGameConfigs() {
+  const legacyGames = Object.entries(GAMES_CONFIG).map(([gameType, config]) => ({
+    gameType,
+    config,
+  }))
+
+  // Get games from registry and transform to legacy format
+  const registryGames = getAllGames().map((gameDef) => ({
+    gameType: gameDef.manifest.name,
+    config: {
+      name: gameDef.manifest.displayName,
+      fullName: gameDef.manifest.displayName,
+      maxPlayers: gameDef.manifest.maxPlayers,
+      description: gameDef.manifest.description,
+      longDescription: gameDef.manifest.longDescription,
+      url: `/arcade/room?game=${gameDef.manifest.name}`, // Registry games load in room
+      icon: gameDef.manifest.icon,
+      chips: gameDef.manifest.chips,
+      color: gameDef.manifest.color,
+      gradient: gameDef.manifest.gradient,
+      borderColor: gameDef.manifest.borderColor,
+      difficulty: gameDef.manifest.difficulty,
+      available: gameDef.manifest.available,
+    },
+  }))
+
+  return [...legacyGames, ...registryGames]
+}

 interface GameSelectorProps {
  variant?: 'compact' | 'detailed'
@@ -87,17 +121,17 @@ export function GameSelector({
 }: GameSelectorProps) {
  const { activePlayerCount } = useGameMode()

+  // Memoize the combined games list
+  const allGames = useMemo(() => getAllGameConfigs(), [])
+
  return (
    <div
-      className={css(
-        {
-          height: '100%',
-          display: 'flex',
-          flexDirection: 'column',
-          overflow: 'hidden',
-        },
-        className
-      )}
+      className={`${css({
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        overflow: 'hidden',
+      })} ${className || ''}`}
    >
      {showHeader && (
        <h3
@@ -125,7 +159,7 @@ export function GameSelector({
          overflow: 'hidden',
        })}
      >
-        {Object.entries(GAMES_CONFIG).map(([gameType, config]) => (
+        {allGames.map(({ gameType, config }) => (
          <GameCard
            key={gameType}
            gameType={gameType as GameType}
--- a/apps/web/src/components/nav/AddPlayerButton.tsx
+++ b/apps/web/src/components/nav/AddPlayerButton.tsx
@@ -26,7 +26,7 @@ interface AddPlayerButtonProps {
  // Context-aware: show different content based on room state
  isInRoom?: boolean
  // Game info for room creation
-  gameName?: 'matching' | 'memory-quiz' | 'complement-race'
+  gameName?: string | null
 }

 export function AddPlayerButton({
@@ -38,7 +38,7 @@ export function AddPlayerButton({
  activeTab: activeTabProp,
  setActiveTab: setActiveTabProp,
  isInRoom = false,
-  gameName = 'Arcade',
+  gameName = null,
 }: AddPlayerButtonProps) {
  const popoverRef = React.useRef<HTMLDivElement>(null)
  const router = useRouter()
--- a/apps/web/src/components/nav/GameContextNav.tsx
+++ b/apps/web/src/components/nav/GameContextNav.tsx
@@ -28,7 +28,7 @@ interface NetworkPlayer {
 interface ArcadeRoomInfo {
  roomId?: string
  roomName?: string
-  gameName: string
+  gameName: string | null
  playerCount: number
  joinCode?: string
 }
@@ -200,6 +200,7 @@ export function GameContextNav({
            onSetup={onSetup}
            onNewGame={onNewGame}
            onQuit={onExitSession}
+            showMenu={true}
          />
          <div style={{ marginLeft: 'auto' }}>
            <GameModeIndicator
@@ -287,7 +288,7 @@ export function GameContextNav({
                  playerScores={playerScores}
                  playerStreaks={playerStreaks}
                  roomId={roomInfo?.roomId}
-                  currentUserId={currentUserId}
+                  currentUserId={currentUserId ?? undefined}
                  isCurrentUserHost={isCurrentUserHost}
                />
              ))}
--- a/apps/web/src/components/nav/JoinRoomModal.tsx
+++ b/apps/web/src/components/nav/JoinRoomModal.tsx
@@ -2,7 +2,7 @@ import { useEffect, useState } from 'react'
 import { io } from 'socket.io-client'
 import { Modal } from '@/components/common/Modal'
 import type { schema } from '@/db'
-import { useRoomData } from '@/hooks/useRoomData'
+import { useGetRoomByCode, useJoinRoom } from '@/hooks/useRoomData'

 export interface JoinRoomModalProps {
  /**
@@ -25,7 +25,8 @@ export interface JoinRoomModalProps {
 * Modal for joining a room by entering a 6-character code
 */
 export function JoinRoomModal({ isOpen, onClose, onSuccess }: JoinRoomModalProps) {
-  const { getRoomByCode, joinRoom } = useRoomData()
+  const { mutateAsync: getRoomByCode } = useGetRoomByCode()
+  const { mutate: joinRoom } = useJoinRoom()
  const [code, setCode] = useState('')
  const [password, setPassword] = useState('')
  const [error, setError] = useState('')
--- a/apps/web/src/components/nav/RecentRoomsList.tsx
+++ b/apps/web/src/components/nav/RecentRoomsList.tsx
@@ -4,7 +4,7 @@ import { getRoomDisplayWithEmoji } from '@/utils/room-display'
 interface RecentRoom {
  code: string
  name: string | null
-  gameName: string
+  gameName: string | null
  joinedAt: number
 }

@@ -105,7 +105,7 @@ export function RecentRoomsList({ onSelectRoom }: RecentRoomsListProps) {
                {getRoomDisplayWithEmoji({
                  name: room.name,
                  code: room.code,
-                  gameName: room.gameName,
+                  gameName: room.gameName ?? undefined,
                })}
              </span>
            </div>
@@ -133,7 +133,7 @@ export function RecentRoomsList({ onSelectRoom }: RecentRoomsListProps) {
 export function addToRecentRooms(room: {
  code: string
  name: string | null
-  gameName: string
+  gameName: string | null
 }): void {
  try {
    const stored = localStorage.getItem(STORAGE_KEY)
--- a/apps/web/src/db/schema/arcade-rooms.ts
+++ b/apps/web/src/db/schema/arcade-rooms.ts
@@ -34,7 +34,7 @@ export const arcadeRooms = sqliteTable('arcade_rooms', {

  // Game configuration (nullable to support game selection in room)
  gameName: text('game_name', {
-    enum: ['matching', 'memory-quiz', 'complement-race'],
+    enum: ['matching', 'memory-quiz', 'complement-race', 'number-guesser'],
  }),
  gameConfig: text('game_config', { mode: 'json' }), // Game-specific settings (nullable when no game selected)

--- a/apps/web/src/db/schema/arcade-sessions.ts
+++ b/apps/web/src/db/schema/arcade-sessions.ts
@@ -17,7 +17,7 @@ export const arcadeSessions = sqliteTable('arcade_sessions', {

  // Session metadata
  currentGame: text('current_game', {
-    enum: ['matching', 'memory-quiz', 'complement-race'],
+    enum: ['matching', 'memory-quiz', 'complement-race', 'number-guesser'],
  }).notNull(),

  gameUrl: text('game_url').notNull(), // e.g., '/arcade/matching'
--- a/apps/web/src/db/schema/room-game-configs.ts
+++ b/apps/web/src/db/schema/room-game-configs.ts
@@ -20,7 +20,7 @@ export const roomGameConfigs = sqliteTable(

    // Game identifier
    gameName: text('game_name', {
-      enum: ['matching', 'memory-quiz', 'complement-race'],
+      enum: ['matching', 'memory-quiz', 'complement-race', 'number-guesser'],
    }).notNull(),

    // Game-specific configuration JSON
--- a/apps/web/src/hooks/useArcadeSession.ts
+++ b/apps/web/src/hooks/useArcadeSession.ts
@@ -46,6 +46,11 @@ export interface UseArcadeSessionReturn<TState> {
   */
  hasPendingMoves: boolean

+  /**
+   * Last error from server (move rejection)
+   */
+  lastError: string | null
+
  /**
   * Send a game move (applies optimistically and sends to server)
   * Note: playerId must be provided by caller (not omitted)
@@ -57,6 +62,11 @@ export interface UseArcadeSessionReturn<TState> {
   */
  exitSession: () => void

+  /**
+   * Clear the last error
+   */
+  clearError: () => void
+
  /**
   * Manually sync with server (useful after reconnect)
   */
@@ -172,8 +182,10 @@ export function useArcadeSession<TState>(
    version: optimistic.version,
    connected,
    hasPendingMoves: optimistic.hasPendingMoves,
+    lastError: optimistic.lastError,
    sendMove,
    exitSession,
+    clearError: optimistic.clearError,
    refresh,
  }
 }
--- a/apps/web/src/hooks/useOptimisticGameState.ts
+++ b/apps/web/src/hooks/useOptimisticGameState.ts
@@ -46,6 +46,11 @@ export interface UseOptimisticGameStateReturn<TState> {
   */
  hasPendingMoves: boolean

+  /**
+   * Last error from server (move rejection)
+   */
+  lastError: string | null
+
  /**
   * Apply a move optimistically and send to server
   */
@@ -66,6 +71,11 @@ export interface UseOptimisticGameStateReturn<TState> {
   */
  syncWithServer: (serverState: TState, serverVersion: number) => void

+  /**
+   * Clear the last error
+   */
+  clearError: () => void
+
  /**
   * Reset to initial state
   */
@@ -94,6 +104,9 @@ export function useOptimisticGameState<TState>(
  // Pending moves that haven't been confirmed by server yet
  const [pendingMoves, setPendingMoves] = useState<PendingMove<TState>[]>([])

+  // Last error from move rejection
+  const [lastError, setLastError] = useState<string | null>(null)
+
  // Ref for callbacks to avoid stale closures
  const callbacksRef = useRef({ onMoveAccepted, onMoveRejected })
  useEffect(() => {
@@ -152,6 +165,9 @@ export function useOptimisticGameState<TState>(
  )

  const handleMoveRejected = useCallback((error: string, rejectedMove: GameMove) => {
+    // Set the error for UI display
+    setLastError(error)
+
    // Remove the rejected move and all subsequent moves from pending queue
    setPendingMoves((prev) => {
      const index = prev.findIndex(
@@ -176,20 +192,27 @@ export function useOptimisticGameState<TState>(
    setPendingMoves([])
  }, [])

+  const clearError = useCallback(() => {
+    setLastError(null)
+  }, [])
+
  const reset = useCallback(() => {
    setServerState(initialState)
    setServerVersion(1)
    setPendingMoves([])
+    setLastError(null)
  }, [initialState])

  return {
    state: currentState,
    version: serverVersion,
    hasPendingMoves: pendingMoves.length > 0,
+    lastError,
    applyOptimisticMove,
    handleMoveAccepted,
    handleMoveRejected,
    syncWithServer,
+    clearError,
    reset,
  }
 }
--- a/apps/web/src/lib/arcade/game-config-helpers.ts
+++ b/apps/web/src/lib/arcade/game-config-helpers.ts
@@ -8,18 +8,25 @@
 import { and, eq } from 'drizzle-orm'
 import { createId } from '@paralleldrive/cuid2'
 import { db, schema } from '@/db'
-import type { GameName } from './validation'
+import type { GameName } from './validators'
 import type { GameConfigByName } from './game-configs'
 import {
  DEFAULT_MATCHING_CONFIG,
  DEFAULT_MEMORY_QUIZ_CONFIG,
  DEFAULT_COMPLEMENT_RACE_CONFIG,
+  DEFAULT_NUMBER_GUESSER_CONFIG,
 } from './game-configs'

+/**
+ * Extended game name type that includes both registered validators and legacy games
+ * TODO: Remove 'complement-race' once migrated to the new modular system
+ */
+type ExtendedGameName = GameName | 'complement-race'
+
 /**
 * Get default config for a game
 */
-function getDefaultGameConfig(gameName: GameName): GameConfigByName[GameName] {
+function getDefaultGameConfig(gameName: ExtendedGameName): GameConfigByName[ExtendedGameName] {
  switch (gameName) {
    case 'matching':
      return DEFAULT_MATCHING_CONFIG
@@ -27,6 +34,8 @@ function getDefaultGameConfig(gameName: GameName): GameConfigByName[GameName] {
      return DEFAULT_MEMORY_QUIZ_CONFIG
    case 'complement-race':
      return DEFAULT_COMPLEMENT_RACE_CONFIG
+    case 'number-guesser':
+      return DEFAULT_NUMBER_GUESSER_CONFIG
    default:
      throw new Error(`Unknown game: ${gameName}`)
  }
@@ -36,7 +45,7 @@ function getDefaultGameConfig(gameName: GameName): GameConfigByName[GameName] {
 * Get game-specific config from database with defaults
 * Type-safe: returns the correct config type based on gameName
 */
-export async function getGameConfig<T extends GameName>(
+export async function getGameConfig<T extends ExtendedGameName>(
  roomId: string,
  gameName: T
 ): Promise<GameConfigByName[T]> {
@@ -62,7 +71,7 @@ export async function getGameConfig<T extends GameName>(
 * Set (upsert) a game's config in the database
 * Creates a new row if it doesn't exist, updates if it does
 */
-export async function setGameConfig<T extends GameName>(
+export async function setGameConfig<T extends ExtendedGameName>(
  roomId: string,
  gameName: T,
  config: Partial<GameConfigByName[T]>
@@ -110,7 +119,7 @@ export async function setGameConfig<T extends GameName>(
 * Convenience wrapper around setGameConfig
 */
 export async function updateGameConfigField<
-  T extends GameName,
+  T extends ExtendedGameName,
  K extends keyof GameConfigByName[T],
 >(roomId: string, gameName: T, field: K, value: GameConfigByName[T][K]): Promise<void> {
  // Create a partial config with just the field being updated
@@ -123,7 +132,7 @@ export async function updateGameConfigField<
 * Delete a game's config from the database
 * Useful when clearing game selection or cleaning up
 */
-export async function deleteGameConfig(roomId: string, gameName: GameName): Promise<void> {
+export async function deleteGameConfig(roomId: string, gameName: ExtendedGameName): Promise<void> {
  await db
    .delete(schema.roomGameConfigs)
    .where(
@@ -139,14 +148,14 @@ export async function deleteGameConfig(roomId: string, gameName: GameName): Prom
 */
 export async function getAllGameConfigs(
  roomId: string
-): Promise<Partial<Record<GameName, unknown>>> {
+): Promise<Partial<Record<ExtendedGameName, unknown>>> {
  const configs = await db.query.roomGameConfigs.findMany({
    where: eq(schema.roomGameConfigs.roomId, roomId),
  })

-  const result: Partial<Record<GameName, unknown>> = {}
+  const result: Partial<Record<ExtendedGameName, unknown>> = {}
  for (const config of configs) {
-    result[config.gameName as GameName] = config.config
+    result[config.gameName as ExtendedGameName] = config.config
  }

  return result
@@ -165,7 +174,7 @@ export async function deleteAllGameConfigs(roomId: string): Promise<void> {
 * Validate a game config at runtime
 * Returns true if the config is valid for the given game
 */
-export function validateGameConfig(gameName: GameName, config: any): boolean {
+export function validateGameConfig(gameName: ExtendedGameName, config: any): boolean {
  switch (gameName) {
    case 'matching':
      return (
@@ -194,6 +203,18 @@ export function validateGameConfig(gameName: GameName, config: any): boolean {
      // TODO: Add validation when complement-race settings are defined
      return typeof config === 'object' && config !== null

+    case 'number-guesser':
+      return (
+        typeof config === 'object' &&
+        config !== null &&
+        typeof config.minNumber === 'number' &&
+        typeof config.maxNumber === 'number' &&
+        typeof config.roundsToWin === 'number' &&
+        config.minNumber >= 1 &&
+        config.maxNumber > config.minNumber &&
+        config.roundsToWin >= 1
+      )
+
    default:
      return false
  }
--- a/apps/web/src/lib/arcade/game-configs.ts
+++ b/apps/web/src/lib/arcade/game-configs.ts
@@ -40,6 +40,15 @@ export interface ComplementRaceGameConfig {
  placeholder?: never
 }

+/**
+ * Configuration for number-guesser game
+ */
+export interface NumberGuesserGameConfig {
+  minNumber: number
+  maxNumber: number
+  roundsToWin: number
+}
+
 /**
 * Union type of all game configs for type-safe access
 */
@@ -47,6 +56,7 @@ export type GameConfigByName = {
  matching: MatchingGameConfig
  'memory-quiz': MemoryQuizGameConfig
  'complement-race': ComplementRaceGameConfig
+  'number-guesser': NumberGuesserGameConfig
 }

 /**
@@ -57,6 +67,7 @@ export interface RoomGameConfig {
  matching?: MatchingGameConfig
  'memory-quiz'?: MemoryQuizGameConfig
  'complement-race'?: ComplementRaceGameConfig
+  'number-guesser'?: NumberGuesserGameConfig
 }

 /**
@@ -78,3 +89,9 @@ export const DEFAULT_MEMORY_QUIZ_CONFIG: MemoryQuizGameConfig = {
 export const DEFAULT_COMPLEMENT_RACE_CONFIG: ComplementRaceGameConfig = {
  // Future defaults will go here
 }
+
+export const DEFAULT_NUMBER_GUESSER_CONFIG: NumberGuesserGameConfig = {
+  minNumber: 1,
+  maxNumber: 100,
+  roundsToWin: 3,
+}
--- a/apps/web/src/lib/arcade/game-registry.ts
+++ b/apps/web/src/lib/arcade/game-registry.ts
@@ -0,0 +1,111 @@
+/**
+ * Game Registry
+ *
+ * Central registry for all arcade games.
+ * Games are explicitly registered here after being defined.
+ */
+
+import type { GameConfig, GameDefinition, GameMove, GameState } from './game-sdk/types'
+
+/**
+ * Global game registry
+ * Maps game name to game definition
+ * Using `any` for generics to allow different game types
+ */
+const registry = new Map<string, GameDefinition<any, any, any>>()
+
+/**
+ * Register a game in the registry
+ *
+ * @param game - Game definition to register
+ * @throws Error if game with same name already registered
+ */
+export function registerGame<
+  TConfig extends GameConfig,
+  TState extends GameState,
+  TMove extends GameMove,
+>(game: GameDefinition<TConfig, TState, TMove>): void {
+  const { name } = game.manifest
+
+  if (registry.has(name)) {
+    throw new Error(`Game "${name}" is already registered`)
+  }
+
+  // Verify validator is also registered server-side
+  try {
+    const { hasValidator, getValidator } = require('./validators')
+    if (!hasValidator(name)) {
+      console.error(
+        `⚠️  Game "${name}" registered but validator not found in server registry!` +
+          `\n   Add to src/lib/arcade/validators.ts to enable multiplayer.`
+      )
+    } else {
+      const serverValidator = getValidator(name)
+      if (serverValidator !== game.validator) {
+        console.warn(
+          `⚠️  Game "${name}" has different validator instances (client vs server).` +
+            `\n   This may cause issues. Ensure both use the same import.`
+        )
+      }
+    }
+  } catch (error) {
+    // If validators.ts can't be imported (e.g., in browser), skip check
+    // This is expected - validator registry is isomorphic but check only runs server-side
+  }
+
+  registry.set(name, game)
+  console.log(`✅ Registered game: ${name}`)
+}
+
+/**
+ * Get a game from the registry
+ *
+ * @param gameName - Internal game identifier
+ * @returns Game definition or undefined if not found
+ */
+export function getGame(gameName: string): GameDefinition<any, any, any> | undefined {
+  return registry.get(gameName)
+}
+
+/**
+ * Get all registered games
+ *
+ * @returns Array of all game definitions
+ */
+export function getAllGames(): GameDefinition<any, any, any>[] {
+  return Array.from(registry.values())
+}
+
+/**
+ * Get all available games (where available: true)
+ *
+ * @returns Array of available game definitions
+ */
+export function getAvailableGames(): GameDefinition<any, any, any>[] {
+  return getAllGames().filter((game) => game.manifest.available)
+}
+
+/**
+ * Check if a game is registered
+ *
+ * @param gameName - Internal game identifier
+ * @returns true if game is registered
+ */
+export function hasGame(gameName: string): boolean {
+  return registry.has(gameName)
+}
+
+/**
+ * Clear all games from registry (used for testing)
+ */
+export function clearRegistry(): void {
+  registry.clear()
+}
+
+// ============================================================================
+// Game Registrations
+// ============================================================================
+
+import { numberGuesserGame } from '@/arcade-games/number-guesser'
+
+registerGame(numberGuesserGame)
--- a/apps/web/src/lib/arcade/game-sdk/GameErrorBoundary.tsx
+++ b/apps/web/src/lib/arcade/game-sdk/GameErrorBoundary.tsx
@@ -0,0 +1,124 @@
+/**
+ * Error Boundary for Arcade Games
+ *
+ * Catches errors in game components and displays a friendly error message
+ * instead of crashing the entire app.
+ */
+
+'use client'
+
+import { Component, type ReactNode } from 'react'
+
+interface Props {
+  children: ReactNode
+  gameName?: string
+}
+
+interface State {
+  hasError: boolean
+  error?: Error
+}
+
+export class GameErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return {
+      hasError: true,
+      error,
+    }
+  }
+
+  componentDidCatch(error: Error, errorInfo: unknown) {
+    console.error('Game error:', error, errorInfo)
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            padding: '40px',
+            textAlign: 'center',
+            minHeight: '400px',
+            background: 'linear-gradient(135deg, #fef2f2, #fee2e2)',
+          }}
+        >
+          <div
+            style={{
+              fontSize: '64px',
+              marginBottom: '20px',
+            }}
+          >
+            ⚠️
+          </div>
+          <h2
+            style={{
+              fontSize: '24px',
+              fontWeight: 'bold',
+              marginBottom: '12px',
+              color: '#dc2626',
+            }}
+          >
+            Game Error
+          </h2>
+          <p
+            style={{
+              fontSize: '16px',
+              color: '#6b7280',
+              marginBottom: '12px',
+              maxWidth: '500px',
+            }}
+          >
+            {this.props.gameName
+              ? `There was an error loading the game "${this.props.gameName}".`
+              : 'There was an error loading the game.'}
+          </p>
+          {this.state.error && (
+            <pre
+              style={{
+                background: '#f9fafb',
+                border: '1px solid #e5e7eb',
+                borderRadius: '8px',
+                padding: '16px',
+                marginTop: '12px',
+                maxWidth: '600px',
+                overflow: 'auto',
+                textAlign: 'left',
+                fontSize: '12px',
+                color: '#374151',
+              }}
+            >
+              {this.state.error.message}
+            </pre>
+          )}
+          <button
+            onClick={() => window.location.reload()}
+            style={{
+              marginTop: '24px',
+              padding: '12px 24px',
+              background: '#3b82f6',
+              color: 'white',
+              border: 'none',
+              borderRadius: '8px',
+              fontSize: '14px',
+              fontWeight: '600',
+              cursor: 'pointer',
+            }}
+          >
+            Reload Page
+          </button>
+        </div>
+      )
+    }
+
+    return this.props.children
+  }
+}
--- a/apps/web/src/lib/arcade/game-sdk/define-game.ts
+++ b/apps/web/src/lib/arcade/game-sdk/define-game.ts
@@ -0,0 +1,80 @@
+/**
+ * Game definition helper
+ * Provides type-safe game registration
+ */
+
+import type {
+  GameComponent,
+  GameConfig,
+  GameDefinition,
+  GameMove,
+  GameProviderComponent,
+  GameState,
+  GameValidator,
+} from './types'
+import type { GameManifest } from '../manifest-schema'
+
+/**
+ * Options for defining a game
+ */
+export interface DefineGameOptions<
+  TConfig extends GameConfig,
+  TState extends GameState,
+  TMove extends GameMove,
+> {
+  /** Game manifest (loaded from game.yaml) */
+  manifest: GameManifest
+
+  /** React provider component */
+  Provider: GameProviderComponent
+
+  /** Main game UI component */
+  GameComponent: GameComponent
+
+  /** Server-side validator */
+  validator: GameValidator<TState, TMove>
+
+  /** Default configuration for the game */
+  defaultConfig: TConfig
+}
+
+/**
+ * Define a game with full type safety
+ *
+ * This helper ensures all required parts of a game are provided
+ * and returns a properly typed GameDefinition.
+ *
+ * @example
+ * ```typescript
+ * export const myGame = defineGame({
+ *   manifest: loadManifest('./game.yaml'),
+ *   Provider: MyGameProvider,
+ *   GameComponent: MyGameComponent,
+ *   validator: myGameValidator,
+ *   defaultConfig: {
+ *     difficulty: 'easy',
+ *     maxTime: 60
+ *   }
+ * })
+ * ```
+ */
+export function defineGame<
+  TConfig extends GameConfig,
+  TState extends GameState,
+  TMove extends GameMove,
+>(options: DefineGameOptions<TConfig, TState, TMove>): GameDefinition<TConfig, TState, TMove> {
+  const { manifest, Provider, GameComponent, validator, defaultConfig } = options
+
+  // Validate that manifest.name matches the game identifier
+  if (!manifest.name) {
+    throw new Error('Game manifest must have a "name" field')
+  }
+
+  return {
+    manifest,
+    Provider,
+    GameComponent,
+    validator,
+    defaultConfig,
+  }
+}
--- a/apps/web/src/lib/arcade/game-sdk/index.ts
+++ b/apps/web/src/lib/arcade/game-sdk/index.ts
@@ -0,0 +1,92 @@
+/**
+ * Arcade Game SDK - Stable API Surface
+ *
+ * This is the ONLY module that games are allowed to import from.
+ * All game code must use this SDK - no direct imports from /src/
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   defineGame,
+ *   useArcadeSession,
+ *   useRoomData,
+ *   type GameDefinition
+ * } from '@/lib/arcade/game-sdk'
+ * ```
+ */
+
+// ============================================================================
+// Core Types
+// ============================================================================
+export type {
+  GameDefinition,
+  GameProviderComponent,
+  GameComponent,
+  GameValidator,
+  GameConfig,
+  GameState,
+  GameMove,
+  ValidationContext,
+  ValidationResult,
+  TeamMoveSentinel,
+} from './types'
+
+export { TEAM_MOVE } from './types'
+
+export type { GameManifest } from '../manifest-schema'
+
+// ============================================================================
+// React Hooks (Controlled API)
+// ============================================================================
+
+/**
+ * Arcade session management hook
+ * Handles state synchronization, move validation, and multiplayer sync
+ */
+export { useArcadeSession } from '@/hooks/useArcadeSession'
+
+/**
+ * Room data hook - access current room information
+ */
+export { useRoomData, useUpdateGameConfig } from '@/hooks/useRoomData'
+
+/**
+ * Game mode context - access players and game mode
+ */
+export { useGameMode } from '@/contexts/GameModeContext'
+
+/**
+ * Viewer ID hook - get current user's ID
+ */
+export { useViewerId } from '@/hooks/useViewerId'
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+/**
+ * Player ownership and metadata utilities
+ */
+export {
+  buildPlayerMetadata,
+  buildPlayerOwnershipFromRoomData,
+} from '@/lib/arcade/player-ownership.client'
+
+/**
+ * Helper for loading and validating game manifests
+ */
+export { loadManifest } from './load-manifest'
+
+/**
+ * Game definition helper
+ */
+export { defineGame } from './define-game'
+
+// ============================================================================
+// Re-exports for convenience
+// ============================================================================
+
+/**
+ * Common types from contexts
+ */
+export type { Player } from '@/contexts/GameModeContext'
--- a/apps/web/src/lib/arcade/game-sdk/load-manifest.ts
+++ b/apps/web/src/lib/arcade/game-sdk/load-manifest.ts
@@ -0,0 +1,39 @@
+/**
+ * Manifest loading and validation utilities
+ */
+
+import yaml from 'js-yaml'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { validateManifest, type GameManifest } from '../manifest-schema'
+
+/**
+ * Load and validate a game manifest from a YAML file
+ *
+ * @param manifestPath - Absolute path to game.yaml file
+ * @returns Validated GameManifest object
+ * @throws Error if manifest is invalid or file doesn't exist
+ */
+export function loadManifest(manifestPath: string): GameManifest {
+  try {
+    const fileContents = readFileSync(manifestPath, 'utf8')
+    const data = yaml.load(fileContents)
+    return validateManifest(data)
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to load manifest from ${manifestPath}: ${error.message}`)
+    }
+    throw error
+  }
+}
+
+/**
+ * Load manifest from a game directory
+ *
+ * @param gameDir - Absolute path to game directory
+ * @returns Validated GameManifest object
+ */
+export function loadManifestFromDir(gameDir: string): GameManifest {
+  const manifestPath = join(gameDir, 'game.yaml')
+  return loadManifest(manifestPath)
+}
--- a/apps/web/src/lib/arcade/game-sdk/types.ts
+++ b/apps/web/src/lib/arcade/game-sdk/types.ts
@@ -0,0 +1,80 @@
+/**
+ * Type definitions for the Arcade Game SDK
+ * These types define the contract that all games must implement
+ */
+
+import type { ReactNode } from 'react'
+import type { GameManifest } from '../manifest-schema'
+import type {
+  GameMove as BaseGameMove,
+  GameValidator as BaseGameValidator,
+  ValidationContext,
+  ValidationResult,
+} from '../validation/types'
+
+/**
+ * Re-export base validation types from arcade system
+ */
+export type { GameMove, ValidationContext, ValidationResult } from '../validation/types'
+export { TEAM_MOVE } from '../validation/types'
+export type { TeamMoveSentinel } from '../validation/types'
+
+/**
+ * Generic game configuration
+ * Each game defines its own specific config type
+ */
+export type GameConfig = Record<string, unknown>
+
+/**
+ * Generic game state
+ * Each game defines its own specific state type
+ */
+export type GameState = Record<string, unknown>
+
+/**
+ * Game validator interface
+ * Games must implement this to validate moves server-side
+ */
+export interface GameValidator<TState = GameState, TMove extends BaseGameMove = BaseGameMove>
+  extends BaseGameValidator<TState, TMove> {
+  validateMove(state: TState, move: TMove, context?: ValidationContext): ValidationResult
+  isGameComplete(state: TState): boolean
+  getInitialState(config: unknown): TState
+}
+
+/**
+ * Provider component interface
+ * Each game provides a React context provider that wraps the game UI
+ */
+export type GameProviderComponent = (props: { children: ReactNode }) => JSX.Element
+
+/**
+ * Main game component interface
+ * The root component that renders the game UI
+ */
+export type GameComponent = () => JSX.Element
+
+/**
+ * Complete game definition
+ * This is what games export after using defineGame()
+ */
+export interface GameDefinition<
+  TConfig extends GameConfig = GameConfig,
+  TState extends GameState = GameState,
+  TMove extends BaseGameMove = BaseGameMove,
+> {
+  /** Parsed and validated manifest */
+  manifest: GameManifest
+
+  /** React provider component */
+  Provider: GameProviderComponent
+
+  /** Main game UI component */
+  GameComponent: GameComponent
+
+  /** Server-side validator */
+  validator: GameValidator<TState, TMove>
+
+  /** Default configuration */
+  defaultConfig: TConfig
+}
--- a/apps/web/src/lib/arcade/manifest-schema.ts
+++ b/apps/web/src/lib/arcade/manifest-schema.ts
@@ -0,0 +1,38 @@
+/**
+ * Game manifest schema validation
+ * Validates game.yaml files using Zod
+ */
+
+import { z } from 'zod'
+
+/**
+ * Schema for game manifest (game.yaml)
+ */
+export const GameManifestSchema = z.object({
+  name: z.string().min(1).describe('Internal game identifier (e.g., "matching")'),
+  displayName: z.string().min(1).describe('Display name shown to users'),
+  icon: z.string().min(1).describe('Emoji icon for the game'),
+  description: z.string().min(1).describe('Short description'),
+  longDescription: z.string().min(1).describe('Detailed description'),
+  maxPlayers: z.number().int().min(1).max(10).describe('Maximum number of players'),
+  difficulty: z
+    .enum(['Beginner', 'Intermediate', 'Advanced', 'Expert'])
+    .describe('Difficulty level'),
+  chips: z.array(z.string()).describe('Feature chips displayed on game card'),
+  color: z.string().min(1).describe('Color theme (e.g., "purple")'),
+  gradient: z.string().min(1).describe('CSS gradient for card background'),
+  borderColor: z.string().min(1).describe('Border color (e.g., "purple.200")'),
+  available: z.boolean().describe('Whether game is available to play'),
+})
+
+/**
+ * Inferred TypeScript type from schema
+ */
+export type GameManifest = z.infer<typeof GameManifestSchema>
+
+/**
+ * Validate a parsed manifest object
+ */
+export function validateManifest(data: unknown): GameManifest {
+  return GameManifestSchema.parse(data)
+}
--- a/apps/web/src/lib/arcade/session-manager.ts
+++ b/apps/web/src/lib/arcade/session-manager.ts
@@ -6,7 +6,8 @@
 import { eq } from 'drizzle-orm'
 import { db, schema } from '@/db'
 import { buildPlayerOwnershipMap, type PlayerOwnershipMap } from './player-ownership'
-import { type GameMove, type GameName, getValidator } from './validation'
+import { getValidator, type GameName } from './validators'
+import type { GameMove } from './validation/types'

 export interface CreateSessionOptions {
  userId: string // User who owns/created the session (typically room creator)
--- a/apps/web/src/lib/arcade/validation/index.ts
+++ b/apps/web/src/lib/arcade/validation/index.ts
@@ -1,26 +1,19 @@
 /**
 * Game validator registry
- * Maps game names to their validators
+ * @deprecated This file now re-exports from the unified registry
+ * New code should import from '@/lib/arcade/validators' instead
 */

-import { matchingGameValidator } from './MatchingGameValidator'
-import { memoryQuizGameValidator } from './MemoryQuizGameValidator'
-import type { GameName, GameValidator } from './types'
+// Re-export everything from unified registry
+export {
+  getValidator,
+  hasValidator,
+  getRegisteredGameNames,
+  validatorRegistry,
+  matchingGameValidator,
+  memoryQuizGameValidator,
+  numberGuesserValidator,
+} from '../validators'

-const validators = new Map<GameName, GameValidator>([
-  ['matching', matchingGameValidator],
-  ['memory-quiz', memoryQuizGameValidator],
-  // Add other game validators here as they're implemented
-])
-
-export function getValidator(gameName: GameName): GameValidator {
-  const validator = validators.get(gameName)
-  if (!validator) {
-    throw new Error(`No validator found for game: ${gameName}`)
-  }
-  return validator
-}
-
-export { matchingGameValidator } from './MatchingGameValidator'
-export { memoryQuizGameValidator } from './MemoryQuizGameValidator'
+export type { GameName } from '../validators'
 export * from './types'
--- a/apps/web/src/lib/arcade/validation/types.ts
+++ b/apps/web/src/lib/arcade/validation/types.ts
@@ -6,7 +6,11 @@
 import type { MemoryPairsState } from '@/app/games/matching/context/types'
 import type { SorobanQuizState } from '@/app/arcade/memory-quiz/types'

-export type GameName = 'matching' | 'memory-quiz' | 'complement-race'
+/**
+ * Game name type - auto-derived from validator registry
+ * @deprecated Import from '@/lib/arcade/validators' instead
+ */
+export type { GameName } from '../validators'

 export interface ValidationResult {
  valid: boolean
--- a/apps/web/src/lib/arcade/validators.ts
+++ b/apps/web/src/lib/arcade/validators.ts
@@ -0,0 +1,68 @@
+/**
+ * Unified Validator Registry (Isomorphic - runs on client AND server)
+ *
+ * This is the single source of truth for game validators.
+ * Both client and server import validators from here.
+ *
+ * To add a new game:
+ * 1. Import the validator
+ * 2. Add to validatorRegistry Map
+ * 3. GameName type will auto-update
+ */
+
+import { matchingGameValidator } from './validation/MatchingGameValidator'
+import { memoryQuizGameValidator } from './validation/MemoryQuizGameValidator'
+import { numberGuesserValidator } from '@/arcade-games/number-guesser/Validator'
+import type { GameValidator } from './validation/types'
+
+/**
+ * Central registry of all game validators
+ * Key: game name (matches manifest.name)
+ * Value: validator instance
+ */
+export const validatorRegistry = {
+  matching: matchingGameValidator,
+  'memory-quiz': memoryQuizGameValidator,
+  'number-guesser': numberGuesserValidator,
+  // Add new games here - GameName type will auto-update
+} as const
+
+/**
+ * Auto-derived game name type from registry
+ * No need to manually update this!
+ */
+export type GameName = keyof typeof validatorRegistry
+
+/**
+ * Get validator for a game
+ * @throws Error if game not found (fail fast)
+ */
+export function getValidator(gameName: string): GameValidator {
+  const validator = validatorRegistry[gameName as GameName]
+  if (!validator) {
+    throw new Error(
+      `No validator found for game: ${gameName}. ` +
+        `Available games: ${Object.keys(validatorRegistry).join(', ')}`
+    )
+  }
+  return validator
+}
+
+/**
+ * Check if a game has a registered validator
+ */
+export function hasValidator(gameName: string): gameName is GameName {
+  return gameName in validatorRegistry
+}
+
+/**
+ * Get all registered game names
+ */
+export function getRegisteredGameNames(): GameName[] {
+  return Object.keys(validatorRegistry) as GameName[]
+}
+
+/**
+ * Re-export validators for backwards compatibility
+ */
+export { matchingGameValidator, memoryQuizGameValidator, numberGuesserValidator }
--- a/apps/web/src/socket-server.ts
+++ b/apps/web/src/socket-server.ts
@@ -13,8 +13,8 @@ import {
 import { createRoom, getRoomById } from './lib/arcade/room-manager'
 import { getRoomMembers, getUserRooms, setMemberOnline } from './lib/arcade/room-membership'
 import { getRoomActivePlayers, getRoomPlayerIds } from './lib/arcade/player-manager'
-import type { GameMove, GameName } from './lib/arcade/validation'
-import { getValidator } from './lib/arcade/validation'
+import { getValidator, type GameName } from './lib/arcade/validators'
+import type { GameMove } from './lib/arcade/validation/types'
 import { getGameConfig } from './lib/arcade/game-config-helpers'

 // Use globalThis to store socket.io instance to avoid module isolation issues
--- a/apps/web/tsconfig.server.json
+++ b/apps/web/tsconfig.server.json
@@ -19,10 +19,24 @@
    "src/db/schema/**/*.ts",
    "src/db/migrate.ts",
    "src/lib/arcade/**/*.ts",
+    "src/arcade-games/**/Validator.ts",
+    "src/arcade-games/**/types.ts",
    "src/app/games/matching/context/types.ts",
    "src/app/games/matching/utils/cardGeneration.ts",
    "src/app/games/matching/utils/matchValidation.ts",
+    "src/app/arcade/memory-quiz/types.ts",
    "src/socket-server.ts"
  ],
-  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts"]
+  "exclude": [
+    "node_modules",
+    "dist",
+    "src/components/**/*",
+    "src/contexts/**/*",
+    "src/hooks/**/*",
+    "src/stories/**/*",
+    "src/utils/**/*",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts"
+  ]
 }
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "soroban-monorepo",
-  "version": "3.20.0",
+  "version": "3.22.3",
  "private": true,
  "description": "Beautiful Soroban Flashcard Generator - Monorepo",
  "workspaces": [
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -152,6 +152,9 @@ importers:
      jose:
        specifier: ^6.1.0
        version: 6.1.0
+      js-yaml:
+        specifier: ^4.1.0
+        version: 4.1.0
      lucide-react:
        specifier: ^0.294.0
        version: 0.294.0(react@18.3.1)
@@ -210,6 +213,9 @@ importers:
      '@types/better-sqlite3':
        specifier: ^7.6.13
        version: 7.6.13
+      '@types/js-yaml':
+        specifier: ^4.0.9
+        version: 4.0.9
      '@types/node':
        specifier: ^20.0.0
        version: 20.19.19
@@ -3668,6 +3674,9 @@ packages:
  '@types/istanbul-reports@3.0.4':
    resolution: {integrity: sha512-pk2B1NWalF9toCRu6gjBzR69syFjP4Od8WRAX+0mmf9lAjCRicLOWc+ZrxZHx/0XRjotgkF9t6iaMJ+aXcOdZQ==}

+  '@types/js-yaml@4.0.9':
+    resolution: {integrity: sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==}
+
  '@types/jsdom@21.1.7':
    resolution: {integrity: sha512-yOriVnggzrnQ3a9OKOCxaVuSug3w3/SbOj5i7VwXWZEyUNl3bLF9V3MfxGbZKuwqJOQyRfqXyROBB1CoZLFWzA==}

@@ -13150,6 +13159,8 @@ snapshots:
    dependencies:
      '@types/istanbul-lib-report': 3.0.3

+  '@types/js-yaml@4.0.9': {}
+
  '@types/jsdom@21.1.7':
    dependencies:
      '@types/node': 20.19.19
Author	SHA1	Message	Date
semantic-release-bot	693fe6bb9f	chore(release): 3.22.3 [skip ci] ## [3.22.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.2...v3.22.3) (2025-10-16) ### Bug Fixes * number-guesser: add turn indicators, error feedback, and fix player ordering ([`9f62623`](`9f62623684`)) ### Documentation * arcade: update docs for unified validator registry ([`6f6cb14`](`6f6cb14650`))	2025-10-16 01:46:31 +00:00
Thomas Hallock	9f62623684	fix(number-guesser): add turn indicators, error feedback, and fix player ordering ## Bug Fixes ### 1. Turn Indicators - Added `currentPlayerId` prop to PageWithNav - Shows whose turn it is during choosing and guessing phases - Visual highlighting of active player avatar - Displays "Your turn" label for current user Files: - `GameComponent.tsx`: Calculate currentPlayerId based on game phase - `Provider.tsx`: Expose lastError and clearError to context ### 2. Error Feedback - Added error banner in GuessingPhase - Shows server rejection messages (out of bounds, not your turn, etc.) - Auto-dismisses after 5 seconds - Clear dismiss button for manual dismissal Impact: Users now see why their moves were rejected instead of silent failures. ### 3. Player Ordering Consistency - Fixed player ordering mismatch between UI and game logic - Removed `.sort()` to keep Set iteration order consistent - Both UI (PageWithNav) and game logic now use same player order Issue: UI showed players in Set order, but game logic used alphabetical order, causing "skipped leftmost player" bug. Fix: Use `Array.from(activePlayerIds)` without sorting everywhere. ### 4. Score Display - Added `playerScores` prop to PageWithNav - Shows scores for all players in the navigation ## Testing Notes These fixes address all issues found during manual testing: - ✅ Turn indicator now shows correctly - ✅ Error messages display to users - ✅ Player order matches between UI and game logic - ✅ Scores visible in navigation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-15 20:45:39 -05:00
Thomas Hallock	6f6cb14650	docs(arcade): update docs for unified validator registry ## Documentation Updates ### src/arcade-games/README.md - Step 7: Expanded to explain both registration steps - 7a: Register validator in validators.ts (server-side) - 7b: Register game in game-registry.ts (client-side) - Added explanation of why both steps are needed - Added verification warnings that appear during registration - Clarified the difference between isomorphic and client-only code ### docs/AUDIT_MODULAR_GAME_SYSTEM.md - Status: Updated from "CRITICAL ISSUES" to "ISSUE RESOLVED" - Executive Summary: Marked system as Production Ready - Issue #1: Marked as RESOLVED with implementation details - Issue #2: Marked as RESOLVED (validators now accessible) - Issue #5: Marked as RESOLVED (GameName auto-derived) - Compliance Table: Updated grade from D to B+ - Action Items: Marked critical items 1-3 as completed ## Summary Documentation now accurately reflects the unified validator registry implementation, providing clear guidance for developers adding new games. Related: 9459f37b (implementation commit) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-15 20:41:06 -05:00
semantic-release-bot	61196ccbff	chore(release): 3.22.2 [skip ci] ## [3.22.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.1...v3.22.2) (2025-10-16) ### Code Refactoring * arcade: create unified validator registry to fix dual registration ([`f775fc5`](`f775fc55e5`)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)	2025-10-16 01:39:05 +00:00
Thomas Hallock	f775fc55e5	refactor(arcade): create unified validator registry to fix dual registration Problem: Games required dual registration - once in client registry (game-registry.ts) and again in server validator map (validation/index.ts). This broke the modular architecture goal. Solution: Created unified isomorphic validator registry that serves both client and server needs. ## Changes ### New File - `src/lib/arcade/validators.ts` - Unified validator registry - Single source of truth for all game validators - Auto-derives GameName type from registry keys - Isomorphic (runs on both client and server) ### Updated Files - `validation/index.ts` - Converted to re-export from unified registry - Maintains backwards compatibility - Marked as deprecated - `validation/types.ts` - GameName now re-exported from validators - No longer hard-coded union type - Auto-updates when new games added - `game-registry.ts` - Added runtime validation - Checks if validator registered server-side - Warns on registration mismatch - `session-manager.ts` - Import from unified registry - `socket-server.ts` - Import from unified registry - `route.ts` (rooms API) - Use hasValidator() instead of hard-coded array - `game-config-helpers.ts` - Handle ExtendedGameName for legacy games - Supports both registered validators and legacy 'complement-race' - TODO comment for migration ## Benefits ✅ Single registration point for new games ✅ Auto-derived GameName type (no manual updates) ✅ Type-safe validator access ✅ Backwards compatible with existing code ✅ Clear migration path for old games ## Migration Status - ✅ number-guesser: Uses new system - 🔄 matching, memory-quiz: Use new validator registry, not migrated to arcade-games/ yet - ⏳ complement-race: Legacy game, handled via ExtendedGameName Addresses critical Issue #1 from AUDIT_MODULAR_GAME_SYSTEM.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-15 20:38:15 -05:00
semantic-release-bot	3cef4fcbac	chore(release): 3.22.1 [skip ci] ## [3.22.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.0...v3.22.1) (2025-10-16) ### Bug Fixes * arcade: add Number Guesser to game config helpers ([`7d1a351`](`7d1a351ed6`)) * nav: update types for registry games with nullable gameName ([`a51e539`](`a51e539d02`))	2025-10-16 00:16:26 +00:00
Thomas Hallock	a51e539d02	fix(nav): update types for registry games with nullable gameName Fixes TypeScript errors introduced by registry game system: - Allow gameName to be string \| null in nav component types - Update RecentRoom, AddPlayerButton, GameContextNav, ArcadeRoomInfo interfaces - Convert null to undefined where needed for legacy function calls - Fix GameTitleMenu showMenu prop - Update JoinRoomModal to use separate useGetRoomByCode and useJoinRoom hooks These changes allow rooms to exist without a selected game (gameName = null). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-15 19:15:32 -05:00
Thomas Hallock	7d1a351ed6	fix(arcade): add Number Guesser to game config helpers Fixes server-side session creation for Number Guesser: - Import DEFAULT_NUMBER_GUESSER_CONFIG - Add case for 'number-guesser' in getDefaultGameConfig() - Add validation for number-guesser config - Include arcade-games validators in server TypeScript build This resolves the "Unknown game: number-guesser" error when creating sessions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-15 19:15:32 -05:00
semantic-release-bot	3e81c1f480	chore(release): 3.22.0 [skip ci] ## [3.22.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.21.0...v3.22.0) (2025-10-16) ### Features * arcade: add Number Guesser demo game with plugin architecture ([`0e3c058`](`0e3c058707`))	2025-10-16 00:08:18 +00:00
Thomas Hallock	0e3c058707	feat(arcade): add Number Guesser demo game with plugin architecture Implements the first registry-based game to demonstrate the modular plugin system: Game Features: - Turn-based number guessing with hot/cold feedback - 2-4 players with configurable settings - Round-based scoring system - Complete game phases: Setup → Choosing → Guessing → Results Technical Implementation: - Created Number Guesser game in src/arcade-games/number-guesser/ - Registered NumberGuesserValidator in validation system - Added 'number-guesser' to database schema enums (arcade_rooms, arcade_sessions, room_game_configs) - Created NumberGuesserGameConfig type with default configuration - Integrated game into GameSelector and room page - Added PageWithNav wrapper for consistent navigation - Fixed controlled input warnings with fallback values Registry Integration: - Game automatically appears in /arcade/room selection UI - Settings persist to room_game_configs table - Validator creates and manages server-side game state - Provider syncs client state via arcade session 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-15 19:07:20 -05:00
semantic-release-bot	0e76bcd79a	chore(release): 3.21.0 [skip ci] ## [3.21.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.20.0...v3.21.0) (2025-10-15) ### Features * arcade: add modular game SDK and registry system ([`de30bec`](`de30bec479`))	2025-10-15 23:10:06 +00:00
Thomas Hallock	de30bec479	feat(arcade): add modular game SDK and registry system Create foundation for modular arcade game architecture: Game SDK (`/src/lib/arcade/game-sdk/`): - Stable API surface that games can safely import - Type-safe game definition with `defineGame()` helper - Controlled hook exports (useArcadeSession, useRoomData, etc.) - Player ownership and metadata utilities - Error boundary component for game crashes Manifest System: - YAML-based game manifests with Zod validation - Game metadata (name, icon, description, difficulty, etc.) - Type-safe manifest loading with `loadManifest()` Game Registry: - Central registry for all arcade games - Explicit registration pattern via `registerGame()` - Helper functions to query available games Type Safety: - Full TypeScript contracts for games - GameValidator, GameState, GameMove, GameConfig types - Compile-time validation of game implementations This establishes the plugin system for drop-in arcade games. Next: Create demo games to exercise the system. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-15 18:09:17 -05:00