chore(release): 3.17.12 [skip ci]

## [3.17.12](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.11...v3.17.12) (2025-10-15)

### Code Refactoring

* **arcade:** remove non-productive debug logging from memory-quiz ([38e554e](38e554e6ea))

### Documentation

* **arcade:** document game settings persistence architecture ([8f8f112](8f8f112de2))

CHANGELOG.md

@@ -1,3 +1,83 @@
+## [3.17.12](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.11...v3.17.12) (2025-10-15)
+
+
+### Code Refactoring
+
+* **arcade:** remove non-productive debug logging from memory-quiz ([38e554e](https://github.com/antialias/soroban-abacus-flashcards/commit/38e554e6ea0386e48798338dd938e50ba73d5576))
+
+
+### Documentation
+
+* **arcade:** document game settings persistence architecture ([8f8f112](https://github.com/antialias/soroban-abacus-flashcards/commit/8f8f112de222e40901d4b3168fa751d233337e4b))
+
+## [3.17.11](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.10...v3.17.11) (2025-10-15)
+
+
+### Bug Fixes
+
+* **memory-quiz:** fix playMode persistence by updating validator ([de0efd5](https://github.com/antialias/soroban-abacus-flashcards/commit/de0efd59321ec779cddb900724035884290419b7))
+
+## [3.17.10](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.9...v3.17.10) (2025-10-15)
+
+
+### Bug Fixes
+
+* **memory-quiz:** persist playMode setting across game switches ([487ca7f](https://github.com/antialias/soroban-abacus-flashcards/commit/487ca7fba62e370c85bc3779ca8a96eb2c2cc3e3))
+
+## [3.17.9](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.8...v3.17.9) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade:** read nested gameConfig correctly when creating sessions ([94ef392](https://github.com/antialias/soroban-abacus-flashcards/commit/94ef39234d362b82e032cb69d3561b9fcb436eaf))
+
+## [3.17.8](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.7...v3.17.8) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade:** preserve game settings when returning to game selection ([0ee7739](https://github.com/antialias/soroban-abacus-flashcards/commit/0ee7739091d60580d2f98cfe288b8586b03348f3))
+
+## [3.17.7](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.6...v3.17.7) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade:** prevent gameConfig from being overwritten when switching games ([a89d3a9](https://github.com/antialias/soroban-abacus-flashcards/commit/a89d3a970137471e2652de992c45370dbb97416d))
+
+## [3.17.6](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.5...v3.17.6) (2025-10-15)
+
+
+### Code Refactoring
+
+* **logging:** use JSON.stringify for all object logging ([c33698c](https://github.com/antialias/soroban-abacus-flashcards/commit/c33698ce52ebdc18ce3a0d856f9241c7389ed651))
+
+## [3.17.5](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.4...v3.17.5) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade:** implement settings persistence for matching game ([08fe432](https://github.com/antialias/soroban-abacus-flashcards/commit/08fe4326a6a7c484b9058a241f4ff79b3fb5125f))
+
+## [3.17.4](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.3...v3.17.4) (2025-10-15)
+
+
+### Bug Fixes
+
+* **matching:** add settings persistence to matching game ([00dcb87](https://github.com/antialias/soroban-abacus-flashcards/commit/00dcb872b7e70bdb7de301b56fe42195e6ee923f))
+
+## [3.17.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.2...v3.17.3) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade:** preserve gameConfig when switching games ([2273c71](https://github.com/antialias/soroban-abacus-flashcards/commit/2273c71a872a5122d0b2023835fe30640106048e))
+
+
+### Code Refactoring
+
+* remove verbose console logging for cleaner debugging ([9cb5fdd](https://github.com/antialias/soroban-abacus-flashcards/commit/9cb5fdd2fa43560adc32dd052f47a7b06b2c5b69))
+
 ## [3.17.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.1...v3.17.2) (2025-10-15)
 
 

apps/web/.claude/CLAUDE.md

@@ -108,3 +108,31 @@ npm run check          # Biome check (format + lint + organize imports)
 - Lint checks
 
 **Status:** Known issue, does not block development or deployment.
+
+## Game Settings Persistence
+
+When working on arcade room game settings, refer to:
+
+- **`.claude/GAME_SETTINGS_PERSISTENCE.md`** - Complete architecture documentation
+  - How settings are stored (nested by game name)
+  - Three critical systems that must stay in sync
+  - Common bugs and their solutions
+  - Debugging checklist
+  - Step-by-step guide for adding new settings
+
+- **`.claude/GAME_SETTINGS_REFACTORING.md`** - Recommended improvements
+  - Shared config types to prevent inconsistencies
+  - Helper functions to reduce duplication
+  - Type-safe validation
+  - Migration strategy
+
+**Quick Reference:**
+
+Settings are stored as: `gameConfig[gameName][setting]`
+
+Three places must handle settings correctly:
+1. **Provider** (`Room{Game}Provider.tsx`) - Merges saved config with defaults
+2. **Socket Server** (`socket-server.ts`) - Creates session from saved config
+3. **Validator** (`{Game}Validator.ts`) - `getInitialState()` must accept ALL settings
+
+If a setting doesn't persist, check all three locations.

apps/web/.claude/GAME_SETTINGS_PERSISTENCE.md

@@ -0,0 +1,237 @@
+# Game Settings Persistence Architecture
+
+## Overview
+
+Game settings in room mode persist across game switches using a nested gameConfig structure. This document describes the architecture and common pitfalls.
+
+## Data Structure
+
+Settings are stored in the `arcadeRooms` table's `gameConfig` column with this structure:
+
+```typescript
+{
+  "matching": {
+    "gameType": "complement-pairs",
+    "difficulty": 15,
+    "turnTimer": 60
+  },
+  "memory-quiz": {
+    "selectedCount": 8,
+    "displayTime": 3.0,
+    "selectedDifficulty": "medium",
+    "playMode": "competitive"
+  }
+}
+```
+
+**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
+
+## Critical Components
+
+Settings persistence requires coordination between THREE systems:
+
+### 1. Client-Side Provider
+**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`
+
+**Example:** `RoomMemoryQuizProvider.tsx:211-247`
+```typescript
+const mergedInitialState = useMemo(() => {
+  const gameConfig = roomData?.gameConfig as Record<string, any>
+  const savedConfig = gameConfig?.['memory-quiz']
+
+  return {
+    ...initialState,
+    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`
+
+**Responsibilities:**
+- Create initial arcade session when user joins room
+- Read saved settings from `room.gameConfig[gameName]`
+- Pass settings to validator's `getInitialState()`
+
+**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',
+})
+```
+
+### 3. Game Validator
+**Location:** `src/lib/arcade/validation/{Game}Validator.ts`
+
+**Responsibilities:**
+- Define `getInitialState()` method that creates initial game state
+- Accept ALL game settings as parameters
+- Use provided values or fall back to defaults
+
+**Example:** `MemoryQuizGameValidator.ts:404-442`
+```typescript
+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!
+  }
+}
+```
+
+## Common Bugs and Solutions
+
+### Bug #1: Settings Wiped When Returning to Game Selection
+
+**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
+```typescript
+// ❌ WRONG
+body: JSON.stringify({ gameName: null, gameConfig: null })
+
+// ✅ CORRECT
+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]`
+
+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()
+
+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
+
+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
+
+## 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
+
+## Testing Settings Persistence
+
+Manual test procedure:
+
+1. Join a room and select a game
+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
+
+**Expected behavior:** All settings should be exactly as you left them.
+
+## Refactoring Recommendations
+
+See next section for suggested improvements to prevent these bugs.

apps/web/.claude/GAME_SETTINGS_REFACTORING.md

@@ -0,0 +1,479 @@
+# Game Settings Persistence - Refactoring Recommendations
+
+## Current Pain Points
+
+1. **Type safety is weak** - Easy to forget to add a setting in one place
+2. **Duplication** - Config reading logic duplicated in socket-server.ts for each game
+3. **Manual synchronization** - Have to manually keep validator signature, provider, and socket server in sync
+4. **Error-prone** - Easy to hardcode values or forget to read from config
+
+## Recommended Refactorings
+
+### 1. Create Shared Config Types (HIGHEST PRIORITY)
+
+**Problem:** Each game's settings are defined in multiple places with no type enforcement
+
+**Solution:** Define a single source of truth for each game's config
+
+```typescript
+// src/lib/arcade/game-configs.ts
+
+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'
+}
+
+export interface ComplementRaceGameConfig {
+  // ... future settings
+}
+
+export interface RoomGameConfig {
+  matching?: MatchingGameConfig
+  'memory-quiz'?: MemoryQuizGameConfig
+  'complement-race'?: ComplementRaceGameConfig
+}
+
+// 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',
+}
+```
+
+**Benefits:**
+- Single source of truth for each game's settings
+- TypeScript enforces consistency across codebase
+- Easy to see what settings each game has
+
+### 2. Create Config Helper Functions
+
+**Problem:** Config reading logic is duplicated and error-prone
+
+**Solution:** Centralized helper functions with type safety
+
+```typescript
+// src/lib/arcade/game-config-helpers.ts
+
+import type { GameName } from './validation'
+import type { RoomGameConfig, MatchingGameConfig, MemoryQuizGameConfig } from './game-configs'
+import { DEFAULT_MATCHING_CONFIG, DEFAULT_MEMORY_QUIZ_CONFIG } from './game-configs'
+
+/**
+ * Get game-specific config from room's gameConfig with defaults
+ */
+export function getGameConfig<T extends GameName>(
+  roomGameConfig: RoomGameConfig | null | undefined,
+  gameName: T
+): T extends 'matching'
+  ? MatchingGameConfig
+  : T extends 'memory-quiz'
+  ? MemoryQuizGameConfig
+  : never {
+
+  if (!roomGameConfig) {
+    return getDefaultGameConfig(gameName) as any
+  }
+
+  const savedConfig = roomGameConfig[gameName]
+  if (!savedConfig) {
+    return getDefaultGameConfig(gameName) as any
+  }
+
+  // Merge saved config with defaults to handle missing fields
+  const defaults = getDefaultGameConfig(gameName)
+  return { ...defaults, ...savedConfig } as any
+}
+
+function getDefaultGameConfig(gameName: 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
+      throw new Error('complement-race config not implemented')
+    default:
+      throw new Error(`Unknown game: ${gameName}`)
+  }
+}
+
+/**
+ * Update a specific game's config in the room's gameConfig
+ */
+export function updateGameConfig<T extends GameName>(
+  currentRoomConfig: RoomGameConfig | null | undefined,
+  gameName: T,
+  updates: Partial<T extends 'matching' ? MatchingGameConfig : T extends 'memory-quiz' ? MemoryQuizGameConfig : never>
+): RoomGameConfig {
+  const current = currentRoomConfig || {}
+  const gameConfig = current[gameName] || getDefaultGameConfig(gameName)
+
+  return {
+    ...current,
+    [gameName]: {
+      ...gameConfig,
+      ...updates,
+    },
+  }
+}
+```
+
+**Usage in socket-server.ts:**
+```typescript
+// BEFORE (error-prone, duplicated)
+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',
+})
+
+// AFTER (type-safe, concise)
+const config = getGameConfig(room.gameConfig, 'memory-quiz')
+initialState = validator.getInitialState(config)
+```
+
+**Usage in RoomMemoryQuizProvider.tsx:**
+```typescript
+// BEFORE (verbose, error-prone)
+const mergedInitialState = useMemo(() => {
+  const gameConfig = roomData?.gameConfig as Record<string, any>
+  const savedConfig = gameConfig?.['memory-quiz']
+
+  return {
+    ...initialState,
+    selectedCount: savedConfig?.selectedCount ?? initialState.selectedCount,
+    displayTime: savedConfig?.displayTime ?? initialState.displayTime,
+    selectedDifficulty: savedConfig?.selectedDifficulty ?? initialState.selectedDifficulty,
+    playMode: savedConfig?.playMode ?? initialState.playMode,
+  }
+}, [roomData?.gameConfig])
+
+// AFTER (type-safe, concise)
+const mergedInitialState = useMemo(() => {
+  const config = getGameConfig(roomData?.gameConfig, 'memory-quiz')
+  return {
+    ...initialState,
+    ...config,  // Spread config directly - all settings included
+  }
+}, [roomData?.gameConfig])
+```
+
+**Benefits:**
+- No more manual property-by-property merging
+- Type-safe
+- Defaults handled automatically
+- Reusable across codebase
+
+### 3. Enforce Validator Config Type from Game Config
+
+**Problem:** Easy to forget to add a new setting to validator's `getInitialState()` signature
+
+**Solution:** Make validator use the shared config type
+
+```typescript
+// src/lib/arcade/validation/MemoryQuizGameValidator.ts
+
+import type { MemoryQuizGameConfig } from '@/lib/arcade/game-configs'
+
+export class MemoryQuizGameValidator {
+  // BEFORE: Manual type definition
+  // getInitialState(config: {
+  //   selectedCount: number
+  //   displayTime: number
+  //   selectedDifficulty: DifficultyLevel
+  //   playMode?: 'cooperative' | 'competitive'
+  // }): SorobanQuizState
+
+  // AFTER: Use shared type
+  getInitialState(config: MemoryQuizGameConfig): SorobanQuizState {
+    return {
+      // ...
+      selectedCount: config.selectedCount,
+      displayTime: config.displayTime,
+      selectedDifficulty: config.selectedDifficulty,
+      playMode: config.playMode,  // TypeScript ensures all fields are handled
+      // ...
+    }
+  }
+}
+```
+
+**Benefits:**
+- If you add a setting to `MemoryQuizGameConfig`, TypeScript forces you to handle it
+- Impossible to forget a setting
+- Impossible to use wrong type
+
+### 4. Add Exhaustiveness Checking
+
+**Problem:** Easy to miss handling a setting field
+
+**Solution:** Use TypeScript's exhaustiveness checking
+
+```typescript
+// src/lib/arcade/validation/MemoryQuizGameValidator.ts
+
+getInitialState(config: MemoryQuizGameConfig): SorobanQuizState {
+  // Exhaustiveness check - ensures all config fields are used
+  const _exhaustivenessCheck: Record<keyof MemoryQuizGameConfig, boolean> = {
+    selectedCount: true,
+    displayTime: true,
+    selectedDifficulty: true,
+    playMode: true,
+  }
+
+  return {
+    // ... use all config fields
+    selectedCount: config.selectedCount,
+    displayTime: config.displayTime,
+    selectedDifficulty: config.selectedDifficulty,
+    playMode: config.playMode,
+  }
+}
+```
+
+If you add a new field to `MemoryQuizGameConfig`, TypeScript will error on `_exhaustivenessCheck` until you add it.
+
+### 5. Validate Config on Save
+
+**Problem:** Invalid config can be saved to database
+
+**Solution:** Add runtime validation
+
+```typescript
+// src/lib/arcade/game-config-helpers.ts
+
+export function validateGameConfig(
+  gameName: GameName,
+  config: any
+): config is MatchingGameConfig | MemoryQuizGameConfig {
+  switch (gameName) {
+    case 'matching':
+      return (
+        typeof config.gameType === 'string' &&
+        ['abacus-numeral', 'complement-pairs'].includes(config.gameType) &&
+        typeof config.difficulty === 'number' &&
+        config.difficulty > 0 &&
+        typeof config.turnTimer === 'number' &&
+        config.turnTimer > 0
+      )
+
+    case 'memory-quiz':
+      return (
+        [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)
+      )
+
+    default:
+      return false
+  }
+}
+```
+
+Use in settings API:
+```typescript
+// src/app/api/arcade/rooms/[roomId]/settings/route.ts
+
+if (body.gameConfig !== undefined) {
+  if (!validateGameConfig(room.gameName, body.gameConfig[room.gameName])) {
+    return NextResponse.json({ error: 'Invalid game config' }, { status: 400 })
+  }
+  updateData.gameConfig = body.gameConfig
+}
+```
+
+## Schema Refactoring: Separate Table for Game Configs
+
+### Current Problem
+
+All game configs are stored in a single JSON column in `arcade_rooms.gameConfig`:
+
+```json
+{
+  "matching": { "gameType": "...", "difficulty": 15 },
+  "memory-quiz": { "selectedCount": 8, "playMode": "competitive" }
+}
+```
+
+**Issues:**
+- No schema validation
+- Inefficient updates (read/parse/modify/serialize entire blob)
+- Grows without bounds as more games added
+- Can't query or index individual game settings
+- No audit trail
+- Potential concurrent update race conditions
+
+### Recommended: Separate Table
+
+Create `room_game_configs` table with one row per game per room:
+
+```typescript
+// src/db/schema/room-game-configs.ts
+
+export const roomGameConfigs = sqliteTable('room_game_configs', {
+  id: text('id').primaryKey().$defaultFn(() => createId()),
+  roomId: text('room_id')
+    .notNull()
+    .references(() => arcadeRooms.id, { onDelete: 'cascade' }),
+  gameName: text('game_name', {
+    enum: ['matching', 'memory-quiz', 'complement-race'],
+  }).notNull(),
+  config: text('config', { mode: 'json' }).notNull(), // Game-specific JSON
+  createdAt: integer('created_at', { mode: 'timestamp' })
+    .notNull()
+    .$defaultFn(() => new Date()),
+  updatedAt: integer('updated_at', { mode: 'timestamp' })
+    .notNull()
+    .$defaultFn(() => new Date()),
+}, (table) => ({
+  uniqueRoomGame: uniqueIndex('room_game_idx').on(table.roomId, table.gameName),
+}))
+```
+
+**Benefits:**
+- ✅ Smaller rows (only configs for games that have been used)
+- ✅ Easier updates (single row, not entire JSON blob)
+- ✅ Can track updatedAt per game
+- ✅ Better concurrency (no lock contention between games)
+- ✅ Foundation for future audit trail
+
+**Migration Strategy:**
+1. Create new table
+2. Migrate existing data from `arcade_rooms.gameConfig`
+3. Update all config read/write code
+4. Deploy and test
+5. Drop old `gameConfig` column from `arcade_rooms`
+
+See migration SQL below.
+
+## Implementation Priority
+
+### Phase 1: Schema Migration (HIGHEST PRIORITY)
+1. **Create new table** - Add `room_game_configs` schema
+2. **Create migration** - SQL to migrate existing data
+3. **Update helper functions** - Adapt to new table structure
+4. **Update all read/write code** - Use new table
+5. **Test thoroughly** - Verify all settings persist correctly
+6. **Drop old column** - Remove `gameConfig` from `arcade_rooms`
+
+### Phase 2: Type Safety (HIGH)
+1. **Create shared config types** (`game-configs.ts`) - Prevents type mismatches
+2. **Create helper functions** (`game-config-helpers.ts`) - Now queries new table
+3. **Update validators** to use shared types - Enforces consistency
+
+### Phase 3: Compile-Time Safety (MEDIUM)
+1. **Add exhaustiveness checking** - Catches missing fields at compile time
+2. **Enforce validator config types** - Use shared types
+
+### Phase 4: Runtime Safety (LOW)
+1. **Add runtime validation** - Prevents invalid data from being saved
+
+## Detailed Migration SQL
+
+```sql
+-- drizzle/migrations/XXXX_split_game_configs.sql
+
+-- Create new table
+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
+);
+
+CREATE UNIQUE INDEX room_game_idx ON room_game_configs(room_id, game_name);
+
+-- Migrate existing 'matching' configs
+INSERT INTO room_game_configs (id, room_id, game_name, config, created_at, updated_at)
+SELECT
+  lower(hex(randomblob(16))),
+  id,
+  'matching',
+  json_extract(game_config, '$.matching'),
+  created_at,
+  last_activity
+FROM arcade_rooms
+WHERE json_extract(game_config, '$.matching') IS NOT NULL;
+
+-- Migrate existing 'memory-quiz' configs
+INSERT INTO room_game_configs (id, room_id, game_name, config, created_at, updated_at)
+SELECT
+  lower(hex(randomblob(16))),
+  id,
+  'memory-quiz',
+  json_extract(game_config, '$."memory-quiz"'),
+  created_at,
+  last_activity
+FROM arcade_rooms
+WHERE json_extract(game_config, '$."memory-quiz"') IS NOT NULL;
+
+-- After testing and verifying all works:
+-- ALTER TABLE arcade_rooms DROP COLUMN game_config;
+```
+
+## Migration Strategy
+
+### Step-by-Step with Checkpoints
+
+**Checkpoint 1: Schema & Migration**
+1. Create `src/db/schema/room-game-configs.ts`
+2. Export from `src/db/schema/index.ts`
+3. Generate and apply migration
+4. Verify data migrated correctly
+
+**Checkpoint 2: Helper Functions**
+1. Create shared config types in `src/lib/arcade/game-configs.ts`
+2. Create helper functions in `src/lib/arcade/game-config-helpers.ts`
+3. Add unit tests for helpers
+
+**Checkpoint 3: Update Config Reads**
+1. Update socket-server.ts to read from new table
+2. Update RoomMemoryQuizProvider to read from new table
+3. Update RoomMemoryPairsProvider to read from new table
+4. Test: Load room and verify settings appear
+
+**Checkpoint 4: Update Config Writes**
+1. Update useRoomData.ts updateGameConfig to write to new table
+2. Update settings API to write to new table
+3. Test: Change settings and verify they persist
+
+**Checkpoint 5: Update Validators**
+1. Update validators to use shared config types
+2. Test: All games work correctly
+
+**Checkpoint 6: Cleanup**
+1. Remove old gameConfig column references
+2. Drop gameConfig column from arcade_rooms table
+3. Final testing of all games
+
+## Benefits Summary
+
+- **Type Safety:** TypeScript enforces consistency across all systems
+- **DRY:** Config reading logic not duplicated
+- **Maintainability:** Adding a setting requires changes in fewer places
+- **Correctness:** Impossible to forget a setting or use wrong type
+- **Debugging:** Centralized config logic easier to trace
+- **Testing:** Can test config helpers in isolation

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

@@ -27,6 +27,36 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
     const viewerId = await getViewerId()
     const body = await req.json()
 
+    console.log(
+      '[Settings API] PATCH request received:',
+      JSON.stringify(
+        {
+          roomId,
+          body,
+        },
+        null,
+        2
+      )
+    )
+
+    // Read current room state from database BEFORE any changes
+    const [currentRoom] = await db
+      .select()
+      .from(schema.arcadeRooms)
+      .where(eq(schema.arcadeRooms.id, roomId))
+
+    console.log(
+      '[Settings API] Current room state in database BEFORE update:',
+      JSON.stringify(
+        {
+          gameName: currentRoom?.gameName,
+          gameConfig: currentRoom?.gameConfig,
+        },
+        null,
+        2
+      )
+    )
+
     // Check if user is the host
     const members = await getRoomMembers(roomId)
     const currentMember = members.find((m) => m.userId === viewerId)
@@ -97,6 +127,11 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
       updateData.gameConfig = body.gameConfig
     }
 
+    console.log(
+      '[Settings API] Update data to be written to database:',
+      JSON.stringify(updateData, null, 2)
+    )
+
     // If game is being changed (or cleared), delete the existing arcade session
     // This ensures a fresh session will be created with the new game settings
     if (body.gameName !== undefined) {
@@ -111,17 +146,39 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
       .where(eq(schema.arcadeRooms.id, roomId))
       .returning()
 
+    console.log(
+      '[Settings API] Room state in database AFTER update:',
+      JSON.stringify(
+        {
+          gameName: updatedRoom.gameName,
+          gameConfig: updatedRoom.gameConfig,
+        },
+        null,
+        2
+      )
+    )
+
     // Broadcast game change to all room members
     if (body.gameName !== undefined) {
       const io = await getSocketIO()
       if (io) {
         try {
           console.log(`[Settings API] Broadcasting game change to room ${roomId}: ${body.gameName}`)
-          io.to(`room:${roomId}`).emit('room-game-changed', {
+          const broadcastData: {
+            roomId: string
+            gameName: string | null
+            gameConfig?: Record<string, unknown>
+          } = {
             roomId,
             gameName: body.gameName,
-            gameConfig: body.gameConfig || {},
-          })
+          }
+
+          // Only include gameConfig if it was explicitly provided
+          if (body.gameConfig !== undefined) {
+            broadcastData.gameConfig = body.gameConfig
+          }
+
+          io.to(`room:${roomId}`).emit('room-game-changed', broadcastData)
         } catch (socketError) {
           console.error('[Settings API] Failed to broadcast game change:', socketError)
         }

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

@@ -28,6 +28,19 @@ export async function GET() {
       return NextResponse.json({ error: 'Room not found' }, { status: 404 })
     }
 
+    console.log(
+      '[Current Room API] Room data READ from database:',
+      JSON.stringify(
+        {
+          roomId,
+          gameName: room.gameName,
+          gameConfig: room.gameConfig,
+        },
+        null,
+        2
+      )
+    )
+
     // Get members
     const members = await getRoomMembers(roomId)
 

apps/web/src/app/arcade/matching/context/RoomMemoryPairsProvider.tsx

@@ -2,7 +2,7 @@
 
 import { type ReactNode, useCallback, useEffect, useMemo } from 'react'
 import { useArcadeSession } from '@/hooks/useArcadeSession'
-import { useRoomData } from '@/hooks/useRoomData'
+import { useRoomData, useUpdateGameConfig } from '@/hooks/useRoomData'
 import { useViewerId } from '@/hooks/useViewerId'
 import {
   buildPlayerMetadata as buildPlayerMetadataUtil,
@@ -240,6 +240,7 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
   const { data: viewerId } = useViewerId()
   const { roomData } = useRoomData() // Fetch room data for room-based play
   const { activePlayerCount, activePlayers: activePlayerIds, players } = useGameMode()
+  const { mutate: updateGameConfig } = useUpdateGameConfig()
 
   // Get active player IDs directly as strings (UUIDs)
   const activePlayers = Array.from(activePlayerIds)
@@ -247,8 +248,77 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
   // Derive game mode from active player count
   const gameMode = activePlayerCount > 1 ? 'multiplayer' : 'single'
 
-  // NO LOCAL STATE - Configuration lives in session state
-  // Changes are sent as moves and synchronized across all room members
+  // Track roomData.gameConfig changes
+  useEffect(() => {
+    console.log(
+      '[RoomMemoryPairsProvider] roomData.gameConfig changed:',
+      JSON.stringify(
+        {
+          gameConfig: roomData?.gameConfig,
+          roomId: roomData?.id,
+          gameName: roomData?.gameName,
+        },
+        null,
+        2
+      )
+    )
+  }, [roomData?.gameConfig, roomData?.id, roomData?.gameName])
+
+  // Merge saved game config from room with initialState
+  // Settings are scoped by game name to preserve settings when switching games
+  const mergedInitialState = useMemo(() => {
+    const gameConfig = roomData?.gameConfig as Record<string, any> | null | undefined
+    console.log(
+      '[RoomMemoryPairsProvider] Loading settings from database:',
+      JSON.stringify(
+        {
+          gameConfig,
+          roomId: roomData?.id,
+        },
+        null,
+        2
+      )
+    )
+
+    if (!gameConfig) {
+      console.log('[RoomMemoryPairsProvider] No gameConfig, using initialState')
+      return initialState
+    }
+
+    // Get settings for this specific game (matching)
+    const savedConfig = gameConfig.matching as Record<string, any> | null | undefined
+    console.log(
+      '[RoomMemoryPairsProvider] Saved config for matching:',
+      JSON.stringify(savedConfig, null, 2)
+    )
+
+    if (!savedConfig) {
+      console.log('[RoomMemoryPairsProvider] No saved config for matching, using initialState')
+      return initialState
+    }
+
+    const merged = {
+      ...initialState,
+      // Restore settings from saved config
+      gameType: savedConfig.gameType ?? initialState.gameType,
+      difficulty: savedConfig.difficulty ?? initialState.difficulty,
+      turnTimer: savedConfig.turnTimer ?? initialState.turnTimer,
+    }
+    console.log(
+      '[RoomMemoryPairsProvider] Merged state:',
+      JSON.stringify(
+        {
+          gameType: merged.gameType,
+          difficulty: merged.difficulty,
+          turnTimer: merged.turnTimer,
+        },
+        null,
+        2
+      )
+    )
+
+    return merged
+  }, [roomData?.gameConfig])
 
   // Arcade session integration WITH room sync
   const {
@@ -259,7 +329,7 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
   } = useArcadeSession<MemoryPairsState>({
     userId: viewerId || '',
     roomId: roomData?.id, // CRITICAL: Pass roomId for network sync across room members
-    initialState,
+    initialState: mergedInitialState,
     applyMove: applyMoveOptimistically,
   })
 
@@ -498,6 +568,8 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
 
   const setGameType = useCallback(
     (gameType: typeof state.gameType) => {
+      console.log('[RoomMemoryPairsProvider] setGameType called:', gameType)
+
       // Use first active player as playerId, or empty string if none
       const playerId = activePlayers[0] || ''
       sendMove({
@@ -506,12 +578,45 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
         userId: viewerId || '',
         data: { field: 'gameType', value: gameType },
       })
+
+      // Save setting to room's gameConfig for persistence
+      if (roomData?.id) {
+        const currentGameConfig = (roomData.gameConfig as Record<string, any>) || {}
+        const currentMatchingConfig = (currentGameConfig.matching as Record<string, any>) || {}
+
+        const updatedConfig = {
+          ...currentGameConfig,
+          matching: {
+            ...currentMatchingConfig,
+            gameType,
+          },
+        }
+        console.log(
+          '[RoomMemoryPairsProvider] Saving gameType to database:',
+          JSON.stringify(
+            {
+              roomId: roomData.id,
+              updatedConfig,
+            },
+            null,
+            2
+          )
+        )
+        updateGameConfig({
+          roomId: roomData.id,
+          gameConfig: updatedConfig,
+        })
+      } else {
+        console.warn('[RoomMemoryPairsProvider] Cannot save gameType - no roomData.id')
+      }
     },
-    [activePlayers, sendMove, viewerId]
+    [activePlayers, sendMove, viewerId, roomData?.id, roomData?.gameConfig, updateGameConfig]
   )
 
   const setDifficulty = useCallback(
     (difficulty: typeof state.difficulty) => {
+      console.log('[RoomMemoryPairsProvider] setDifficulty called:', difficulty)
+
       const playerId = activePlayers[0] || ''
       sendMove({
         type: 'SET_CONFIG',
@@ -519,12 +624,45 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
         userId: viewerId || '',
         data: { field: 'difficulty', value: difficulty },
       })
+
+      // Save setting to room's gameConfig for persistence
+      if (roomData?.id) {
+        const currentGameConfig = (roomData.gameConfig as Record<string, any>) || {}
+        const currentMatchingConfig = (currentGameConfig.matching as Record<string, any>) || {}
+
+        const updatedConfig = {
+          ...currentGameConfig,
+          matching: {
+            ...currentMatchingConfig,
+            difficulty,
+          },
+        }
+        console.log(
+          '[RoomMemoryPairsProvider] Saving difficulty to database:',
+          JSON.stringify(
+            {
+              roomId: roomData.id,
+              updatedConfig,
+            },
+            null,
+            2
+          )
+        )
+        updateGameConfig({
+          roomId: roomData.id,
+          gameConfig: updatedConfig,
+        })
+      } else {
+        console.warn('[RoomMemoryPairsProvider] Cannot save difficulty - no roomData.id')
+      }
     },
-    [activePlayers, sendMove, viewerId]
+    [activePlayers, sendMove, viewerId, roomData?.id, roomData?.gameConfig, updateGameConfig]
   )
 
   const setTurnTimer = useCallback(
     (turnTimer: typeof state.turnTimer) => {
+      console.log('[RoomMemoryPairsProvider] setTurnTimer called:', turnTimer)
+
       const playerId = activePlayers[0] || ''
       sendMove({
         type: 'SET_CONFIG',
@@ -532,8 +670,39 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
         userId: viewerId || '',
         data: { field: 'turnTimer', value: turnTimer },
       })
+
+      // Save setting to room's gameConfig for persistence
+      if (roomData?.id) {
+        const currentGameConfig = (roomData.gameConfig as Record<string, any>) || {}
+        const currentMatchingConfig = (currentGameConfig.matching as Record<string, any>) || {}
+
+        const updatedConfig = {
+          ...currentGameConfig,
+          matching: {
+            ...currentMatchingConfig,
+            turnTimer,
+          },
+        }
+        console.log(
+          '[RoomMemoryPairsProvider] Saving turnTimer to database:',
+          JSON.stringify(
+            {
+              roomId: roomData.id,
+              updatedConfig,
+            },
+            null,
+            2
+          )
+        )
+        updateGameConfig({
+          roomId: roomData.id,
+          gameConfig: updatedConfig,
+        })
+      } else {
+        console.warn('[RoomMemoryPairsProvider] Cannot save turnTimer - no roomData.id')
+      }
     },
-    [activePlayers, sendMove, viewerId]
+    [activePlayers, sendMove, viewerId, roomData?.id, roomData?.gameConfig, updateGameConfig]
   )
 
   const goToSetup = useCallback(() => {

apps/web/src/app/arcade/memory-quiz/context/RoomMemoryQuizProvider.tsx

@@ -55,35 +55,21 @@ function applyMoveOptimistically(state: SorobanQuizState, move: GameMove): Sorob
       const activePlayers = move.data.activePlayers || []
       const playerMetadata = move.data.playerMetadata || {}
 
-      console.log('🎯 [START_QUIZ] Initializing player scores:', {
-        activePlayers,
-        playerMetadata,
-      })
-
       // Extract unique userIds from playerMetadata
       const uniqueUserIds = new Set<string>()
       for (const playerId of activePlayers) {
         const metadata = playerMetadata[playerId]
-        console.log('🎯 [START_QUIZ] Processing player:', {
-          playerId,
-          metadata,
-          hasUserId: !!metadata?.userId,
-        })
         if (metadata?.userId) {
           uniqueUserIds.add(metadata.userId)
         }
       }
 
-      console.log('🎯 [START_QUIZ] Unique userIds found:', Array.from(uniqueUserIds))
-
       // Initialize scores for each userId
       const playerScores = Array.from(uniqueUserIds).reduce((acc: any, userId: string) => {
         acc[userId] = { correct: 0, incorrect: 0 }
         return acc
       }, {})
 
-      console.log('🎯 [START_QUIZ] Initialized playerScores:', playerScores)
-
       return {
         ...state,
         quizCards,
@@ -122,12 +108,6 @@ function applyMoveOptimistically(state: SorobanQuizState, move: GameMove): Sorob
       const foundNumbers = state.foundNumbers || []
       const numberFoundBy = state.numberFoundBy || {}
 
-      console.log('✅ [ACCEPT_NUMBER] Before update:', {
-        moveUserId: move.userId,
-        currentPlayerScores: playerScores,
-        number: move.data.number,
-      })
-
       const newPlayerScores = { ...playerScores }
       const newNumberFoundBy = { ...numberFoundBy }
 
@@ -139,15 +119,6 @@ function applyMoveOptimistically(state: SorobanQuizState, move: GameMove): Sorob
         }
         // Track who found this number
         newNumberFoundBy[move.data.number] = move.userId
-
-        console.log('✅ [ACCEPT_NUMBER] After update:', {
-          userId: move.userId,
-          newScore: newPlayerScores[move.userId],
-          allScores: newPlayerScores,
-          numberFoundBy: move.data.number,
-        })
-      } else {
-        console.warn('⚠️ [ACCEPT_NUMBER] No userId in move!')
       }
       return {
         ...state,
@@ -162,11 +133,6 @@ function applyMoveOptimistically(state: SorobanQuizState, move: GameMove): Sorob
       // Defensive check: ensure state properties exist
       const playerScores = state.playerScores || {}
 
-      console.log('❌ [REJECT_NUMBER] Before update:', {
-        moveUserId: move.userId,
-        currentPlayerScores: playerScores,
-      })
-
       const newPlayerScores = { ...playerScores }
       if (move.userId) {
         const currentScore = newPlayerScores[move.userId] || { correct: 0, incorrect: 0 }
@@ -174,13 +140,6 @@ function applyMoveOptimistically(state: SorobanQuizState, move: GameMove): Sorob
           ...currentScore,
           incorrect: currentScore.incorrect + 1,
         }
-        console.log('❌ [REJECT_NUMBER] After update:', {
-          userId: move.userId,
-          newScore: newPlayerScores[move.userId],
-          allScores: newPlayerScores,
-        })
-      } else {
-        console.warn('⚠️ [REJECT_NUMBER] No userId in move!')
       }
       return {
         ...state,
@@ -251,13 +210,17 @@ export function RoomMemoryQuizProvider({ children }: { children: ReactNode }) {
   // Settings are scoped by game name to preserve settings when switching games
   const mergedInitialState = useMemo(() => {
     const gameConfig = roomData?.gameConfig as Record<string, any> | null | undefined
-    if (!gameConfig) return initialState
+
+    if (!gameConfig) {
+      return initialState
+    }
 
     // Get settings for this specific game (memory-quiz)
     const savedConfig = gameConfig['memory-quiz'] as Record<string, any> | null | undefined
-    if (!savedConfig) return initialState
 
-    console.log('[RoomMemoryQuizProvider] Loading saved game config for memory-quiz:', savedConfig)
+    if (!savedConfig) {
+      return initialState
+    }
 
     return {
       ...initialState,
@@ -310,19 +273,8 @@ export function RoomMemoryQuizProvider({ children }: { children: ReactNode }) {
 
   // Build player metadata from room data and player map
   const buildPlayerMetadata = useCallback(() => {
-    console.log('🔍 [buildPlayerMetadata] Starting:', {
-      roomData: roomData?.id,
-      activePlayers,
-      viewerId,
-      playersMapSize: players.size,
-    })
-
     const playerOwnership = buildPlayerOwnershipFromRoomData(roomData)
-    console.log('🔍 [buildPlayerMetadata] Player ownership:', playerOwnership)
-
     const metadata = buildPlayerMetadataUtil(activePlayers, playerOwnership, players, viewerId)
-    console.log('🔍 [buildPlayerMetadata] Built metadata:', metadata)
-
     return metadata
   }, [activePlayers, players, roomData, viewerId])
 
@@ -336,13 +288,6 @@ export function RoomMemoryQuizProvider({ children }: { children: ReactNode }) {
       // Build player metadata for multiplayer
       const playerMetadata = buildPlayerMetadata()
 
-      console.log('🚀 [startQuiz] Sending START_QUIZ move:', {
-        viewerId,
-        activePlayers,
-        playerMetadata,
-        numbers,
-      })
-
       sendMove({
         type: 'START_QUIZ',
         playerId: TEAM_MOVE, // Team move - all players act together
@@ -381,11 +326,6 @@ export function RoomMemoryQuizProvider({ children }: { children: ReactNode }) {
       // Clear local input immediately
       setLocalCurrentInput('')
 
-      console.log('🚀 [acceptNumber] Sending ACCEPT_NUMBER move:', {
-        viewerId,
-        number,
-      })
-
       sendMove({
         type: 'ACCEPT_NUMBER',
         playerId: TEAM_MOVE, // Team move - can't identify specific player
@@ -400,10 +340,6 @@ export function RoomMemoryQuizProvider({ children }: { children: ReactNode }) {
     // Clear local input immediately
     setLocalCurrentInput('')
 
-    console.log('🚀 [rejectNumber] Sending REJECT_NUMBER move:', {
-      viewerId,
-    })
-
     sendMove({
       type: 'REJECT_NUMBER',
       playerId: TEAM_MOVE, // Team move - can't identify specific player
@@ -438,6 +374,8 @@ export function RoomMemoryQuizProvider({ children }: { children: ReactNode }) {
 
   const setConfig = useCallback(
     (field: 'selectedCount' | 'displayTime' | 'selectedDifficulty' | 'playMode', value: any) => {
+      console.log(`[RoomMemoryQuizProvider] setConfig called: ${field} = ${value}`)
+
       sendMove({
         type: 'SET_CONFIG',
         playerId: TEAM_MOVE,
@@ -452,17 +390,15 @@ export function RoomMemoryQuizProvider({ children }: { children: ReactNode }) {
         const currentMemoryQuizConfig =
           (currentGameConfig['memory-quiz'] as Record<string, any>) || {}
 
-        const updatedConfig = {
-          ...currentGameConfig,
-          'memory-quiz': {
-            ...currentMemoryQuizConfig,
-            [field]: value,
-          },
-        }
-        console.log('[RoomMemoryQuizProvider] Saving game config for memory-quiz:', updatedConfig)
         updateGameConfig({
           roomId: roomData.id,
-          gameConfig: updatedConfig,
+          gameConfig: {
+            ...currentGameConfig,
+            'memory-quiz': {
+              ...currentMemoryQuizConfig,
+              [field]: value,
+            },
+          },
         })
       }
     },

apps/web/src/app/arcade/room/page.tsx

@@ -111,13 +111,13 @@ export default function RoomPage() {
       console.log('[RoomPage] Calling setRoomGame with:', {
         roomId: roomData.id,
         gameName: internalGameName,
-        gameConfig: {},
+        preservingGameConfig: true,
       })
 
+      // Don't pass gameConfig - we want to preserve existing settings for all games
       setRoomGame({
         roomId: roomData.id,
         gameName: internalGameName,
-        gameConfig: {},
       })
     }
 

apps/web/src/hooks/useRoomData.ts

@@ -353,7 +353,6 @@ export function useRoomData() {
 
     // Moderation event handlers
     const handleKickedFromRoom = (data: { roomId: string; kickedBy: string; reason?: string }) => {
-      console.log('[useRoomData] User was kicked from room:', data)
       setModerationEvent({
         type: 'kicked',
         data: {
@@ -367,7 +366,6 @@ export function useRoomData() {
     }
 
     const handleBannedFromRoom = (data: { roomId: string; bannedBy: string; reason: string }) => {
-      console.log('[useRoomData] User was banned from room:', data)
       setModerationEvent({
         type: 'banned',
         data: {
@@ -391,7 +389,6 @@ export function useRoomData() {
         createdAt: Date
       }
     }) => {
-      console.log('[useRoomData] New report submitted:', data)
       setModerationEvent({
         type: 'report',
         data: {
@@ -416,7 +413,6 @@ export function useRoomData() {
         createdAt: Date
       }
     }) => {
-      console.log('[useRoomData] Room invitation received:', data)
       setModerationEvent({
         type: 'invitation',
         data: {
@@ -439,7 +435,6 @@ export function useRoomData() {
         createdAt: Date
       }
     }) => {
-      console.log('[useRoomData] New join request submitted:', data)
       setModerationEvent({
         type: 'join-request',
         data: {
@@ -454,7 +449,7 @@ export function useRoomData() {
     const handleRoomGameChanged = (data: {
       roomId: string
       gameName: string | null
-      gameConfig: Record<string, unknown>
+      gameConfig?: Record<string, unknown>
     }) => {
       console.log('[useRoomData] Room game changed:', data)
       if (data.roomId === roomData?.id) {
@@ -463,6 +458,8 @@ export function useRoomData() {
           return {
             ...prev,
             gameName: data.gameName,
+            // Only update gameConfig if it was provided in the broadcast
+            ...(data.gameConfig !== undefined ? { gameConfig: data.gameConfig } : {}),
           }
         })
       }
@@ -496,7 +493,6 @@ export function useRoomData() {
   // Function to notify room members of player updates
   const notifyRoomOfPlayerUpdate = useCallback(() => {
     if (socket && roomData?.id && userId) {
-      console.log('[useRoomData] Notifying room of player update')
       socket.emit('players-updated', { roomId: roomData.id, userId })
     }
   }, [socket, roomData?.id, userId])
@@ -591,13 +587,20 @@ async function setRoomGameApi(params: {
   gameName: string
   gameConfig?: Record<string, unknown>
 }): Promise<void> {
+  // Only include gameConfig in the request if it was explicitly provided
+  // Otherwise, we preserve the existing gameConfig in the database
+  const body: { gameName: string; gameConfig?: Record<string, unknown> } = {
+    gameName: params.gameName,
+  }
+
+  if (params.gameConfig !== undefined) {
+    body.gameConfig = params.gameConfig
+  }
+
   const response = await fetch(`/api/arcade/rooms/${params.roomId}/settings`, {
     method: 'PATCH',
     headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      gameName: params.gameName,
-      gameConfig: params.gameConfig || {},
-    }),
+    body: JSON.stringify(body),
   })
 
   if (!response.ok) {
@@ -631,6 +634,8 @@ export function useSetRoomGame() {
 
 /**
  * Clear/reset game for a room (host only)
+ * This only clears gameName (returns to game selection) but preserves gameConfig
+ * so settings persist when the user selects a game again.
  */
 async function clearRoomGameApi(roomId: string): Promise<void> {
   const response = await fetch(`/api/arcade/rooms/${roomId}/settings`, {
@@ -638,7 +643,7 @@ async function clearRoomGameApi(roomId: string): Promise<void> {
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
       gameName: null,
-      gameConfig: null,
+      // DO NOT send gameConfig: null - we want to preserve settings!
     }),
   })
 
@@ -678,6 +683,18 @@ async function updateGameConfigApi(params: {
   roomId: string
   gameConfig: Record<string, unknown>
 }): Promise<void> {
+  console.log(
+    '[updateGameConfigApi] Sending PATCH to server:',
+    JSON.stringify(
+      {
+        url: `/api/arcade/rooms/${params.roomId}/settings`,
+        gameConfig: params.gameConfig,
+      },
+      null,
+      2
+    )
+  )
+
   const response = await fetch(`/api/arcade/rooms/${params.roomId}/settings`, {
     method: 'PATCH',
     headers: { 'Content-Type': 'application/json' },
@@ -688,8 +705,11 @@ async function updateGameConfigApi(params: {
 
   if (!response.ok) {
     const errorData = await response.json()
+    console.error('[updateGameConfigApi] Server error:', JSON.stringify(errorData, null, 2))
     throw new Error(errorData.error || 'Failed to update game config')
   }
+
+  console.log('[updateGameConfigApi] Server responded OK')
 }
 
 /**
@@ -710,7 +730,10 @@ export function useUpdateGameConfig() {
           gameConfig: variables.gameConfig,
         }
       })
-      console.log('[useUpdateGameConfig] Updated cache with new gameConfig:', variables.gameConfig)
+      console.log(
+        '[useUpdateGameConfig] Updated cache with new gameConfig:',
+        JSON.stringify(variables.gameConfig, null, 2)
+      )
     },
   })
 }

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

@@ -180,12 +180,6 @@ export class MemoryQuizGameValidator
     }
 
     // Number must be in correct answers
-    console.log('[MemoryQuizValidator] Checking number:', {
-      number,
-      correctAnswers: state.correctAnswers,
-      includes: state.correctAnswers.includes(number),
-    })
-
     if (!state.correctAnswers.includes(number)) {
       return {
         valid: false,
@@ -405,6 +399,7 @@ export class MemoryQuizGameValidator
     selectedCount: number
     displayTime: number
     selectedDifficulty: DifficultyLevel
+    playMode?: 'cooperative' | 'competitive'
   }): SorobanQuizState {
     return {
       cards: [],
@@ -422,7 +417,7 @@ export class MemoryQuizGameValidator
       activePlayers: [],
       playerMetadata: {},
       playerScores: {},
-      playMode: 'cooperative',
+      playMode: config.playMode || 'cooperative',
       numberFoundBy: {},
       // UI state
       gamePhase: 'setup',

apps/web/src/socket-server.ts

@@ -84,16 +84,21 @@ export function initializeSocketServer(httpServer: HTTPServer) {
               // 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: (room.gameConfig as any)?.difficulty || 6,
-                  gameType: (room.gameConfig as any)?.gameType || 'abacus-numeral',
-                  turnTimer: (room.gameConfig as any)?.turnTimer || 30,
+                  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: (room.gameConfig as any)?.selectedCount || 5,
-                  displayTime: (room.gameConfig as any)?.displayTime || 2.0,
-                  selectedDifficulty: (room.gameConfig as any)?.selectedDifficulty || 'easy',
+                  selectedCount: memoryQuizConfig.selectedCount || 5,
+                  displayTime: memoryQuizConfig.displayTime || 2.0,
+                  selectedDifficulty: memoryQuizConfig.selectedDifficulty || 'easy',
+                  playMode: memoryQuizConfig.playMode || 'cooperative',
                 })
               } else {
                 // Fallback for other games

package.json

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