chore(release): 3.19.0 [skip ci]

## [3.19.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.18.1...v3.19.0) (2025-10-15)

### Features

* implement avatar-themed name generation with probabilistic mixing ([76a8472](76a8472f12))

CHANGELOG.md

@@ -1,3 +1,48 @@
+## [3.19.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.18.1...v3.19.0) (2025-10-15)
+
+
+### Features
+
+* implement avatar-themed name generation with probabilistic mixing ([76a8472](https://github.com/antialias/soroban-abacus-flashcards/commit/76a8472f12d251071b97f2288f62f0b358576232))
+
+## [3.18.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.18.0...v3.18.1) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade:** prevent empty update in settings API when only gameConfig changes ([ffb626f](https://github.com/antialias/soroban-abacus-flashcards/commit/ffb626f4038fd32d0f40dba8d83ae4d881d698d0))
+
+## [3.18.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.14...v3.18.0) (2025-10-15)
+
+
+### Features
+
+* add drizzle migration for room_game_configs table ([3bae00b](https://github.com/antialias/soroban-abacus-flashcards/commit/3bae00b9a9dc925039a02fe07d036a2fc5e0fb79))
+
+
+### Documentation
+
+* document manual migration of room_game_configs table ([ff79140](https://github.com/antialias/soroban-abacus-flashcards/commit/ff791409cf4bae1a5df43eb974eacbc7612d8eec))
+
+## [3.17.14](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.13...v3.17.14) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade:** resolve TypeScript errors in game config helpers ([04c9944](https://github.com/antialias/soroban-abacus-flashcards/commit/04c9944f2ed1025f5a4ece61761889edd08cc60d))
+
+
+### Documentation
+
+* **arcade:** update GAME_SETTINGS_PERSISTENCE.md for new schema ([260bdc2](https://github.com/antialias/soroban-abacus-flashcards/commit/260bdc2e9d458cb42a96d3ed36a18134260b4520))
+
+## [3.17.13](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.12...v3.17.13) (2025-10-15)
+
+
+### Code Refactoring
+
+* **arcade:** migrate game settings to normalized database schema ([1bd7354](https://github.com/antialias/soroban-abacus-flashcards/commit/1bd73544df6d62416961eea0b358955aaf82b79d))
+
 ## [3.17.12](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.11...v3.17.12) (2025-10-15)
 
 

apps/web/.claude/GAME_SETTINGS_PERSISTENCE.md

@@ -2,115 +2,279 @@
 
 ## Overview
 
-Game settings in room mode persist across game switches using a nested gameConfig structure. This document describes the architecture and common pitfalls.
+Game settings in room mode persist across game switches using a normalized database schema. Settings for each game are stored in a dedicated `room_game_configs` table with one row per game per room.
 
-## Data Structure
+## Database Schema
 
-Settings are stored in the `arcadeRooms` table's `gameConfig` column with this structure:
+Settings are stored in the `room_game_configs` table:
 
-```typescript
+```sql
+CREATE TABLE room_game_configs (
+  id TEXT PRIMARY KEY,
+  room_id TEXT NOT NULL REFERENCES arcade_rooms(id) ON DELETE CASCADE,
+  game_name TEXT NOT NULL CHECK(game_name IN ('matching', 'memory-quiz', 'complement-race')),
+  config TEXT NOT NULL,  -- JSON
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(room_id, game_name)
+);
+```
+
+**Benefits:**
+- ✅ Type-safe config access with shared types
+- ✅ Smaller rows (only configs for games that have been used)
+- ✅ Easier updates (single row vs entire JSON blob)
+- ✅ Better concurrency (no lock contention between games)
+- ✅ Foundation for per-game audit trail
+- ✅ Can query/index individual game settings
+
+**Example Row:**
+```json
 {
-  "matching": {
-    "gameType": "complement-pairs",
-    "difficulty": 15,
-    "turnTimer": 60
-  },
-  "memory-quiz": {
+  "id": "clxyz123",
+  "room_id": "room_abc",
+  "game_name": "memory-quiz",
+  "config": {
     "selectedCount": 8,
     "displayTime": 3.0,
     "selectedDifficulty": "medium",
     "playMode": "competitive"
+  },
+  "created_at": 1234567890,
+  "updated_at": 1234567890
+}
+```
+
+## Shared Type System
+
+All game configs are defined in `src/lib/arcade/game-configs.ts`:
+
+```typescript
+// Shared config types (single source of truth)
+export interface MatchingGameConfig {
+  gameType: 'abacus-numeral' | 'complement-pairs'
+  difficulty: number
+  turnTimer: number
+}
+
+export interface MemoryQuizGameConfig {
+  selectedCount: 2 | 5 | 8 | 12 | 15
+  displayTime: number
+  selectedDifficulty: DifficultyLevel
+  playMode: 'cooperative' | 'competitive'
+}
+
+// Default configs
+export const DEFAULT_MATCHING_CONFIG: MatchingGameConfig = {
+  gameType: 'abacus-numeral',
+  difficulty: 6,
+  turnTimer: 30,
+}
+
+export const DEFAULT_MEMORY_QUIZ_CONFIG: MemoryQuizGameConfig = {
+  selectedCount: 5,
+  displayTime: 2.0,
+  selectedDifficulty: 'easy',
+  playMode: 'cooperative',
+}
+```
+
+**Why This Matters:**
+- TypeScript enforces that validators, helpers, and API routes all use the same types
+- Adding a new setting requires changes in only ONE place (the type definition)
+- Impossible to forget a setting or use wrong type
+
+## Critical Components
+
+Settings persistence requires coordination between FOUR systems:
+
+### 1. Helper Functions
+**Location:** `src/lib/arcade/game-config-helpers.ts`
+
+**Responsibilities:**
+- Read/write game configs from `room_game_configs` table
+- Provide type-safe access with automatic defaults
+- Validate configs at runtime
+
+**Key Functions:**
+```typescript
+// Get config with defaults (type-safe)
+const config = await getGameConfig(roomId, 'memory-quiz')
+// Returns: MemoryQuizGameConfig
+
+// Set/update config (upsert)
+await setGameConfig(roomId, 'memory-quiz', {
+  playMode: 'competitive',
+  selectedCount: 8,
+})
+
+// Get all game configs for a room
+const allConfigs = await getAllGameConfigs(roomId)
+// Returns: { matching?: MatchingGameConfig, 'memory-quiz'?: MemoryQuizGameConfig }
+```
+
+### 2. API Routes
+**Location:**
+- `src/app/api/arcade/rooms/current/route.ts` (read)
+- `src/app/api/arcade/rooms/[roomId]/settings/route.ts` (write)
+
+**Responsibilities:**
+- Aggregate game configs from database
+- Return them to client in `room.gameConfig`
+- Write config updates to `room_game_configs` table
+
+**Read Example:** `GET /api/arcade/rooms/current`
+```typescript
+const gameConfig = await getAllGameConfigs(roomId)
+
+return NextResponse.json({
+  room: {
+    ...room,
+    gameConfig, // Aggregated from room_game_configs table
+  },
+  members,
+  memberPlayers,
+})
+```
+
+**Write Example:** `PATCH /api/arcade/rooms/[roomId]/settings`
+```typescript
+if (body.gameConfig !== undefined) {
+  // body.gameConfig: { matching: {...}, memory-quiz: {...} }
+  for (const [gameName, config] of Object.entries(body.gameConfig)) {
+    await setGameConfig(roomId, gameName, config)
   }
 }
 ```
 
-**Key Points:**
-- Settings are **nested by game name** (`matching`, `memory-quiz`, etc.)
-- Each game has its own isolated settings object
-- This allows switching games without losing settings
+### 3. Socket Server (Session Creation)
+**Location:** `src/socket-server.ts:70-90`
 
-## Critical Components
+**Responsibilities:**
+- Create initial arcade session when user joins room
+- Read saved settings using `getGameConfig()` helper
+- Pass settings to validator's `getInitialState()`
 
-Settings persistence requires coordination between THREE systems:
+**Example:**
+```typescript
+const room = await getRoomById(roomId)
+const validator = getValidator(room.gameName as GameName)
 
-### 1. Client-Side Provider
+// Get config from database (type-safe, includes defaults)
+const gameConfig = await getGameConfig(roomId, room.gameName as GameName)
+
+// Pass to validator (types match automatically)
+const initialState = validator.getInitialState(gameConfig)
+
+await createArcadeSession({ userId, gameName, initialState, roomId })
+```
+
+**Key Point:** No more manual config extraction or default fallbacks!
+
+### 4. Game Validators
+**Location:** `src/lib/arcade/validation/*Validator.ts`
+
+**Responsibilities:**
+- Define `getInitialState()` method with shared config type
+- Create initial game state from config
+- TypeScript enforces all settings are handled
+
+**Example:** `MemoryQuizGameValidator.ts`
+```typescript
+import type { MemoryQuizGameConfig } from '@/lib/arcade/game-configs'
+
+class MemoryQuizGameValidator {
+  getInitialState(config: MemoryQuizGameConfig): SorobanQuizState {
+    return {
+      selectedCount: config.selectedCount,
+      displayTime: config.displayTime,
+      selectedDifficulty: config.selectedDifficulty,
+      playMode: config.playMode,  // TypeScript ensures this field exists!
+      // ...other state
+    }
+  }
+}
+```
+
+### 5. Client Providers (Unchanged)
 **Location:** `src/app/arcade/{game}/context/Room{Game}Provider.tsx`
 
 **Responsibilities:**
-- Load saved settings from `roomData.gameConfig[gameName]`
-- Merge saved settings with `initialState` defaults
-- Save settings changes to database via `updateGameConfig`
+- Read settings from `roomData.gameConfig[gameName]`
+- Merge with `initialState` defaults
+- Works transparently with new backend structure
 
-**Example:** `RoomMemoryQuizProvider.tsx:211-247`
+**Example:** `RoomMemoryQuizProvider.tsx:211-233`
 ```typescript
 const mergedInitialState = useMemo(() => {
   const gameConfig = roomData?.gameConfig as Record<string, any>
   const savedConfig = gameConfig?.['memory-quiz']
 
+  if (!savedConfig) {
+    return initialState
+  }
+
   return {
     ...initialState,
-    selectedCount: savedConfig?.selectedCount ?? initialState.selectedCount,
-    displayTime: savedConfig?.displayTime ?? initialState.displayTime,
-    selectedDifficulty: savedConfig?.selectedDifficulty ?? initialState.selectedDifficulty,
-    playMode: savedConfig?.playMode ?? initialState.playMode,
+    selectedCount: savedConfig.selectedCount ?? initialState.selectedCount,
+    displayTime: savedConfig.displayTime ?? initialState.displayTime,
+    selectedDifficulty: savedConfig.selectedDifficulty ?? initialState.selectedDifficulty,
+    playMode: savedConfig.playMode ?? initialState.playMode,
   }
 }, [roomData?.gameConfig])
 ```
 
-### 2. Socket Server (Session Creation)
-**Location:** `src/socket-server.ts:86-125`
+## Common Bugs and Solutions
 
-**Responsibilities:**
-- Create initial arcade session when user joins room
-- Read saved settings from `room.gameConfig[gameName]`
-- Pass settings to validator's `getInitialState()`
+### Bug #1: Settings Not Persisting
+**Symptom:** Settings reset to defaults after game switch
 
-**Example:** `socket-server.ts:94-110`
-```typescript
-const memoryQuizConfig = (room.gameConfig as any)?.['memory-quiz'] || {}
-initialState = validator.getInitialState({
-  selectedCount: memoryQuizConfig.selectedCount || 5,
-  displayTime: memoryQuizConfig.displayTime || 2.0,
-  selectedDifficulty: memoryQuizConfig.selectedDifficulty || 'easy',
-  playMode: memoryQuizConfig.playMode || 'cooperative',
-})
+**Root Cause:** One of the following:
+1. API route not writing to `room_game_configs` table
+2. Helper function not being used correctly
+3. Validator not using shared config type
+
+**Solution:** Verify the data flow:
+```bash
+# 1. Check database write
+SELECT * FROM room_game_configs WHERE room_id = '...';
+
+# 2. Check API logs for setGameConfig() calls
+# Look for: [GameConfig] Updated {game} config for room {roomId}
+
+# 3. Check socket server logs for getGameConfig() calls
+# Look for: [join-arcade-session] Got validator for: {game}
+
+# 4. Check validator signature matches shared type
+# MemoryQuizGameValidator.getInitialState(config: MemoryQuizGameConfig)
 ```
 
-### 3. Game Validator
-**Location:** `src/lib/arcade/validation/{Game}Validator.ts`
+### Bug #2: TypeScript Errors About Missing Fields
+**Symptom:** `Property '{field}' is missing in type ...`
 
-**Responsibilities:**
-- Define `getInitialState()` method that creates initial game state
-- Accept ALL game settings as parameters
-- Use provided values or fall back to defaults
+**Root Cause:** Validator's `getInitialState()` signature doesn't match shared config type
 
-**Example:** `MemoryQuizGameValidator.ts:404-442`
+**Solution:** Import and use the shared config type:
 ```typescript
+// ❌ WRONG
 getInitialState(config: {
   selectedCount: number
   displayTime: number
-  selectedDifficulty: DifficultyLevel
-  playMode?: 'cooperative' | 'competitive'  // ← Must include ALL settings!
-}): SorobanQuizState {
-  return {
-    // ...
-    selectedCount: config.selectedCount,
-    displayTime: config.displayTime,
-    selectedDifficulty: config.selectedDifficulty,
-    playMode: config.playMode || 'cooperative',  // ← Use config value!
-  }
-}
+  // Missing playMode!
+}): SorobanQuizState
+
+// ✅ CORRECT
+import type { MemoryQuizGameConfig } from '@/lib/arcade/game-configs'
+
+getInitialState(config: MemoryQuizGameConfig): SorobanQuizState
 ```
 
-## Common Bugs and Solutions
+### Bug #3: Settings Wiped When Returning to Game Selection
+**Symptom:** Settings reset when going back to game selection
 
-### Bug #1: Settings Wiped When Returning to Game Selection
+**Root Cause:** Sending `gameConfig: null` in PATCH request
 
-**Symptom:** Settings reset to defaults after going back to game selection
-
-**Root Cause:** `clearRoomGameApi` was sending `gameConfig: null`
-
-**Solution:** Only send `gameName: null`, don't send `gameConfig` at all
+**Solution:** Only send `gameName: null`, don't touch gameConfig:
 ```typescript
 // ❌ WRONG
 body: JSON.stringify({ gameName: null, gameConfig: null })
@@ -119,106 +283,76 @@ body: JSON.stringify({ gameName: null, gameConfig: null })
 body: JSON.stringify({ gameName: null })
 ```
 
-**Fixed in:** `useRoomData.ts:638-654`
-
-### Bug #2: Settings Not Loaded from Database
-
-**Symptom:** Session always uses default settings, ignoring saved values
-
-**Root Cause:** Socket server reading from wrong level of nesting
-
-**Example Problem:**
-```typescript
-// ❌ WRONG - reads from root level
-const gameType = room.gameConfig.gameType  // undefined!
-
-// ✅ CORRECT - reads from nested game config
-const matchingConfig = room.gameConfig.matching
-const gameType = matchingConfig.gameType
-```
-
-**Fixed in:** `socket-server.ts:86-125`
-
-### Bug #3: Validator Ignores Setting
-
-**Symptom:** Specific setting always resets to default (e.g., playMode always "cooperative")
-
-**Root Cause:** Validator's `getInitialState()` config parameter missing the setting
-
-**How to Diagnose:**
-1. Check validator's `getInitialState()` TypeScript signature
-2. Ensure ALL game settings are included as parameters
-3. Ensure settings use `config.{setting}` not hardcoded values
-
-**Example Problem:**
-```typescript
-// ❌ WRONG - playMode not in config type
-getInitialState(config: {
-  selectedCount: number
-  displayTime: number
-  selectedDifficulty: DifficultyLevel
-}): SorobanQuizState {
-  return {
-    playMode: 'cooperative',  // ← Hardcoded!
-  }
-}
-
-// ✅ CORRECT - playMode in config type and used
-getInitialState(config: {
-  selectedCount: number
-  displayTime: number
-  selectedDifficulty: DifficultyLevel
-  playMode?: 'cooperative' | 'competitive'
-}): SorobanQuizState {
-  return {
-    playMode: config.playMode || 'cooperative',  // ← Uses config!
-  }
-}
-```
-
-**Fixed in:** `MemoryQuizGameValidator.ts:404-442`
-
 ## Debugging Checklist
 
 When a setting doesn't persist:
 
 1. **Check database:**
-   - Add logging in `/api/arcade/rooms/[roomId]/settings/route.ts`
-   - Verify setting is saved to `gameConfig[gameName]`
+   - Query `room_game_configs` table
+   - Verify row exists for room + game
+   - Verify JSON config has correct structure
 
-2. **Check socket server:**
-   - Add logging in `socket-server.ts` join-arcade-session handler
-   - Verify `room.gameConfig[gameName].{setting}` is read correctly
-   - Verify setting is passed to `validator.getInitialState()`
-   - Verify `initialState.{setting}` has correct value after getInitialState()
+2. **Check API write path:**
+   - `/api/arcade/rooms/[roomId]/settings` logs
+   - Verify `setGameConfig()` is called
+   - Check for errors in console
 
-3. **Check validator:**
-   - Verify `getInitialState()` config parameter includes the setting
-   - Verify setting uses `config.{setting}` not a hardcoded value
-   - Add logging to see what config is received and what state is returned
+3. **Check API read path:**
+   - `/api/arcade/rooms/current` logs
+   - Verify `getAllGameConfigs()` returns data
+   - Check `room.gameConfig` in response
 
-4. **Check client provider:**
-   - Add logging in `Room{Game}Provider.tsx` mergedInitialState useMemo
-   - Verify `roomData.gameConfig[gameName].{setting}` is read correctly
-   - Verify merged state includes the saved value
+4. **Check socket server:**
+   - `socket-server.ts` logs for `getGameConfig()`
+   - Verify config passed to validator
+   - Check `initialState` has correct values
+
+5. **Check validator:**
+   - Signature uses shared config type
+   - All config fields used (not hardcoded)
+   - Add logging to see received config
 
 ## Adding a New Setting
 
 To add a new setting to an existing game:
 
-1. **Update the game's state type** (`types.ts`)
-2. **Update the Provider** (`Room{Game}Provider.tsx`):
-   - Add to `mergedInitialState` useMemo
-   - Add to `setConfig` function
-   - Add to `updateGameConfig` call
-3. **Update the Validator** (`{Game}Validator.ts`):
-   - Add to `getInitialState()` config parameter type
-   - Add to returned state object, using `config.{setting}`
-   - Add validation case in `validateSetConfig()`
-4. **Update Socket Server** (`socket-server.ts`):
-   - Add to `{game}Config` extraction
-   - Add to `getInitialState()` call
-5. **Update the UI component** to expose the setting
+1. **Update the shared config type** (`game-configs.ts`):
+```typescript
+export interface MemoryQuizGameConfig {
+  selectedCount: 2 | 5 | 8 | 12 | 15
+  displayTime: number
+  selectedDifficulty: DifficultyLevel
+  playMode: 'cooperative' | 'competitive'
+  newSetting: string  // ← Add here
+}
+
+export const DEFAULT_MEMORY_QUIZ_CONFIG: MemoryQuizGameConfig = {
+  selectedCount: 5,
+  displayTime: 2.0,
+  selectedDifficulty: 'easy',
+  playMode: 'cooperative',
+  newSetting: 'default',  // ← Add default
+}
+```
+
+2. **TypeScript will now enforce:**
+   - ✅ Validator must accept `newSetting` (compile error if missing)
+   - ✅ Helper functions will include it automatically
+   - ✅ Client providers will need to handle it
+
+3. **Update the validator** (`*Validator.ts`):
+```typescript
+getInitialState(config: MemoryQuizGameConfig): SorobanQuizState {
+  return {
+    // ...
+    newSetting: config.newSetting,  // TypeScript enforces this
+  }
+}
+```
+
+4. **Update the UI** to expose the new setting
+   - No changes needed to API routes or helper functions!
+   - They automatically handle any field in the config type
 
 ## Testing Settings Persistence
 
@@ -228,10 +362,60 @@ Manual test procedure:
 2. Change each setting to a non-default value
 3. Go back to game selection (gameName becomes null)
 4. Select the same game again
-5. Verify ALL settings retained their values
+5. **Verify ALL settings retained their values**
 
 **Expected behavior:** All settings should be exactly as you left them.
 
-## Refactoring Recommendations
+## Migration Notes
 
-See next section for suggested improvements to prevent these bugs.
+**Old Schema:**
+- Settings stored in `arcade_rooms.game_config` JSON column
+- Config stored directly for currently selected game only
+- Config lost when switching games
+
+**New Schema:**
+- Settings stored in `room_game_configs` table
+- One row per game per room
+- Unique constraint on (room_id, game_name)
+- Configs persist when switching between games
+
+**Migration:** See `.claude/MANUAL_MIGRATION_0011.md` for complete details
+
+**Summary:**
+- Manual migration applied on 2025-10-15
+- Created `room_game_configs` table via sqlite3 CLI
+- Migrated 6000 existing configs (5991 matching, 9 memory-quiz)
+- Table created directly instead of through drizzle migration system
+
+**Rollback Plan:**
+- Old `game_config` column still exists in `arcade_rooms` table
+- Old data preserved (was only read, not deleted)
+- Can revert to reading from old column if needed
+- New table can be dropped: `DROP TABLE room_game_configs`
+
+## Architecture Benefits
+
+**Type Safety:**
+- Single source of truth for config types
+- TypeScript enforces consistency everywhere
+- Impossible to forget a setting
+
+**DRY (Don't Repeat Yourself):**
+- No duplicated default values
+- No manual config extraction
+- No manual merging with defaults
+
+**Maintainability:**
+- Adding a setting touches fewer places
+- Clear separation of concerns
+- Easier to trace data flow
+
+**Performance:**
+- Smaller database rows
+- Better query performance
+- Less network payload
+
+**Correctness:**
+- Runtime validation available
+- Database constraints (unique index)
+- Impossible to create duplicate configs

apps/web/.claude/MANUAL_MIGRATION_0011.md

@@ -0,0 +1,120 @@
+# Manual Migration: room_game_configs Table
+
+**Date:** 2025-10-15
+**Migration:** Create `room_game_configs` table (equivalent to drizzle migration 0011)
+
+## Context
+
+This migration was applied manually using sqlite3 CLI instead of through drizzle-kit's migration system, because the interactive prompt from `drizzle-kit push` cannot be automated in the deployment pipeline.
+
+## What Was Done
+
+### 1. Created Table
+
+```sql
+CREATE TABLE IF NOT EXISTS room_game_configs (
+  id TEXT PRIMARY KEY NOT NULL,
+  room_id TEXT NOT NULL,
+  game_name TEXT NOT NULL,
+  config TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (room_id) REFERENCES arcade_rooms(id) ON UPDATE NO ACTION ON DELETE CASCADE
+);
+```
+
+### 2. Created Index
+
+```sql
+CREATE UNIQUE INDEX IF NOT EXISTS room_game_idx ON room_game_configs (room_id, game_name);
+```
+
+### 3. Migrated Existing Data
+
+Migrated 6000 game configs from the old `arcade_rooms.game_config` column to the new normalized table:
+
+```sql
+INSERT OR IGNORE INTO room_game_configs (id, room_id, game_name, config, created_at, updated_at)
+SELECT
+  lower(hex(randomblob(16))) as id,
+  id as room_id,
+  game_name,
+  game_config as config,
+  created_at,
+  last_activity as updated_at
+FROM arcade_rooms
+WHERE game_config IS NOT NULL
+  AND game_name IS NOT NULL;
+```
+
+**Results:**
+- 5991 matching game configs migrated
+- 9 memory-quiz game configs migrated
+- Total: 6000 configs
+
+## Old vs New Schema
+
+**Old Schema:**
+- `arcade_rooms.game_config` (TEXT/JSON) - stored config for currently selected game only
+- Config was lost when switching games
+
+**New Schema:**
+- `room_game_configs` table - one row per game per room
+- Unique constraint on (room_id, game_name)
+- Configs persist when switching between games
+
+## Verification
+
+```bash
+# Verify table exists
+sqlite3 data/sqlite.db ".tables" | grep room_game_configs
+
+# Verify schema
+sqlite3 data/sqlite.db ".schema room_game_configs"
+
+# Count migrated data
+sqlite3 data/sqlite.db "SELECT COUNT(*) FROM room_game_configs;"
+# Expected: 6000
+
+# Check data distribution
+sqlite3 data/sqlite.db "SELECT game_name, COUNT(*) FROM room_game_configs GROUP BY game_name;"
+# Expected: matching: 5991, memory-quiz: 9
+```
+
+## Related Files
+
+This migration supports the refactoring documented in:
+- `.claude/GAME_SETTINGS_PERSISTENCE.md` - Architecture documentation
+- `src/lib/arcade/game-configs.ts` - Shared config types
+- `src/lib/arcade/game-config-helpers.ts` - Database access helpers
+
+## Note on Drizzle Migration Tracking
+
+This migration was NOT recorded in drizzle's `__drizzle_migrations` table because it was applied manually. This is acceptable because:
+
+1. The schema definition exists in code (`src/db/schema/room-game-configs.ts`)
+2. The table was created with the exact schema drizzle would generate
+3. Future schema changes will go through proper drizzle migrations
+4. The `arcade_rooms.game_config` column is preserved for rollback safety
+
+## Rollback Plan
+
+If issues arise, the old system can be restored by:
+
+1. Reverting code changes (game-config-helpers.ts, API routes, validators)
+2. The old `game_config` column still exists in `arcade_rooms` table
+3. Data is still there (we only read from it, didn't delete it)
+
+The new `room_game_configs` table can be dropped if needed:
+
+```sql
+DROP TABLE IF EXISTS room_game_configs;
+```
+
+## Future Work
+
+Once this migration is stable in production:
+
+1. Consider dropping the old `arcade_rooms.game_config` column
+2. Add this migration to drizzle's migration journal for tracking (optional)
+3. Monitor for any issues with settings persistence

apps/web/.claude/settings.local.json

@@ -70,7 +70,10 @@
       "Bash(lsof:*)",
       "Bash(killall:*)",
       "Bash(echo:*)",
-      "Bash(git restore:*)"
+      "Bash(git restore:*)",
+      "Bash(timeout 10 npm run dev:*)",
+      "Bash(timeout 30 npm run dev)",
+      "Bash(pkill:*)"
     ],
     "deny": [],
     "ask": []

apps/web/drizzle/0011_add_room_game_configs.sql

@@ -0,0 +1,33 @@
+-- Create room_game_configs table for normalized game settings storage
+-- This migration is safe to run multiple times (uses IF NOT EXISTS)
+
+-- Create the table
+CREATE TABLE IF NOT EXISTS `room_game_configs` (
+	`id` text PRIMARY KEY NOT NULL,
+	`room_id` text NOT NULL,
+	`game_name` text NOT NULL,
+	`config` text NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL,
+	FOREIGN KEY (`room_id`) REFERENCES `arcade_rooms`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+
+-- Create unique index
+CREATE UNIQUE INDEX IF NOT EXISTS `room_game_idx` ON `room_game_configs` (`room_id`,`game_name`);
+--> statement-breakpoint
+
+-- Migrate existing game configs from arcade_rooms.game_config column
+-- This INSERT will only run if data hasn't been migrated yet
+INSERT OR IGNORE INTO room_game_configs (id, room_id, game_name, config, created_at, updated_at)
+SELECT
+  lower(hex(randomblob(16))) as id,
+  id as room_id,
+  game_name,
+  game_config as config,
+  created_at,
+  last_activity as updated_at
+FROM arcade_rooms
+WHERE game_config IS NOT NULL
+  AND game_name IS NOT NULL
+  AND game_name IN ('matching', 'memory-quiz', 'complement-race');

apps/web/drizzle/meta/_journal.json

@@ -78,6 +78,13 @@
       "when": 1760700000000,
       "tag": "0010_make_game_name_nullable",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1760800000000,
+      "tag": "0011_add_room_game_configs",
+      "breakpoints": true
     }
   ]
 }

apps/web/src/app/api/arcade/rooms/[roomId]/settings/route.ts

@@ -7,6 +7,8 @@ import { recordRoomMemberHistory } from '@/lib/arcade/room-member-history'
 import { getRoomMembers } from '@/lib/arcade/room-membership'
 import { getSocketIO } from '@/lib/socket-io'
 import { getViewerId } from '@/lib/viewer'
+import { getAllGameConfigs, setGameConfig } from '@/lib/arcade/game-config-helpers'
+import type { GameName } from '@/lib/arcade/validation'
 
 type RouteContext = {
   params: Promise<{ roomId: string }>
@@ -122,9 +124,16 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
       updateData.gameName = body.gameName
     }
 
-    // Update game config if provided
-    if (body.gameConfig !== undefined) {
-      updateData.gameConfig = body.gameConfig
+    // Handle game config updates - write to new room_game_configs table
+    if (body.gameConfig !== undefined && body.gameConfig !== null) {
+      // body.gameConfig is expected to be nested by game name: { matching: {...}, memory-quiz: {...} }
+      // Extract each game's config and write to the new table
+      for (const [gameName, config] of Object.entries(body.gameConfig)) {
+        if (config && typeof config === 'object') {
+          await setGameConfig(roomId, gameName as GameName, config)
+          console.log(`[Settings API] Wrote ${gameName} config to room_game_configs table`)
+        }
+      }
     }
 
     console.log(
@@ -139,19 +148,25 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
       await db.delete(schema.arcadeSessions).where(eq(schema.arcadeSessions.roomId, roomId))
     }
 
-    // Update room settings
-    const [updatedRoom] = await db
-      .update(schema.arcadeRooms)
-      .set(updateData)
-      .where(eq(schema.arcadeRooms.id, roomId))
-      .returning()
+    // Update room settings (only if there's something to update)
+    let updatedRoom = currentRoom
+    if (Object.keys(updateData).length > 0) {
+      ;[updatedRoom] = await db
+        .update(schema.arcadeRooms)
+        .set(updateData)
+        .where(eq(schema.arcadeRooms.id, roomId))
+        .returning()
+    }
+
+    // Get aggregated game configs from new table
+    const gameConfig = await getAllGameConfigs(roomId)
 
     console.log(
       '[Settings API] Room state in database AFTER update:',
       JSON.stringify(
         {
           gameName: updatedRoom.gameName,
-          gameConfig: updatedRoom.gameConfig,
+          gameConfig,
         },
         null,
         2
@@ -171,11 +186,7 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
           } = {
             roomId,
             gameName: body.gameName,
-          }
-
-          // Only include gameConfig if it was explicitly provided
-          if (body.gameConfig !== undefined) {
-            broadcastData.gameConfig = body.gameConfig
+            gameConfig, // Include aggregated configs from new table
           }
 
           io.to(`room:${roomId}`).emit('room-game-changed', broadcastData)
@@ -251,7 +262,15 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
       }
     }
 
-    return NextResponse.json({ room: updatedRoom }, { status: 200 })
+    return NextResponse.json(
+      {
+        room: {
+          ...updatedRoom,
+          gameConfig, // Include aggregated configs from new table
+        },
+      },
+      { status: 200 }
+    )
   } catch (error: any) {
     console.error('Failed to update room settings:', error)
     return NextResponse.json({ error: 'Failed to update room settings' }, { status: 500 })

apps/web/src/app/api/arcade/rooms/current/route.ts

@@ -4,6 +4,7 @@ import { getRoomById } from '@/lib/arcade/room-manager'
 import { getRoomMembers } from '@/lib/arcade/room-membership'
 import { getRoomActivePlayers } from '@/lib/arcade/player-manager'
 import { getViewerId } from '@/lib/viewer'
+import { getAllGameConfigs } from '@/lib/arcade/game-config-helpers'
 
 /**
  * GET /api/arcade/rooms/current
@@ -28,13 +29,16 @@ export async function GET() {
       return NextResponse.json({ error: 'Room not found' }, { status: 404 })
     }
 
+    // Get game configs from new room_game_configs table
+    const gameConfig = await getAllGameConfigs(roomId)
+
     console.log(
       '[Current Room API] Room data READ from database:',
       JSON.stringify(
         {
           roomId,
           gameName: room.gameName,
-          gameConfig: room.gameConfig,
+          gameConfig,
         },
         null,
         2
@@ -54,7 +58,10 @@ export async function GET() {
     }
 
     return NextResponse.json({
-      room,
+      room: {
+        ...room,
+        gameConfig, // Override with configs from new table
+      },
       members,
       memberPlayers: memberPlayersObj,
     })

apps/web/src/components/nav/PlayerConfigDialog.tsx

@@ -52,7 +52,7 @@ export function PlayerConfigDialog({ playerId, onClose }: PlayerConfigDialogProp
   const handleGenerateNewName = () => {
     const allPlayers = Array.from(players.values())
     const existingNames = allPlayers.filter((p) => p.id !== playerId).map((p) => p.name)
-    const newName = generateUniquePlayerName(existingNames)
+    const newName = generateUniquePlayerName(existingNames, player.emoji)
 
     setLocalName(newName)
     updatePlayer(playerId, { name: newName })

apps/web/src/contexts/GameModeContext.tsx

@@ -11,7 +11,7 @@ import {
 } from '@/hooks/useUserPlayers'
 import { useViewerId } from '@/hooks/useViewerId'
 import { getNextPlayerColor } from '../types/player'
-import { generateUniquePlayerName, generateUniquePlayerNames } from '../utils/playerNames'
+import { generateUniquePlayerName } from '../utils/playerNames'
 
 // Client-side Player type (compatible with old type)
 export interface Player {
@@ -141,8 +141,13 @@ export function GameModeProvider({ children }: { children: ReactNode }) {
   useEffect(() => {
     if (!isLoading && !isInitialized) {
       if (dbPlayers.length === 0) {
-        // Generate unique names for default players
-        const generatedNames = generateUniquePlayerNames(DEFAULT_PLAYER_CONFIGS.length)
+        // Generate unique names for default players, themed by their emoji
+        const existingNames: string[] = []
+        const generatedNames = DEFAULT_PLAYER_CONFIGS.map((config) => {
+          const name = generateUniquePlayerName(existingNames, config.emoji)
+          existingNames.push(name)
+          return name
+        })
 
         // Create default players with generated names
         DEFAULT_PLAYER_CONFIGS.forEach((config, index) => {
@@ -167,10 +172,11 @@ export function GameModeProvider({ children }: { children: ReactNode }) {
   const addPlayer = (playerData?: Partial<Player>) => {
     const playerList = Array.from(players.values())
     const existingNames = playerList.map((p) => p.name)
+    const emoji = playerData?.emoji ?? '🎮'
 
     const newPlayer = {
-      name: playerData?.name ?? generateUniquePlayerName(existingNames),
-      emoji: playerData?.emoji ?? '🎮',
+      name: playerData?.name ?? generateUniquePlayerName(existingNames, emoji),
+      emoji,
       color: playerData?.color ?? getNextPlayerColor(playerList),
       isActive: playerData?.isActive ?? false,
     }
@@ -254,8 +260,13 @@ export function GameModeProvider({ children }: { children: ReactNode }) {
       deletePlayer(player.id)
     })
 
-    // Generate unique names for default players
-    const generatedNames = generateUniquePlayerNames(DEFAULT_PLAYER_CONFIGS.length)
+    // Generate unique names for default players, themed by their emoji
+    const existingNames: string[] = []
+    const generatedNames = DEFAULT_PLAYER_CONFIGS.map((config) => {
+      const name = generateUniquePlayerName(existingNames, config.emoji)
+      existingNames.push(name)
+      return name
+    })
 
     // Create default players with generated names
     DEFAULT_PLAYER_CONFIGS.forEach((config, index) => {

apps/web/src/db/schema/index.ts

@@ -15,5 +15,6 @@ export * from './room-invitations'
 export * from './room-reports'
 export * from './room-bans'
 export * from './room-join-requests'
+export * from './room-game-configs'
 export * from './user-stats'
 export * from './users'

apps/web/src/db/schema/room-game-configs.ts

@@ -0,0 +1,48 @@
+import { createId } from '@paralleldrive/cuid2'
+import { integer, sqliteTable, text, uniqueIndex } from 'drizzle-orm/sqlite-core'
+import { arcadeRooms } from './arcade-rooms'
+
+/**
+ * Game-specific configuration settings for arcade rooms
+ * Each row represents one game's settings for one room
+ */
+export const roomGameConfigs = sqliteTable(
+  'room_game_configs',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => createId()),
+
+    // Room reference
+    roomId: text('room_id')
+      .notNull()
+      .references(() => arcadeRooms.id, { onDelete: 'cascade' }),
+
+    // Game identifier
+    gameName: text('game_name', {
+      enum: ['matching', 'memory-quiz', 'complement-race'],
+    }).notNull(),
+
+    // Game-specific configuration JSON
+    // Structure depends on gameName:
+    // - matching: { gameType, difficulty, turnTimer }
+    // - memory-quiz: { selectedCount, displayTime, selectedDifficulty, playMode }
+    // - complement-race: TBD
+    config: text('config', { mode: 'json' }).notNull(),
+
+    // Timestamps
+    createdAt: integer('created_at', { mode: 'timestamp' })
+      .notNull()
+      .$defaultFn(() => new Date()),
+    updatedAt: integer('updated_at', { mode: 'timestamp' })
+      .notNull()
+      .$defaultFn(() => new Date()),
+  },
+  (table) => ({
+    // Ensure only one config per game per room
+    uniqueRoomGame: uniqueIndex('room_game_idx').on(table.roomId, table.gameName),
+  })
+)
+
+export type RoomGameConfig = typeof roomGameConfigs.$inferSelect
+export type NewRoomGameConfig = typeof roomGameConfigs.$inferInsert

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

@@ -0,0 +1,200 @@
+/**
+ * Game configuration helpers
+ *
+ * Centralized functions for reading and writing game configs from the database.
+ * Uses the room_game_configs table (one row per game per room).
+ */
+
+import { and, eq } from 'drizzle-orm'
+import { createId } from '@paralleldrive/cuid2'
+import { db, schema } from '@/db'
+import type { GameName } from './validation'
+import type { GameConfigByName } from './game-configs'
+import {
+  DEFAULT_MATCHING_CONFIG,
+  DEFAULT_MEMORY_QUIZ_CONFIG,
+  DEFAULT_COMPLEMENT_RACE_CONFIG,
+} from './game-configs'
+
+/**
+ * Get default config for a game
+ */
+function getDefaultGameConfig(gameName: GameName): GameConfigByName[GameName] {
+  switch (gameName) {
+    case 'matching':
+      return DEFAULT_MATCHING_CONFIG
+    case 'memory-quiz':
+      return DEFAULT_MEMORY_QUIZ_CONFIG
+    case 'complement-race':
+      return DEFAULT_COMPLEMENT_RACE_CONFIG
+    default:
+      throw new Error(`Unknown game: ${gameName}`)
+  }
+}
+
+/**
+ * Get game-specific config from database with defaults
+ * Type-safe: returns the correct config type based on gameName
+ */
+export async function getGameConfig<T extends GameName>(
+  roomId: string,
+  gameName: T
+): Promise<GameConfigByName[T]> {
+  // Query the room_game_configs table for this specific room+game
+  const configRow = await db.query.roomGameConfigs.findFirst({
+    where: and(
+      eq(schema.roomGameConfigs.roomId, roomId),
+      eq(schema.roomGameConfigs.gameName, gameName)
+    ),
+  })
+
+  // If no config exists, return defaults
+  if (!configRow) {
+    return getDefaultGameConfig(gameName) as GameConfigByName[T]
+  }
+
+  // Merge saved config with defaults to handle missing fields
+  const defaults = getDefaultGameConfig(gameName)
+  return { ...defaults, ...(configRow.config as object) } as GameConfigByName[T]
+}
+
+/**
+ * Set (upsert) a game's config in the database
+ * Creates a new row if it doesn't exist, updates if it does
+ */
+export async function setGameConfig<T extends GameName>(
+  roomId: string,
+  gameName: T,
+  config: Partial<GameConfigByName[T]>
+): Promise<void> {
+  const now = new Date()
+
+  // Check if config already exists
+  const existing = await db.query.roomGameConfigs.findFirst({
+    where: and(
+      eq(schema.roomGameConfigs.roomId, roomId),
+      eq(schema.roomGameConfigs.gameName, gameName)
+    ),
+  })
+
+  if (existing) {
+    // Update existing config (merge with existing values)
+    const mergedConfig = { ...(existing.config as object), ...config }
+    await db
+      .update(schema.roomGameConfigs)
+      .set({
+        config: mergedConfig as any,
+        updatedAt: now,
+      })
+      .where(eq(schema.roomGameConfigs.id, existing.id))
+  } else {
+    // Insert new config (merge with defaults)
+    const defaults = getDefaultGameConfig(gameName)
+    const mergedConfig = { ...defaults, ...config }
+
+    await db.insert(schema.roomGameConfigs).values({
+      id: createId(),
+      roomId,
+      gameName,
+      config: mergedConfig as any,
+      createdAt: now,
+      updatedAt: now,
+    })
+  }
+
+  console.log(`[GameConfig] Updated ${gameName} config for room ${roomId}`)
+}
+
+/**
+ * Update a specific field in a game's config
+ * Convenience wrapper around setGameConfig
+ */
+export async function updateGameConfigField<
+  T extends GameName,
+  K extends keyof GameConfigByName[T],
+>(roomId: string, gameName: T, field: K, value: GameConfigByName[T][K]): Promise<void> {
+  // Create a partial config with just the field being updated
+  const partialConfig: Partial<GameConfigByName[T]> = {} as any
+  ;(partialConfig as any)[field] = value
+  await setGameConfig(roomId, gameName, partialConfig)
+}
+
+/**
+ * Delete a game's config from the database
+ * Useful when clearing game selection or cleaning up
+ */
+export async function deleteGameConfig(roomId: string, gameName: GameName): Promise<void> {
+  await db
+    .delete(schema.roomGameConfigs)
+    .where(
+      and(eq(schema.roomGameConfigs.roomId, roomId), eq(schema.roomGameConfigs.gameName, gameName))
+    )
+
+  console.log(`[GameConfig] Deleted ${gameName} config for room ${roomId}`)
+}
+
+/**
+ * Get all game configs for a room (all games)
+ * Returns a map of gameName -> config
+ */
+export async function getAllGameConfigs(
+  roomId: string
+): Promise<Partial<Record<GameName, unknown>>> {
+  const configs = await db.query.roomGameConfigs.findMany({
+    where: eq(schema.roomGameConfigs.roomId, roomId),
+  })
+
+  const result: Partial<Record<GameName, unknown>> = {}
+  for (const config of configs) {
+    result[config.gameName as GameName] = config.config
+  }
+
+  return result
+}
+
+/**
+ * Delete all game configs for a room
+ * Called when deleting a room (cascade should handle this, but useful for explicit cleanup)
+ */
+export async function deleteAllGameConfigs(roomId: string): Promise<void> {
+  await db.delete(schema.roomGameConfigs).where(eq(schema.roomGameConfigs.roomId, roomId))
+  console.log(`[GameConfig] Deleted all configs for room ${roomId}`)
+}
+
+/**
+ * Validate a game config at runtime
+ * Returns true if the config is valid for the given game
+ */
+export function validateGameConfig(gameName: GameName, config: any): boolean {
+  switch (gameName) {
+    case 'matching':
+      return (
+        typeof config === 'object' &&
+        config !== null &&
+        ['abacus-numeral', 'complement-pairs'].includes(config.gameType) &&
+        typeof config.difficulty === 'number' &&
+        [6, 8, 12, 15].includes(config.difficulty) &&
+        typeof config.turnTimer === 'number' &&
+        config.turnTimer >= 5 &&
+        config.turnTimer <= 300
+      )
+
+    case 'memory-quiz':
+      return (
+        typeof config === 'object' &&
+        config !== null &&
+        [2, 5, 8, 12, 15].includes(config.selectedCount) &&
+        typeof config.displayTime === 'number' &&
+        config.displayTime > 0 &&
+        ['beginner', 'easy', 'medium', 'hard', 'expert'].includes(config.selectedDifficulty) &&
+        ['cooperative', 'competitive'].includes(config.playMode)
+      )
+
+    case 'complement-race':
+      // TODO: Add validation when complement-race settings are defined
+      return typeof config === 'object' && config !== null
+
+    default:
+      return false
+  }
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Shared game configuration types
+ *
+ * This is the single source of truth for all game settings.
+ * These types are used across:
+ * - Database storage (room_game_configs table)
+ * - Validators (getInitialState method signatures)
+ * - Client providers (settings UI and state management)
+ * - Helper functions (reading/writing configs)
+ */
+
+import type { DifficultyLevel } from '@/app/arcade/memory-quiz/types'
+import type { Difficulty, GameType } from '@/app/games/matching/context/types'
+
+/**
+ * Configuration for matching (memory pairs) game
+ */
+export interface MatchingGameConfig {
+  gameType: GameType
+  difficulty: Difficulty
+  turnTimer: number
+}
+
+/**
+ * Configuration for memory-quiz (soroban lightning) game
+ */
+export interface MemoryQuizGameConfig {
+  selectedCount: 2 | 5 | 8 | 12 | 15
+  displayTime: number
+  selectedDifficulty: DifficultyLevel
+  playMode: 'cooperative' | 'competitive'
+}
+
+/**
+ * Configuration for complement-race game
+ * TODO: Define when implementing complement-race settings
+ */
+export interface ComplementRaceGameConfig {
+  // Future settings will go here
+  placeholder?: never
+}
+
+/**
+ * Union type of all game configs for type-safe access
+ */
+export type GameConfigByName = {
+  matching: MatchingGameConfig
+  'memory-quiz': MemoryQuizGameConfig
+  'complement-race': ComplementRaceGameConfig
+}
+
+/**
+ * Room's game configuration object (nested by game name)
+ * This matches the structure stored in room_game_configs table
+ */
+export interface RoomGameConfig {
+  matching?: MatchingGameConfig
+  'memory-quiz'?: MemoryQuizGameConfig
+  'complement-race'?: ComplementRaceGameConfig
+}
+
+/**
+ * Default configurations for each game
+ */
+export const DEFAULT_MATCHING_CONFIG: MatchingGameConfig = {
+  gameType: 'abacus-numeral',
+  difficulty: 6,
+  turnTimer: 30,
+}
+
+export const DEFAULT_MEMORY_QUIZ_CONFIG: MemoryQuizGameConfig = {
+  selectedCount: 5,
+  displayTime: 2.0,
+  selectedDifficulty: 'easy',
+  playMode: 'cooperative',
+}
+
+export const DEFAULT_COMPLEMENT_RACE_CONFIG: ComplementRaceGameConfig = {
+  // Future defaults will go here
+}

apps/web/src/lib/arcade/validation/MatchingGameValidator.ts

@@ -3,15 +3,10 @@
  * Validates all game moves and state transitions
  */
 
-import type {
-  Difficulty,
-  GameCard,
-  GameType,
-  MemoryPairsState,
-  Player,
-} from '@/app/games/matching/context/types'
+import type { GameCard, MemoryPairsState, Player } from '@/app/games/matching/context/types'
 import { generateGameCards } from '@/app/games/matching/utils/cardGeneration'
 import { canFlipCard, validateMatch } from '@/app/games/matching/utils/matchValidation'
+import type { MatchingGameConfig } from '@/lib/arcade/game-configs'
 import type { GameValidator, MatchingGameMove, ValidationResult } from './types'
 
 export class MatchingGameValidator implements GameValidator<MemoryPairsState, MatchingGameMove> {
@@ -536,11 +531,7 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
     return state.gamePhase === 'results' || state.matchedPairs === state.totalPairs
   }
 
-  getInitialState(config: {
-    difficulty: Difficulty
-    gameType: GameType
-    turnTimer: number
-  }): MemoryPairsState {
+  getInitialState(config: MatchingGameConfig): MemoryPairsState {
     return {
       cards: [],
       gameCards: [],

apps/web/src/lib/arcade/validation/MemoryQuizGameValidator.ts

@@ -3,7 +3,8 @@
  * Validates all game moves and state transitions
  */
 
-import type { DifficultyLevel, SorobanQuizState } from '@/app/arcade/memory-quiz/types'
+import type { SorobanQuizState } from '@/app/arcade/memory-quiz/types'
+import type { MemoryQuizGameConfig } from '@/lib/arcade/game-configs'
 import type {
   GameValidator,
   MemoryQuizGameMove,
@@ -395,12 +396,7 @@ export class MemoryQuizGameValidator
     return state.gamePhase === 'results'
   }
 
-  getInitialState(config: {
-    selectedCount: number
-    displayTime: number
-    selectedDifficulty: DifficultyLevel
-    playMode?: 'cooperative' | 'competitive'
-  }): SorobanQuizState {
+  getInitialState(config: MemoryQuizGameConfig): SorobanQuizState {
     return {
       cards: [],
       quizCards: [],

apps/web/src/socket-server.ts

@@ -15,6 +15,7 @@ import { getRoomMembers, getUserRooms, setMemberOnline } from './lib/arcade/room
 import { getRoomActivePlayers, getRoomPlayerIds } from './lib/arcade/player-manager'
 import type { GameMove, GameName } from './lib/arcade/validation'
 import { getValidator } from './lib/arcade/validation'
+import { getGameConfig } from './lib/arcade/game-config-helpers'
 
 // Use globalThis to store socket.io instance to avoid module isolation issues
 // This ensures the same instance is accessible across dynamic imports
@@ -81,29 +82,9 @@ export function initializeSocketServer(httpServer: HTTPServer) {
               const validator = getValidator(room.gameName as GameName)
               console.log('[join-arcade-session] Got validator for:', room.gameName)
 
-              // Different games have different initial configs
-              let initialState: any
-              if (room.gameName === 'matching') {
-                // Access nested gameConfig: { matching: { gameType, difficulty, turnTimer } }
-                const matchingConfig = (room.gameConfig as any)?.matching || {}
-                initialState = validator.getInitialState({
-                  difficulty: matchingConfig.difficulty || 6,
-                  gameType: matchingConfig.gameType || 'abacus-numeral',
-                  turnTimer: matchingConfig.turnTimer || 30,
-                })
-              } else if (room.gameName === 'memory-quiz') {
-                // Access nested gameConfig: { 'memory-quiz': { selectedCount, displayTime, selectedDifficulty, playMode } }
-                const memoryQuizConfig = (room.gameConfig as any)?.['memory-quiz'] || {}
-                initialState = validator.getInitialState({
-                  selectedCount: memoryQuizConfig.selectedCount || 5,
-                  displayTime: memoryQuizConfig.displayTime || 2.0,
-                  selectedDifficulty: memoryQuizConfig.selectedDifficulty || 'easy',
-                  playMode: memoryQuizConfig.playMode || 'cooperative',
-                })
-              } else {
-                // Fallback for other games
-                initialState = validator.getInitialState(room.gameConfig || {})
-              }
+              // Get game-specific config from database (type-safe)
+              const gameConfig = await getGameConfig(roomId, room.gameName as GameName)
+              const initialState = validator.getInitialState(gameConfig)
 
               session = await createArcadeSession({
                 userId,

apps/web/src/utils/__tests__/playerNames.test.ts

@@ -47,7 +47,7 @@ describe('playerNames', () => {
     it('should append number if all combinations are exhausted', () => {
       // Create a mock with limited attempts
       const existingNames = ['Swift Ninja']
-      const name = generateUniquePlayerName(existingNames, 1)
+      const name = generateUniquePlayerName(existingNames, undefined, 1)
 
       // Should either be unique or have a number appended
       expect(name).toBeTruthy()

apps/web/src/utils/playerNames.ts

@@ -1,8 +1,19 @@
 /**
  * Fun automatic player name generation system
  * Generates creative names by combining adjectives with nouns/roles
+ *
+ * Supports avatar-specific theming! Each emoji can have its own personality-matched words.
+ * Falls back gracefully: emoji-specific → category → generic abacus theme
  */
 
+import {
+  EMOJI_SPECIFIC_WORDS,
+  EMOJI_TO_THEME,
+  THEMED_WORD_LISTS,
+  type ThemedWordList,
+} from './themedWords'
+
+// Generic abacus-themed words (used as ultimate fallback)
 const ADJECTIVES = [
   // Abacus-themed adjectives
   'Ancient',
@@ -114,32 +125,115 @@ const NOUNS = [
 ]
 
 /**
- * Generate a random player name by combining an adjective and noun
+ * Get themed word list for an emoji avatar using probabilistic tier selection
+ * Strongly prefers emoji-specific (70%), then category (20%), then global (10%)
+ * This adds variety while maintaining personality-matched theming
  */
-export function generatePlayerName(): string {
-  const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)]
-  const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)]
+function getThemedWordsForEmoji(emoji: string): ThemedWordList {
+  // Collect available tiers
+  const availableTiers: Array<{ weight: number; words: ThemedWordList }> = []
+
+  // Emoji-specific tier (70% preference)
+  const emojiSpecific = EMOJI_SPECIFIC_WORDS[emoji]
+  if (emojiSpecific) {
+    availableTiers.push({ weight: 70, words: emojiSpecific })
+  }
+
+  // Category tier (20% preference)
+  const category = EMOJI_TO_THEME[emoji]
+  if (category) {
+    const categoryTheme = THEMED_WORD_LISTS[category]
+    if (categoryTheme) {
+      availableTiers.push({ weight: 20, words: categoryTheme })
+    }
+  }
+
+  // Global abacus tier (10% preference)
+  availableTiers.push({ weight: 10, words: { adjectives: ADJECTIVES, nouns: NOUNS } })
+
+  // Weighted random selection
+  const totalWeight = availableTiers.reduce((sum, tier) => sum + tier.weight, 0)
+  let random = Math.random() * totalWeight
+
+  for (const tier of availableTiers) {
+    random -= tier.weight
+    if (random <= 0) {
+      return tier.words
+    }
+  }
+
+  // Fallback (should never reach here)
+  return { adjectives: ADJECTIVES, nouns: NOUNS }
+}
+
+/**
+ * Generate a random player name by combining an adjective and noun
+ * Optionally themed based on avatar emoji for ultra-personalized names!
+ * Uses probabilistic tier selection and cross-tier mixing for abacus flavor
+ *
+ * @param emoji - Optional emoji avatar to theme the name around
+ * @returns A creative player name like "Grinning Calculator" or "Lightning Abacist"
+ */
+export function generatePlayerName(emoji?: string): string {
+  if (!emoji) {
+    // No emoji provided, use pure abacus theme
+    const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)]
+    const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)]
+    return `${adjective} ${noun}`
+  }
+
+  // Get themed words using probabilistic tier selection
+  const themedWords = getThemedWordsForEmoji(emoji)
+  const abacusWords = { adjectives: ADJECTIVES, nouns: NOUNS }
+
+  // 60% chance: Use themed words for both adjective and noun
+  // 30% chance: Mix themed adjective with abacus noun (infuses abacus flavor)
+  // 10% chance: Mix abacus adjective with themed noun (infuses abacus flavor)
+  const mixStrategy = Math.random()
+
+  let adjective: string
+  let noun: string
+
+  if (mixStrategy < 0.6) {
+    // Pure themed
+    adjective = themedWords.adjectives[Math.floor(Math.random() * themedWords.adjectives.length)]
+    noun = themedWords.nouns[Math.floor(Math.random() * themedWords.nouns.length)]
+  } else if (mixStrategy < 0.9) {
+    // Themed adjective + abacus noun
+    adjective = themedWords.adjectives[Math.floor(Math.random() * themedWords.adjectives.length)]
+    noun = abacusWords.nouns[Math.floor(Math.random() * abacusWords.nouns.length)]
+  } else {
+    // Abacus adjective + themed noun
+    adjective = abacusWords.adjectives[Math.floor(Math.random() * abacusWords.adjectives.length)]
+    noun = themedWords.nouns[Math.floor(Math.random() * themedWords.nouns.length)]
+  }
+
   return `${adjective} ${noun}`
 }
 
 /**
  * Generate a unique player name that doesn't conflict with existing players
  * @param existingNames - Array of names already in use
+ * @param emoji - Optional emoji avatar to theme the name around
  * @param maxAttempts - Maximum attempts to find a unique name (default: 50)
  * @returns A unique player name
  */
-export function generateUniquePlayerName(existingNames: string[], maxAttempts = 50): string {
+export function generateUniquePlayerName(
+  existingNames: string[],
+  emoji?: string,
+  maxAttempts = 50
+): string {
   const existingNamesSet = new Set(existingNames.map((name) => name.toLowerCase()))
 
   for (let i = 0; i < maxAttempts; i++) {
-    const name = generatePlayerName()
+    const name = generatePlayerName(emoji)
     if (!existingNamesSet.has(name.toLowerCase())) {
       return name
     }
   }
 
   // Fallback: if we can't find a unique name, append a number
-  const baseName = generatePlayerName()
+  const baseName = generatePlayerName(emoji)
   let counter = 1
   while (existingNamesSet.has(`${baseName} ${counter}`.toLowerCase())) {
     counter++
@@ -150,12 +244,13 @@ export function generateUniquePlayerName(existingNames: string[], maxAttempts =
 /**
  * Generate a batch of unique player names
  * @param count - Number of names to generate
+ * @param emoji - Optional emoji avatar to theme the names around
  * @returns Array of unique player names
  */
-export function generateUniquePlayerNames(count: number): string[] {
+export function generateUniquePlayerNames(count: number, emoji?: string): string[] {
   const names: string[] = []
   for (let i = 0; i < count; i++) {
-    const name = generateUniquePlayerName(names)
+    const name = generateUniquePlayerName(names, emoji)
     names.push(name)
   }
   return names

package.json

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