chore(release): 4.0.0 [skip ci]

## [4.0.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.24.0...v4.0.0) (2025-10-16)

### ⚠ BREAKING CHANGES

* **db:** Database schemas now accept any string for game names

### Code Refactoring

* **db:** remove database schema coupling for game names ([e135d92](e135d92abb)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)

CHANGELOG.md

@@ -1,3 +1,531 @@
+## [4.0.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.24.0...v4.0.0) (2025-10-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* **db:** Database schemas now accept any string for game names
+
+### Code Refactoring
+
+* **db:** remove database schema coupling for game names ([e135d92](https://github.com/antialias/soroban-abacus-flashcards/commit/e135d92abb4d27f646c1fbeff6524a729d107426)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)
+
+## [3.24.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.23.0...v3.24.0) (2025-10-16)
+
+
+### Features
+
+* **math-sprint:** add game manifest ([1eefcc8](https://github.com/antialias/soroban-abacus-flashcards/commit/1eefcc89a58b79f928932a7425d6b88fb45a5526))
+
+## [3.23.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.3...v3.23.0) (2025-10-16)
+
+
+### Features
+
+* **arcade:** add Math Sprint game implementation ([e5be09e](https://github.com/antialias/soroban-abacus-flashcards/commit/e5be09ef5f170c7544557f75b9eca17bb2069246))
+* **arcade:** register Math Sprint in game system ([0c05a7c](https://github.com/antialias/soroban-abacus-flashcards/commit/0c05a7c6bbc8d6f6e1f92e15e691d7e1aba0d8f7)), closes [#2](https://github.com/antialias/soroban-abacus-flashcards/issues/2) [#3](https://github.com/antialias/soroban-abacus-flashcards/issues/3)
+
+
+### Bug Fixes
+
+* **api:** add 'math-sprint' to settings endpoint validation ([d790e5e](https://github.com/antialias/soroban-abacus-flashcards/commit/d790e5e278f81686077dbe3ef4adca49574ae434)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)
+* **db:** add 'math-sprint' to database schema enums ([7b112a9](https://github.com/antialias/soroban-abacus-flashcards/commit/7b112a98babe782d4c254ef18a0295e7cbf8fefa)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)
+
+
+### Documentation
+
+* add architecture quality audit [#2](https://github.com/antialias/soroban-abacus-flashcards/issues/2) ([5b91b71](https://github.com/antialias/soroban-abacus-flashcards/commit/5b91b710782dc450405583bc196e5156a296d0df))
+
+## [3.22.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.2...v3.22.3) (2025-10-16)
+
+
+### Bug Fixes
+
+* **number-guesser:** add turn indicators, error feedback, and fix player ordering ([9f62623](https://github.com/antialias/soroban-abacus-flashcards/commit/9f626236845493ef68e1b3626e80efa35637b449))
+
+
+### Documentation
+
+* **arcade:** update docs for unified validator registry ([6f6cb14](https://github.com/antialias/soroban-abacus-flashcards/commit/6f6cb14650ba3636a7e2b036e2a2a9410492e7c3))
+
+## [3.22.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.1...v3.22.2) (2025-10-16)
+
+
+### Code Refactoring
+
+* **arcade:** create unified validator registry to fix dual registration ([f775fc5](https://github.com/antialias/soroban-abacus-flashcards/commit/f775fc55e50af0c3a29b3e00fc722e7d7ce90212)), closes [#1](https://github.com/antialias/soroban-abacus-flashcards/issues/1)
+
+## [3.22.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.22.0...v3.22.1) (2025-10-16)
+
+
+### Bug Fixes
+
+* **arcade:** add Number Guesser to game config helpers ([7d1a351](https://github.com/antialias/soroban-abacus-flashcards/commit/7d1a351ed6a1442ae34f6b75d46039bfa77a921b))
+* **nav:** update types for registry games with nullable gameName ([a51e539](https://github.com/antialias/soroban-abacus-flashcards/commit/a51e539d023681daf639ec104e79079c8ceec98e))
+
+## [3.22.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.21.0...v3.22.0) (2025-10-16)
+
+
+### Features
+
+* **arcade:** add Number Guesser demo game with plugin architecture ([0e3c058](https://github.com/antialias/soroban-abacus-flashcards/commit/0e3c0587073a69574a50f05c467f2499296012bf))
+
+## [3.21.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.20.0...v3.21.0) (2025-10-15)
+
+
+### Features
+
+* **arcade:** add modular game SDK and registry system ([de30bec](https://github.com/antialias/soroban-abacus-flashcards/commit/de30bec47923565fe5d1d5a6f719f3fc4e9d1509))
+
+## [3.20.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.19.0...v3.20.0) (2025-10-15)
+
+
+### Features
+
+* adjust tier probabilities for more abacus flavor ([49219e3](https://github.com/antialias/soroban-abacus-flashcards/commit/49219e34cde32736155a11929d10581e783cba69))
+
+
+### Code Refactoring
+
+* use per-word-type tier selection for name generation ([499ee52](https://github.com/antialias/soroban-abacus-flashcards/commit/499ee525a835249b439044cf602bf9f0ff322cec))
+
+## [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)
+
+
+### 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)
+
+
+### Bug Fixes
+
+* **room-data:** update query cache when gameConfig changes ([7cea297](https://github.com/antialias/soroban-abacus-flashcards/commit/7cea297095b78d74f5b77ca83489ec1be684a486))
+
+## [3.17.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.17.0...v3.17.1) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade-rooms:** navigate to invite link after room creation ([1922b21](https://github.com/antialias/soroban-abacus-flashcards/commit/1922b2122bb1bc4aeada7526d8c46aa89024bb00))
+* **memory-quiz:** scope game settings by game name for proper persistence ([3dfe54f](https://github.com/antialias/soroban-abacus-flashcards/commit/3dfe54f1cb89bd636e763e1c5acb03776f97c011))
+
+## [3.17.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.16.0...v3.17.0) (2025-10-15)
+
+
+### Features
+
+* **memory-quiz:** persist game settings per-game across sessions ([05a8e0a](https://github.com/antialias/soroban-abacus-flashcards/commit/05a8e0a84272c6c45a4014413ee00726eb88b76a))
+
+## [3.16.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.15.2...v3.16.0) (2025-10-15)
+
+
+### Features
+
+* **arcade:** broadcast game selection changes to all room members ([b99e754](https://github.com/antialias/soroban-abacus-flashcards/commit/b99e7543952bb0d47f42e79dc4226b3c1280a0ee))
+
+## [3.15.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.15.1...v3.15.2) (2025-10-15)
+
+
+### Bug Fixes
+
+* **memory-quiz:** prevent duplicate card processing from optimistic updates ([51676fc](https://github.com/antialias/soroban-abacus-flashcards/commit/51676fc15f5bc15cdb43393d3e66f7c5a0667868))
+
+## [3.15.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.15.0...v3.15.1) (2025-10-15)
+
+
+### Bug Fixes
+
+* **memory-quiz:** synchronize card display across all players in multiplayer ([472f201](https://github.com/antialias/soroban-abacus-flashcards/commit/472f201088d82f92030273fadaf8a8e488820d6c))
+
+## [3.15.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.14.4...v3.15.0) (2025-10-15)
+
+
+### Features
+
+* **memory-quiz:** add multiplayer support with redesigned scoreboards ([1cf4469](https://github.com/antialias/soroban-abacus-flashcards/commit/1cf44696c26473ce4ab2fc2039ff42f08c20edb6))
+* **memory-quiz:** show player emojis on cards to indicate who found them ([05bd11a](https://github.com/antialias/soroban-abacus-flashcards/commit/05bd11a133706c9ed8c09c744da7ca8955fa979a))
+
+
+### Bug Fixes
+
+* **arcade:** add defensive checks and update test fixtures ([a93d981](https://github.com/antialias/soroban-abacus-flashcards/commit/a93d981d1ab3abed019b28cebe87525191313cc7))
+
+## [3.14.4](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.14.3...v3.14.4) (2025-10-15)
+
+
+### Bug Fixes
+
+* **memory-quiz:** prevent input lag during rapid typing in room mode ([b45139b](https://github.com/antialias/soroban-abacus-flashcards/commit/b45139b588d0ab6df4d6c1003c1b65b634e2b041))
+
+## [3.14.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.14.2...v3.14.3) (2025-10-15)
+
+
+### Bug Fixes
+
+* **arcade:** delete old session when room game changes ([98a3a25](https://github.com/antialias/soroban-abacus-flashcards/commit/98a3a2573db51899c41ba02796895d676c4e16ef))
+
+## [3.14.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.14.1...v3.14.2) (2025-10-15)
+
+
+### Bug Fixes
+
+* **room:** update GAME_TYPE_TO_NAME mapping for memory-quiz ([4afa171](https://github.com/antialias/soroban-abacus-flashcards/commit/4afa171af212902120599b3d68f58cfbdf7820b0))
+
+## [3.14.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.14.0...v3.14.1) (2025-10-14)
+
+
+### Bug Fixes
+
+* resolve Memory Quiz room-based multiplayer validation issues ([2ffeade](https://github.com/antialias/soroban-abacus-flashcards/commit/2ffeade43710b5f3fff9991cc84763bbdbf97010))
+
+## [3.14.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.13.7...v3.14.0) (2025-10-14)
+
+
+### Features
+
+* **arcade:** add Change Game functionality for room hosts ([ee39241](https://github.com/antialias/soroban-abacus-flashcards/commit/ee39241e3c9e04202592497d9987eafcb89c00c9))
+* **arcade:** add game selection screen with navigation to room page ([4124f1c](https://github.com/antialias/soroban-abacus-flashcards/commit/4124f1cc081f5cb9d6f450f3c2e0cca8a247deba))
+
+
+### Bug Fixes
+
+* **player-config:** correct label positioning in player settings dialog ([554cc40](https://github.com/antialias/soroban-abacus-flashcards/commit/554cc4063bc756c9c9cd1adf0c1964d3f2f6151b))
+
+
+### Code Refactoring
+
+* implement in-room game selection UI ([f07b96d](https://github.com/antialias/soroban-abacus-flashcards/commit/f07b96d26eb9f63f3ee55f721139c37ccc34c3df))
+* make game_name nullable to support in-room game selection ([a9a6cef](https://github.com/antialias/soroban-abacus-flashcards/commit/a9a6cefafcaf7340902328ef1cb02eb3fdd3aa84))
+* **nav:** rename emphasizeGameContext to emphasizePlayerSelection ([6bb7016](https://github.com/antialias/soroban-abacus-flashcards/commit/6bb7016eea1e8ca40204a921db4a8b8fb9a06f73))
+
+## [3.13.7](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.13.6...v3.13.7) (2025-10-14)
+
+
+### Bug Fixes
+
+* **toast:** scope animations to prevent affecting other UI elements ([245ed8a](https://github.com/antialias/soroban-abacus-flashcards/commit/245ed8a625ba848f8cd79d51bfd88600cd77f0b9))
+
+## [3.13.6](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.13.5...v3.13.6) (2025-10-14)
+
+
+### Bug Fixes
+
+* **nav:** navigate to /arcade/room (not /arcade/rooms/{id}) ([1c55f36](https://github.com/antialias/soroban-abacus-flashcards/commit/1c55f3630cb5f07b685555e41baa5a49314f15a3))
+
+## [3.13.5](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.13.4...v3.13.5) (2025-10-14)
+
+
+### Bug Fixes
+
+* **nav:** navigate to room after creation from (+) menu ([21e6e33](https://github.com/antialias/soroban-abacus-flashcards/commit/21e6e33173e7939102a7e6d6a7bd5168a97a49d6))
+
+
+### Documentation
+
+* add production deployment guide ([6d16436](https://github.com/antialias/soroban-abacus-flashcards/commit/6d164361331fae2135afd84ab6e6f38a241b9170))
+
+## [3.13.4](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.13.3...v3.13.4) (2025-10-14)
+
+
+### Bug Fixes
+
+* **api:** include members and memberPlayers in room creation response ([8320d9e](https://github.com/antialias/soroban-abacus-flashcards/commit/8320d9e730e2b9964e509847dfa504a78b721b5a))
+
+## [3.13.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.13.2...v3.13.3) (2025-10-14)
+
+
+### Bug Fixes
+
+* **migrations:** add migration 0009 for display_password column ([040d749](https://github.com/antialias/soroban-abacus-flashcards/commit/040d7495a0801076b252d2574023f5323540db1a))
+
+
+### Code Refactoring
+
+* replace browser alert() calls with toast notifications ([87ef356](https://github.com/antialias/soroban-abacus-flashcards/commit/87ef35682e5c129033f21b91987fc84a45f43ad3))
+
+## [3.13.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.13.1...v3.13.2) (2025-10-14)
+
+
+### Bug Fixes
+
+* **arcade:** only notify room creator of join requests ([bc571e3](https://github.com/antialias/soroban-abacus-flashcards/commit/bc571e3d0d11fe4142680132d551e25ca626d950))
+
+## [3.13.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.13.0...v3.13.1) (2025-10-14)
+
+
+### Bug Fixes
+
+* **arcade:** allow room creator to rejoin restricted/approval rooms ([654ba19](https://github.com/antialias/soroban-abacus-flashcards/commit/654ba19ccca595d34ad205c036c18afb99a494c7))
+
+## [3.13.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.12.0...v3.13.0) (2025-10-14)
+
+
+### Features
+
+* **moderation:** add inline feedback and persistent password display ([86e3d41](https://github.com/antialias/soroban-abacus-flashcards/commit/86e3d4199628f95048b9265c9de0adfdc2934f93))
+
+## [3.12.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.11.1...v3.12.0) (2025-10-14)
+
+
+### Features
+
+* **moderation:** improve password input with copy button ([2580e47](https://github.com/antialias/soroban-abacus-flashcards/commit/2580e474d08bf91477339e998b2c70962a633f41))
+
+## [3.11.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.11.0...v3.11.1) (2025-10-14)
+
+
+### Bug Fixes
+
+* **moderation:** improve access mode settings UX ([dd9e657](https://github.com/antialias/soroban-abacus-flashcards/commit/dd9e657db85752b32ff91ae1b33a0bf7a7628e07))
+
+## [3.11.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.10.0...v3.11.0) (2025-10-14)
+
+
+### Features
+
+* add name generator button and abacus emoji ([07212e4](https://github.com/antialias/soroban-abacus-flashcards/commit/07212e4df0c7fd4b8cccf935c48b14164df6961d))
+
+
+### Code Refactoring
+
+* make player names abacus and arithmetic themed ([97daad9](https://github.com/antialias/soroban-abacus-flashcards/commit/97daad9abb40a6f4d59ca8a4d4b671822b7b0955))
+
+## [3.10.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.9.2...v3.10.0) (2025-10-14)
+
+
+### Features
+
+* add fun automatic player naming system ([249257c](https://github.com/antialias/soroban-abacus-flashcards/commit/249257c6c77d503b48479065664c96c5de36a234))
+
+## [3.9.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.9.1...v3.9.2) (2025-10-14)
+
+
+### Bug Fixes
+
+* remove duplicate ModerationNotifications causing double toasts ([c6886a0](https://github.com/antialias/soroban-abacus-flashcards/commit/c6886a0e59b3cbf051a828e0157495101cd8c823))
+
+## [3.9.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.9.0...v3.9.1) (2025-10-14)
+
+
+### Bug Fixes
+
+* reset join request toast state when moderation event cleared ([6beb58a](https://github.com/antialias/soroban-abacus-flashcards/commit/6beb58a7b8f8e1841c71729a3517ab459e924aa9))
+
+## [3.9.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.8.1...v3.9.0) (2025-10-14)
+
+
+### Features
+
+* prevent invitations to retired rooms ([a7c3c1f](https://github.com/antialias/soroban-abacus-flashcards/commit/a7c3c1f4cd802985c8f040bc1cdf3ea4482a2fce))
+
+## [3.8.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.8.0...v3.8.1) (2025-10-14)
+
+
+### Bug Fixes
+
+* improve kicked modal message for retired room ejections ([f865ce1](https://github.com/antialias/soroban-abacus-flashcards/commit/f865ce16ecf7648e41549795c8137f4fc33e34ac))
+
+## [3.8.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.7.1...v3.8.0) (2025-10-14)
+
+
+### Features
+
+* implement proper retired room behavior with member expulsion ([a2d5368](https://github.com/antialias/soroban-abacus-flashcards/commit/a2d53680f27db04b2cd09973e62a76c5a7d4ce06))
+
+## [3.7.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.7.0...v3.7.1) (2025-10-14)
+
+
+### Bug Fixes
+
+* improve join request approval error handling with actionable messages ([57bf846](https://github.com/antialias/soroban-abacus-flashcards/commit/57bf8460c8ecff374355bfb93f4b06dfbb148273))
+
+## [3.7.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.6.3...v3.7.0) (2025-10-14)
+
+
+### Features
+
+* add prominent join request approval notifications for room moderators ([036da6d](https://github.com/antialias/soroban-abacus-flashcards/commit/036da6de66ca7d3f459c55df657b04a9e88d9cd3))
+
+## [3.6.3](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.6.2...v3.6.3) (2025-10-14)
+
+
+### Bug Fixes
+
+* update locked room terminology and allow existing members ([1ddf985](https://github.com/antialias/soroban-abacus-flashcards/commit/1ddf985938d9542fe26e44da58234f3d4e3c9543))
+
+## [3.6.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.6.1...v3.6.2) (2025-10-14)
+
+
+### Bug Fixes
+
+* allow join with pending invitation for restricted rooms ([85b2cf9](https://github.com/antialias/soroban-abacus-flashcards/commit/85b2cf98167ccf632ab634a94eb436e1eb584614))
+
+## [3.6.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.6.0...v3.6.1) (2025-10-14)
+
+
+### Bug Fixes
+
+* join user socket channel to receive approval notifications ([7d08fdd](https://github.com/antialias/soroban-abacus-flashcards/commit/7d08fdd90643920857eda09998ac01afbae74154))
+
+
+### Code Refactoring
+
+* remove redundant polling from approval notifications ([0d4f400](https://github.com/antialias/soroban-abacus-flashcards/commit/0d4f400dca02ad9497522c24fded8b6d07d85fd2))
+
+## [3.6.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.5.0...v3.6.0) (2025-10-14)
+
+
+### Features
+
+* add socket listener and polling for approval notifications ([35b4a72](https://github.com/antialias/soroban-abacus-flashcards/commit/35b4a72c8b2f80a74b5d2fe02b048d4ec4d1d6f2))
+
+## [3.5.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.4.0...v3.5.0) (2025-10-14)
+
+
+### Features
+
+* replace access mode dropdown with visual button grid ([e5d0672](https://github.com/antialias/soroban-abacus-flashcards/commit/e5d067205989d7c3105998dcd7d67fd0408f332c))
+
+## [3.4.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.3.1...v3.4.0) (2025-10-14)
+
+
+### Features
+
+* add waiting state for approval requests in JoinRoomModal ([f9b0429](https://github.com/antialias/soroban-abacus-flashcards/commit/f9b0429a2e2d22944acba66009dd87a9d9eb28c2))
+
+## [3.3.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.3.0...v3.3.1) (2025-10-14)
+
+
+### Bug Fixes
+
+* add POST handler for join requests API endpoint ([d3e5cdf](https://github.com/antialias/soroban-abacus-flashcards/commit/d3e5cdfc54f2749f27c6f8b8db854a8d0b6029f8))
+
+## [3.3.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.2.1...v3.3.0) (2025-10-14)
+
+
+### Features
+
+* implement approval request flow for share links ([4a6b3ca](https://github.com/antialias/soroban-abacus-flashcards/commit/4a6b3cabe5c6aa42f4fa00ed09f9b3713f097539))
+
 ## [3.2.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v3.2.0...v3.2.1) (2025-10-14)
 
 

apps/web/.claude/CLAUDE.md

@@ -89,3 +89,50 @@ npm run check          # Biome check (format + lint + organize imports)
 ---
 
 **Remember: Always run `npm run pre-commit` before creating commits.**
+
+## Known Issues
+
+### @soroban/abacus-react TypeScript Module Resolution
+
+**Issue:** TypeScript reports that `AbacusReact`, `useAbacusConfig`, and other exports do not exist from the `@soroban/abacus-react` package, even though:
+- The package builds successfully
+- The exports are correctly defined in `dist/index.d.ts`
+- The imports work at runtime
+- 20+ files across the codebase use these same imports without issue
+
+**Impact:** `npm run type-check` will report errors for any files importing from `@soroban/abacus-react`.
+
+**Workaround:** This is a known pre-existing issue. When running pre-commit checks, TypeScript errors related to `@soroban/abacus-react` imports can be ignored. Focus on:
+- New TypeScript errors in your changed files (excluding @soroban/abacus-react imports)
+- Format checks
+- 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/DEPLOYMENT.md

@@ -0,0 +1,191 @@
+# Production Deployment Guide
+
+This document describes the production deployment infrastructure and procedures for the abaci.one web application.
+
+## Infrastructure Overview
+
+### Production Server
+- **Host**: `nas.home.network` (Synology NAS DS923+)
+- **Access**: SSH access required
+  - Must be connected to network at **730 N. Oak Park Ave**
+  - Server is not accessible from external networks
+- **Project Directory**: `/volume1/homes/antialias/projects/abaci.one`
+
+### Docker Configuration
+- **Docker binary**: `/usr/local/bin/docker`
+- **Docker Compose binary**: `/usr/local/bin/docker-compose`
+- **Container name**: `soroban-abacus-flashcards`
+- **Image**: `ghcr.io/antialias/soroban-abacus-flashcards:latest`
+
+### Auto-Deployment
+- **Watchtower** monitors and auto-updates containers
+- **Update frequency**: Every **5 minutes**
+- Watchtower pulls latest images and restarts containers automatically
+- No manual intervention required for deployments after pushing to main
+
+## Database Management
+
+### Location
+- **Database path**: `data/sqlite.db` (relative to project directory)
+- **WAL files**: `data/sqlite.db-shm` and `data/sqlite.db-wal`
+
+### Migrations
+- **Automatic**: Migrations run on server startup via `server.js`
+- **Migration folder**: `./drizzle`
+- **Process**:
+  1. Server starts
+  2. Logs: `🔄 Running database migrations...`
+  3. Drizzle migrator runs all pending migrations
+  4. Logs: `✅ Migrations complete` (on success)
+  5. Logs: `❌ Migration failed: [error]` (on failure, process exits)
+
+### Nuke and Rebuild Database
+If you need to completely reset the production database:
+
+```bash
+# SSH into the server
+ssh nas.home.network
+
+# Navigate to project directory
+cd /volume1/homes/antialias/projects/abaci.one
+
+# Stop the container
+/usr/local/bin/docker-compose down
+
+# Remove database files
+rm -f data/sqlite.db data/sqlite.db-shm data/sqlite.db-wal
+
+# Restart container (migrations will rebuild DB)
+/usr/local/bin/docker-compose up -d
+
+# Check logs to verify migration success
+/usr/local/bin/docker logs soroban-abacus-flashcards | grep -E '(Migration|Starting)'
+```
+
+## CI/CD Pipeline
+
+### GitHub Actions
+When code is pushed to `main` branch:
+
+1. **Workflows triggered**:
+   - `Build and Deploy` - Builds Docker image and pushes to GHCR
+   - `Release` - Manages semantic versioning and releases
+   - `Verify Examples` - Runs example tests
+   - `Deploy Storybooks to GitHub Pages` - Publishes Storybook
+
+2. **Image build**:
+   - Built image is tagged as `latest`
+   - Pushed to GitHub Container Registry (ghcr.io)
+   - Typically completes within 1-2 minutes
+
+3. **Deployment**:
+   - Watchtower detects new image (within 5 minutes)
+   - Pulls latest image
+   - Recreates and restarts container
+   - Total deployment time: ~5-7 minutes from push to production
+
+## Manual Deployment Procedures
+
+### Force Pull Latest Image
+If you need to immediately deploy without waiting for Watchtower:
+
+```bash
+ssh nas.home.network "cd /volume1/homes/antialias/projects/abaci.one && /usr/local/bin/docker-compose pull && /usr/local/bin/docker-compose up -d"
+```
+
+### Check Container Status
+```bash
+ssh nas.home.network "/usr/local/bin/docker ps | grep -E '(soroban|abaci)'"
+```
+
+### View Logs
+```bash
+# Recent logs
+ssh nas.home.network "/usr/local/bin/docker logs --tail 100 soroban-abacus-flashcards"
+
+# Follow logs in real-time
+ssh nas.home.network "/usr/local/bin/docker logs -f soroban-abacus-flashcards"
+
+# Search for specific patterns
+ssh nas.home.network "/usr/local/bin/docker logs soroban-abacus-flashcards" | grep -i "error"
+```
+
+### Restart Container
+```bash
+ssh nas.home.network "cd /volume1/homes/antialias/projects/abaci.one && /usr/local/bin/docker-compose restart"
+```
+
+## Deployment Script
+
+The project includes a deployment script at `nas-deployment/deploy.sh` for manual deployments.
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Migration Failures
+**Symptom**: Container keeps restarting, logs show migration errors
+
+**Solution**:
+1. Check migration files in `drizzle/` directory
+2. Verify `drizzle/meta/_journal.json` is up to date
+3. If migrations are corrupted, may need to nuke database (see above)
+
+#### 2. Container Not Updating
+**Symptom**: Changes pushed but production still shows old code
+
+**Possible causes**:
+- GitHub Actions build failed - check workflow status with `gh run list`
+- Watchtower not running - check with `docker ps | grep watchtower`
+- Image not pulled - manually pull with `docker-compose pull`
+
+**Solution**:
+```bash
+# Force pull and restart
+ssh nas.home.network "cd /volume1/homes/antialias/projects/abaci.one && /usr/local/bin/docker-compose pull && /usr/local/bin/docker-compose up -d"
+```
+
+#### 3. Missing Database Columns
+**Symptom**: Errors like `SqliteError: no such column: "column_name"`
+
+**Cause**: Migration not registered or not run
+
+**Solution**:
+1. Verify migration exists in `drizzle/` directory
+2. Check migration is registered in `drizzle/meta/_journal.json`
+3. If migration is new, restart container to run migrations
+4. If migration is malformed, fix it and nuke database
+
+#### 4. API Returns Unexpected Response
+**Symptom**: Client shows errors but API appears to work
+
+**Debugging**:
+1. Test API directly with curl: `curl -X POST 'https://abaci.one/api/arcade/rooms' -H 'Content-Type: application/json' -d '...'`
+2. Check production logs for errors
+3. Verify container is running latest image:
+   ```bash
+   ssh nas.home.network "/usr/local/bin/docker inspect soroban-abacus-flashcards --format '{{.Created}}'"
+   ```
+4. Compare with commit timestamp: `git log --format="%ci" -1`
+
+## Environment Variables
+
+Production environment variables are configured in the docker-compose.yml file on the server. Common variables:
+
+- `NEXT_PUBLIC_URL` - Base URL for the application
+- `DATABASE_URL` - SQLite database path
+- Additional variables may be set in `.env.production` or docker-compose.yml
+
+## Network Configuration
+
+- **Reverse Proxy**: Traefik
+- **HTTPS**: Automatic via Traefik with Let's Encrypt
+- **Domain**: abaci.one
+- **Exposed Port**: 3000 (internal to Docker network)
+
+## Security Notes
+
+- Production database contains user data and should be handled carefully
+- SSH access is restricted to local network only
+- Docker container runs with appropriate user permissions
+- Secrets are managed via environment variables, not committed to repo

apps/web/.claude/GAME_SETTINGS_PERSISTENCE.md

@@ -0,0 +1,421 @@
+# Game Settings Persistence Architecture
+
+## Overview
+
+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.
+
+## Database Schema
+
+Settings are stored in the `room_game_configs` table:
+
+```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
+{
+  "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)
+  }
+}
+```
+
+### 3. Socket Server (Session Creation)
+**Location:** `src/socket-server.ts:70-90`
+
+**Responsibilities:**
+- Create initial arcade session when user joins room
+- Read saved settings using `getGameConfig()` helper
+- Pass settings to validator's `getInitialState()`
+
+**Example:**
+```typescript
+const room = await getRoomById(roomId)
+const validator = getValidator(room.gameName as GameName)
+
+// 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:**
+- Read settings from `roomData.gameConfig[gameName]`
+- Merge with `initialState` defaults
+- Works transparently with new backend structure
+
+**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,
+  }
+}, [roomData?.gameConfig])
+```
+
+## Common Bugs and Solutions
+
+### Bug #1: Settings Not Persisting
+**Symptom:** Settings reset to defaults after game switch
+
+**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)
+```
+
+### Bug #2: TypeScript Errors About Missing Fields
+**Symptom:** `Property '{field}' is missing in type ...`
+
+**Root Cause:** Validator's `getInitialState()` signature doesn't match shared config type
+
+**Solution:** Import and use the shared config type:
+```typescript
+// ❌ WRONG
+getInitialState(config: {
+  selectedCount: number
+  displayTime: number
+  // Missing playMode!
+}): SorobanQuizState
+
+// ✅ CORRECT
+import type { MemoryQuizGameConfig } from '@/lib/arcade/game-configs'
+
+getInitialState(config: MemoryQuizGameConfig): SorobanQuizState
+```
+
+### Bug #3: Settings Wiped When Returning to Game Selection
+**Symptom:** Settings reset when going back to game selection
+
+**Root Cause:** Sending `gameConfig: null` in PATCH request
+
+**Solution:** Only send `gameName: null`, don't touch gameConfig:
+```typescript
+// ❌ WRONG
+body: JSON.stringify({ gameName: null, gameConfig: null })
+
+// ✅ CORRECT
+body: JSON.stringify({ gameName: null })
+```
+
+## Debugging Checklist
+
+When a setting doesn't persist:
+
+1. **Check database:**
+   - Query `room_game_configs` table
+   - Verify row exists for room + game
+   - Verify JSON config has correct structure
+
+2. **Check API write path:**
+   - `/api/arcade/rooms/[roomId]/settings` logs
+   - Verify `setGameConfig()` is called
+   - Check for errors in console
+
+3. **Check API read path:**
+   - `/api/arcade/rooms/current` logs
+   - Verify `getAllGameConfigs()` returns data
+   - Check `room.gameConfig` in response
+
+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 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
+
+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.
+
+## Migration Notes
+
+**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/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/.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

@@ -46,7 +46,39 @@
       "Bash(npx @biomejs/biome check:*)",
       "Bash(printf '\\n')",
       "Bash(npm install bcryptjs)",
-      "Bash(npm install:*)"
+      "Bash(npm install:*)",
+      "Bash(pnpm add:*)",
+      "Bash(sqlite3:*)",
+      "Bash(shasum:*)",
+      "Bash(awk:*)",
+      "Bash(if npx tsc --noEmit)",
+      "Bash(then echo \"TypeScript errors found in our files\")",
+      "Bash(else echo \"✓ No TypeScript errors in our modified files\")",
+      "Bash(fi)",
+      "Bash(then echo \"TypeScript errors found\")",
+      "Bash(else echo \"✓ No TypeScript errors in join page\")",
+      "Bash(npx @biomejs/biome format:*)",
+      "Bash(npx drizzle-kit generate:*)",
+      "Bash(ssh nas.home.network \"docker ps | grep -E ''soroban|abaci|web''\")",
+      "Bash(ssh:*)",
+      "Bash(printf \"\\n\\n\")",
+      "Bash(timeout 10 npx drizzle-kit generate:*)",
+      "Bash(git checkout:*)",
+      "Bash(git log:*)",
+      "Bash(python3:*)",
+      "Bash(git reset:*)",
+      "Bash(lsof:*)",
+      "Bash(killall:*)",
+      "Bash(echo:*)",
+      "Bash(git restore:*)",
+      "Bash(timeout 10 npm run dev:*)",
+      "Bash(timeout 30 npm run dev)",
+      "Bash(pkill:*)",
+      "Bash(for i in {1..30})",
+      "Bash(do gh run list --limit 1 --json conclusion,status,name,databaseId --jq '.[0] | \"\"\\(.status) - \\(.conclusion // \"\"running\"\") - Run ID: \\(.databaseId)\"\"')",
+      "Bash(tsc:*)",
+      "Bash(tsc-alias:*)",
+      "Bash(npx tsc-alias:*)"
     ],
     "deny": [],
     "ask": []

apps/web/docs/AUDIT_2_ARCHITECTURE_QUALITY.md

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

apps/web/docs/AUDIT_MODULAR_GAME_SYSTEM.md

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

apps/web/docs/arcade-game-architecture.md

@@ -0,0 +1,792 @@
+# Arcade Game Architecture
+
+> **Design Philosophy**: Modular, type-safe, multiplayer-first game development with real-time synchronization
+
+---
+
+## Table of Contents
+
+- [Design Goals](#design-goals)
+- [Architecture Overview](#architecture-overview)
+- [Core Concepts](#core-concepts)
+- [Implementation Details](#implementation-details)
+- [Design Decisions](#design-decisions)
+- [Lessons Learned](#lessons-learned)
+- [Future Improvements](#future-improvements)
+
+---
+
+## Design Goals
+
+### Primary Goals
+
+1. **Modularity**
+   - Each game is a self-contained module
+   - Games can be added/removed without affecting the core system
+   - No tight coupling between games and infrastructure
+
+2. **Type Safety**
+   - Full TypeScript support throughout the stack
+   - Compile-time validation of game definitions
+   - Type-safe move validation and state management
+
+3. **Multiplayer-First**
+   - Real-time state synchronization via WebSocket
+   - Optimistic updates for instant feedback
+   - Server-authoritative validation to prevent cheating
+
+4. **Developer Experience**
+   - Simple, intuitive API for game creators
+   - Minimal boilerplate
+   - Clear separation of concerns
+   - Comprehensive error messages
+
+5. **Consistency**
+   - Shared navigation and UI components
+   - Standardized player management
+   - Common error handling patterns
+   - Unified room/lobby experience
+
+### Non-Goals
+
+- Supporting non-multiplayer games (use existing game routes for that)
+- Backwards compatibility with old game implementations
+- Supporting games outside the monorepo
+
+---
+
+## Architecture Overview
+
+### System Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Application Layer                         │
+│  - GameSelector (game discovery)                            │
+│  - Room management                                          │
+│  - Player management                                        │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Registry Layer                             │
+│  - Game registration                                        │
+│  - Game discovery (getGame, getAllGames)                    │
+│  - Manifest validation                                      │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      SDK Layer                               │
+│  - Stable API surface                                       │
+│  - React hooks (useArcadeSession, etc.)                     │
+│  - Type definitions                                         │
+│  - Utilities (buildPlayerMetadata, etc.)                    │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Game Layer                                 │
+│  Individual games (number-guesser, math-sprint, etc.)      │
+│  Each game: Validator + Provider + Components + Types      │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                Infrastructure Layer                          │
+│  - WebSocket (useArcadeSocket)                              │
+│  - Optimistic state (useOptimisticGameState)                │
+│  - Database (room data, player data)                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow: Move Execution
+
+```
+1. User clicks button
+   │
+   ▼
+2. Provider calls sendMove()
+   │
+   ▼
+3. useArcadeSession
+   ├─→ Apply optimistically (instant UI update)
+   └─→ Send via WebSocket to server
+   │
+   ▼
+4. Server validates move
+   │
+   ├─→ VALID:
+   │   ├─→ Apply to server state
+   │   ├─→ Increment version
+   │   ├─→ Broadcast to all clients
+   │   └─→ Client: Remove from pending, confirm state
+   │
+   └─→ INVALID:
+       ├─→ Send rejection message
+       └─→ Client: Rollback optimistic state, show error
+```
+
+---
+
+## Core Concepts
+
+### 1. Game Definition
+
+A game is defined by five core pieces:
+
+```typescript
+interface GameDefinition<TConfig, TState, TMove> {
+  manifest: GameManifest          // Display metadata
+  Provider: GameProviderComponent // React context provider
+  GameComponent: GameComponent    // Main UI component
+  validator: GameValidator        // Server validation logic
+  defaultConfig: TConfig          // Default settings
+}
+```
+
+**Why this structure?**
+- `manifest`: Declarative metadata for discovery and UI
+- `Provider`: Encapsulates all game logic and state management
+- `GameComponent`: Pure UI component, no business logic
+- `validator`: Server-authoritative validation prevents cheating
+- `defaultConfig`: Sensible defaults, can be overridden per-room
+
+### 2. Validator (Server-Side)
+
+The validator is the **source of truth** for game logic.
+
+```typescript
+interface GameValidator<TState, TMove> {
+  validateMove(state: TState, move: TMove): ValidationResult
+  isGameComplete(state: TState): boolean
+  getInitialState(config: unknown): TState
+}
+```
+
+**Key Principles:**
+- **Pure functions**: No side effects, no I/O
+- **Deterministic**: Same input → same output
+- **Complete game logic**: All rules enforced here
+- **Returns new state**: Immutable state updates
+
+**Why server-side?**
+- Prevents cheating (client can't fake moves)
+- Single source of truth (no client/server divergence)
+- Easier debugging (all logic in one place)
+- Can add server-only features (analytics, anti-cheat)
+
+### 3. Provider (Client-Side)
+
+The provider manages client state and provides a clean API.
+
+```typescript
+interface GameContextValue {
+  state: GameState           // Current game state
+  lastError: string | null   // Last validation error
+  startGame: () => void      // Action creators
+  makeMove: (data) => void   // ...
+  clearError: () => void
+  exitSession: () => void
+}
+```
+
+**Responsibilities:**
+- Wrap `useArcadeSession` with game-specific actions
+- Build player metadata from game mode context
+- Provide clean, typed API to components
+- Handle room config persistence
+
+**Anti-Pattern:** Don't put game logic here. The provider is a **thin wrapper** around the SDK.
+
+### 4. Optimistic Updates
+
+The system uses **optimistic UI** for instant feedback:
+
+1. User makes a move → UI updates immediately
+2. Move sent to server for validation
+3. Server validates:
+   - ✓ Valid → Confirm optimistic state
+   - ✗ Invalid → Rollback and show error
+
+**Why optimistic updates?**
+- Instant feedback (no perceived latency)
+- Better UX for fast-paced games
+- Handles network issues gracefully
+
+**Tradeoff:**
+- More complex state management
+- Need rollback logic
+- Potential for flashing/jumpy UI on rollback
+
+**When NOT to use:**
+- High-stakes actions (payments, permanent changes)
+- Actions with irreversible side effects
+- When server latency is acceptable
+
+### 5. State Synchronization
+
+State is synchronized across all clients in a room:
+
+```
+Client A makes move → Server validates → Broadcast to all clients
+  ├─→ Client A: Confirm optimistic update
+  ├─→ Client B: Apply server state
+  └─→ Client C: Apply server state
+```
+
+**Conflict Resolution:**
+- Server state is **always authoritative**
+- Version numbers prevent out-of-order updates
+- Pending moves are reapplied after server sync
+
+---
+
+## Implementation Details
+
+### SDK Design
+
+The SDK provides a **stable API surface** that games import from:
+
+```typescript
+// ✅ GOOD: Import from SDK
+import { useArcadeSession, type GameDefinition } from '@/lib/arcade/game-sdk'
+
+// ❌ BAD: Import internal implementation
+import { useArcadeSocket } from '@/hooks/useArcadeSocket'
+```
+
+**Why?**
+- **Stability**: Internal APIs can change, SDK stays stable
+- **Discoverability**: One place to find all game APIs
+- **Encapsulation**: Hide implementation details
+- **Documentation**: SDK is the "public API" to document
+
+**SDK Exports:**
+
+```typescript
+// Types
+export type { GameDefinition, GameValidator, GameState, GameMove, ... }
+
+// React Hooks
+export { useArcadeSession, useRoomData, useGameMode, useViewerId }
+
+// Utilities
+export { defineGame, buildPlayerMetadata, loadManifest }
+```
+
+### Registry Pattern
+
+Games register themselves on module load:
+
+```typescript
+// game-registry.ts
+const registry = new Map<string, GameDefinition>()
+
+export function registerGame(game: GameDefinition) {
+  registry.set(game.manifest.name, game)
+}
+
+export function getGame(name: string) {
+  return registry.get(name)
+}
+
+// At bottom of file
+import { numberGuesserGame } from '@/arcade-games/number-guesser'
+registerGame(numberGuesserGame)
+```
+
+**Why self-registration?**
+- No central "game list" to maintain
+- Games are automatically discovered
+- Import errors are caught at module load time
+- Easy to enable/disable games (comment out registration)
+
+**Alternative Considered:** Auto-discovery via file system
+
+```typescript
+// ❌ Rejected: Magic, fragile, breaks with bundlers
+const games = import.meta.glob('../arcade-games/*/index.ts')
+```
+
+### Player Metadata
+
+Player metadata is built from multiple sources:
+
+```typescript
+function buildPlayerMetadata(
+  playerIds: string[],
+  existingMetadata: Record<string, unknown>,
+  playerMap: Map<string, Player>,
+  viewerId?: string
+): Record<string, PlayerMetadata>
+```
+
+**Sources:**
+1. `playerIds`: Which players are active
+2. `existingMetadata`: Carry over existing data (for reconnects)
+3. `playerMap`: Player details (name, emoji, color, userId)
+4. `viewerId`: Current user (for ownership checks)
+
+**Why so complex?**
+- Players can be local or remote (in rooms)
+- Need to preserve data across state updates
+- Must map player IDs to user IDs for permissions
+- Support for guest players vs. authenticated users
+
+### Move Validation Flow
+
+```typescript
+// 1. Client sends move
+sendMove({
+  type: 'MAKE_GUESS',
+  playerId: 'player-123',
+  userId: 'user-456',
+  timestamp: Date.now(),
+  data: { guess: 42 }
+})
+
+// 2. Optimistic update (client-side)
+const optimisticState = applyMove(currentState, move)
+setOptimisticState(optimisticState)
+
+// 3. Server validates
+const result = validator.validateMove(serverState, move)
+
+// 4a. Valid → Broadcast new state
+if (result.valid) {
+  serverState = result.newState
+  version++
+  broadcastToAllClients({ gameState: serverState, version })
+}
+
+// 4b. Invalid → Send rejection
+else {
+  sendToClient({ error: result.error, move })
+}
+
+// 5. Client handles response
+// Valid: Confirm optimistic state, remove from pending
+// Invalid: Rollback optimistic state, show error
+```
+
+**Key Points:**
+- Optimistic update happens **before** server response
+- Server is **authoritative** (client state can be overwritten)
+- Version numbers prevent stale updates
+- Rejected moves trigger error UI
+
+---
+
+## Design Decisions
+
+### Decision: Server-Authoritative Validation
+
+**Choice:** All game logic runs on server, client is "dumb"
+
+**Rationale:**
+- Prevents cheating (client can't manipulate state)
+- Single source of truth (no client/server divergence)
+- Easier testing (one codebase for game logic)
+- Can add server-side features (analytics, matchmaking)
+
+**Tradeoff:**
+- ➕ Secure, consistent, easier to maintain
+- ➖ Network latency affects UX (mitigated by optimistic updates)
+- ➖ Can't play offline
+
+**Alternative Considered:** Client-side validation + server verification
+- Rejected: Duplicate logic, potential for divergence
+
+### Decision: Optimistic Updates
+
+**Choice:** Apply moves immediately, rollback on rejection
+
+**Rationale:**
+- Instant feedback (no perceived latency)
+- Better UX for turn-based games
+- Handles network issues gracefully
+
+**Tradeoff:**
+- ➕ Feels instant, smooth UX
+- ➖ More complex state management
+- ➖ Potential for jarring rollbacks
+
+**When to disable:** High-stakes actions (payments, permanent bans)
+
+### Decision: TypeScript Everywhere
+
+**Choice:** Full TypeScript on client and server
+
+**Rationale:**
+- Compile-time validation catches bugs early
+- Better IDE support (autocomplete, refactoring)
+- Self-documenting code (types as documentation)
+- Easier refactoring (compiler catches breakages)
+
+**Tradeoff:**
+- ➕ Fewer runtime errors, better DX
+- ➖ Slower initial development (must define types)
+- ➖ Learning curve for new developers
+
+**Alternative Considered:** JavaScript with JSDoc
+- Rejected: JSDoc is not type-safe, easy to drift
+
+### Decision: React Context for State
+
+**Choice:** Each game has a Provider that wraps game logic
+
+**Rationale:**
+- Natural React pattern
+- Easy to compose (Provider wraps GameComponent)
+- No prop drilling
+- Easy to test (can provide mock context)
+
+**Tradeoff:**
+- ➕ Clean component APIs, easy to understand
+- ➖ Can't use context outside React tree
+- ➖ Re-renders if not memoized carefully
+
+**Alternative Considered:** Zustand/Redux
+- Rejected: Overkill for game-specific state, harder to isolate per-game
+
+### Decision: Phase-Based UI
+
+**Choice:** Each game has distinct phases (setup, playing, results)
+
+**Rationale:**
+- Clear separation of concerns
+- Easy to understand game flow
+- Each phase is independently testable
+- Natural mapping to game states
+
+**Tradeoff:**
+- ➕ Organized, predictable
+- ➖ Some duplication (multiple components)
+- ➖ Can't have overlapping phases
+
+**Pattern:**
+
+```typescript
+{state.gamePhase === 'setup' && <SetupPhase />}
+{state.gamePhase === 'playing' && <PlayingPhase />}
+{state.gamePhase === 'results' && <ResultsPhase />}
+```
+
+### Decision: Player Order from Set Iteration
+
+**Choice:** Don't sort player arrays, use Set iteration order
+
+**Rationale:**
+- Set order is consistent within a session
+- Matches UI display order (PageWithNav uses same Set)
+- Avoids alphabetical bias (first player isn't always "AAA")
+
+**Tradeoff:**
+- ➕ UI and game logic always match
+- ➖ Order is not predictable across sessions
+- ➖ Different players see different orders (based on join time)
+
+**Why not sort?**
+- Creates mismatch: UI shows Set order, game uses sorted order
+- Causes "skipping first player" bug (discovered in Number Guesser)
+
+### Decision: No Optimistic Logic in Provider
+
+**Choice:** Provider's `applyMove` just returns current state
+
+```typescript
+const { state, sendMove } = useArcadeSession({
+  applyMove: (state, move) => state // Don't apply, wait for server
+})
+```
+
+**Rationale:**
+- Keeps client logic minimal (less code to maintain)
+- Prevents client/server logic divergence
+- Server is authoritative (no client-side cheats)
+
+**Tradeoff:**
+- ➕ Simple, secure
+- ➖ Slightly slower UX (wait for server)
+
+**When to use client-side `applyMove`:**
+- Very fast-paced games (60fps animations)
+- Purely cosmetic updates (particles, sounds)
+- Never for game logic (scoring, winning, etc.)
+
+---
+
+## Lessons Learned
+
+### From Number Guesser Implementation
+
+#### 1. Type Coercion is Critical
+
+**Problem:** WebSocket/JSON serialization converts numbers to strings.
+
+```typescript
+// Client sends
+sendMove({ data: { guess: 42 } })
+
+// Server receives
+move.data.guess === "42" // String! 😱
+```
+
+**Solution:** Explicit coercion in validator
+
+```typescript
+validateMove(state, move) {
+  case 'MAKE_GUESS':
+    return this.validateGuess(state, Number(move.data.guess))
+}
+```
+
+**Lesson:** Always coerce types from `move.data` in validator.
+
+**Symptom Observed:** User reported "first guess always rejected, second guess always correct" which was caused by:
+- First guess: `"42" < 1` evaluates to `false` (string comparison)
+- Validator thinks it's valid, calculates distance as `NaN`
+- `NaN === 0` is false, so guess is "wrong"
+- Second guess: `"50" < 1` also evaluates oddly, but `Math.abs("50" - 42)` coerces correctly
+- The behavior was unpredictable due to mixed type coercion
+
+**Root Cause:** String comparison operators (`<`, `>`) have weird behavior with string numbers.
+
+#### 2. Player Ordering Must Be Consistent
+
+**Problem:** Set iteration order differed from sorted order, causing "skipped player" bug.
+
+**Root Cause:**
+- UI used `Array.from(Set)` → Set iteration order
+- Game used `Array.from(Set).sort()` → Alphabetical order
+- Leftmost UI player ≠ First game player
+
+**Solution:** Remove `.sort()` everywhere, use raw Set order.
+
+**Lesson:** Player order must be identical in UI and game logic.
+
+#### 3. Error Feedback is Essential
+
+**Problem:** Moves rejected silently, users confused.
+
+**Solution:** `lastError` state with auto-dismiss UI.
+
+```typescript
+const { lastError, clearError } = useArcadeSession()
+
+{lastError && (
+  <ErrorBanner message={lastError} onDismiss={clearError} />
+)}
+```
+
+**Lesson:** Always surface validation errors to users.
+
+#### 4. Turn Indicators Improve UX
+
+**Problem:** Players didn't know whose turn it was.
+
+**Solution:** `currentPlayerId` prop to `PageWithNav`.
+
+```typescript
+<PageWithNav
+  currentPlayerId={state.currentPlayer}
+  playerScores={state.scores}
+>
+```
+
+**Lesson:** Visual feedback for turn-based games is critical.
+
+#### 5. Round vs. Game Completion
+
+**Problem:** Validator checked `!state.winner` for next round, but winner is only set when game ends.
+
+**Root Cause:** Confused "round complete" (someone guessed) with "game complete" (someone won).
+
+**Solution:** Check if last guess was correct:
+
+```typescript
+const roundComplete = state.guesses.length > 0 &&
+  state.guesses[state.guesses.length - 1].distance === 0
+```
+
+**Lesson:** Be precise about what "complete" means (round vs. game).
+
+#### 6. Debug Logging is Invaluable
+
+**Problem:** Type issues caused subtle bugs (always correct guess).
+
+**Solution:** Add logging in validator:
+
+```typescript
+console.log('[NumberGuesser] Validating guess:', {
+  guess,
+  guessType: typeof guess,
+  secretNumber: state.secretNumber,
+  secretNumberType: typeof state.secretNumber,
+  distance: Math.abs(guess - state.secretNumber)
+})
+```
+
+**Lesson:** Log types and values during development.
+
+---
+
+## Future Improvements
+
+### 1. Automated Testing
+
+**Current State:** Manual testing only
+
+**Proposal:**
+- Unit tests for validators (pure functions, easy to test)
+- Integration tests for Provider + useArcadeSession
+- E2E tests for full game flows (Playwright)
+
+**Example:**
+
+```typescript
+describe('NumberGuesserValidator', () => {
+  it('should reject out-of-bounds guess', () => {
+    const validator = new NumberGuesserValidator()
+    const state = { minNumber: 1, maxNumber: 100, ... }
+    const move = { type: 'MAKE_GUESS', data: { guess: 200 } }
+
+    const result = validator.validateMove(state, move)
+
+    expect(result.valid).toBe(false)
+    expect(result.error).toContain('must be between')
+  })
+})
+```
+
+### 2. Move History / Replay
+
+**Current State:** No move history
+
+**Proposal:**
+- Store all moves in database
+- Allow "replay" of games
+- Enable undo/redo (for certain games)
+- Analytics on player behavior
+
+**Schema:**
+
+```typescript
+interface GameSession {
+  id: string
+  roomId: string
+  gameType: string
+  moves: GameMove[]
+  finalState: GameState
+  startTime: number
+  endTime: number
+}
+```
+
+### 3. Game Analytics
+
+**Current State:** No analytics
+
+**Proposal:**
+- Track game completions, durations, winners
+- Player skill ratings (Elo, TrueSkill)
+- Popular games dashboard
+- A/B testing for game variants
+
+### 4. Spectator Mode
+
+**Current State:** Only active players can view game
+
+**Proposal:**
+- Allow non-players to watch
+- Spectators can't send moves (read-only)
+- Show spectator count in room
+
+**Implementation:**
+
+```typescript
+interface RoomMember {
+  userId: string
+  role: 'player' | 'spectator' | 'host'
+}
+```
+
+### 5. Game Variants
+
+**Current State:** One config per game
+
+**Proposal:**
+- Preset variants (Easy, Medium, Hard)
+- Custom rules per room
+- "House rules" feature
+
+**Example:**
+
+```typescript
+const variants = {
+  beginner: { minNumber: 1, maxNumber: 20, roundsToWin: 1 },
+  standard: { minNumber: 1, maxNumber: 100, roundsToWin: 3 },
+  expert: { minNumber: 1, maxNumber: 1000, roundsToWin: 5 },
+}
+```
+
+### 6. Tournaments / Brackets
+
+**Current State:** Single-room games only
+
+**Proposal:**
+- Multi-round tournaments
+- Bracket generation
+- Leaderboards
+
+### 7. Game Mod Support
+
+**Current State:** Games are hard-coded
+
+**Proposal:**
+- Load games from external bundles
+- Community-created games
+- Sandboxed execution (Deno, WASM)
+
+**Challenges:**
+- Security (untrusted code)
+- Type safety (dynamic loading)
+- Versioning (breaking changes)
+
+### 8. Voice/Video Chat
+
+**Current State:** Text chat only (if implemented)
+
+**Proposal:**
+- WebRTC voice/video
+- Per-room channels
+- Mute/kick controls
+
+---
+
+## Appendix: Key Files Reference
+
+| Path | Purpose |
+|------|---------|
+| `src/lib/arcade/game-sdk/index.ts` | SDK exports (public API) |
+| `src/lib/arcade/game-registry.ts` | Game registration |
+| `src/lib/arcade/manifest-schema.ts` | Manifest validation |
+| `src/hooks/useArcadeSession.ts` | Session management hook |
+| `src/hooks/useArcadeSocket.ts` | WebSocket connection |
+| `src/hooks/useOptimisticGameState.ts` | Optimistic state management |
+| `src/contexts/GameModeContext.tsx` | Player management |
+| `src/components/PageWithNav.tsx` | Game navigation wrapper |
+| `src/arcade-games/number-guesser/` | Example game implementation |
+
+---
+
+## Related Documentation
+
+- [Game Development Guide](../arcade-games/README.md) - Step-by-step guide to creating games
+- [API Reference](./arcade-game-api-reference.md) - Complete SDK API documentation (TODO)
+- [Deployment Guide](./arcade-game-deployment.md) - How to deploy new games (TODO)
+
+---
+
+*Last Updated: 2025-10-15*

apps/web/drizzle/0009_add_display_password.sql

@@ -0,0 +1,2 @@
+-- Add display_password column to arcade_rooms for showing plain text passwords to room owners
+ALTER TABLE `arcade_rooms` ADD `display_password` text(100);

apps/web/drizzle/0010_make_game_name_nullable.sql

@@ -0,0 +1,42 @@
+-- Make game_name and game_config nullable to support game selection in room
+-- SQLite doesn't support ALTER COLUMN, so we need to recreate the table
+
+PRAGMA foreign_keys=OFF;--> statement-breakpoint
+
+-- Create temporary table with correct schema
+CREATE TABLE `arcade_rooms_new` (
+	`id` text PRIMARY KEY NOT NULL,
+	`code` text(6) NOT NULL,
+	`name` text(50),
+	`created_by` text NOT NULL,
+	`creator_name` text(50) NOT NULL,
+	`created_at` integer NOT NULL,
+	`last_activity` integer NOT NULL,
+	`ttl_minutes` integer DEFAULT 60 NOT NULL,
+	`access_mode` text DEFAULT 'open' NOT NULL,
+	`password` text(255),
+	`display_password` text(100),
+	`game_name` text,
+	`game_config` text,
+	`status` text DEFAULT 'lobby' NOT NULL,
+	`current_session_id` text,
+	`total_games_played` integer DEFAULT 0 NOT NULL
+);--> statement-breakpoint
+
+-- Copy all data
+INSERT INTO `arcade_rooms_new`
+SELECT `id`, `code`, `name`, `created_by`, `creator_name`, `created_at`,
+       `last_activity`, `ttl_minutes`, `access_mode`, `password`, `display_password`,
+       `game_name`, `game_config`, `status`, `current_session_id`, `total_games_played`
+FROM `arcade_rooms`;--> statement-breakpoint
+
+-- Drop old table
+DROP TABLE `arcade_rooms`;--> statement-breakpoint
+
+-- Rename new table
+ALTER TABLE `arcade_rooms_new` RENAME TO `arcade_rooms`;--> statement-breakpoint
+
+-- Recreate index
+CREATE UNIQUE INDEX `arcade_rooms_code_unique` ON `arcade_rooms` (`code`);--> statement-breakpoint
+
+PRAGMA foreign_keys=ON;

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

@@ -64,6 +64,27 @@
       "when": 1760548800000,
       "tag": "0008_make_room_name_nullable",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1760600000000,
+      "tag": "0009_add_display_password",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "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/package.json

@@ -59,6 +59,7 @@
     "drizzle-orm": "^0.44.6",
     "emojibase-data": "^16.0.3",
     "jose": "^6.1.0",
+    "js-yaml": "^4.1.0",
     "lucide-react": "^0.294.0",
     "make-plural": "^7.4.0",
     "nanoid": "^5.1.6",
@@ -69,7 +70,8 @@
     "react-dom": "^18.2.0",
     "react-resizable-layout": "^0.7.3",
     "socket.io": "^4.8.1",
-    "socket.io-client": "^4.8.1"
+    "socket.io-client": "^4.8.1",
+    "zod": "^4.1.12"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.1",
@@ -80,6 +82,7 @@
     "@testing-library/react": "^16.3.0",
     "@types/bcryptjs": "^2.4.6",
     "@types/better-sqlite3": "^7.6.13",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.0.0",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",

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

@@ -1,13 +1,14 @@
 import { type NextRequest, NextResponse } from 'next/server'
-import { getRoomMembers } from '@/lib/arcade/room-membership'
 import {
   createInvitation,
   declineInvitation,
   getInvitation,
   getRoomInvitations,
 } from '@/lib/arcade/room-invitations'
-import { getViewerId } from '@/lib/viewer'
+import { getRoomById } from '@/lib/arcade/room-manager'
+import { getRoomMembers } from '@/lib/arcade/room-membership'
 import { getSocketIO } from '@/lib/socket-io'
+import { getViewerId } from '@/lib/viewer'
 
 type RouteContext = {
   params: Promise<{ roomId: string }>
@@ -35,6 +36,20 @@ export async function POST(req: NextRequest, context: RouteContext) {
       )
     }
 
+    // Get room to check access mode
+    const room = await getRoomById(roomId)
+    if (!room) {
+      return NextResponse.json({ error: 'Room not found' }, { status: 404 })
+    }
+
+    // Cannot invite to retired rooms
+    if (room.accessMode === 'retired') {
+      return NextResponse.json(
+        { error: 'Cannot send invitations to retired rooms' },
+        { status: 403 }
+      )
+    }
+
     // Check if user is the host
     const members = await getRoomMembers(roomId)
     const currentMember = members.find((m) => m.userId === viewerId)

apps/web/src/app/api/arcade/rooms/[roomId]/join-requests/route.ts

@@ -1,6 +1,8 @@
 import { type NextRequest, NextResponse } from 'next/server'
+import { createJoinRequest, getPendingJoinRequests } from '@/lib/arcade/room-join-requests'
+import { getRoomById } from '@/lib/arcade/room-manager'
 import { getRoomMembers } from '@/lib/arcade/room-membership'
-import { getPendingJoinRequests } from '@/lib/arcade/room-join-requests'
+import { getSocketIO } from '@/lib/socket-io'
 import { getViewerId } from '@/lib/viewer'
 
 type RouteContext = {
@@ -37,3 +39,82 @@ export async function GET(req: NextRequest, context: RouteContext) {
     return NextResponse.json({ error: 'Failed to get join requests' }, { status: 500 })
   }
 }
+
+/**
+ * POST /api/arcade/rooms/:roomId/join-requests
+ * Create a join request for an approval-only room
+ * Body:
+ *   - displayName?: string (optional, will generate from viewerId if not provided)
+ */
+export async function POST(req: NextRequest, context: RouteContext) {
+  try {
+    const { roomId } = await context.params
+    const viewerId = await getViewerId()
+    const body = await req.json().catch(() => ({}))
+
+    // Get room to verify it exists
+    const room = await getRoomById(roomId)
+    if (!room) {
+      return NextResponse.json({ error: 'Room not found' }, { status: 404 })
+    }
+
+    // Verify room is approval-only
+    if (room.accessMode !== 'approval-only') {
+      return NextResponse.json(
+        { error: 'This room does not require approval to join' },
+        { status: 400 }
+      )
+    }
+
+    // Get or generate display name
+    const displayName = body.displayName || `Guest ${viewerId.slice(-4)}`
+
+    // Validate display name length
+    if (displayName.length > 50) {
+      return NextResponse.json(
+        { error: 'Display name too long (max 50 characters)' },
+        { status: 400 }
+      )
+    }
+
+    // Create join request
+    const request = await createJoinRequest({
+      roomId,
+      userId: viewerId,
+      userName: displayName,
+    })
+
+    console.log(
+      `[Join Requests] Created request for user ${viewerId} (${displayName}) to join room ${roomId}`
+    )
+
+    // Broadcast to the room host (creator) only via socket
+    const io = await getSocketIO()
+    if (io) {
+      try {
+        // Send notification only to the room creator's user channel
+        io.to(`user:${room.createdBy}`).emit('join-request-submitted', {
+          roomId,
+          request: {
+            id: request.id,
+            userId: request.userId,
+            userName: request.userName,
+            createdAt: request.requestedAt,
+          },
+        })
+
+        console.log(
+          `[Join Requests] Broadcasted join-request-submitted to room creator ${room.createdBy}`
+        )
+      } catch (socketError) {
+        // Log but don't fail the request if socket broadcast fails
+        console.error('[Join Requests] Failed to broadcast join-request-submitted:', socketError)
+      }
+    }
+
+    return NextResponse.json({ request }, { status: 201 })
+  } catch (error: any) {
+    console.error('Failed to create join request:', error)
+    return NextResponse.json({ error: 'Failed to create join request' }, { status: 500 })
+  }
+}

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

@@ -1,13 +1,13 @@
+import bcrypt from 'bcryptjs'
 import { type NextRequest, NextResponse } from 'next/server'
-import { getRoomById, touchRoom } from '@/lib/arcade/room-manager'
-import { addRoomMember, getRoomMembers } from '@/lib/arcade/room-membership'
 import { getActivePlayers, getRoomActivePlayers } from '@/lib/arcade/player-manager'
-import { isUserBanned } from '@/lib/arcade/room-moderation'
 import { getInvitation } from '@/lib/arcade/room-invitations'
 import { getJoinRequest } from '@/lib/arcade/room-join-requests'
-import { getViewerId } from '@/lib/viewer'
+import { getRoomById, touchRoom } from '@/lib/arcade/room-manager'
+import { addRoomMember, getRoomMembers } from '@/lib/arcade/room-membership'
+import { isUserBanned } from '@/lib/arcade/room-moderation'
 import { getSocketIO } from '@/lib/socket-io'
-import bcrypt from 'bcryptjs'
+import { getViewerId } from '@/lib/viewer'
 
 type RouteContext = {
   params: Promise<{ roomId: string }>
@@ -38,13 +38,32 @@ export async function POST(req: NextRequest, context: RouteContext) {
       return NextResponse.json({ error: 'You are banned from this room' }, { status: 403 })
     }
 
+    // Check if user is already a member (for locked/retired room access)
+    const members = await getRoomMembers(roomId)
+    const isExistingMember = members.some((m) => m.userId === viewerId)
+    const isRoomCreator = room.createdBy === viewerId
+
     // Validate access mode
     switch (room.accessMode) {
       case 'locked':
-        return NextResponse.json({ error: 'This room is locked' }, { status: 403 })
+        // Allow existing members to continue using the room, but block new members
+        if (!isExistingMember) {
+          return NextResponse.json(
+            { error: 'This room is locked and not accepting new members' },
+            { status: 403 }
+          )
+        }
+        break
 
       case 'retired':
-        return NextResponse.json({ error: 'This room has been retired' }, { status: 410 })
+        // Only the room creator can access retired rooms
+        if (!isRoomCreator) {
+          return NextResponse.json(
+            { error: 'This room has been retired and is only accessible to the owner' },
+            { status: 410 }
+          )
+        }
+        break
 
       case 'password': {
         if (!body.password) {
@@ -64,30 +83,34 @@ export async function POST(req: NextRequest, context: RouteContext) {
       }
 
       case 'restricted': {
-        // Check for valid pending invitation
-        const invitation = await getInvitation(roomId, viewerId)
-        if (!invitation || invitation.status !== 'pending') {
-          return NextResponse.json(
-            { error: 'You need a valid invitation to join this room' },
-            { status: 403 }
-          )
+        // Room creator can always rejoin their own room
+        if (!isRoomCreator) {
+          // Check for valid pending invitation
+          const invitation = await getInvitation(roomId, viewerId)
+          if (!invitation || invitation.status !== 'pending') {
+            return NextResponse.json(
+              { error: 'You need a valid invitation to join this room' },
+              { status: 403 }
+            )
+          }
         }
         break
       }
 
       case 'approval-only': {
-        // Check for approved join request
-        const joinRequest = await getJoinRequest(roomId, viewerId)
-        if (!joinRequest || joinRequest.status !== 'approved') {
-          return NextResponse.json(
-            { error: 'Your join request must be approved by the host' },
-            { status: 403 }
-          )
+        // Room creator can always rejoin their own room without approval
+        if (!isRoomCreator) {
+          // Check for approved join request
+          const joinRequest = await getJoinRequest(roomId, viewerId)
+          if (!joinRequest || joinRequest.status !== 'approved') {
+            return NextResponse.json(
+              { error: 'Your join request must be approved by the host' },
+              { status: 403 }
+            )
+          }
         }
         break
       }
-
-      case 'open':
       default:
         // No additional checks needed
         break

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

@@ -42,8 +42,13 @@ export async function GET(_req: NextRequest, context: RouteContext) {
     // Update room activity when viewing (keeps active rooms fresh)
     await touchRoom(roomId)
 
+    // Prepare room data - include displayPassword only for room creator
+    const roomData = canModerate
+      ? room // Creator gets full room data including displayPassword
+      : { ...room, displayPassword: undefined } // Others don't see displayPassword
+
     return NextResponse.json({
-      room,
+      room: roomData,
       members,
       memberPlayers, // Map of userId -> active Player[] for each member
       canModerate,

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

@@ -1,9 +1,15 @@
-import { eq } from 'drizzle-orm'
+import bcrypt from 'bcryptjs'
+import { and, eq } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
 import { db, schema } from '@/db'
+import { getRoomActivePlayers } from '@/lib/arcade/player-manager'
+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 bcrypt from 'bcryptjs'
+import { getAllGameConfigs, setGameConfig } from '@/lib/arcade/game-config-helpers'
+import { isValidGameName } from '@/lib/arcade/validators'
+import type { GameName } from '@/lib/arcade/validators'
 
 type RouteContext = {
   params: Promise<{ roomId: string }>
@@ -15,6 +21,11 @@ type RouteContext = {
  * Body:
  *   - accessMode?: 'open' | 'locked' | 'retired' | 'password' | 'restricted' | 'approval-only'
  *   - password?: string (plain text, will be hashed)
+ *   - gameName?: string | null (any game with a registered validator)
+ *   - gameConfig?: object (game-specific settings)
+ *
+ * Note: gameName is validated at runtime against the validator registry.
+ * No need to update this file when adding new games!
  */
 export async function PATCH(req: NextRequest, context: RouteContext) {
   try {
@@ -22,6 +33,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)
@@ -55,6 +96,18 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
       )
     }
 
+    // Validate gameName if provided - check against validator registry at runtime
+    if (body.gameName !== undefined && body.gameName !== null) {
+      if (!isValidGameName(body.gameName)) {
+        return NextResponse.json(
+          {
+            error: `Invalid game name: ${body.gameName}. Game must have a registered validator.`,
+          },
+          { status: 400 }
+        )
+      }
+    }
+
     // Prepare update data
     const updateData: Record<string, any> = {}
 
@@ -66,20 +119,166 @@ export async function PATCH(req: NextRequest, context: RouteContext) {
     if (body.password !== undefined) {
       if (body.password === null || body.password === '') {
         updateData.password = null // Clear password
+        updateData.displayPassword = null // Also clear display password
       } else {
         const hashedPassword = await bcrypt.hash(body.password, 10)
         updateData.password = hashedPassword
+        updateData.displayPassword = body.password // Store plain text for display
       }
     }
 
-    // Update room settings
-    const [updatedRoom] = await db
-      .update(schema.arcadeRooms)
-      .set(updateData)
-      .where(eq(schema.arcadeRooms.id, roomId))
-      .returning()
+    // Update game selection if provided
+    if (body.gameName !== undefined) {
+      updateData.gameName = body.gameName
+    }
 
-    return NextResponse.json({ room: updatedRoom }, { status: 200 })
+    // 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(
+      '[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) {
+      console.log(`[Settings API] Deleting existing arcade session for room ${roomId}`)
+      await db.delete(schema.arcadeSessions).where(eq(schema.arcadeSessions.roomId, roomId))
+    }
+
+    // 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,
+        },
+        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}`)
+          const broadcastData: {
+            roomId: string
+            gameName: string | null
+            gameConfig?: Record<string, unknown>
+          } = {
+            roomId,
+            gameName: body.gameName,
+            gameConfig, // Include aggregated configs from new table
+          }
+
+          io.to(`room:${roomId}`).emit('room-game-changed', broadcastData)
+        } catch (socketError) {
+          console.error('[Settings API] Failed to broadcast game change:', socketError)
+        }
+      }
+    }
+
+    // If setting to retired, expel all non-owner members
+    if (body.accessMode === 'retired') {
+      const nonOwnerMembers = members.filter((m) => !m.isCreator)
+
+      if (nonOwnerMembers.length > 0) {
+        // Remove all non-owner members from the room
+        await db.delete(schema.roomMembers).where(
+          and(
+            eq(schema.roomMembers.roomId, roomId),
+            // Delete all members except the creator
+            eq(schema.roomMembers.isCreator, false)
+          )
+        )
+
+        // Record in history for each expelled member
+        for (const member of nonOwnerMembers) {
+          await recordRoomMemberHistory({
+            roomId,
+            userId: member.userId,
+            displayName: member.displayName,
+            action: 'left',
+          })
+        }
+
+        // Broadcast updates via socket
+        const io = await getSocketIO()
+        if (io) {
+          try {
+            // Get updated member list (should only be the owner now)
+            const updatedMembers = await getRoomMembers(roomId)
+            const memberPlayers = await getRoomActivePlayers(roomId)
+
+            // Convert memberPlayers Map to object for JSON serialization
+            const memberPlayersObj: Record<string, any[]> = {}
+            for (const [uid, players] of memberPlayers.entries()) {
+              memberPlayersObj[uid] = players
+            }
+
+            // Notify each expelled member
+            for (const member of nonOwnerMembers) {
+              io.to(`user:${member.userId}`).emit('kicked-from-room', {
+                roomId,
+                kickedBy: currentMember.displayName,
+                reason: 'Room has been retired',
+              })
+            }
+
+            // Notify the owner that members were expelled
+            io.to(`room:${roomId}`).emit('member-left', {
+              roomId,
+              userId: nonOwnerMembers.map((m) => m.userId),
+              members: updatedMembers,
+              memberPlayers: memberPlayersObj,
+              reason: 'room-retired',
+            })
+
+            console.log(
+              `[Settings API] Expelled ${nonOwnerMembers.length} members from retired room ${roomId}`
+            )
+          } catch (socketError) {
+            console.error('[Settings API] Failed to broadcast member expulsion:', socketError)
+          }
+        }
+      }
+    }
+
+    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,6 +29,22 @@ 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,
+        },
+        null,
+        2
+      )
+    )
+
     // Get members
     const members = await getRoomMembers(roomId)
 
@@ -41,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/app/api/arcade/rooms/route.ts

@@ -3,7 +3,7 @@ import { createRoom, listActiveRooms } from '@/lib/arcade/room-manager'
 import { addRoomMember, getRoomMembers, isMember } from '@/lib/arcade/room-membership'
 import { getRoomActivePlayers } from '@/lib/arcade/player-manager'
 import { getViewerId } from '@/lib/viewer'
-import type { GameName } from '@/lib/arcade/validation'
+import { hasValidator, type GameName } from '@/lib/arcade/validators'
 
 /**
  * GET /api/arcade/rooms
@@ -62,42 +62,65 @@ export async function GET(req: NextRequest) {
  *   - gameName: string
  *   - gameConfig?: object
  *   - ttlMinutes?: number
+ *   - accessMode?: 'open' | 'password' | 'approval-only' | 'restricted' | 'locked' | 'retired'
+ *   - password?: string
  */
 export async function POST(req: NextRequest) {
   try {
     const viewerId = await getViewerId()
     const body = await req.json()
 
-    // Validate required fields
-    if (!body.name || !body.gameName) {
+    // Validate game name if provided (gameName is now optional)
+    if (body.gameName) {
+      if (!hasValidator(body.gameName)) {
+        return NextResponse.json({ error: 'Invalid game name' }, { status: 400 })
+      }
+    }
+
+    // Validate name length (if provided)
+    if (body.name && body.name.length > 50) {
+      return NextResponse.json({ error: 'Room name too long (max 50 characters)' }, { status: 400 })
+    }
+
+    // Normalize empty name to null
+    const roomName = body.name?.trim() || null
+
+    // Validate access mode
+    if (body.accessMode) {
+      const validAccessModes = [
+        'open',
+        'password',
+        'approval-only',
+        'restricted',
+        'locked',
+        'retired',
+      ]
+      if (!validAccessModes.includes(body.accessMode)) {
+        return NextResponse.json({ error: 'Invalid access mode' }, { status: 400 })
+      }
+    }
+
+    // Validate password if provided
+    if (body.accessMode === 'password' && !body.password) {
       return NextResponse.json(
-        { error: 'Missing required fields: name, gameName' },
+        { error: 'Password is required for password-protected rooms' },
         { status: 400 }
       )
     }
 
-    // Validate game name
-    const validGames: GameName[] = ['matching', 'memory-quiz', 'complement-race']
-    if (!validGames.includes(body.gameName)) {
-      return NextResponse.json({ error: 'Invalid game name' }, { status: 400 })
-    }
-
-    // Validate name length
-    if (body.name.length > 50) {
-      return NextResponse.json({ error: 'Room name too long (max 50 characters)' }, { status: 400 })
-    }
-
     // Get display name from body or generate from viewerId
     const displayName = body.creatorName || `Guest ${viewerId.slice(-4)}`
 
     // Create room
     const room = await createRoom({
-      name: body.name,
+      name: roomName,
       createdBy: viewerId,
       creatorName: displayName,
-      gameName: body.gameName,
-      gameConfig: body.gameConfig || {},
+      gameName: body.gameName || null,
+      gameConfig: body.gameConfig || null,
       ttlMinutes: body.ttlMinutes,
+      accessMode: body.accessMode,
+      password: body.password,
     })
 
     // Add creator as first member
@@ -108,6 +131,16 @@ export async function POST(req: NextRequest) {
       isCreator: true,
     })
 
+    // Get members and active players for the response
+    const members = await getRoomMembers(room.id)
+    const memberPlayers = await getRoomActivePlayers(room.id)
+
+    // Convert Map to object for JSON serialization
+    const memberPlayersObj: Record<string, any[]> = {}
+    for (const [uid, players] of memberPlayers.entries()) {
+      memberPlayersObj[uid] = players
+    }
+
     // Generate join URL
     const baseUrl = process.env.NEXT_PUBLIC_URL || 'http://localhost:3000'
     const joinUrl = `${baseUrl}/arcade/rooms/${room.id}`
@@ -115,6 +148,8 @@ export async function POST(req: NextRequest) {
     return NextResponse.json(
       {
         room,
+        members,
+        memberPlayers: memberPlayersObj,
         joinUrl,
       },
       { status: 201 }

apps/web/src/app/api/players/__tests__/arcade-session-validation.e2e.test.ts

@@ -48,9 +48,26 @@ describe('PATCH /api/players/[id] - Arcade Session Validation', () => {
   })
 
   it('should return 403 when trying to change isActive with active arcade session', async () => {
+    // Create an arcade room first
+    const [room] = await db
+      .insert(schema.arcadeRooms)
+      .values({
+        code: 'TEST01',
+        createdBy: testGuestId,
+        creatorName: 'Test User',
+        gameName: 'matching',
+        gameConfig: JSON.stringify({
+          difficulty: 6,
+          gameType: 'abacus-numeral',
+          turnTimer: 30,
+        }),
+      })
+      .returning()
+
     // Create an active arcade session
     const now = new Date()
     await db.insert(schema.arcadeSessions).values({
+      roomId: room.id,
       userId: testGuestId,
       currentGame: 'matching',
       gameUrl: '/arcade/matching',
@@ -117,9 +134,26 @@ describe('PATCH /api/players/[id] - Arcade Session Validation', () => {
   })
 
   it('should allow non-isActive changes even with active arcade session', async () => {
+    // Create an arcade room first
+    const [room] = await db
+      .insert(schema.arcadeRooms)
+      .values({
+        code: 'TEST02',
+        createdBy: testGuestId,
+        creatorName: 'Test User',
+        gameName: 'matching',
+        gameConfig: JSON.stringify({
+          difficulty: 6,
+          gameType: 'abacus-numeral',
+          turnTimer: 30,
+        }),
+      })
+      .returning()
+
     // Create an active arcade session
     const now = new Date()
     await db.insert(schema.arcadeSessions).values({
+      roomId: room.id,
       userId: testGuestId,
       currentGame: 'matching',
       gameUrl: '/arcade/matching',
@@ -164,9 +198,26 @@ describe('PATCH /api/players/[id] - Arcade Session Validation', () => {
   })
 
   it('should allow isActive change after arcade session ends', async () => {
+    // Create an arcade room first
+    const [room] = await db
+      .insert(schema.arcadeRooms)
+      .values({
+        code: 'TEST03',
+        createdBy: testGuestId,
+        creatorName: 'Test User',
+        gameName: 'matching',
+        gameConfig: JSON.stringify({
+          difficulty: 6,
+          gameType: 'abacus-numeral',
+          turnTimer: 30,
+        }),
+      })
+      .returning()
+
     // Create an active arcade session
     const now = new Date()
     await db.insert(schema.arcadeSessions).values({
+      roomId: room.id,
       userId: testGuestId,
       currentGame: 'matching',
       gameUrl: '/arcade/matching',
@@ -179,7 +230,7 @@ describe('PATCH /api/players/[id] - Arcade Session Validation', () => {
     })
 
     // End the session
-    await db.delete(schema.arcadeSessions).where(eq(schema.arcadeSessions.userId, testGuestId))
+    await db.delete(schema.arcadeSessions).where(eq(schema.arcadeSessions.roomId, room.id))
 
     // Mock request to change isActive
     const mockRequest = new NextRequest(`http://localhost:3000/api/players/${testPlayerId}`, {
@@ -212,9 +263,26 @@ describe('PATCH /api/players/[id] - Arcade Session Validation', () => {
       })
       .returning()
 
+    // Create an arcade room first
+    const [room] = await db
+      .insert(schema.arcadeRooms)
+      .values({
+        code: 'TEST04',
+        createdBy: testGuestId,
+        creatorName: 'Test User',
+        gameName: 'matching',
+        gameConfig: JSON.stringify({
+          difficulty: 6,
+          gameType: 'abacus-numeral',
+          turnTimer: 30,
+        }),
+      })
+      .returning()
+
     // Create arcade session
     const now2 = new Date()
     await db.insert(schema.arcadeSessions).values({
+      roomId: room.id,
       userId: testGuestId,
       currentGame: 'matching',
       gameUrl: '/arcade/matching',

apps/web/src/app/arcade-rooms/[roomId]/page.tsx

@@ -4,13 +4,15 @@ import { useEffect, useState } from 'react'
 import { useParams, useRouter } from 'next/navigation'
 import { io, type Socket } from 'socket.io-client'
 import { css } from '../../../../styled-system/css'
+import { useToast } from '@/components/common/ToastContext'
 import { PageWithNav } from '@/components/PageWithNav'
 import { useViewerId } from '@/hooks/useViewerId'
+import { getRoomDisplayWithEmoji } from '@/utils/room-display'
 
 interface Room {
   id: string
   code: string
-  name: string
+  name: string | null
   gameName: string
   status: 'lobby' | 'playing' | 'finished'
   createdBy: string
@@ -39,6 +41,7 @@ interface Player {
 export default function RoomDetailPage() {
   const params = useParams()
   const router = useRouter()
+  const { showError } = useToast()
   const roomId = params.roomId as string
   const { data: guestId } = useViewerId()
 
@@ -171,7 +174,7 @@ export default function RoomDetailPage() {
 
         // Handle specific room membership conflict
         if (errorData.code === 'ROOM_MEMBERSHIP_CONFLICT') {
-          alert(errorData.userMessage || errorData.message)
+          showError('Already in Another Room', errorData.userMessage || errorData.message)
           // Refresh the page to update room state
           await fetchRoom()
           return
@@ -192,7 +195,7 @@ export default function RoomDetailPage() {
       await fetchRoom()
     } catch (err) {
       console.error('Failed to join room:', err)
-      alert('Failed to join room')
+      showError('Failed to join room', err instanceof Error ? err.message : undefined)
     }
   }
 
@@ -212,7 +215,7 @@ export default function RoomDetailPage() {
       router.push('/arcade')
     } catch (err) {
       console.error('Failed to leave room:', err)
-      alert('Failed to leave room')
+      showError('Failed to leave room', err instanceof Error ? err.message : undefined)
     }
   }
 
@@ -357,7 +360,11 @@ export default function RoomDetailPage() {
                     mb: '2',
                   })}
                 >
-                  {room.name}
+                  {getRoomDisplayWithEmoji({
+                    name: room.name,
+                    code: room.code,
+                    gameName: room.gameName,
+                  })}
                 </h1>
                 <div
                   className={css({

apps/web/src/app/arcade-rooms/page.tsx

@@ -3,6 +3,7 @@
 import { useEffect, useState } from 'react'
 import { useRouter } from 'next/navigation'
 import { css } from '../../../styled-system/css'
+import { useToast } from '@/components/common/ToastContext'
 import { PageWithNav } from '@/components/PageWithNav'
 import { getRoomDisplayWithEmoji } from '@/utils/room-display'
 
@@ -23,6 +24,7 @@ interface Room {
 
 export default function RoomBrowserPage() {
   const router = useRouter()
+  const { showError, showInfo } = useToast()
   const [rooms, setRooms] = useState<Room[]>([])
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState<string | null>(null)
@@ -68,10 +70,10 @@ export default function RoomBrowserPage() {
       }
 
       const data = await response.json()
-      router.push(`/arcade-rooms/${data.room.id}`)
+      router.push(`/join/${data.room.code}`)
     } catch (err) {
       console.error('Failed to create room:', err)
-      alert('Failed to create room')
+      showError('Failed to create room', err instanceof Error ? err.message : undefined)
     }
   }
 
@@ -90,7 +92,7 @@ export default function RoomBrowserPage() {
 
         if (!response.ok) {
           const errorData = await response.json()
-          alert(errorData.error || 'Failed to join room')
+          showError('Failed to join room', errorData.error)
           return
         }
 
@@ -99,12 +101,18 @@ export default function RoomBrowserPage() {
       }
 
       if (room.accessMode === 'approval-only') {
-        alert('This room requires host approval. Please use the Join Room modal to request access.')
+        showInfo(
+          'Approval Required',
+          'This room requires host approval. Please use the Join Room modal to request access.'
+        )
         return
       }
 
       if (room.accessMode === 'restricted') {
-        alert('This room is invitation-only. Please ask the host for an invitation.')
+        showInfo(
+          'Invitation Only',
+          'This room is invitation-only. Please ask the host for an invitation.'
+        )
         return
       }
 
@@ -120,7 +128,7 @@ export default function RoomBrowserPage() {
 
         // Handle specific room membership conflict
         if (errorData.code === 'ROOM_MEMBERSHIP_CONFLICT') {
-          alert(errorData.userMessage || errorData.message)
+          showError('Already in Another Room', errorData.userMessage || errorData.message)
           // Refresh the page to update room list state
           await fetchRooms()
           return
@@ -140,7 +148,7 @@ export default function RoomBrowserPage() {
       router.push(`/arcade-rooms/${room.id}`)
     } catch (err) {
       console.error('Failed to join room:', err)
-      alert('Failed to join room')
+      showError('Failed to join room', err instanceof Error ? err.message : undefined)
     }
   }
 

apps/web/src/app/arcade/matching/components/MemoryPairsGame.tsx

@@ -33,7 +33,7 @@ export function MemoryPairsGame() {
     <PageWithNav
       navTitle={navTitle}
       navEmoji={navEmoji}
-      emphasizeGameContext={state.gamePhase === 'setup'}
+      emphasizePlayerSelection={state.gamePhase === 'setup'}
       onExitSession={() => {
         exitSession()
         router.push('/arcade')

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,
@@ -90,16 +90,19 @@ function applyMoveOptimistically(state: MemoryPairsState, move: GameMove): Memor
 
     case 'FLIP_CARD': {
       // Optimistically flip the card
-      const card = state.gameCards.find((c) => c.id === move.data.cardId)
+      // Defensive check: ensure arrays exist
+      const gameCards = state.gameCards || []
+      const flippedCards = state.flippedCards || []
+
+      const card = gameCards.find((c) => c.id === move.data.cardId)
       if (!card) return state
 
-      const newFlippedCards = [...state.flippedCards, card]
+      const newFlippedCards = [...flippedCards, card]
 
       return {
         ...state,
         flippedCards: newFlippedCards,
-        currentMoveStartTime:
-          state.flippedCards.length === 0 ? Date.now() : state.currentMoveStartTime,
+        currentMoveStartTime: flippedCards.length === 0 ? Date.now() : state.currentMoveStartTime,
         isProcessingMove: newFlippedCards.length === 2, // Processing if 2 cards flipped
         showMismatchFeedback: false,
       }
@@ -237,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)
@@ -244,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 {
@@ -256,39 +329,55 @@ 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,
   })
 
+  // Detect state corruption/mismatch (e.g., game type mismatch between sessions)
+  const hasStateCorruption =
+    !state.gameCards || !state.flippedCards || !Array.isArray(state.gameCards)
+
   // Handle mismatch feedback timeout
   useEffect(() => {
-    if (state.showMismatchFeedback && state.flippedCards.length === 2) {
+    // Defensive check: ensure flippedCards exists
+    if (state.showMismatchFeedback && state.flippedCards?.length === 2) {
       // After 1.5 seconds, send CLEAR_MISMATCH
       // Server will validate that cards are still in mismatch state before clearing
       const timeout = setTimeout(() => {
         sendMove({
           type: 'CLEAR_MISMATCH',
           playerId: state.currentPlayer,
+          userId: viewerId || '',
           data: {},
         })
       }, 1500)
 
       return () => clearTimeout(timeout)
     }
-  }, [state.showMismatchFeedback, state.flippedCards.length, sendMove, state.currentPlayer])
+  }, [
+    state.showMismatchFeedback,
+    state.flippedCards?.length,
+    sendMove,
+    state.currentPlayer,
+    viewerId,
+  ])
 
   // Computed values
   const isGameActive = state.gamePhase === 'playing'
 
   const canFlipCard = useCallback(
     (cardId: string): boolean => {
+      // Defensive check: ensure required state exists
+      const flippedCards = state.flippedCards || []
+      const gameCards = state.gameCards || []
+
       console.log('[RoomProvider][canFlipCard] Checking card:', {
         cardId,
         isGameActive,
         isProcessingMove: state.isProcessingMove,
         currentPlayer: state.currentPlayer,
         hasRoomData: !!roomData,
-        flippedCardsCount: state.flippedCards.length,
+        flippedCardsCount: flippedCards.length,
       })
 
       if (!isGameActive || state.isProcessingMove) {
@@ -296,20 +385,20 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
         return false
       }
 
-      const card = state.gameCards.find((c) => c.id === cardId)
+      const card = gameCards.find((c) => c.id === cardId)
       if (!card || card.matched) {
         console.log('[RoomProvider][canFlipCard] Blocked: card not found or already matched')
         return false
       }
 
       // Can't flip if already flipped
-      if (state.flippedCards.some((c) => c.id === cardId)) {
+      if (flippedCards.some((c) => c.id === cardId)) {
         console.log('[RoomProvider][canFlipCard] Blocked: card already flipped')
         return false
       }
 
       // Can't flip more than 2 cards
-      if (state.flippedCards.length >= 2) {
+      if (flippedCards.length >= 2) {
         console.log('[RoomProvider][canFlipCard] Blocked: 2 cards already flipped')
         return false
       }
@@ -414,13 +503,14 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
     sendMove({
       type: 'START_GAME',
       playerId: firstPlayer,
+      userId: viewerId || '',
       data: {
         cards,
         activePlayers,
         playerMetadata,
       },
     })
-  }, [state.gameType, state.difficulty, activePlayers, buildPlayerMetadata, sendMove])
+  }, [state.gameType, state.difficulty, activePlayers, buildPlayerMetadata, sendMove, viewerId])
 
   const flipCard = useCallback(
     (cardId: string) => {
@@ -441,6 +531,7 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
       const move = {
         type: 'FLIP_CARD' as const,
         playerId: state.currentPlayer, // Use the current player ID from game state (database player ID)
+        userId: viewerId || '',
         data: { cardId },
       }
       console.log('[RoomProvider] Sending FLIP_CARD move via sendMove:', move)
@@ -466,49 +557,152 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
     sendMove({
       type: 'START_GAME',
       playerId: firstPlayer,
+      userId: viewerId || '',
       data: {
         cards,
         activePlayers,
         playerMetadata,
       },
     })
-  }, [state.gameType, state.difficulty, activePlayers, buildPlayerMetadata, sendMove])
+  }, [state.gameType, state.difficulty, activePlayers, buildPlayerMetadata, sendMove, viewerId])
 
   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({
         type: 'SET_CONFIG',
         playerId,
+        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]
+    [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',
         playerId,
+        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]
+    [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',
         playerId,
+        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]
+    [activePlayers, sendMove, viewerId, roomData?.id, roomData?.gameConfig, updateGameConfig]
   )
 
   const goToSetup = useCallback(() => {
@@ -517,9 +711,10 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
     sendMove({
       type: 'GO_TO_SETUP',
       playerId,
+      userId: viewerId || '',
       data: {},
     })
-  }, [activePlayers, state.currentPlayer, sendMove])
+  }, [activePlayers, state.currentPlayer, sendMove, viewerId])
 
   const resumeGame = useCallback(() => {
     // PAUSE/RESUME: Resume paused game if config unchanged
@@ -532,9 +727,10 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
     sendMove({
       type: 'RESUME_GAME',
       playerId,
+      userId: viewerId || '',
       data: {},
     })
-  }, [canResumeGame, activePlayers, state.currentPlayer, sendMove])
+  }, [canResumeGame, activePlayers, state.currentPlayer, sendMove, viewerId])
 
   const hoverCard = useCallback(
     (cardId: string | null) => {
@@ -546,10 +742,11 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
       sendMove({
         type: 'HOVER_CARD',
         playerId,
+        userId: viewerId || '',
         data: { cardId },
       })
     },
-    [state.currentPlayer, activePlayers, sendMove]
+    [state.currentPlayer, activePlayers, sendMove, viewerId]
   )
 
   // NO MORE effectiveState merging! Just use session state directly with gameMode added
@@ -557,6 +754,100 @@ export function RoomMemoryPairsProvider({ children }: { children: ReactNode }) {
     gameMode: GameMode
   }
 
+  // If state is corrupted, show error message instead of crashing
+  if (hasStateCorruption) {
+    return (
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: '40px',
+          textAlign: 'center',
+          minHeight: '400px',
+        }}
+      >
+        <div
+          style={{
+            fontSize: '48px',
+            marginBottom: '20px',
+          }}
+        >
+          ⚠️
+        </div>
+        <h2
+          style={{
+            fontSize: '24px',
+            fontWeight: 'bold',
+            marginBottom: '12px',
+            color: '#dc2626',
+          }}
+        >
+          Game State Mismatch
+        </h2>
+        <p
+          style={{
+            fontSize: '16px',
+            color: '#6b7280',
+            marginBottom: '24px',
+            maxWidth: '500px',
+          }}
+        >
+          There's a mismatch between game types in this room. This usually happens when room members
+          are playing different games.
+        </p>
+        <div
+          style={{
+            background: '#f9fafb',
+            border: '1px solid #e5e7eb',
+            borderRadius: '8px',
+            padding: '16px',
+            marginBottom: '24px',
+            maxWidth: '500px',
+          }}
+        >
+          <p
+            style={{
+              fontSize: '14px',
+              fontWeight: '600',
+              marginBottom: '8px',
+            }}
+          >
+            To fix this:
+          </p>
+          <ol
+            style={{
+              fontSize: '14px',
+              textAlign: 'left',
+              paddingLeft: '20px',
+              lineHeight: '1.6',
+            }}
+          >
+            <li>Make sure all room members are on the same game page</li>
+            <li>Try refreshing the page</li>
+            <li>If the issue persists, leave and rejoin the room</li>
+          </ol>
+        </div>
+        <button
+          onClick={() => window.location.reload()}
+          style={{
+            padding: '10px 20px',
+            background: '#3b82f6',
+            color: 'white',
+            border: 'none',
+            borderRadius: '6px',
+            fontSize: '14px',
+            fontWeight: '600',
+            cursor: 'pointer',
+          }}
+        >
+          Refresh Page
+        </button>
+      </div>
+    )
+  }
+
   const contextValue: MemoryPairsContextValue = {
     state: effectiveState,
     dispatch: () => {

apps/web/src/app/arcade/memory-quiz/components/CardGrid.tsx

@@ -0,0 +1,197 @@
+import { AbacusReact } from '@soroban/abacus-react'
+import type { SorobanQuizState } from '../types'
+
+interface CardGridProps {
+  state: SorobanQuizState
+}
+
+export function CardGrid({ state }: CardGridProps) {
+  if (state.quizCards.length === 0) return null
+
+  // Calculate optimal grid layout based on number of cards
+  const cardCount = state.quizCards.length
+
+  // Define static grid classes that Panda can generate
+  const getGridClass = (count: number) => {
+    if (count <= 2) return 'repeat(2, 1fr)'
+    if (count <= 4) return 'repeat(2, 1fr)'
+    if (count <= 6) return 'repeat(3, 1fr)'
+    if (count <= 9) return 'repeat(3, 1fr)'
+    if (count <= 12) return 'repeat(4, 1fr)'
+    return 'repeat(5, 1fr)'
+  }
+
+  const getCardSize = (count: number) => {
+    if (count <= 2) return { minSize: '180px', cardHeight: '160px' }
+    if (count <= 4) return { minSize: '160px', cardHeight: '150px' }
+    if (count <= 6) return { minSize: '140px', cardHeight: '140px' }
+    if (count <= 9) return { minSize: '120px', cardHeight: '130px' }
+    if (count <= 12) return { minSize: '110px', cardHeight: '120px' }
+    return { minSize: '100px', cardHeight: '110px' }
+  }
+
+  const gridClass = getGridClass(cardCount)
+  const cardSize = getCardSize(cardCount)
+
+  return (
+    <div
+      style={{
+        marginTop: '12px',
+        padding: '12px',
+        background: '#f9fafb',
+        borderRadius: '8px',
+        border: '1px solid #e5e7eb',
+        maxHeight: '50vh',
+        overflowY: 'auto',
+      }}
+    >
+      <h4
+        style={{
+          textAlign: 'center',
+          color: '#374151',
+          marginBottom: '12px',
+          fontSize: '14px',
+          fontWeight: '600',
+        }}
+      >
+        Cards you saw ({cardCount}):
+      </h4>
+
+      <div
+        style={{
+          display: 'grid',
+          gap: '8px',
+          maxWidth: '100%',
+          margin: '0 auto',
+          width: 'fit-content',
+          gridTemplateColumns: gridClass,
+        }}
+      >
+        {state.quizCards.map((card, index) => {
+          const isRevealed = state.foundNumbers.includes(card.number)
+          return (
+            <div
+              key={`card-${index}-${card.number}`}
+              style={{
+                perspective: '1000px',
+                maxWidth: '200px',
+                height: cardSize.cardHeight,
+                minWidth: cardSize.minSize,
+              }}
+            >
+              <div
+                style={{
+                  position: 'relative',
+                  width: '100%',
+                  height: '100%',
+                  textAlign: 'center',
+                  transition: 'transform 0.8s',
+                  transformStyle: 'preserve-3d',
+                  transform: isRevealed ? 'rotateY(180deg)' : 'rotateY(0deg)',
+                }}
+              >
+                {/* Card back (hidden state) */}
+                <div
+                  style={{
+                    position: 'absolute',
+                    width: '100%',
+                    height: '100%',
+                    backfaceVisibility: 'hidden',
+                    borderRadius: '8px',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    boxShadow: '0 4px 8px rgba(0, 0, 0, 0.1)',
+                    background: 'linear-gradient(135deg, #6c5ce7, #a29bfe)',
+                    color: 'white',
+                    fontSize: '32px',
+                    fontWeight: 'bold',
+                    textShadow: '2px 2px 4px rgba(0, 0, 0, 0.3)',
+                    border: '2px solid #5f3dc4',
+                  }}
+                >
+                  <div style={{ opacity: 0.8 }}>?</div>
+                </div>
+
+                {/* Card front (revealed state) */}
+                <div
+                  style={{
+                    position: 'absolute',
+                    width: '100%',
+                    height: '100%',
+                    backfaceVisibility: 'hidden',
+                    borderRadius: '8px',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    boxShadow: '0 4px 8px rgba(0, 0, 0, 0.1)',
+                    background: 'white',
+                    border: '2px solid #28a745',
+                    transform: 'rotateY(180deg)',
+                  }}
+                >
+                  <div
+                    style={{
+                      width: '100%',
+                      height: '100%',
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      overflow: 'hidden',
+                      padding: '4px',
+                    }}
+                  >
+                    <div
+                      style={{
+                        width: '100%',
+                        height: '100%',
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                      }}
+                    >
+                      <AbacusReact
+                        value={card.number}
+                        columns="auto"
+                        beadShape="diamond"
+                        colorScheme="place-value"
+                        hideInactiveBeads={false}
+                        scaleFactor={1.2}
+                        interactive={false}
+                        showNumbers={false}
+                        animated={false}
+                      />
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </div>
+          )
+        })}
+      </div>
+
+      {/* Summary row for large numbers of cards */}
+      {cardCount > 8 && (
+        <div
+          style={{
+            marginTop: '8px',
+            padding: '6px 8px',
+            background: '#eff6ff',
+            borderRadius: '6px',
+            border: '1px solid #bfdbfe',
+            textAlign: 'center',
+            fontSize: '12px',
+            color: '#1d4ed8',
+          }}
+        >
+          <strong>{state.foundNumbers.length}</strong> of <strong>{cardCount}</strong> cards found
+          {state.foundNumbers.length > 0 && (
+            <span style={{ marginLeft: '6px', fontWeight: 'normal' }}>
+              ({Math.round((state.foundNumbers.length / cardCount) * 100)}% complete)
+            </span>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

apps/web/src/app/arcade/memory-quiz/components/DisplayPhase.tsx

@@ -0,0 +1,244 @@
+import { AbacusReact, useAbacusConfig } from '@soroban/abacus-react'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { useMemoryQuiz } from '../context/MemoryQuizContext'
+import type { QuizCard } from '../types'
+
+// Calculate maximum columns needed for a set of numbers
+function calculateMaxColumns(numbers: number[]): number {
+  if (numbers.length === 0) return 1
+  const maxNumber = Math.max(...numbers)
+  if (maxNumber === 0) return 1
+  return Math.floor(Math.log10(maxNumber)) + 1
+}
+
+export function DisplayPhase() {
+  const { state, nextCard, showInputPhase, resetGame, isRoomCreator } = useMemoryQuiz()
+  const [currentCard, setCurrentCard] = useState<QuizCard | null>(null)
+  const [isTransitioning, setIsTransitioning] = useState(false)
+  const isDisplayPhaseActive = state.currentCardIndex < state.quizCards.length
+  const isProcessingRef = useRef(false)
+  const lastProcessedIndexRef = useRef(-1)
+  const appConfig = useAbacusConfig()
+
+  // In multiplayer room mode, only the room creator controls card timing
+  // In local mode (isRoomCreator === undefined), allow timing control
+  const shouldControlTiming = isRoomCreator === undefined || isRoomCreator === true
+
+  // Calculate maximum columns needed for this quiz set
+  const maxColumns = useMemo(() => {
+    const allNumbers = state.quizCards.map((card) => card.number)
+    return calculateMaxColumns(allNumbers)
+  }, [state.quizCards])
+
+  // Calculate adaptive animation duration
+  const flashDuration = useMemo(() => {
+    const displayTimeMs = state.displayTime * 1000
+    return Math.min(Math.max(displayTimeMs * 0.3, 150), 600) / 1000 // Convert to seconds for CSS
+  }, [state.displayTime])
+
+  const progressPercentage = (state.currentCardIndex / state.quizCards.length) * 100
+
+  useEffect(() => {
+    // Prevent processing the same card index multiple times
+    // This prevents race conditions from optimistic updates
+    if (state.currentCardIndex === lastProcessedIndexRef.current) {
+      console.log(
+        `DisplayPhase: Skipping duplicate processing of index ${state.currentCardIndex} (lastProcessed: ${lastProcessedIndexRef.current})`
+      )
+      return
+    }
+
+    if (state.currentCardIndex >= state.quizCards.length) {
+      // Only the room creator (or local mode) triggers phase transitions
+      if (shouldControlTiming) {
+        console.log(
+          `DisplayPhase: All cards shown (${state.quizCards.length}), transitioning to input phase`
+        )
+        showInputPhase?.()
+      }
+      return
+    }
+
+    // Prevent multiple concurrent executions
+    if (isProcessingRef.current) {
+      console.log(
+        `DisplayPhase: Already processing, skipping (index: ${state.currentCardIndex}, lastProcessed: ${lastProcessedIndexRef.current})`
+      )
+      return
+    }
+
+    // Mark this index as being processed
+    lastProcessedIndexRef.current = state.currentCardIndex
+
+    const showNextCard = async () => {
+      isProcessingRef.current = true
+      const card = state.quizCards[state.currentCardIndex]
+      console.log(
+        `DisplayPhase: Showing card ${state.currentCardIndex + 1}/${state.quizCards.length}, number: ${card.number} (isRoomCreator: ${isRoomCreator}, shouldControlTiming: ${shouldControlTiming})`
+      )
+
+      // Calculate adaptive timing based on display speed
+      const displayTimeMs = state.displayTime * 1000
+      const flashDuration = Math.min(Math.max(displayTimeMs * 0.3, 150), 600) // 30% of display time, between 150ms-600ms
+      const transitionPause = Math.min(Math.max(displayTimeMs * 0.1, 50), 200) // 10% of display time, between 50ms-200ms
+
+      // Trigger adaptive transition effect
+      setIsTransitioning(true)
+      setCurrentCard(card)
+
+      // Reset transition effect with adaptive duration
+      setTimeout(() => setIsTransitioning(false), flashDuration)
+
+      console.log(
+        `DisplayPhase: Card ${state.currentCardIndex + 1} now visible (flash: ${flashDuration}ms, pause: ${transitionPause}ms)`
+      )
+
+      // Only the room creator (or local mode) controls the timing
+      if (shouldControlTiming) {
+        // Display card for specified time with adaptive transition pause
+        await new Promise((resolve) => setTimeout(resolve, displayTimeMs - transitionPause))
+
+        // Don't hide the abacus - just advance to next card for smooth transition
+        console.log(
+          `DisplayPhase: Card ${state.currentCardIndex + 1} transitioning to next (controlled by ${isRoomCreator === undefined ? 'local mode' : 'room creator'})`
+        )
+        await new Promise((resolve) => setTimeout(resolve, transitionPause)) // Adaptive pause for visual transition
+
+        isProcessingRef.current = false
+        nextCard?.()
+      } else {
+        // Non-creator players just display the card, don't control timing
+        console.log(
+          `DisplayPhase: Non-creator player displaying card ${state.currentCardIndex + 1}, waiting for creator to advance`
+        )
+        isProcessingRef.current = false
+      }
+    }
+
+    showNextCard()
+  }, [
+    state.currentCardIndex,
+    state.displayTime,
+    state.quizCards.length,
+    nextCard,
+    showInputPhase,
+    shouldControlTiming,
+    isRoomCreator,
+  ])
+
+  return (
+    <div
+      style={{
+        textAlign: 'center',
+        padding: '12px',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        boxSizing: 'border-box',
+        height: '100%',
+        animation: isTransitioning ? `subtlePageFlash ${flashDuration}s ease-out` : undefined,
+      }}
+    >
+      <div
+        style={{
+          position: 'relative',
+          width: '100%',
+          maxWidth: '800px',
+          marginBottom: '12px',
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '12px',
+        }}
+      >
+        <div>
+          <div
+            style={{
+              width: '100%',
+              height: '8px',
+              background: '#e5e7eb',
+              borderRadius: '4px',
+              overflow: 'hidden',
+              marginBottom: '8px',
+            }}
+          >
+            <div
+              style={{
+                height: '100%',
+                background: 'linear-gradient(90deg, #28a745, #20c997)',
+                borderRadius: '4px',
+                width: `${progressPercentage}%`,
+                transition: 'width 0.5s ease',
+              }}
+            />
+          </div>
+          <span
+            style={{
+              fontSize: '14px',
+              fontWeight: 'bold',
+              color: '#374151',
+            }}
+          >
+            Card {state.currentCardIndex + 1} of {state.quizCards.length}
+          </span>
+        </div>
+        <div style={{ display: 'flex', justifyContent: 'flex-end' }}>
+          <button
+            style={{
+              background: '#ef4444',
+              color: 'white',
+              border: 'none',
+              borderRadius: '6px',
+              padding: '6px 12px',
+              fontSize: '12px',
+              cursor: 'pointer',
+              transition: 'background 0.2s ease',
+            }}
+            onClick={() => resetGame?.()}
+          >
+            End Quiz
+          </button>
+        </div>
+      </div>
+
+      {/* Persistent abacus container - stays mounted during entire memorize phase */}
+      <div
+        style={{
+          width: 'min(90vw, 800px)',
+          height: 'min(70vh, 500px)',
+          display: isDisplayPhaseActive ? 'flex' : 'none',
+          alignItems: 'center',
+          justifyContent: 'center',
+          margin: '0 auto',
+          transition: 'opacity 0.3s ease',
+          overflow: 'visible',
+          padding: '20px 12px',
+        }}
+      >
+        <div
+          style={{
+            width: '100%',
+            height: '100%',
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: '20px',
+          }}
+        >
+          {/* Persistent abacus with smooth bead animations and dynamically calculated columns */}
+          <AbacusReact
+            value={currentCard?.number || 0}
+            columns={maxColumns}
+            beadShape={appConfig.beadShape}
+            colorScheme={appConfig.colorScheme}
+            hideInactiveBeads={appConfig.hideInactiveBeads}
+            scaleFactor={5.5}
+            interactive={false}
+            showNumbers={false}
+            animated={true}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}

apps/web/src/app/arcade/memory-quiz/components/InputPhase.tsx

@@ -0,0 +1,848 @@
+import { useCallback, useEffect, useState } from 'react'
+import { isPrefix } from '@/lib/memory-quiz-utils'
+import { useMemoryQuiz } from '../context/MemoryQuizContext'
+import { CardGrid } from './CardGrid'
+
+export function InputPhase() {
+  const { state, dispatch, acceptNumber, rejectNumber, setInput, showResults } = useMemoryQuiz()
+  const [displayFeedback, setDisplayFeedback] = useState<'neutral' | 'correct' | 'incorrect'>(
+    'neutral'
+  )
+
+  // Use keyboard state from parent state instead of local state
+  const { hasPhysicalKeyboard, testingMode, showOnScreenKeyboard } = state
+
+  // Debug: Log state changes and detect what's causing re-renders
+  useEffect(() => {
+    console.log('🔍 Keyboard state changed:', {
+      hasPhysicalKeyboard,
+      testingMode,
+      showOnScreenKeyboard,
+    })
+    console.trace('🔍 State change trace:')
+  }, [hasPhysicalKeyboard, testingMode, showOnScreenKeyboard])
+
+  // Debug: Monitor for unexpected state resets
+  useEffect(() => {
+    if (showOnScreenKeyboard) {
+      const timer = setTimeout(() => {
+        if (!showOnScreenKeyboard) {
+          console.error('🚨 Keyboard was unexpectedly hidden!')
+        }
+      }, 1000)
+      return () => clearTimeout(timer)
+    }
+  }, [showOnScreenKeyboard])
+
+  // Detect physical keyboard availability (disabled when testing mode is active)
+  useEffect(() => {
+    // Skip keyboard detection entirely when testing mode is enabled
+    if (testingMode) {
+      console.log('🧪 Testing mode enabled - skipping keyboard detection')
+      return
+    }
+
+    let detectionTimer: NodeJS.Timeout | null = null
+
+    const detectKeyboard = () => {
+      // Method 1: Check if device supports keyboard via media queries
+      const hasKeyboardSupport =
+        window.matchMedia('(pointer: fine)').matches && window.matchMedia('(hover: hover)').matches
+
+      // Method 2: Check if device is likely touch-only
+      const isTouchDevice =
+        'ontouchstart' in window ||
+        navigator.maxTouchPoints > 0 ||
+        /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)
+
+      // Method 3: Check viewport characteristics for mobile devices
+      const isMobileViewport = window.innerWidth <= 768 && window.innerHeight <= 1024
+
+      // Combined heuristic: assume no physical keyboard if:
+      // - It's a touch device AND has mobile viewport AND lacks precise pointer
+      const likelyNoKeyboard = isTouchDevice && isMobileViewport && !hasKeyboardSupport
+
+      console.log('⌨️ Keyboard detection result:', !likelyNoKeyboard)
+      dispatch({
+        type: 'SET_PHYSICAL_KEYBOARD',
+        hasKeyboard: !likelyNoKeyboard,
+      })
+    }
+
+    // Test for actual keyboard input within 3 seconds
+    let keyboardDetected = false
+    const handleFirstKeyPress = (e: KeyboardEvent) => {
+      if (/^[0-9]$/.test(e.key)) {
+        console.log('⌨️ Physical keyboard detected via keypress')
+        keyboardDetected = true
+        dispatch({ type: 'SET_PHYSICAL_KEYBOARD', hasKeyboard: true })
+        document.removeEventListener('keypress', handleFirstKeyPress)
+        if (detectionTimer) clearTimeout(detectionTimer)
+      }
+    }
+
+    // Start detection
+    document.addEventListener('keypress', handleFirstKeyPress)
+
+    // Fallback to heuristic detection after 3 seconds
+    detectionTimer = setTimeout(() => {
+      if (!keyboardDetected) {
+        console.log('⌨️ Using fallback keyboard detection')
+        detectKeyboard()
+      }
+      document.removeEventListener('keypress', handleFirstKeyPress)
+    }, 3000)
+
+    // Initial heuristic detection (but don't commit to it yet)
+    const initialDetection = setTimeout(detectKeyboard, 100)
+
+    return () => {
+      document.removeEventListener('keypress', handleFirstKeyPress)
+      if (detectionTimer) clearTimeout(detectionTimer)
+      clearTimeout(initialDetection)
+    }
+  }, [testingMode, dispatch])
+
+  const acceptCorrectNumber = useCallback(
+    (number: number) => {
+      acceptNumber?.(number)
+      // setInput('') is called inside acceptNumber action creator
+      setDisplayFeedback('correct')
+
+      setTimeout(() => setDisplayFeedback('neutral'), 500)
+
+      // Auto-finish if all found
+      if (state.foundNumbers.length + 1 === state.correctAnswers.length) {
+        setTimeout(() => showResults?.(), 1000)
+      }
+    },
+    [acceptNumber, showResults, state.foundNumbers.length, state.correctAnswers.length]
+  )
+
+  const handleIncorrectGuess = useCallback(() => {
+    const wrongNumber = parseInt(state.currentInput, 10)
+    if (!Number.isNaN(wrongNumber)) {
+      dispatch({ type: 'ADD_WRONG_GUESS_ANIMATION', number: wrongNumber })
+      // Clear wrong guess animations after explosion
+      setTimeout(() => {
+        dispatch({ type: 'CLEAR_WRONG_GUESS_ANIMATIONS' })
+      }, 1500)
+    }
+
+    rejectNumber?.()
+    // setInput('') is called inside rejectNumber action creator
+    setDisplayFeedback('incorrect')
+
+    setTimeout(() => setDisplayFeedback('neutral'), 500)
+
+    // Auto-finish if out of guesses
+    if (state.guessesRemaining - 1 === 0) {
+      setTimeout(() => showResults?.(), 1000)
+    }
+  }, [state.currentInput, dispatch, rejectNumber, showResults, state.guessesRemaining])
+
+  // Simple keyboard event handlers that will be defined after callbacks
+  const handleKeyboardInput = useCallback(
+    (key: string) => {
+      // Handle number input
+      if (/^[0-9]$/.test(key)) {
+        // Only handle if input phase is active and guesses remain
+        if (state.guessesRemaining === 0) return
+
+        // Update input with new key
+        const newInput = state.currentInput + key
+        setInput?.(newInput)
+
+        // Clear any existing timeout
+        if (state.prefixAcceptanceTimeout) {
+          clearTimeout(state.prefixAcceptanceTimeout)
+          dispatch({ type: 'SET_PREFIX_TIMEOUT', timeout: null })
+        }
+
+        setDisplayFeedback('neutral')
+
+        const number = parseInt(newInput, 10)
+        if (Number.isNaN(number)) return
+
+        // Check if correct and not already found
+        if (state.correctAnswers.includes(number) && !state.foundNumbers.includes(number)) {
+          if (!isPrefix(newInput, state.correctAnswers, state.foundNumbers)) {
+            acceptCorrectNumber(number)
+          } else {
+            const timeout = setTimeout(() => {
+              acceptCorrectNumber(number)
+            }, 500)
+            dispatch({ type: 'SET_PREFIX_TIMEOUT', timeout })
+          }
+        } else {
+          // Check if this input could be a valid prefix or complete number
+          const couldBePrefix = state.correctAnswers.some((n) => n.toString().startsWith(newInput))
+          const isCompleteWrongNumber = !state.correctAnswers.includes(number) && !couldBePrefix
+
+          // Trigger explosion if:
+          // 1. It's a complete wrong number (length >= 2 or can't be a prefix)
+          // 2. It's a single digit that can't possibly be a prefix of any target
+          if ((newInput.length >= 2 || isCompleteWrongNumber) && state.guessesRemaining > 0) {
+            handleIncorrectGuess()
+          }
+        }
+      }
+    },
+    [
+      state.currentInput,
+      state.prefixAcceptanceTimeout,
+      state.correctAnswers,
+      state.foundNumbers,
+      state.guessesRemaining,
+      dispatch,
+      setInput,
+      acceptCorrectNumber,
+      handleIncorrectGuess,
+    ]
+  )
+
+  const handleKeyboardBackspace = useCallback(() => {
+    if (state.currentInput.length > 0) {
+      const newInput = state.currentInput.slice(0, -1)
+      setInput?.(newInput)
+
+      // Clear any existing timeout
+      if (state.prefixAcceptanceTimeout) {
+        clearTimeout(state.prefixAcceptanceTimeout)
+        dispatch({ type: 'SET_PREFIX_TIMEOUT', timeout: null })
+      }
+
+      setDisplayFeedback('neutral')
+    }
+  }, [state.currentInput, state.prefixAcceptanceTimeout, dispatch, setInput])
+
+  // Set up global keyboard listeners
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      // Only handle backspace/delete on keydown to prevent repetition
+      if (e.key === 'Backspace' || e.key === 'Delete') {
+        e.preventDefault()
+        handleKeyboardBackspace()
+      }
+    }
+
+    const handleKeyPressEvent = (e: KeyboardEvent) => {
+      // Handle number input
+      if (/^[0-9]$/.test(e.key)) {
+        handleKeyboardInput(e.key)
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown)
+    document.addEventListener('keypress', handleKeyPressEvent)
+
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown)
+      document.removeEventListener('keypress', handleKeyPressEvent)
+    }
+  }, [handleKeyboardInput, handleKeyboardBackspace])
+
+  const hasFoundSome = state.foundNumbers.length > 0
+  const hasFoundAll = state.foundNumbers.length === state.correctAnswers.length
+  const outOfGuesses = state.guessesRemaining === 0
+  const showFinishButtons = hasFoundAll || outOfGuesses || hasFoundSome
+
+  return (
+    <div
+      style={{
+        textAlign: 'center',
+        padding: '12px',
+        paddingBottom:
+          (hasPhysicalKeyboard === false || testingMode) && state.guessesRemaining > 0
+            ? '100px'
+            : '12px', // Add space for keyboard
+        maxWidth: '800px',
+        margin: '0 auto',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'flex-start',
+      }}
+    >
+      <h3
+        style={{
+          marginBottom: '16px',
+          color: '#1f2937',
+          fontSize: '18px',
+          fontWeight: '600',
+        }}
+      >
+        Enter the Numbers You Remember
+      </h3>
+      <div
+        style={{
+          display: 'flex',
+          justifyContent: 'center',
+          gap: '16px',
+          marginBottom: '20px',
+          padding: '16px',
+          background: '#f9fafb',
+          borderRadius: '8px',
+          flexWrap: 'wrap',
+        }}
+      >
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            minWidth: '80px',
+          }}
+        >
+          <span
+            style={{
+              fontSize: '12px',
+              color: '#6b7280',
+              fontWeight: '500',
+            }}
+          >
+            Cards shown:
+          </span>
+          <span
+            style={{
+              fontSize: '20px',
+              fontWeight: 'bold',
+              color: '#1f2937',
+            }}
+          >
+            {state.quizCards.length}
+          </span>
+        </div>
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            minWidth: '80px',
+          }}
+        >
+          <span
+            style={{
+              fontSize: '12px',
+              color: '#6b7280',
+              fontWeight: '500',
+            }}
+          >
+            Guesses left:
+          </span>
+          <span
+            style={{
+              fontSize: '20px',
+              fontWeight: 'bold',
+              color: '#1f2937',
+            }}
+          >
+            {state.guessesRemaining}
+          </span>
+        </div>
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            minWidth: '80px',
+          }}
+        >
+          <span
+            style={{
+              fontSize: '12px',
+              color: '#6b7280',
+              fontWeight: '500',
+            }}
+          >
+            Found:
+          </span>
+          <span
+            style={{
+              fontSize: '20px',
+              fontWeight: 'bold',
+              color: '#1f2937',
+            }}
+          >
+            {state.foundNumbers.length}
+          </span>
+        </div>
+      </div>
+
+      {/* Live Scoreboard - Competitive Mode Only */}
+      {state.playMode === 'competitive' &&
+        state.activePlayers &&
+        state.activePlayers.length > 1 && (
+          <div
+            style={{
+              marginBottom: '16px',
+              padding: '12px',
+              background: 'linear-gradient(135deg, #fef3c7 0%, #fde68a 100%)',
+              borderRadius: '8px',
+              border: '2px solid #f59e0b',
+            }}
+          >
+            <div
+              style={{
+                fontSize: '12px',
+                fontWeight: 'bold',
+                color: '#92400e',
+                marginBottom: '8px',
+                textAlign: 'center',
+              }}
+            >
+              🏆 LIVE SCOREBOARD
+            </div>
+            <div
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                gap: '6px',
+              }}
+            >
+              {(() => {
+                // Group players by userId
+                const userTeams = new Map<
+                  string,
+                  { userId: string; players: any[]; score: { correct: number; incorrect: number } }
+                >()
+
+                console.log('📊 [InputPhase] Building scoreboard:', {
+                  activePlayers: state.activePlayers,
+                  playerMetadata: state.playerMetadata,
+                  playerScores: state.playerScores,
+                })
+
+                for (const playerId of state.activePlayers) {
+                  const metadata = state.playerMetadata?.[playerId]
+                  const userId = metadata?.userId
+                  console.log('📊 [InputPhase] Processing player for scoreboard:', {
+                    playerId,
+                    metadata,
+                    userId,
+                  })
+                  if (!userId) continue
+
+                  if (!userTeams.has(userId)) {
+                    userTeams.set(userId, {
+                      userId,
+                      players: [],
+                      score: state.playerScores?.[userId] || { correct: 0, incorrect: 0 },
+                    })
+                  }
+                  userTeams.get(userId)!.players.push(metadata)
+                }
+
+                console.log('📊 [InputPhase] UserTeams created:', {
+                  count: userTeams.size,
+                  teams: Array.from(userTeams.entries()),
+                })
+
+                // Sort teams by score
+                return Array.from(userTeams.values())
+                  .sort((a, b) => {
+                    const aScore = a.score.correct - a.score.incorrect * 0.5
+                    const bScore = b.score.correct - b.score.incorrect * 0.5
+                    return bScore - aScore
+                  })
+                  .map((team, index) => {
+                    const netScore = team.score.correct - team.score.incorrect * 0.5
+                    return (
+                      <div
+                        key={team.userId}
+                        style={{
+                          padding: '10px 12px',
+                          background: index === 0 ? '#fef3c7' : 'white',
+                          borderRadius: '8px',
+                          border: index === 0 ? '2px solid #f59e0b' : '1px solid #e5e7eb',
+                        }}
+                      >
+                        {/* Team header with rank and stats */}
+                        <div
+                          style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'space-between',
+                            marginBottom: '8px',
+                          }}
+                        >
+                          <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+                            <span style={{ fontSize: '18px' }}>
+                              {index === 0 ? '👑' : `${index + 1}.`}
+                            </span>
+                            <span
+                              style={{
+                                fontWeight: 'bold',
+                                fontSize: '16px',
+                                color: '#1f2937',
+                              }}
+                            >
+                              Score: {netScore.toFixed(1)}
+                            </span>
+                          </div>
+                          <div
+                            style={{
+                              display: 'flex',
+                              alignItems: 'center',
+                              gap: '10px',
+                              fontSize: '14px',
+                            }}
+                          >
+                            <span style={{ color: '#10b981', fontWeight: 'bold' }}>
+                              ✓{team.score.correct}
+                            </span>
+                            <span style={{ color: '#ef4444', fontWeight: 'bold' }}>
+                              ✗{team.score.incorrect}
+                            </span>
+                          </div>
+                        </div>
+                        {/* Players list */}
+                        <div
+                          style={{
+                            display: 'flex',
+                            flexDirection: 'column',
+                            gap: '4px',
+                            paddingLeft: '26px',
+                          }}
+                        >
+                          {team.players.map((player, i) => (
+                            <div
+                              key={i}
+                              style={{
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: '6px',
+                                fontSize: '13px',
+                              }}
+                            >
+                              <span style={{ fontSize: '16px' }}>{player?.emoji || '🎮'}</span>
+                              <span
+                                style={{
+                                  color: '#1f2937',
+                                  fontWeight: '500',
+                                }}
+                              >
+                                {player?.name || `Player ${i + 1}`}
+                              </span>
+                            </div>
+                          ))}
+                        </div>
+                      </div>
+                    )
+                  })
+              })()}
+            </div>
+          </div>
+        )}
+
+      <div
+        style={{
+          position: 'relative',
+          margin: '16px 0',
+          textAlign: 'center',
+        }}
+      >
+        <div
+          style={{
+            fontSize: '12px',
+            color: '#6b7280',
+            marginBottom: '8px',
+            fontWeight: '500',
+          }}
+        >
+          {state.guessesRemaining === 0
+            ? '🚫 No more guesses available'
+            : '⌨️ Type the numbers you remember'}
+        </div>
+
+        {/* Testing control - remove in production */}
+        <div
+          style={{
+            fontSize: '10px',
+            color: '#9ca3af',
+            marginBottom: '4px',
+          }}
+        >
+          <label
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: '4px',
+              justifyContent: 'center',
+            }}
+          >
+            <input
+              type="checkbox"
+              checked={testingMode}
+              onChange={(e) =>
+                dispatch({
+                  type: 'SET_TESTING_MODE',
+                  enabled: e.target.checked,
+                })
+              }
+            />
+            Test on-screen keyboard (for demo)
+          </label>
+          <div style={{ fontSize: '9px', opacity: 0.7 }}>
+            Keyboard detected:{' '}
+            {hasPhysicalKeyboard === null ? 'detecting...' : hasPhysicalKeyboard ? 'yes' : 'no'}
+          </div>
+        </div>
+        <div
+          style={{
+            minHeight: '50px',
+            padding: '12px 16px',
+            fontSize: '22px',
+            fontFamily: 'system-ui, -apple-system, sans-serif',
+            textAlign: 'center',
+            fontWeight: '600',
+            color: state.guessesRemaining === 0 ? '#6b7280' : '#1f2937',
+            letterSpacing: '1px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            transition: 'all 0.3s ease',
+            background:
+              displayFeedback === 'correct'
+                ? 'linear-gradient(45deg, #d4edda, #c3e6cb)'
+                : displayFeedback === 'incorrect'
+                  ? 'linear-gradient(45deg, #f8d7da, #f1b0b7)'
+                  : state.guessesRemaining === 0
+                    ? '#e5e7eb'
+                    : 'linear-gradient(135deg, #f0f8ff, #e6f3ff)',
+            borderRadius: '12px',
+            position: 'relative',
+            border: '2px solid',
+            borderColor:
+              displayFeedback === 'correct'
+                ? '#28a745'
+                : displayFeedback === 'incorrect'
+                  ? '#dc3545'
+                  : state.guessesRemaining === 0
+                    ? '#9ca3af'
+                    : '#3b82f6',
+            boxShadow:
+              displayFeedback === 'correct'
+                ? '0 4px 12px rgba(40, 167, 69, 0.2)'
+                : displayFeedback === 'incorrect'
+                  ? '0 4px 12px rgba(220, 53, 69, 0.2)'
+                  : '0 4px 12px rgba(59, 130, 246, 0.15)',
+            cursor: state.guessesRemaining === 0 ? 'not-allowed' : 'pointer',
+          }}
+        >
+          <span style={{ opacity: 1, position: 'relative' }}>
+            {state.guessesRemaining === 0
+              ? '🔒 Game Over'
+              : state.currentInput || (
+                  <span
+                    style={{
+                      color: '#74c0fc',
+                      opacity: 0.8,
+                      fontStyle: 'normal',
+                      fontSize: '20px',
+                    }}
+                  >
+                    💭 Think & Type
+                  </span>
+                )}
+            {state.currentInput && (
+              <span
+                style={{
+                  position: 'absolute',
+                  right: '-8px',
+                  top: '50%',
+                  transform: 'translateY(-50%)',
+                  width: '2px',
+                  height: '20px',
+                  background: '#3b82f6',
+                  animation: 'blink 1s infinite',
+                }}
+              />
+            )}
+          </span>
+        </div>
+      </div>
+
+      {/* Visual card grid showing cards the user was shown */}
+      <div
+        style={{
+          marginTop: '12px',
+          flex: 1,
+          overflow: 'auto',
+          minHeight: '0',
+        }}
+      >
+        <CardGrid state={state} />
+      </div>
+
+      {/* Wrong guess explosion animations */}
+      <div
+        style={{
+          position: 'fixed',
+          top: 0,
+          left: 0,
+          width: '100vw',
+          height: '100vh',
+          pointerEvents: 'none',
+          zIndex: 1000,
+        }}
+      >
+        {state.wrongGuessAnimations.map((animation) => (
+          <div
+            key={animation.id}
+            style={{
+              position: 'absolute',
+              top: '50%',
+              left: '50%',
+              transform: 'translate(-50%, -50%)',
+              fontSize: '48px',
+              fontWeight: 'bold',
+              color: '#ef4444',
+              textShadow: '2px 2px 4px rgba(0, 0, 0, 0.3)',
+              animation: 'explode 1.5s ease-out forwards',
+            }}
+          >
+            {animation.number}
+          </div>
+        ))}
+      </div>
+
+      {/* Simple fixed keyboard bar - appears when needed, no hiding of game elements */}
+      {(hasPhysicalKeyboard === false || testingMode) && state.guessesRemaining > 0 && (
+        <div
+          style={{
+            position: 'fixed',
+            bottom: 0,
+            left: 0,
+            right: 0,
+            background: 'linear-gradient(135deg, #f8fafc 0%, #e2e8f0 100%)',
+            borderTop: '2px solid #3b82f6',
+            padding: '12px',
+            zIndex: 1000,
+            display: 'flex',
+            gap: '8px',
+            justifyContent: 'center',
+            flexWrap: 'wrap',
+            boxShadow: '0 -4px 12px rgba(0, 0, 0, 0.1)',
+          }}
+        >
+          {[1, 2, 3, 4, 5, 6, 7, 8, 9, 0].map((digit) => (
+            <button
+              key={digit}
+              style={{
+                padding: '12px 16px',
+                border: '2px solid #e5e7eb',
+                borderRadius: '8px',
+                background: 'white',
+                fontSize: '18px',
+                fontWeight: 'bold',
+                color: '#1f2937',
+                cursor: 'pointer',
+                minWidth: '50px',
+                minHeight: '50px',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                userSelect: 'none',
+                boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)',
+                transition: 'all 0.15s ease',
+              }}
+              onMouseDown={(e) => {
+                e.currentTarget.style.transform = 'scale(0.95)'
+                e.currentTarget.style.background = '#f3f4f6'
+                e.currentTarget.style.borderColor = '#3b82f6'
+              }}
+              onMouseUp={(e) => {
+                e.currentTarget.style.transform = 'scale(1)'
+                e.currentTarget.style.background = 'white'
+                e.currentTarget.style.borderColor = '#e5e7eb'
+              }}
+              onMouseLeave={(e) => {
+                e.currentTarget.style.transform = 'scale(1)'
+                e.currentTarget.style.background = 'white'
+                e.currentTarget.style.borderColor = '#e5e7eb'
+              }}
+              onClick={() => handleKeyboardInput(digit.toString())}
+            >
+              {digit}
+            </button>
+          ))}
+          <button
+            style={{
+              padding: '12px 16px',
+              border: '2px solid #dc2626',
+              borderRadius: '8px',
+              background: state.currentInput.length > 0 ? '#fef2f2' : '#f9fafb',
+              fontSize: '14px',
+              fontWeight: 'bold',
+              color: state.currentInput.length > 0 ? '#dc2626' : '#9ca3af',
+              cursor: state.currentInput.length > 0 ? 'pointer' : 'not-allowed',
+              minWidth: '70px',
+              minHeight: '50px',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              userSelect: 'none',
+              transition: 'all 0.15s ease',
+            }}
+            disabled={state.currentInput.length === 0}
+            onClick={handleKeyboardBackspace}
+          >
+            ⌫
+          </button>
+        </div>
+      )}
+
+      {showFinishButtons && (
+        <div
+          style={{
+            display: 'flex',
+            justifyContent: 'center',
+            gap: '8px',
+            marginTop: '12px',
+            paddingTop: '12px',
+            borderTop: '1px solid #e5e7eb',
+            flexWrap: 'wrap',
+          }}
+        >
+          <button
+            style={{
+              padding: '10px 20px',
+              border: 'none',
+              borderRadius: '6px',
+              fontSize: '14px',
+              fontWeight: 'bold',
+              cursor: 'pointer',
+              transition: 'all 0.2s ease',
+              background: '#3b82f6',
+              color: 'white',
+              minWidth: '120px',
+            }}
+            onClick={() => showResults?.()}
+          >
+            {hasFoundAll ? 'Finish Quiz' : 'Show Results'}
+          </button>
+          {hasFoundSome && !hasFoundAll && !outOfGuesses && (
+            <button
+              style={{
+                padding: '10px 20px',
+                border: 'none',
+                borderRadius: '6px',
+                fontSize: '14px',
+                fontWeight: 'bold',
+                cursor: 'pointer',
+                transition: 'all 0.2s ease',
+                background: '#6b7280',
+                color: 'white',
+                minWidth: '120px',
+              }}
+              onClick={() => showResults?.()}
+            >
+              Can't Remember More
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

apps/web/src/app/arcade/memory-quiz/components/MemoryQuizGame.tsx

@@ -0,0 +1,157 @@
+'use client'
+
+import Link from 'next/link'
+import { useRouter } from 'next/navigation'
+import { PageWithNav } from '@/components/PageWithNav'
+import { css } from '../../../../../styled-system/css'
+import { useMemoryQuiz } from '../context/MemoryQuizContext'
+import { DisplayPhase } from './DisplayPhase'
+import { InputPhase } from './InputPhase'
+import { ResultsPhase } from './ResultsPhase'
+import { SetupPhase } from './SetupPhase'
+
+// CSS animations that need to be global
+const globalAnimations = `
+@keyframes pulse {
+  0% { transform: scale(1); box-shadow: 0 4px 12px rgba(59, 130, 246, 0.3); }
+  50% { transform: scale(1.05); box-shadow: 0 6px 20px rgba(59, 130, 246, 0.5); }
+  100% { transform: scale(1); box-shadow: 0 4px 12px rgba(59, 130, 246, 0.3); }
+}
+
+@keyframes subtlePageFlash {
+  0% { background: linear-gradient(to bottom right, #f0fdf4, #ecfdf5); }
+  50% { background: linear-gradient(to bottom right, #dcfce7, #d1fae5); }
+  100% { background: linear-gradient(to bottom right, #f0fdf4, #ecfdf5); }
+}
+
+@keyframes fadeInScale {
+  from { opacity: 0; transform: scale(0.8); }
+  to { opacity: 1; transform: scale(1); }
+}
+
+@keyframes explode {
+  0% {
+    opacity: 1;
+    transform: translate(-50%, -50%) scale(1);
+  }
+  50% {
+    opacity: 1;
+    transform: translate(-50%, -50%) scale(1.5);
+  }
+  100% {
+    opacity: 0;
+    transform: translate(-50%, -50%) scale(2) rotate(180deg);
+  }
+}
+
+@keyframes blink {
+  0%, 50% { opacity: 1; }
+  51%, 100% { opacity: 0; }
+}
+
+@keyframes slideUp {
+  from {
+    opacity: 0;
+    transform: translateX(-50%) translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(-50%) translateY(0);
+  }
+}
+`
+
+export function MemoryQuizGame() {
+  const router = useRouter()
+  const { state, exitSession, resetGame } = useMemoryQuiz()
+
+  return (
+    <PageWithNav
+      navTitle="Memory Lightning"
+      navEmoji="🧠"
+      emphasizePlayerSelection={state.gamePhase === 'setup'}
+      onExitSession={() => {
+        exitSession?.()
+        router.push('/arcade')
+      }}
+      onNewGame={() => {
+        resetGame?.()
+      }}
+    >
+      <style dangerouslySetInnerHTML={{ __html: globalAnimations }} />
+
+      <div
+        style={{
+          flex: 1,
+          display: 'flex',
+          flexDirection: 'column',
+          overflow: 'auto',
+          padding: '20px 8px',
+          minHeight: '100vh',
+          background: 'linear-gradient(135deg, #f8fafc, #e2e8f0)',
+        }}
+      >
+        <div
+          style={{
+            maxWidth: '100%',
+            margin: '0 auto',
+            flex: 1,
+            display: 'flex',
+            flexDirection: 'column',
+          }}
+        >
+          <div
+            className={css({
+              textAlign: 'center',
+              mb: '4',
+              flexShrink: 0,
+            })}
+          >
+            <Link
+              href="/arcade"
+              className={css({
+                display: 'inline-flex',
+                alignItems: 'center',
+                color: 'gray.600',
+                textDecoration: 'none',
+                mb: '4',
+                _hover: { color: 'gray.800' },
+              })}
+            >
+              ← Back to Champion Arena
+            </Link>
+          </div>
+
+          <div
+            className={css({
+              bg: 'white',
+              rounded: 'xl',
+              shadow: 'xl',
+              overflow: 'hidden',
+              border: '1px solid',
+              borderColor: 'gray.200',
+              flex: 1,
+              display: 'flex',
+              flexDirection: 'column',
+              maxHeight: '100%',
+            })}
+          >
+            <div
+              className={css({
+                flex: 1,
+                display: 'flex',
+                flexDirection: 'column',
+                overflow: 'auto',
+              })}
+            >
+              {state.gamePhase === 'setup' && <SetupPhase />}
+              {state.gamePhase === 'display' && <DisplayPhase />}
+              {state.gamePhase === 'input' && <InputPhase key="input-phase" />}
+              {state.gamePhase === 'results' && <ResultsPhase />}
+            </div>
+          </div>
+        </div>
+      </div>
+    </PageWithNav>
+  )
+}

apps/web/src/app/arcade/memory-quiz/components/ResultsCardGrid.tsx

@@ -0,0 +1,254 @@
+import { AbacusReact } from '@soroban/abacus-react'
+import type { SorobanQuizState } from '../types'
+
+interface ResultsCardGridProps {
+  state: SorobanQuizState
+}
+
+export function ResultsCardGrid({ state }: ResultsCardGridProps) {
+  if (state.quizCards.length === 0) return null
+
+  // Calculate optimal grid layout based on number of cards (same as CardGrid)
+  const cardCount = state.quizCards.length
+
+  // Define static grid classes that Panda can generate (same as CardGrid)
+  const getGridClass = (count: number) => {
+    if (count <= 2) return 'repeat(2, 1fr)'
+    if (count <= 4) return 'repeat(2, 1fr)'
+    if (count <= 6) return 'repeat(3, 1fr)'
+    if (count <= 9) return 'repeat(3, 1fr)'
+    if (count <= 12) return 'repeat(4, 1fr)'
+    return 'repeat(5, 1fr)'
+  }
+
+  const getCardSize = (count: number) => {
+    if (count <= 2) return { minSize: '180px', cardHeight: '160px' }
+    if (count <= 4) return { minSize: '160px', cardHeight: '150px' }
+    if (count <= 6) return { minSize: '140px', cardHeight: '140px' }
+    if (count <= 9) return { minSize: '120px', cardHeight: '130px' }
+    if (count <= 12) return { minSize: '110px', cardHeight: '120px' }
+    return { minSize: '100px', cardHeight: '110px' }
+  }
+
+  const gridClass = getGridClass(cardCount)
+  const cardSize = getCardSize(cardCount)
+
+  return (
+    <div>
+      <div
+        style={{
+          display: 'grid',
+          gap: '8px',
+          padding: '6px',
+          justifyContent: 'center',
+          maxWidth: '100%',
+          margin: '0 auto',
+          gridTemplateColumns: gridClass,
+        }}
+      >
+        {state.quizCards.map((card, index) => {
+          const isRevealed = true // All cards revealed in results
+          const wasFound = state.foundNumbers.includes(card.number)
+
+          return (
+            <div
+              key={`${card.number}-${index}`}
+              style={{
+                perspective: '1000px',
+                position: 'relative',
+                aspectRatio: '3/4',
+                height: cardSize.cardHeight,
+                minWidth: cardSize.minSize,
+              }}
+            >
+              <div
+                style={{
+                  position: 'relative',
+                  width: '100%',
+                  height: '100%',
+                  textAlign: 'center',
+                  transition: 'transform 0.8s',
+                  transformStyle: 'preserve-3d',
+                  transform: isRevealed ? 'rotateY(180deg)' : 'rotateY(0deg)',
+                }}
+              >
+                {/* Card back (hidden state) - not visible in results */}
+                <div
+                  style={{
+                    position: 'absolute',
+                    width: '100%',
+                    height: '100%',
+                    backfaceVisibility: 'hidden',
+                    borderRadius: '8px',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)',
+                    background: 'linear-gradient(135deg, #6c5ce7, #a29bfe)',
+                    color: 'white',
+                    fontSize: '24px',
+                    fontWeight: 'bold',
+                    textShadow: '1px 1px 2px rgba(0, 0, 0, 0.3)',
+                    border: '2px solid #5f3dc4',
+                  }}
+                >
+                  <div style={{ opacity: 0.8 }}>?</div>
+                </div>
+
+                {/* Card front (revealed state) with success/failure indicators */}
+                <div
+                  style={{
+                    position: 'absolute',
+                    width: '100%',
+                    height: '100%',
+                    backfaceVisibility: 'hidden',
+                    borderRadius: '8px',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)',
+                    background: 'white',
+                    border: '2px solid',
+                    borderColor: wasFound ? '#10b981' : '#ef4444',
+                    transform: 'rotateY(180deg)',
+                  }}
+                >
+                  <div
+                    style={{
+                      width: '100%',
+                      height: '100%',
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      overflow: 'hidden',
+                      padding: '4px',
+                    }}
+                  >
+                    <div
+                      style={{
+                        width: '100%',
+                        height: '100%',
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                      }}
+                    >
+                      <AbacusReact
+                        value={card.number}
+                        columns="auto"
+                        beadShape="diamond"
+                        colorScheme="place-value"
+                        hideInactiveBeads={false}
+                        scaleFactor={1.2}
+                        interactive={false}
+                        showNumbers={false}
+                        animated={false}
+                      />
+                    </div>
+                  </div>
+
+                  {/* Player indicator overlay */}
+                  <div
+                    style={{
+                      position: 'absolute',
+                      top: '4px',
+                      right: '4px',
+                      minWidth: wasFound ? '24px' : '20px',
+                      minHeight: '20px',
+                      maxHeight: '48px',
+                      borderRadius: wasFound ? '8px' : '50%',
+                      background: wasFound ? '#10b981' : '#ef4444',
+                      color: 'white',
+                      display: 'flex',
+                      flexDirection: 'column',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      fontSize: wasFound ? '14px' : '12px',
+                      fontWeight: 'bold',
+                      boxShadow: '0 1px 2px rgba(0, 0, 0, 0.2)',
+                      padding: wasFound ? '2px' : '0',
+                      gap: '1px',
+                      overflow: 'hidden',
+                    }}
+                  >
+                    {wasFound
+                      ? (() => {
+                          // Get the userId who found this number
+                          const foundByUserId = state.numberFoundBy?.[card.number]
+                          if (!foundByUserId) return '✓'
+
+                          // Get all players on that team
+                          const teamPlayers = state.activePlayers
+                            ?.filter((playerId) => {
+                              const metadata = state.playerMetadata?.[playerId]
+                              return metadata?.userId === foundByUserId
+                            })
+                            .map((playerId) => state.playerMetadata?.[playerId])
+                            .filter(Boolean)
+
+                          if (!teamPlayers || teamPlayers.length === 0) return '✓'
+
+                          // Display emojis (stacked vertically if multiple)
+                          return teamPlayers.map((player, idx) => (
+                            <span
+                              key={idx}
+                              style={{
+                                lineHeight: '1',
+                                fontSize: '14px',
+                              }}
+                            >
+                              {player?.emoji || '🎮'}
+                            </span>
+                          ))
+                        })()
+                      : '✗'}
+                  </div>
+
+                  {/* Number label overlay */}
+                  <div
+                    style={{
+                      position: 'absolute',
+                      bottom: '4px',
+                      left: '4px',
+                      padding: '2px 4px',
+                      borderRadius: '3px',
+                      background: 'rgba(0, 0, 0, 0.7)',
+                      color: 'white',
+                      fontSize: '10px',
+                      fontWeight: 'bold',
+                    }}
+                  >
+                    {card.number}
+                  </div>
+                </div>
+              </div>
+            </div>
+          )
+        })}
+      </div>
+
+      {/* Summary row for large numbers of cards (same as CardGrid) */}
+      {cardCount > 8 && (
+        <div
+          style={{
+            marginTop: '8px',
+            padding: '6px 8px',
+            background: '#eff6ff',
+            borderRadius: '6px',
+            border: '1px solid #bfdbfe',
+            textAlign: 'center',
+            fontSize: '12px',
+            color: '#1d4ed8',
+          }}
+        >
+          <strong>{state.foundNumbers.length}</strong> of <strong>{cardCount}</strong> cards found
+          {state.foundNumbers.length > 0 && (
+            <span style={{ marginLeft: '6px', fontWeight: 'normal' }}>
+              ({Math.round((state.foundNumbers.length / cardCount) * 100)}% complete)
+            </span>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

apps/web/src/app/arcade/memory-quiz/components/ResultsPhase.tsx

@@ -0,0 +1,561 @@
+import { useAbacusConfig } from '@soroban/abacus-react'
+import { useMemoryQuiz } from '../context/MemoryQuizContext'
+import { DIFFICULTY_LEVELS, type DifficultyLevel, type QuizCard } from '../types'
+import { ResultsCardGrid } from './ResultsCardGrid'
+
+// Generate quiz cards with difficulty-based number ranges
+const generateQuizCards = (
+  count: number,
+  difficulty: DifficultyLevel,
+  appConfig: any
+): QuizCard[] => {
+  const { min, max } = DIFFICULTY_LEVELS[difficulty].range
+
+  // Generate unique numbers - no duplicates allowed
+  const numbers: number[] = []
+  const maxAttempts = (max - min + 1) * 10 // Prevent infinite loops
+  let attempts = 0
+
+  while (numbers.length < count && attempts < maxAttempts) {
+    const newNumber = Math.floor(Math.random() * (max - min + 1)) + min
+    if (!numbers.includes(newNumber)) {
+      numbers.push(newNumber)
+    }
+    attempts++
+  }
+
+  // If we couldn't generate enough unique numbers, fill with sequential numbers
+  if (numbers.length < count) {
+    for (let i = min; i <= max && numbers.length < count; i++) {
+      if (!numbers.includes(i)) {
+        numbers.push(i)
+      }
+    }
+  }
+
+  return numbers.map((number) => ({
+    number,
+    svgComponent: <div />, // Placeholder - not used in results phase
+    element: null,
+  }))
+}
+
+export function ResultsPhase() {
+  const { state, resetGame, startQuiz } = useMemoryQuiz()
+  const appConfig = useAbacusConfig()
+  const correct = state.foundNumbers.length
+  const total = state.correctAnswers.length
+  const percentage = Math.round((correct / total) * 100)
+
+  return (
+    <div
+      style={{
+        textAlign: 'center',
+        padding: '12px',
+        maxWidth: '800px',
+        margin: '0 auto',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'flex-start',
+      }}
+    >
+      <h3
+        style={{
+          marginBottom: '20px',
+          color: '#1f2937',
+          fontSize: '18px',
+          fontWeight: '600',
+        }}
+      >
+        Quiz Results
+      </h3>
+      <div
+        style={{
+          display: 'flex',
+          justifyContent: 'center',
+          alignItems: 'center',
+          gap: '16px',
+          marginBottom: '20px',
+          padding: '16px',
+          background: '#f9fafb',
+          borderRadius: '8px',
+          flexWrap: 'wrap',
+        }}
+      >
+        <div
+          style={{
+            width: '80px',
+            height: '80px',
+            borderRadius: '50%',
+            background: 'linear-gradient(45deg, #3b82f6, #2563eb)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            color: 'white',
+            fontSize: '18px',
+            fontWeight: 'bold',
+          }}
+        >
+          <span>{percentage}%</span>
+        </div>
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '8px',
+          }}
+        >
+          <div
+            style={{
+              display: 'flex',
+              justifyContent: 'space-between',
+              gap: '12px',
+              fontSize: '16px',
+            }}
+          >
+            <span style={{ fontWeight: '500', color: '#6b7280' }}>Correct:</span>
+            <span style={{ fontWeight: 'bold' }}>{correct}</span>
+          </div>
+          <div
+            style={{
+              display: 'flex',
+              justifyContent: 'space-between',
+              gap: '12px',
+              fontSize: '16px',
+            }}
+          >
+            <span style={{ fontWeight: '500', color: '#6b7280' }}>Total:</span>
+            <span style={{ fontWeight: 'bold' }}>{total}</span>
+          </div>
+        </div>
+      </div>
+
+      {/* Multiplayer Leaderboard - Competitive Mode */}
+      {state.playMode === 'competitive' &&
+        state.activePlayers &&
+        state.activePlayers.length > 1 && (
+          <div
+            style={{
+              marginBottom: '16px',
+              padding: '16px',
+              background: 'linear-gradient(135deg, #fef3c7 0%, #fde68a 100%)',
+              borderRadius: '12px',
+              border: '2px solid #f59e0b',
+            }}
+          >
+            <div
+              style={{
+                fontSize: '16px',
+                fontWeight: 'bold',
+                color: '#92400e',
+                marginBottom: '12px',
+                textAlign: 'center',
+              }}
+            >
+              🏆 FINAL LEADERBOARD
+            </div>
+            <div
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                gap: '8px',
+              }}
+            >
+              {(() => {
+                // Group players by userId
+                const userTeams = new Map<
+                  string,
+                  { userId: string; players: any[]; score: { correct: number; incorrect: number } }
+                >()
+
+                console.log('🏆 [ResultsPhase] Building leaderboard:', {
+                  activePlayers: state.activePlayers,
+                  playerMetadata: state.playerMetadata,
+                  playerScores: state.playerScores,
+                })
+
+                for (const playerId of state.activePlayers) {
+                  const metadata = state.playerMetadata?.[playerId]
+                  const userId = metadata?.userId
+                  console.log('🏆 [ResultsPhase] Processing player for leaderboard:', {
+                    playerId,
+                    metadata,
+                    userId,
+                  })
+                  if (!userId) continue
+
+                  if (!userTeams.has(userId)) {
+                    userTeams.set(userId, {
+                      userId,
+                      players: [],
+                      score: state.playerScores?.[userId] || { correct: 0, incorrect: 0 },
+                    })
+                  }
+                  userTeams.get(userId)!.players.push(metadata)
+                }
+
+                console.log('🏆 [ResultsPhase] UserTeams created:', {
+                  count: userTeams.size,
+                  teams: Array.from(userTeams.entries()),
+                })
+
+                // Sort teams by score
+                return Array.from(userTeams.values())
+                  .sort((a, b) => {
+                    const aScore = a.score.correct - a.score.incorrect * 0.5
+                    const bScore = b.score.correct - b.score.incorrect * 0.5
+                    return bScore - aScore
+                  })
+                  .map((team, index) => {
+                    const netScore = team.score.correct - team.score.incorrect * 0.5
+                    return (
+                      <div
+                        key={team.userId}
+                        style={{
+                          padding: '14px 16px',
+                          background:
+                            index === 0
+                              ? 'linear-gradient(135deg, #fef3c7 0%, #fde68a 50%)'
+                              : 'white',
+                          borderRadius: '10px',
+                          border: index === 0 ? '3px solid #f59e0b' : '1px solid #e5e7eb',
+                          boxShadow: index === 0 ? '0 4px 12px rgba(245, 158, 11, 0.3)' : 'none',
+                        }}
+                      >
+                        {/* Team header with rank and stats */}
+                        <div
+                          style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'space-between',
+                            marginBottom: '10px',
+                          }}
+                        >
+                          <div style={{ display: 'flex', alignItems: 'center', gap: '10px' }}>
+                            <span style={{ fontSize: '24px', minWidth: '32px' }}>
+                              {index === 0
+                                ? '🏆'
+                                : index === 1
+                                  ? '🥈'
+                                  : index === 2
+                                    ? '🥉'
+                                    : `${index + 1}.`}
+                            </span>
+                            <div style={{ display: 'flex', flexDirection: 'column' }}>
+                              <span
+                                style={{
+                                  fontWeight: 'bold',
+                                  fontSize: index === 0 ? '20px' : '18px',
+                                  color: index === 0 ? '#f59e0b' : '#1f2937',
+                                }}
+                              >
+                                {netScore.toFixed(1)}
+                              </span>
+                              {index === 0 && (
+                                <span
+                                  style={{
+                                    fontSize: '11px',
+                                    color: '#92400e',
+                                    fontWeight: 'bold',
+                                  }}
+                                >
+                                  CHAMPION
+                                </span>
+                              )}
+                            </div>
+                          </div>
+                          <div
+                            style={{
+                              display: 'flex',
+                              alignItems: 'center',
+                              gap: '12px',
+                            }}
+                          >
+                            <div
+                              style={{
+                                display: 'flex',
+                                flexDirection: 'column',
+                                alignItems: 'center',
+                              }}
+                            >
+                              <span
+                                style={{
+                                  color: '#10b981',
+                                  fontWeight: 'bold',
+                                  fontSize: '16px',
+                                }}
+                              >
+                                ✓{team.score.correct}
+                              </span>
+                              <span style={{ fontSize: '10px', color: '#6b7280' }}>correct</span>
+                            </div>
+                            <div
+                              style={{
+                                display: 'flex',
+                                flexDirection: 'column',
+                                alignItems: 'center',
+                              }}
+                            >
+                              <span
+                                style={{
+                                  color: '#ef4444',
+                                  fontWeight: 'bold',
+                                  fontSize: '16px',
+                                }}
+                              >
+                                ✗{team.score.incorrect}
+                              </span>
+                              <span style={{ fontSize: '10px', color: '#6b7280' }}>wrong</span>
+                            </div>
+                          </div>
+                        </div>
+                        {/* Players list */}
+                        <div
+                          style={{
+                            display: 'flex',
+                            flexDirection: 'column',
+                            gap: '6px',
+                            paddingLeft: '42px',
+                          }}
+                        >
+                          {team.players.map((player, i) => (
+                            <div
+                              key={i}
+                              style={{
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: '8px',
+                              }}
+                            >
+                              <span style={{ fontSize: '18px' }}>{player?.emoji || '🎮'}</span>
+                              <span
+                                style={{
+                                  color: '#1f2937',
+                                  fontWeight: '500',
+                                  fontSize: '14px',
+                                }}
+                              >
+                                {player?.name || `Player ${i + 1}`}
+                              </span>
+                            </div>
+                          ))}
+                        </div>
+                      </div>
+                    )
+                  })
+              })()}
+            </div>
+          </div>
+        )}
+
+      {/* Multiplayer Stats - Cooperative Mode */}
+      {state.playMode === 'cooperative' &&
+        state.activePlayers &&
+        state.activePlayers.length > 1 && (
+          <div
+            style={{
+              marginBottom: '16px',
+              padding: '16px',
+              background: 'linear-gradient(135deg, #dbeafe 0%, #bfdbfe 100%)',
+              borderRadius: '12px',
+              border: '2px solid #3b82f6',
+            }}
+          >
+            <div
+              style={{
+                fontSize: '16px',
+                fontWeight: 'bold',
+                color: '#1e3a8a',
+                marginBottom: '12px',
+                textAlign: 'center',
+              }}
+            >
+              🤝 TEAM CONTRIBUTIONS
+            </div>
+            <div
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                gap: '8px',
+              }}
+            >
+              {(() => {
+                // Group players by userId
+                const userTeams = new Map<
+                  string,
+                  { userId: string; players: any[]; score: { correct: number; incorrect: 0 } }
+                >()
+
+                console.log('🤝 [ResultsPhase] Building team contributions:', {
+                  activePlayers: state.activePlayers,
+                  playerMetadata: state.playerMetadata,
+                  playerScores: state.playerScores,
+                })
+
+                for (const playerId of state.activePlayers) {
+                  const metadata = state.playerMetadata?.[playerId]
+                  const userId = metadata?.userId
+                  console.log('🤝 [ResultsPhase] Processing player for contributions:', {
+                    playerId,
+                    metadata,
+                    userId,
+                  })
+                  if (!userId) continue
+
+                  if (!userTeams.has(userId)) {
+                    userTeams.set(userId, {
+                      userId,
+                      players: [],
+                      score: state.playerScores?.[userId] || { correct: 0, incorrect: 0 },
+                    })
+                  }
+                  userTeams.get(userId)!.players.push(metadata)
+                }
+
+                console.log('🤝 [ResultsPhase] UserTeams created for contributions:', {
+                  count: userTeams.size,
+                  teams: Array.from(userTeams.entries()),
+                })
+
+                // Sort teams by correct answers
+                return Array.from(userTeams.values())
+                  .sort((a, b) => b.score.correct - a.score.correct)
+                  .map((team, index) => (
+                    <div
+                      key={team.userId}
+                      style={{
+                        padding: '12px 14px',
+                        background: 'white',
+                        borderRadius: '8px',
+                        border: '1px solid #e5e7eb',
+                      }}
+                    >
+                      {/* Team header with stats */}
+                      <div
+                        style={{
+                          display: 'flex',
+                          alignItems: 'center',
+                          justifyContent: 'space-between',
+                          marginBottom: '8px',
+                        }}
+                      >
+                        <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+                          <span style={{ fontSize: '16px', fontWeight: '600', color: '#6b7280' }}>
+                            Team {index + 1}
+                          </span>
+                        </div>
+                        <div
+                          style={{
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: '10px',
+                            fontSize: '14px',
+                          }}
+                        >
+                          <span style={{ color: '#10b981', fontWeight: 'bold' }}>
+                            ✓ {team.score.correct}
+                          </span>
+                          <span style={{ color: '#ef4444', fontWeight: 'bold' }}>
+                            ✗ {team.score.incorrect}
+                          </span>
+                        </div>
+                      </div>
+                      {/* Players list */}
+                      <div
+                        style={{
+                          display: 'flex',
+                          flexDirection: 'column',
+                          gap: '4px',
+                          paddingLeft: '8px',
+                        }}
+                      >
+                        {team.players.map((player, i) => (
+                          <div
+                            key={i}
+                            style={{
+                              display: 'flex',
+                              alignItems: 'center',
+                              gap: '6px',
+                              fontSize: '13px',
+                            }}
+                          >
+                            <span style={{ fontSize: '18px' }}>{player?.emoji || '🎮'}</span>
+                            <span
+                              style={{
+                                color: '#1f2937',
+                                fontWeight: '500',
+                              }}
+                            >
+                              {player?.name || `Player ${i + 1}`}
+                            </span>
+                          </div>
+                        ))}
+                      </div>
+                    </div>
+                  ))
+              })()}
+            </div>
+          </div>
+        )}
+
+      {/* Results card grid - reuse CardGrid but with all cards revealed and status indicators */}
+      <div style={{ marginTop: '12px', flex: 1, overflow: 'auto' }}>
+        <ResultsCardGrid state={state} />
+      </div>
+
+      <div
+        style={{
+          display: 'flex',
+          justifyContent: 'center',
+          gap: '8px',
+          marginTop: '16px',
+          flexWrap: 'wrap',
+        }}
+      >
+        <button
+          style={{
+            padding: '10px 20px',
+            border: 'none',
+            borderRadius: '6px',
+            fontSize: '14px',
+            fontWeight: 'bold',
+            cursor: 'pointer',
+            transition: 'all 0.2s ease',
+            background: '#10b981',
+            color: 'white',
+            minWidth: '120px',
+          }}
+          onClick={() => {
+            resetGame?.()
+            const quizCards = generateQuizCards(
+              state.selectedCount,
+              state.selectedDifficulty,
+              appConfig
+            )
+            startQuiz?.(quizCards)
+          }}
+        >
+          Try Again
+        </button>
+        <button
+          style={{
+            padding: '10px 20px',
+            border: 'none',
+            borderRadius: '6px',
+            fontSize: '14px',
+            fontWeight: 'bold',
+            cursor: 'pointer',
+            transition: 'all 0.2s ease',
+            background: '#6b7280',
+            color: 'white',
+            minWidth: '120px',
+          }}
+          onClick={() => resetGame?.()}
+        >
+          Back to Cards
+        </button>
+      </div>
+    </div>
+  )
+}

apps/web/src/app/arcade/memory-quiz/components/SetupPhase.tsx

@@ -0,0 +1,335 @@
+import { AbacusReact, useAbacusConfig } from '@soroban/abacus-react'
+import { useMemoryQuiz } from '../context/MemoryQuizContext'
+import { DIFFICULTY_LEVELS, type DifficultyLevel, type QuizCard } from '../types'
+
+// Generate quiz cards with difficulty-based number ranges
+const generateQuizCards = (
+  count: number,
+  difficulty: DifficultyLevel,
+  appConfig: any
+): QuizCard[] => {
+  const { min, max } = DIFFICULTY_LEVELS[difficulty].range
+
+  // Generate unique numbers - no duplicates allowed
+  const numbers: number[] = []
+  const maxAttempts = (max - min + 1) * 10 // Prevent infinite loops
+  let attempts = 0
+
+  while (numbers.length < count && attempts < maxAttempts) {
+    const newNumber = Math.floor(Math.random() * (max - min + 1)) + min
+    if (!numbers.includes(newNumber)) {
+      numbers.push(newNumber)
+    }
+    attempts++
+  }
+
+  // If we couldn't generate enough unique numbers, fill with sequential numbers
+  if (numbers.length < count) {
+    for (let i = min; i <= max && numbers.length < count; i++) {
+      if (!numbers.includes(i)) {
+        numbers.push(i)
+      }
+    }
+  }
+
+  return numbers.map((number) => ({
+    number,
+    svgComponent: (
+      <AbacusReact
+        value={number}
+        columns="auto"
+        beadShape={appConfig.beadShape}
+        colorScheme={appConfig.colorScheme}
+        hideInactiveBeads={appConfig.hideInactiveBeads}
+        scaleFactor={1.0}
+        interactive={false}
+        showNumbers={false}
+        animated={false}
+        soundEnabled={appConfig.soundEnabled}
+        soundVolume={appConfig.soundVolume}
+      />
+    ),
+    element: null,
+  }))
+}
+
+export function SetupPhase() {
+  const { state, setConfig, startQuiz } = useMemoryQuiz()
+  const appConfig = useAbacusConfig()
+
+  const handleCountSelect = (count: number) => {
+    setConfig?.('selectedCount', count)
+  }
+
+  const handleTimeChange = (time: number) => {
+    setConfig?.('displayTime', time)
+  }
+
+  const handleDifficultySelect = (difficulty: DifficultyLevel) => {
+    setConfig?.('selectedDifficulty', difficulty)
+  }
+
+  const handlePlayModeSelect = (playMode: 'cooperative' | 'competitive') => {
+    setConfig?.('playMode', playMode)
+  }
+
+  const handleStartQuiz = () => {
+    const quizCards = generateQuizCards(
+      state.selectedCount ?? 5,
+      state.selectedDifficulty ?? 'easy',
+      appConfig
+    )
+    startQuiz?.(quizCards)
+  }
+
+  return (
+    <div
+      style={{
+        textAlign: 'center',
+        padding: '12px',
+        maxWidth: '100%',
+        margin: '0 auto',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        overflow: 'hidden',
+      }}
+    >
+      <div
+        style={{
+          maxWidth: '100%',
+          margin: '0 auto',
+          flex: 1,
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '16px',
+          overflow: 'auto',
+        }}
+      >
+        <div style={{ margin: '12px 0' }}>
+          <label
+            style={{
+              display: 'block',
+              fontWeight: 'bold',
+              marginBottom: '8px',
+              color: '#6b7280',
+              fontSize: '14px',
+            }}
+          >
+            Difficulty Level:
+          </label>
+          <div
+            style={{
+              display: 'grid',
+              gridTemplateColumns: 'repeat(2, 1fr)',
+              gap: '8px',
+              justifyContent: 'center',
+            }}
+          >
+            {Object.entries(DIFFICULTY_LEVELS).map(([key, level]) => (
+              <button
+                key={key}
+                type="button"
+                style={{
+                  background: state.selectedDifficulty === key ? '#3b82f6' : 'white',
+                  color: state.selectedDifficulty === key ? 'white' : '#1f2937',
+                  border: '2px solid',
+                  borderColor: state.selectedDifficulty === key ? '#3b82f6' : '#d1d5db',
+                  borderRadius: '8px',
+                  padding: '8px 12px',
+                  cursor: 'pointer',
+                  textAlign: 'center',
+                  display: 'flex',
+                  flexDirection: 'column',
+                  gap: '2px',
+                  fontSize: '12px',
+                }}
+                onClick={() => handleDifficultySelect(key as DifficultyLevel)}
+                title={level.description}
+              >
+                <div style={{ fontWeight: 'bold', fontSize: '13px' }}>{level.name}</div>
+                <div style={{ fontSize: '10px', opacity: 0.8 }}>{level.description}</div>
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <div style={{ margin: '12px 0' }}>
+          <label
+            style={{
+              display: 'block',
+              fontWeight: 'bold',
+              marginBottom: '8px',
+              color: '#6b7280',
+              fontSize: '14px',
+            }}
+          >
+            Play Mode:
+          </label>
+          <div
+            style={{
+              display: 'grid',
+              gridTemplateColumns: 'repeat(2, 1fr)',
+              gap: '8px',
+              justifyContent: 'center',
+            }}
+          >
+            <button
+              key="cooperative"
+              type="button"
+              style={{
+                background: state.playMode === 'cooperative' ? '#10b981' : 'white',
+                color: state.playMode === 'cooperative' ? 'white' : '#1f2937',
+                border: '2px solid',
+                borderColor: state.playMode === 'cooperative' ? '#10b981' : '#d1d5db',
+                borderRadius: '8px',
+                padding: '8px 12px',
+                cursor: 'pointer',
+                textAlign: 'center',
+                display: 'flex',
+                flexDirection: 'column',
+                gap: '2px',
+                fontSize: '12px',
+              }}
+              onClick={() => handlePlayModeSelect('cooperative')}
+              title="Work together as a team to find all numbers"
+            >
+              <div style={{ fontWeight: 'bold', fontSize: '13px' }}>🤝 Cooperative</div>
+              <div style={{ fontSize: '10px', opacity: 0.8 }}>Work together</div>
+            </button>
+            <button
+              key="competitive"
+              type="button"
+              style={{
+                background: state.playMode === 'competitive' ? '#ef4444' : 'white',
+                color: state.playMode === 'competitive' ? 'white' : '#1f2937',
+                border: '2px solid',
+                borderColor: state.playMode === 'competitive' ? '#ef4444' : '#d1d5db',
+                borderRadius: '8px',
+                padding: '8px 12px',
+                cursor: 'pointer',
+                textAlign: 'center',
+                display: 'flex',
+                flexDirection: 'column',
+                gap: '2px',
+                fontSize: '12px',
+              }}
+              onClick={() => handlePlayModeSelect('competitive')}
+              title="Compete for the highest score"
+            >
+              <div style={{ fontWeight: 'bold', fontSize: '13px' }}>🏆 Competitive</div>
+              <div style={{ fontSize: '10px', opacity: 0.8 }}>Battle for score</div>
+            </button>
+          </div>
+        </div>
+
+        <div style={{ margin: '12px 0' }}>
+          <label
+            style={{
+              display: 'block',
+              fontWeight: 'bold',
+              marginBottom: '8px',
+              color: '#6b7280',
+              fontSize: '14px',
+            }}
+          >
+            Cards to Quiz:
+          </label>
+          <div
+            style={{
+              display: 'flex',
+              gap: '6px',
+              justifyContent: 'center',
+              flexWrap: 'wrap',
+            }}
+          >
+            {[2, 5, 8, 12, 15].map((count) => (
+              <button
+                key={count}
+                type="button"
+                style={{
+                  background: state.selectedCount === count ? '#3b82f6' : 'white',
+                  color: state.selectedCount === count ? 'white' : '#1f2937',
+                  border: '2px solid',
+                  borderColor: state.selectedCount === count ? '#3b82f6' : '#d1d5db',
+                  borderRadius: '8px',
+                  padding: '8px 16px',
+                  cursor: 'pointer',
+                  fontSize: '14px',
+                  minWidth: '50px',
+                }}
+                onClick={() => handleCountSelect(count)}
+              >
+                {count}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <div style={{ margin: '12px 0' }}>
+          <label
+            style={{
+              display: 'block',
+              fontWeight: 'bold',
+              marginBottom: '8px',
+              color: '#6b7280',
+              fontSize: '14px',
+            }}
+          >
+            Display Time per Card:
+          </label>
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              gap: '10px',
+            }}
+          >
+            <input
+              type="range"
+              min="0.5"
+              max="10"
+              step="0.5"
+              value={state.displayTime ?? 2.0}
+              onChange={(e) => handleTimeChange(parseFloat(e.target.value))}
+              style={{
+                flex: 1,
+                maxWidth: '200px',
+              }}
+            />
+            <span
+              style={{
+                fontWeight: 'bold',
+                color: '#3b82f6',
+                minWidth: '40px',
+                fontSize: '14px',
+              }}
+            >
+              {(state.displayTime ?? 2.0).toFixed(1)}s
+            </span>
+          </div>
+        </div>
+
+        <button
+          style={{
+            background: '#10b981',
+            color: 'white',
+            border: 'none',
+            borderRadius: '8px',
+            padding: '12px 24px',
+            fontSize: '16px',
+            fontWeight: 'bold',
+            cursor: 'pointer',
+            marginTop: '16px',
+            width: '100%',
+            maxWidth: '200px',
+          }}
+          onClick={handleStartQuiz}
+        >
+          Start Quiz
+        </button>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,113 @@
+'use client'
+
+import type { ReactNode } from 'react'
+import { useCallback, useEffect, useReducer } from 'react'
+import { useRouter } from 'next/navigation'
+import { initialState, quizReducer } from '../reducer'
+import type { QuizCard } from '../types'
+import { MemoryQuizContext, type MemoryQuizContextValue } from './MemoryQuizContext'
+
+interface LocalMemoryQuizProviderProps {
+  children: ReactNode
+}
+
+/**
+ * LocalMemoryQuizProvider - Provides context for single-player local mode
+ *
+ * This provider wraps the memory quiz reducer and provides action creators
+ * to child components. It's used for standalone local play (non-room mode).
+ *
+ * Action creators wrap dispatch calls to maintain same interface as RoomProvider.
+ */
+export function LocalMemoryQuizProvider({ children }: LocalMemoryQuizProviderProps) {
+  const router = useRouter()
+  const [state, dispatch] = useReducer(quizReducer, initialState)
+
+  // Cleanup timeouts on unmount
+  useEffect(() => {
+    return () => {
+      if (state.prefixAcceptanceTimeout) {
+        clearTimeout(state.prefixAcceptanceTimeout)
+      }
+    }
+  }, [state.prefixAcceptanceTimeout])
+
+  // Computed values
+  const isGameActive = state.gamePhase === 'display' || state.gamePhase === 'input'
+
+  // Action creators - wrap dispatch calls to match RoomProvider interface
+  const startQuiz = useCallback((quizCards: QuizCard[]) => {
+    dispatch({ type: 'START_QUIZ', quizCards })
+  }, [])
+
+  const nextCard = useCallback(() => {
+    dispatch({ type: 'NEXT_CARD' })
+  }, [])
+
+  const showInputPhase = useCallback(() => {
+    dispatch({ type: 'SHOW_INPUT_PHASE' })
+  }, [])
+
+  const acceptNumber = useCallback((number: number) => {
+    dispatch({ type: 'ACCEPT_NUMBER', number })
+  }, [])
+
+  const rejectNumber = useCallback(() => {
+    dispatch({ type: 'REJECT_NUMBER' })
+  }, [])
+
+  const setInput = useCallback((input: string) => {
+    dispatch({ type: 'SET_INPUT', input })
+  }, [])
+
+  const showResults = useCallback(() => {
+    dispatch({ type: 'SHOW_RESULTS' })
+  }, [])
+
+  const resetGame = useCallback(() => {
+    dispatch({ type: 'RESET_QUIZ' })
+  }, [])
+
+  const setConfig = useCallback(
+    (field: 'selectedCount' | 'displayTime' | 'selectedDifficulty', value: any) => {
+      switch (field) {
+        case 'selectedCount':
+          dispatch({ type: 'SET_SELECTED_COUNT', count: value })
+          break
+        case 'displayTime':
+          dispatch({ type: 'SET_DISPLAY_TIME', time: value })
+          break
+        case 'selectedDifficulty':
+          dispatch({ type: 'SET_DIFFICULTY', difficulty: value })
+          break
+      }
+    },
+    []
+  )
+
+  const exitSession = useCallback(() => {
+    router.push('/games')
+  }, [router])
+
+  const contextValue: MemoryQuizContextValue = {
+    state,
+    dispatch: () => {
+      // No-op - local provider uses action creators instead
+      console.warn('dispatch() is not available in local mode, use action creators instead')
+    },
+    isGameActive,
+    resetGame,
+    exitSession,
+    // Expose action creators for components to use
+    startQuiz,
+    nextCard,
+    showInputPhase,
+    acceptNumber,
+    rejectNumber,
+    setInput,
+    showResults,
+    setConfig,
+  }
+
+  return <MemoryQuizContext.Provider value={contextValue}>{children}</MemoryQuizContext.Provider>
+}

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

@@ -0,0 +1,45 @@
+'use client'
+
+import { createContext, useContext } from 'react'
+import type { QuizAction, QuizCard, SorobanQuizState } from '../types'
+
+// Context value interface
+export interface MemoryQuizContextValue {
+  state: SorobanQuizState
+  dispatch: React.Dispatch<QuizAction>
+
+  // Computed values
+  isGameActive: boolean
+  isRoomCreator?: boolean // True if current user is room creator (controls timing in multiplayer)
+
+  // Action creators (to be implemented by providers)
+  // Local mode uses dispatch, room mode uses these action creators
+  startGame?: () => void
+  resetGame?: () => void
+  exitSession?: () => void
+
+  // Room mode action creators (optional for local mode)
+  startQuiz?: (quizCards: QuizCard[]) => void
+  nextCard?: () => void
+  showInputPhase?: () => void
+  acceptNumber?: (number: number) => void
+  rejectNumber?: () => void
+  setInput?: (input: string) => void
+  showResults?: () => void
+  setConfig?: (
+    field: 'selectedCount' | 'displayTime' | 'selectedDifficulty' | 'playMode',
+    value: any
+  ) => void
+}
+
+// Create context
+export const MemoryQuizContext = createContext<MemoryQuizContextValue | null>(null)
+
+// Hook to use the context
+export function useMemoryQuiz(): MemoryQuizContextValue {
+  const context = useContext(MemoryQuizContext)
+  if (!context) {
+    throw new Error('useMemoryQuiz must be used within a MemoryQuizProvider')
+  }
+  return context
+}

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

@@ -0,0 +1,537 @@
+'use client'
+
+import type { ReactNode } from 'react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useGameMode } from '@/contexts/GameModeContext'
+import { useArcadeSession } from '@/hooks/useArcadeSession'
+import { useRoomData, useUpdateGameConfig } from '@/hooks/useRoomData'
+import { useViewerId } from '@/hooks/useViewerId'
+import type { GameMove } from '@/lib/arcade/validation'
+import { TEAM_MOVE } from '@/lib/arcade/validation/types'
+import {
+  buildPlayerMetadata as buildPlayerMetadataUtil,
+  buildPlayerOwnershipFromRoomData,
+} from '@/lib/arcade/player-ownership.client'
+import { initialState } from '../reducer'
+import type { QuizCard, SorobanQuizState } from '../types'
+import { MemoryQuizContext, type MemoryQuizContextValue } from './MemoryQuizContext'
+
+/**
+ * Optimistic move application (client-side prediction)
+ * The server will validate and send back the authoritative state
+ */
+function applyMoveOptimistically(state: SorobanQuizState, move: GameMove): SorobanQuizState {
+  switch (move.type) {
+    case 'START_QUIZ': {
+      // Handle both client-generated moves (with quizCards) and server-generated moves (with numbers only)
+      // Server can't serialize React components, so it only sends numbers
+      const clientQuizCards = move.data.quizCards
+      const serverNumbers = move.data.numbers
+
+      let quizCards: QuizCard[]
+      let correctAnswers: number[]
+
+      if (clientQuizCards) {
+        // Client-side optimistic update: use the full quizCards with React components
+        quizCards = clientQuizCards
+        correctAnswers = clientQuizCards.map((card: QuizCard) => card.number)
+      } else if (serverNumbers) {
+        // Server update: create minimal quizCards from numbers (no React components needed for validation)
+        quizCards = serverNumbers.map((number: number) => ({
+          number,
+          svgComponent: null,
+          element: null,
+        }))
+        correctAnswers = serverNumbers
+      } else {
+        // Fallback: preserve existing state
+        quizCards = state.quizCards
+        correctAnswers = state.correctAnswers
+      }
+
+      const cardCount = quizCards.length
+
+      // Initialize player scores for all active players (by userId, not playerId)
+      const activePlayers = move.data.activePlayers || []
+      const playerMetadata = move.data.playerMetadata || {}
+
+      // Extract unique userIds from playerMetadata
+      const uniqueUserIds = new Set<string>()
+      for (const playerId of activePlayers) {
+        const metadata = playerMetadata[playerId]
+        if (metadata?.userId) {
+          uniqueUserIds.add(metadata.userId)
+        }
+      }
+
+      // Initialize scores for each userId
+      const playerScores = Array.from(uniqueUserIds).reduce((acc: any, userId: string) => {
+        acc[userId] = { correct: 0, incorrect: 0 }
+        return acc
+      }, {})
+
+      return {
+        ...state,
+        quizCards,
+        correctAnswers,
+        currentCardIndex: 0,
+        foundNumbers: [],
+        guessesRemaining: cardCount + Math.floor(cardCount / 2),
+        gamePhase: 'display',
+        incorrectGuesses: 0,
+        currentInput: '',
+        wrongGuessAnimations: [],
+        prefixAcceptanceTimeout: null,
+        // Multiplayer state
+        activePlayers,
+        playerMetadata,
+        playerScores,
+      }
+    }
+
+    case 'NEXT_CARD':
+      return {
+        ...state,
+        currentCardIndex: state.currentCardIndex + 1,
+      }
+
+    case 'SHOW_INPUT_PHASE':
+      return {
+        ...state,
+        gamePhase: 'input',
+      }
+
+    case 'ACCEPT_NUMBER': {
+      // Track scores by userId (not playerId) since we can't determine which player typed
+      // Defensive check: ensure state properties exist
+      const playerScores = state.playerScores || {}
+      const foundNumbers = state.foundNumbers || []
+      const numberFoundBy = state.numberFoundBy || {}
+
+      const newPlayerScores = { ...playerScores }
+      const newNumberFoundBy = { ...numberFoundBy }
+
+      if (move.userId) {
+        const currentScore = newPlayerScores[move.userId] || { correct: 0, incorrect: 0 }
+        newPlayerScores[move.userId] = {
+          ...currentScore,
+          correct: currentScore.correct + 1,
+        }
+        // Track who found this number
+        newNumberFoundBy[move.data.number] = move.userId
+      }
+      return {
+        ...state,
+        foundNumbers: [...foundNumbers, move.data.number],
+        playerScores: newPlayerScores,
+        numberFoundBy: newNumberFoundBy,
+      }
+    }
+
+    case 'REJECT_NUMBER': {
+      // Track scores by userId (not playerId) since we can't determine which player typed
+      // Defensive check: ensure state properties exist
+      const playerScores = state.playerScores || {}
+
+      const newPlayerScores = { ...playerScores }
+      if (move.userId) {
+        const currentScore = newPlayerScores[move.userId] || { correct: 0, incorrect: 0 }
+        newPlayerScores[move.userId] = {
+          ...currentScore,
+          incorrect: currentScore.incorrect + 1,
+        }
+      }
+      return {
+        ...state,
+        guessesRemaining: state.guessesRemaining - 1,
+        incorrectGuesses: state.incorrectGuesses + 1,
+        playerScores: newPlayerScores,
+      }
+    }
+
+    case 'SHOW_RESULTS':
+      return {
+        ...state,
+        gamePhase: 'results',
+      }
+
+    case 'RESET_QUIZ':
+      return {
+        ...state,
+        gamePhase: 'setup',
+        quizCards: [],
+        correctAnswers: [],
+        currentCardIndex: 0,
+        foundNumbers: [],
+        guessesRemaining: 0,
+        currentInput: '',
+        incorrectGuesses: 0,
+        wrongGuessAnimations: [],
+        prefixAcceptanceTimeout: null,
+        finishButtonsBound: false,
+      }
+
+    case 'SET_CONFIG': {
+      const { field, value } = move.data as {
+        field: 'selectedCount' | 'displayTime' | 'selectedDifficulty' | 'playMode'
+        value: any
+      }
+      return {
+        ...state,
+        [field]: value,
+      }
+    }
+
+    default:
+      return state
+  }
+}
+
+/**
+ * RoomMemoryQuizProvider - Provides context for room-based multiplayer mode
+ *
+ * This provider uses useArcadeSession for network-synchronized gameplay.
+ * All state changes are sent as moves and validated on the server.
+ */
+export function RoomMemoryQuizProvider({ children }: { children: ReactNode }) {
+  const { data: viewerId } = useViewerId()
+  const { roomData } = useRoomData()
+  const { activePlayers: activePlayerIds, players } = useGameMode()
+  const { mutate: updateGameConfig } = useUpdateGameConfig()
+
+  // Get active player IDs as array
+  const activePlayers = Array.from(activePlayerIds)
+
+  // LOCAL-ONLY state for current input (not synced over network)
+  // This prevents sending a network request for every keystroke
+  const [localCurrentInput, setLocalCurrentInput] = useState('')
+
+  // 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
+
+    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
+    }
+
+    return {
+      ...initialState,
+      // Restore settings from saved config
+      selectedCount: savedConfig.selectedCount ?? initialState.selectedCount,
+      displayTime: savedConfig.displayTime ?? initialState.displayTime,
+      selectedDifficulty: savedConfig.selectedDifficulty ?? initialState.selectedDifficulty,
+      playMode: savedConfig.playMode ?? initialState.playMode,
+    }
+  }, [roomData?.gameConfig])
+
+  // Arcade session integration WITH room sync
+  const {
+    state,
+    sendMove,
+    connected: _connected,
+    exitSession,
+  } = useArcadeSession<SorobanQuizState>({
+    userId: viewerId || '',
+    roomId: roomData?.id, // CRITICAL: Pass roomId for network sync across room members
+    initialState: mergedInitialState,
+    applyMove: applyMoveOptimistically,
+  })
+
+  // Clear local input when game phase changes or when game resets
+  useEffect(() => {
+    if (state.gamePhase !== 'input') {
+      setLocalCurrentInput('')
+    }
+  }, [state.gamePhase])
+
+  // Cleanup timeouts on unmount
+  useEffect(() => {
+    return () => {
+      if (state.prefixAcceptanceTimeout) {
+        clearTimeout(state.prefixAcceptanceTimeout)
+      }
+    }
+  }, [state.prefixAcceptanceTimeout])
+
+  // Detect state corruption/mismatch (e.g., game type mismatch between sessions)
+  const hasStateCorruption =
+    !state.quizCards ||
+    !state.correctAnswers ||
+    !state.foundNumbers ||
+    !Array.isArray(state.quizCards)
+
+  // Computed values
+  const isGameActive = state.gamePhase === 'display' || state.gamePhase === 'input'
+
+  // Build player metadata from room data and player map
+  const buildPlayerMetadata = useCallback(() => {
+    const playerOwnership = buildPlayerOwnershipFromRoomData(roomData)
+    const metadata = buildPlayerMetadataUtil(activePlayers, playerOwnership, players, viewerId)
+    return metadata
+  }, [activePlayers, players, roomData, viewerId])
+
+  // Action creators - send moves to arcade session
+  const startQuiz = useCallback(
+    (quizCards: QuizCard[]) => {
+      // Extract only serializable data (numbers) for server
+      // React components can't be sent over Socket.IO
+      const numbers = quizCards.map((card) => card.number)
+
+      // Build player metadata for multiplayer
+      const playerMetadata = buildPlayerMetadata()
+
+      sendMove({
+        type: 'START_QUIZ',
+        playerId: TEAM_MOVE, // Team move - all players act together
+        userId: viewerId || '', // User who initiated
+        data: {
+          numbers, // Send to server
+          quizCards, // Keep for optimistic local update
+          activePlayers, // Send active players list
+          playerMetadata, // Send player display info
+        },
+      })
+    },
+    [viewerId, sendMove, activePlayers, buildPlayerMetadata]
+  )
+
+  const nextCard = useCallback(() => {
+    sendMove({
+      type: 'NEXT_CARD',
+      playerId: TEAM_MOVE,
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [viewerId, sendMove])
+
+  const showInputPhase = useCallback(() => {
+    sendMove({
+      type: 'SHOW_INPUT_PHASE',
+      playerId: TEAM_MOVE,
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [viewerId, sendMove])
+
+  const acceptNumber = useCallback(
+    (number: number) => {
+      // Clear local input immediately
+      setLocalCurrentInput('')
+
+      sendMove({
+        type: 'ACCEPT_NUMBER',
+        playerId: TEAM_MOVE, // Team move - can't identify specific player
+        userId: viewerId || '', // User who guessed correctly
+        data: { number },
+      })
+    },
+    [viewerId, sendMove]
+  )
+
+  const rejectNumber = useCallback(() => {
+    // Clear local input immediately
+    setLocalCurrentInput('')
+
+    sendMove({
+      type: 'REJECT_NUMBER',
+      playerId: TEAM_MOVE, // Team move - can't identify specific player
+      userId: viewerId || '', // User who guessed incorrectly
+      data: {},
+    })
+  }, [viewerId, sendMove])
+
+  const setInput = useCallback((input: string) => {
+    // LOCAL ONLY - no network sync!
+    // This makes typing instant with zero network lag
+    setLocalCurrentInput(input)
+  }, [])
+
+  const showResults = useCallback(() => {
+    sendMove({
+      type: 'SHOW_RESULTS',
+      playerId: TEAM_MOVE,
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [viewerId, sendMove])
+
+  const resetGame = useCallback(() => {
+    sendMove({
+      type: 'RESET_QUIZ',
+      playerId: TEAM_MOVE,
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [viewerId, sendMove])
+
+  const setConfig = useCallback(
+    (field: 'selectedCount' | 'displayTime' | 'selectedDifficulty' | 'playMode', value: any) => {
+      console.log(`[RoomMemoryQuizProvider] setConfig called: ${field} = ${value}`)
+
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId: TEAM_MOVE,
+        userId: viewerId || '',
+        data: { field, value },
+      })
+
+      // Save setting to room's gameConfig for persistence
+      // Settings are scoped by game name to preserve settings when switching games
+      if (roomData?.id) {
+        const currentGameConfig = (roomData.gameConfig as Record<string, any>) || {}
+        const currentMemoryQuizConfig =
+          (currentGameConfig['memory-quiz'] as Record<string, any>) || {}
+
+        updateGameConfig({
+          roomId: roomData.id,
+          gameConfig: {
+            ...currentGameConfig,
+            'memory-quiz': {
+              ...currentMemoryQuizConfig,
+              [field]: value,
+            },
+          },
+        })
+      }
+    },
+    [viewerId, sendMove, roomData?.id, roomData?.gameConfig, updateGameConfig]
+  )
+
+  // Merge network state with local input state
+  const mergedState = {
+    ...state,
+    currentInput: localCurrentInput, // Override network state with local input
+  }
+
+  // If state is corrupted, show error message instead of crashing
+  if (hasStateCorruption) {
+    return (
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: '40px',
+          textAlign: 'center',
+          minHeight: '400px',
+        }}
+      >
+        <div
+          style={{
+            fontSize: '48px',
+            marginBottom: '20px',
+          }}
+        >
+          ⚠️
+        </div>
+        <h2
+          style={{
+            fontSize: '24px',
+            fontWeight: 'bold',
+            marginBottom: '12px',
+            color: '#dc2626',
+          }}
+        >
+          Game State Mismatch
+        </h2>
+        <p
+          style={{
+            fontSize: '16px',
+            color: '#6b7280',
+            marginBottom: '24px',
+            maxWidth: '500px',
+          }}
+        >
+          There's a mismatch between game types in this room. This usually happens when room members
+          are playing different games.
+        </p>
+        <div
+          style={{
+            background: '#f9fafb',
+            border: '1px solid #e5e7eb',
+            borderRadius: '8px',
+            padding: '16px',
+            marginBottom: '24px',
+            maxWidth: '500px',
+          }}
+        >
+          <p
+            style={{
+              fontSize: '14px',
+              fontWeight: '600',
+              marginBottom: '8px',
+            }}
+          >
+            To fix this:
+          </p>
+          <ol
+            style={{
+              fontSize: '14px',
+              textAlign: 'left',
+              paddingLeft: '20px',
+              lineHeight: '1.6',
+            }}
+          >
+            <li>Make sure all room members are on the same game page</li>
+            <li>Try refreshing the page</li>
+            <li>If the issue persists, leave and rejoin the room</li>
+          </ol>
+        </div>
+        <button
+          onClick={() => window.location.reload()}
+          style={{
+            padding: '10px 20px',
+            background: '#3b82f6',
+            color: 'white',
+            border: 'none',
+            borderRadius: '6px',
+            fontSize: '14px',
+            fontWeight: '600',
+            cursor: 'pointer',
+          }}
+        >
+          Refresh Page
+        </button>
+      </div>
+    )
+  }
+
+  // Determine if current user is the room creator (controls card timing)
+  const isRoomCreator =
+    roomData?.members.find((member) => member.userId === viewerId)?.isCreator || false
+
+  const contextValue: MemoryQuizContextValue = {
+    state: mergedState,
+    dispatch: () => {
+      // No-op - replaced with action creators
+      console.warn('dispatch() is deprecated in room mode, use action creators instead')
+    },
+    isGameActive,
+    resetGame,
+    exitSession,
+    isRoomCreator, // Pass room creator flag to components
+    // Expose action creators for components to use
+    startQuiz,
+    nextCard,
+    showInputPhase,
+    acceptNumber,
+    rejectNumber,
+    setInput,
+    showResults,
+    setConfig,
+  }
+
+  return <MemoryQuizContext.Provider value={contextValue}>{children}</MemoryQuizContext.Provider>
+}
+
+// Export the hook for this provider
+export { useMemoryQuiz } from './MemoryQuizContext'

apps/web/src/app/arcade/memory-quiz/reducer.ts

@@ -0,0 +1,138 @@
+import type { QuizAction, SorobanQuizState } from './types'
+
+export const initialState: SorobanQuizState = {
+  cards: [],
+  quizCards: [],
+  correctAnswers: [],
+  currentCardIndex: 0,
+  displayTime: 2.0,
+  selectedCount: 5,
+  selectedDifficulty: 'easy', // Default to easy level
+  foundNumbers: [],
+  guessesRemaining: 0,
+  currentInput: '',
+  incorrectGuesses: 0,
+  // Multiplayer state
+  activePlayers: [],
+  playerMetadata: {},
+  playerScores: {},
+  playMode: 'cooperative', // Default to cooperative
+  numberFoundBy: {},
+  // UI state
+  gamePhase: 'setup',
+  prefixAcceptanceTimeout: null,
+  finishButtonsBound: false,
+  wrongGuessAnimations: [],
+  // Keyboard state (persistent across re-renders)
+  hasPhysicalKeyboard: null,
+  testingMode: false,
+  showOnScreenKeyboard: false,
+}
+
+export function quizReducer(state: SorobanQuizState, action: QuizAction): SorobanQuizState {
+  switch (action.type) {
+    case 'SET_CARDS':
+      return { ...state, cards: action.cards }
+    case 'SET_DISPLAY_TIME':
+      return { ...state, displayTime: action.time }
+    case 'SET_SELECTED_COUNT':
+      return { ...state, selectedCount: action.count }
+    case 'SET_DIFFICULTY':
+      return { ...state, selectedDifficulty: action.difficulty }
+    case 'SET_PLAY_MODE':
+      return { ...state, playMode: action.playMode }
+    case 'START_QUIZ':
+      return {
+        ...state,
+        quizCards: action.quizCards,
+        correctAnswers: action.quizCards.map((card) => card.number),
+        currentCardIndex: 0,
+        foundNumbers: [],
+        guessesRemaining: action.quizCards.length + Math.floor(action.quizCards.length / 2),
+        gamePhase: 'display',
+      }
+    case 'NEXT_CARD':
+      return { ...state, currentCardIndex: state.currentCardIndex + 1 }
+    case 'SHOW_INPUT_PHASE':
+      return { ...state, gamePhase: 'input' }
+    case 'ACCEPT_NUMBER': {
+      // In competitive mode, track which player guessed correctly
+      const newPlayerScores = { ...state.playerScores }
+      if (state.playMode === 'competitive' && action.playerId) {
+        const currentScore = newPlayerScores[action.playerId] || { correct: 0, incorrect: 0 }
+        newPlayerScores[action.playerId] = {
+          ...currentScore,
+          correct: currentScore.correct + 1,
+        }
+      }
+      return {
+        ...state,
+        foundNumbers: [...state.foundNumbers, action.number],
+        currentInput: '',
+        playerScores: newPlayerScores,
+      }
+    }
+    case 'REJECT_NUMBER': {
+      // In competitive mode, track which player guessed incorrectly
+      const newPlayerScores = { ...state.playerScores }
+      if (state.playMode === 'competitive' && action.playerId) {
+        const currentScore = newPlayerScores[action.playerId] || { correct: 0, incorrect: 0 }
+        newPlayerScores[action.playerId] = {
+          ...currentScore,
+          incorrect: currentScore.incorrect + 1,
+        }
+      }
+      return {
+        ...state,
+        guessesRemaining: state.guessesRemaining - 1,
+        incorrectGuesses: state.incorrectGuesses + 1,
+        currentInput: '',
+        playerScores: newPlayerScores,
+      }
+    }
+    case 'SET_INPUT':
+      return { ...state, currentInput: action.input }
+    case 'SET_PREFIX_TIMEOUT':
+      return { ...state, prefixAcceptanceTimeout: action.timeout }
+    case 'ADD_WRONG_GUESS_ANIMATION':
+      return {
+        ...state,
+        wrongGuessAnimations: [
+          ...state.wrongGuessAnimations,
+          {
+            number: action.number,
+            id: `wrong-${action.number}-${Date.now()}`,
+            timestamp: Date.now(),
+          },
+        ],
+      }
+    case 'CLEAR_WRONG_GUESS_ANIMATIONS':
+      return {
+        ...state,
+        wrongGuessAnimations: [],
+      }
+    case 'SHOW_RESULTS':
+      return { ...state, gamePhase: 'results' }
+    case 'RESET_QUIZ':
+      return {
+        ...initialState,
+        cards: state.cards, // Preserve generated cards
+        displayTime: state.displayTime,
+        selectedCount: state.selectedCount,
+        selectedDifficulty: state.selectedDifficulty,
+        playMode: state.playMode, // Preserve play mode
+        // Preserve keyboard state across resets
+        hasPhysicalKeyboard: state.hasPhysicalKeyboard,
+        testingMode: state.testingMode,
+        showOnScreenKeyboard: state.showOnScreenKeyboard,
+      }
+    case 'SET_PHYSICAL_KEYBOARD':
+      return { ...state, hasPhysicalKeyboard: action.hasKeyboard }
+    case 'SET_TESTING_MODE':
+      return { ...state, testingMode: action.enabled }
+    case 'TOGGLE_ONSCREEN_KEYBOARD':
+      return { ...state, showOnScreenKeyboard: !state.showOnScreenKeyboard }
+    default:
+      return state
+  }
+}

apps/web/src/app/arcade/memory-quiz/types.ts

@@ -0,0 +1,105 @@
+import type { PlayerMetadata } from '@/lib/arcade/player-ownership.client'
+
+export interface QuizCard {
+  number: number
+  svgComponent: JSX.Element | null
+  element: HTMLElement | null
+}
+
+export interface PlayerScore {
+  correct: number
+  incorrect: number
+}
+
+export interface SorobanQuizState {
+  // Core game data
+  cards: QuizCard[]
+  quizCards: QuizCard[]
+  correctAnswers: number[]
+
+  // Game progression
+  currentCardIndex: number
+  displayTime: number
+  selectedCount: number
+  selectedDifficulty: DifficultyLevel
+
+  // Input system state
+  foundNumbers: number[]
+  guessesRemaining: number
+  currentInput: string
+  incorrectGuesses: number
+
+  // Multiplayer state
+  activePlayers: string[]
+  playerMetadata: Record<string, PlayerMetadata>
+  playerScores: Record<string, PlayerScore>
+  playMode: 'cooperative' | 'competitive'
+  numberFoundBy: Record<number, string> // Maps number to userId who found it
+
+  // UI state
+  gamePhase: 'setup' | 'display' | 'input' | 'results'
+  prefixAcceptanceTimeout: NodeJS.Timeout | null
+  finishButtonsBound: boolean
+  wrongGuessAnimations: Array<{
+    number: number
+    id: string
+    timestamp: number
+  }>
+
+  // Keyboard state (moved from InputPhase to persist across re-renders)
+  hasPhysicalKeyboard: boolean | null
+  testingMode: boolean
+  showOnScreenKeyboard: boolean
+}
+
+export type QuizAction =
+  | { type: 'SET_CARDS'; cards: QuizCard[] }
+  | { type: 'SET_DISPLAY_TIME'; time: number }
+  | { type: 'SET_SELECTED_COUNT'; count: number }
+  | { type: 'SET_DIFFICULTY'; difficulty: DifficultyLevel }
+  | { type: 'SET_PLAY_MODE'; playMode: 'cooperative' | 'competitive' }
+  | { type: 'START_QUIZ'; quizCards: QuizCard[] }
+  | { type: 'NEXT_CARD' }
+  | { type: 'SHOW_INPUT_PHASE' }
+  | { type: 'ACCEPT_NUMBER'; number: number; playerId?: string }
+  | { type: 'REJECT_NUMBER'; playerId?: string }
+  | { type: 'ADD_WRONG_GUESS_ANIMATION'; number: number }
+  | { type: 'CLEAR_WRONG_GUESS_ANIMATIONS' }
+  | { type: 'SET_INPUT'; input: string }
+  | { type: 'SET_PREFIX_TIMEOUT'; timeout: NodeJS.Timeout | null }
+  | { type: 'SHOW_RESULTS' }
+  | { type: 'RESET_QUIZ' }
+  | { type: 'SET_PHYSICAL_KEYBOARD'; hasKeyboard: boolean | null }
+  | { type: 'SET_TESTING_MODE'; enabled: boolean }
+  | { type: 'TOGGLE_ONSCREEN_KEYBOARD' }
+
+// Difficulty levels with progressive number ranges
+export const DIFFICULTY_LEVELS = {
+  beginner: {
+    name: 'Beginner',
+    range: { min: 1, max: 9 },
+    description: 'Single digits (1-9)',
+  },
+  easy: {
+    name: 'Easy',
+    range: { min: 10, max: 99 },
+    description: 'Two digits (10-99)',
+  },
+  medium: {
+    name: 'Medium',
+    range: { min: 100, max: 499 },
+    description: 'Three digits (100-499)',
+  },
+  hard: {
+    name: 'Hard',
+    range: { min: 500, max: 999 },
+    description: 'Large numbers (500-999)',
+  },
+  expert: {
+    name: 'Expert',
+    range: { min: 1, max: 999 },
+    description: 'Mixed range (1-999)',
+  },
+} as const
+
+export type DifficultyLevel = keyof typeof DIFFICULTY_LEVELS

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

@@ -78,7 +78,7 @@ function ArcadeContent() {
 
 function ArcadePageWithRedirect() {
   return (
-    <PageWithNav navTitle="Champion Arena" navEmoji="🏟️" emphasizeGameContext={true}>
+    <PageWithNav navTitle="Champion Arena" navEmoji="🏟️" emphasizePlayerSelection={true}>
       <ArcadeContent />
     </PageWithNav>
   )

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

@@ -1,92 +1,364 @@
 'use client'
 
-import { useRoomData } from '@/hooks/useRoomData'
-import { ModerationNotifications } from '@/components/nav/ModerationNotifications'
+import { useRouter } from 'next/navigation'
+import { useRoomData, useSetRoomGame } from '@/hooks/useRoomData'
 import { MemoryPairsGame } from '../matching/components/MemoryPairsGame'
 import { RoomMemoryPairsProvider } from '../matching/context/RoomMemoryPairsProvider'
+import { MemoryQuizGame } from '../memory-quiz/components/MemoryQuizGame'
+import { RoomMemoryQuizProvider } from '../memory-quiz/context/RoomMemoryQuizProvider'
+import { GAMES_CONFIG } from '@/components/GameSelector'
+import type { GameType } from '@/components/GameSelector'
+import { PageWithNav } from '@/components/PageWithNav'
+import { css } from '../../../../styled-system/css'
+import { getAllGames, getGame, hasGame } from '@/lib/arcade/game-registry'
+
+// Map GameType keys to internal game names
+const GAME_TYPE_TO_NAME: Record<GameType, string> = {
+  'battle-arena': 'matching',
+  'memory-quiz': 'memory-quiz',
+  'complement-race': 'complement-race',
+  'master-organizer': 'master-organizer',
+}
 
 /**
  * /arcade/room - Renders the game for the user's current room
  * Since users can only be in one room at a time, this is a simple singular route
  *
+ * Shows game selection when no game is set, then shows the game itself once selected.
+ * URL never changes - it's always /arcade/room regardless of selection, setup, or gameplay.
+ *
  * Note: We don't redirect to /arcade if no room exists to avoid navigation loops.
  * Instead, we show a friendly message with a link back to the Champion Arena.
+ *
+ * Note: ModerationNotifications is handled by PageWithNav inside each game component,
+ * so we don't need to render it here.
  */
 export default function RoomPage() {
-  const { roomData, isLoading, moderationEvent, clearModerationEvent } = useRoomData()
+  const router = useRouter()
+  const { roomData, isLoading } = useRoomData()
+  const { mutate: setRoomGame } = useSetRoomGame()
 
   // Show loading state
   if (isLoading) {
     return (
-      <>
-        <div
-          style={{
-            display: 'flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            height: '100vh',
-            fontSize: '18px',
-            color: '#666',
-          }}
-        >
-          Loading room...
-        </div>
-        <ModerationNotifications moderationEvent={moderationEvent} onClose={clearModerationEvent} />
-      </>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          height: '100vh',
+          fontSize: '18px',
+          color: '#666',
+        }}
+      >
+        Loading room...
+      </div>
     )
   }
 
   // Show error if no room (instead of redirecting)
   if (!roomData) {
     return (
-      <>
-        <div
+      <div
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          justifyContent: 'center',
+          height: '100vh',
+          fontSize: '18px',
+          color: '#666',
+          gap: '1rem',
+        }}
+      >
+        <div>No active room found</div>
+        <a
+          href="/arcade"
           style={{
+            color: '#3b82f6',
+            textDecoration: 'underline',
+          }}
+        >
+          Go to Champion Arena
+        </a>
+      </div>
+    )
+  }
+
+  // Show game selection if no game is set
+  if (!roomData.gameName) {
+    const handleGameSelect = (gameType: GameType) => {
+      console.log('[RoomPage] handleGameSelect called with gameType:', gameType)
+
+      // Check if it's a registry game first
+      if (hasGame(gameType)) {
+        const gameDef = getGame(gameType)
+        if (!gameDef?.manifest.available) {
+          console.log('[RoomPage] Registry game not available, blocking selection')
+          return
+        }
+
+        console.log('[RoomPage] Selecting registry game:', gameType)
+        setRoomGame({
+          roomId: roomData.id,
+          gameName: gameType, // Use the game name directly for registry games
+        })
+        return
+      }
+
+      // Legacy game handling
+      const gameConfig = GAMES_CONFIG[gameType as keyof typeof GAMES_CONFIG]
+      if (!gameConfig) {
+        console.log('[RoomPage] Unknown game type:', gameType)
+        return
+      }
+
+      console.log('[RoomPage] Game config:', {
+        name: gameConfig.name,
+        available: 'available' in gameConfig ? gameConfig.available : true,
+      })
+
+      if ('available' in gameConfig && gameConfig.available === false) {
+        console.log('[RoomPage] Game not available, blocking selection')
+        return // Don't allow selecting unavailable games
+      }
+
+      // Map GameType to internal game name
+      const internalGameName = GAME_TYPE_TO_NAME[gameType]
+      console.log('[RoomPage] Mapping:', {
+        gameType,
+        internalGameName,
+        mappingExists: !!internalGameName,
+      })
+
+      console.log('[RoomPage] Calling setRoomGame with:', {
+        roomId: roomData.id,
+        gameName: internalGameName,
+        preservingGameConfig: true,
+      })
+
+      // Don't pass gameConfig - we want to preserve existing settings for all games
+      setRoomGame({
+        roomId: roomData.id,
+        gameName: internalGameName,
+      })
+    }
+
+    return (
+      <PageWithNav
+        navTitle="Choose Game"
+        navEmoji="🎮"
+        emphasizePlayerSelection={true}
+        onExitSession={() => router.push('/arcade')}
+      >
+        <div
+          className={css({
+            minHeight: '100vh',
+            background: 'linear-gradient(135deg, #0f0f23 0%, #1a1a3a 50%, #2d1b69 100%)',
             display: 'flex',
             flexDirection: 'column',
             alignItems: 'center',
             justifyContent: 'center',
-            height: '100vh',
-            fontSize: '18px',
-            color: '#666',
-            gap: '1rem',
-          }}
+            padding: '4',
+          })}
         >
-          <div>No active room found</div>
-          <a
-            href="/arcade"
-            style={{
-              color: '#3b82f6',
-              textDecoration: 'underline',
-            }}
+          <h1
+            className={css({
+              fontSize: { base: '2xl', md: '3xl' },
+              fontWeight: 'bold',
+              color: 'white',
+              mb: '8',
+              textAlign: 'center',
+            })}
           >
-            Go to Champion Arena
-          </a>
+            Choose a Game
+          </h1>
+
+          <div
+            className={css({
+              display: 'grid',
+              gridTemplateColumns: { base: '1fr', md: 'repeat(2, 1fr)' },
+              gap: '4',
+              maxWidth: '800px',
+              width: '100%',
+            })}
+          >
+            {/* Legacy games */}
+            {Object.entries(GAMES_CONFIG).map(([gameType, config]) => {
+              const isAvailable = !('available' in config) || config.available !== false
+              return (
+                <button
+                  key={gameType}
+                  onClick={() => handleGameSelect(gameType as GameType)}
+                  disabled={!isAvailable}
+                  className={css({
+                    background: config.gradient,
+                    border: '2px solid',
+                    borderColor: config.borderColor || 'blue.200',
+                    borderRadius: '2xl',
+                    padding: '6',
+                    cursor: !isAvailable ? 'not-allowed' : 'pointer',
+                    opacity: !isAvailable ? 0.5 : 1,
+                    transition: 'all 0.3s ease',
+                    _hover: !isAvailable
+                      ? {}
+                      : {
+                          transform: 'translateY(-4px) scale(1.02)',
+                          boxShadow: '0 20px 40px rgba(59, 130, 246, 0.2)',
+                        },
+                  })}
+                >
+                  <div
+                    className={css({
+                      fontSize: '4xl',
+                      mb: '2',
+                    })}
+                  >
+                    {config.icon}
+                  </div>
+                  <h3
+                    className={css({
+                      fontSize: 'xl',
+                      fontWeight: 'bold',
+                      color: 'gray.900',
+                      mb: '2',
+                    })}
+                  >
+                    {config.name}
+                  </h3>
+                  <p
+                    className={css({
+                      fontSize: 'sm',
+                      color: 'gray.600',
+                    })}
+                  >
+                    {config.description}
+                  </p>
+                </button>
+              )
+            })}
+
+            {/* Registry games */}
+            {getAllGames().map((gameDef) => {
+              const isAvailable = gameDef.manifest.available
+              return (
+                <button
+                  key={gameDef.manifest.name}
+                  onClick={() => handleGameSelect(gameDef.manifest.name)}
+                  disabled={!isAvailable}
+                  className={css({
+                    background: gameDef.manifest.gradient,
+                    border: '2px solid',
+                    borderColor: gameDef.manifest.borderColor,
+                    borderRadius: '2xl',
+                    padding: '6',
+                    cursor: !isAvailable ? 'not-allowed' : 'pointer',
+                    opacity: !isAvailable ? 0.5 : 1,
+                    transition: 'all 0.3s ease',
+                    _hover: !isAvailable
+                      ? {}
+                      : {
+                          transform: 'translateY(-4px) scale(1.02)',
+                          boxShadow: '0 20px 40px rgba(59, 130, 246, 0.2)',
+                        },
+                  })}
+                >
+                  <div
+                    className={css({
+                      fontSize: '4xl',
+                      mb: '2',
+                    })}
+                  >
+                    {gameDef.manifest.icon}
+                  </div>
+                  <h3
+                    className={css({
+                      fontSize: 'xl',
+                      fontWeight: 'bold',
+                      color: 'gray.900',
+                      mb: '2',
+                    })}
+                  >
+                    {gameDef.manifest.displayName}
+                  </h3>
+                  <p
+                    className={css({
+                      fontSize: 'sm',
+                      color: 'gray.600',
+                    })}
+                  >
+                    {gameDef.manifest.description}
+                  </p>
+                </button>
+              )
+            })}
+          </div>
         </div>
-        <ModerationNotifications moderationEvent={moderationEvent} onClose={clearModerationEvent} />
-      </>
+      </PageWithNav>
     )
   }
 
-  // Render the appropriate game based on room's gameName
+  // Check if this is a registry game first
+  if (hasGame(roomData.gameName)) {
+    const gameDef = getGame(roomData.gameName)
+    if (!gameDef) {
+      return (
+        <PageWithNav
+          navTitle="Game Not Found"
+          navEmoji="⚠️"
+          emphasizePlayerSelection={true}
+          onExitSession={() => router.push('/arcade')}
+        >
+          <div
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              height: '100vh',
+              fontSize: '18px',
+              color: '#666',
+            }}
+          >
+            Game "{roomData.gameName}" not found in registry
+          </div>
+        </PageWithNav>
+      )
+    }
+
+    // Render registry game dynamically
+    const { Provider, GameComponent } = gameDef
+    return (
+      <Provider>
+        <GameComponent />
+      </Provider>
+    )
+  }
+
+  // Render legacy games based on room's gameName
   switch (roomData.gameName) {
     case 'matching':
       return (
-        <>
-          <RoomMemoryPairsProvider>
-            <MemoryPairsGame />
-          </RoomMemoryPairsProvider>
-          <ModerationNotifications
-            moderationEvent={moderationEvent}
-            onClose={clearModerationEvent}
-          />
-        </>
+        <RoomMemoryPairsProvider>
+          <MemoryPairsGame />
+        </RoomMemoryPairsProvider>
       )
 
-    // TODO: Add other games (complement-race, memory-quiz, etc.)
+    case 'memory-quiz':
+      return (
+        <RoomMemoryQuizProvider>
+          <MemoryQuizGame />
+        </RoomMemoryQuizProvider>
+      )
+
+    // TODO: Add other games (complement-race, etc.)
     default:
       return (
-        <>
+        <PageWithNav
+          navTitle="Game Not Available"
+          navEmoji="⚠️"
+          emphasizePlayerSelection={true}
+          onExitSession={() => router.push('/arcade')}
+        >
           <div
             style={{
               display: 'flex',
@@ -99,11 +371,7 @@ export default function RoomPage() {
           >
             Game "{roomData.gameName}" not yet supported
           </div>
-          <ModerationNotifications
-            moderationEvent={moderationEvent}
-            onClose={clearModerationEvent}
-          />
-        </>
+        </PageWithNav>
       )
   }
 }

apps/web/src/app/games/matching/components/MemoryPairsGame.tsx

@@ -32,7 +32,7 @@ export function MemoryPairsGame() {
       navTitle={navTitle}
       navEmoji={navEmoji}
       gameName="matching"
-      emphasizeGameContext={state.gamePhase === 'setup'}
+      emphasizePlayerSelection={state.gamePhase === 'setup'}
       currentPlayerId={state.currentPlayer}
       playerScores={state.scores}
       playerStreaks={state.consecutiveMatches}

apps/web/src/app/games/page.tsx

@@ -21,7 +21,7 @@ function GamesPageContent() {
   const _handleGameClick = (gameType: string) => {
     // Navigate directly to games using the centralized game mode with Next.js router
     console.log('🔄 GamesPage: Navigating with Next.js router (no page reload)')
-    if (gameType === 'memory-lightning') {
+    if (gameType === 'memory-quiz') {
       router.push('/games/memory-quiz')
     } else if (gameType === 'battle-arena') {
       router.push('/games/matching')

apps/web/src/app/join/[code]/page.tsx

@@ -1,7 +1,8 @@
 'use client'
 
-import { useCallback, useEffect, useState } from 'react'
 import { useRouter } from 'next/navigation'
+import { useCallback, useEffect, useState } from 'react'
+import { io } from 'socket.io-client'
 import { useGetRoomByCode, useJoinRoom, useRoomData } from '@/hooks/useRoomData'
 import { getRoomDisplayWithEmoji } from '@/utils/room-display'
 
@@ -211,6 +212,8 @@ export default function JoinRoomPage({ params }: { params: { code: string } }) {
   } | null>(null)
   const [showConfirmation, setShowConfirmation] = useState(false)
   const [showPasswordPrompt, setShowPasswordPrompt] = useState(false)
+  const [showApprovalPrompt, setShowApprovalPrompt] = useState(false)
+  const [approvalRequested, setApprovalRequested] = useState(false)
   const [password, setPassword] = useState('')
   const [error, setError] = useState<string | null>(null)
   const [isJoining, setIsJoining] = useState(false)
@@ -274,21 +277,17 @@ export default function JoinRoomPage({ params }: { params: { code: string } }) {
           return
         }
 
-        if (room.accessMode === 'restricted') {
-          setError('This room is invitation-only')
-          return
-        }
-
         if (room.accessMode === 'approval-only') {
-          setError('This room requires host approval. Please join via the room browser.')
+          setShowApprovalPrompt(true)
           return
         }
 
+        // For restricted rooms, try to join - the API will check for invitation
         // If user is in a different room, show confirmation
         if (roomData) {
           setShowConfirmation(true)
         } else {
-          // Otherwise, auto-join (for open rooms)
+          // Otherwise, auto-join (for open rooms and restricted rooms with invitation)
           handleJoin(room.id)
         }
       })
@@ -323,8 +322,88 @@ export default function JoinRoomPage({ params }: { params: { code: string } }) {
     }
   }
 
-  // Only show error page for non-password errors (password errors are shown in the password prompt UI)
-  if (error && !showPasswordPrompt) {
+  const handleRequestApproval = async () => {
+    if (!targetRoomData) return
+
+    setIsJoining(true)
+    setError(null)
+
+    try {
+      const res = await fetch(`/api/arcade/rooms/${targetRoomData.id}/join-requests`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      if (!res.ok) {
+        const errorData = await res.json()
+        throw new Error(errorData.error || 'Failed to request approval')
+      }
+
+      // Request sent successfully - show waiting state
+      setApprovalRequested(true)
+      setIsJoining(false)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to request approval')
+      setIsJoining(false)
+    }
+  }
+
+  // Socket listener for approval notifications
+  useEffect(() => {
+    if (!approvalRequested || !targetRoomData) return
+
+    console.log('[Join Page] Setting up approval listener for room:', targetRoomData.id)
+
+    let socket: ReturnType<typeof io> | null = null
+
+    // Fetch viewer ID and set up socket
+    const setupSocket = async () => {
+      try {
+        // Get current user's viewer ID
+        const res = await fetch('/api/viewer')
+        if (!res.ok) {
+          console.error('[Join Page] Failed to get viewer ID')
+          return
+        }
+
+        const { viewerId } = await res.json()
+        console.log('[Join Page] Got viewer ID:', viewerId)
+
+        // Connect socket
+        socket = io({ path: '/api/socket' })
+
+        socket.on('connect', () => {
+          console.log('[Join Page] Socket connected, joining user channel')
+          // Join user-specific channel to receive moderation events
+          socket?.emit('join-user-channel', { userId: viewerId })
+        })
+
+        socket.on('join-request-approved', (data: { roomId: string; requestId: string }) => {
+          console.log('[Join Page] Request approved via socket!', data)
+          if (data.roomId === targetRoomData.id) {
+            console.log('[Join Page] Joining room automatically...')
+            handleJoin(targetRoomData.id)
+          }
+        })
+
+        socket.on('connect_error', (error) => {
+          console.error('[Join Page] Socket connection error:', error)
+        })
+      } catch (error) {
+        console.error('[Join Page] Error setting up socket:', error)
+      }
+    }
+
+    setupSocket()
+
+    return () => {
+      console.log('[Join Page] Cleaning up approval listener')
+      socket?.disconnect()
+    }
+  }, [approvalRequested, targetRoomData, handleJoin])
+
+  // Only show error page for non-password and non-approval errors
+  if (error && !showPasswordPrompt && !showApprovalPrompt) {
     return (
       <div
         style={{
@@ -546,5 +625,260 @@ export default function JoinRoomPage({ params }: { params: { code: string } }) {
     )
   }
 
+  if (showApprovalPrompt && targetRoomData) {
+    return (
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          height: '100vh',
+          background: 'linear-gradient(135deg, #0f0f23 0%, #1a1a3a 50%, #2d1b69 100%)',
+        }}
+      >
+        <div
+          style={{
+            background: 'linear-gradient(135deg, rgba(17, 24, 39, 0.98), rgba(31, 41, 55, 0.98))',
+            borderRadius: '16px',
+            padding: '32px',
+            maxWidth: '450px',
+            width: '90%',
+            border: '2px solid rgba(59, 130, 246, 0.3)',
+            boxShadow: '0 20px 60px rgba(0, 0, 0, 0.5)',
+          }}
+        >
+          {approvalRequested ? (
+            // Waiting for approval state
+            <>
+              <div style={{ textAlign: 'center', marginBottom: '20px' }}>
+                <div style={{ fontSize: '48px', marginBottom: '16px' }}>⏳</div>
+                <h2
+                  style={{
+                    fontSize: '24px',
+                    fontWeight: 'bold',
+                    marginBottom: '8px',
+                    color: 'rgba(96, 165, 250, 1)',
+                  }}
+                >
+                  Waiting for Approval
+                </h2>
+                <p
+                  style={{
+                    fontSize: '14px',
+                    color: 'rgba(209, 213, 219, 0.8)',
+                  }}
+                >
+                  Your request has been sent to the room moderator.
+                </p>
+              </div>
+
+              <div
+                style={{
+                  background: 'rgba(59, 130, 246, 0.1)',
+                  border: '1px solid rgba(59, 130, 246, 0.3)',
+                  borderRadius: '12px',
+                  padding: '16px',
+                  marginBottom: '20px',
+                }}
+              >
+                <div
+                  style={{ fontSize: '14px', fontWeight: '600', color: 'rgba(96, 165, 250, 1)' }}
+                >
+                  {getRoomDisplayWithEmoji({
+                    name: targetRoomData.name,
+                    code: targetRoomData.code,
+                    gameName: targetRoomData.gameName,
+                  })}
+                </div>
+                <div
+                  style={{
+                    fontSize: '13px',
+                    color: 'rgba(209, 213, 219, 0.7)',
+                    fontFamily: 'monospace',
+                    marginTop: '4px',
+                  }}
+                >
+                  Code: {targetRoomData.code}
+                </div>
+              </div>
+
+              <p
+                style={{
+                  fontSize: '13px',
+                  color: 'rgba(156, 163, 175, 1)',
+                  textAlign: 'center',
+                  marginBottom: '20px',
+                }}
+              >
+                You'll be able to join once the host approves your request. You can close this page
+                and check back later.
+              </p>
+
+              <button
+                type="button"
+                onClick={() => router.push('/arcade')}
+                style={{
+                  width: '100%',
+                  padding: '12px',
+                  background: 'rgba(75, 85, 99, 0.3)',
+                  color: 'rgba(209, 213, 219, 1)',
+                  border: '2px solid rgba(75, 85, 99, 0.5)',
+                  borderRadius: '10px',
+                  fontSize: '15px',
+                  fontWeight: '600',
+                  cursor: 'pointer',
+                  transition: 'all 0.2s ease',
+                }}
+                onMouseEnter={(e) => {
+                  e.currentTarget.style.background = 'rgba(75, 85, 99, 0.4)'
+                }}
+                onMouseLeave={(e) => {
+                  e.currentTarget.style.background = 'rgba(75, 85, 99, 0.3)'
+                }}
+              >
+                Go to Champion Arena
+              </button>
+            </>
+          ) : (
+            // Request approval prompt
+            <>
+              <h2
+                style={{
+                  fontSize: '24px',
+                  fontWeight: 'bold',
+                  marginBottom: '8px',
+                  color: 'rgba(96, 165, 250, 1)',
+                }}
+              >
+                ✋ Approval Required
+              </h2>
+              <p
+                style={{
+                  fontSize: '14px',
+                  color: 'rgba(209, 213, 219, 0.8)',
+                  marginBottom: '20px',
+                }}
+              >
+                This room requires host approval to join. Send a request?
+              </p>
+
+              <div
+                style={{
+                  background: 'rgba(59, 130, 246, 0.1)',
+                  border: '1px solid rgba(59, 130, 246, 0.3)',
+                  borderRadius: '12px',
+                  padding: '16px',
+                  marginBottom: '20px',
+                }}
+              >
+                <div
+                  style={{ fontSize: '14px', fontWeight: '600', color: 'rgba(96, 165, 250, 1)' }}
+                >
+                  {getRoomDisplayWithEmoji({
+                    name: targetRoomData.name,
+                    code: targetRoomData.code,
+                    gameName: targetRoomData.gameName,
+                  })}
+                </div>
+                <div
+                  style={{
+                    fontSize: '13px',
+                    color: 'rgba(209, 213, 219, 0.7)',
+                    fontFamily: 'monospace',
+                    marginTop: '4px',
+                  }}
+                >
+                  Code: {targetRoomData.code}
+                </div>
+              </div>
+
+              {error && (
+                <p
+                  style={{
+                    fontSize: '13px',
+                    color: 'rgba(248, 113, 113, 1)',
+                    marginBottom: '16px',
+                    textAlign: 'center',
+                  }}
+                >
+                  {error}
+                </p>
+              )}
+
+              <div style={{ display: 'flex', gap: '12px' }}>
+                <button
+                  type="button"
+                  onClick={() => router.push('/arcade')}
+                  disabled={isJoining}
+                  style={{
+                    flex: 1,
+                    padding: '12px',
+                    background: 'rgba(75, 85, 99, 0.3)',
+                    color: 'rgba(209, 213, 219, 1)',
+                    border: '2px solid rgba(75, 85, 99, 0.5)',
+                    borderRadius: '10px',
+                    fontSize: '15px',
+                    fontWeight: '600',
+                    cursor: isJoining ? 'not-allowed' : 'pointer',
+                    opacity: isJoining ? 0.5 : 1,
+                    transition: 'all 0.2s ease',
+                  }}
+                  onMouseEnter={(e) => {
+                    if (!isJoining) {
+                      e.currentTarget.style.background = 'rgba(75, 85, 99, 0.4)'
+                    }
+                  }}
+                  onMouseLeave={(e) => {
+                    if (!isJoining) {
+                      e.currentTarget.style.background = 'rgba(75, 85, 99, 0.3)'
+                    }
+                  }}
+                >
+                  Cancel
+                </button>
+                <button
+                  type="button"
+                  onClick={handleRequestApproval}
+                  disabled={isJoining}
+                  style={{
+                    flex: 1,
+                    padding: '12px',
+                    background: isJoining
+                      ? 'rgba(75, 85, 99, 0.3)'
+                      : 'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))',
+                    color: isJoining ? 'rgba(156, 163, 175, 1)' : 'rgba(255, 255, 255, 1)',
+                    border: isJoining
+                      ? '2px solid rgba(75, 85, 99, 0.5)'
+                      : '2px solid rgba(59, 130, 246, 0.6)',
+                    borderRadius: '10px',
+                    fontSize: '15px',
+                    fontWeight: '600',
+                    cursor: isJoining ? 'not-allowed' : 'pointer',
+                    opacity: isJoining ? 0.5 : 1,
+                    transition: 'all 0.2s ease',
+                  }}
+                  onMouseEnter={(e) => {
+                    if (!isJoining) {
+                      e.currentTarget.style.background =
+                        'linear-gradient(135deg, rgba(59, 130, 246, 0.9), rgba(37, 99, 235, 0.9))'
+                    }
+                  }}
+                  onMouseLeave={(e) => {
+                    if (!isJoining) {
+                      e.currentTarget.style.background =
+                        'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))'
+                    }
+                  }}
+                >
+                  {isJoining ? 'Sending...' : 'Request to Join'}
+                </button>
+              </div>
+            </>
+          )}
+        </div>
+      </div>
+    )
+  }
+
   return null
 }

apps/web/src/arcade-games/README.md

@@ -0,0 +1,816 @@
+# Arcade Game System
+
+A modular, plugin-based architecture for building multiplayer arcade games with real-time synchronization.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Game SDK](#game-sdk)
+- [Creating a New Game](#creating-a-new-game)
+- [File Structure](#file-structure)
+- [Examples](#examples)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+### Goals
+
+1. **Modularity**: Each game is self-contained and independently deployable
+2. **Type Safety**: Full TypeScript support with compile-time validation
+3. **Real-time Sync**: Built-in multiplayer support via WebSocket
+4. **Optimistic Updates**: Instant client feedback with server validation
+5. **Consistent UX**: Shared navigation, player management, and room features
+
+### Key Features
+
+- **Plugin Architecture**: Games register themselves with a central registry
+- **Stable SDK API**: Games only import from `@/lib/arcade/game-sdk`
+- **Server-side Validation**: All moves validated server-side with client rollback
+- **Automatic State Sync**: Multi-client synchronization handled automatically
+- **Turn Indicators**: Built-in UI for showing active player
+- **Error Handling**: Standardized error feedback to users
+
+---
+
+## Architecture
+
+### System Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Game Registry                            │
+│  - Registers all available games                            │
+│  - Provides game discovery                                  │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      Game SDK                                │
+│  - Stable API surface for games                             │
+│  - React hooks (useArcadeSession, useRoomData, etc.)        │
+│  - Type definitions and utilities                           │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Individual Games                           │
+│  number-guesser/                                            │
+│    ├── index.ts          (Game definition)                  │
+│    ├── Validator.ts      (Server validation)                │
+│    ├── Provider.tsx      (Client state management)          │
+│    ├── GameComponent.tsx (Main UI)                          │
+│    ├── types.ts          (TypeScript types)                 │
+│    └── components/       (Phase UIs)                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow
+
+```
+User Action → Provider (sendMove)
+              ↓
+        useArcadeSession
+              ↓
+        Optimistic Update (instant UI feedback)
+              ↓
+        WebSocket → Server
+              ↓
+        Validator.validateMove()
+              ↓
+        ✓ Valid: State Update → Broadcast
+        ✗ Invalid: Reject → Client Rollback
+              ↓
+        Client receives validated state
+```
+
+---
+
+## Game SDK
+
+### Core API Surface
+
+```typescript
+import {
+  // Types
+  type GameDefinition,
+  type GameValidator,
+  type GameState,
+  type GameMove,
+  type GameConfig,
+  type ValidationResult,
+
+  // React Hooks
+  useArcadeSession,
+  useRoomData,
+  useGameMode,
+  useViewerId,
+  useUpdateGameConfig,
+
+  // Utilities
+  defineGame,
+  buildPlayerMetadata,
+
+} from '@/lib/arcade/game-sdk'
+```
+
+### Key Concepts
+
+#### GameDefinition
+
+Complete description of a game:
+
+```typescript
+interface GameDefinition<TConfig, TState, TMove> {
+  manifest: GameManifest          // Display info, max players, etc.
+  Provider: GameProviderComponent // React context provider
+  GameComponent: GameComponent    // Main UI component
+  validator: GameValidator        // Server-side validation
+  defaultConfig: TConfig          // Default game settings
+}
+```
+
+#### GameState
+
+The complete game state that's synchronized across all clients:
+
+```typescript
+interface GameState {
+  gamePhase: string                          // Current phase (setup, playing, results)
+  activePlayers: string[]                    // Array of player IDs
+  playerMetadata: Record<string, PlayerMeta> // Player info (name, emoji, etc.)
+  // ... game-specific state
+}
+```
+
+#### GameMove
+
+Actions that players take, validated server-side:
+
+```typescript
+interface GameMove {
+  type: string           // Move type (e.g., 'FLIP_CARD', 'MAKE_GUESS')
+  playerId: string       // Player making the move
+  userId: string         // User ID (for authentication)
+  timestamp: number      // Client timestamp
+  data: Record<string, unknown> // Move-specific payload
+}
+```
+
+#### GameValidator
+
+Server-side validation logic:
+
+```typescript
+interface GameValidator<TState, TMove> {
+  validateMove(state: TState, move: TMove): ValidationResult
+  isGameComplete(state: TState): boolean
+  getInitialState(config: unknown): TState
+}
+```
+
+---
+
+## Creating a New Game
+
+### Step 1: Create Game Directory
+
+```bash
+mkdir -p src/arcade-games/my-game/components
+```
+
+### Step 2: Define Types (`types.ts`)
+
+```typescript
+import type { GameConfig, GameMove, GameState } from '@/lib/arcade/game-sdk'
+
+// Game configuration (persisted to database)
+export interface MyGameConfig extends GameConfig {
+  difficulty: number
+  timer: number
+}
+
+// Game state (synchronized across clients)
+export interface MyGameState extends GameState {
+  gamePhase: 'setup' | 'playing' | 'results'
+  activePlayers: string[]
+  playerMetadata: Record<string, PlayerMetadata>
+  currentPlayer: string
+  score: Record<string, number>
+  // ... your game-specific state
+}
+
+// Move types
+export type MyGameMove =
+  | { type: 'START_GAME'; playerId: string; userId: string; timestamp: number; data: { activePlayers: string[] } }
+  | { type: 'MAKE_MOVE'; playerId: string; userId: string; timestamp: number; data: { /* move data */ } }
+  | { type: 'END_GAME'; playerId: string; userId: string; timestamp: number; data: {} }
+```
+
+### Step 3: Create Validator (`Validator.ts`)
+
+```typescript
+import type { GameValidator, ValidationResult } from '@/lib/arcade/game-sdk'
+import type { MyGameState, MyGameMove } from './types'
+
+export class MyGameValidator implements GameValidator<MyGameState, MyGameMove> {
+  validateMove(state: MyGameState, move: MyGameMove): ValidationResult {
+    switch (move.type) {
+      case 'START_GAME':
+        return this.validateStartGame(state, move.data.activePlayers)
+      case 'MAKE_MOVE':
+        return this.validateMakeMove(state, move.playerId, move.data)
+      default:
+        return { valid: false, error: 'Unknown move type' }
+    }
+  }
+
+  private validateStartGame(state: MyGameState, activePlayers: string[]): ValidationResult {
+    if (activePlayers.length < 2) {
+      return { valid: false, error: 'Need at least 2 players' }
+    }
+
+    const newState: MyGameState = {
+      ...state,
+      gamePhase: 'playing',
+      activePlayers,
+      currentPlayer: activePlayers[0],
+      score: activePlayers.reduce((acc, p) => ({ ...acc, [p]: 0 }), {}),
+    }
+
+    return { valid: true, newState }
+  }
+
+  // ... more validation methods
+
+  isGameComplete(state: MyGameState): boolean {
+    return state.gamePhase === 'results'
+  }
+
+  getInitialState(config: unknown): MyGameState {
+    const { difficulty, timer } = config as MyGameConfig
+    return {
+      difficulty,
+      timer,
+      gamePhase: 'setup',
+      activePlayers: [],
+      playerMetadata: {},
+      currentPlayer: '',
+      score: {},
+    }
+  }
+}
+
+export const myGameValidator = new MyGameValidator()
+```
+
+### Step 4: Create Provider (`Provider.tsx`)
+
+```typescript
+'use client'
+
+import { createContext, useCallback, useContext, useMemo } from 'react'
+import {
+  type GameMove,
+  buildPlayerMetadata,
+  useArcadeSession,
+  useGameMode,
+  useRoomData,
+  useViewerId,
+} from '@/lib/arcade/game-sdk'
+import type { MyGameState } from './types'
+
+interface MyGameContextValue {
+  state: MyGameState
+  lastError: string | null
+  startGame: () => void
+  makeMove: (data: any) => void
+  clearError: () => void
+  exitSession: () => void
+}
+
+const MyGameContext = createContext<MyGameContextValue | null>(null)
+
+export function useMyGame() {
+  const context = useContext(MyGameContext)
+  if (!context) throw new Error('useMyGame must be used within MyGameProvider')
+  return context
+}
+
+export function MyGameProvider({ children }: { children: React.ReactNode }) {
+  const { data: viewerId } = useViewerId()
+  const { roomData } = useRoomData()
+  const { activePlayers: activePlayerIds, players } = useGameMode()
+
+  // Get active players as array (keep Set iteration order to match UI display)
+  const activePlayers = Array.from(activePlayerIds)
+
+  const initialState = useMemo(() => ({
+    difficulty: 1,
+    timer: 30,
+    gamePhase: 'setup' as const,
+    activePlayers: [],
+    playerMetadata: {},
+    currentPlayer: '',
+    score: {},
+  }), [])
+
+  const { state, sendMove, exitSession, lastError, clearError } =
+    useArcadeSession<MyGameState>({
+      userId: viewerId || '',
+      roomId: roomData?.id,
+      initialState,
+      applyMove: (state, move) => state, // Server handles all updates
+    })
+
+  const startGame = useCallback(() => {
+    const playerMetadata = buildPlayerMetadata(activePlayers, {}, players, viewerId)
+
+    sendMove({
+      type: 'START_GAME',
+      playerId: activePlayers[0],
+      userId: viewerId || '',
+      data: { activePlayers, playerMetadata },
+    })
+  }, [activePlayers, players, viewerId, sendMove])
+
+  const makeMove = useCallback((data: any) => {
+    sendMove({
+      type: 'MAKE_MOVE',
+      playerId: state.currentPlayer,
+      userId: viewerId || '',
+      data,
+    })
+  }, [state.currentPlayer, viewerId, sendMove])
+
+  return (
+    <MyGameContext.Provider value={{
+      state,
+      lastError,
+      startGame,
+      makeMove,
+      clearError,
+      exitSession,
+    }}>
+      {children}
+    </MyGameContext.Provider>
+  )
+}
+```
+
+### Step 5: Create Game Component (`GameComponent.tsx`)
+
+```typescript
+'use client'
+
+import { useRouter } from 'next/navigation'
+import { PageWithNav } from '@/components/PageWithNav'
+import { useMyGame } from '../Provider'
+import { SetupPhase } from './SetupPhase'
+import { PlayingPhase } from './PlayingPhase'
+import { ResultsPhase } from './ResultsPhase'
+
+export function GameComponent() {
+  const router = useRouter()
+  const { state, exitSession } = useMyGame()
+
+  // Determine whose turn it is for the turn indicator
+  const currentPlayerId = state.gamePhase === 'playing' ? state.currentPlayer : undefined
+
+  return (
+    <PageWithNav
+      navTitle="My Game"
+      navEmoji="🎮"
+      emphasizePlayerSelection={state.gamePhase === 'setup'}
+      currentPlayerId={currentPlayerId}
+      playerScores={state.score}
+      onExitSession={() => {
+        exitSession()
+        router.push('/arcade')
+      }}
+    >
+      {state.gamePhase === 'setup' && <SetupPhase />}
+      {state.gamePhase === 'playing' && <PlayingPhase />}
+      {state.gamePhase === 'results' && <ResultsPhase />}
+    </PageWithNav>
+  )
+}
+```
+
+### Step 6: Define Game (`index.ts`)
+
+```typescript
+import { defineGame } from '@/lib/arcade/game-sdk'
+import type { GameManifest } from '@/lib/arcade/game-sdk'
+import { GameComponent } from './components/GameComponent'
+import { MyGameProvider } from './Provider'
+import type { MyGameConfig, MyGameMove, MyGameState } from './types'
+import { myGameValidator } from './Validator'
+
+const manifest: GameManifest = {
+  name: 'my-game',
+  displayName: 'My Awesome Game',
+  icon: '🎮',
+  description: 'A fun multiplayer game',
+  longDescription: 'Detailed description of gameplay...',
+  maxPlayers: 4,
+  difficulty: 'Beginner',
+  chips: ['👥 Multiplayer', '🎲 Turn-Based'],
+  color: 'blue',
+  gradient: 'linear-gradient(135deg, #bfdbfe, #93c5fd)',
+  borderColor: 'blue.200',
+  available: true,
+}
+
+const defaultConfig: MyGameConfig = {
+  difficulty: 1,
+  timer: 30,
+}
+
+export const myGame = defineGame<MyGameConfig, MyGameState, MyGameMove>({
+  manifest,
+  Provider: MyGameProvider,
+  GameComponent,
+  validator: myGameValidator,
+  defaultConfig,
+})
+```
+
+### Step 7: Register Game
+
+#### 7a. Register Validator (Server-Side)
+
+Add your validator to the unified registry in `src/lib/arcade/validators.ts`:
+
+```typescript
+import { myGameValidator } from '@/arcade-games/my-game/Validator'
+
+export const validatorRegistry = {
+  matching: matchingGameValidator,
+  'memory-quiz': memoryQuizGameValidator,
+  'number-guesser': numberGuesserValidator,
+  'my-game': myGameValidator,  // Add your game here!
+  // GameName type will auto-update from these keys
+} as const
+```
+
+**Why**: The validator registry is isomorphic (runs on both client and server) and serves as the single source of truth for all game validators. Adding your validator here automatically:
+- Makes it available for server-side move validation
+- Updates the `GameName` type (no manual type updates needed!)
+- Enables your game for multiplayer rooms
+
+#### 7b. Register Game Definition (Client-Side)
+
+Add to `src/lib/arcade/game-registry.ts`:
+
+```typescript
+import { myGame } from '@/arcade-games/my-game'
+
+registerGame(myGame)
+```
+
+**Why**: The game registry is client-only and connects your game's UI components (Provider, GameComponent) with the arcade system. Registration happens on client init and verifies that your validator is also registered server-side.
+
+**Verification**: When you register a game, the registry will warn you if:
+- ⚠️  The validator is missing from `validators.ts`
+- ⚠️  The validator instance doesn't match (different imports)
+
+**Important**: Both steps are required for a working game. The validator registry handles server logic, while the game registry handles client UI.
+
+---
+
+## File Structure
+
+```
+src/arcade-games/my-game/
+├── index.ts                 # Game definition and export
+├── Validator.ts             # Server-side move validation
+├── Provider.tsx             # Client state management
+├── GameComponent.tsx        # Main UI wrapper
+├── types.ts                 # TypeScript type definitions
+└── components/
+    ├── SetupPhase.tsx       # Setup/lobby UI
+    ├── PlayingPhase.tsx     # Main gameplay UI
+    └── ResultsPhase.tsx     # End game/scores UI
+```
+
+### File Responsibilities
+
+| File | Purpose | Runs On |
+|------|---------|---------|
+| `index.ts` | Game registration | Both |
+| `Validator.ts` | Move validation, game logic | **Server only** |
+| `Provider.tsx` | State management, API calls | Client only |
+| `GameComponent.tsx` | Navigation, phase routing | Client only |
+| `types.ts` | Shared type definitions | Both |
+| `components/*` | UI for each game phase | Client only |
+
+---
+
+## Examples
+
+### Number Guesser (Turn-Based)
+
+See `src/arcade-games/number-guesser/` for a complete example of:
+- Turn-based gameplay (chooser → guessers)
+- Player rotation logic
+- Round management
+- Score tracking
+- Hot/cold feedback system
+- Error handling and user feedback
+
+**Key Patterns:**
+- Setting `currentPlayerId` for turn indicators
+- Rotating turns in validator
+- Handling round vs. game completion
+- Type coercion for JSON-serialized numbers
+
+---
+
+## Best Practices
+
+### 1. Player Ordering Consistency
+
+**Problem**: Sets don't guarantee order, causing mismatch between UI and game logic.
+
+**Solution**: Use `Array.from(activePlayerIds)` without sorting in both UI and game logic.
+
+```typescript
+// In Provider
+const activePlayers = Array.from(activePlayerIds) // NO .sort()
+
+// In Validator
+const newState = {
+  ...state,
+  currentPlayer: activePlayers[0], // First in Set order = first in UI
+}
+```
+
+### 2. Type Coercion for Numbers
+
+**Problem**: WebSocket JSON serialization converts numbers to strings.
+
+**Solution**: Explicitly coerce in validator:
+
+```typescript
+validateMove(state: MyGameState, move: MyGameMove): ValidationResult {
+  switch (move.type) {
+    case 'MAKE_GUESS':
+      return this.validateGuess(state, Number(move.data.guess)) // Coerce!
+  }
+}
+```
+
+### 3. Error Feedback
+
+**Problem**: Users don't see why their moves were rejected.
+
+**Solution**: Use `lastError` from `useArcadeSession`:
+
+```typescript
+const { state, lastError, clearError } = useArcadeSession(...)
+
+// Auto-dismiss after 5 seconds
+useEffect(() => {
+  if (lastError) {
+    const timeout = setTimeout(() => clearError(), 5000)
+    return () => clearTimeout(timeout)
+  }
+}, [lastError, clearError])
+
+// Show in UI
+{lastError && (
+  <div className="error-banner">
+    <div>⚠️ Move Rejected</div>
+    <div>{lastError}</div>
+    <button onClick={clearError}>Dismiss</button>
+  </div>
+)}
+```
+
+### 4. Turn Indicators
+
+**Problem**: Players don't know whose turn it is.
+
+**Solution**: Pass `currentPlayerId` to `PageWithNav`:
+
+```typescript
+<PageWithNav
+  currentPlayerId={state.currentPlayer}
+  playerScores={state.scores}
+>
+```
+
+### 5. Server-Only Logic
+
+**Problem**: Client can cheat by modifying local state.
+
+**Solution**: All game logic in validator, client uses `applyMove: (state) => state`:
+
+```typescript
+// ❌ BAD: Client calculates winner
+const { state, sendMove } = useArcadeSession({
+  applyMove: (state, move) => {
+    if (move.type === 'SCORE') {
+      return { ...state, winner: calculateWinner(state) } // Cheatable!
+    }
+  }
+})
+
+// ✅ GOOD: Server calculates everything
+const { state, sendMove } = useArcadeSession({
+  applyMove: (state, move) => state // Client just waits for server
+})
+```
+
+### 6. Phase Management
+
+Use discriminated union for type-safe phase rendering:
+
+```typescript
+type GamePhase = 'setup' | 'playing' | 'results'
+
+interface MyGameState {
+  gamePhase: GamePhase
+  // ...
+}
+
+// In GameComponent
+{state.gamePhase === 'setup' && <SetupPhase />}
+{state.gamePhase === 'playing' && <PlayingPhase />}
+{state.gamePhase === 'results' && <ResultsPhase />}
+```
+
+---
+
+## Troubleshooting
+
+### "Player not found" errors
+
+**Cause**: Player IDs from `useGameMode()` don't match server state.
+
+**Fix**: Always use `buildPlayerMetadata()` helper:
+
+```typescript
+const playerMetadata = buildPlayerMetadata(activePlayers, {}, players, viewerId)
+```
+
+### Turn indicator not showing
+
+**Cause**: `currentPlayerId` not passed or doesn't match player IDs in UI.
+
+**Fix**: Verify player order matches between game state and `activePlayerIds`:
+
+```typescript
+// Both should use same source without sorting
+const activePlayers = Array.from(activePlayerIds) // Provider
+const activePlayerList = Array.from(activePlayers) // PageWithNav
+```
+
+### Moves rejected with type errors
+
+**Cause**: JSON serialization converts numbers to strings.
+
+**Fix**: Add `Number()` coercion in validator:
+
+```typescript
+case 'SET_VALUE':
+  return this.validateValue(state, Number(move.data.value))
+```
+
+### State not syncing across clients
+
+**Cause**: Not using `useArcadeSession` correctly.
+
+**Fix**: Ensure `roomId` is passed:
+
+```typescript
+const { state, sendMove } = useArcadeSession({
+  userId: viewerId || '',
+  roomId: roomData?.id, // Required for room sync!
+  initialState,
+  applyMove: (state) => state,
+})
+```
+
+### Game not appearing in selector
+
+**Cause**: Not registered or `available: false`.
+
+**Fix**:
+1. Add to `game-registry.ts`: `registerGame(myGame)`
+2. Set `available: true` in manifest
+3. Verify no console errors on import
+
+### Config changes not taking effect
+
+**Cause**: State sync timing - validator uses old state while config is being updated.
+
+**Context**: When you change game config (e.g., min/max numbers), there's a brief window where:
+1. Client updates config in database
+2. Config change hasn't propagated to server state yet
+3. Moves are validated against old state
+
+**Fix**: Ensure config changes trigger state reset or are applied atomically:
+
+```typescript
+// When changing config, also update initialState
+const setConfig = useCallback((field, value) => {
+  sendMove({ type: 'SET_CONFIG', data: { field, value } })
+
+  // Persist to database for next session
+  if (roomData?.id) {
+    updateGameConfig({
+      roomId: roomData.id,
+      gameConfig: {
+        ...roomData.gameConfig,
+        'my-game': { ...currentConfig, [field]: value }
+      }
+    })
+  }
+}, [sendMove, updateGameConfig, roomData])
+```
+
+**Best Practice**: Make config changes only during setup phase, before game starts.
+
+### Debugging validation errors
+
+**Problem**: Moves rejected but unclear why (especially type-related issues).
+
+**Solution**: Add debug logging in validator:
+
+```typescript
+private validateGuess(state: State, guess: number): ValidationResult {
+  // Debug logging
+  console.log('[MyGame] Validating guess:', {
+    guess,
+    guessType: typeof guess,           // Check if it's a string!
+    min: state.minNumber,
+    minType: typeof state.minNumber,
+    max: state.maxNumber,
+    maxType: typeof state.maxNumber,
+  })
+
+  if (guess < state.minNumber || guess > state.maxNumber) {
+    return { valid: false, error: `Guess must be between ${state.minNumber} and ${state.maxNumber}` }
+  }
+
+  // ... rest of validation
+}
+```
+
+**What to check:**
+1. **Browser console**: Look for `[ArcadeSession] Move rejected by server:` messages
+2. **Server logs**: Check validator console.log output for types and values
+3. **Type mismatches**: Numbers becoming strings is the #1 issue
+4. **State sync**: Is the validator using the state you expect?
+
+**Common debugging workflow:**
+1. Move rejected → Check browser console for error message
+2. Error unclear → Add console.log to validator
+3. Restart server → See debug output when move is made
+4. Compare expected vs. actual values/types
+5. Add `Number()` coercion if types don't match
+
+---
+
+## Resources
+
+- **Game SDK**: `src/lib/arcade/game-sdk/`
+- **Registry**: `src/lib/arcade/game-registry.ts`
+- **Example Game**: `src/arcade-games/number-guesser/`
+- **Validation Types**: `src/lib/arcade/validation/types.ts`
+
+---
+
+## FAQ
+
+**Q: Can I use external libraries in my game?**
+A: Yes, but install them in the workspace package.json. Games should be self-contained.
+
+**Q: How do I add game configuration that persists?**
+A: Use `useUpdateGameConfig()` to save to room:
+
+```typescript
+const { mutate: updateGameConfig } = useUpdateGameConfig()
+
+updateGameConfig({
+  roomId: roomData.id,
+  gameConfig: {
+    ...roomData.gameConfig,
+    'my-game': { difficulty: 5 }
+  }
+})
+```
+
+**Q: Can I have asymmetric player roles?**
+A: Yes! See Number Guesser's chooser/guesser pattern.
+
+**Q: How do I handle real-time timers?**
+A: Store `startTime` in state, use client-side countdown, server validates elapsed time.
+
+**Q: What's the difference between `playerId` and `userId`?**
+A: `userId` is the user account, `playerId` is the avatar/character in the game. One user can control multiple players.

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

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

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

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

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

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

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

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

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

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

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

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

apps/web/src/arcade-games/math-sprint/game.yaml

@@ -0,0 +1,16 @@
+name: math-sprint
+displayName: Math Sprint
+icon: 🧮
+description: Fast-paced math racing game
+longDescription: Race against other players to solve math problems! Answer questions quickly to earn points. First person to answer correctly wins the round. Features multiple difficulty levels and customizable question counts.
+maxPlayers: 6
+difficulty: Beginner
+chips:
+  - 👥 Multiplayer
+  - ⚡ Free-for-All
+  - 🧮 Math Skills
+  - 🏃 Speed
+color: purple
+gradient: linear-gradient(135deg, #ddd6fe, #c4b5fd)
+borderColor: purple.200
+available: true

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

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

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

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

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

@@ -0,0 +1,215 @@
+/**
+ * Number Guesser Provider
+ * Manages game state using the Arcade SDK
+ */
+
+'use client'
+
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from 'react'
+import {
+  type GameMove,
+  buildPlayerMetadata,
+  useArcadeSession,
+  useGameMode,
+  useRoomData,
+  useUpdateGameConfig,
+  useViewerId,
+} from '@/lib/arcade/game-sdk'
+import type { NumberGuesserState } from './types'
+
+/**
+ * Context value interface
+ */
+interface NumberGuesserContextValue {
+  state: NumberGuesserState
+  lastError: string | null
+  startGame: () => void
+  chooseNumber: (number: number) => void
+  makeGuess: (guess: number) => void
+  nextRound: () => void
+  goToSetup: () => void
+  setConfig: (field: 'minNumber' | 'maxNumber' | 'roundsToWin', value: number) => void
+  clearError: () => void
+  exitSession: () => void
+}
+
+const NumberGuesserContext = createContext<NumberGuesserContextValue | null>(null)
+
+/**
+ * Hook to access Number Guesser context
+ */
+export function useNumberGuesser() {
+  const context = useContext(NumberGuesserContext)
+  if (!context) {
+    throw new Error('useNumberGuesser must be used within NumberGuesserProvider')
+  }
+  return context
+}
+
+/**
+ * Optimistic move application
+ */
+function applyMoveOptimistically(state: NumberGuesserState, move: GameMove): NumberGuesserState {
+  // For simplicity, just return current state
+  // Server will send back the validated new state
+  return state
+}
+
+/**
+ * Number Guesser Provider Component
+ */
+export function NumberGuesserProvider({ children }: { children: ReactNode }) {
+  const { data: viewerId } = useViewerId()
+  const { roomData } = useRoomData()
+  const { activePlayers: activePlayerIds, players } = useGameMode()
+  const { mutate: updateGameConfig } = useUpdateGameConfig()
+
+  // Get active players as array (keep Set iteration order to match UI display)
+  const activePlayers = Array.from(activePlayerIds)
+
+  // Merge saved config from room
+  const initialState = useMemo(() => {
+    const gameConfig = roomData?.gameConfig as Record<string, unknown> | null | undefined
+    const savedConfig = gameConfig?.['number-guesser'] as Record<string, unknown> | undefined
+
+    return {
+      minNumber: (savedConfig?.minNumber as number) || 1,
+      maxNumber: (savedConfig?.maxNumber as number) || 100,
+      roundsToWin: (savedConfig?.roundsToWin as number) || 3,
+      gamePhase: 'setup' as const,
+      activePlayers: [],
+      playerMetadata: {},
+      secretNumber: null,
+      chooser: '',
+      currentGuesser: '',
+      guesses: [],
+      roundNumber: 0,
+      scores: {},
+      gameStartTime: null,
+      gameEndTime: null,
+      winner: null,
+    }
+  }, [roomData?.gameConfig])
+
+  // Arcade session integration
+  const { state, sendMove, exitSession, lastError, clearError } =
+    useArcadeSession<NumberGuesserState>({
+      userId: viewerId || '',
+      roomId: roomData?.id,
+      initialState,
+      applyMove: applyMoveOptimistically,
+    })
+
+  // Action creators
+  const startGame = useCallback(() => {
+    if (activePlayers.length < 2) {
+      console.error('Need at least 2 players to start')
+      return
+    }
+
+    const playerMetadata = buildPlayerMetadata(activePlayers, {}, players, viewerId || undefined)
+
+    sendMove({
+      type: 'START_GAME',
+      playerId: activePlayers[0],
+      userId: viewerId || '',
+      data: {
+        activePlayers,
+        playerMetadata,
+      },
+    })
+  }, [activePlayers, players, viewerId, sendMove])
+
+  const chooseNumber = useCallback(
+    (secretNumber: number) => {
+      sendMove({
+        type: 'CHOOSE_NUMBER',
+        playerId: state.chooser,
+        userId: viewerId || '',
+        data: { secretNumber },
+      })
+    },
+    [state.chooser, viewerId, sendMove]
+  )
+
+  const makeGuess = useCallback(
+    (guess: number) => {
+      const playerName = state.playerMetadata[state.currentGuesser]?.name || 'Unknown'
+
+      sendMove({
+        type: 'MAKE_GUESS',
+        playerId: state.currentGuesser,
+        userId: viewerId || '',
+        data: { guess, playerName },
+      })
+    },
+    [state.currentGuesser, state.playerMetadata, viewerId, sendMove]
+  )
+
+  const nextRound = useCallback(() => {
+    sendMove({
+      type: 'NEXT_ROUND',
+      playerId: activePlayers[0] || '',
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [activePlayers, viewerId, sendMove])
+
+  const goToSetup = useCallback(() => {
+    sendMove({
+      type: 'GO_TO_SETUP',
+      playerId: activePlayers[0] || state.chooser || '',
+      userId: viewerId || '',
+      data: {},
+    })
+  }, [activePlayers, state.chooser, viewerId, sendMove])
+
+  const setConfig = useCallback(
+    (field: 'minNumber' | 'maxNumber' | 'roundsToWin', value: number) => {
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId: activePlayers[0] || '',
+        userId: viewerId || '',
+        data: { field, value },
+      })
+
+      // Persist to database
+      if (roomData?.id) {
+        const currentGameConfig = (roomData.gameConfig as Record<string, unknown>) || {}
+        const currentNumberGuesserConfig =
+          (currentGameConfig['number-guesser'] as Record<string, unknown>) || {}
+
+        const updatedConfig = {
+          ...currentGameConfig,
+          'number-guesser': {
+            ...currentNumberGuesserConfig,
+            [field]: value,
+          },
+        }
+
+        updateGameConfig({
+          roomId: roomData.id,
+          gameConfig: updatedConfig,
+        })
+      }
+    },
+    [activePlayers, viewerId, sendMove, roomData?.id, roomData?.gameConfig, updateGameConfig]
+  )
+
+  const contextValue: NumberGuesserContextValue = {
+    state,
+    lastError,
+    startGame,
+    chooseNumber,
+    makeGuess,
+    nextRound,
+    goToSetup,
+    setConfig,
+    clearError,
+    exitSession,
+  }
+
+  return (
+    <NumberGuesserContext.Provider value={contextValue}>{children}</NumberGuesserContext.Provider>
+  )
+}

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

@@ -0,0 +1,315 @@
+/**
+ * Server-side validator for Number Guesser game
+ */
+
+import type { GameValidator, ValidationResult } from '@/lib/arcade/game-sdk'
+import type { NumberGuesserConfig, NumberGuesserMove, NumberGuesserState } from './types'
+
+export class NumberGuesserValidator
+  implements GameValidator<NumberGuesserState, NumberGuesserMove>
+{
+  validateMove(state: NumberGuesserState, move: NumberGuesserMove): ValidationResult {
+    switch (move.type) {
+      case 'START_GAME':
+        return this.validateStartGame(state, move.data.activePlayers, move.data.playerMetadata)
+
+      case 'CHOOSE_NUMBER':
+        // Ensure secretNumber is a number (JSON deserialization can make it a string)
+        return this.validateChooseNumber(state, Number(move.data.secretNumber), move.playerId)
+
+      case 'MAKE_GUESS':
+        // Ensure guess is a number (JSON deserialization can make it a string)
+        return this.validateMakeGuess(
+          state,
+          Number(move.data.guess),
+          move.playerId,
+          move.data.playerName
+        )
+
+      case 'NEXT_ROUND':
+        return this.validateNextRound(state)
+
+      case 'GO_TO_SETUP':
+        return this.validateGoToSetup(state)
+
+      case 'SET_CONFIG':
+        // Ensure value is a number (JSON deserialization can make it a string)
+        return this.validateSetConfig(state, move.data.field, Number(move.data.value))
+
+      default:
+        return {
+          valid: false,
+          error: `Unknown move type: ${(move as { type: string }).type}`,
+        }
+    }
+  }
+
+  private validateStartGame(
+    state: NumberGuesserState,
+    activePlayers: string[],
+    playerMetadata: Record<string, unknown>
+  ): ValidationResult {
+    if (!activePlayers || activePlayers.length < 2) {
+      return { valid: false, error: 'Need at least 2 players' }
+    }
+
+    const newState: NumberGuesserState = {
+      ...state,
+      gamePhase: 'choosing',
+      activePlayers,
+      playerMetadata: playerMetadata as typeof state.playerMetadata,
+      chooser: activePlayers[0],
+      currentGuesser: '',
+      secretNumber: null,
+      guesses: [],
+      roundNumber: 1,
+      scores: activePlayers.reduce((acc, p) => ({ ...acc, [p]: 0 }), {}),
+      gameStartTime: Date.now(),
+      gameEndTime: null,
+      winner: null,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateChooseNumber(
+    state: NumberGuesserState,
+    secretNumber: number,
+    playerId: string
+  ): ValidationResult {
+    if (state.gamePhase !== 'choosing') {
+      return { valid: false, error: 'Not in choosing phase' }
+    }
+
+    if (playerId !== state.chooser) {
+      return { valid: false, error: 'Not your turn to choose' }
+    }
+
+    if (
+      secretNumber < state.minNumber ||
+      secretNumber > state.maxNumber ||
+      !Number.isInteger(secretNumber)
+    ) {
+      return {
+        valid: false,
+        error: `Number must be between ${state.minNumber} and ${state.maxNumber}`,
+      }
+    }
+
+    // Debug logging
+    console.log('[NumberGuesser] Setting secret number:', {
+      secretNumber,
+      secretNumberType: typeof secretNumber,
+    })
+
+    // First guesser is the next player after chooser
+    const chooserIndex = state.activePlayers.indexOf(state.chooser)
+    const firstGuesserIndex = (chooserIndex + 1) % state.activePlayers.length
+    const firstGuesser = state.activePlayers[firstGuesserIndex]
+
+    const newState: NumberGuesserState = {
+      ...state,
+      gamePhase: 'guessing',
+      secretNumber,
+      currentGuesser: firstGuesser,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateMakeGuess(
+    state: NumberGuesserState,
+    guess: number,
+    playerId: string,
+    playerName: string
+  ): ValidationResult {
+    if (state.gamePhase !== 'guessing') {
+      return { valid: false, error: 'Not in guessing phase' }
+    }
+
+    if (playerId !== state.currentGuesser) {
+      return { valid: false, error: 'Not your turn to guess' }
+    }
+
+    if (guess < state.minNumber || guess > state.maxNumber || !Number.isInteger(guess)) {
+      return {
+        valid: false,
+        error: `Guess must be between ${state.minNumber} and ${state.maxNumber}`,
+      }
+    }
+
+    if (!state.secretNumber) {
+      return { valid: false, error: 'No secret number set' }
+    }
+
+    // Debug logging
+    console.log('[NumberGuesser] Validating guess:', {
+      guess,
+      guessType: typeof guess,
+      secretNumber: state.secretNumber,
+      secretNumberType: typeof state.secretNumber,
+    })
+
+    const distance = Math.abs(guess - state.secretNumber)
+
+    console.log('[NumberGuesser] Calculated distance:', distance)
+    const newGuess = {
+      playerId,
+      playerName,
+      guess,
+      distance,
+      timestamp: Date.now(),
+    }
+
+    const guesses = [...state.guesses, newGuess]
+
+    // Check if guess is correct
+    if (distance === 0) {
+      // Correct guess! Award point and end round
+      const newScores = {
+        ...state.scores,
+        [playerId]: (state.scores[playerId] || 0) + 1,
+      }
+
+      // Check if player won
+      const winner = newScores[playerId] >= state.roundsToWin ? playerId : null
+
+      const newState: NumberGuesserState = {
+        ...state,
+        guesses,
+        scores: newScores,
+        gamePhase: winner ? 'results' : 'guessing',
+        gameEndTime: winner ? Date.now() : null,
+        winner,
+      }
+
+      return { valid: true, newState }
+    }
+
+    // Incorrect guess, move to next guesser
+    const guesserIndex = state.activePlayers.indexOf(state.currentGuesser)
+    let nextGuesserIndex = (guesserIndex + 1) % state.activePlayers.length
+
+    // Skip the chooser
+    if (state.activePlayers[nextGuesserIndex] === state.chooser) {
+      nextGuesserIndex = (nextGuesserIndex + 1) % state.activePlayers.length
+    }
+
+    const newState: NumberGuesserState = {
+      ...state,
+      guesses,
+      currentGuesser: state.activePlayers[nextGuesserIndex],
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateNextRound(state: NumberGuesserState): ValidationResult {
+    if (state.gamePhase !== 'guessing') {
+      return { valid: false, error: 'Not in guessing phase' }
+    }
+
+    // Check if the round is complete (someone guessed correctly)
+    const roundComplete =
+      state.guesses.length > 0 && state.guesses[state.guesses.length - 1].distance === 0
+
+    if (!roundComplete) {
+      return { valid: false, error: 'Round not complete yet - no one has guessed the number' }
+    }
+
+    // Rotate chooser to next player
+    const chooserIndex = state.activePlayers.indexOf(state.chooser)
+    const nextChooserIndex = (chooserIndex + 1) % state.activePlayers.length
+    const nextChooser = state.activePlayers[nextChooserIndex]
+
+    const newState: NumberGuesserState = {
+      ...state,
+      gamePhase: 'choosing',
+      chooser: nextChooser,
+      currentGuesser: '',
+      secretNumber: null,
+      guesses: [],
+      roundNumber: state.roundNumber + 1,
+      winner: null,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateGoToSetup(state: NumberGuesserState): ValidationResult {
+    const newState: NumberGuesserState = {
+      ...state,
+      gamePhase: 'setup',
+      secretNumber: null,
+      chooser: '',
+      currentGuesser: '',
+      guesses: [],
+      roundNumber: 0,
+      scores: {},
+      activePlayers: [],
+      playerMetadata: {},
+      gameStartTime: null,
+      gameEndTime: null,
+      winner: null,
+    }
+
+    return { valid: true, newState }
+  }
+
+  private validateSetConfig(
+    state: NumberGuesserState,
+    field: 'minNumber' | 'maxNumber' | 'roundsToWin',
+    value: number
+  ): ValidationResult {
+    if (state.gamePhase !== 'setup') {
+      return { valid: false, error: 'Can only change config in setup' }
+    }
+
+    if (!Number.isInteger(value) || value < 1) {
+      return { valid: false, error: 'Value must be a positive integer' }
+    }
+
+    if (field === 'minNumber' && value >= state.maxNumber) {
+      return { valid: false, error: 'Min must be less than max' }
+    }
+
+    if (field === 'maxNumber' && value <= state.minNumber) {
+      return { valid: false, error: 'Max must be greater than min' }
+    }
+
+    const newState: NumberGuesserState = {
+      ...state,
+      [field]: value,
+    }
+
+    return { valid: true, newState }
+  }
+
+  isGameComplete(state: NumberGuesserState): boolean {
+    return state.gamePhase === 'results' && state.winner !== null
+  }
+
+  getInitialState(config: unknown): NumberGuesserState {
+    const { minNumber, maxNumber, roundsToWin } = config as NumberGuesserConfig
+
+    return {
+      minNumber: minNumber || 1,
+      maxNumber: maxNumber || 100,
+      roundsToWin: roundsToWin || 3,
+      gamePhase: 'setup',
+      activePlayers: [],
+      playerMetadata: {},
+      secretNumber: null,
+      chooser: '',
+      currentGuesser: '',
+      guesses: [],
+      roundNumber: 0,
+      scores: {},
+      gameStartTime: null,
+      gameEndTime: null,
+      winner: null,
+    }
+  }
+}
+
+export const numberGuesserValidator = new NumberGuesserValidator()

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

@@ -0,0 +1,211 @@
+/**
+ * Choosing Phase - Chooser picks a secret number
+ */
+
+'use client'
+
+import { useState } from 'react'
+import { useViewerId } from '@/lib/arcade/game-sdk'
+import { css } from '../../../../styled-system/css'
+import { useNumberGuesser } from '../Provider'
+
+export function ChoosingPhase() {
+  const { state, chooseNumber } = useNumberGuesser()
+  const { data: viewerId } = useViewerId()
+  const [inputValue, setInputValue] = useState('')
+
+  const chooserMetadata = state.playerMetadata[state.chooser]
+  const isChooser = chooserMetadata?.userId === viewerId
+
+  const handleSubmit = () => {
+    const number = Number.parseInt(inputValue, 10)
+    if (Number.isNaN(number)) return
+
+    chooseNumber(number)
+  }
+
+  return (
+    <div
+      className={css({
+        padding: '32px',
+        maxWidth: '600px',
+        margin: '0 auto',
+      })}
+    >
+      <div
+        className={css({
+          textAlign: 'center',
+          marginBottom: '32px',
+        })}
+      >
+        <div
+          className={css({
+            fontSize: '64px',
+            marginBottom: '16px',
+          })}
+        >
+          {chooserMetadata?.emoji || '🤔'}
+        </div>
+        <h2
+          className={css({
+            fontSize: '2xl',
+            fontWeight: 'bold',
+            marginBottom: '8px',
+          })}
+        >
+          {isChooser ? "You're choosing!" : `${chooserMetadata?.name || 'Someone'} is choosing...`}
+        </h2>
+        <p
+          className={css({
+            color: 'gray.600',
+          })}
+        >
+          Round {state.roundNumber}
+        </p>
+      </div>
+
+      {isChooser ? (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: 'orange.200',
+            borderRadius: '12px',
+            padding: '24px',
+          })}
+        >
+          <label
+            className={css({
+              display: 'block',
+              fontSize: 'md',
+              fontWeight: '600',
+              marginBottom: '12px',
+              textAlign: 'center',
+            })}
+          >
+            Choose a secret number ({state.minNumber} - {state.maxNumber})
+          </label>
+          <input
+            type="number"
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+            min={state.minNumber}
+            max={state.maxNumber}
+            placeholder={`${state.minNumber} - ${state.maxNumber}`}
+            className={css({
+              width: '100%',
+              padding: '16px',
+              border: '2px solid',
+              borderColor: 'gray.300',
+              borderRadius: '8px',
+              fontSize: 'xl',
+              textAlign: 'center',
+              marginBottom: '16px',
+            })}
+          />
+          <button
+            onClick={handleSubmit}
+            disabled={!inputValue}
+            className={css({
+              width: '100%',
+              padding: '16px',
+              background: 'linear-gradient(135deg, #fb923c, #f97316)',
+              color: 'white',
+              border: 'none',
+              borderRadius: '8px',
+              fontSize: 'lg',
+              fontWeight: 'bold',
+              cursor: 'pointer',
+              transition: 'all 0.2s',
+              _disabled: {
+                opacity: 0.5,
+                cursor: 'not-allowed',
+              },
+              _hover: {
+                transform: 'translateY(-2px)',
+              },
+            })}
+          >
+            Confirm Choice
+          </button>
+        </div>
+      ) : (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: 'orange.200',
+            borderRadius: '12px',
+            padding: '32px',
+            textAlign: 'center',
+          })}
+        >
+          <div
+            className={css({
+              fontSize: '48px',
+              marginBottom: '16px',
+            })}
+          >
+            ⏳
+          </div>
+          <p
+            className={css({
+              fontSize: 'lg',
+              color: 'gray.600',
+            })}
+          >
+            Waiting for {chooserMetadata?.name || 'player'} to choose a number...
+          </p>
+        </div>
+      )}
+
+      {/* Scoreboard */}
+      <div
+        className={css({
+          marginTop: '32px',
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '16px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'md',
+            fontWeight: 'bold',
+            marginBottom: '12px',
+            textAlign: 'center',
+          })}
+        >
+          Scores
+        </h3>
+        <div
+          className={css({
+            display: 'flex',
+            flexWrap: 'wrap',
+            gap: '8px',
+            justifyContent: 'center',
+          })}
+        >
+          {state.activePlayers.map((playerId) => {
+            const player = state.playerMetadata[playerId]
+            return (
+              <div
+                key={playerId}
+                className={css({
+                  padding: '8px 16px',
+                  background: 'gray.100',
+                  borderRadius: '8px',
+                  fontSize: 'sm',
+                })}
+              >
+                {player?.emoji} {player?.name}: {state.scores[playerId] || 0}
+              </div>
+            )
+          })}
+        </div>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Number Guesser Game Component
+ * Main component that switches between game phases
+ */
+
+'use client'
+
+import { useRouter } from 'next/navigation'
+import { PageWithNav } from '@/components/PageWithNav'
+import { useNumberGuesser } from '../Provider'
+import { ChoosingPhase } from './ChoosingPhase'
+import { GuessingPhase } from './GuessingPhase'
+import { ResultsPhase } from './ResultsPhase'
+import { SetupPhase } from './SetupPhase'
+
+export function GameComponent() {
+  const router = useRouter()
+  const { state, exitSession, goToSetup } = useNumberGuesser()
+
+  // Determine whose turn it is based on game phase
+  const currentPlayerId =
+    state.gamePhase === 'choosing'
+      ? state.chooser
+      : state.gamePhase === 'guessing'
+        ? state.currentGuesser
+        : undefined
+
+  return (
+    <PageWithNav
+      navTitle="Number Guesser"
+      navEmoji="🎯"
+      emphasizePlayerSelection={state.gamePhase === 'setup'}
+      currentPlayerId={currentPlayerId}
+      playerScores={state.scores}
+      onExitSession={() => {
+        exitSession?.()
+        router.push('/arcade')
+      }}
+      onNewGame={() => {
+        goToSetup?.()
+      }}
+    >
+      <div
+        style={{
+          flex: 1,
+          display: 'flex',
+          flexDirection: 'column',
+          overflow: 'auto',
+          minHeight: '100vh',
+          background: 'linear-gradient(135deg, #fff7ed, #ffedd5)',
+        }}
+      >
+        {state.gamePhase === 'setup' && <SetupPhase />}
+        {state.gamePhase === 'choosing' && <ChoosingPhase />}
+        {state.gamePhase === 'guessing' && <GuessingPhase />}
+        {state.gamePhase === 'results' && <ResultsPhase />}
+      </div>
+    </PageWithNav>
+  )
+}

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

@@ -0,0 +1,445 @@
+/**
+ * Guessing Phase - Players take turns guessing the secret number
+ */
+
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useViewerId } from '@/lib/arcade/game-sdk'
+import { css } from '../../../../styled-system/css'
+import { useNumberGuesser } from '../Provider'
+
+export function GuessingPhase() {
+  const { state, makeGuess, nextRound, lastError, clearError } = useNumberGuesser()
+  const { data: viewerId } = useViewerId()
+  const [inputValue, setInputValue] = useState('')
+
+  const currentGuesserMetadata = state.playerMetadata[state.currentGuesser]
+  const isCurrentGuesser = currentGuesserMetadata?.userId === viewerId
+
+  // Check if someone just won the round
+  const lastGuess = state.guesses[state.guesses.length - 1]
+  const roundJustEnded = lastGuess?.distance === 0
+
+  // Auto-clear error after 5 seconds
+  useEffect(() => {
+    if (lastError) {
+      const timeout = setTimeout(() => clearError(), 5000)
+      return () => clearTimeout(timeout)
+    }
+  }, [lastError, clearError])
+
+  const handleSubmit = () => {
+    const guess = Number.parseInt(inputValue, 10)
+    if (Number.isNaN(guess)) return
+
+    makeGuess(guess)
+    setInputValue('')
+  }
+
+  const getHotColdMessage = (distance: number) => {
+    if (distance === 0) return '🎯 Correct!'
+    if (distance <= 5) return '🔥 Very Hot!'
+    if (distance <= 10) return '🌡️ Hot'
+    if (distance <= 20) return '😊 Warm'
+    if (distance <= 30) return '😐 Cool'
+    if (distance <= 50) return '❄️ Cold'
+    return '🧊 Very Cold'
+  }
+
+  return (
+    <div
+      className={css({
+        padding: '32px',
+        maxWidth: '800px',
+        margin: '0 auto',
+      })}
+    >
+      {/* Header */}
+      <div
+        className={css({
+          textAlign: 'center',
+          marginBottom: '32px',
+        })}
+      >
+        <div
+          className={css({
+            fontSize: '64px',
+            marginBottom: '16px',
+          })}
+        >
+          {roundJustEnded ? '🎉' : currentGuesserMetadata?.emoji || '🤔'}
+        </div>
+        <h2
+          className={css({
+            fontSize: '2xl',
+            fontWeight: 'bold',
+            marginBottom: '8px',
+          })}
+        >
+          {roundJustEnded
+            ? `${lastGuess.playerName} guessed it!`
+            : isCurrentGuesser
+              ? 'Your turn to guess!'
+              : `${currentGuesserMetadata?.name || 'Someone'} is guessing...`}
+        </h2>
+        <p
+          className={css({
+            color: 'gray.600',
+          })}
+        >
+          Round {state.roundNumber} • Range: {state.minNumber} - {state.maxNumber}
+        </p>
+      </div>
+
+      {/* Error Banner */}
+      {lastError && (
+        <div
+          className={css({
+            background: 'linear-gradient(135deg, #fef2f2, #fee2e2)',
+            border: '2px solid',
+            borderColor: 'red.300',
+            borderRadius: '12px',
+            padding: '16px 20px',
+            marginBottom: '24px',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            animation: 'slideIn 0.3s ease',
+          })}
+        >
+          <div
+            className={css({
+              display: 'flex',
+              alignItems: 'center',
+              gap: '12px',
+            })}
+          >
+            <div
+              className={css({
+                fontSize: '24px',
+              })}
+            >
+              ⚠️
+            </div>
+            <div>
+              <div
+                className={css({
+                  fontSize: 'md',
+                  fontWeight: 'bold',
+                  color: 'red.700',
+                  marginBottom: '4px',
+                })}
+              >
+                Move Rejected
+              </div>
+              <div
+                className={css({
+                  fontSize: 'sm',
+                  color: 'red.600',
+                })}
+              >
+                {lastError}
+              </div>
+            </div>
+          </div>
+          <button
+            type="button"
+            onClick={clearError}
+            className={css({
+              padding: '8px 12px',
+              background: 'white',
+              border: '1px solid',
+              borderColor: 'red.300',
+              borderRadius: '6px',
+              fontSize: 'sm',
+              fontWeight: '600',
+              color: 'red.700',
+              cursor: 'pointer',
+              transition: 'all 0.2s',
+              _hover: {
+                background: 'red.50',
+              },
+            })}
+          >
+            Dismiss
+          </button>
+        </div>
+      )}
+
+      {/* Round ended - show next round button */}
+      {roundJustEnded && (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: 'green.200',
+            borderRadius: '12px',
+            padding: '24px',
+            marginBottom: '24px',
+            textAlign: 'center',
+          })}
+        >
+          <div
+            className={css({
+              fontSize: '48px',
+              marginBottom: '16px',
+            })}
+          >
+            🎯
+          </div>
+          <p
+            className={css({
+              fontSize: 'lg',
+              marginBottom: '16px',
+            })}
+          >
+            The secret number was <strong>{state.secretNumber}</strong>!
+          </p>
+          <button
+            type="button"
+            onClick={nextRound}
+            className={css({
+              padding: '12px 24px',
+              background: 'linear-gradient(135deg, #fb923c, #f97316)',
+              color: 'white',
+              border: 'none',
+              borderRadius: '8px',
+              fontSize: 'md',
+              fontWeight: 'bold',
+              cursor: 'pointer',
+              transition: 'all 0.2s',
+              _hover: {
+                transform: 'translateY(-2px)',
+              },
+            })}
+          >
+            Next Round
+          </button>
+        </div>
+      )}
+
+      {/* Guessing input (only if round not ended) */}
+      {!roundJustEnded && (
+        <div
+          className={css({
+            background: 'white',
+            border: '2px solid',
+            borderColor: 'orange.200',
+            borderRadius: '12px',
+            padding: '24px',
+            marginBottom: '24px',
+          })}
+        >
+          {isCurrentGuesser ? (
+            <>
+              <label
+                className={css({
+                  display: 'block',
+                  fontSize: 'md',
+                  fontWeight: '600',
+                  marginBottom: '12px',
+                  textAlign: 'center',
+                })}
+              >
+                Make your guess ({state.minNumber} - {state.maxNumber})
+              </label>
+              <input
+                type="number"
+                value={inputValue}
+                onChange={(e) => setInputValue(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' && inputValue) {
+                    handleSubmit()
+                  }
+                }}
+                min={state.minNumber}
+                max={state.maxNumber}
+                placeholder={`${state.minNumber} - ${state.maxNumber}`}
+                className={css({
+                  width: '100%',
+                  padding: '16px',
+                  border: '2px solid',
+                  borderColor: 'gray.300',
+                  borderRadius: '8px',
+                  fontSize: 'xl',
+                  textAlign: 'center',
+                  marginBottom: '16px',
+                })}
+              />
+              <button
+                type="button"
+                onClick={handleSubmit}
+                disabled={!inputValue}
+                className={css({
+                  width: '100%',
+                  padding: '16px',
+                  background: 'linear-gradient(135deg, #fb923c, #f97316)',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: '8px',
+                  fontSize: 'lg',
+                  fontWeight: 'bold',
+                  cursor: 'pointer',
+                  transition: 'all 0.2s',
+                  _disabled: {
+                    opacity: 0.5,
+                    cursor: 'not-allowed',
+                  },
+                  _hover: {
+                    transform: 'translateY(-2px)',
+                  },
+                })}
+              >
+                Submit Guess
+              </button>
+            </>
+          ) : (
+            <div
+              className={css({
+                textAlign: 'center',
+                padding: '16px',
+              })}
+            >
+              <div
+                className={css({
+                  fontSize: '48px',
+                  marginBottom: '16px',
+                })}
+              >
+                ⏳
+              </div>
+              <p
+                className={css({
+                  fontSize: 'lg',
+                  color: 'gray.600',
+                })}
+              >
+                Waiting for {currentGuesserMetadata?.name || 'player'} to guess...
+              </p>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Guess history */}
+      {state.guesses.length > 0 && (
+        <div
+          className={css({
+            background: 'white',
+            border: '1px solid',
+            borderColor: 'gray.200',
+            borderRadius: '12px',
+            padding: '16px',
+            marginBottom: '24px',
+          })}
+        >
+          <h3
+            className={css({
+              fontSize: 'md',
+              fontWeight: 'bold',
+              marginBottom: '12px',
+            })}
+          >
+            Guess History
+          </h3>
+          <div
+            className={css({
+              display: 'flex',
+              flexDirection: 'column',
+              gap: '8px',
+            })}
+          >
+            {state.guesses.map((guess, index) => {
+              const player = state.playerMetadata[guess.playerId]
+              return (
+                <div
+                  key={index}
+                  className={css({
+                    padding: '12px',
+                    background: guess.distance === 0 ? 'green.50' : 'gray.50',
+                    borderRadius: '8px',
+                    display: 'flex',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                  })}
+                >
+                  <div
+                    className={css({
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: '8px',
+                    })}
+                  >
+                    <span>{player?.emoji || '🎮'}</span>
+                    <span className={css({ fontWeight: '600' })}>{guess.playerName}</span>
+                    <span className={css({ color: 'gray.600' })}>guessed</span>
+                    <span className={css({ fontWeight: 'bold', fontSize: 'lg' })}>
+                      {guess.guess}
+                    </span>
+                  </div>
+                  <div
+                    className={css({
+                      fontWeight: 'bold',
+                      color: guess.distance === 0 ? 'green.700' : 'orange.700',
+                    })}
+                  >
+                    {getHotColdMessage(guess.distance)}
+                  </div>
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+
+      {/* Scoreboard */}
+      <div
+        className={css({
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '16px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'md',
+            fontWeight: 'bold',
+            marginBottom: '12px',
+            textAlign: 'center',
+          })}
+        >
+          Scores (First to {state.roundsToWin} wins!)
+        </h3>
+        <div
+          className={css({
+            display: 'flex',
+            flexWrap: 'wrap',
+            gap: '8px',
+            justifyContent: 'center',
+          })}
+        >
+          {state.activePlayers.map((playerId) => {
+            const player = state.playerMetadata[playerId]
+            const score = state.scores[playerId] || 0
+            return (
+              <div
+                key={playerId}
+                className={css({
+                  padding: '8px 16px',
+                  background: 'gray.100',
+                  borderRadius: '8px',
+                  fontSize: 'sm',
+                })}
+              >
+                {player?.emoji} {player?.name}: {score}
+              </div>
+            )
+          })}
+        </div>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,208 @@
+/**
+ * Results Phase - Shows winner and final scores
+ */
+
+'use client'
+
+import { css } from '../../../../styled-system/css'
+import { useNumberGuesser } from '../Provider'
+
+export function ResultsPhase() {
+  const { state, goToSetup } = useNumberGuesser()
+
+  const winnerMetadata = state.winner ? state.playerMetadata[state.winner] : null
+  const winnerScore = state.winner ? state.scores[state.winner] : 0
+
+  // Sort players by score
+  const sortedPlayers = [...state.activePlayers].sort((a, b) => {
+    const scoreA = state.scores[a] || 0
+    const scoreB = state.scores[b] || 0
+    return scoreB - scoreA
+  })
+
+  return (
+    <div
+      className={css({
+        padding: '32px',
+        maxWidth: '600px',
+        margin: '0 auto',
+      })}
+    >
+      {/* Winner Celebration */}
+      <div
+        className={css({
+          textAlign: 'center',
+          marginBottom: '32px',
+        })}
+      >
+        <div
+          className={css({
+            fontSize: '96px',
+            marginBottom: '16px',
+            animation: 'bounce 1s ease-in-out infinite',
+          })}
+        >
+          {winnerMetadata?.emoji || '🏆'}
+        </div>
+        <h1
+          className={css({
+            fontSize: '3xl',
+            fontWeight: 'bold',
+            marginBottom: '8px',
+            background: 'linear-gradient(135deg, #fb923c, #f97316)',
+            backgroundClip: 'text',
+            color: 'transparent',
+          })}
+        >
+          {winnerMetadata?.name || 'Someone'} Wins!
+        </h1>
+        <p
+          className={css({
+            fontSize: 'xl',
+            color: 'gray.600',
+          })}
+        >
+          with {winnerScore} {winnerScore === 1 ? 'round' : 'rounds'} won
+        </p>
+      </div>
+
+      {/* Final Standings */}
+      <div
+        className={css({
+          background: 'white',
+          border: '2px solid',
+          borderColor: 'orange.200',
+          borderRadius: '12px',
+          padding: '24px',
+          marginBottom: '24px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'lg',
+            fontWeight: 'bold',
+            marginBottom: '16px',
+            textAlign: 'center',
+          })}
+        >
+          Final Standings
+        </h3>
+        <div
+          className={css({
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '12px',
+          })}
+        >
+          {sortedPlayers.map((playerId, index) => {
+            const player = state.playerMetadata[playerId]
+            const score = state.scores[playerId] || 0
+            const isWinner = playerId === state.winner
+
+            return (
+              <div
+                key={playerId}
+                className={css({
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'space-between',
+                  padding: '16px',
+                  background: isWinner ? 'linear-gradient(135deg, #fed7aa, #fdba74)' : 'gray.100',
+                  borderRadius: '8px',
+                  border: isWinner ? '2px solid' : 'none',
+                  borderColor: isWinner ? 'orange.300' : undefined,
+                })}
+              >
+                <div
+                  className={css({
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: '12px',
+                  })}
+                >
+                  <span
+                    className={css({
+                      fontSize: '2xl',
+                      fontWeight: 'bold',
+                      color: 'gray.400',
+                      width: '32px',
+                      textAlign: 'center',
+                    })}
+                  >
+                    {index + 1}
+                  </span>
+                  <span className={css({ fontSize: '32px' })}>{player?.emoji || '🎮'}</span>
+                  <span className={css({ fontSize: 'lg', fontWeight: '600' })}>
+                    {player?.name || 'Unknown'}
+                  </span>
+                </div>
+                <div
+                  className={css({
+                    fontSize: '2xl',
+                    fontWeight: 'bold',
+                    color: isWinner ? 'orange.700' : 'gray.700',
+                  })}
+                >
+                  {score} {isWinner && '🏆'}
+                </div>
+              </div>
+            )
+          })}
+        </div>
+      </div>
+
+      {/* Game Stats */}
+      <div
+        className={css({
+          background: 'white',
+          border: '1px solid',
+          borderColor: 'gray.200',
+          borderRadius: '12px',
+          padding: '16px',
+          marginBottom: '24px',
+          textAlign: 'center',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'md',
+            fontWeight: 'bold',
+            marginBottom: '8px',
+          })}
+        >
+          Game Stats
+        </h3>
+        <p className={css({ color: 'gray.600', fontSize: 'sm' })}>
+          {state.roundNumber} {state.roundNumber === 1 ? 'round' : 'rounds'} played
+        </p>
+        <p className={css({ color: 'gray.600', fontSize: 'sm' })}>
+          {state.guesses.length} {state.guesses.length === 1 ? 'guess' : 'guesses'} made
+        </p>
+      </div>
+
+      {/* Actions */}
+      <button
+        type="button"
+        onClick={goToSetup}
+        className={css({
+          width: '100%',
+          padding: '16px',
+          background: 'linear-gradient(135deg, #fb923c, #f97316)',
+          color: 'white',
+          border: 'none',
+          borderRadius: '12px',
+          fontSize: 'lg',
+          fontWeight: 'bold',
+          cursor: 'pointer',
+          transition: 'all 0.2s',
+          _hover: {
+            transform: 'translateY(-2px)',
+            boxShadow: '0 8px 16px rgba(249, 115, 22, 0.3)',
+          },
+        })}
+      >
+        Play Again
+      </button>
+    </div>
+  )
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Setup Phase - Game configuration
+ */
+
+'use client'
+
+import { css } from '../../../../styled-system/css'
+import { useNumberGuesser } from '../Provider'
+
+export function SetupPhase() {
+  const { state, startGame, setConfig } = useNumberGuesser()
+
+  return (
+    <div
+      className={css({
+        padding: '32px',
+        maxWidth: '600px',
+        margin: '0 auto',
+      })}
+    >
+      <h2
+        className={css({
+          fontSize: '2xl',
+          fontWeight: 'bold',
+          marginBottom: '24px',
+          textAlign: 'center',
+        })}
+      >
+        🎯 Number Guesser Setup
+      </h2>
+
+      <div
+        className={css({
+          background: 'white',
+          border: '2px solid',
+          borderColor: 'orange.200',
+          borderRadius: '12px',
+          padding: '24px',
+          marginBottom: '24px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'lg',
+            fontWeight: 'bold',
+            marginBottom: '16px',
+          })}
+        >
+          Game Rules
+        </h3>
+        <ul
+          className={css({
+            listStyle: 'disc',
+            paddingLeft: '24px',
+            lineHeight: '1.6',
+            color: 'gray.700',
+          })}
+        >
+          <li>One player chooses a secret number</li>
+          <li>Other players take turns guessing</li>
+          <li>Get feedback on how close your guess is</li>
+          <li>First to guess correctly wins the round!</li>
+          <li>First to {state.roundsToWin} rounds wins the game!</li>
+        </ul>
+      </div>
+
+      <div
+        className={css({
+          background: 'white',
+          border: '2px solid',
+          borderColor: 'orange.200',
+          borderRadius: '12px',
+          padding: '24px',
+          marginBottom: '24px',
+        })}
+      >
+        <h3
+          className={css({
+            fontSize: 'lg',
+            fontWeight: 'bold',
+            marginBottom: '16px',
+          })}
+        >
+          Configuration
+        </h3>
+
+        <div
+          className={css({
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '16px',
+          })}
+        >
+          <div>
+            <label
+              className={css({
+                display: 'block',
+                fontSize: 'sm',
+                fontWeight: '600',
+                marginBottom: '4px',
+              })}
+            >
+              Minimum Number
+            </label>
+            <input
+              type="number"
+              value={state.minNumber ?? 1}
+              onChange={(e) => setConfig('minNumber', Number.parseInt(e.target.value, 10))}
+              className={css({
+                width: '100%',
+                padding: '8px 12px',
+                border: '1px solid',
+                borderColor: 'gray.300',
+                borderRadius: '6px',
+                fontSize: 'md',
+              })}
+            />
+          </div>
+
+          <div>
+            <label
+              className={css({
+                display: 'block',
+                fontSize: 'sm',
+                fontWeight: '600',
+                marginBottom: '4px',
+              })}
+            >
+              Maximum Number
+            </label>
+            <input
+              type="number"
+              value={state.maxNumber ?? 100}
+              onChange={(e) => setConfig('maxNumber', Number.parseInt(e.target.value, 10))}
+              className={css({
+                width: '100%',
+                padding: '8px 12px',
+                border: '1px solid',
+                borderColor: 'gray.300',
+                borderRadius: '6px',
+                fontSize: 'md',
+              })}
+            />
+          </div>
+
+          <div>
+            <label
+              className={css({
+                display: 'block',
+                fontSize: 'sm',
+                fontWeight: '600',
+                marginBottom: '4px',
+              })}
+            >
+              Rounds to Win
+            </label>
+            <input
+              type="number"
+              value={state.roundsToWin ?? 3}
+              onChange={(e) => setConfig('roundsToWin', Number.parseInt(e.target.value, 10))}
+              className={css({
+                width: '100%',
+                padding: '8px 12px',
+                border: '1px solid',
+                borderColor: 'gray.300',
+                borderRadius: '6px',
+                fontSize: 'md',
+              })}
+            />
+          </div>
+        </div>
+      </div>
+
+      <button
+        onClick={startGame}
+        className={css({
+          width: '100%',
+          padding: '16px',
+          background: 'linear-gradient(135deg, #fb923c, #f97316)',
+          color: 'white',
+          border: 'none',
+          borderRadius: '12px',
+          fontSize: 'lg',
+          fontWeight: 'bold',
+          cursor: 'pointer',
+          transition: 'all 0.2s',
+          _hover: {
+            transform: 'translateY(-2px)',
+            boxShadow: '0 8px 16px rgba(249, 115, 22, 0.3)',
+          },
+        })}
+      >
+        Start Game
+      </button>
+    </div>
+  )
+}

apps/web/src/arcade-games/number-guesser/game.yaml

@@ -0,0 +1,15 @@
+name: number-guesser
+displayName: Number Guesser
+icon: 🎯
+description: Classic turn-based number guessing game
+longDescription: One player thinks of a number, others take turns guessing. Get hot/cold feedback as you try to find the secret number. Perfect for testing your deduction skills!
+maxPlayers: 4
+difficulty: Beginner
+chips:
+  - 👥 Multiplayer
+  - 🎲 Turn-Based
+  - 🧠 Logic Puzzle
+color: orange
+gradient: linear-gradient(135deg, #fed7aa, #fdba74)
+borderColor: orange.200
+available: true

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

@@ -0,0 +1,48 @@
+/**
+ * Number Guesser Game Definition
+ * Exports the complete game using the Arcade SDK
+ */
+
+import { defineGame } from '@/lib/arcade/game-sdk'
+import type { GameManifest } from '@/lib/arcade/game-sdk'
+import { GameComponent } from './components/GameComponent'
+import { NumberGuesserProvider } from './Provider'
+import type { NumberGuesserConfig, NumberGuesserMove, NumberGuesserState } from './types'
+import { numberGuesserValidator } from './Validator'
+
+// Game manifest (matches game.yaml)
+const manifest: GameManifest = {
+  name: 'number-guesser',
+  displayName: 'Number Guesser',
+  icon: '🎯',
+  description: 'Classic turn-based number guessing game',
+  longDescription:
+    'One player thinks of a number, others take turns guessing. Get hot/cold feedback to narrow down your guesses. First to guess wins the round!',
+  maxPlayers: 4,
+  difficulty: 'Beginner',
+  chips: ['👥 Multiplayer', '🎲 Turn-Based', '🧠 Logic Puzzle'],
+  color: 'orange',
+  gradient: 'linear-gradient(135deg, #fed7aa, #fdba74)',
+  borderColor: 'orange.200',
+  available: true,
+}
+
+// Default configuration
+const defaultConfig: NumberGuesserConfig = {
+  minNumber: 1,
+  maxNumber: 100,
+  roundsToWin: 3,
+}
+
+// Export game definition
+export const numberGuesserGame = defineGame<
+  NumberGuesserConfig,
+  NumberGuesserState,
+  NumberGuesserMove
+>({
+  manifest,
+  Provider: NumberGuesserProvider,
+  GameComponent,
+  validator: numberGuesserValidator,
+  defaultConfig,
+})

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

@@ -0,0 +1,116 @@
+/**
+ * Type definitions for Number Guesser game
+ */
+
+import type { GameMove } from '@/lib/arcade/game-sdk'
+
+/**
+ * Game configuration
+ */
+export type NumberGuesserConfig = {
+  minNumber: number
+  maxNumber: number
+  roundsToWin: number
+}
+
+/**
+ * A single guess attempt
+ */
+export interface Guess {
+  playerId: string
+  playerName: string
+  guess: number
+  distance: number // How far from the secret number
+  timestamp: number
+}
+
+/**
+ * Game phases
+ */
+export type GamePhase = 'setup' | 'choosing' | 'guessing' | 'results'
+
+/**
+ * Game state
+ */
+export type NumberGuesserState = {
+  // Configuration
+  minNumber: number
+  maxNumber: number
+  roundsToWin: number
+
+  // Game phase
+  gamePhase: GamePhase
+
+  // Players
+  activePlayers: string[]
+  playerMetadata: Record<string, { name: string; emoji: string; color: string; userId: string }>
+
+  // Current round
+  secretNumber: number | null
+  chooser: string // Player ID who chose the number
+  currentGuesser: string // Player ID whose turn it is to guess
+
+  // Round history
+  guesses: Guess[]
+  roundNumber: number
+
+  // Scores
+  scores: Record<string, number>
+
+  // Game state
+  gameStartTime: number | null
+  gameEndTime: number | null
+  winner: string | null
+}
+
+/**
+ * Game moves
+ */
+export interface StartGameMove extends GameMove {
+  type: 'START_GAME'
+  data: {
+    activePlayers: string[]
+    playerMetadata: Record<string, unknown>
+  }
+}
+
+export interface ChooseNumberMove extends GameMove {
+  type: 'CHOOSE_NUMBER'
+  data: {
+    secretNumber: number
+  }
+}
+
+export interface MakeGuessMove extends GameMove {
+  type: 'MAKE_GUESS'
+  data: {
+    guess: number
+    playerName: string
+  }
+}
+
+export interface NextRoundMove extends GameMove {
+  type: 'NEXT_ROUND'
+  data: Record<string, never>
+}
+
+export interface GoToSetupMove extends GameMove {
+  type: 'GO_TO_SETUP'
+  data: Record<string, never>
+}
+
+export interface SetConfigMove extends GameMove {
+  type: 'SET_CONFIG'
+  data: {
+    field: 'minNumber' | 'maxNumber' | 'roundsToWin'
+    value: number
+  }
+}
+
+export type NumberGuesserMove =
+  | StartGameMove
+  | ChooseNumberMove
+  | MakeGuessMove
+  | NextRoundMove
+  | GoToSetupMove
+  | SetConfigMove

apps/web/src/components/ClientProviders.tsx

@@ -3,6 +3,7 @@
 import { AbacusDisplayProvider } from '@soroban/abacus-react'
 import { QueryClientProvider } from '@tanstack/react-query'
 import { type ReactNode, useState } from 'react'
+import { ToastProvider } from '@/components/common/ToastContext'
 import { FullscreenProvider } from '@/contexts/FullscreenContext'
 import { GameModeProvider } from '@/contexts/GameModeContext'
 import { UserProfileProvider } from '@/contexts/UserProfileContext'
@@ -20,17 +21,19 @@ export function ClientProviders({ children }: ClientProvidersProps) {
 
   return (
     <QueryClientProvider client={queryClient}>
-      <AbacusDisplayProvider>
-        <AbacusSettingsSync />
-        <UserProfileProvider>
-          <GameModeProvider>
-            <FullscreenProvider>
-              {children}
-              <DeploymentInfo />
-            </FullscreenProvider>
-          </GameModeProvider>
-        </UserProfileProvider>
-      </AbacusDisplayProvider>
+      <ToastProvider>
+        <AbacusDisplayProvider>
+          <AbacusSettingsSync />
+          <UserProfileProvider>
+            <GameModeProvider>
+              <FullscreenProvider>
+                {children}
+                <DeploymentInfo />
+              </FullscreenProvider>
+            </GameModeProvider>
+          </UserProfileProvider>
+        </AbacusDisplayProvider>
+      </ToastProvider>
     </QueryClientProvider>
   )
 }

apps/web/src/components/GameCard.tsx

@@ -23,10 +23,23 @@ export function GameCard({ gameType, config, variant = 'detailed', className }:
   }
 
   const handleGameClick = () => {
+    console.log(`[GameCard] Clicked on ${config.name}:`, {
+      activePlayerCount,
+      maxPlayers: config.maxPlayers,
+      isGameAvailable: isGameAvailable(),
+      configAvailable: config.available,
+      willNavigate: isGameAvailable() && config.available !== false,
+      url: config.url,
+    })
+
     if (isGameAvailable() && config.available !== false) {
       console.log('🔄 GameCard: Navigating with Next.js router (no page reload)')
       // Use Next.js router for client-side navigation - this preserves fullscreen!
       router.push(config.url)
+    } else {
+      console.warn('❌ GameCard: Navigation blocked', {
+        reason: !isGameAvailable() ? 'Player count mismatch' : 'Game not available',
+      })
     }
   }
 

apps/web/src/components/GameSelector.tsx

@@ -1,21 +1,23 @@
 'use client'
 
+import { useMemo } from 'react'
 import { css } from '../../styled-system/css'
 import { useGameMode } from '../contexts/GameModeContext'
+import { getAllGames } from '../lib/arcade/game-registry'
 import { GameCard } from './GameCard'
 
 // Game configuration defining player limits
 export const GAMES_CONFIG = {
-  'memory-lightning': {
+  'memory-quiz': {
     name: 'Memory Lightning',
     fullName: 'Memory Lightning ⚡',
-    maxPlayers: 1,
+    maxPlayers: 4,
     description: 'Test your memory speed with rapid-fire abacus calculations',
     longDescription:
-      'Challenge yourself with lightning-fast memory tests. Perfect your mental math skills with this intense solo experience.',
+      'Challenge yourself or compete with friends in lightning-fast memory tests. Work together cooperatively or compete for the highest score!',
     url: '/arcade/memory-quiz',
     icon: '⚡',
-    chips: ['⭐ Beginner Friendly', '🔥 Speed Challenge', '🧮 Abacus Focus'],
+    chips: ['👥 Multiplayer', '🔥 Speed Challenge', '🧮 Abacus Focus'],
     color: 'green',
     gradient: 'linear-gradient(135deg, #dcfce7, #bbf7d0)',
     borderColor: 'green.200',
@@ -70,7 +72,39 @@ export const GAMES_CONFIG = {
   },
 } as const
 
-export type GameType = keyof typeof GAMES_CONFIG
+export type GameType = keyof typeof GAMES_CONFIG | string
+
+/**
+ * Get all games from both legacy config and new registry
+ */
+function getAllGameConfigs() {
+  const legacyGames = Object.entries(GAMES_CONFIG).map(([gameType, config]) => ({
+    gameType,
+    config,
+  }))
+
+  // Get games from registry and transform to legacy format
+  const registryGames = getAllGames().map((gameDef) => ({
+    gameType: gameDef.manifest.name,
+    config: {
+      name: gameDef.manifest.displayName,
+      fullName: gameDef.manifest.displayName,
+      maxPlayers: gameDef.manifest.maxPlayers,
+      description: gameDef.manifest.description,
+      longDescription: gameDef.manifest.longDescription,
+      url: `/arcade/room?game=${gameDef.manifest.name}`, // Registry games load in room
+      icon: gameDef.manifest.icon,
+      chips: gameDef.manifest.chips,
+      color: gameDef.manifest.color,
+      gradient: gameDef.manifest.gradient,
+      borderColor: gameDef.manifest.borderColor,
+      difficulty: gameDef.manifest.difficulty,
+      available: gameDef.manifest.available,
+    },
+  }))
+
+  return [...legacyGames, ...registryGames]
+}
 
 interface GameSelectorProps {
   variant?: 'compact' | 'detailed'
@@ -87,17 +121,17 @@ export function GameSelector({
 }: GameSelectorProps) {
   const { activePlayerCount } = useGameMode()
 
+  // Memoize the combined games list
+  const allGames = useMemo(() => getAllGameConfigs(), [])
+
   return (
     <div
-      className={css(
-        {
-          height: '100%',
-          display: 'flex',
-          flexDirection: 'column',
-          overflow: 'hidden',
-        },
-        className
-      )}
+      className={`${css({
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        overflow: 'hidden',
+      })} ${className || ''}`}
     >
       {showHeader && (
         <h3
@@ -125,7 +159,7 @@ export function GameSelector({
           overflow: 'hidden',
         })}
       >
-        {Object.entries(GAMES_CONFIG).map(([gameType, config]) => (
+        {allGames.map(({ gameType, config }) => (
           <GameCard
             key={gameType}
             gameType={gameType as GameType}

apps/web/src/components/PageWithNav.tsx

@@ -13,7 +13,7 @@ interface PageWithNavProps {
   navTitle?: string
   navEmoji?: string
   gameName?: 'matching' | 'memory-quiz' | 'complement-race' // Internal game name for API
-  emphasizeGameContext?: boolean
+  emphasizePlayerSelection?: boolean
   onExitSession?: () => void
   onSetup?: () => void
   onNewGame?: () => void
@@ -28,7 +28,7 @@ export function PageWithNav({
   navTitle,
   navEmoji,
   gameName,
-  emphasizeGameContext = false,
+  emphasizePlayerSelection = false,
   onExitSession,
   onSetup,
   onNewGame,
@@ -103,7 +103,7 @@ export function PageWithNav({
             ? 'tournament'
             : 'none'
 
-  const shouldEmphasize = emphasizeGameContext && mounted
+  const shouldEmphasize = emphasizePlayerSelection && mounted
   const showFullscreenSelection = shouldEmphasize && activePlayerCount === 0
 
   // Compute arcade session info for display

apps/web/src/components/common/ToastContext.tsx

@@ -0,0 +1,235 @@
+'use client'
+
+import * as Toast from '@radix-ui/react-toast'
+import { createContext, useCallback, useContext, useState, type ReactNode } from 'react'
+
+export interface ToastMessage {
+  id: string
+  type: 'success' | 'error' | 'info'
+  title: string
+  description?: string
+  duration?: number
+}
+
+interface ToastContextValue {
+  showToast: (toast: Omit<ToastMessage, 'id'>) => void
+  showSuccess: (title: string, description?: string) => void
+  showError: (title: string, description?: string) => void
+  showInfo: (title: string, description?: string) => void
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null)
+
+export function useToast() {
+  const context = useContext(ToastContext)
+  if (!context) {
+    throw new Error('useToast must be used within ToastProvider')
+  }
+  return context
+}
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<ToastMessage[]>([])
+
+  const showToast = useCallback((toast: Omit<ToastMessage, 'id'>) => {
+    const id = Math.random().toString(36).substring(7)
+    setToasts((prev) => [...prev, { ...toast, id }])
+  }, [])
+
+  const showSuccess = useCallback(
+    (title: string, description?: string) => {
+      showToast({ type: 'success', title, description, duration: 5000 })
+    },
+    [showToast]
+  )
+
+  const showError = useCallback(
+    (title: string, description?: string) => {
+      showToast({ type: 'error', title, description, duration: 7000 })
+    },
+    [showToast]
+  )
+
+  const showInfo = useCallback(
+    (title: string, description?: string) => {
+      showToast({ type: 'info', title, description, duration: 5000 })
+    },
+    [showToast]
+  )
+
+  const removeToast = useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id))
+  }, [])
+
+  const getToastStyles = (type: ToastMessage['type']) => {
+    switch (type) {
+      case 'success':
+        return {
+          background: 'linear-gradient(135deg, rgba(34, 197, 94, 0.97), rgba(22, 163, 74, 0.97))',
+          border: '2px solid rgba(34, 197, 94, 0.6)',
+          icon: '✓',
+        }
+      case 'error':
+        return {
+          background: 'linear-gradient(135deg, rgba(239, 68, 68, 0.97), rgba(220, 38, 38, 0.97))',
+          border: '2px solid rgba(239, 68, 68, 0.6)',
+          icon: '⚠',
+        }
+      case 'info':
+        return {
+          background: 'linear-gradient(135deg, rgba(59, 130, 246, 0.97), rgba(37, 99, 235, 0.97))',
+          border: '2px solid rgba(59, 130, 246, 0.6)',
+          icon: 'ℹ',
+        }
+    }
+  }
+
+  return (
+    <ToastContext.Provider value={{ showToast, showSuccess, showError, showInfo }}>
+      {children}
+      <Toast.Provider swipeDirection="right">
+        {toasts.map((toast) => {
+          const styles = getToastStyles(toast.type)
+          return (
+            <Toast.Root
+              key={toast.id}
+              open={true}
+              onOpenChange={(open) => {
+                if (!open) {
+                  removeToast(toast.id)
+                }
+              }}
+              duration={toast.duration}
+              style={{
+                background: styles.background,
+                border: styles.border,
+                borderRadius: '12px',
+                padding: '16px',
+                boxShadow: '0 8px 24px rgba(0, 0, 0, 0.4)',
+                display: 'flex',
+                gap: '12px',
+                alignItems: 'flex-start',
+                minWidth: '300px',
+                maxWidth: '450px',
+                transition: 'all 0.2s ease',
+              }}
+            >
+              <div style={{ fontSize: '20px', flexShrink: 0 }}>{styles.icon}</div>
+              <div style={{ flex: 1 }}>
+                <Toast.Title
+                  style={{
+                    fontSize: '14px',
+                    fontWeight: 'bold',
+                    color: 'white',
+                    marginBottom: toast.description ? '4px' : 0,
+                  }}
+                >
+                  {toast.title}
+                </Toast.Title>
+                {toast.description && (
+                  <Toast.Description
+                    style={{
+                      fontSize: '13px',
+                      color: 'rgba(255, 255, 255, 0.9)',
+                    }}
+                  >
+                    {toast.description}
+                  </Toast.Description>
+                )}
+              </div>
+              <Toast.Close
+                style={{
+                  background: 'rgba(255, 255, 255, 0.2)',
+                  border: 'none',
+                  borderRadius: '50%',
+                  width: '24px',
+                  height: '24px',
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  cursor: 'pointer',
+                  color: 'white',
+                  fontSize: '16px',
+                  lineHeight: 1,
+                  flexShrink: 0,
+                }}
+              >
+                ×
+              </Toast.Close>
+            </Toast.Root>
+          )
+        })}
+
+        <Toast.Viewport
+          style={{
+            position: 'fixed',
+            top: '80px',
+            right: '20px',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '10px',
+            zIndex: 10001,
+            maxWidth: '100vw',
+            margin: 0,
+            listStyle: 'none',
+            outline: 'none',
+          }}
+        />
+
+        <style
+          dangerouslySetInnerHTML={{
+            __html: `
+              @keyframes toastSlideIn {
+                from {
+                  transform: translateX(calc(100% + 25px));
+                }
+                to {
+                  transform: translateX(0);
+                }
+              }
+
+              @keyframes toastSlideOut {
+                from {
+                  transform: translateX(0);
+                }
+                to {
+                  transform: translateX(calc(100% + 25px));
+                }
+              }
+
+              @keyframes toastHide {
+                from {
+                  opacity: 1;
+                }
+                to {
+                  opacity: 0;
+                }
+              }
+
+              [data-radix-toast-viewport] [data-state='open'] {
+                animation: toastSlideIn 150ms cubic-bezier(0.16, 1, 0.3, 1);
+              }
+
+              [data-radix-toast-viewport] [data-state='closed'] {
+                animation: toastHide 100ms ease-in, toastSlideOut 200ms cubic-bezier(0.32, 0, 0.67, 0);
+              }
+
+              [data-radix-toast-viewport] [data-swipe='move'] {
+                transform: translateX(var(--radix-toast-swipe-move-x));
+              }
+
+              [data-radix-toast-viewport] [data-swipe='cancel'] {
+                transform: translateX(0);
+                transition: transform 200ms ease-out;
+              }
+
+              [data-radix-toast-viewport] [data-swipe='end'] {
+                animation: toastSlideOut 100ms ease-out;
+              }
+            `,
+          }}
+        />
+      </Toast.Provider>
+    </ToastContext.Provider>
+  )
+}

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

@@ -1,5 +1,6 @@
 import React from 'react'
 import { useRouter } from 'next/navigation'
+import { useToast } from '@/components/common/ToastContext'
 import { InvitePlayersTab } from './InvitePlayersTab'
 import { PlayOnlineTab } from './PlayOnlineTab'
 import { addToRecentRooms } from './RecentRoomsList'
@@ -25,7 +26,7 @@ interface AddPlayerButtonProps {
   // Context-aware: show different content based on room state
   isInRoom?: boolean
   // Game info for room creation
-  gameName?: 'matching' | 'memory-quiz' | 'complement-race'
+  gameName?: string | null
 }
 
 export function AddPlayerButton({
@@ -37,10 +38,11 @@ export function AddPlayerButton({
   activeTab: activeTabProp,
   setActiveTab: setActiveTabProp,
   isInRoom = false,
-  gameName = 'Arcade',
+  gameName = null,
 }: AddPlayerButtonProps) {
   const popoverRef = React.useRef<HTMLDivElement>(null)
   const router = useRouter()
+  const { showError } = useToast()
 
   // Use lifted state if provided, otherwise fallback to internal state
   const [internalShowPopover, setInternalShowPopover] = React.useState(false)
@@ -60,22 +62,29 @@ export function AddPlayerButton({
   const { mutate: joinRoom } = useJoinRoom()
   const { mutateAsync: getRoomByCode } = useGetRoomByCode()
 
-  // Handler for creating a new room
+  // Handler for creating a new room (without a game - game will be selected in room)
   const handleCreateRoom = () => {
     createRoom(
       {
-        name: `${gameName} Room`,
-        gameName: gameName,
+        name: null, // Auto-generated from code
+        gameName: null, // No game selected yet - will be chosen in room
         creatorName: 'Player',
       },
       {
         onSuccess: (data) => {
-          // Popover stays open, switch to invite tab to share room code
-          setActiveTab('invite')
+          // Add to recent rooms
+          addToRecentRooms({
+            code: data.code,
+            name: data.name,
+            gameName: data.gameName,
+          })
+          // Close popover and navigate to room to choose game
+          setShowPopover(false)
+          router.push('/arcade/room')
         },
         onError: (error) => {
           console.error('Failed to create room:', error)
-          alert(`Failed to create room: ${error.message}`)
+          showError('Failed to create room', error.message)
         },
       }
     )
@@ -100,8 +109,9 @@ export function AddPlayerButton({
                 gameName: data.room.gameName,
               })
             }
-            // Close popover
+            // Close popover and navigate to room
             setShowPopover(false)
+            router.push('/arcade/room')
           },
         }
       )

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

@@ -28,7 +28,7 @@ interface NetworkPlayer {
 interface ArcadeRoomInfo {
   roomId?: string
   roomName?: string
-  gameName: string
+  gameName: string | null
   playerCount: number
   joinCode?: string
 }
@@ -200,6 +200,7 @@ export function GameContextNav({
             onSetup={onSetup}
             onNewGame={onNewGame}
             onQuit={onExitSession}
+            showMenu={true}
           />
           <div style={{ marginLeft: 'auto' }}>
             <GameModeIndicator
@@ -287,7 +288,7 @@ export function GameContextNav({
                   playerScores={playerScores}
                   playerStreaks={playerStreaks}
                   roomId={roomInfo?.roomId}
-                  currentUserId={currentUserId}
+                  currentUserId={currentUserId ?? undefined}
                   isCurrentUserHost={isCurrentUserHost}
                 />
               ))}

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

@@ -1,6 +1,8 @@
-import { useState } from 'react'
+import { useEffect, useState } from 'react'
+import { io } from 'socket.io-client'
 import { Modal } from '@/components/common/Modal'
-import { useRoomData } from '@/hooks/useRoomData'
+import type { RoomData } from '@/hooks/useRoomData'
+import { useGetRoomByCode, useJoinRoom } from '@/hooks/useRoomData'
 
 export interface JoinRoomModalProps {
   /**
@@ -23,15 +25,26 @@ export interface JoinRoomModalProps {
  * Modal for joining a room by entering a 6-character code
  */
 export function JoinRoomModal({ isOpen, onClose, onSuccess }: JoinRoomModalProps) {
-  const { getRoomByCode, joinRoom } = useRoomData()
+  const { mutateAsync: getRoomByCode } = useGetRoomByCode()
+  const { mutateAsync: joinRoom } = useJoinRoom()
   const [code, setCode] = useState('')
+  const [password, setPassword] = useState('')
   const [error, setError] = useState('')
   const [isLoading, setIsLoading] = useState(false)
+  const [roomInfo, setRoomInfo] = useState<RoomData | null>(null)
+  const [needsPassword, setNeedsPassword] = useState(false)
+  const [needsApproval, setNeedsApproval] = useState(false)
+  const [approvalRequested, setApprovalRequested] = useState(false)
 
   const handleClose = () => {
     setCode('')
+    setPassword('')
     setError('')
     setIsLoading(false)
+    setRoomInfo(null)
+    setNeedsPassword(false)
+    setNeedsApproval(false)
+    setApprovalRequested(false)
     onClose()
   }
 
@@ -50,9 +63,46 @@ export function JoinRoomModal({ isOpen, onClose, onSuccess }: JoinRoomModalProps
     try {
       // Look up room by code
       const room = await getRoomByCode(normalizedCode)
+      setRoomInfo(room)
 
-      // Join the room
-      await joinRoom(room.id)
+      // Check access mode
+      if (room.accessMode === 'retired') {
+        setError('This room has been retired and is no longer accepting members')
+        setIsLoading(false)
+        return
+      }
+
+      if (room.accessMode === 'locked') {
+        setError('This room is locked and not accepting new members')
+        setIsLoading(false)
+        return
+      }
+
+      if (room.accessMode === 'approval-only') {
+        setNeedsApproval(true)
+        setIsLoading(false)
+        return
+      }
+
+      // For restricted rooms, try to join - the API will check for invitation
+
+      if (room.accessMode === 'password') {
+        // Check if password is provided
+        if (!needsPassword) {
+          setNeedsPassword(true)
+          setIsLoading(false)
+          return
+        }
+
+        if (!password) {
+          setError('Password is required')
+          setIsLoading(false)
+          return
+        }
+      }
+
+      // Join the room (with password if needed)
+      await joinRoom({ roomId: room.id, password: password || undefined })
 
       // Success! Close modal
       handleClose()
@@ -64,6 +114,93 @@ export function JoinRoomModal({ isOpen, onClose, onSuccess }: JoinRoomModalProps
     }
   }
 
+  const handleRequestAccess = async () => {
+    if (!roomInfo) return
+
+    setIsLoading(true)
+    setError('')
+
+    try {
+      const res = await fetch(`/api/arcade/rooms/${roomInfo.id}/join-requests`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      if (!res.ok) {
+        const errorData = await res.json()
+        throw new Error(errorData.error || 'Failed to request access')
+      }
+
+      // Success! Show waiting state
+      setApprovalRequested(true)
+      setIsLoading(false)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to request access')
+      setIsLoading(false)
+    }
+  }
+
+  // Socket listener for approval notifications
+  useEffect(() => {
+    if (!approvalRequested || !roomInfo) return
+
+    console.log('[JoinRoomModal] Setting up approval listener for room:', roomInfo.id)
+
+    let socket: ReturnType<typeof io> | null = null
+
+    // Fetch viewer ID and set up socket
+    const setupSocket = async () => {
+      try {
+        // Get current user's viewer ID
+        const res = await fetch('/api/viewer')
+        if (!res.ok) {
+          console.error('[JoinRoomModal] Failed to get viewer ID')
+          return
+        }
+
+        const { viewerId } = await res.json()
+        console.log('[JoinRoomModal] Got viewer ID:', viewerId)
+
+        // Connect socket
+        socket = io({ path: '/api/socket' })
+
+        socket.on('connect', () => {
+          console.log('[JoinRoomModal] Socket connected, joining user channel')
+          // Join user-specific channel to receive moderation events
+          socket?.emit('join-user-channel', { userId: viewerId })
+        })
+
+        socket.on('join-request-approved', async (data: { roomId: string; requestId: string }) => {
+          console.log('[JoinRoomModal] Request approved via socket!', data)
+          if (data.roomId === roomInfo.id) {
+            console.log('[JoinRoomModal] Joining room automatically...')
+            try {
+              await joinRoom({ roomId: roomInfo.id })
+              handleClose()
+              onSuccess?.()
+            } catch (err) {
+              setError(err instanceof Error ? err.message : 'Failed to join room')
+              setIsLoading(false)
+            }
+          }
+        })
+
+        socket.on('connect_error', (error) => {
+          console.error('[JoinRoomModal] Socket connection error:', error)
+        })
+      } catch (error) {
+        console.error('[JoinRoomModal] Error setting up socket:', error)
+      }
+    }
+
+    setupSocket()
+
+    return () => {
+      console.log('[JoinRoomModal] Cleaning up approval listener')
+      socket?.disconnect()
+    }
+  }, [approvalRequested, roomInfo, joinRoom, handleClose, onSuccess])
+
   return (
     <Modal isOpen={isOpen} onClose={handleClose}>
       <div
@@ -80,7 +217,7 @@ export function JoinRoomModal({ isOpen, onClose, onSuccess }: JoinRoomModalProps
             color: 'rgba(196, 181, 253, 1)',
           }}
         >
-          Join Room by Code
+          {needsApproval ? 'Request to Join Room' : 'Join Room by Code'}
         </h2>
         <p
           style={{
@@ -89,125 +226,354 @@ export function JoinRoomModal({ isOpen, onClose, onSuccess }: JoinRoomModalProps
             marginBottom: '24px',
           }}
         >
-          Enter the 6-character room code
+          {needsApproval
+            ? approvalRequested
+              ? 'Your request has been sent to the room moderator.'
+              : 'This room requires host approval. Send a request to join?'
+            : needsPassword
+              ? 'This room is password protected'
+              : 'Enter the 6-character room code'}
         </p>
 
-        <form onSubmit={handleSubmit}>
-          <input
-            type="text"
-            value={code}
-            onChange={(e) => {
-              setCode(e.target.value.toUpperCase())
-              setError('')
-            }}
-            placeholder="ABC123"
-            maxLength={6}
-            disabled={isLoading}
-            style={{
-              width: '100%',
-              padding: '14px',
-              border: error
-                ? '2px solid rgba(239, 68, 68, 0.6)'
-                : '2px solid rgba(139, 92, 246, 0.4)',
-              borderRadius: '10px',
-              fontSize: '18px',
-              fontWeight: 'bold',
-              fontFamily: 'monospace',
-              textAlign: 'center',
-              letterSpacing: '4px',
-              background: 'rgba(255, 255, 255, 0.05)',
-              color: 'rgba(196, 181, 253, 1)',
-              outline: 'none',
-              marginBottom: '8px',
-            }}
-          />
+        {needsApproval ? (
+          // Approval request UI
+          <div>
+            {approvalRequested ? (
+              // Waiting for approval state
+              <>
+                <div style={{ textAlign: 'center', marginBottom: '20px' }}>
+                  <div style={{ fontSize: '48px', marginBottom: '16px' }}>⏳</div>
+                  <h3
+                    style={{
+                      fontSize: '18px',
+                      fontWeight: 'bold',
+                      marginBottom: '8px',
+                      color: 'rgba(96, 165, 250, 1)',
+                    }}
+                  >
+                    Waiting for Approval
+                  </h3>
+                </div>
 
-          {error && (
-            <p
-              style={{
-                fontSize: '13px',
-                color: 'rgba(248, 113, 113, 1)',
-                marginBottom: '16px',
-                textAlign: 'center',
-              }}
-            >
-              {error}
-            </p>
-          )}
+                <div
+                  style={{
+                    padding: '16px',
+                    background: 'rgba(59, 130, 246, 0.1)',
+                    border: '1px solid rgba(59, 130, 246, 0.3)',
+                    borderRadius: '8px',
+                    marginBottom: '20px',
+                  }}
+                >
+                  <p
+                    style={{
+                      fontSize: '14px',
+                      color: 'rgba(209, 213, 219, 1)',
+                      marginBottom: '8px',
+                    }}
+                  >
+                    <strong>{roomInfo?.name}</strong>
+                  </p>
+                  <p style={{ fontSize: '13px', color: 'rgba(156, 163, 175, 1)' }}>
+                    Code: {roomInfo?.code}
+                  </p>
+                </div>
 
-          <div style={{ display: 'flex', gap: '12px', marginTop: '24px' }}>
-            <button
-              type="button"
-              onClick={handleClose}
-              disabled={isLoading}
-              style={{
-                flex: 1,
-                padding: '12px',
-                background: 'rgba(75, 85, 99, 0.3)',
-                color: 'rgba(209, 213, 219, 1)',
-                border: '2px solid rgba(75, 85, 99, 0.5)',
-                borderRadius: '10px',
-                fontSize: '15px',
-                fontWeight: '600',
-                cursor: isLoading ? 'not-allowed' : 'pointer',
-                opacity: isLoading ? 0.5 : 1,
-                transition: 'all 0.2s ease',
-              }}
-              onMouseEnter={(e) => {
-                if (!isLoading) {
-                  e.currentTarget.style.background = 'rgba(75, 85, 99, 0.4)'
-                }
-              }}
-              onMouseLeave={(e) => {
-                if (!isLoading) {
-                  e.currentTarget.style.background = 'rgba(75, 85, 99, 0.3)'
-                }
-              }}
-            >
-              Cancel
-            </button>
-            <button
-              type="submit"
-              disabled={code.trim().length !== 6 || isLoading}
-              style={{
-                flex: 1,
-                padding: '12px',
-                background:
-                  code.trim().length === 6 && !isLoading
-                    ? 'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))'
-                    : 'rgba(75, 85, 99, 0.3)',
-                color:
-                  code.trim().length === 6 && !isLoading
-                    ? 'rgba(255, 255, 255, 1)'
-                    : 'rgba(156, 163, 175, 1)',
-                border:
-                  code.trim().length === 6 && !isLoading
-                    ? '2px solid rgba(59, 130, 246, 0.6)'
-                    : '2px solid rgba(75, 85, 99, 0.5)',
-                borderRadius: '10px',
-                fontSize: '15px',
-                fontWeight: '600',
-                cursor: code.trim().length === 6 && !isLoading ? 'pointer' : 'not-allowed',
-                opacity: code.trim().length === 6 && !isLoading ? 1 : 0.5,
-                transition: 'all 0.2s ease',
-              }}
-              onMouseEnter={(e) => {
-                if (code.trim().length === 6 && !isLoading) {
-                  e.currentTarget.style.background =
-                    'linear-gradient(135deg, rgba(59, 130, 246, 0.9), rgba(37, 99, 235, 0.9))'
-                }
-              }}
-              onMouseLeave={(e) => {
-                if (code.trim().length === 6 && !isLoading) {
-                  e.currentTarget.style.background =
-                    'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))'
-                }
-              }}
-            >
-              {isLoading ? 'Joining...' : 'Join Room'}
-            </button>
+                <p
+                  style={{
+                    fontSize: '13px',
+                    color: 'rgba(156, 163, 175, 1)',
+                    textAlign: 'center',
+                    marginBottom: '20px',
+                  }}
+                >
+                  You'll be able to join once the host approves your request. You can close this
+                  dialog and check back later.
+                </p>
+
+                <button
+                  type="button"
+                  onClick={handleClose}
+                  style={{
+                    width: '100%',
+                    padding: '12px',
+                    background: 'rgba(75, 85, 99, 0.3)',
+                    color: 'rgba(209, 213, 219, 1)',
+                    border: '2px solid rgba(75, 85, 99, 0.5)',
+                    borderRadius: '10px',
+                    fontSize: '15px',
+                    fontWeight: '600',
+                    cursor: 'pointer',
+                    transition: 'all 0.2s ease',
+                  }}
+                  onMouseEnter={(e) => {
+                    e.currentTarget.style.background = 'rgba(75, 85, 99, 0.4)'
+                  }}
+                  onMouseLeave={(e) => {
+                    e.currentTarget.style.background = 'rgba(75, 85, 99, 0.3)'
+                  }}
+                >
+                  Close
+                </button>
+              </>
+            ) : (
+              // Initial request prompt
+              <>
+                <div
+                  style={{
+                    padding: '16px',
+                    background: 'rgba(59, 130, 246, 0.1)',
+                    border: '1px solid rgba(59, 130, 246, 0.3)',
+                    borderRadius: '8px',
+                    marginBottom: '20px',
+                  }}
+                >
+                  <p
+                    style={{
+                      fontSize: '14px',
+                      color: 'rgba(209, 213, 219, 1)',
+                      marginBottom: '8px',
+                    }}
+                  >
+                    <strong>{roomInfo?.name}</strong>
+                  </p>
+                  <p style={{ fontSize: '13px', color: 'rgba(156, 163, 175, 1)' }}>
+                    Code: {roomInfo?.code}
+                  </p>
+                </div>
+
+                {error && (
+                  <p
+                    style={{
+                      fontSize: '13px',
+                      color: 'rgba(248, 113, 113, 1)',
+                      marginBottom: '16px',
+                      textAlign: 'center',
+                    }}
+                  >
+                    {error}
+                  </p>
+                )}
+
+                <div style={{ display: 'flex', gap: '12px' }}>
+                  <button
+                    type="button"
+                    onClick={handleClose}
+                    disabled={isLoading}
+                    style={{
+                      flex: 1,
+                      padding: '12px',
+                      background: 'rgba(75, 85, 99, 0.3)',
+                      color: 'rgba(209, 213, 219, 1)',
+                      border: '2px solid rgba(75, 85, 99, 0.5)',
+                      borderRadius: '10px',
+                      fontSize: '15px',
+                      fontWeight: '600',
+                      cursor: isLoading ? 'not-allowed' : 'pointer',
+                      opacity: isLoading ? 0.5 : 1,
+                      transition: 'all 0.2s ease',
+                    }}
+                    onMouseEnter={(e) => {
+                      if (!isLoading) {
+                        e.currentTarget.style.background = 'rgba(75, 85, 99, 0.4)'
+                      }
+                    }}
+                    onMouseLeave={(e) => {
+                      if (!isLoading) {
+                        e.currentTarget.style.background = 'rgba(75, 85, 99, 0.3)'
+                      }
+                    }}
+                  >
+                    Cancel
+                  </button>
+                  <button
+                    type="button"
+                    onClick={handleRequestAccess}
+                    disabled={isLoading}
+                    style={{
+                      flex: 1,
+                      padding: '12px',
+                      background: isLoading
+                        ? 'rgba(75, 85, 99, 0.3)'
+                        : 'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))',
+                      color: isLoading ? 'rgba(156, 163, 175, 1)' : 'rgba(255, 255, 255, 1)',
+                      border: isLoading
+                        ? '2px solid rgba(75, 85, 99, 0.5)'
+                        : '2px solid rgba(59, 130, 246, 0.6)',
+                      borderRadius: '10px',
+                      fontSize: '15px',
+                      fontWeight: '600',
+                      cursor: isLoading ? 'not-allowed' : 'pointer',
+                      opacity: isLoading ? 0.5 : 1,
+                      transition: 'all 0.2s ease',
+                    }}
+                    onMouseEnter={(e) => {
+                      if (!isLoading) {
+                        e.currentTarget.style.background =
+                          'linear-gradient(135deg, rgba(59, 130, 246, 0.9), rgba(37, 99, 235, 0.9))'
+                      }
+                    }}
+                    onMouseLeave={(e) => {
+                      if (!isLoading) {
+                        e.currentTarget.style.background =
+                          'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))'
+                      }
+                    }}
+                  >
+                    {isLoading ? 'Sending...' : 'Send Request'}
+                  </button>
+                </div>
+              </>
+            )}
           </div>
-        </form>
+        ) : (
+          // Standard join form
+          <form onSubmit={handleSubmit}>
+            <input
+              type="text"
+              value={code}
+              onChange={(e) => {
+                setCode(e.target.value.toUpperCase())
+                setError('')
+                setNeedsPassword(false)
+                setNeedsApproval(false)
+              }}
+              placeholder="ABC123"
+              maxLength={6}
+              disabled={isLoading || needsPassword}
+              style={{
+                width: '100%',
+                padding: '14px',
+                border: error
+                  ? '2px solid rgba(239, 68, 68, 0.6)'
+                  : '2px solid rgba(139, 92, 246, 0.4)',
+                borderRadius: '10px',
+                fontSize: '18px',
+                fontWeight: 'bold',
+                fontFamily: 'monospace',
+                textAlign: 'center',
+                letterSpacing: '4px',
+                background: 'rgba(255, 255, 255, 0.05)',
+                color: 'rgba(196, 181, 253, 1)',
+                outline: 'none',
+                marginBottom: '8px',
+              }}
+            />
+
+            {needsPassword && (
+              <input
+                type="password"
+                value={password}
+                onChange={(e) => {
+                  setPassword(e.target.value)
+                  setError('')
+                }}
+                placeholder="Enter password"
+                disabled={isLoading}
+                style={{
+                  width: '100%',
+                  padding: '14px',
+                  border: error
+                    ? '2px solid rgba(239, 68, 68, 0.6)'
+                    : '2px solid rgba(251, 191, 36, 0.4)',
+                  borderRadius: '10px',
+                  fontSize: '16px',
+                  textAlign: 'center',
+                  background: 'rgba(255, 255, 255, 0.05)',
+                  color: 'rgba(251, 191, 36, 1)',
+                  outline: 'none',
+                  marginBottom: '8px',
+                  marginTop: '12px',
+                }}
+              />
+            )}
+
+            {error && (
+              <p
+                style={{
+                  fontSize: '13px',
+                  color: 'rgba(248, 113, 113, 1)',
+                  marginBottom: '16px',
+                  textAlign: 'center',
+                }}
+              >
+                {error}
+              </p>
+            )}
+
+            <div style={{ display: 'flex', gap: '12px', marginTop: '24px' }}>
+              <button
+                type="button"
+                onClick={handleClose}
+                disabled={isLoading}
+                style={{
+                  flex: 1,
+                  padding: '12px',
+                  background: 'rgba(75, 85, 99, 0.3)',
+                  color: 'rgba(209, 213, 219, 1)',
+                  border: '2px solid rgba(75, 85, 99, 0.5)',
+                  borderRadius: '10px',
+                  fontSize: '15px',
+                  fontWeight: '600',
+                  cursor: isLoading ? 'not-allowed' : 'pointer',
+                  opacity: isLoading ? 0.5 : 1,
+                  transition: 'all 0.2s ease',
+                }}
+                onMouseEnter={(e) => {
+                  if (!isLoading) {
+                    e.currentTarget.style.background = 'rgba(75, 85, 99, 0.4)'
+                  }
+                }}
+                onMouseLeave={(e) => {
+                  if (!isLoading) {
+                    e.currentTarget.style.background = 'rgba(75, 85, 99, 0.3)'
+                  }
+                }}
+              >
+                Cancel
+              </button>
+              <button
+                type="submit"
+                disabled={code.trim().length !== 6 || isLoading}
+                style={{
+                  flex: 1,
+                  padding: '12px',
+                  background:
+                    code.trim().length === 6 && !isLoading
+                      ? 'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))'
+                      : 'rgba(75, 85, 99, 0.3)',
+                  color:
+                    code.trim().length === 6 && !isLoading
+                      ? 'rgba(255, 255, 255, 1)'
+                      : 'rgba(156, 163, 175, 1)',
+                  border:
+                    code.trim().length === 6 && !isLoading
+                      ? '2px solid rgba(59, 130, 246, 0.6)'
+                      : '2px solid rgba(75, 85, 99, 0.5)',
+                  borderRadius: '10px',
+                  fontSize: '15px',
+                  fontWeight: '600',
+                  cursor: code.trim().length === 6 && !isLoading ? 'pointer' : 'not-allowed',
+                  opacity: code.trim().length === 6 && !isLoading ? 1 : 0.5,
+                  transition: 'all 0.2s ease',
+                }}
+                onMouseEnter={(e) => {
+                  if (code.trim().length === 6 && !isLoading) {
+                    e.currentTarget.style.background =
+                      'linear-gradient(135deg, rgba(59, 130, 246, 0.9), rgba(37, 99, 235, 0.9))'
+                  }
+                }}
+                onMouseLeave={(e) => {
+                  if (code.trim().length === 6 && !isLoading) {
+                    e.currentTarget.style.background =
+                      'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))'
+                  }
+                }}
+              >
+                {isLoading ? 'Joining...' : needsPassword ? 'Join with Password' : 'Join Room'}
+              </button>
+            </div>
+          </form>
+        )}
       </div>
     </Modal>
   )

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

@@ -1,7 +1,9 @@
-import { useEffect, useState } from 'react'
-import { useRouter } from 'next/navigation'
 import * as Toast from '@radix-ui/react-toast'
+import { useQueryClient } from '@tanstack/react-query'
+import { useRouter } from 'next/navigation'
+import { useEffect, useState } from 'react'
 import { Modal } from '@/components/common/Modal'
+import { useToast } from '@/components/common/ToastContext'
 import type { ModerationEvent } from '@/hooks/useRoomData'
 import { useJoinRoom } from '@/hooks/useRoomData'
 
@@ -25,8 +27,13 @@ export function ModerationNotifications({
   onClose,
 }: ModerationNotificationsProps) {
   const router = useRouter()
+  const queryClient = useQueryClient()
+  const { showError } = useToast()
   const [showToast, setShowToast] = useState(false)
+  const [showJoinRequestToast, setShowJoinRequestToast] = useState(false)
   const [isAcceptingInvitation, setIsAcceptingInvitation] = useState(false)
+  const [isProcessingRequest, setIsProcessingRequest] = useState(false)
+  const [requestError, setRequestError] = useState<string | null>(null)
   const { mutateAsync: joinRoom } = useJoinRoom()
 
   // Handle report toast (for hosts)
@@ -42,8 +49,94 @@ export function ModerationNotifications({
     }
   }, [moderationEvent, onClose])
 
+  // Handle join request toast (for hosts)
+  useEffect(() => {
+    if (moderationEvent?.type === 'join-request') {
+      setShowJoinRequestToast(true)
+      setRequestError(null) // Clear any previous errors
+    } else {
+      // Reset toast state when event is cleared or changes type
+      setShowJoinRequestToast(false)
+      setRequestError(null)
+    }
+  }, [moderationEvent])
+
+  // Handle approve join request
+  const handleApprove = async () => {
+    if (!moderationEvent?.data.requestId || !moderationEvent?.data.roomId) return
+
+    setIsProcessingRequest(true)
+    setRequestError(null) // Clear any previous errors
+
+    try {
+      const response = await fetch(
+        `/api/arcade/rooms/${moderationEvent.data.roomId}/join-requests/${moderationEvent.data.requestId}/approve`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}))
+        throw new Error(errorData.error || 'Failed to approve join request')
+      }
+
+      // Close toast and event on success
+      setShowJoinRequestToast(false)
+      onClose()
+
+      // Invalidate join requests query to refresh the list
+      queryClient.invalidateQueries({ queryKey: ['join-requests'] })
+    } catch (error) {
+      console.error('Failed to approve join request:', error)
+      // Keep toast visible and show error message
+      setRequestError(error instanceof Error ? error.message : 'Failed to approve request')
+    } finally {
+      setIsProcessingRequest(false)
+    }
+  }
+
+  // Handle deny join request
+  const handleDeny = async () => {
+    if (!moderationEvent?.data.requestId || !moderationEvent?.data.roomId) return
+
+    setIsProcessingRequest(true)
+    setRequestError(null) // Clear any previous errors
+
+    try {
+      const response = await fetch(
+        `/api/arcade/rooms/${moderationEvent.data.roomId}/join-requests/${moderationEvent.data.requestId}/deny`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}))
+        throw new Error(errorData.error || 'Failed to deny join request')
+      }
+
+      // Close toast and event on success
+      setShowJoinRequestToast(false)
+      onClose()
+
+      // Invalidate join requests query to refresh the list
+      queryClient.invalidateQueries({ queryKey: ['join-requests'] })
+    } catch (error) {
+      console.error('Failed to deny join request:', error)
+      // Keep toast visible and show error message
+      setRequestError(error instanceof Error ? error.message : 'Failed to deny request')
+    } finally {
+      setIsProcessingRequest(false)
+    }
+  }
+
   // Kicked modal
   if (moderationEvent?.type === 'kicked') {
+    const isRetired = moderationEvent.data.reason?.includes('retired')
+
     return (
       <Modal isOpen={true} onClose={() => {}}>
         <div
@@ -54,7 +147,7 @@ export function ModerationNotifications({
             minWidth: '400px',
           }}
         >
-          <div style={{ fontSize: '48px', marginBottom: '16px' }}>⚠️</div>
+          <div style={{ fontSize: '48px', marginBottom: '16px' }}>{isRetired ? '🏁' : '⚠️'}</div>
           <h2
             style={{
               fontSize: '24px',
@@ -63,7 +156,7 @@ export function ModerationNotifications({
               color: 'rgba(253, 186, 116, 1)',
             }}
           >
-            Kicked from Room
+            {isRetired ? 'Room Retired' : 'Kicked from Room'}
           </h2>
           <p
             style={{
@@ -72,10 +165,16 @@ export function ModerationNotifications({
               marginBottom: '8px',
             }}
           >
-            You were kicked from the room by{' '}
-            <strong style={{ color: 'rgba(253, 186, 116, 1)' }}>
-              {moderationEvent.data.kickedBy}
-            </strong>
+            {isRetired ? (
+              <>The room owner has retired this room and access has been closed</>
+            ) : (
+              <>
+                You were kicked from the room by{' '}
+                <strong style={{ color: 'rgba(253, 186, 116, 1)' }}>
+                  {moderationEvent.data.kickedBy}
+                </strong>
+              </>
+            )}
           </p>
           <p
             style={{
@@ -84,7 +183,9 @@ export function ModerationNotifications({
               marginBottom: '24px',
             }}
           >
-            You can rejoin if the host sends you a new invite
+            {isRetired
+              ? 'Only the room owner can access retired rooms'
+              : 'You can rejoin if the host sends you a new invite'}
           </p>
 
           <button
@@ -391,6 +492,255 @@ export function ModerationNotifications({
     )
   }
 
+  // Join request toast (for hosts)
+  if (moderationEvent?.type === 'join-request') {
+    return (
+      <Toast.Provider swipeDirection="right" duration={Infinity}>
+        <Toast.Root
+          open={showJoinRequestToast}
+          onOpenChange={(open) => {
+            if (!open) {
+              setShowJoinRequestToast(false)
+              onClose()
+            }
+          }}
+          style={{
+            background:
+              'linear-gradient(135deg, rgba(59, 130, 246, 0.97), rgba(37, 99, 235, 0.97))',
+            border: '2px solid rgba(59, 130, 246, 0.6)',
+            borderRadius: '12px',
+            padding: '16px',
+            boxShadow: '0 8px 24px rgba(0, 0, 0, 0.4)',
+            display: 'flex',
+            gap: '12px',
+            alignItems: 'flex-start',
+            minWidth: '350px',
+            maxWidth: '450px',
+            transition: 'all 0.2s ease',
+          }}
+        >
+          <div style={{ fontSize: '24px', flexShrink: 0 }}>✋</div>
+          <div style={{ flex: 1 }}>
+            <Toast.Title
+              style={{
+                fontSize: '15px',
+                fontWeight: 'bold',
+                color: 'white',
+                marginBottom: '4px',
+              }}
+            >
+              Join Request
+            </Toast.Title>
+            <Toast.Description
+              style={{
+                fontSize: '13px',
+                color: 'rgba(255, 255, 255, 0.9)',
+                marginBottom: '12px',
+              }}
+            >
+              <strong>{moderationEvent.data.requesterName}</strong> wants to join your room
+            </Toast.Description>
+
+            {/* Error message */}
+            {requestError && (
+              <div
+                style={{
+                  padding: '8px 10px',
+                  background: 'rgba(239, 68, 68, 0.2)',
+                  border: '1px solid rgba(239, 68, 68, 0.4)',
+                  borderRadius: '6px',
+                  marginBottom: '12px',
+                }}
+              >
+                <div
+                  style={{
+                    fontSize: '12px',
+                    color: 'rgba(254, 202, 202, 1)',
+                    fontWeight: '600',
+                    marginBottom: '2px',
+                  }}
+                >
+                  ⚠️ Error
+                </div>
+                <div
+                  style={{
+                    fontSize: '11px',
+                    color: 'rgba(255, 255, 255, 0.9)',
+                  }}
+                >
+                  {requestError}
+                </div>
+              </div>
+            )}
+
+            {/* Action buttons */}
+            <div style={{ display: 'flex', gap: '8px' }}>
+              <button
+                type="button"
+                disabled={isProcessingRequest}
+                onClick={(e) => {
+                  e.stopPropagation()
+                  handleDeny()
+                }}
+                style={{
+                  flex: 1,
+                  padding: '8px 12px',
+                  background: isProcessingRequest
+                    ? 'rgba(75, 85, 99, 0.3)'
+                    : 'rgba(255, 255, 255, 0.2)',
+                  color: 'white',
+                  border: '1px solid rgba(255, 255, 255, 0.3)',
+                  borderRadius: '8px',
+                  fontSize: '13px',
+                  fontWeight: '600',
+                  cursor: isProcessingRequest ? 'not-allowed' : 'pointer',
+                  transition: 'all 0.2s ease',
+                  opacity: isProcessingRequest ? 0.5 : 1,
+                }}
+                onMouseEnter={(e) => {
+                  if (!isProcessingRequest) {
+                    e.currentTarget.style.background = 'rgba(255, 255, 255, 0.25)'
+                  }
+                }}
+                onMouseLeave={(e) => {
+                  if (!isProcessingRequest) {
+                    e.currentTarget.style.background = 'rgba(255, 255, 255, 0.2)'
+                  }
+                }}
+              >
+                Deny
+              </button>
+              <button
+                type="button"
+                disabled={isProcessingRequest}
+                onClick={(e) => {
+                  e.stopPropagation()
+                  handleApprove()
+                }}
+                style={{
+                  flex: 1,
+                  padding: '8px 12px',
+                  background: isProcessingRequest
+                    ? 'rgba(75, 85, 99, 0.3)'
+                    : 'rgba(34, 197, 94, 0.9)',
+                  color: 'white',
+                  border: '1px solid rgba(34, 197, 94, 0.8)',
+                  borderRadius: '8px',
+                  fontSize: '13px',
+                  fontWeight: '600',
+                  cursor: isProcessingRequest ? 'not-allowed' : 'pointer',
+                  transition: 'all 0.2s ease',
+                  opacity: isProcessingRequest ? 0.5 : 1,
+                }}
+                onMouseEnter={(e) => {
+                  if (!isProcessingRequest) {
+                    e.currentTarget.style.background = 'rgba(34, 197, 94, 1)'
+                  }
+                }}
+                onMouseLeave={(e) => {
+                  if (!isProcessingRequest) {
+                    e.currentTarget.style.background = 'rgba(34, 197, 94, 0.9)'
+                  }
+                }}
+              >
+                {isProcessingRequest ? 'Processing...' : 'Approve'}
+              </button>
+            </div>
+          </div>
+          <Toast.Close
+            style={{
+              background: 'rgba(255, 255, 255, 0.2)',
+              border: 'none',
+              borderRadius: '50%',
+              width: '24px',
+              height: '24px',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              cursor: 'pointer',
+              color: 'white',
+              fontSize: '16px',
+              lineHeight: 1,
+              flexShrink: 0,
+            }}
+          >
+            ×
+          </Toast.Close>
+        </Toast.Root>
+
+        <Toast.Viewport
+          style={{
+            position: 'fixed',
+            top: '80px',
+            right: '20px',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '10px',
+            zIndex: 10001,
+            maxWidth: '100vw',
+            margin: 0,
+            listStyle: 'none',
+            outline: 'none',
+          }}
+        />
+
+        <style
+          dangerouslySetInnerHTML={{
+            __html: `
+              @keyframes slideIn {
+                from {
+                  transform: translateX(calc(100% + 25px));
+                }
+                to {
+                  transform: translateX(0);
+                }
+              }
+
+              @keyframes slideOut {
+                from {
+                  transform: translateX(0);
+                }
+                to {
+                  transform: translateX(calc(100% + 25px));
+                }
+              }
+
+              @keyframes hide {
+                from {
+                  opacity: 1;
+                }
+                to {
+                  opacity: 0;
+                }
+              }
+
+              [data-state='open'] {
+                animation: slideIn 150ms cubic-bezier(0.16, 1, 0.3, 1);
+              }
+
+              [data-state='closed'] {
+                animation: hide 100ms ease-in, slideOut 200ms cubic-bezier(0.32, 0, 0.67, 0);
+              }
+
+              [data-swipe='move'] {
+                transform: translateX(var(--radix-toast-swipe-move-x));
+              }
+
+              [data-swipe='cancel'] {
+                transform: translateX(0);
+                transition: transform 200ms ease-out;
+              }
+
+              [data-swipe='end'] {
+                animation: slideOut 100ms ease-out;
+              }
+            `,
+          }}
+        />
+      </Toast.Provider>
+    )
+  }
+
   // Invitation modal
   if (moderationEvent?.type === 'invitation') {
     const invitationType = moderationEvent.data.invitationType
@@ -486,7 +836,10 @@ export function ModerationNotifications({
                   router.push('/arcade/room')
                 } catch (error) {
                   console.error('Failed to join room:', error)
-                  alert(error instanceof Error ? error.message : 'Failed to join room')
+                  showError(
+                    'Failed to join room',
+                    error instanceof Error ? error.message : undefined
+                  )
                   setIsAcceptingInvitation(false)
                 }
               }}

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

@@ -1,7 +1,8 @@
 import * as Dialog from '@radix-ui/react-dialog'
 import { useEffect, useState } from 'react'
 import { Modal } from '@/components/common/Modal'
-import type { RoomBan, RoomMember, RoomReport } from '@/db/schema'
+import type { RoomBan, RoomReport } from '@/db/schema'
+import type { RoomMember } from '@/hooks/useRoomData'
 
 export interface RoomPlayer {
   id: string
@@ -47,7 +48,7 @@ export interface ModerationPanelProps {
   focusedUserId?: string
 }
 
-type Tab = 'members' | 'bans' | 'history'
+type Tab = 'members' | 'bans' | 'history' | 'settings'
 
 export interface HistoricalMemberWithStatus {
   userId: string
@@ -86,6 +87,19 @@ export function ModerationPanel({
   const [error, setError] = useState('')
   const [actionLoading, setActionLoading] = useState<string | null>(null)
 
+  // Settings state
+  const [accessMode, setAccessMode] = useState<string>('open')
+  const [originalAccessMode, setOriginalAccessMode] = useState<string>('open')
+  const [roomPassword, setRoomPassword] = useState('')
+  const [showPasswordInput, setShowPasswordInput] = useState(false)
+  const [selectedNewOwner, setSelectedNewOwner] = useState<string>('')
+  const [joinRequests, setJoinRequests] = useState<any[]>([])
+  const [passwordCopied, setPasswordCopied] = useState(false)
+
+  // Inline feedback state
+  const [successMessage, setSuccessMessage] = useState<string>('')
+  const [errorMessage, setErrorMessage] = useState<string>('')
+
   // Ban modal state
   const [showBanModal, setShowBanModal] = useState(false)
   const [banTargetUserId, setBanTargetUserId] = useState<string | null>(null)
@@ -173,8 +187,9 @@ export function ModerationPanel({
       }
 
       // Success - member will be removed via socket update
+      showSuccess('Player kicked from room')
     } catch (err) {
-      alert(err instanceof Error ? err.message : 'Failed to kick player')
+      showError(err instanceof Error ? err.message : 'Failed to kick player')
     } finally {
       setActionLoading(null)
     }
@@ -211,8 +226,10 @@ export function ModerationPanel({
         const data = await bansRes.json()
         setBans(data.bans || [])
       }
+
+      showSuccess('Player banned from room')
     } catch (err) {
-      alert(err instanceof Error ? err.message : 'Failed to ban player')
+      showError(err instanceof Error ? err.message : 'Failed to ban player')
     } finally {
       setActionLoading(null)
       setBanTargetUserId(null)
@@ -248,8 +265,10 @@ export function ModerationPanel({
         const data = await historyRes.json()
         setHistoricalMembers(data.historicalMembers || [])
       }
+
+      showSuccess('Player unbanned')
     } catch (err) {
-      alert(err instanceof Error ? err.message : 'Failed to unban player')
+      showError(err instanceof Error ? err.message : 'Failed to unban player')
     } finally {
       setActionLoading(null)
     }
@@ -285,9 +304,9 @@ export function ModerationPanel({
         setHistoricalMembers(data.historicalMembers || [])
       }
 
-      alert(`${userName} has been unbanned and invited back to the room!`)
+      showSuccess(`${userName} has been unbanned and invited back to the room`)
     } catch (err) {
-      alert(err instanceof Error ? err.message : 'Failed to unban player')
+      showError(err instanceof Error ? err.message : 'Failed to unban player')
     } finally {
       setActionLoading(null)
     }
@@ -315,17 +334,197 @@ export function ModerationPanel({
         setHistoricalMembers(data.historicalMembers || [])
       }
 
-      alert(`Invitation sent to ${userName}!`)
+      showSuccess(`Invitation sent to ${userName}`)
     } catch (err) {
-      alert(err instanceof Error ? err.message : 'Failed to send invitation')
+      showError(err instanceof Error ? err.message : 'Failed to send invitation')
     } finally {
       setActionLoading(null)
     }
   }
 
+  // Load room settings and join requests when Settings tab is opened
+  useEffect(() => {
+    if (!isOpen || activeTab !== 'settings') return
+
+    const loadSettings = async () => {
+      try {
+        // Fetch current room data to get access mode and password
+        const roomRes = await fetch(`/api/arcade/rooms/${roomId}`)
+        if (roomRes.ok) {
+          const data = await roomRes.json()
+          const currentAccessMode = data.room?.accessMode || 'open'
+          setAccessMode(currentAccessMode)
+          setOriginalAccessMode(currentAccessMode)
+
+          // Set password field if room has a password and user is the creator
+          if (currentAccessMode === 'password' && data.room?.displayPassword) {
+            setRoomPassword(data.room.displayPassword)
+            setShowPasswordInput(true)
+          }
+        }
+
+        // Fetch join requests if any
+        const requestsRes = await fetch(`/api/arcade/rooms/${roomId}/join-requests`)
+        if (requestsRes.ok) {
+          const data = await requestsRes.json()
+          setJoinRequests(data.requests || [])
+        }
+      } catch (err) {
+        console.error('Failed to load settings:', err)
+      }
+    }
+
+    loadSettings()
+  }, [isOpen, activeTab, roomId])
+
+  // Handlers for Settings tab
+  const handleUpdateAccessMode = async () => {
+    setActionLoading('update-settings')
+    try {
+      const body: any = { accessMode }
+      if (accessMode === 'password' && roomPassword) {
+        body.password = roomPassword
+      }
+
+      const res = await fetch(`/api/arcade/rooms/${roomId}/settings`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      })
+
+      if (!res.ok) {
+        const errorData = await res.json()
+        throw new Error(errorData.error || 'Failed to update settings')
+      }
+
+      showSuccess('Room settings updated successfully')
+      setOriginalAccessMode(accessMode) // Update original to current
+      setShowPasswordInput(false)
+      setRoomPassword('')
+    } catch (err) {
+      showError(err instanceof Error ? err.message : 'Failed to update settings')
+    } finally {
+      setActionLoading(null)
+    }
+  }
+
+  const handleTransferOwnership = async () => {
+    if (!selectedNewOwner) return
+
+    const newOwner = members.find((m) => m.userId === selectedNewOwner)
+    if (!newOwner) return
+
+    if (!confirm(`Transfer ownership to ${newOwner.displayName}? You will no longer be the host.`))
+      return
+
+    setActionLoading('transfer-ownership')
+    try {
+      const res = await fetch(`/api/arcade/rooms/${roomId}/transfer-ownership`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ newOwnerId: selectedNewOwner }),
+      })
+
+      if (!res.ok) {
+        const errorData = await res.json()
+        throw new Error(errorData.error || 'Failed to transfer ownership')
+      }
+
+      showSuccess(`Ownership transferred to ${newOwner.displayName}`)
+      setTimeout(() => onClose(), 2000) // Close panel after showing message
+    } catch (err) {
+      showError(err instanceof Error ? err.message : 'Failed to transfer ownership')
+    } finally {
+      setActionLoading(null)
+    }
+  }
+
+  const handleApproveJoinRequest = async (requestId: string) => {
+    setActionLoading(`approve-request-${requestId}`)
+    try {
+      const res = await fetch(`/api/arcade/rooms/${roomId}/join-requests/${requestId}/approve`, {
+        method: 'POST',
+      })
+
+      if (!res.ok) {
+        const errorData = await res.json()
+        throw new Error(errorData.error || 'Failed to approve request')
+      }
+
+      // Reload requests
+      const requestsRes = await fetch(`/api/arcade/rooms/${roomId}/join-requests`)
+      if (requestsRes.ok) {
+        const data = await requestsRes.json()
+        setJoinRequests(data.requests || [])
+      }
+
+      showSuccess('Join request approved')
+    } catch (err) {
+      showError(err instanceof Error ? err.message : 'Failed to approve request')
+    } finally {
+      setActionLoading(null)
+    }
+  }
+
+  const handleDenyJoinRequest = async (requestId: string) => {
+    setActionLoading(`deny-request-${requestId}`)
+    try {
+      const res = await fetch(`/api/arcade/rooms/${roomId}/join-requests/${requestId}/deny`, {
+        method: 'POST',
+      })
+
+      if (!res.ok) {
+        const errorData = await res.json()
+        throw new Error(errorData.error || 'Failed to deny request')
+      }
+
+      // Reload requests
+      const requestsRes = await fetch(`/api/arcade/rooms/${roomId}/join-requests`)
+      if (requestsRes.ok) {
+        const data = await requestsRes.json()
+        setJoinRequests(data.requests || [])
+      }
+
+      showSuccess('Join request denied')
+    } catch (err) {
+      showError(err instanceof Error ? err.message : 'Failed to deny request')
+    } finally {
+      setActionLoading(null)
+    }
+  }
+
+  const handleCopyPassword = async () => {
+    if (!roomPassword) return
+
+    try {
+      await navigator.clipboard.writeText(roomPassword)
+      setPasswordCopied(true)
+      setTimeout(() => setPasswordCopied(false), 2000)
+    } catch (err) {
+      console.error('Failed to copy password:', err)
+      showError('Failed to copy password to clipboard')
+    }
+  }
+
+  // Utility functions for showing feedback
+  const showSuccess = (message: string) => {
+    setSuccessMessage(message)
+    setErrorMessage('')
+    setTimeout(() => setSuccessMessage(''), 5000)
+  }
+
+  const showError = (message: string) => {
+    setErrorMessage(message)
+    setSuccessMessage('')
+    setTimeout(() => setErrorMessage(''), 5000)
+  }
+
   const pendingReports = reports.filter((r) => r.status === 'pending')
   const otherMembers = members.filter((m) => m.userId !== currentUserId)
 
+  // Check if there are unsaved changes in settings
+  const hasUnsavedAccessModeChanges = accessMode !== originalAccessMode
+
   // Group reports by reported user ID
   const reportsByUser = pendingReports.reduce(
     (acc, report) => {
@@ -366,6 +565,69 @@ export function ModerationPanel({
           Manage members, reports, and bans
         </p>
 
+        {/* Success/Error Messages */}
+        {(successMessage || errorMessage) && (
+          <div
+            style={{
+              padding: '12px 16px',
+              background: successMessage ? 'rgba(34, 197, 94, 0.1)' : 'rgba(239, 68, 68, 0.1)',
+              border: successMessage
+                ? '1px solid rgba(34, 197, 94, 0.4)'
+                : '1px solid rgba(239, 68, 68, 0.4)',
+              borderRadius: '8px',
+              marginBottom: '16px',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'space-between',
+              animation: 'fadeIn 0.2s ease',
+            }}
+          >
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: '8px',
+                flex: 1,
+              }}
+            >
+              <span style={{ fontSize: '16px' }}>{successMessage ? '✓' : '⚠'}</span>
+              <span
+                style={{
+                  fontSize: '14px',
+                  fontWeight: '600',
+                  color: successMessage ? 'rgba(34, 197, 94, 1)' : 'rgba(239, 68, 68, 1)',
+                }}
+              >
+                {successMessage || errorMessage}
+              </span>
+            </div>
+            <button
+              type="button"
+              onClick={() => {
+                setSuccessMessage('')
+                setErrorMessage('')
+              }}
+              style={{
+                background: 'none',
+                border: 'none',
+                color: successMessage ? 'rgba(34, 197, 94, 0.8)' : 'rgba(239, 68, 68, 0.8)',
+                fontSize: '18px',
+                cursor: 'pointer',
+                padding: '0 4px',
+                lineHeight: 1,
+              }}
+              onMouseEnter={(e) => {
+                e.currentTarget.style.opacity = '1'
+              }}
+              onMouseLeave={(e) => {
+                e.currentTarget.style.opacity = '0.8'
+              }}
+            >
+              ✕
+            </button>
+          </div>
+        )}
+
         {/* Tabs */}
         <div
           style={{
@@ -375,7 +637,7 @@ export function ModerationPanel({
             borderBottom: '1px solid rgba(75, 85, 99, 0.3)',
           }}
         >
-          {(['members', 'bans', 'history'] as Tab[]).map((tab) => (
+          {(['members', 'bans', 'history', 'settings'] as Tab[]).map((tab) => (
             <button
               key={tab}
               type="button"
@@ -415,6 +677,26 @@ export function ModerationPanel({
               )}
               {tab === 'bans' && `Banned (${bans.length})`}
               {tab === 'history' && `History (${historicalMembers.length})`}
+              {tab === 'settings' && (
+                <span>
+                  ⚙️ Settings
+                  {joinRequests.filter((r: any) => r.status === 'pending').length > 0 && (
+                    <span
+                      style={{
+                        marginLeft: '6px',
+                        padding: '2px 6px',
+                        borderRadius: '10px',
+                        background: 'rgba(59, 130, 246, 0.8)',
+                        color: 'white',
+                        fontSize: '11px',
+                        fontWeight: '700',
+                      }}
+                    >
+                      {joinRequests.filter((r: any) => r.status === 'pending').length} pending
+                    </span>
+                  )}
+                </span>
+              )}
             </button>
           ))}
         </div>
@@ -1139,29 +1421,477 @@ export function ModerationPanel({
                 )}
               </div>
             )}
+
+            {/* Settings Tab */}
+            {activeTab === 'settings' && (
+              <div style={{ display: 'flex', flexDirection: 'column', gap: '24px' }}>
+                {/* Access Mode Section */}
+                <div>
+                  <div
+                    style={{
+                      fontSize: '14px',
+                      fontWeight: '700',
+                      color: 'rgba(253, 186, 116, 1)',
+                      marginBottom: '12px',
+                      textTransform: 'uppercase',
+                      letterSpacing: '0.5px',
+                    }}
+                  >
+                    🔒 Room Access Mode
+                  </div>
+
+                  <div
+                    style={{
+                      padding: '16px',
+                      background: 'rgba(255, 255, 255, 0.05)',
+                      border: '1px solid rgba(75, 85, 99, 0.3)',
+                      borderRadius: '8px',
+                    }}
+                  >
+                    {/* Access mode button grid */}
+                    <div
+                      style={{
+                        display: 'grid',
+                        gridTemplateColumns: '1fr 1fr',
+                        gap: '8px',
+                        marginBottom: '12px',
+                      }}
+                    >
+                      {[
+                        { value: 'open', emoji: '🌐', label: 'Open', desc: 'Anyone' },
+                        { value: 'password', emoji: '🔑', label: 'Password', desc: 'With key' },
+                        { value: 'approval-only', emoji: '✋', label: 'Approval', desc: 'Request' },
+                        {
+                          value: 'restricted',
+                          emoji: '🚫',
+                          label: 'Restricted',
+                          desc: 'Invite only',
+                        },
+                        { value: 'locked', emoji: '🔒', label: 'Locked', desc: 'No new members' },
+                        { value: 'retired', emoji: '🏁', label: 'Retired', desc: 'Closed' },
+                      ].map((mode) => (
+                        <button
+                          key={mode.value}
+                          type="button"
+                          disabled={actionLoading === 'update-settings'}
+                          onClick={() => {
+                            setAccessMode(mode.value)
+                            setShowPasswordInput(mode.value === 'password')
+                          }}
+                          style={{
+                            padding: '10px 12px',
+                            background:
+                              accessMode === mode.value
+                                ? 'rgba(253, 186, 116, 0.15)'
+                                : 'rgba(255, 255, 255, 0.05)',
+                            border:
+                              accessMode === mode.value
+                                ? '2px solid rgba(253, 186, 116, 0.6)'
+                                : '2px solid rgba(75, 85, 99, 0.5)',
+                            borderRadius: '8px',
+                            color:
+                              accessMode === mode.value
+                                ? 'rgba(253, 186, 116, 1)'
+                                : 'rgba(209, 213, 219, 0.8)',
+                            fontSize: '13px',
+                            fontWeight: '500',
+                            cursor: actionLoading === 'update-settings' ? 'not-allowed' : 'pointer',
+                            opacity: actionLoading === 'update-settings' ? 0.5 : 1,
+                            transition: 'all 0.2s ease',
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: '8px',
+                          }}
+                          onMouseEnter={(e) => {
+                            if (actionLoading !== 'update-settings' && accessMode !== mode.value) {
+                              e.currentTarget.style.background = 'rgba(255, 255, 255, 0.08)'
+                              e.currentTarget.style.borderColor = 'rgba(253, 186, 116, 0.4)'
+                            }
+                          }}
+                          onMouseLeave={(e) => {
+                            if (accessMode !== mode.value) {
+                              e.currentTarget.style.background = 'rgba(255, 255, 255, 0.05)'
+                              e.currentTarget.style.borderColor = 'rgba(75, 85, 99, 0.5)'
+                            }
+                          }}
+                        >
+                          <span style={{ fontSize: '18px' }}>{mode.emoji}</span>
+                          <div style={{ textAlign: 'left', flex: 1, lineHeight: '1.2' }}>
+                            <div style={{ fontSize: '13px', fontWeight: '600' }}>{mode.label}</div>
+                            <div style={{ fontSize: '11px', opacity: 0.7 }}>{mode.desc}</div>
+                          </div>
+                        </button>
+                      ))}
+                    </div>
+
+                    {/* Password input (conditional) */}
+                    {(accessMode === 'password' || showPasswordInput) && (
+                      <div style={{ marginBottom: '12px' }}>
+                        <label
+                          style={{
+                            display: 'block',
+                            fontSize: '12px',
+                            fontWeight: '600',
+                            color: 'rgba(209, 213, 219, 0.8)',
+                            marginBottom: '6px',
+                          }}
+                        >
+                          Room Password
+                        </label>
+                        <div style={{ display: 'flex', gap: '8px' }}>
+                          <input
+                            type="text"
+                            value={roomPassword}
+                            onChange={(e) => setRoomPassword(e.target.value)}
+                            placeholder="Enter password to share with guests"
+                            style={{
+                              flex: 1,
+                              padding: '10px 12px',
+                              background: 'rgba(255, 255, 255, 0.05)',
+                              border: '1px solid rgba(75, 85, 99, 0.5)',
+                              borderRadius: '6px',
+                              color: 'rgba(209, 213, 219, 1)',
+                              fontSize: '14px',
+                              outline: 'none',
+                              transition: 'border-color 0.2s ease',
+                            }}
+                            onFocus={(e) => {
+                              e.currentTarget.style.borderColor = 'rgba(253, 186, 116, 0.6)'
+                            }}
+                            onBlur={(e) => {
+                              e.currentTarget.style.borderColor = 'rgba(75, 85, 99, 0.5)'
+                            }}
+                          />
+                          <button
+                            type="button"
+                            onClick={handleCopyPassword}
+                            disabled={!roomPassword}
+                            title="Copy password to clipboard"
+                            style={{
+                              padding: '10px 16px',
+                              background: passwordCopied
+                                ? 'rgba(34, 197, 94, 0.2)'
+                                : roomPassword
+                                  ? 'rgba(59, 130, 246, 0.2)'
+                                  : 'rgba(75, 85, 99, 0.2)',
+                              color: passwordCopied
+                                ? 'rgba(34, 197, 94, 1)'
+                                : roomPassword
+                                  ? 'rgba(59, 130, 246, 1)'
+                                  : 'rgba(156, 163, 175, 1)',
+                              border: passwordCopied
+                                ? '1px solid rgba(34, 197, 94, 0.4)'
+                                : roomPassword
+                                  ? '1px solid rgba(59, 130, 246, 0.4)'
+                                  : '1px solid rgba(75, 85, 99, 0.3)',
+                              borderRadius: '6px',
+                              fontSize: '14px',
+                              fontWeight: '600',
+                              cursor: roomPassword ? 'pointer' : 'not-allowed',
+                              opacity: roomPassword ? 1 : 0.5,
+                              transition: 'all 0.2s ease',
+                              whiteSpace: 'nowrap',
+                            }}
+                            onMouseEnter={(e) => {
+                              if (roomPassword && !passwordCopied) {
+                                e.currentTarget.style.background = 'rgba(59, 130, 246, 0.3)'
+                              }
+                            }}
+                            onMouseLeave={(e) => {
+                              if (roomPassword && !passwordCopied) {
+                                e.currentTarget.style.background = 'rgba(59, 130, 246, 0.2)'
+                              }
+                            }}
+                          >
+                            {passwordCopied ? '✓ Copied!' : '📋 Copy'}
+                          </button>
+                        </div>
+                        <div
+                          style={{
+                            fontSize: '11px',
+                            color: 'rgba(156, 163, 175, 1)',
+                            marginTop: '4px',
+                          }}
+                        >
+                          Share this password with guests to allow them to join
+                        </div>
+                      </div>
+                    )}
+
+                    {hasUnsavedAccessModeChanges && (
+                      <button
+                        type="button"
+                        onClick={handleUpdateAccessMode}
+                        disabled={actionLoading === 'update-settings'}
+                        style={{
+                          width: '100%',
+                          padding: '10px',
+                          background:
+                            actionLoading === 'update-settings'
+                              ? 'rgba(75, 85, 99, 0.3)'
+                              : 'linear-gradient(135deg, rgba(59, 130, 246, 0.8), rgba(37, 99, 235, 0.8))',
+                          color: 'white',
+                          border:
+                            actionLoading === 'update-settings'
+                              ? '1px solid rgba(75, 85, 99, 0.5)'
+                              : '1px solid rgba(59, 130, 246, 0.6)',
+                          borderRadius: '6px',
+                          fontSize: '14px',
+                          fontWeight: '600',
+                          cursor: actionLoading === 'update-settings' ? 'not-allowed' : 'pointer',
+                          opacity: actionLoading === 'update-settings' ? 0.5 : 1,
+                        }}
+                      >
+                        {actionLoading === 'update-settings' ? 'Updating...' : 'Update Access Mode'}
+                      </button>
+                    )}
+                  </div>
+                </div>
+
+                {/* Join Requests Section (for approval-only mode) */}
+                {joinRequests.filter((r: any) => r.status === 'pending').length > 0 && (
+                  <div>
+                    <div
+                      style={{
+                        fontSize: '14px',
+                        fontWeight: '700',
+                        color: 'rgba(59, 130, 246, 1)',
+                        marginBottom: '12px',
+                        textTransform: 'uppercase',
+                        letterSpacing: '0.5px',
+                      }}
+                    >
+                      🙋 Pending Join Requests
+                    </div>
+
+                    <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+                      {joinRequests
+                        .filter((r: any) => r.status === 'pending')
+                        .map((request: any) => (
+                          <div
+                            key={request.id}
+                            style={{
+                              padding: '12px',
+                              background: 'rgba(59, 130, 246, 0.08)',
+                              border: '1px solid rgba(59, 130, 246, 0.3)',
+                              borderRadius: '8px',
+                              display: 'flex',
+                              alignItems: 'center',
+                              justifyContent: 'space-between',
+                            }}
+                          >
+                            <div>
+                              <div
+                                style={{
+                                  fontSize: '14px',
+                                  fontWeight: '600',
+                                  color: 'rgba(209, 213, 219, 1)',
+                                }}
+                              >
+                                {request.userName || 'Anonymous User'}
+                              </div>
+                              <div
+                                style={{
+                                  fontSize: '12px',
+                                  color: 'rgba(156, 163, 175, 1)',
+                                  marginTop: '2px',
+                                }}
+                              >
+                                Requested {new Date(request.createdAt).toLocaleString()}
+                              </div>
+                            </div>
+
+                            <div style={{ display: 'flex', gap: '8px' }}>
+                              <button
+                                type="button"
+                                onClick={() => handleDenyJoinRequest(request.id)}
+                                disabled={actionLoading === `deny-request-${request.id}`}
+                                style={{
+                                  padding: '6px 12px',
+                                  background: 'rgba(239, 68, 68, 0.2)',
+                                  color: 'rgba(239, 68, 68, 1)',
+                                  border: '1px solid rgba(239, 68, 68, 0.4)',
+                                  borderRadius: '6px',
+                                  fontSize: '13px',
+                                  fontWeight: '600',
+                                  cursor:
+                                    actionLoading === `deny-request-${request.id}`
+                                      ? 'not-allowed'
+                                      : 'pointer',
+                                  opacity: actionLoading === `deny-request-${request.id}` ? 0.5 : 1,
+                                }}
+                              >
+                                {actionLoading === `deny-request-${request.id}`
+                                  ? 'Denying...'
+                                  : 'Deny'}
+                              </button>
+                              <button
+                                type="button"
+                                onClick={() => handleApproveJoinRequest(request.id)}
+                                disabled={actionLoading === `approve-request-${request.id}`}
+                                style={{
+                                  padding: '6px 12px',
+                                  background: 'rgba(34, 197, 94, 0.2)',
+                                  color: 'rgba(34, 197, 94, 1)',
+                                  border: '1px solid rgba(34, 197, 94, 0.4)',
+                                  borderRadius: '6px',
+                                  fontSize: '13px',
+                                  fontWeight: '600',
+                                  cursor:
+                                    actionLoading === `approve-request-${request.id}`
+                                      ? 'not-allowed'
+                                      : 'pointer',
+                                  opacity:
+                                    actionLoading === `approve-request-${request.id}` ? 0.5 : 1,
+                                }}
+                              >
+                                {actionLoading === `approve-request-${request.id}`
+                                  ? 'Approving...'
+                                  : 'Approve'}
+                              </button>
+                            </div>
+                          </div>
+                        ))}
+                    </div>
+                  </div>
+                )}
+
+                {/* Transfer Ownership Section */}
+                <div>
+                  <div
+                    style={{
+                      fontSize: '14px',
+                      fontWeight: '700',
+                      color: 'rgba(251, 146, 60, 1)',
+                      marginBottom: '12px',
+                      textTransform: 'uppercase',
+                      letterSpacing: '0.5px',
+                    }}
+                  >
+                    👑 Transfer Ownership
+                  </div>
+
+                  <div
+                    style={{
+                      padding: '16px',
+                      background: 'rgba(251, 146, 60, 0.08)',
+                      border: '1px solid rgba(251, 146, 60, 0.3)',
+                      borderRadius: '8px',
+                    }}
+                  >
+                    <p
+                      style={{
+                        fontSize: '13px',
+                        color: 'rgba(209, 213, 219, 0.8)',
+                        marginBottom: '12px',
+                      }}
+                    >
+                      Transfer host privileges to another member. You will no longer be the host.
+                    </p>
+
+                    <select
+                      value={selectedNewOwner}
+                      onChange={(e) => setSelectedNewOwner(e.target.value)}
+                      style={{
+                        width: '100%',
+                        padding: '10px',
+                        background: 'rgba(255, 255, 255, 0.05)',
+                        border: '1px solid rgba(75, 85, 99, 0.5)',
+                        borderRadius: '6px',
+                        color: 'rgba(209, 213, 219, 1)',
+                        fontSize: '14px',
+                        marginBottom: '12px',
+                        cursor: 'pointer',
+                      }}
+                    >
+                      <option value="">Select new owner...</option>
+                      {otherMembers.map((member) => (
+                        <option key={member.userId} value={member.userId}>
+                          {member.displayName}
+                          {member.isOnline ? ' (Online)' : ' (Offline)'}
+                        </option>
+                      ))}
+                    </select>
+
+                    <button
+                      type="button"
+                      onClick={handleTransferOwnership}
+                      disabled={!selectedNewOwner || actionLoading === 'transfer-ownership'}
+                      style={{
+                        width: '100%',
+                        padding: '10px',
+                        background:
+                          !selectedNewOwner || actionLoading === 'transfer-ownership'
+                            ? 'rgba(75, 85, 99, 0.3)'
+                            : 'linear-gradient(135deg, rgba(251, 146, 60, 0.8), rgba(249, 115, 22, 0.8))',
+                        color: 'white',
+                        border:
+                          !selectedNewOwner || actionLoading === 'transfer-ownership'
+                            ? '1px solid rgba(75, 85, 99, 0.5)'
+                            : '1px solid rgba(251, 146, 60, 0.6)',
+                        borderRadius: '6px',
+                        fontSize: '14px',
+                        fontWeight: '600',
+                        cursor:
+                          !selectedNewOwner || actionLoading === 'transfer-ownership'
+                            ? 'not-allowed'
+                            : 'pointer',
+                        opacity:
+                          !selectedNewOwner || actionLoading === 'transfer-ownership' ? 0.5 : 1,
+                      }}
+                    >
+                      {actionLoading === 'transfer-ownership'
+                        ? 'Transferring...'
+                        : 'Transfer Ownership'}
+                    </button>
+                  </div>
+                </div>
+              </div>
+            )}
           </div>
         )}
 
         <div style={{ display: 'flex', justifyContent: 'flex-end', marginTop: '20px' }}>
           <button
             type="button"
-            onClick={onClose}
+            onClick={hasUnsavedAccessModeChanges ? undefined : onClose}
+            disabled={hasUnsavedAccessModeChanges}
+            title={
+              hasUnsavedAccessModeChanges
+                ? 'Please update access mode settings before closing'
+                : undefined
+            }
             style={{
               padding: '10px 20px',
-              background: 'rgba(75, 85, 99, 0.3)',
-              color: 'rgba(209, 213, 219, 1)',
-              border: '1px solid rgba(75, 85, 99, 0.5)',
+              background: hasUnsavedAccessModeChanges
+                ? 'rgba(75, 85, 99, 0.2)'
+                : 'rgba(75, 85, 99, 0.3)',
+              color: hasUnsavedAccessModeChanges
+                ? 'rgba(156, 163, 175, 1)'
+                : 'rgba(209, 213, 219, 1)',
+              border: hasUnsavedAccessModeChanges
+                ? '1px solid rgba(251, 146, 60, 0.4)'
+                : '1px solid rgba(75, 85, 99, 0.5)',
               borderRadius: '10px',
               fontSize: '14px',
               fontWeight: '600',
-              cursor: 'pointer',
+              cursor: hasUnsavedAccessModeChanges ? 'not-allowed' : 'pointer',
+              opacity: hasUnsavedAccessModeChanges ? 0.6 : 1,
               transition: 'all 0.2s ease',
             }}
             onMouseEnter={(e) => {
-              e.currentTarget.style.background = 'rgba(75, 85, 99, 0.4)'
+              if (!hasUnsavedAccessModeChanges) {
+                e.currentTarget.style.background = 'rgba(75, 85, 99, 0.4)'
+              } else {
+                e.currentTarget.style.borderColor = 'rgba(251, 146, 60, 0.8)'
+              }
             }}
             onMouseLeave={(e) => {
-              e.currentTarget.style.background = 'rgba(75, 85, 99, 0.3)'
+              if (!hasUnsavedAccessModeChanges) {
+                e.currentTarget.style.background = 'rgba(75, 85, 99, 0.3)'
+              } else {
+                e.currentTarget.style.borderColor = 'rgba(251, 146, 60, 0.4)'
+              }
             }}
           >
             Close

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

@@ -1,4 +1,4 @@
-import React, { useState } from 'react'
+import { useState } from 'react'
 import { PlayerTooltip } from './PlayerTooltip'
 import { ReportPlayerModal } from './ReportPlayerModal'
 

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

@@ -1,5 +1,6 @@
 import { useRouter } from 'next/navigation'
 import { useEffect, useState } from 'react'
+import { useToast } from '@/components/common/ToastContext'
 import { useJoinRoom } from '@/hooks/useRoomData'
 
 interface PendingInvitation {
@@ -32,6 +33,7 @@ export interface PendingInvitationsProps {
  */
 export function PendingInvitations({ onInvitationChange, currentRoomId }: PendingInvitationsProps) {
   const router = useRouter()
+  const { showError } = useToast()
   const [invitations, setInvitations] = useState<PendingInvitation[]>([])
   const [isLoading, setIsLoading] = useState(true)
   const [error, setError] = useState('')
@@ -72,7 +74,7 @@ export function PendingInvitations({ onInvitationChange, currentRoomId }: Pendin
       onInvitationChange?.()
     } catch (error) {
       console.error('Failed to join room:', error)
-      alert(error instanceof Error ? error.message : 'Failed to join room')
+      showError('Failed to join room', error instanceof Error ? error.message : undefined)
     } finally {
       setActionLoading(null)
     }
@@ -97,7 +99,7 @@ export function PendingInvitations({ onInvitationChange, currentRoomId }: Pendin
       onInvitationChange?.()
     } catch (error) {
       console.error('Failed to decline invitation:', error)
-      alert(error instanceof Error ? error.message : 'Failed to decline invitation')
+      showError('Failed to decline invitation', error instanceof Error ? error.message : undefined)
     } finally {
       setActionLoading(null)
     }

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

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from 'react'
 import { EmojiPicker } from '../../app/games/matching/components/EmojiPicker'
 import { useGameMode } from '../../contexts/GameModeContext'
+import { generateUniquePlayerName } from '../../utils/playerNames'
 
 interface PlayerConfigDialogProps {
   playerId: string
@@ -48,6 +49,15 @@ export function PlayerConfigDialog({ playerId, onClose }: PlayerConfigDialogProp
     setShowEmojiPicker(false)
   }
 
+  const handleGenerateNewName = () => {
+    const allPlayers = Array.from(players.values())
+    const existingNames = allPlayers.filter((p) => p.id !== playerId).map((p) => p.name)
+    const newName = generateUniquePlayerName(existingNames, player.emoji)
+
+    setLocalName(newName)
+    updatePlayer(playerId, { name: newName })
+  }
+
   // Get player number for UI theming (first 4 players get special colors)
   const allPlayers = Array.from(players.values()).sort((a, b) => {
     const aTime =
@@ -256,40 +266,89 @@ export function PlayerConfigDialog({ playerId, onClose }: PlayerConfigDialogProp
           >
             Name
           </label>
-          <input
-            type="text"
-            value={localName}
-            onChange={(e) => handleNameChange(e.target.value)}
-            placeholder="Player Name"
-            maxLength={20}
-            style={{
-              width: '100%',
-              padding: '12px 16px',
-              fontSize: '16px',
-              border: '2px solid #e5e7eb',
-              borderRadius: '12px',
-              outline: 'none',
-              transition: 'all 0.2s ease',
-              fontWeight: '500',
-            }}
-            onFocus={(e) => {
-              e.currentTarget.style.borderColor = gradientColor
-              e.currentTarget.style.boxShadow = `0 0 0 3px ${gradientColor}20`
-            }}
-            onBlur={(e) => {
-              e.currentTarget.style.borderColor = '#e5e7eb'
-              e.currentTarget.style.boxShadow = 'none'
-            }}
-          />
           <div
             style={{
-              fontSize: '12px',
-              color: '#6b7280',
-              marginTop: '4px',
-              textAlign: 'right',
+              display: 'flex',
+              gap: '8px',
+              alignItems: 'flex-start',
             }}
           >
-            {localName.length}/20 characters
+            <div style={{ flex: 1 }}>
+              <input
+                type="text"
+                value={localName}
+                onChange={(e) => handleNameChange(e.target.value)}
+                placeholder="Player Name"
+                maxLength={20}
+                style={{
+                  width: '100%',
+                  padding: '12px 16px',
+                  fontSize: '16px',
+                  border: '2px solid #e5e7eb',
+                  borderRadius: '12px',
+                  outline: 'none',
+                  transition: 'all 0.2s ease',
+                  fontWeight: '500',
+                }}
+                onFocus={(e) => {
+                  e.currentTarget.style.borderColor = gradientColor
+                  e.currentTarget.style.boxShadow = `0 0 0 3px ${gradientColor}20`
+                }}
+                onBlur={(e) => {
+                  e.currentTarget.style.borderColor = '#e5e7eb'
+                  e.currentTarget.style.boxShadow = 'none'
+                }}
+              />
+              <div
+                style={{
+                  fontSize: '12px',
+                  color: '#6b7280',
+                  marginTop: '6px',
+                }}
+              >
+                {localName.length}/20 characters
+              </div>
+            </div>
+            <div style={{ flexShrink: 0 }}>
+              <button
+                type="button"
+                onClick={handleGenerateNewName}
+                style={{
+                  padding: '12px 16px',
+                  background: `linear-gradient(135deg, ${gradientColor}, ${gradientColor}dd)`,
+                  border: 'none',
+                  borderRadius: '12px',
+                  color: 'white',
+                  fontSize: '20px',
+                  cursor: 'pointer',
+                  transition: 'all 0.2s ease',
+                  display: 'flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                }}
+                onMouseEnter={(e) => {
+                  e.currentTarget.style.transform = 'scale(1.05)'
+                  e.currentTarget.style.boxShadow = `0 4px 12px ${gradientColor}40`
+                }}
+                onMouseLeave={(e) => {
+                  e.currentTarget.style.transform = 'scale(1)'
+                  e.currentTarget.style.boxShadow = 'none'
+                }}
+                title="Generate random name"
+              >
+                🎲
+              </button>
+              <div
+                style={{
+                  fontSize: '12px',
+                  color: '#6b7280',
+                  marginTop: '6px',
+                  textAlign: 'center',
+                }}
+              >
+                Random name
+              </div>
+            </div>
           </div>
         </div>
       </div>

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

@@ -1,9 +1,10 @@
 import React from 'react'
+import { getRoomDisplayWithEmoji } from '@/utils/room-display'
 
 interface RecentRoom {
   code: string
-  name: string
-  gameName: string
+  name: string | null
+  gameName: string | null
   joinedAt: number
 }
 
@@ -100,7 +101,13 @@ export function RecentRoomsList({ onSelectRoom }: RecentRoomsListProps) {
               }}
             >
               <span>🏟️</span>
-              <span>{room.name}</span>
+              <span>
+                {getRoomDisplayWithEmoji({
+                  name: room.name,
+                  code: room.code,
+                  gameName: room.gameName ?? undefined,
+                })}
+              </span>
             </div>
             <div
               style={{
@@ -123,7 +130,11 @@ export function RecentRoomsList({ onSelectRoom }: RecentRoomsListProps) {
 }
 
 // Helper function to add a room to recent rooms
-export function addToRecentRooms(room: { code: string; name: string; gameName: string }): void {
+export function addToRecentRooms(room: {
+  code: string
+  name: string | null
+  gameName: string | null
+}): void {
   try {
     const stored = localStorage.getItem(STORAGE_KEY)
     const rooms: RecentRoom[] = stored ? JSON.parse(stored) : []

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

@@ -1,8 +1,9 @@
 import * as DropdownMenu from '@radix-ui/react-dropdown-menu'
 import { useRouter } from 'next/navigation'
 import { useEffect, useState } from 'react'
-import { useLeaveRoom, useRoomData } from '@/hooks/useRoomData'
+import { useClearRoomGame, useLeaveRoom, useRoomData } from '@/hooks/useRoomData'
 import { useViewerId } from '@/hooks/useViewerId'
+import { getRoomDisplayWithEmoji } from '@/utils/room-display'
 import { CreateRoomModal } from './CreateRoomModal'
 import { JoinRoomModal } from './JoinRoomModal'
 import { ModerationPanel } from './ModerationPanel'
@@ -11,7 +12,7 @@ import { RoomShareButtons } from './RoomShareButtons'
 type GameMode = 'none' | 'single' | 'battle' | 'tournament'
 
 interface RoomInfoProps {
-  roomName?: string
+  roomName?: string | null
   gameName: string
   playerCount: number
   joinCode?: string
@@ -57,11 +58,16 @@ export function RoomInfo({
   const [showModerationPanel, setShowModerationPanel] = useState(false)
   const [focusedUserId, setFocusedUserId] = useState<string | undefined>(undefined)
   const [pendingReportsCount, setPendingReportsCount] = useState(0)
+  const [pendingJoinRequestsCount, setPendingJoinRequestsCount] = useState(0)
   const { getRoomShareUrl, roomData } = useRoomData()
   const { data: currentUserId } = useViewerId()
   const { mutateAsync: leaveRoom } = useLeaveRoom()
+  const { mutate: clearRoomGame } = useClearRoomGame()
 
-  const displayName = roomName || gameName
+  // Use room display utility for consistent naming
+  const displayName = joinCode
+    ? getRoomDisplayWithEmoji({ name: roomName || null, code: joinCode, gameName })
+    : roomName || gameName
   const shareUrl = joinCode ? getRoomShareUrl(joinCode) : ''
 
   // Determine ownership status
@@ -93,6 +99,29 @@ export function RoomInfo({
     return () => clearInterval(interval)
   }, [isCurrentUserCreator, roomId])
 
+  // Fetch pending join requests count if user is host
+  useEffect(() => {
+    if (!isCurrentUserCreator || !roomId) return
+
+    const fetchPendingJoinRequests = async () => {
+      try {
+        const res = await fetch(`/api/arcade/rooms/${roomId}/join-requests`)
+        if (res.ok) {
+          const data = await res.json()
+          const pending = data.requests?.filter((r: any) => r.status === 'pending') || []
+          setPendingJoinRequestsCount(pending.length)
+        }
+      } catch (error) {
+        console.error('[RoomInfo] Failed to fetch join requests:', error)
+      }
+    }
+
+    fetchPendingJoinRequests()
+    // Poll every 30 seconds
+    const interval = setInterval(fetchPendingJoinRequests, 30000)
+    return () => clearInterval(interval)
+  }, [isCurrentUserCreator, roomId])
+
   // Listen for moderation events to update report count in real-time
   const { moderationEvent } = useRoomData()
   useEffect(() => {
@@ -235,8 +264,8 @@ export function RoomInfo({
                 >
                   <span style={{ fontSize: '10px', lineHeight: 1 }}>👑</span>
                   <span style={{ lineHeight: 1 }}>You are host</span>
-                  {/* Pending reports badge */}
-                  {pendingReportsCount > 0 && (
+                  {/* Pending items badge (reports + join requests) */}
+                  {(pendingReportsCount > 0 || pendingJoinRequestsCount > 0) && (
                     <span
                       style={{
                         display: 'inline-flex',
@@ -245,15 +274,24 @@ export function RoomInfo({
                         width: '16px',
                         height: '16px',
                         borderRadius: '50%',
-                        background: 'rgba(239, 68, 68, 1)',
+                        background:
+                          pendingJoinRequestsCount > 0
+                            ? 'rgba(59, 130, 246, 1)'
+                            : 'rgba(239, 68, 68, 1)',
                         color: 'white',
                         fontSize: '8px',
                         fontWeight: '700',
                         marginLeft: '2px',
                       }}
-                      title={`${pendingReportsCount} pending report${pendingReportsCount > 1 ? 's' : ''}`}
+                      title={
+                        pendingJoinRequestsCount > 0 && pendingReportsCount > 0
+                          ? `${pendingJoinRequestsCount} join request${pendingJoinRequestsCount > 1 ? 's' : ''}, ${pendingReportsCount} report${pendingReportsCount > 1 ? 's' : ''}`
+                          : pendingJoinRequestsCount > 0
+                            ? `${pendingJoinRequestsCount} join request${pendingJoinRequestsCount > 1 ? 's' : ''}`
+                            : `${pendingReportsCount} report${pendingReportsCount > 1 ? 's' : ''}`
+                      }
                     >
-                      {pendingReportsCount}
+                      {pendingReportsCount + pendingJoinRequestsCount}
                     </span>
                   )}
                 </div>
@@ -366,6 +404,43 @@ export function RoomInfo({
               </DropdownMenu.Item>
             )}
 
+            {/* Change Game - only show for host and only when a game is selected */}
+            {isCurrentUserCreator && roomId && roomData?.gameName && (
+              <DropdownMenu.Item
+                onSelect={() => {
+                  if (roomId) {
+                    clearRoomGame(roomId)
+                  }
+                }}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: '10px',
+                  padding: '10px 14px',
+                  borderRadius: '8px',
+                  border: 'none',
+                  background: 'transparent',
+                  color: 'rgba(209, 213, 219, 1)',
+                  fontSize: '14px',
+                  fontWeight: '500',
+                  cursor: 'pointer',
+                  outline: 'none',
+                  transition: 'all 0.2s ease',
+                }}
+                onMouseEnter={(e) => {
+                  e.currentTarget.style.background = 'rgba(236, 72, 153, 0.2)'
+                  e.currentTarget.style.color = 'rgba(249, 168, 212, 1)'
+                }}
+                onMouseLeave={(e) => {
+                  e.currentTarget.style.background = 'transparent'
+                  e.currentTarget.style.color = 'rgba(209, 213, 219, 1)'
+                }}
+              >
+                <span style={{ fontSize: '16px' }}>🔄</span>
+                <span>Change Game</span>
+              </DropdownMenu.Item>
+            )}
+
             {/* Moderation - only show for host */}
             {isCurrentUserCreator && roomId && (
               <DropdownMenu.Item

apps/web/src/constants/playerEmojis.ts

@@ -1,5 +1,8 @@
 // Available character emojis for players
 export const PLAYER_EMOJIS = [
+  // Abacus
+  '🧮',
+
   // People & Characters
   '😀',
   '😃',

apps/web/src/contexts/GameModeContext.tsx

@@ -2,15 +2,16 @@
 
 import { createContext, type ReactNode, useContext, useEffect, useMemo, useState } from 'react'
 import type { Player as DBPlayer } from '@/db/schema/players'
+import { useRoomData } from '@/hooks/useRoomData'
 import {
   useCreatePlayer,
   useDeletePlayer,
   useUpdatePlayer,
   useUserPlayers,
 } from '@/hooks/useUserPlayers'
-import { useRoomData } from '@/hooks/useRoomData'
 import { useViewerId } from '@/hooks/useViewerId'
 import { getNextPlayerColor } from '../types/player'
+import { generateUniquePlayerName } from '../utils/playerNames'
 
 // Client-side Player type (compatible with old type)
 export interface Player {
@@ -44,11 +45,12 @@ export interface GameModeContextType {
 const GameModeContext = createContext<GameModeContextType | null>(null)
 
 // Default players to create if none exist
-const DEFAULT_PLAYERS = [
-  { name: 'Player 1', emoji: '😀', color: '#3b82f6' },
-  { name: 'Player 2', emoji: '😎', color: '#8b5cf6' },
-  { name: 'Player 3', emoji: '🤠', color: '#10b981' },
-  { name: 'Player 4', emoji: '🚀', color: '#f59e0b' },
+// Names are generated randomly on first initialization
+const DEFAULT_PLAYER_CONFIGS = [
+  { emoji: '😀', color: '#3b82f6' },
+  { emoji: '😎', color: '#8b5cf6' },
+  { emoji: '🤠', color: '#10b981' },
+  { emoji: '🚀', color: '#f59e0b' },
 ]
 
 // Convert DB player to client Player type
@@ -139,14 +141,24 @@ export function GameModeProvider({ children }: { children: ReactNode }) {
   useEffect(() => {
     if (!isLoading && !isInitialized) {
       if (dbPlayers.length === 0) {
-        // Create default players
-        DEFAULT_PLAYERS.forEach((data, index) => {
+        // 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) => {
           createPlayer({
-            ...data,
+            name: generatedNames[index],
+            emoji: config.emoji,
+            color: config.color,
             isActive: index === 0, // First player active by default
           })
         })
-        console.log('✅ Created default players via API')
+        console.log('✅ Created default players via API with auto-generated names:', generatedNames)
       } else {
         console.log('✅ Loaded players from API', {
           playerCount: dbPlayers.length,
@@ -159,10 +171,12 @@ 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 ?? `Player ${players.size + 1}`,
-      emoji: playerData?.emoji ?? '🎮',
+      name: playerData?.name ?? generateUniquePlayerName(existingNames, emoji),
+      emoji,
       color: playerData?.color ?? getNextPlayerColor(playerList),
       isActive: playerData?.isActive ?? false,
     }
@@ -246,10 +260,20 @@ export function GameModeProvider({ children }: { children: ReactNode }) {
       deletePlayer(player.id)
     })
 
-    // Create default players
-    DEFAULT_PLAYERS.forEach((data, index) => {
+    // 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) => {
       createPlayer({
-        ...data,
+        name: generatedNames[index],
+        emoji: config.emoji,
+        color: config.color,
         isActive: index === 0,
       })
     })

apps/web/src/db/schema/arcade-rooms.ts

@@ -8,7 +8,7 @@ export const arcadeRooms = sqliteTable('arcade_rooms', {
 
   // Room identity
   code: text('code', { length: 6 }).notNull().unique(), // e.g., "ABC123"
-  name: text('name', { length: 50 }).notNull(),
+  name: text('name', { length: 50 }), // Optional: auto-generates from code and game if null
 
   // Creator info
   createdBy: text('created_by').notNull(), // User/guest ID
@@ -30,12 +30,12 @@ export const arcadeRooms = sqliteTable('arcade_rooms', {
     .notNull()
     .default('open'),
   password: text('password', { length: 255 }), // Hashed password for password-protected rooms
+  displayPassword: text('display_password', { length: 100 }), // Plain text password for display to room owner
 
-  // Game configuration
-  gameName: text('game_name', {
-    enum: ['matching', 'memory-quiz', 'complement-race'],
-  }).notNull(),
-  gameConfig: text('game_config', { mode: 'json' }).notNull(), // Game-specific settings
+  // Game configuration (nullable to support game selection in room)
+  // Accepts any string - validation happens at runtime against validator registry
+  gameName: text('game_name'),
+  gameConfig: text('game_config', { mode: 'json' }), // Game-specific settings (nullable when no game selected)
 
   // Current state
   status: text('status', {

apps/web/src/db/schema/arcade-sessions.ts

@@ -16,9 +16,8 @@ export const arcadeSessions = sqliteTable('arcade_sessions', {
     .references(() => users.id, { onDelete: 'cascade' }),
 
   // Session metadata
-  currentGame: text('current_game', {
-    enum: ['matching', 'memory-quiz', 'complement-race'],
-  }).notNull(),
+  // Accepts any string - validation happens at runtime against validator registry
+  currentGame: text('current_game').notNull(),
 
   gameUrl: text('game_url').notNull(), // e.g., '/arcade/matching'
 

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,49 @@
+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
+    // Accepts any string - validation happens at runtime against validator registry
+    gameName: text('game_name').notNull(),
+
+    // Game-specific configuration JSON
+    // Structure depends on gameName:
+    // - matching: { gameType, difficulty, turnTimer }
+    // - memory-quiz: { selectedCount, displayTime, selectedDifficulty, playMode }
+    // - complement-race: TBD
+    // - number-guesser: { minNumber, maxNumber, roundsToWin }
+    // - math-sprint: { difficulty, questionsPerRound, timePerQuestion }
+    config: text('config', { mode: 'json' }).notNull(),
+
+    // Timestamps
+    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/hooks/__tests__/useOptimisticGameState.test.ts

@@ -42,6 +42,7 @@ describe('useOptimisticGameState', () => {
     const move: GameMove = {
       type: 'INCREMENT',
       playerId: 'test',
+      userId: 'test-user',
       timestamp: Date.now(),
       data: {},
     }
@@ -65,6 +66,7 @@ describe('useOptimisticGameState', () => {
     const move: GameMove = {
       type: 'INCREMENT',
       playerId: 'test',
+      userId: 'test-user',
       timestamp: 123,
       data: {},
     }
@@ -100,6 +102,7 @@ describe('useOptimisticGameState', () => {
     const move: GameMove = {
       type: 'INCREMENT',
       playerId: 'test',
+      userId: 'test-user',
       timestamp: 123,
       data: {},
     }
@@ -133,6 +136,7 @@ describe('useOptimisticGameState', () => {
     const move1: GameMove = {
       type: 'INCREMENT',
       playerId: 'test',
+      userId: 'test-user',
       timestamp: 123,
       data: {},
     }
@@ -140,6 +144,7 @@ describe('useOptimisticGameState', () => {
     const move2: GameMove = {
       type: 'INCREMENT',
       playerId: 'test',
+      userId: 'test-user',
       timestamp: 124,
       data: {},
     }
@@ -184,6 +189,7 @@ describe('useOptimisticGameState', () => {
       result.current.applyOptimisticMove({
         type: 'INCREMENT',
         playerId: 'test',
+        userId: 'test-user',
         timestamp: 123,
         data: {},
       })
@@ -215,6 +221,7 @@ describe('useOptimisticGameState', () => {
       result.current.applyOptimisticMove({
         type: 'INCREMENT',
         playerId: 'test',
+        userId: 'test-user',
         timestamp: 123,
         data: {},
       })
@@ -245,6 +252,7 @@ describe('useOptimisticGameState', () => {
     const move: GameMove = {
       type: 'INCREMENT',
       playerId: 'test',
+      userId: 'test-user',
       timestamp: 123,
       data: {},
     }

apps/web/src/hooks/useArcadeSession.ts

@@ -46,6 +46,11 @@ export interface UseArcadeSessionReturn<TState> {
    */
   hasPendingMoves: boolean
 
+  /**
+   * Last error from server (move rejection)
+   */
+  lastError: string | null
+
   /**
    * Send a game move (applies optimistically and sends to server)
    * Note: playerId must be provided by caller (not omitted)
@@ -57,6 +62,11 @@ export interface UseArcadeSessionReturn<TState> {
    */
   exitSession: () => void
 
+  /**
+   * Clear the last error
+   */
+  clearError: () => void
+
   /**
    * Manually sync with server (useful after reconnect)
    */
@@ -172,8 +182,10 @@ export function useArcadeSession<TState>(
     version: optimistic.version,
     connected,
     hasPendingMoves: optimistic.hasPendingMoves,
+    lastError: optimistic.lastError,
     sendMove,
     exitSession,
+    clearError: optimistic.clearError,
     refresh,
   }
 }

apps/web/src/hooks/useOptimisticGameState.ts

@@ -46,6 +46,11 @@ export interface UseOptimisticGameStateReturn<TState> {
    */
   hasPendingMoves: boolean
 
+  /**
+   * Last error from server (move rejection)
+   */
+  lastError: string | null
+
   /**
    * Apply a move optimistically and send to server
    */
@@ -66,6 +71,11 @@ export interface UseOptimisticGameStateReturn<TState> {
    */
   syncWithServer: (serverState: TState, serverVersion: number) => void
 
+  /**
+   * Clear the last error
+   */
+  clearError: () => void
+
   /**
    * Reset to initial state
    */
@@ -94,6 +104,9 @@ export function useOptimisticGameState<TState>(
   // Pending moves that haven't been confirmed by server yet
   const [pendingMoves, setPendingMoves] = useState<PendingMove<TState>[]>([])
 
+  // Last error from move rejection
+  const [lastError, setLastError] = useState<string | null>(null)
+
   // Ref for callbacks to avoid stale closures
   const callbacksRef = useRef({ onMoveAccepted, onMoveRejected })
   useEffect(() => {
@@ -152,6 +165,9 @@ export function useOptimisticGameState<TState>(
   )
 
   const handleMoveRejected = useCallback((error: string, rejectedMove: GameMove) => {
+    // Set the error for UI display
+    setLastError(error)
+
     // Remove the rejected move and all subsequent moves from pending queue
     setPendingMoves((prev) => {
       const index = prev.findIndex(
@@ -176,20 +192,27 @@ export function useOptimisticGameState<TState>(
     setPendingMoves([])
   }, [])
 
+  const clearError = useCallback(() => {
+    setLastError(null)
+  }, [])
+
   const reset = useCallback(() => {
     setServerState(initialState)
     setServerVersion(1)
     setPendingMoves([])
+    setLastError(null)
   }, [initialState])
 
   return {
     state: currentState,
     version: serverVersion,
     hasPendingMoves: pendingMoves.length > 0,
+    lastError,
     applyOptimisticMove,
     handleMoveAccepted,
     handleMoveRejected,
     syncWithServer,
+    clearError,
     reset,
   }
 }

apps/web/src/hooks/useRoomData.ts

@@ -1,5 +1,5 @@
-import { useCallback, useEffect, useState } from 'react'
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { useCallback, useEffect, useState } from 'react'
 import { io, type Socket } from 'socket.io-client'
 import { useViewerId } from './useViewerId'
 
@@ -22,7 +22,8 @@ export interface RoomData {
   id: string
   name: string
   code: string
-  gameName: string
+  gameName: string | null // Nullable to support game selection in room
+  gameConfig?: Record<string, unknown> | null // Game-specific settings
   accessMode: 'open' | 'password' | 'approval-only' | 'restricted' | 'locked' | 'retired'
   members: RoomMember[]
   memberPlayers: Record<string, RoomPlayer[]> // userId -> players
@@ -30,7 +31,7 @@ export interface RoomData {
 
 export interface CreateRoomParams {
   name: string | null
-  gameName: string
+  gameName?: string | null // Optional - rooms can be created without a game
   creatorName?: string
   gameConfig?: Record<string, unknown>
   accessMode?: 'open' | 'password' | 'approval-only' | 'restricted' | 'locked' | 'retired'
@@ -71,6 +72,7 @@ async function fetchCurrentRoom(): Promise<RoomData | null> {
     name: data.room.name,
     code: data.room.code,
     gameName: data.room.gameName,
+    gameConfig: data.room.gameConfig || null,
     accessMode: data.room.accessMode || 'open',
     members: data.members || [],
     memberPlayers: data.memberPlayers || {},
@@ -86,9 +88,9 @@ async function createRoomApi(params: CreateRoomParams): Promise<RoomData> {
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
       name: params.name,
-      gameName: params.gameName,
+      gameName: params.gameName || null,
       creatorName: params.creatorName || 'Player',
-      gameConfig: params.gameConfig || { difficulty: 6 },
+      gameConfig: params.gameConfig || null,
       accessMode: params.accessMode,
       password: params.password,
     }),
@@ -105,6 +107,7 @@ async function createRoomApi(params: CreateRoomParams): Promise<RoomData> {
     name: data.room.name,
     code: data.room.code,
     gameName: data.room.gameName,
+    gameConfig: data.room.gameConfig || null,
     accessMode: data.room.accessMode || 'open',
     members: data.members || [],
     memberPlayers: data.memberPlayers || {},
@@ -141,6 +144,7 @@ async function joinRoomApi(params: {
       name: data.room.name,
       code: data.room.code,
       gameName: data.room.gameName,
+      gameConfig: data.room.gameConfig || null,
       accessMode: data.room.accessMode || 'open',
       members: data.members || [],
       memberPlayers: data.memberPlayers || {},
@@ -183,6 +187,7 @@ async function getRoomByCodeApi(code: string): Promise<RoomData> {
     name: data.room.name,
     code: data.room.code,
     gameName: data.room.gameName,
+    gameConfig: data.room.gameConfig || null,
     accessMode: data.room.accessMode || 'open',
     members: data.members || [],
     memberPlayers: data.memberPlayers || {},
@@ -190,7 +195,7 @@ async function getRoomByCodeApi(code: string): Promise<RoomData> {
 }
 
 export interface ModerationEvent {
-  type: 'kicked' | 'banned' | 'report' | 'invitation'
+  type: 'kicked' | 'banned' | 'report' | 'invitation' | 'join-request'
   data: {
     roomId?: string
     kickedBy?: string
@@ -206,6 +211,10 @@ export interface ModerationEvent {
     invitedByName?: string
     invitationType?: 'manual' | 'auto-unban' | 'auto-create'
     message?: string
+    // Join request fields
+    requestId?: string
+    requesterId?: string
+    requesterName?: string
   }
 }
 
@@ -343,13 +352,13 @@ export function useRoomData() {
     }
 
     // Moderation event handlers
-    const handleKickedFromRoom = (data: { roomId: string; kickedBy: string }) => {
-      console.log('[useRoomData] User was kicked from room:', data)
+    const handleKickedFromRoom = (data: { roomId: string; kickedBy: string; reason?: string }) => {
       setModerationEvent({
         type: 'kicked',
         data: {
           roomId: data.roomId,
           kickedBy: data.kickedBy,
+          reason: data.reason,
         },
       })
       // Clear room data since user was kicked
@@ -357,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: {
@@ -381,7 +389,6 @@ export function useRoomData() {
         createdAt: Date
       }
     }) => {
-      console.log('[useRoomData] New report submitted:', data)
       setModerationEvent({
         type: 'report',
         data: {
@@ -406,7 +413,6 @@ export function useRoomData() {
         createdAt: Date
       }
     }) => {
-      console.log('[useRoomData] Room invitation received:', data)
       setModerationEvent({
         type: 'invitation',
         data: {
@@ -420,6 +426,45 @@ export function useRoomData() {
       })
     }
 
+    const handleJoinRequestSubmitted = (data: {
+      roomId: string
+      request: {
+        id: string
+        userId: string
+        userName: string
+        createdAt: Date
+      }
+    }) => {
+      setModerationEvent({
+        type: 'join-request',
+        data: {
+          roomId: data.roomId,
+          requestId: data.request.id,
+          requesterId: data.request.userId,
+          requesterName: data.request.userName,
+        },
+      })
+    }
+
+    const handleRoomGameChanged = (data: {
+      roomId: string
+      gameName: string | null
+      gameConfig?: Record<string, unknown>
+    }) => {
+      console.log('[useRoomData] Room game changed:', data)
+      if (data.roomId === roomData?.id) {
+        queryClient.setQueryData<RoomData | null>(roomKeys.current(), (prev) => {
+          if (!prev) return null
+          return {
+            ...prev,
+            gameName: data.gameName,
+            // Only update gameConfig if it was provided in the broadcast
+            ...(data.gameConfig !== undefined ? { gameConfig: data.gameConfig } : {}),
+          }
+        })
+      }
+    }
+
     socket.on('room-joined', handleRoomJoined)
     socket.on('member-joined', handleMemberJoined)
     socket.on('member-left', handleMemberLeft)
@@ -428,6 +473,8 @@ export function useRoomData() {
     socket.on('banned-from-room', handleBannedFromRoom)
     socket.on('report-submitted', handleReportSubmitted)
     socket.on('room-invitation-received', handleInvitationReceived)
+    socket.on('join-request-submitted', handleJoinRequestSubmitted)
+    socket.on('room-game-changed', handleRoomGameChanged)
 
     return () => {
       socket.off('room-joined', handleRoomJoined)
@@ -438,13 +485,14 @@ export function useRoomData() {
       socket.off('banned-from-room', handleBannedFromRoom)
       socket.off('report-submitted', handleReportSubmitted)
       socket.off('room-invitation-received', handleInvitationReceived)
+      socket.off('join-request-submitted', handleJoinRequestSubmitted)
+      socket.off('room-game-changed', handleRoomGameChanged)
     }
   }, [socket, roomData?.id, queryClient])
 
   // 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])
@@ -530,3 +578,162 @@ export function useGetRoomByCode() {
     mutationFn: getRoomByCodeApi,
   })
 }
+
+/**
+ * Set game for a room
+ */
+async function setRoomGameApi(params: {
+  roomId: string
+  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(body),
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json()
+    throw new Error(errorData.error || 'Failed to set room game')
+  }
+}
+
+/**
+ * Hook: Set game for a room
+ */
+export function useSetRoomGame() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: setRoomGameApi,
+    onSuccess: (_, variables) => {
+      // Update the cache with the new game
+      queryClient.setQueryData<RoomData | null>(roomKeys.current(), (prev) => {
+        if (!prev) return null
+        return {
+          ...prev,
+          gameName: variables.gameName,
+        }
+      })
+      // Refetch to get the full updated room data
+      queryClient.invalidateQueries({ queryKey: roomKeys.current() })
+    },
+  })
+}
+
+/**
+ * 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`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      gameName: null,
+      // DO NOT send gameConfig: null - we want to preserve settings!
+    }),
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json()
+    throw new Error(errorData.error || 'Failed to clear room game')
+  }
+}
+
+/**
+ * Hook: Clear/reset game for a room (returns to game selection screen)
+ */
+export function useClearRoomGame() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: clearRoomGameApi,
+    onSuccess: () => {
+      // Update the cache to clear the game
+      queryClient.setQueryData<RoomData | null>(roomKeys.current(), (prev) => {
+        if (!prev) return null
+        return {
+          ...prev,
+          gameName: null,
+        }
+      })
+      // Refetch to get the full updated room data
+      queryClient.invalidateQueries({ queryKey: roomKeys.current() })
+    },
+  })
+}
+
+/**
+ * Update game config for current room (game-specific settings)
+ */
+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' },
+    body: JSON.stringify({
+      gameConfig: params.gameConfig,
+    }),
+  })
+
+  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')
+}
+
+/**
+ * Hook: Update game config for current room
+ * This allows games to persist their settings (e.g., difficulty, card count)
+ */
+export function useUpdateGameConfig() {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: updateGameConfigApi,
+    onSuccess: (_, variables) => {
+      // Update the cache with the new gameConfig
+      queryClient.setQueryData<RoomData | null>(roomKeys.current(), (prev) => {
+        if (!prev) return null
+        return {
+          ...prev,
+          gameConfig: variables.gameConfig,
+        }
+      })
+      console.log(
+        '[useUpdateGameConfig] Updated cache with new gameConfig:',
+        JSON.stringify(variables.gameConfig, null, 2)
+      )
+    },
+  })
+}

apps/web/src/lib/arcade/__tests__/arcade-session-integration.test.ts

@@ -67,6 +67,7 @@ describe('Arcade Session Integration', () => {
       moves: 0,
       scores: {},
       activePlayers: ['1'],
+      playerMetadata: {},
       consecutiveMatches: {},
       gameStartTime: null,
       gameEndTime: null,
@@ -76,6 +77,7 @@ describe('Arcade Session Integration', () => {
       isProcessingMove: false,
       showMismatchFeedback: false,
       lastMatchedPair: null,
+      playerHovers: {},
     }
 
     const session = await createArcadeSession({
@@ -170,6 +172,7 @@ describe('Arcade Session Integration', () => {
       moves: 0,
       scores: { 1: 0 },
       activePlayers: ['1'],
+      playerMetadata: {},
       consecutiveMatches: { 1: 0 },
       gameStartTime: Date.now(),
       gameEndTime: null,
@@ -179,6 +182,7 @@ describe('Arcade Session Integration', () => {
       isProcessingMove: false,
       showMismatchFeedback: false,
       lastMatchedPair: null,
+      playerHovers: {},
     }
 
     await createArcadeSession({

apps/web/src/lib/arcade/__tests__/orphaned-session-cleanup.test.ts

@@ -52,38 +52,12 @@ describe('Orphaned Session Cleanup', () => {
     await db.delete(schema.users).where(eq(schema.users.id, testUserId))
   })
 
-  it('should return undefined when session has no roomId', async () => {
-    // Create a session with a valid room
-    const session = await createArcadeSession({
-      userId: testGuestId,
-      gameName: 'matching',
-      gameUrl: '/arcade/matching',
-      initialState: { gamePhase: 'setup' },
-      activePlayers: ['player-1'],
-      roomId: testRoomId,
-    })
-
-    expect(session).toBeDefined()
-    expect(session.roomId).toBe(testRoomId)
-
-    // Manually set roomId to null to simulate orphaned session
-    await db
-      .update(schema.arcadeSessions)
-      .set({ roomId: null })
-      .where(eq(schema.arcadeSessions.userId, testUserId))
-
-    // Getting the session should auto-delete it and return undefined
-    const result = await getArcadeSession(testGuestId)
-    expect(result).toBeUndefined()
-
-    // Verify session was actually deleted
-    const [directCheck] = await db
-      .select()
-      .from(schema.arcadeSessions)
-      .where(eq(schema.arcadeSessions.userId, testUserId))
-      .limit(1)
-
-    expect(directCheck).toBeUndefined()
+  // NOTE: This test is no longer valid with roomId as primary key
+  // roomId cannot be null since it's the primary key with a foreign key constraint
+  // Orphaned sessions are now automatically cleaned up via CASCADE delete when room is deleted
+  it.skip('should return undefined when session has no roomId', async () => {
+    // This test scenario is impossible with the new schema where roomId is the primary key
+    // and has a foreign key constraint with CASCADE delete
   })
 
   it('should return undefined when session room has been deleted', async () => {

apps/web/src/lib/arcade/__tests__/room-manager.test.ts

@@ -62,6 +62,7 @@ describe('Room Manager', () => {
     ttlMinutes: 60,
     accessMode: 'open',
     password: null,
+    displayPassword: null,
     gameName: 'matching',
     gameConfig: { difficulty: 6 },
     status: 'lobby',

apps/web/src/lib/arcade/__tests__/session-manager.test.ts

@@ -260,6 +260,7 @@ describe('session-manager', () => {
         type: 'FLIP_CARD',
         data: { cardId: '1' },
         playerId: '1',
+        userId: mockUserId,
         timestamp: Date.now(),
       }
 

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

@@ -0,0 +1,236 @@
+/**
+ * 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 './validators'
+import type { GameConfigByName } from './game-configs'
+import {
+  DEFAULT_MATCHING_CONFIG,
+  DEFAULT_MEMORY_QUIZ_CONFIG,
+  DEFAULT_COMPLEMENT_RACE_CONFIG,
+  DEFAULT_NUMBER_GUESSER_CONFIG,
+  DEFAULT_MATH_SPRINT_CONFIG,
+} from './game-configs'
+
+/**
+ * Extended game name type that includes both registered validators and legacy games
+ * TODO: Remove 'complement-race' once migrated to the new modular system
+ */
+type ExtendedGameName = GameName | 'complement-race'
+
+/**
+ * Get default config for a game
+ */
+function getDefaultGameConfig(gameName: ExtendedGameName): GameConfigByName[ExtendedGameName] {
+  switch (gameName) {
+    case 'matching':
+      return DEFAULT_MATCHING_CONFIG
+    case 'memory-quiz':
+      return DEFAULT_MEMORY_QUIZ_CONFIG
+    case 'complement-race':
+      return DEFAULT_COMPLEMENT_RACE_CONFIG
+    case 'number-guesser':
+      return DEFAULT_NUMBER_GUESSER_CONFIG
+    case 'math-sprint':
+      return DEFAULT_MATH_SPRINT_CONFIG
+    default:
+      throw new Error(`Unknown game: ${gameName}`)
+  }
+}
+
+/**
+ * Get game-specific config from database with defaults
+ * Type-safe: returns the correct config type based on gameName
+ */
+export async function getGameConfig<T extends ExtendedGameName>(
+  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 ExtendedGameName>(
+  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 ExtendedGameName,
+  K extends keyof GameConfigByName[T],
+>(roomId: string, gameName: T, field: K, value: GameConfigByName[T][K]): Promise<void> {
+  // Create a partial config with just the field being updated
+  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: ExtendedGameName): 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<ExtendedGameName, unknown>>> {
+  const configs = await db.query.roomGameConfigs.findMany({
+    where: eq(schema.roomGameConfigs.roomId, roomId),
+  })
+
+  const result: Partial<Record<ExtendedGameName, unknown>> = {}
+  for (const config of configs) {
+    result[config.gameName as ExtendedGameName] = 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: ExtendedGameName, 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
+
+    case 'number-guesser':
+      return (
+        typeof config === 'object' &&
+        config !== null &&
+        typeof config.minNumber === 'number' &&
+        typeof config.maxNumber === 'number' &&
+        typeof config.roundsToWin === 'number' &&
+        config.minNumber >= 1 &&
+        config.maxNumber > config.minNumber &&
+        config.roundsToWin >= 1
+      )
+
+    case 'math-sprint':
+      return (
+        typeof config === 'object' &&
+        config !== null &&
+        ['easy', 'medium', 'hard'].includes(config.difficulty) &&
+        typeof config.questionsPerRound === 'number' &&
+        typeof config.timePerQuestion === 'number' &&
+        config.questionsPerRound >= 5 &&
+        config.questionsPerRound <= 20 &&
+        config.timePerQuestion >= 10
+      )
+
+    default:
+      return false
+  }
+}

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

@@ -0,0 +1,115 @@
+/**
+ * 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'
+import type { Difficulty as MathSprintDifficulty } from '@/arcade-games/math-sprint/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
+}
+
+/**
+ * Configuration for number-guesser game
+ */
+export interface NumberGuesserGameConfig {
+  minNumber: number
+  maxNumber: number
+  roundsToWin: number
+}
+
+/**
+ * Configuration for math-sprint game
+ */
+export interface MathSprintGameConfig {
+  difficulty: MathSprintDifficulty
+  questionsPerRound: number
+  timePerQuestion: number
+}
+
+/**
+ * Union type of all game configs for type-safe access
+ */
+export type GameConfigByName = {
+  matching: MatchingGameConfig
+  'memory-quiz': MemoryQuizGameConfig
+  'complement-race': ComplementRaceGameConfig
+  'number-guesser': NumberGuesserGameConfig
+  'math-sprint': MathSprintGameConfig
+}
+
+/**
+ * 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
+  'number-guesser'?: NumberGuesserGameConfig
+  'math-sprint'?: MathSprintGameConfig
+}
+
+/**
+ * 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
+}
+
+export const DEFAULT_NUMBER_GUESSER_CONFIG: NumberGuesserGameConfig = {
+  minNumber: 1,
+  maxNumber: 100,
+  roundsToWin: 3,
+}
+
+export const DEFAULT_MATH_SPRINT_CONFIG: MathSprintGameConfig = {
+  difficulty: 'medium',
+  questionsPerRound: 10,
+  timePerQuestion: 30,
+}

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

@@ -0,0 +1,113 @@
+/**
+ * Game Registry
+ *
+ * Central registry for all arcade games.
+ * Games are explicitly registered here after being defined.
+ */
+
+import type { GameConfig, GameDefinition, GameMove, GameState } from './game-sdk/types'
+
+/**
+ * Global game registry
+ * Maps game name to game definition
+ * Using `any` for generics to allow different game types
+ */
+const registry = new Map<string, GameDefinition<any, any, any>>()
+
+/**
+ * Register a game in the registry
+ *
+ * @param game - Game definition to register
+ * @throws Error if game with same name already registered
+ */
+export function registerGame<
+  TConfig extends GameConfig,
+  TState extends GameState,
+  TMove extends GameMove,
+>(game: GameDefinition<TConfig, TState, TMove>): void {
+  const { name } = game.manifest
+
+  if (registry.has(name)) {
+    throw new Error(`Game "${name}" is already registered`)
+  }
+
+  // Verify validator is also registered server-side
+  try {
+    const { hasValidator, getValidator } = require('./validators')
+    if (!hasValidator(name)) {
+      console.error(
+        `⚠️  Game "${name}" registered but validator not found in server registry!` +
+          `\n   Add to src/lib/arcade/validators.ts to enable multiplayer.`
+      )
+    } else {
+      const serverValidator = getValidator(name)
+      if (serverValidator !== game.validator) {
+        console.warn(
+          `⚠️  Game "${name}" has different validator instances (client vs server).` +
+            `\n   This may cause issues. Ensure both use the same import.`
+        )
+      }
+    }
+  } catch (error) {
+    // If validators.ts can't be imported (e.g., in browser), skip check
+    // This is expected - validator registry is isomorphic but check only runs server-side
+  }
+
+  registry.set(name, game)
+  console.log(`✅ Registered game: ${name}`)
+}
+
+/**
+ * Get a game from the registry
+ *
+ * @param gameName - Internal game identifier
+ * @returns Game definition or undefined if not found
+ */
+export function getGame(gameName: string): GameDefinition<any, any, any> | undefined {
+  return registry.get(gameName)
+}
+
+/**
+ * Get all registered games
+ *
+ * @returns Array of all game definitions
+ */
+export function getAllGames(): GameDefinition<any, any, any>[] {
+  return Array.from(registry.values())
+}
+
+/**
+ * Get all available games (where available: true)
+ *
+ * @returns Array of available game definitions
+ */
+export function getAvailableGames(): GameDefinition<any, any, any>[] {
+  return getAllGames().filter((game) => game.manifest.available)
+}
+
+/**
+ * Check if a game is registered
+ *
+ * @param gameName - Internal game identifier
+ * @returns true if game is registered
+ */
+export function hasGame(gameName: string): boolean {
+  return registry.has(gameName)
+}
+
+/**
+ * Clear all games from registry (used for testing)
+ */
+export function clearRegistry(): void {
+  registry.clear()
+}
+
+// ============================================================================
+// Game Registrations
+// ============================================================================
+
+import { numberGuesserGame } from '@/arcade-games/number-guesser'
+import { mathSprintGame } from '@/arcade-games/math-sprint'
+
+registerGame(numberGuesserGame)
+registerGame(mathSprintGame)

apps/web/src/lib/arcade/game-sdk/GameErrorBoundary.tsx

@@ -0,0 +1,124 @@
+/**
+ * Error Boundary for Arcade Games
+ *
+ * Catches errors in game components and displays a friendly error message
+ * instead of crashing the entire app.
+ */
+
+'use client'
+
+import { Component, type ReactNode } from 'react'
+
+interface Props {
+  children: ReactNode
+  gameName?: string
+}
+
+interface State {
+  hasError: boolean
+  error?: Error
+}
+
+export class GameErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props)
+    this.state = { hasError: false }
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return {
+      hasError: true,
+      error,
+    }
+  }
+
+  componentDidCatch(error: Error, errorInfo: unknown) {
+    console.error('Game error:', error, errorInfo)
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            padding: '40px',
+            textAlign: 'center',
+            minHeight: '400px',
+            background: 'linear-gradient(135deg, #fef2f2, #fee2e2)',
+          }}
+        >
+          <div
+            style={{
+              fontSize: '64px',
+              marginBottom: '20px',
+            }}
+          >
+            ⚠️
+          </div>
+          <h2
+            style={{
+              fontSize: '24px',
+              fontWeight: 'bold',
+              marginBottom: '12px',
+              color: '#dc2626',
+            }}
+          >
+            Game Error
+          </h2>
+          <p
+            style={{
+              fontSize: '16px',
+              color: '#6b7280',
+              marginBottom: '12px',
+              maxWidth: '500px',
+            }}
+          >
+            {this.props.gameName
+              ? `There was an error loading the game "${this.props.gameName}".`
+              : 'There was an error loading the game.'}
+          </p>
+          {this.state.error && (
+            <pre
+              style={{
+                background: '#f9fafb',
+                border: '1px solid #e5e7eb',
+                borderRadius: '8px',
+                padding: '16px',
+                marginTop: '12px',
+                maxWidth: '600px',
+                overflow: 'auto',
+                textAlign: 'left',
+                fontSize: '12px',
+                color: '#374151',
+              }}
+            >
+              {this.state.error.message}
+            </pre>
+          )}
+          <button
+            onClick={() => window.location.reload()}
+            style={{
+              marginTop: '24px',
+              padding: '12px 24px',
+              background: '#3b82f6',
+              color: 'white',
+              border: 'none',
+              borderRadius: '8px',
+              fontSize: '14px',
+              fontWeight: '600',
+              cursor: 'pointer',
+            }}
+          >
+            Reload Page
+          </button>
+        </div>
+      )
+    }
+
+    return this.props.children
+  }
+}

apps/web/src/lib/arcade/game-sdk/define-game.ts

@@ -0,0 +1,80 @@
+/**
+ * Game definition helper
+ * Provides type-safe game registration
+ */
+
+import type {
+  GameComponent,
+  GameConfig,
+  GameDefinition,
+  GameMove,
+  GameProviderComponent,
+  GameState,
+  GameValidator,
+} from './types'
+import type { GameManifest } from '../manifest-schema'
+
+/**
+ * Options for defining a game
+ */
+export interface DefineGameOptions<
+  TConfig extends GameConfig,
+  TState extends GameState,
+  TMove extends GameMove,
+> {
+  /** Game manifest (loaded from game.yaml) */
+  manifest: GameManifest
+
+  /** React provider component */
+  Provider: GameProviderComponent
+
+  /** Main game UI component */
+  GameComponent: GameComponent
+
+  /** Server-side validator */
+  validator: GameValidator<TState, TMove>
+
+  /** Default configuration for the game */
+  defaultConfig: TConfig
+}
+
+/**
+ * Define a game with full type safety
+ *
+ * This helper ensures all required parts of a game are provided
+ * and returns a properly typed GameDefinition.
+ *
+ * @example
+ * ```typescript
+ * export const myGame = defineGame({
+ *   manifest: loadManifest('./game.yaml'),
+ *   Provider: MyGameProvider,
+ *   GameComponent: MyGameComponent,
+ *   validator: myGameValidator,
+ *   defaultConfig: {
+ *     difficulty: 'easy',
+ *     maxTime: 60
+ *   }
+ * })
+ * ```
+ */
+export function defineGame<
+  TConfig extends GameConfig,
+  TState extends GameState,
+  TMove extends GameMove,
+>(options: DefineGameOptions<TConfig, TState, TMove>): GameDefinition<TConfig, TState, TMove> {
+  const { manifest, Provider, GameComponent, validator, defaultConfig } = options
+
+  // Validate that manifest.name matches the game identifier
+  if (!manifest.name) {
+    throw new Error('Game manifest must have a "name" field')
+  }
+
+  return {
+    manifest,
+    Provider,
+    GameComponent,
+    validator,
+    defaultConfig,
+  }
+}