chore(release): 3.23.0 [skip ci]

## [3.23.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.3...v3.23.0) (2025-10-16)

### Features

* **arcade:** add Math Sprint game implementation ([e5be09e](e5be09ef5f))
* **arcade:** register Math Sprint in game system ([0c05a7c](0c05a7c6bb)), closes [#2](https://github.com/antialias/soroban-abacus-flashcards/issues/2) [#3](https://github.com/antialias/soroban-abacus-flashcards/issues/3)

### Bug Fixes

* **api:** add 'math-sprint' to settings endpoint validation ([d790e5e](d790e5e278)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)
* **db:** add 'math-sprint' to database schema enums ([7b112a9](7b112a98ba)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)

### Documentation

* add architecture quality audit [#2](https://github.com/antialias/soroban-abacus-flashcards/issues/2) ([5b91b71](5b91b71078))

CHANGELOG.md

@@ -1,3 +1,34 @@
+## [3.23.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.3...v3.23.0) (2025-10-16)
+
+
+### Features
+
+* **arcade:** add Math Sprint game implementation ([e5be09e](https://github.com/antialias/soroban-abacus-flashcards/commit/e5be09ef5f170c7544557f75b9eca17bb2069246))
+* **arcade:** register Math Sprint in game system ([0c05a7c](https://github.com/antialias/soroban-abacus-flashcards/commit/0c05a7c6bbc8d6f6e1f92e15e691d7e1aba0d8f7)), closes [#2](https://github.com/antialias/soroban-abacus-flashcards/issues/2) [#3](https://github.com/antialias/soroban-abacus-flashcards/issues/3)
+
+
+### Bug Fixes
+
+* **api:** add 'math-sprint' to settings endpoint validation ([d790e5e](https://github.com/antialias/soroban-abacus-flashcards/commit/d790e5e278f81686077dbe3ef4adca49574ae434)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)
+* **db:** add 'math-sprint' to database schema enums ([7b112a9](https://github.com/antialias/soroban-abacus-flashcards/commit/7b112a98babe782d4c254ef18a0295e7cbf8fefa)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)
+
+
+### Documentation
+
+* add architecture quality audit [#2](https://github.com/antialias/soroban-abacus-flashcards/issues/2) ([5b91b71](https://github.com/antialias/soroban-abacus-flashcards/commit/5b91b710782dc450405583bc196e5156a296d0df))
+
+## [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)
 
 

apps/web/docs/AUDIT_2_ARCHITECTURE_QUALITY.md

@@ -0,0 +1,451 @@
+# Architecture Quality Audit #2
+
+**Date**: 2025-10-16
+**Context**: After implementing Number Guesser (turn-based) and starting Math Sprint (free-for-all)
+**Goal**: Assess if the system is truly modular or if there's too much boilerplate
+
+---
+
+## Executive Summary
+
+**Status**: ⚠️ **Good Foundation, But Boilerplate Issues**
+
+The unified validator registry successfully solved the dual registration problem. However, implementing a second game revealed **significant boilerplate** and **database schema coupling** that violate the modular architecture goals.
+
+**Grade**: **B-** (Down from B+ after implementation testing)
+
+---
+
+## Issues Found
+
+### 🚨 Issue #1: Database Schema Coupling (CRITICAL)
+
+**Problem**: The `room_game_configs` table schema hard-codes game names, preventing true modularity.
+
+**Evidence**:
+```typescript
+// db/schema/room-game-configs.ts
+gameName: text('game_name').$type<'matching' | 'memory-quiz' | 'number-guesser' | 'complement-race'>()
+```
+
+When adding 'math-sprint':
+```
+Type '"math-sprint"' is not assignable to type '"matching" | "memory-quiz" | "number-guesser" | "complement-race"'
+```
+
+**Impact**:
+- ❌ Must manually update database schema for every new game
+- ❌ TypeScript errors force schema migration
+- ❌ Breaks "just register and go" promise
+- ❌ Requires database migration for each game
+
+**Root Cause**: The schema uses a union type instead of a string with runtime validation.
+
+**Fix Required**: Change schema to accept any string, validate against registry at runtime.
+
+---
+
+### ⚠️ Issue #2: game-config-helpers.ts Boilerplate
+
+**Problem**: Three switch statements must be updated for every new game:
+
+1. `getDefaultGameConfig()` - add case
+2. Import default config constant
+3. `validateGameConfig()` - add validation logic
+
+**Example** (from Math Sprint):
+```typescript
+// Must add to imports
+import { DEFAULT_MATH_SPRINT_CONFIG } from './game-configs'
+
+// Must add case to switch #1
+case 'math-sprint':
+  return DEFAULT_MATH_SPRINT_CONFIG
+
+// Must add case to switch #2
+case 'math-sprint':
+  return (
+    typeof config === 'object' &&
+    config !== null &&
+    ['easy', 'medium', 'hard'].includes(config.difficulty) &&
+    // ... 10+ lines of validation
+  )
+```
+
+**Impact**:
+- ⏱️ 5-10 minutes of boilerplate per game
+- 🐛 Easy to forget a switch case
+- 📝 Repetitive validation logic
+
+**Better Approach**: Config defaults and validation should be part of the game definition.
+
+---
+
+### ⚠️ Issue #3: game-configs.ts Boilerplate
+
+**Problem**: Must update 4 places in game-configs.ts:
+
+1. Import types from game
+2. Define `XGameConfig` interface
+3. Add to `GameConfigByName` union
+4. Add to `RoomGameConfig` interface
+5. Create `DEFAULT_X_CONFIG` constant
+
+**Example** (from Math Sprint):
+```typescript
+// 1. Import
+import type { Difficulty as MathSprintDifficulty } from '@/arcade-games/math-sprint/types'
+
+// 2. Interface
+export interface MathSprintGameConfig {
+  difficulty: MathSprintDifficulty
+  questionsPerRound: number
+  timePerQuestion: number
+}
+
+// 3. Add to union
+export type GameConfigByName = {
+  'math-sprint': MathSprintGameConfig
+  // ...
+}
+
+// 4. Add to RoomGameConfig
+export interface RoomGameConfig {
+  'math-sprint'?: MathSprintGameConfig
+  // ...
+}
+
+// 5. Default constant
+export const DEFAULT_MATH_SPRINT_CONFIG: MathSprintGameConfig = {
+  difficulty: 'medium',
+  questionsPerRound: 10,
+  timePerQuestion: 30,
+}
+```
+
+**Impact**:
+- ⏱️ 10-15 lines of boilerplate per game
+- 🐛 Easy to forget one of the 5 updates
+- 🔄 Repeating type information (already in game definition)
+
+**Better Approach**: Game config types should be inferred from game definitions.
+
+---
+
+### 📊 Issue #4: High Boilerplate Ratio
+
+**Files Required Per Game**:
+
+| Category | Files | Purpose |
+|----------|-------|---------|
+| **Game Code** | 7 files | types.ts, Validator.ts, Provider.tsx, index.ts, 3x components |
+| **Registration** | 2 files | validators.ts, game-registry.ts |
+| **Config** | 2 files | game-configs.ts, game-config-helpers.ts |
+| **Database** | 1 file | schema migration |
+| **Total** | **12 files** | For one game! |
+
+**Lines of Boilerplate** (non-game-logic):
+- game-configs.ts: ~15 lines
+- game-config-helpers.ts: ~25 lines
+- validators.ts: ~2 lines
+- game-registry.ts: ~2 lines
+- **Total: ~44 lines of pure boilerplate per game**
+
+**Comparison**:
+- Number Guesser: ~500 lines of actual game logic
+- Boilerplate: ~44 lines (8.8% overhead) ✅ Acceptable
+- But spread across 4 different files ⚠️ Developer friction
+
+---
+
+## Positive Aspects
+
+### ✅ What Works Well
+
+1. **SDK Abstraction**
+   - `useArcadeSession` is clean and reusable
+   - `buildPlayerMetadata` helper reduces duplication
+   - Hook-based API is intuitive
+
+2. **Provider Pattern**
+   - Consistent across games
+   - Clear separation of concerns
+   - Easy to understand
+
+3. **Component Structure**
+   - SetupPhase, PlayingPhase, ResultsPhase pattern is clear
+   - GameComponent wrapper is simple
+   - PageWithNav integration is seamless
+
+4. **Unified Validator Registry**
+   - Single source of truth for validators ✅
+   - Auto-derived GameName type ✅
+   - Type-safe validator access ✅
+
+5. **Error Feedback**
+   - lastError/clearError pattern works well
+   - Auto-dismiss UX is good
+   - Consistent error handling
+
+---
+
+## Comparison: Number Guesser vs. Math Sprint
+
+### Similarities (Good!)
+- ✅ Same file structure
+- ✅ Same SDK usage patterns
+- ✅ Same Provider pattern
+- ✅ Same component phases
+
+### Differences (Revealing!)
+- Math Sprint uses TEAM_MOVE (no turn owner)
+- Math Sprint has server-generated questions
+- Database schema didn't support Math Sprint name
+
+**Key Insight**: The SDK handles different game types well (turn-based vs. free-for-all), but infrastructure (database, config system) is rigid.
+
+---
+
+## Developer Experience Score
+
+### Time to Add a Game
+
+| Task | Time | Notes |
+|------|------|-------|
+| Write game logic | 2-4 hours | Validator, state management, components |
+| Registration boilerplate | 15-20 min | 4 files to update |
+| Database migration | 10-15 min | Schema update, migration file |
+| Debugging type errors | 10-30 min | Database schema mismatches |
+| **Total** | **3-5 hours** | For a simple game |
+
+### Pain Points
+
+1. **Database Schema** ⚠️ Critical blocker
+   - Must update schema for each game
+   - Requires migration
+   - TypeScript errors are confusing
+
+2. **Config System** ⚠️ Medium friction
+   - 5 places to update in game-configs.ts
+   - Easy to miss one
+   - Repetitive type definitions
+
+3. **Helper Functions** ⚠️ Low friction
+   - Switch statements in game-config-helpers.ts
+   - Not hard, just tedious
+
+### What Developers Like
+
+1. ✅ SDK is intuitive
+2. ✅ Pattern is consistent
+3. ✅ Error messages are clear (once you know where to look)
+4. ✅ Documentation is comprehensive
+
+---
+
+## Architectural Recommendations
+
+### Critical (Before Adding More Games)
+
+**1. Fix Database Schema Coupling**
+
+**Current**:
+```typescript
+gameName: text('game_name').$type<'matching' | 'memory-quiz' | 'number-guesser' | 'complement-race'>()
+```
+
+**Recommended**:
+```typescript
+// Accept any string, validate at runtime
+gameName: text('game_name').$type<string>().notNull()
+
+// Runtime validation in helper functions
+export function validateGameName(gameName: string): gameName is GameName {
+  return hasValidator(gameName)
+}
+```
+
+**Benefits**:
+- ✅ No schema migration per game
+- ✅ Works with auto-derived GameName
+- ✅ Runtime validation is sufficient
+
+---
+
+**2. Infer Config Types from Game Definitions**
+
+**Current** (manual):
+```typescript
+// In game-configs.ts
+export interface MathSprintGameConfig { ... }
+export const DEFAULT_MATH_SPRINT_CONFIG = { ... }
+
+// In game definition
+const defaultConfig: MathSprintGameConfig = { ... }
+```
+
+**Recommended**:
+```typescript
+// In game definition (single source of truth)
+export const mathSprintGame = defineGame({
+  defaultConfig: {
+    difficulty: 'medium',
+    questionsPerRound: 10,
+    timePerQuestion: 30,
+  },
+  validator: mathSprintValidator,
+  // ...
+})
+
+// Auto-infer types
+type MathSprintConfig = typeof mathSprintGame.defaultConfig
+```
+
+**Benefits**:
+- ✅ No duplication
+- ✅ Single source of truth
+- ✅ Type inference handles it
+
+---
+
+**3. Move Config Validation to Game Definition**
+
+**Current** (switch statement in helper):
+```typescript
+function validateGameConfig(gameName: GameName, config: any): boolean {
+  switch (gameName) {
+    case 'math-sprint':
+      return /* 15 lines of validation */
+  }
+}
+```
+
+**Recommended**:
+```typescript
+// In game definition
+export const mathSprintGame = defineGame({
+  defaultConfig: { ... },
+  validateConfig: (config: any): config is MathSprintConfig => {
+    return /* validation logic */
+  },
+  // ...
+})
+
+// In helper (generic)
+export function validateGameConfig(gameName: GameName, config: any): boolean {
+  const game = getGame(gameName)
+  return game?.validateConfig?.(config) ?? true
+}
+```
+
+**Benefits**:
+- ✅ No switch statement
+- ✅ Validation lives with game
+- ✅ One place to update
+
+---
+
+### Medium Priority
+
+**4. Create CLI Tool for Game Generation**
+
+```bash
+npm run create-game math-sprint "Math Sprint" "🧮"
+```
+
+Generates:
+- File structure
+- Boilerplate code
+- Registration entries
+- Types
+
+**Benefits**:
+- ✅ Eliminates manual boilerplate
+- ✅ Consistent structure
+- ✅ Reduces errors
+
+---
+
+**5. Add Runtime Registry Validation**
+
+On app start, verify:
+- ✅ All games in registry have validators
+- ✅ All validators have games
+- ✅ No orphaned configs
+- ✅ All game names are unique
+
+```typescript
+function validateRegistries() {
+  const games = getAllGames()
+  const validators = getRegisteredGameNames()
+
+  for (const game of games) {
+    if (!validators.includes(game.manifest.name)) {
+      throw new Error(`Game ${game.manifest.name} has no validator!`)
+    }
+  }
+}
+```
+
+---
+
+## Updated Compliance Table
+
+| Intention | Status | Notes |
+|-----------|--------|-------|
+| Modularity | ⚠️ Partial | Validators unified, but database/config not modular |
+| Self-registration | ✅ Pass | Two registration points (validator + game), both clear |
+| Type safety | ⚠️ Partial | Types work, but database schema breaks for new games |
+| No core changes | ⚠️ Partial | Must update 4 files + database schema |
+| Drop-in games | ❌ Fail | Database migration required |
+| Stable SDK API | ✅ Pass | SDK is excellent |
+| Clear patterns | ✅ Pass | Patterns are consistent |
+| Low boilerplate | ⚠️ Partial | SDK usage is clean, registration is verbose |
+
+**Overall Grade**: **B-** (Was B+, downgraded after implementation testing)
+
+---
+
+## Summary
+
+### What We Learned
+
+✅ **The Good**:
+- SDK design is solid
+- Unified validator registry works
+- Pattern is consistent and learnable
+- Number Guesser proves the concept
+
+⚠️ **The Not-So-Good**:
+- Database schema couples to game names (critical blocker)
+- Config system has too much boilerplate
+- 12 files touched per game is high
+
+❌ **The Bad**:
+- Can't truly "drop in" a game without schema migration
+- Config types are duplicated
+- Helper switch statements are tedious
+
+### Verdict
+
+The system **works** and is **usable**, but falls short of "modular architecture" goals due to:
+1. Database schema hard-coding
+2. Config system boilerplate
+3. Required schema migrations
+
+**Recommendation**:
+1. **Option A (Quick Fix)**: Document the 12-file checklist, live with boilerplate for now
+2. **Option B (Proper Fix)**: Implement Critical recommendations 1-3 before adding Math Sprint
+
+**My Recommendation**: Option A for now (get Math Sprint working), then Option B as a refactoring sprint.
+
+---
+
+## Next Steps
+
+1. ✅ Document "Adding a Game" checklist (12 files)
+2. 🔴 Fix database schema to accept any game name
+3. 🟡 Test Math Sprint with current architecture
+4. 🟡 Evaluate if boilerplate is acceptable in practice
+5. 🟢 Consider config system refactoring for later
+

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`

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' | 'number-guesser' | null (select game for room)
+ *   - gameName?: 'matching' | 'memory-quiz' | 'complement-race' | 'number-guesser' | 'math-sprint' | null (select game for room)
  *   - gameConfig?: object (game-specific settings)
  */
 export async function PATCH(req: NextRequest, context: RouteContext) {
@@ -95,7 +95,7 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
     // Validate gameName if provided
     if (body.gameName !== undefined && body.gameName !== null) {
       // Legacy games + registry games (TODO: make this dynamic when we refactor to lazy-load registry)
-      const validGames = ['matching', 'memory-quiz', 'complement-race', 'number-guesser']
+      const validGames = ['matching', 'memory-quiz', 'complement-race', 'number-guesser', 'math-sprint']
       if (!validGames.includes(body.gameName)) {
         return NextResponse.json({ error: 'Invalid game name' }, { status: 400 })
       }

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.

apps/web/src/arcade-games/math-sprint/Provider.tsx

@@ -0,0 +1,198 @@
+/**
+ * Math Sprint Provider
+ *
+ * Context provider for Math Sprint game state management.
+ * Demonstrates free-for-all gameplay with TEAM_MOVE pattern.
+ */
+
+'use client'
+
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from 'react'
+import {
+  buildPlayerMetadata,
+  useArcadeSession,
+  useGameMode,
+  useRoomData,
+  useUpdateGameConfig,
+  useViewerId,
+} from '@/lib/arcade/game-sdk'
+import { TEAM_MOVE } from '@/lib/arcade/validation/types'
+import type { Difficulty, MathSprintState } from './types'
+
+/**
+ * Context value provided to child components
+ */
+interface MathSprintContextValue {
+  state: MathSprintState
+  lastError: string | null
+  startGame: () => void
+  submitAnswer: (answer: number) => void
+  nextQuestion: () => void
+  resetGame: () => void
+  setConfig: (field: 'difficulty' | 'questionsPerRound' | 'timePerQuestion', value: any) => void
+  clearError: () => void
+  exitSession: () => void
+}
+
+const MathSprintContext = createContext<MathSprintContextValue | null>(null)
+
+/**
+ * Hook to access Math Sprint context
+ */
+export function useMathSprint() {
+  const context = useContext(MathSprintContext)
+  if (!context) {
+    throw new Error('useMathSprint must be used within MathSprintProvider')
+  }
+  return context
+}
+
+/**
+ * Math Sprint Provider Component
+ */
+export function MathSprintProvider({ 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)
+  const activePlayers = Array.from(activePlayerIds)
+
+  // Merge saved config from room with defaults
+  const gameConfig = useMemo(() => {
+    const allGameConfigs = roomData?.gameConfig as Record<string, unknown> | null | undefined
+    const savedConfig = allGameConfigs?.['math-sprint'] as Record<string, unknown> | undefined
+    return {
+      difficulty: (savedConfig?.difficulty as Difficulty) || 'medium',
+      questionsPerRound: (savedConfig?.questionsPerRound as number) || 10,
+      timePerQuestion: (savedConfig?.timePerQuestion as number) || 30,
+    }
+  }, [roomData?.gameConfig])
+
+  // Initial state with merged config
+  const initialState = useMemo<MathSprintState>(
+    () => ({
+      gamePhase: 'setup',
+      activePlayers: [],
+      playerMetadata: {},
+      difficulty: gameConfig.difficulty,
+      questionsPerRound: gameConfig.questionsPerRound,
+      timePerQuestion: gameConfig.timePerQuestion,
+      currentQuestionIndex: 0,
+      questions: [],
+      scores: {},
+      correctAnswersCount: {},
+      answers: [],
+      questionStartTime: 0,
+      questionAnswered: false,
+      winnerId: null,
+    }),
+    [gameConfig]
+  )
+
+  // Arcade session integration
+  const { state, sendMove, exitSession, lastError, clearError } =
+    useArcadeSession<MathSprintState>({
+      userId: viewerId || '',
+      roomId: roomData?.id,
+      initialState,
+      applyMove: (state) => state, // Server handles all state updates
+    })
+
+  // Action: Start game
+  const startGame = useCallback(() => {
+    const playerMetadata = buildPlayerMetadata(activePlayers, {}, players, viewerId || undefined)
+
+    sendMove({
+      type: 'START_GAME',
+      playerId: TEAM_MOVE, // Free-for-all: no specific turn owner
+      userId: viewerId || '',
+      data: { activePlayers, playerMetadata },
+    })
+  }, [activePlayers, players, viewerId, sendMove])
+
+  // Action: Submit answer
+  const submitAnswer = useCallback(
+    (answer: number) => {
+      // Find this user's player ID from game state
+      const myPlayerId = state.activePlayers.find((pid) => {
+        return state.playerMetadata[pid]?.userId === viewerId
+      })
+
+      if (!myPlayerId) {
+        console.error('[MathSprint] No player found for current user')
+        return
+      }
+
+      sendMove({
+        type: 'SUBMIT_ANSWER',
+        playerId: myPlayerId, // Specific player answering
+        userId: viewerId || '',
+        data: { answer },
+      })
+    },
+    [state.activePlayers, state.playerMetadata, viewerId, sendMove]
+  )
+
+  // Action: Next question
+  const nextQuestion = useCallback(() => {
+    sendMove({
+      type: 'NEXT_QUESTION',
+      playerId: TEAM_MOVE, // Any player can advance
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [viewerId, sendMove])
+
+  // Action: Reset game
+  const resetGame = useCallback(() => {
+    sendMove({
+      type: 'RESET_GAME',
+      playerId: TEAM_MOVE,
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [viewerId, sendMove])
+
+  // Action: Set config
+  const setConfig = useCallback(
+    (field: 'difficulty' | 'questionsPerRound' | 'timePerQuestion', value: any) => {
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId: TEAM_MOVE,
+        userId: viewerId || '',
+        data: { field, value },
+      })
+
+      // Persist to database for next session
+      if (roomData?.id) {
+        updateGameConfig({
+          roomId: roomData.id,
+          gameConfig: {
+            ...roomData.gameConfig,
+            'math-sprint': {
+              ...(roomData.gameConfig?.['math-sprint'] || {}),
+              [field]: value,
+            },
+          },
+        })
+      }
+    },
+    [viewerId, sendMove, updateGameConfig, roomData]
+  )
+
+  const contextValue: MathSprintContextValue = {
+    state,
+    lastError,
+    startGame,
+    submitAnswer,
+    nextQuestion,
+    resetGame,
+    setConfig,
+    clearError,
+    exitSession,
+  }
+
+  return <MathSprintContext.Provider value={contextValue}>{children}</MathSprintContext.Provider>
+}

apps/web/src/arcade-games/math-sprint/Validator.ts

@@ -0,0 +1,340 @@
+/**
+ * Math Sprint Validator
+ *
+ * Server-side validation for Math Sprint game.
+ * Generates questions, validates answers, awards points.
+ */
+
+import type { GameValidator, ValidationResult } from '@/lib/arcade/game-sdk'
+import { TEAM_MOVE } from '@/lib/arcade/validation/types'
+import type {
+  Difficulty,
+  MathSprintConfig,
+  MathSprintMove,
+  MathSprintState,
+  Operation,
+  Question,
+} from './types'
+
+export class MathSprintValidator
+  implements GameValidator<MathSprintState, MathSprintMove>
+{
+  /**
+   * Validate a game move
+   */
+  validateMove(
+    state: MathSprintState,
+    move: MathSprintMove,
+    context?: { userId?: string }
+  ): ValidationResult {
+    switch (move.type) {
+      case 'START_GAME':
+        return this.validateStartGame(state, move.data.activePlayers, move.data.playerMetadata)
+
+      case 'SUBMIT_ANSWER':
+        return this.validateSubmitAnswer(
+          state,
+          move.playerId,
+          Number(move.data.answer),
+          move.timestamp
+        )
+
+      case 'NEXT_QUESTION':
+        return this.validateNextQuestion(state)
+
+      case 'RESET_GAME':
+        return this.validateResetGame(state)
+
+      case 'SET_CONFIG':
+        return this.validateSetConfig(state, move.data.field, move.data.value)
+
+      default:
+        return { valid: false, error: 'Unknown move type' }
+    }
+  }
+
+  /**
+   * Check if game is complete
+   */
+  isGameComplete(state: MathSprintState): boolean {
+    return state.gamePhase === 'results'
+  }
+
+  /**
+   * Get initial state for new game
+   */
+  getInitialState(config: unknown): MathSprintState {
+    const { difficulty, questionsPerRound, timePerQuestion } = config as MathSprintConfig
+
+    return {
+      gamePhase: 'setup',
+      activePlayers: [],
+      playerMetadata: {},
+      difficulty: difficulty || 'medium',
+      questionsPerRound: questionsPerRound || 10,
+      timePerQuestion: timePerQuestion || 30,
+      currentQuestionIndex: 0,
+      questions: [],
+      scores: {},
+      correctAnswersCount: {},
+      answers: [],
+      questionStartTime: 0,
+      questionAnswered: false,
+      winnerId: null,
+    }
+  }
+
+  // ============================================================================
+  // Validation Methods
+  // ============================================================================
+
+  private validateStartGame(
+    state: MathSprintState,
+    activePlayers: string[],
+    playerMetadata: Record<string, any>
+  ): ValidationResult {
+    if (state.gamePhase !== 'setup') {
+      return { valid: false, error: 'Game already started' }
+    }
+
+    if (activePlayers.length < 2) {
+      return { valid: false, error: 'Need at least 2 players' }
+    }
+
+    // Generate questions
+    const questions = this.generateQuestions(state.difficulty, state.questionsPerRound)
+
+    const newState: MathSprintState = {
+      ...state,
+      gamePhase: 'playing',
+      activePlayers,
+      playerMetadata,
+      questions,
+      currentQuestionIndex: 0,
+      scores: activePlayers.reduce((acc, p) => ({ ...acc, [p]: 0 }), {}),
+      correctAnswersCount: activePlayers.reduce((acc, p) => ({ ...acc, [p]: 0 }), {}),
+      answers: [],
+      questionStartTime: Date.now(),
+      questionAnswered: false,
+      winnerId: null,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateSubmitAnswer(
+    state: MathSprintState,
+    playerId: string,
+    answer: number,
+    timestamp: number
+  ): ValidationResult {
+    if (state.gamePhase !== 'playing') {
+      return { valid: false, error: 'Game not in progress' }
+    }
+
+    if (!state.activePlayers.includes(playerId)) {
+      return { valid: false, error: 'Player not in game' }
+    }
+
+    if (state.questionAnswered) {
+      return { valid: false, error: 'Question already answered correctly' }
+    }
+
+    // Check if player already answered this question
+    const alreadyAnswered = state.answers.some((a) => a.playerId === playerId)
+    if (alreadyAnswered) {
+      return { valid: false, error: 'You already answered this question' }
+    }
+
+    const currentQuestion = state.questions[state.currentQuestionIndex]
+    const correct = answer === currentQuestion.correctAnswer
+
+    const answerRecord = {
+      playerId,
+      answer,
+      timestamp,
+      correct,
+    }
+
+    const newAnswers = [...state.answers, answerRecord]
+    let newState = { ...state, answers: newAnswers }
+
+    // If correct, award points and mark question as answered
+    if (correct) {
+      newState = {
+        ...newState,
+        questionAnswered: true,
+        winnerId: playerId,
+        scores: {
+          ...state.scores,
+          [playerId]: state.scores[playerId] + 10,
+        },
+        correctAnswersCount: {
+          ...state.correctAnswersCount,
+          [playerId]: state.correctAnswersCount[playerId] + 1,
+        },
+      }
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateNextQuestion(state: MathSprintState): ValidationResult {
+    if (state.gamePhase !== 'playing') {
+      return { valid: false, error: 'Game not in progress' }
+    }
+
+    if (!state.questionAnswered) {
+      return { valid: false, error: 'Current question not answered yet' }
+    }
+
+    const isLastQuestion = state.currentQuestionIndex >= state.questions.length - 1
+
+    if (isLastQuestion) {
+      // Game complete, go to results
+      const newState: MathSprintState = {
+        ...state,
+        gamePhase: 'results',
+      }
+      return { valid: true, newState }
+    }
+
+    // Move to next question
+    const newState: MathSprintState = {
+      ...state,
+      currentQuestionIndex: state.currentQuestionIndex + 1,
+      answers: [],
+      questionStartTime: Date.now(),
+      questionAnswered: false,
+      winnerId: null,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateResetGame(state: MathSprintState): ValidationResult {
+    const newState = this.getInitialState({
+      difficulty: state.difficulty,
+      questionsPerRound: state.questionsPerRound,
+      timePerQuestion: state.timePerQuestion,
+    })
+
+    return { valid: true, newState }
+  }
+
+  private validateSetConfig(
+    state: MathSprintState,
+    field: string,
+    value: any
+  ): ValidationResult {
+    if (state.gamePhase !== 'setup') {
+      return { valid: false, error: 'Cannot change config during game' }
+    }
+
+    const newState = {
+      ...state,
+      [field]: value,
+    }
+
+    return { valid: true, newState }
+  }
+
+  // ============================================================================
+  // Question Generation
+  // ============================================================================
+
+  private generateQuestions(difficulty: Difficulty, count: number): Question[] {
+    const questions: Question[] = []
+
+    for (let i = 0; i < count; i++) {
+      const operation = this.randomOperation()
+      const question = this.generateQuestion(difficulty, operation, `q-${i}`)
+      questions.push(question)
+    }
+
+    return questions
+  }
+
+  private generateQuestion(
+    difficulty: Difficulty,
+    operation: Operation,
+    id: string
+  ): Question {
+    let operand1: number
+    let operand2: number
+    let correctAnswer: number
+
+    switch (difficulty) {
+      case 'easy':
+        operand1 = this.randomInt(1, 10)
+        operand2 = this.randomInt(1, 10)
+        break
+      case 'medium':
+        operand1 = this.randomInt(10, 50)
+        operand2 = this.randomInt(1, 20)
+        break
+      case 'hard':
+        operand1 = this.randomInt(10, 100)
+        operand2 = this.randomInt(10, 50)
+        break
+    }
+
+    switch (operation) {
+      case 'addition':
+        correctAnswer = operand1 + operand2
+        break
+      case 'subtraction':
+        // Ensure positive result
+        if (operand1 < operand2) {
+          ;[operand1, operand2] = [operand2, operand1]
+        }
+        correctAnswer = operand1 - operand2
+        break
+      case 'multiplication':
+        // Smaller numbers for multiplication
+        if (difficulty === 'hard') {
+          operand1 = this.randomInt(2, 20)
+          operand2 = this.randomInt(2, 12)
+        } else {
+          operand1 = this.randomInt(2, 10)
+          operand2 = this.randomInt(2, 10)
+        }
+        correctAnswer = operand1 * operand2
+        break
+    }
+
+    const operationSymbol = this.getOperationSymbol(operation)
+    const displayText = `${operand1} ${operationSymbol} ${operand2} = ?`
+
+    return {
+      id,
+      operand1,
+      operand2,
+      operation,
+      correctAnswer,
+      displayText,
+    }
+  }
+
+  private randomOperation(): Operation {
+    const operations: Operation[] = ['addition', 'subtraction', 'multiplication']
+    return operations[Math.floor(Math.random() * operations.length)]
+  }
+
+  private randomInt(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min
+  }
+
+  private getOperationSymbol(operation: Operation): string {
+    switch (operation) {
+      case 'addition':
+        return '+'
+      case 'subtraction':
+        return '−'
+      case 'multiplication':
+        return '×'
+    }
+  }
+}
+
+export const mathSprintValidator = new MathSprintValidator()

apps/web/src/arcade-games/math-sprint/components/GameComponent.tsx

@@ -0,0 +1,40 @@
+/**
+ * Math Sprint - Game Component
+ *
+ * Main wrapper component with navigation and phase routing.
+ */
+
+'use client'
+
+import { useRouter } from 'next/navigation'
+import { PageWithNav } from '@/components/PageWithNav'
+import { useMathSprint } from '../Provider'
+import { PlayingPhase } from './PlayingPhase'
+import { ResultsPhase } from './ResultsPhase'
+import { SetupPhase } from './SetupPhase'
+
+export function GameComponent() {
+  const router = useRouter()
+  const { state, exitSession, resetGame } = useMathSprint()
+
+  return (
+    <PageWithNav
+      navTitle="Math Sprint"
+      navEmoji="🧮"
+      emphasizePlayerSelection={state.gamePhase === 'setup'}
+      // No currentPlayerId - free-for-all game, everyone can act simultaneously
+      playerScores={state.scores}
+      onExitSession={() => {
+        exitSession?.()
+        router.push('/arcade')
+      }}
+      onNewGame={() => {
+        resetGame()
+      }}
+    >
+      {state.gamePhase === 'setup' && <SetupPhase />}
+      {state.gamePhase === 'playing' && <PlayingPhase />}
+      {state.gamePhase === 'results' && <ResultsPhase />}
+    </PageWithNav>
+  )
+}

apps/web/src/arcade-games/math-sprint/components/PlayingPhase.tsx

@@ -0,0 +1,347 @@
+/**
+ * Math Sprint - Playing Phase
+ *
+ * Main gameplay: show question, accept answers, show feedback.
+ */
+
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useViewerId } from '@/lib/arcade/game-sdk'
+import { css } from '../../../../styled-system/css'
+import { useMathSprint } from '../Provider'
+
+export function PlayingPhase() {
+  const { state, submitAnswer, nextQuestion, lastError, clearError } = useMathSprint()
+  const { data: viewerId } = useViewerId()
+  const [inputValue, setInputValue] = useState('')
+
+  const currentQuestion = state.questions[state.currentQuestionIndex]
+  const progress = `${state.currentQuestionIndex + 1} / ${state.questions.length}`
+
+  // Find if current user answered
+  const myPlayerId = Object.keys(state.playerMetadata).find(
+    (pid) => state.playerMetadata[pid]?.userId === viewerId
+  )
+  const myAnswer = state.answers.find((a) => a.playerId === myPlayerId)
+
+  // Auto-clear error after 3 seconds
+  useEffect(() => {
+    if (lastError) {
+      const timeout = setTimeout(() => clearError(), 3000)
+      return () => clearTimeout(timeout)
+    }
+  }, [lastError, clearError])
+
+  // Clear input after question changes
+  useEffect(() => {
+    setInputValue('')
+  }, [state.currentQuestionIndex])
+
+  const handleSubmit = () => {
+    const answer = Number.parseInt(inputValue, 10)
+    if (Number.isNaN(answer)) return
+
+    submitAnswer(answer)
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter') {
+      handleSubmit()
+    }
+  }
+
+  return (
+    <div
+      className={css({
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '24px',
+        maxWidth: '700px',
+        margin: '0 auto',
+        padding: '32px 20px',
+      })}
+    >
+      {/* Progress Bar */}
+      <div
+        className={css({
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '16px',
+        })}
+      >
+        <div
+          className={css({
+            display: 'flex',
+            justifyContent: 'space-between',
+            alignItems: 'center',
+            marginBottom: '8px',
+          })}
+        >
+          <span className={css({ fontSize: 'sm', fontWeight: 'semibold' })}>Question {progress}</span>
+          <span className={css({ fontSize: 'sm', color: 'gray.600' })}>
+            {state.difficulty.charAt(0).toUpperCase() + state.difficulty.slice(1)}
+          </span>
+        </div>
+        <div
+          className={css({
+            background: 'gray.200',
+            height: '8px',
+            borderRadius: '4px',
+            overflow: 'hidden',
+          })}
+        >
+          <div
+            className={css({
+              background: 'linear-gradient(90deg, #a78bfa, #8b5cf6)',
+              height: '100%',
+              borderRadius: '4px',
+              transition: 'width 0.3s',
+            })}
+            style={{
+              width: `${((state.currentQuestionIndex + 1) / state.questions.length) * 100}%`,
+            }}
+          />
+        </div>
+      </div>
+
+      {/* Error Banner */}
+      {lastError && (
+        <div
+          className={css({
+            background: 'linear-gradient(135deg, #fef2f2, #fee2e2)',
+            border: '2px solid',
+            borderColor: 'red.300',
+            borderRadius: '12px',
+            padding: '12px 16px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+          })}
+        >
+          <div className={css({ display: 'flex', alignItems: 'center', gap: '8px' })}>
+            <span>⚠️</span>
+            <span className={css({ fontSize: 'sm', color: 'red.700' })}>{lastError}</span>
+          </div>
+          <button
+            type="button"
+            onClick={clearError}
+            className={css({
+              fontSize: 'xs',
+              padding: '4px 8px',
+              background: 'red.100',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer',
+              _hover: { background: 'red.200' },
+            })}
+          >
+            Dismiss
+          </button>
+        </div>
+      )}
+
+      {/* Question Display */}
+      <div
+        className={css({
+          background: 'linear-gradient(135deg, #ede9fe, #ddd6fe)',
+          border: '2px solid',
+          borderColor: 'purple.300',
+          borderRadius: '16px',
+          padding: '48px',
+          textAlign: 'center',
+        })}
+      >
+        <div
+          className={css({
+            fontSize: '4xl',
+            fontWeight: 'bold',
+            color: 'purple.700',
+            fontFamily: 'monospace',
+          })}
+        >
+          {currentQuestion.displayText}
+        </div>
+      </div>
+
+      {/* Answer Input */}
+      {!state.questionAnswered && (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: myAnswer ? 'gray.300' : 'purple.500',
+            borderRadius: '12px',
+            padding: '24px',
+          })}
+        >
+          {myAnswer ? (
+            <div className={css({ textAlign: 'center' })}>
+              <div
+                className={css({
+                  fontSize: 'lg',
+                  color: 'gray.600',
+                  marginBottom: '8px',
+                })}
+              >
+                Your answer: <strong>{myAnswer.answer}</strong>
+              </div>
+              <div className={css({ fontSize: 'sm', color: 'gray.500' })}>
+                Waiting for others or correct answer...
+              </div>
+            </div>
+          ) : (
+            <div>
+              <label
+                className={css({
+                  display: 'block',
+                  fontSize: 'sm',
+                  fontWeight: 'semibold',
+                  marginBottom: '8px',
+                })}
+              >
+                Your Answer
+              </label>
+              <div className={css({ display: 'flex', gap: '12px' })}>
+                <input
+                  type="number"
+                  value={inputValue}
+                  onChange={(e) => setInputValue(e.target.value)}
+                  onKeyDown={handleKeyDown}
+                  placeholder="Type your answer..."
+                  autoFocus
+                  className={css({
+                    flex: 1,
+                    padding: '12px 16px',
+                    fontSize: 'lg',
+                    border: '2px solid',
+                    borderColor: 'gray.300',
+                    borderRadius: '8px',
+                    _focus: {
+                      outline: 'none',
+                      borderColor: 'purple.500',
+                    },
+                  })}
+                />
+                <button
+                  type="button"
+                  onClick={handleSubmit}
+                  disabled={!inputValue}
+                  className={css({
+                    padding: '12px 24px',
+                    fontSize: 'md',
+                    fontWeight: 'semibold',
+                    color: 'white',
+                    background: inputValue ? 'purple.600' : 'gray.400',
+                    border: 'none',
+                    borderRadius: '8px',
+                    cursor: inputValue ? 'pointer' : 'not-allowed',
+                    _hover: {
+                      background: inputValue ? 'purple.700' : 'gray.400',
+                    },
+                  })}
+                >
+                  Submit
+                </button>
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Winner Display */}
+      {state.questionAnswered && state.winnerId && (
+        <div
+          className={css({
+            background: 'linear-gradient(135deg, #d1fae5, #a7f3d0)',
+            border: '2px solid',
+            borderColor: 'green.400',
+            borderRadius: '12px',
+            padding: '24px',
+            textAlign: 'center',
+          })}
+        >
+          <div className={css({ fontSize: '3xl', marginBottom: '8px' })}>🎉</div>
+          <div className={css({ fontSize: 'lg', fontWeight: 'bold', color: 'green.700' })}>
+            {state.playerMetadata[state.winnerId]?.name || 'Someone'} got it right!
+          </div>
+          <div className={css({ fontSize: 'md', color: 'green.600', marginTop: '4px' })}>
+            Answer: {currentQuestion.correctAnswer}
+          </div>
+
+          <button
+            type="button"
+            onClick={nextQuestion}
+            className={css({
+              marginTop: '16px',
+              padding: '12px 32px',
+              fontSize: 'md',
+              fontWeight: 'semibold',
+              color: 'white',
+              background: 'green.600',
+              border: 'none',
+              borderRadius: '8px',
+              cursor: 'pointer',
+              _hover: { background: 'green.700' },
+            })}
+          >
+            Next Question →
+          </button>
+        </div>
+      )}
+
+      {/* Scoreboard */}
+      <div
+        className={css({
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '16px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'sm',
+            fontWeight: 'semibold',
+            marginBottom: '12px',
+          })}
+        >
+          Scores
+        </h3>
+        <div className={css({ display: 'flex', flexDirection: 'column', gap: '8px' })}>
+          {Object.entries(state.scores)
+            .sort(([, a], [, b]) => b - a)
+            .map(([playerId, score]) => {
+              const player = state.playerMetadata[playerId]
+              return (
+                <div
+                  key={playerId}
+                  className={css({
+                    display: 'flex',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                    padding: '8px 12px',
+                    background: 'gray.50',
+                    borderRadius: '8px',
+                  })}
+                >
+                  <div className={css({ display: 'flex', alignItems: 'center', gap: '8px' })}>
+                    <span className={css({ fontSize: 'xl' })}>{player?.emoji}</span>
+                    <span className={css({ fontSize: 'sm', fontWeight: 'medium' })}>
+                      {player?.name}
+                    </span>
+                  </div>
+                  <span className={css({ fontSize: 'sm', fontWeight: 'bold', color: 'purple.600' })}>
+                    {score} pts
+                  </span>
+                </div>
+              )
+            })}
+        </div>
+      </div>
+    </div>
+  )
+}

apps/web/src/arcade-games/math-sprint/components/ResultsPhase.tsx

@@ -0,0 +1,194 @@
+/**
+ * Math Sprint - Results Phase
+ *
+ * Show final scores and winner.
+ */
+
+'use client'
+
+import { css } from '../../../../styled-system/css'
+import { useMathSprint } from '../Provider'
+
+export function ResultsPhase() {
+  const { state, resetGame } = useMathSprint()
+
+  // Sort players by score
+  const sortedPlayers = Object.entries(state.scores)
+    .map(([playerId, score]) => ({
+      playerId,
+      score,
+      correct: state.correctAnswersCount[playerId] || 0,
+      player: state.playerMetadata[playerId],
+    }))
+    .sort((a, b) => b.score - a.score)
+
+  const winner = sortedPlayers[0]
+
+  return (
+    <div
+      className={css({
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '24px',
+        maxWidth: '600px',
+        margin: '0 auto',
+        padding: '32px 20px',
+      })}
+    >
+      {/* Winner Announcement */}
+      <div
+        className={css({
+          background: 'linear-gradient(135deg, #fef3c7, #fde68a)',
+          border: '2px solid',
+          borderColor: 'yellow.400',
+          borderRadius: '16px',
+          padding: '32px',
+          textAlign: 'center',
+        })}
+      >
+        <div className={css({ fontSize: '4xl', marginBottom: '12px' })}>🏆</div>
+        <h2
+          className={css({
+            fontSize: '2xl',
+            fontWeight: 'bold',
+            color: 'yellow.800',
+            marginBottom: '8px',
+          })}
+        >
+          {winner.player?.name} Wins!
+        </h2>
+        <div className={css({ fontSize: 'lg', color: 'yellow.700' })}>
+          {winner.score} points • {winner.correct} correct
+        </div>
+      </div>
+
+      {/* Final Scores */}
+      <div
+        className={css({
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '24px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'lg',
+            fontWeight: 'semibold',
+            marginBottom: '16px',
+          })}
+        >
+          Final Scores
+        </h3>
+        <div className={css({ display: 'flex', flexDirection: 'column', gap: '12px' })}>
+          {sortedPlayers.map((item, index) => (
+            <div
+              key={item.playerId}
+              className={css({
+                display: 'flex',
+                alignItems: 'center',
+                gap: '12px',
+                padding: '16px',
+                background: index === 0 ? 'linear-gradient(135deg, #fef3c7, #fde68a)' : 'gray.50',
+                border: '1px solid',
+                borderColor: index === 0 ? 'yellow.300' : 'gray.200',
+                borderRadius: '12px',
+              })}
+            >
+              {/* Rank */}
+              <div
+                className={css({
+                  width: '32px',
+                  height: '32px',
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  background: index === 0 ? 'yellow.500' : 'gray.300',
+                  color: index === 0 ? 'white' : 'gray.700',
+                  borderRadius: '50%',
+                  fontWeight: 'bold',
+                  fontSize: 'sm',
+                })}
+              >
+                {index + 1}
+              </div>
+
+              {/* Player Info */}
+              <div className={css({ flex: 1 })}>
+                <div className={css({ display: 'flex', alignItems: 'center', gap: '8px' })}>
+                  <span className={css({ fontSize: 'xl' })}>{item.player?.emoji}</span>
+                  <span className={css({ fontSize: 'md', fontWeight: 'semibold' })}>
+                    {item.player?.name}
+                  </span>
+                </div>
+                <div className={css({ fontSize: 'xs', color: 'gray.600', marginTop: '2px' })}>
+                  {item.correct} / {state.questions.length} correct
+                </div>
+              </div>
+
+              {/* Score */}
+              <div
+                className={css({
+                  fontSize: 'xl',
+                  fontWeight: 'bold',
+                  color: index === 0 ? 'yellow.700' : 'purple.600',
+                })}
+              >
+                {item.score}
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* Stats */}
+      <div
+        className={css({
+          background: 'linear-gradient(135deg, #ede9fe, #ddd6fe)',
+          border: '1px solid',
+          borderColor: 'purple.300',
+          borderRadius: '12px',
+          padding: '20px',
+        })}
+      >
+        <div className={css({ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '16px' })}>
+          <div className={css({ textAlign: 'center' })}>
+            <div className={css({ fontSize: '2xl', fontWeight: 'bold', color: 'purple.700' })}>
+              {state.questions.length}
+            </div>
+            <div className={css({ fontSize: 'sm', color: 'purple.600' })}>Questions</div>
+          </div>
+          <div className={css({ textAlign: 'center' })}>
+            <div className={css({ fontSize: '2xl', fontWeight: 'bold', color: 'purple.700' })}>
+              {state.difficulty.charAt(0).toUpperCase() + state.difficulty.slice(1)}
+            </div>
+            <div className={css({ fontSize: 'sm', color: 'purple.600' })}>Difficulty</div>
+          </div>
+        </div>
+      </div>
+
+      {/* Play Again Button */}
+      <button
+        type="button"
+        onClick={resetGame}
+        className={css({
+          padding: '14px 28px',
+          fontSize: 'lg',
+          fontWeight: 'semibold',
+          color: 'white',
+          background: 'purple.600',
+          border: 'none',
+          borderRadius: '12px',
+          cursor: 'pointer',
+          transition: 'background 0.2s',
+          _hover: {
+            background: 'purple.700',
+          },
+        })}
+      >
+        Play Again
+      </button>
+    </div>
+  )
+}

apps/web/src/arcade-games/math-sprint/components/SetupPhase.tsx

@@ -0,0 +1,196 @@
+/**
+ * Math Sprint - Setup Phase
+ *
+ * Configure game settings before starting.
+ */
+
+'use client'
+
+import { css } from '../../../../styled-system/css'
+import { useMathSprint } from '../Provider'
+import type { Difficulty } from '../types'
+
+export function SetupPhase() {
+  const { state, startGame, setConfig } = useMathSprint()
+
+  const handleDifficultyChange = (difficulty: Difficulty) => {
+    setConfig('difficulty', difficulty)
+  }
+
+  const handleQuestionsChange = (questions: number) => {
+    setConfig('questionsPerRound', questions)
+  }
+
+  return (
+    <div
+      className={css({
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '24px',
+        maxWidth: '600px',
+        margin: '0 auto',
+        padding: '32px 20px',
+      })}
+    >
+      {/* Game Title */}
+      <div className={css({ textAlign: 'center' })}>
+        <h1
+          className={css({
+            fontSize: '2xl',
+            fontWeight: 'bold',
+            color: 'purple.700',
+            marginBottom: '8px',
+          })}
+        >
+          🧮 Math Sprint
+        </h1>
+        <p className={css({ color: 'gray.600' })}>
+          Race to solve math problems! First correct answer wins points.
+        </p>
+      </div>
+
+      {/* Settings Card */}
+      <div
+        className={css({
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '24px',
+        })}
+      >
+        <h2
+          className={css({
+            fontSize: 'lg',
+            fontWeight: 'semibold',
+            marginBottom: '16px',
+          })}
+        >
+          Game Settings
+        </h2>
+
+        {/* Difficulty */}
+        <div className={css({ marginBottom: '20px' })}>
+          <label
+            className={css({
+              display: 'block',
+              fontSize: 'sm',
+              fontWeight: 'medium',
+              marginBottom: '8px',
+            })}
+          >
+            Difficulty
+          </label>
+          <div className={css({ display: 'flex', gap: '8px' })}>
+            {(['easy', 'medium', 'hard'] as Difficulty[]).map((diff) => (
+              <button
+                key={diff}
+                type="button"
+                onClick={() => handleDifficultyChange(diff)}
+                className={css({
+                  flex: 1,
+                  padding: '10px 16px',
+                  borderRadius: '8px',
+                  border: '2px solid',
+                  borderColor: state.difficulty === diff ? 'purple.500' : 'gray.300',
+                  background: state.difficulty === diff ? 'purple.50' : 'white',
+                  color: state.difficulty === diff ? 'purple.700' : 'gray.700',
+                  fontWeight: state.difficulty === diff ? 'semibold' : 'normal',
+                  cursor: 'pointer',
+                  transition: 'all 0.2s',
+                  _hover: {
+                    borderColor: 'purple.400',
+                  },
+                })}
+              >
+                {diff.charAt(0).toUpperCase() + diff.slice(1)}
+              </button>
+            ))}
+          </div>
+          <p className={css({ fontSize: 'xs', color: 'gray.500', marginTop: '4px' })}>
+            {state.difficulty === 'easy' && 'Numbers 1-10, simple operations'}
+            {state.difficulty === 'medium' && 'Numbers 1-50, varied operations'}
+            {state.difficulty === 'hard' && 'Numbers 1-100, harder calculations'}
+          </p>
+        </div>
+
+        {/* Questions Per Round */}
+        <div>
+          <label
+            className={css({
+              display: 'block',
+              fontSize: 'sm',
+              fontWeight: 'medium',
+              marginBottom: '8px',
+            })}
+          >
+            Questions: {state.questionsPerRound}
+          </label>
+          <input
+            type="range"
+            min="5"
+            max="20"
+            step="5"
+            value={state.questionsPerRound}
+            onChange={(e) => handleQuestionsChange(Number(e.target.value))}
+            className={css({
+              width: '100%',
+            })}
+          />
+          <div className={css({ display: 'flex', justifyContent: 'space-between', fontSize: 'xs' })}>
+            <span>5</span>
+            <span>10</span>
+            <span>15</span>
+            <span>20</span>
+          </div>
+        </div>
+      </div>
+
+      {/* Instructions */}
+      <div
+        className={css({
+          background: 'linear-gradient(135deg, #fef3c7, #fde68a)',
+          border: '1px solid',
+          borderColor: 'yellow.300',
+          borderRadius: '12px',
+          padding: '16px',
+        })}
+      >
+        <h3 className={css({ fontSize: 'sm', fontWeight: 'semibold', marginBottom: '8px' })}>
+          How to Play
+        </h3>
+        <ul className={css({ fontSize: 'sm', color: 'gray.700', paddingLeft: '20px' })}>
+          <li>Solve math problems as fast as you can</li>
+          <li>First correct answer earns 10 points</li>
+          <li>Everyone can answer at the same time</li>
+          <li>Most points wins!</li>
+        </ul>
+      </div>
+
+      {/* Start Button */}
+      <button
+        type="button"
+        onClick={startGame}
+        disabled={state.activePlayers.length < 2}
+        className={css({
+          padding: '14px 28px',
+          fontSize: 'lg',
+          fontWeight: 'semibold',
+          color: 'white',
+          background: state.activePlayers.length < 2 ? 'gray.400' : 'purple.600',
+          borderRadius: '12px',
+          border: 'none',
+          cursor: state.activePlayers.length < 2 ? 'not-allowed' : 'pointer',
+          transition: 'all 0.2s',
+          _hover: {
+            background: state.activePlayers.length < 2 ? 'gray.400' : 'purple.700',
+          },
+        })}
+      >
+        {state.activePlayers.length < 2
+          ? `Need ${2 - state.activePlayers.length} more player(s)`
+          : 'Start Game'}
+      </button>
+    </div>
+  )
+}

apps/web/src/arcade-games/math-sprint/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Math Sprint Game Definition
+ *
+ * A free-for-all math game demonstrating the TEAM_MOVE pattern.
+ * Players race to solve math problems - first correct answer wins points.
+ */
+
+import { defineGame } from '@/lib/arcade/game-sdk'
+import type { GameManifest } from '@/lib/arcade/game-sdk'
+import { GameComponent } from './components/GameComponent'
+import { MathSprintProvider } from './Provider'
+import type { MathSprintConfig, MathSprintMove, MathSprintState } from './types'
+import { mathSprintValidator } from './Validator'
+
+const manifest: GameManifest = {
+  name: 'math-sprint',
+  displayName: 'Math Sprint',
+  icon: '🧮',
+  description: 'Race to solve math problems!',
+  longDescription:
+    'A fast-paced free-for-all game where players compete to solve math problems. First correct answer earns points. Choose your difficulty and test your mental math skills!',
+  maxPlayers: 8,
+  difficulty: 'Beginner',
+  chips: ['👥 Multiplayer', '⚡ Fast-Paced', '🧠 Mental Math'],
+  color: 'purple',
+  gradient: 'linear-gradient(135deg, #ddd6fe, #c4b5fd)',
+  borderColor: 'purple.200',
+  available: true,
+}
+
+const defaultConfig: MathSprintConfig = {
+  difficulty: 'medium',
+  questionsPerRound: 10,
+  timePerQuestion: 30,
+}
+
+export const mathSprintGame = defineGame<MathSprintConfig, MathSprintState, MathSprintMove>({
+  manifest,
+  Provider: MathSprintProvider,
+  GameComponent,
+  validator: mathSprintValidator,
+  defaultConfig,
+})

apps/web/src/arcade-games/math-sprint/types.ts

@@ -0,0 +1,120 @@
+/**
+ * Math Sprint Game Types
+ *
+ * A free-for-all game where players race to solve math problems.
+ * Demonstrates the TEAM_MOVE pattern (no specific turn owner).
+ */
+
+import type { GameConfig, GameMove, GameState } from '@/lib/arcade/game-sdk'
+
+/**
+ * Difficulty levels for math problems
+ */
+export type Difficulty = 'easy' | 'medium' | 'hard'
+
+/**
+ * Math operation types
+ */
+export type Operation = 'addition' | 'subtraction' | 'multiplication'
+
+/**
+ * Game configuration (persisted to database)
+ */
+export interface MathSprintConfig extends GameConfig {
+  difficulty: Difficulty
+  questionsPerRound: number
+  timePerQuestion: number // seconds
+}
+
+/**
+ * A math question
+ */
+export interface Question {
+  id: string
+  operand1: number
+  operand2: number
+  operation: Operation
+  correctAnswer: number
+  displayText: string // e.g., "5 + 3 = ?"
+}
+
+/**
+ * Player answer submission
+ */
+export interface Answer {
+  playerId: string
+  answer: number
+  timestamp: number
+  correct: boolean
+}
+
+/**
+ * Game state (synchronized across all clients)
+ */
+export interface MathSprintState extends GameState {
+  gamePhase: 'setup' | 'playing' | 'results'
+  activePlayers: string[]
+  playerMetadata: Record<string, { name: string; emoji: string; color: string; userId: string }>
+
+  // Configuration
+  difficulty: Difficulty
+  questionsPerRound: number
+  timePerQuestion: number
+
+  // Game progress
+  currentQuestionIndex: number
+  questions: Question[]
+
+  // Scoring
+  scores: Record<string, number> // playerId -> score
+  correctAnswersCount: Record<string, number> // playerId -> count
+
+  // Current question state
+  answers: Answer[] // All answers for current question
+  questionStartTime: number // Timestamp when question was shown
+  questionAnswered: boolean // True if someone got it right
+  winnerId: string | null // Winner of current question (first correct)
+}
+
+/**
+ * Move types for Math Sprint
+ */
+export type MathSprintMove =
+  | StartGameMove
+  | SubmitAnswerMove
+  | NextQuestionMove
+  | ResetGameMove
+  | SetConfigMove
+
+export interface StartGameMove extends GameMove {
+  type: 'START_GAME'
+  data: {
+    activePlayers: string[]
+    playerMetadata: Record<string, unknown>
+  }
+}
+
+export interface SubmitAnswerMove extends GameMove {
+  type: 'SUBMIT_ANSWER'
+  data: {
+    answer: number
+  }
+}
+
+export interface NextQuestionMove extends GameMove {
+  type: 'NEXT_QUESTION'
+  data: Record<string, never>
+}
+
+export interface ResetGameMove extends GameMove {
+  type: 'RESET_GAME'
+  data: Record<string, never>
+}
+
+export interface SetConfigMove extends GameMove {
+  type: 'SET_CONFIG'
+  data: {
+    field: 'difficulty' | 'questionsPerRound' | 'timePerQuestion'
+    value: Difficulty | number
+  }
+}

apps/web/src/arcade-games/number-guesser/Provider.tsx

@@ -22,12 +22,14 @@ import type { NumberGuesserState } from './types'
  */
 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
 }
 
@@ -62,7 +64,7 @@ export function NumberGuesserProvider({ children }: { children: ReactNode }) {
   const { activePlayers: activePlayerIds, players } = useGameMode()
   const { mutate: updateGameConfig } = useUpdateGameConfig()
 
-  // Get active players as array
+  // Get active players as array (keep Set iteration order to match UI display)
   const activePlayers = Array.from(activePlayerIds)
 
   // Merge saved config from room
@@ -90,12 +92,13 @@ export function NumberGuesserProvider({ children }: { children: ReactNode }) {
   }, [roomData?.gameConfig])
 
   // Arcade session integration
-  const { state, sendMove, exitSession } = useArcadeSession<NumberGuesserState>({
-    userId: viewerId || '',
-    roomId: roomData?.id,
-    initialState,
-    applyMove: applyMoveOptimistically,
-  })
+  const { state, sendMove, exitSession, lastError, clearError } =
+    useArcadeSession<NumberGuesserState>({
+      userId: viewerId || '',
+      roomId: roomData?.id,
+      initialState,
+      applyMove: applyMoveOptimistically,
+    })
 
   // Action creators
   const startGame = useCallback(() => {
@@ -195,12 +198,14 @@ export function NumberGuesserProvider({ children }: { children: ReactNode }) {
 
   const contextValue: NumberGuesserContextValue = {
     state,
+    lastError,
     startGame,
     chooseNumber,
     makeGuess,
     nextRound,
     goToSetup,
     setConfig,
+    clearError,
     exitSession,
   }
 

apps/web/src/arcade-games/number-guesser/Validator.ts

@@ -14,10 +14,17 @@ export class NumberGuesserValidator
         return this.validateStartGame(state, move.data.activePlayers, move.data.playerMetadata)
 
       case 'CHOOSE_NUMBER':
-        return this.validateChooseNumber(state, move.data.secretNumber, move.playerId)
+        // 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':
-        return this.validateMakeGuess(state, move.data.guess, move.playerId, move.data.playerName)
+        // 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)
@@ -26,7 +33,8 @@ export class NumberGuesserValidator
         return this.validateGoToSetup(state)
 
       case 'SET_CONFIG':
-        return this.validateSetConfig(state, move.data.field, move.data.value)
+        // 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 {
@@ -88,6 +96,12 @@ export class NumberGuesserValidator
       }
     }
 
+    // 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
@@ -128,7 +142,17 @@ export class NumberGuesserValidator
       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,
@@ -181,8 +205,16 @@ export class NumberGuesserValidator
   }
 
   private validateNextRound(state: NumberGuesserState): ValidationResult {
-    if (state.gamePhase !== 'guessing' || !state.winner) {
-      return { valid: false, error: 'Cannot start next round yet' }
+    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

apps/web/src/arcade-games/number-guesser/components/GameComponent.tsx

@@ -17,11 +17,21 @@ 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')

apps/web/src/arcade-games/number-guesser/components/GuessingPhase.tsx

@@ -4,13 +4,13 @@
 
 'use client'
 
-import { useState } from 'react'
+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 } = useNumberGuesser()
+  const { state, makeGuess, nextRound, lastError, clearError } = useNumberGuesser()
   const { data: viewerId } = useViewerId()
   const [inputValue, setInputValue] = useState('')
 
@@ -21,6 +21,14 @@ export function GuessingPhase() {
   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
@@ -84,6 +92,81 @@ export function GuessingPhase() {
         </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

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', 'number-guesser'],
+    enum: ['matching', 'memory-quiz', 'complement-race', 'number-guesser', 'math-sprint'],
   }),
   gameConfig: text('game_config', { mode: 'json' }), // Game-specific settings (nullable when no game selected)
 

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', 'number-guesser'],
+    enum: ['matching', 'memory-quiz', 'complement-race', 'number-guesser', 'math-sprint'],
   }).notNull(),
 
   gameUrl: text('game_url').notNull(), // e.g., '/arcade/matching'

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', 'number-guesser'],
+      enum: ['matching', 'memory-quiz', 'complement-race', 'number-guesser', 'math-sprint'],
     }).notNull(),
 
     // Game-specific configuration JSON
@@ -28,6 +28,8 @@ export const roomGameConfigs = sqliteTable(
     // - matching: { gameType, difficulty, turnTimer }
     // - memory-quiz: { selectedCount, displayTime, selectedDifficulty, playMode }
     // - complement-race: TBD
+    // - number-guesser: { minNumber, maxNumber, roundsToWin }
+    // - math-sprint: { difficulty, questionsPerRound, timePerQuestion }
     config: text('config', { mode: 'json' }).notNull(),
 
     // Timestamps

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,
   }
 }

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,
   }
 }

apps/web/src/lib/arcade/game-config-helpers.ts

@@ -15,6 +15,7 @@ import {
   DEFAULT_MEMORY_QUIZ_CONFIG,
   DEFAULT_COMPLEMENT_RACE_CONFIG,
   DEFAULT_NUMBER_GUESSER_CONFIG,
+  DEFAULT_MATH_SPRINT_CONFIG,
 } from './game-configs'
 
 /**
@@ -36,6 +37,8 @@ function getDefaultGameConfig(gameName: ExtendedGameName): GameConfigByName[Exte
       return DEFAULT_COMPLEMENT_RACE_CONFIG
     case 'number-guesser':
       return DEFAULT_NUMBER_GUESSER_CONFIG
+    case 'math-sprint':
+      return DEFAULT_MATH_SPRINT_CONFIG
     default:
       throw new Error(`Unknown game: ${gameName}`)
   }
@@ -215,6 +218,18 @@ export function validateGameConfig(gameName: ExtendedGameName, config: any): boo
         config.roundsToWin >= 1
       )
 
+    case 'math-sprint':
+      return (
+        typeof config === 'object' &&
+        config !== null &&
+        ['easy', 'medium', 'hard'].includes(config.difficulty) &&
+        typeof config.questionsPerRound === 'number' &&
+        typeof config.timePerQuestion === 'number' &&
+        config.questionsPerRound >= 5 &&
+        config.questionsPerRound <= 20 &&
+        config.timePerQuestion >= 10
+      )
+
     default:
       return false
   }

apps/web/src/lib/arcade/game-configs.ts

@@ -11,6 +11,7 @@
 
 import type { DifficultyLevel } from '@/app/arcade/memory-quiz/types'
 import type { Difficulty, GameType } from '@/app/games/matching/context/types'
+import type { Difficulty as MathSprintDifficulty } from '@/arcade-games/math-sprint/types'
 
 /**
  * Configuration for matching (memory pairs) game
@@ -49,6 +50,15 @@ export interface NumberGuesserGameConfig {
   roundsToWin: number
 }
 
+/**
+ * Configuration for math-sprint game
+ */
+export interface MathSprintGameConfig {
+  difficulty: MathSprintDifficulty
+  questionsPerRound: number
+  timePerQuestion: number
+}
+
 /**
  * Union type of all game configs for type-safe access
  */
@@ -57,6 +67,7 @@ export type GameConfigByName = {
   'memory-quiz': MemoryQuizGameConfig
   'complement-race': ComplementRaceGameConfig
   'number-guesser': NumberGuesserGameConfig
+  'math-sprint': MathSprintGameConfig
 }
 
 /**
@@ -68,6 +79,7 @@ export interface RoomGameConfig {
   'memory-quiz'?: MemoryQuizGameConfig
   'complement-race'?: ComplementRaceGameConfig
   'number-guesser'?: NumberGuesserGameConfig
+  'math-sprint'?: MathSprintGameConfig
 }
 
 /**
@@ -95,3 +107,9 @@ export const DEFAULT_NUMBER_GUESSER_CONFIG: NumberGuesserGameConfig = {
   maxNumber: 100,
   roundsToWin: 3,
 }
+
+export const DEFAULT_MATH_SPRINT_CONFIG: MathSprintGameConfig = {
+  difficulty: 'medium',
+  questionsPerRound: 10,
+  timePerQuestion: 30,
+}

apps/web/src/lib/arcade/game-registry.ts

@@ -107,5 +107,7 @@ export function clearRegistry(): void {
 // ============================================================================
 
 import { numberGuesserGame } from '@/arcade-games/number-guesser'
+import { mathSprintGame } from '@/arcade-games/math-sprint'
 
 registerGame(numberGuesserGame)
+registerGame(mathSprintGame)

apps/web/src/lib/arcade/validators.ts

@@ -13,6 +13,7 @@
 import { matchingGameValidator } from './validation/MatchingGameValidator'
 import { memoryQuizGameValidator } from './validation/MemoryQuizGameValidator'
 import { numberGuesserValidator } from '@/arcade-games/number-guesser/Validator'
+import { mathSprintValidator } from '@/arcade-games/math-sprint/Validator'
 import type { GameValidator } from './validation/types'
 
 /**
@@ -24,6 +25,7 @@ export const validatorRegistry = {
   matching: matchingGameValidator,
   'memory-quiz': memoryQuizGameValidator,
   'number-guesser': numberGuesserValidator,
+  'math-sprint': mathSprintValidator,
   // Add new games here - GameName type will auto-update
 } as const
 
@@ -65,4 +67,9 @@ export function getRegisteredGameNames(): GameName[] {
 /**
  * Re-export validators for backwards compatibility
  */
-export { matchingGameValidator, memoryQuizGameValidator, numberGuesserValidator }
+export {
+  matchingGameValidator,
+  memoryQuizGameValidator,
+  numberGuesserValidator,
+  mathSprintValidator,
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "soroban-monorepo",
-  "version": "3.22.2",
+  "version": "3.23.0",
   "private": true,
   "description": "Beautiful Soroban Flashcard Generator - Monorepo",
   "workspaces": [