chore(release): 2.11.0 [skip ci]

## [2.11.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v2.10.1...v2.11.0) (2025-10-09)

### Features

* add pause/resume game state architecture ([05eacac](05eacac438))
* add Resume button and config change warning to setup UI ([b5ee04f](b5ee04f576))
* implement pause/resume in game providers with optimistic updates ([ce30fca](ce30fcaf55))

### Bug Fixes

* convert guestId to internal userId for player ownership check ([3a01f46](3a01f4637d))
* implement shared session architecture for room-based multiplayer ([2856f4b](2856f4b83f))

CHANGELOG.md

@@ -1,3 +1,26 @@
+## [2.11.0](https://github.com/antialias/soroban-abacus-flashcards/compare/v2.10.1...v2.11.0) (2025-10-09)
+
+
+### Features
+
+* add pause/resume game state architecture ([05eacac](https://github.com/antialias/soroban-abacus-flashcards/commit/05eacac438dbaf405ce91e188c53dbbe2e9f9507))
+* add Resume button and config change warning to setup UI ([b5ee04f](https://github.com/antialias/soroban-abacus-flashcards/commit/b5ee04f57651f53517468fcc4c456f0ccb65a8e2))
+* implement pause/resume in game providers with optimistic updates ([ce30fca](https://github.com/antialias/soroban-abacus-flashcards/commit/ce30fcaf55270f9089249bd13ba73a25fbfa5ab4))
+
+
+### Bug Fixes
+
+* convert guestId to internal userId for player ownership check ([3a01f46](https://github.com/antialias/soroban-abacus-flashcards/commit/3a01f4637d2081c66fe37c7f8cfee229442ec744))
+* implement shared session architecture for room-based multiplayer ([2856f4b](https://github.com/antialias/soroban-abacus-flashcards/commit/2856f4b83fbcc6483d96cc6e7da2fe5bc911625d))
+
+## [2.10.2](https://github.com/antialias/soroban-abacus-flashcards/compare/v2.10.1...v2.10.2) (2025-10-09)
+
+
+### Bug Fixes
+
+* convert guestId to internal userId for player ownership check ([3a01f46](https://github.com/antialias/soroban-abacus-flashcards/commit/3a01f4637d2081c66fe37c7f8cfee229442ec744))
+* implement shared session architecture for room-based multiplayer ([2856f4b](https://github.com/antialias/soroban-abacus-flashcards/commit/2856f4b83fbcc6483d96cc6e7da2fe5bc911625d))
+
 ## [2.10.1](https://github.com/antialias/soroban-abacus-flashcards/compare/v2.10.0...v2.10.1) (2025-10-09)
 
 

apps/web/socket-server.ts

@@ -6,6 +6,7 @@ import {
   createArcadeSession,
   deleteArcadeSession,
   getArcadeSession,
+  getArcadeSessionByRoom,
   updateSessionActivity,
 } from './src/lib/arcade/session-manager'
 import { createRoom, getRoomById } from './src/lib/arcade/room-manager'
@@ -56,9 +57,19 @@ export function initializeSocketServer(httpServer: HTTPServer) {
         }
 
         // Send current session state if exists
+        // For room-based games, look up shared room session
         try {
-          const session = await getArcadeSession(userId)
+          const session = roomId
+            ? await getArcadeSessionByRoom(roomId)
+            : await getArcadeSession(userId)
+
           if (session) {
+            console.log('[join-arcade-session] Found session:', {
+              userId,
+              roomId,
+              version: session.version,
+              sessionUserId: session.userId,
+            })
             socket.emit('session-state', {
               gameState: session.gameState,
               currentGame: session.currentGame,
@@ -67,6 +78,10 @@ export function initializeSocketServer(httpServer: HTTPServer) {
               version: session.version,
             })
           } else {
+            console.log('[join-arcade-session] No active session found for:', {
+              userId,
+              roomId,
+            })
             socket.emit('no-active-session')
           }
         } catch (error) {
@@ -77,19 +92,23 @@ export function initializeSocketServer(httpServer: HTTPServer) {
     )
 
     // Handle game moves
-    socket.on('game-move', async (data: { userId: string; move: GameMove }) => {
+    socket.on('game-move', async (data: { userId: string; move: GameMove; roomId?: string }) => {
       console.log('🎮 Game move received:', {
         userId: data.userId,
         moveType: data.move.type,
         playerId: data.move.playerId,
         timestamp: data.move.timestamp,
+        roomId: data.roomId,
         fullMove: JSON.stringify(data.move, null, 2),
       })
 
       try {
         // Special handling for START_GAME - create session if it doesn't exist
         if (data.move.type === 'START_GAME') {
-          const existingSession = await getArcadeSession(data.userId)
+          // For room-based games, check if room session exists
+          const existingSession = data.roomId
+            ? await getArcadeSessionByRoom(data.roomId)
+            : await getArcadeSession(data.userId)
 
           if (!existingSession) {
             console.log('🎯 Creating new session for START_GAME')
@@ -174,7 +193,8 @@ export function initializeSocketServer(httpServer: HTTPServer) {
           }
         }
 
-        const result = await applyGameMove(data.userId, data.move)
+        // Apply game move - use roomId for room-based games to access shared session
+        const result = await applyGameMove(data.userId, data.move, data.roomId)
 
         if (result.success && result.session) {
           const moveAcceptedData = {

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

@@ -1,8 +1,9 @@
 'use client'
 
+import { useState } from 'react'
 import { css } from '../../../../../styled-system/css'
 import { useGameMode } from '../../../../contexts/GameModeContext'
-import { useArcadeMemoryPairs } from '../context/ArcadeMemoryPairsContext'
+import { useMemoryPairs } from '../context/MemoryPairsContext'
 
 // Add bounce animation for the start button
 const bounceAnimation = `
@@ -32,14 +33,87 @@ export function SetupPhase() {
     state,
     setGameType,
     setDifficulty,
+    setTurnTimer,
     startGame,
+    resumeGame,
+    canResumeGame,
+    hasConfigChanged,
     activePlayers: _activePlayers,
-  } = useArcadeMemoryPairs()
+  } = useMemoryPairs()
 
   const { activePlayerCount, gameMode: _globalGameMode } = useGameMode()
 
-  const handleStartGame = () => {
-    startGame()
+  // PAUSE/RESUME: Warning dialog state
+  const [showConfigWarning, setShowConfigWarning] = useState(false)
+  const [hasSeenWarning, setHasSeenWarning] = useState(false)
+  const [pendingConfigChange, setPendingConfigChange] = useState<{
+    type: 'gameType' | 'difficulty' | 'turnTimer'
+    value: any
+  } | null>(null)
+
+  // Check if we should show warning when changing config
+  const shouldShowWarning = state.pausedGamePhase && !hasSeenWarning && !hasConfigChanged
+
+  // Config change handlers that check for paused game
+  const handleSetGameType = (value: typeof state.gameType) => {
+    if (shouldShowWarning) {
+      setPendingConfigChange({ type: 'gameType', value })
+      setShowConfigWarning(true)
+    } else {
+      setGameType(value)
+    }
+  }
+
+  const handleSetDifficulty = (value: typeof state.difficulty) => {
+    if (shouldShowWarning) {
+      setPendingConfigChange({ type: 'difficulty', value })
+      setShowConfigWarning(true)
+    } else {
+      setDifficulty(value)
+    }
+  }
+
+  const handleSetTurnTimer = (value: typeof state.turnTimer) => {
+    if (shouldShowWarning) {
+      setPendingConfigChange({ type: 'turnTimer', value })
+      setShowConfigWarning(true)
+    } else {
+      setTurnTimer(value)
+    }
+  }
+
+  // Apply pending config change after warning
+  const applyPendingChange = () => {
+    if (pendingConfigChange) {
+      switch (pendingConfigChange.type) {
+        case 'gameType':
+          setGameType(pendingConfigChange.value)
+          break
+        case 'difficulty':
+          setDifficulty(pendingConfigChange.value)
+          break
+        case 'turnTimer':
+          setTurnTimer(pendingConfigChange.value)
+          break
+      }
+      setHasSeenWarning(true)
+      setPendingConfigChange(null)
+      setShowConfigWarning(false)
+    }
+  }
+
+  // Cancel config change
+  const cancelConfigChange = () => {
+    setPendingConfigChange(null)
+    setShowConfigWarning(false)
+  }
+
+  const handleStartOrResumeGame = () => {
+    if (canResumeGame) {
+      resumeGame()
+    } else {
+      startGame()
+    }
   }
 
   const getButtonStyles = (
@@ -150,6 +224,94 @@ export function SetupPhase() {
           minHeight: 0, // Allow shrinking
         })}
       >
+        {/* PAUSE/RESUME: Config change warning */}
+        {showConfigWarning && (
+          <div
+            className={css({
+              p: '4',
+              background:
+                'linear-gradient(135deg, rgba(251, 191, 36, 0.15), rgba(245, 158, 11, 0.15))',
+              border: '2px solid',
+              borderColor: 'yellow.400',
+              rounded: 'xl',
+              textAlign: 'center',
+              boxShadow: '0 4px 12px rgba(251, 191, 36, 0.2)',
+            })}
+          >
+            <p
+              className={css({
+                color: 'yellow.700',
+                fontSize: { base: '15px', md: '17px' },
+                fontWeight: 'bold',
+                marginBottom: '8px',
+              })}
+            >
+              ⚠️ Warning: Changing Settings Will End Current Game
+            </p>
+            <p
+              className={css({
+                color: 'gray.600',
+                fontSize: { base: '13px', md: '14px' },
+                marginBottom: '12px',
+              })}
+            >
+              You have a paused game in progress. Changing any setting will end it and you won't be
+              able to resume.
+            </p>
+            <div
+              className={css({
+                display: 'flex',
+                gap: '8px',
+                justifyContent: 'center',
+                flexWrap: 'wrap',
+              })}
+            >
+              <button
+                className={css({
+                  background: 'linear-gradient(135deg, #10b981, #059669)',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: '8px',
+                  padding: '8px 16px',
+                  fontSize: '14px',
+                  fontWeight: 'bold',
+                  cursor: 'pointer',
+                  transition: 'all 0.2s',
+                  boxShadow: '0 2px 8px rgba(16, 185, 129, 0.3)',
+                  _hover: {
+                    transform: 'translateY(-2px)',
+                    boxShadow: '0 4px 12px rgba(16, 185, 129, 0.4)',
+                  },
+                })}
+                onClick={cancelConfigChange}
+              >
+                ✓ Keep Game & Cancel Change
+              </button>
+              <button
+                className={css({
+                  background: 'linear-gradient(135deg, #ef4444, #dc2626)',
+                  color: 'white',
+                  border: 'none',
+                  borderRadius: '8px',
+                  padding: '8px 16px',
+                  fontSize: '14px',
+                  fontWeight: 'bold',
+                  cursor: 'pointer',
+                  transition: 'all 0.2s',
+                  boxShadow: '0 2px 8px rgba(239, 68, 68, 0.3)',
+                  _hover: {
+                    transform: 'translateY(-2px)',
+                    boxShadow: '0 4px 12px rgba(239, 68, 68, 0.4)',
+                  },
+                })}
+                onClick={applyPendingChange}
+              >
+                ✗ End Game & Apply Change
+              </button>
+            </div>
+          </div>
+        )}
+
         {/* Warning if no players */}
         {activePlayerCount === 0 && (
           <div
@@ -200,7 +362,7 @@ export function SetupPhase() {
           >
             <button
               className={getButtonStyles(state.gameType === 'abacus-numeral', 'secondary')}
-              onClick={() => setGameType('abacus-numeral')}
+              onClick={() => handleSetGameType('abacus-numeral')}
             >
               <div
                 className={css({
@@ -246,7 +408,7 @@ export function SetupPhase() {
             </button>
             <button
               className={getButtonStyles(state.gameType === 'complement-pairs', 'secondary')}
-              onClick={() => setGameType('complement-pairs')}
+              onClick={() => handleSetGameType('complement-pairs')}
             >
               <div
                 className={css({
@@ -342,7 +504,7 @@ export function SetupPhase() {
                 <button
                   key={difficulty}
                   className={getButtonStyles(state.difficulty === difficulty, 'difficulty')}
-                  onClick={() => setDifficulty(difficulty)}
+                  onClick={() => handleSetDifficulty(difficulty)}
                 >
                   <div
                     className={css({
@@ -414,7 +576,7 @@ export function SetupPhase() {
                   <button
                     key={timer}
                     className={getButtonStyles(state.turnTimer === timer, 'secondary')}
-                    onClick={() => dispatch({ type: 'SET_TURN_TIMER', timer })}
+                    onClick={() => handleSetTurnTimer(timer)}
                   >
                     <div
                       className={css({
@@ -464,7 +626,9 @@ export function SetupPhase() {
         >
           <button
             className={css({
-              background: 'linear-gradient(135deg, #ff6b6b 0%, #ee5a24 50%, #ff9ff3 100%)',
+              background: canResumeGame
+                ? 'linear-gradient(135deg, #10b981 0%, #059669 50%, #34d399 100%)'
+                : 'linear-gradient(135deg, #ff6b6b 0%, #ee5a24 50%, #ff9ff3 100%)',
               color: 'white',
               border: 'none',
               borderRadius: { base: '16px', sm: '20px', md: '24px' },
@@ -473,7 +637,9 @@ export function SetupPhase() {
               fontWeight: 'black',
               cursor: 'pointer',
               transition: 'all 0.4s cubic-bezier(0.4, 0, 0.2, 1)',
-              boxShadow: '0 8px 20px rgba(255, 107, 107, 0.4), inset 0 2px 0 rgba(255,255,255,0.3)',
+              boxShadow: canResumeGame
+                ? '0 8px 20px rgba(16, 185, 129, 0.4), inset 0 2px 0 rgba(255,255,255,0.3)'
+                : '0 8px 20px rgba(255, 107, 107, 0.4), inset 0 2px 0 rgba(255,255,255,0.3)',
               textShadow: '0 2px 4px rgba(0,0,0,0.3)',
               position: 'relative',
               overflow: 'hidden',
@@ -491,9 +657,12 @@ export function SetupPhase() {
               },
               _hover: {
                 transform: { base: 'translateY(-2px)', md: 'translateY(-3px) scale(1.02)' },
-                boxShadow:
-                  '0 12px 30px rgba(255, 107, 107, 0.6), inset 0 2px 0 rgba(255,255,255,0.3)',
-                background: 'linear-gradient(135deg, #ff5252 0%, #dd2c00 50%, #e91e63 100%)',
+                boxShadow: canResumeGame
+                  ? '0 12px 30px rgba(16, 185, 129, 0.6), inset 0 2px 0 rgba(255,255,255,0.3)'
+                  : '0 12px 30px rgba(255, 107, 107, 0.6), inset 0 2px 0 rgba(255,255,255,0.3)',
+                background: canResumeGame
+                  ? 'linear-gradient(135deg, #059669 0%, #047857 50%, #10b981 100%)'
+                  : 'linear-gradient(135deg, #ff5252 0%, #dd2c00 50%, #e91e63 100%)',
                 _before: {
                   left: '100%',
                 },
@@ -502,7 +671,7 @@ export function SetupPhase() {
                 transform: 'translateY(-1px) scale(1.01)',
               },
             })}
-            onClick={handleStartGame}
+            onClick={handleStartOrResumeGame}
           >
             <div
               className={css({
@@ -518,9 +687,9 @@ export function SetupPhase() {
                   animation: 'bounce 2s infinite',
                 })}
               >
-                🚀
+                {canResumeGame ? '▶️' : '🚀'}
               </span>
-              <span>START GAME</span>
+              <span>{canResumeGame ? 'RESUME GAME' : 'START GAME'}</span>
               <span
                 className={css({
                   fontSize: { base: '18px', sm: '20px', md: '24px' },
@@ -528,7 +697,7 @@ export function SetupPhase() {
                   animationDelay: '0.5s',
                 })}
               >
-                🎮
+                {canResumeGame ? '🎮' : '🎮'}
               </span>
             </div>
           </button>

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

@@ -0,0 +1,534 @@
+'use client'
+
+import { type ReactNode, useCallback, useEffect, useMemo } from 'react'
+import { useArcadeSession } from '@/hooks/useArcadeSession'
+import { useViewerId } from '@/hooks/useViewerId'
+import type { GameMove } from '@/lib/arcade/validation'
+import { useGameMode } from '../../../../contexts/GameModeContext'
+import { generateGameCards } from '../utils/cardGeneration'
+import { MemoryPairsContext } from './MemoryPairsContext'
+import type { GameMode, GameStatistics, MemoryPairsContextValue, MemoryPairsState } from './types'
+
+// Initial state
+const initialState: MemoryPairsState = {
+  cards: [],
+  gameCards: [],
+  flippedCards: [],
+  gameType: 'abacus-numeral',
+  difficulty: 6,
+  turnTimer: 30,
+  gamePhase: 'setup',
+  currentPlayer: '', // Will be set to first player ID on START_GAME
+  matchedPairs: 0,
+  totalPairs: 6,
+  moves: 0,
+  scores: {},
+  activePlayers: [],
+  playerMetadata: {}, // Player metadata for cross-user visibility
+  consecutiveMatches: {},
+  gameStartTime: null,
+  gameEndTime: null,
+  currentMoveStartTime: null,
+  timerInterval: null,
+  celebrationAnimations: [],
+  isProcessingMove: false,
+  showMismatchFeedback: false,
+  lastMatchedPair: null,
+  // PAUSE/RESUME: Initialize paused game fields
+  originalConfig: undefined,
+  pausedGamePhase: undefined,
+  pausedGameState: undefined,
+}
+
+/**
+ * Optimistic move application (client-side prediction)
+ * The server will validate and send back the authoritative state
+ */
+function applyMoveOptimistically(state: MemoryPairsState, move: GameMove): MemoryPairsState {
+  switch (move.type) {
+    case 'START_GAME':
+      // Generate cards and initialize game
+      return {
+        ...state,
+        gamePhase: 'playing',
+        gameCards: move.data.cards,
+        cards: move.data.cards,
+        flippedCards: [],
+        matchedPairs: 0,
+        moves: 0,
+        scores: move.data.activePlayers.reduce((acc: any, p: string) => ({ ...acc, [p]: 0 }), {}),
+        consecutiveMatches: move.data.activePlayers.reduce(
+          (acc: any, p: string) => ({ ...acc, [p]: 0 }),
+          {}
+        ),
+        activePlayers: move.data.activePlayers,
+        playerMetadata: move.data.playerMetadata || {}, // Include player metadata
+        currentPlayer: move.data.activePlayers[0] || '',
+        gameStartTime: Date.now(),
+        gameEndTime: null,
+        currentMoveStartTime: Date.now(),
+        celebrationAnimations: [],
+        isProcessingMove: false,
+        showMismatchFeedback: false,
+        lastMatchedPair: null,
+        // PAUSE/RESUME: Save original config and clear paused state
+        originalConfig: {
+          gameType: state.gameType,
+          difficulty: state.difficulty,
+          turnTimer: state.turnTimer,
+        },
+        pausedGamePhase: undefined,
+        pausedGameState: undefined,
+      }
+
+    case 'FLIP_CARD': {
+      // Optimistically flip the card
+      const card = state.gameCards.find((c) => c.id === move.data.cardId)
+      if (!card) return state
+
+      const newFlippedCards = [...state.flippedCards, card]
+
+      return {
+        ...state,
+        flippedCards: newFlippedCards,
+        currentMoveStartTime:
+          state.flippedCards.length === 0 ? Date.now() : state.currentMoveStartTime,
+        isProcessingMove: newFlippedCards.length === 2, // Processing if 2 cards flipped
+        showMismatchFeedback: false,
+      }
+    }
+
+    case 'CLEAR_MISMATCH': {
+      // Clear mismatched cards and feedback
+      return {
+        ...state,
+        flippedCards: [],
+        showMismatchFeedback: false,
+        isProcessingMove: false,
+      }
+    }
+
+    case 'GO_TO_SETUP': {
+      // Return to setup phase - pause game if coming from playing/results
+      const isPausingGame = state.gamePhase === 'playing' || state.gamePhase === 'results'
+
+      return {
+        ...state,
+        gamePhase: 'setup',
+        // PAUSE: Save game state if pausing from active game
+        pausedGamePhase: isPausingGame ? state.gamePhase : undefined,
+        pausedGameState: isPausingGame
+          ? {
+              gameCards: state.gameCards,
+              currentPlayer: state.currentPlayer,
+              matchedPairs: state.matchedPairs,
+              moves: state.moves,
+              scores: state.scores,
+              activePlayers: state.activePlayers,
+              playerMetadata: state.playerMetadata,
+              consecutiveMatches: state.consecutiveMatches,
+              gameStartTime: state.gameStartTime,
+            }
+          : undefined,
+        // Reset visible game state
+        gameCards: [],
+        cards: [],
+        flippedCards: [],
+        currentPlayer: '',
+        matchedPairs: 0,
+        moves: 0,
+        scores: {},
+        activePlayers: [],
+        playerMetadata: {},
+        consecutiveMatches: {},
+        gameStartTime: null,
+        gameEndTime: null,
+        currentMoveStartTime: null,
+        celebrationAnimations: [],
+        isProcessingMove: false,
+        showMismatchFeedback: false,
+        lastMatchedPair: null,
+      }
+    }
+
+    case 'SET_CONFIG': {
+      // Update configuration field optimistically
+      const { field, value } = move.data as { field: string; value: any }
+      const clearPausedGame = !!state.pausedGamePhase
+
+      return {
+        ...state,
+        [field]: value,
+        // Update totalPairs if difficulty changes
+        ...(field === 'difficulty' ? { totalPairs: value } : {}),
+        // Clear paused game if config changed
+        ...(clearPausedGame
+          ? { pausedGamePhase: undefined, pausedGameState: undefined, originalConfig: undefined }
+          : {}),
+      }
+    }
+
+    case 'RESUME_GAME': {
+      // Resume paused game
+      if (!state.pausedGamePhase || !state.pausedGameState) {
+        return state // No paused game, no-op
+      }
+
+      return {
+        ...state,
+        gamePhase: state.pausedGamePhase,
+        gameCards: state.pausedGameState.gameCards,
+        cards: state.pausedGameState.gameCards,
+        currentPlayer: state.pausedGameState.currentPlayer,
+        matchedPairs: state.pausedGameState.matchedPairs,
+        moves: state.pausedGameState.moves,
+        scores: state.pausedGameState.scores,
+        activePlayers: state.pausedGameState.activePlayers,
+        playerMetadata: state.pausedGameState.playerMetadata,
+        consecutiveMatches: state.pausedGameState.consecutiveMatches,
+        gameStartTime: state.pausedGameState.gameStartTime,
+        // Clear paused state
+        pausedGamePhase: undefined,
+        pausedGameState: undefined,
+      }
+    }
+
+    default:
+      return state
+  }
+}
+
+// Provider component for LOCAL play (no network sync)
+export function LocalMemoryPairsProvider({ children }: { children: ReactNode }) {
+  const { data: viewerId } = useViewerId()
+  // NOTE: We deliberately do NOT call useRoomData() for local play
+  const { activePlayerCount, activePlayers: activePlayerIds, players } = useGameMode()
+
+  // Get active player IDs directly as strings (UUIDs)
+  const activePlayers = Array.from(activePlayerIds)
+
+  // 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 (even in local mode for consistency)
+
+  // Arcade session integration WITHOUT room sync
+  const {
+    state,
+    sendMove,
+    connected: _connected,
+    exitSession,
+  } = useArcadeSession<MemoryPairsState>({
+    userId: viewerId || '',
+    roomId: undefined, // CRITICAL: No roomId means no network sync
+    initialState,
+    applyMove: applyMoveOptimistically,
+  })
+
+  // Handle mismatch feedback timeout
+  useEffect(() => {
+    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,
+          data: {},
+        })
+      }, 1500)
+
+      return () => clearTimeout(timeout)
+    }
+  }, [state.showMismatchFeedback, state.flippedCards.length, sendMove, state.currentPlayer])
+
+  // Computed values
+  const isGameActive = state.gamePhase === 'playing'
+
+  const canFlipCard = useCallback(
+    (cardId: string): boolean => {
+      console.log('[LocalProvider][canFlipCard] Checking card:', {
+        cardId,
+        isGameActive,
+        isProcessingMove: state.isProcessingMove,
+        currentPlayer: state.currentPlayer,
+        flippedCardsCount: state.flippedCards.length,
+      })
+
+      if (!isGameActive || state.isProcessingMove) {
+        console.log('[LocalProvider][canFlipCard] Blocked: game not active or processing')
+        return false
+      }
+
+      const card = state.gameCards.find((c) => c.id === cardId)
+      if (!card || card.matched) {
+        console.log('[LocalProvider][canFlipCard] Blocked: card not found or already matched')
+        return false
+      }
+
+      // Can't flip if already flipped
+      if (state.flippedCards.some((c) => c.id === cardId)) {
+        console.log('[LocalProvider][canFlipCard] Blocked: card already flipped')
+        return false
+      }
+
+      // Can't flip more than 2 cards
+      if (state.flippedCards.length >= 2) {
+        console.log('[LocalProvider][canFlipCard] Blocked: 2 cards already flipped')
+        return false
+      }
+
+      // In local play, we allow the current player to flip
+      // Authorization is simpler - just check if it's this player's turn
+      const currentPlayerData = players.get(state.currentPlayer)
+      console.log('[LocalProvider][canFlipCard] Authorization check:', {
+        currentPlayerId: state.currentPlayer,
+        currentPlayerFound: !!currentPlayerData,
+        currentPlayerIsLocal: currentPlayerData?.isLocal,
+      })
+
+      // Block if current player is explicitly marked as remote (shouldn't happen in local play)
+      if (currentPlayerData && currentPlayerData.isLocal === false) {
+        console.log(
+          '[LocalProvider][canFlipCard] BLOCKED: Current player is remote (unexpected in local play)'
+        )
+        return false
+      }
+
+      console.log('[LocalProvider][canFlipCard] ALLOWED: All checks passed')
+      return true
+    },
+    [
+      isGameActive,
+      state.isProcessingMove,
+      state.gameCards,
+      state.flippedCards,
+      state.currentPlayer,
+      players,
+    ]
+  )
+
+  const currentGameStatistics: GameStatistics = useMemo(
+    () => ({
+      totalMoves: state.moves,
+      matchedPairs: state.matchedPairs,
+      totalPairs: state.totalPairs,
+      gameTime: state.gameStartTime ? (state.gameEndTime || Date.now()) - state.gameStartTime : 0,
+      accuracy: state.moves > 0 ? (state.matchedPairs / state.moves) * 100 : 0,
+      averageTimePerMove:
+        state.moves > 0 && state.gameStartTime
+          ? ((state.gameEndTime || Date.now()) - state.gameStartTime) / state.moves
+          : 0,
+    }),
+    [state.moves, state.matchedPairs, state.totalPairs, state.gameStartTime, state.gameEndTime]
+  )
+
+  // PAUSE/RESUME: Computed values for pause/resume functionality
+  const hasConfigChanged = useMemo(() => {
+    if (!state.originalConfig) return false
+    return (
+      state.gameType !== state.originalConfig.gameType ||
+      state.difficulty !== state.originalConfig.difficulty ||
+      state.turnTimer !== state.originalConfig.turnTimer
+    )
+  }, [state.gameType, state.difficulty, state.turnTimer, state.originalConfig])
+
+  const canResumeGame = useMemo(() => {
+    return !!state.pausedGamePhase && !!state.pausedGameState && !hasConfigChanged
+  }, [state.pausedGamePhase, state.pausedGameState, hasConfigChanged])
+
+  // Action creators - send moves to arcade session
+  const startGame = useCallback(() => {
+    // Must have at least one active player
+    if (activePlayers.length === 0) {
+      console.error('[LocalMemoryPairs] Cannot start game without active players')
+      return
+    }
+
+    // Capture player metadata from local players map
+    // This ensures all room members can display player info even if they don't own the players
+    const playerMetadata: { [playerId: string]: any } = {}
+    for (const playerId of activePlayers) {
+      const playerData = players.get(playerId)
+      if (playerData) {
+        playerMetadata[playerId] = {
+          id: playerId,
+          name: playerData.name,
+          emoji: playerData.emoji,
+          userId: viewerId || '',
+          color: playerData.color,
+        }
+      }
+    }
+
+    // Use current session state configuration (no local state!)
+    const cards = generateGameCards(state.gameType, state.difficulty)
+    // Use first active player as playerId for START_GAME move
+    const firstPlayer = activePlayers[0]
+    sendMove({
+      type: 'START_GAME',
+      playerId: firstPlayer,
+      data: {
+        cards,
+        activePlayers,
+        playerMetadata,
+      },
+    })
+  }, [state.gameType, state.difficulty, activePlayers, players, viewerId, sendMove])
+
+  const flipCard = useCallback(
+    (cardId: string) => {
+      console.log('[LocalProvider] flipCard called:', {
+        cardId,
+        viewerId,
+        currentPlayer: state.currentPlayer,
+        activePlayers: state.activePlayers,
+        gamePhase: state.gamePhase,
+        canFlip: canFlipCard(cardId),
+      })
+
+      if (!canFlipCard(cardId)) {
+        console.log('[LocalProvider] Cannot flip card - canFlipCard returned false')
+        return
+      }
+
+      const move = {
+        type: 'FLIP_CARD' as const,
+        playerId: state.currentPlayer, // Use the current player ID from game state (database player ID)
+        data: { cardId },
+      }
+      console.log('[LocalProvider] Sending FLIP_CARD move via sendMove:', move)
+      sendMove(move)
+    },
+    [canFlipCard, sendMove, viewerId, state.currentPlayer, state.activePlayers, state.gamePhase]
+  )
+
+  const resetGame = useCallback(() => {
+    // Must have at least one active player
+    if (activePlayers.length === 0) {
+      console.error('[LocalMemoryPairs] Cannot reset game without active players')
+      return
+    }
+
+    // Capture player metadata from local players map
+    const playerMetadata: { [playerId: string]: any } = {}
+    for (const playerId of activePlayers) {
+      const playerData = players.get(playerId)
+      if (playerData) {
+        playerMetadata[playerId] = {
+          id: playerId,
+          name: playerData.name,
+          emoji: playerData.emoji,
+          userId: viewerId || '',
+          color: playerData.color,
+        }
+      }
+    }
+
+    // Use current session state configuration (no local state!)
+    const cards = generateGameCards(state.gameType, state.difficulty)
+    // Use first active player as playerId for START_GAME move
+    const firstPlayer = activePlayers[0]
+    sendMove({
+      type: 'START_GAME',
+      playerId: firstPlayer,
+      data: {
+        cards,
+        activePlayers,
+        playerMetadata,
+      },
+    })
+  }, [state.gameType, state.difficulty, activePlayers, players, viewerId, sendMove])
+
+  const setGameType = useCallback(
+    (gameType: typeof state.gameType) => {
+      // Use first active player as playerId, or empty string if none
+      const playerId = activePlayers[0] || ''
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId,
+        data: { field: 'gameType', value: gameType },
+      })
+    },
+    [activePlayers, sendMove]
+  )
+
+  const setDifficulty = useCallback(
+    (difficulty: typeof state.difficulty) => {
+      const playerId = activePlayers[0] || ''
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId,
+        data: { field: 'difficulty', value: difficulty },
+      })
+    },
+    [activePlayers, sendMove]
+  )
+
+  const setTurnTimer = useCallback(
+    (turnTimer: typeof state.turnTimer) => {
+      const playerId = activePlayers[0] || ''
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId,
+        data: { field: 'turnTimer', value: turnTimer },
+      })
+    },
+    [activePlayers, sendMove]
+  )
+
+  const resumeGame = useCallback(() => {
+    // PAUSE/RESUME: Resume paused game if config unchanged
+    if (!canResumeGame) {
+      console.warn('[LocalMemoryPairs] Cannot resume - no paused game or config changed')
+      return
+    }
+
+    const playerId = activePlayers[0] || state.currentPlayer || ''
+    sendMove({
+      type: 'RESUME_GAME',
+      playerId,
+      data: {},
+    })
+  }, [canResumeGame, activePlayers, state.currentPlayer, sendMove])
+
+  const goToSetup = useCallback(() => {
+    // Send GO_TO_SETUP move - synchronized across all room members
+    const playerId = activePlayers[0] || state.currentPlayer || ''
+    sendMove({
+      type: 'GO_TO_SETUP',
+      playerId,
+      data: {},
+    })
+  }, [activePlayers, state.currentPlayer, sendMove])
+
+  // NO MORE effectiveState merging! Just use session state directly with gameMode added
+  const effectiveState = { ...state, gameMode } as MemoryPairsState & { gameMode: GameMode }
+
+  const contextValue: MemoryPairsContextValue = {
+    state: effectiveState,
+    dispatch: () => {
+      // No-op - replaced with sendMove
+      console.warn('dispatch() is deprecated in arcade mode, use action creators instead')
+    },
+    isGameActive,
+    canFlipCard,
+    currentGameStatistics,
+    hasConfigChanged,
+    canResumeGame,
+    startGame,
+    resumeGame,
+    flipCard,
+    resetGame,
+    goToSetup,
+    setGameType,
+    setDifficulty,
+    setTurnTimer,
+    exitSession,
+    gameMode,
+    activePlayers,
+  }
+
+  return <MemoryPairsContext.Provider value={contextValue}>{children}</MemoryPairsContext.Provider>
+}

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

@@ -0,0 +1,545 @@
+'use client'
+
+import { type ReactNode, useCallback, useEffect, useMemo } from 'react'
+import { useArcadeSession } from '@/hooks/useArcadeSession'
+import { useRoomData } from '@/hooks/useRoomData'
+import { useViewerId } from '@/hooks/useViewerId'
+import type { GameMove } from '@/lib/arcade/validation'
+import { useGameMode } from '../../../../contexts/GameModeContext'
+import { generateGameCards } from '../utils/cardGeneration'
+import { MemoryPairsContext } from './MemoryPairsContext'
+import type { GameMode, GameStatistics, MemoryPairsContextValue, MemoryPairsState } from './types'
+
+// Initial state
+const initialState: MemoryPairsState = {
+  cards: [],
+  gameCards: [],
+  flippedCards: [],
+  gameType: 'abacus-numeral',
+  difficulty: 6,
+  turnTimer: 30,
+  gamePhase: 'setup',
+  currentPlayer: '', // Will be set to first player ID on START_GAME
+  matchedPairs: 0,
+  totalPairs: 6,
+  moves: 0,
+  scores: {},
+  activePlayers: [],
+  playerMetadata: {}, // Player metadata for cross-user visibility
+  consecutiveMatches: {},
+  gameStartTime: null,
+  gameEndTime: null,
+  currentMoveStartTime: null,
+  timerInterval: null,
+  celebrationAnimations: [],
+  isProcessingMove: false,
+  showMismatchFeedback: false,
+  lastMatchedPair: null,
+  // PAUSE/RESUME: Initialize paused game fields
+  originalConfig: undefined,
+  pausedGamePhase: undefined,
+  pausedGameState: undefined,
+}
+
+/**
+ * Optimistic move application (client-side prediction)
+ * The server will validate and send back the authoritative state
+ */
+function applyMoveOptimistically(state: MemoryPairsState, move: GameMove): MemoryPairsState {
+  switch (move.type) {
+    case 'START_GAME':
+      // Generate cards and initialize game
+      return {
+        ...state,
+        gamePhase: 'playing',
+        gameCards: move.data.cards,
+        cards: move.data.cards,
+        flippedCards: [],
+        matchedPairs: 0,
+        moves: 0,
+        scores: move.data.activePlayers.reduce((acc: any, p: string) => ({ ...acc, [p]: 0 }), {}),
+        consecutiveMatches: move.data.activePlayers.reduce(
+          (acc: any, p: string) => ({ ...acc, [p]: 0 }),
+          {}
+        ),
+        activePlayers: move.data.activePlayers,
+        playerMetadata: move.data.playerMetadata || {}, // Include player metadata
+        currentPlayer: move.data.activePlayers[0] || '',
+        gameStartTime: Date.now(),
+        gameEndTime: null,
+        currentMoveStartTime: Date.now(),
+        celebrationAnimations: [],
+        isProcessingMove: false,
+        showMismatchFeedback: false,
+        lastMatchedPair: null,
+        // PAUSE/RESUME: Save original config and clear paused state
+        originalConfig: {
+          gameType: state.gameType,
+          difficulty: state.difficulty,
+          turnTimer: state.turnTimer,
+        },
+        pausedGamePhase: undefined,
+        pausedGameState: undefined,
+      }
+
+    case 'FLIP_CARD': {
+      // Optimistically flip the card
+      const card = state.gameCards.find((c) => c.id === move.data.cardId)
+      if (!card) return state
+
+      const newFlippedCards = [...state.flippedCards, card]
+
+      return {
+        ...state,
+        flippedCards: newFlippedCards,
+        currentMoveStartTime:
+          state.flippedCards.length === 0 ? Date.now() : state.currentMoveStartTime,
+        isProcessingMove: newFlippedCards.length === 2, // Processing if 2 cards flipped
+        showMismatchFeedback: false,
+      }
+    }
+
+    case 'CLEAR_MISMATCH': {
+      // Clear mismatched cards and feedback
+      return {
+        ...state,
+        flippedCards: [],
+        showMismatchFeedback: false,
+        isProcessingMove: false,
+      }
+    }
+
+    case 'GO_TO_SETUP': {
+      // Return to setup phase - pause game if coming from playing/results
+      const isPausingGame = state.gamePhase === 'playing' || state.gamePhase === 'results'
+
+      return {
+        ...state,
+        gamePhase: 'setup',
+        // PAUSE: Save game state if pausing from active game
+        pausedGamePhase: isPausingGame ? state.gamePhase : undefined,
+        pausedGameState: isPausingGame
+          ? {
+              gameCards: state.gameCards,
+              currentPlayer: state.currentPlayer,
+              matchedPairs: state.matchedPairs,
+              moves: state.moves,
+              scores: state.scores,
+              activePlayers: state.activePlayers,
+              playerMetadata: state.playerMetadata,
+              consecutiveMatches: state.consecutiveMatches,
+              gameStartTime: state.gameStartTime,
+            }
+          : undefined,
+        // Reset visible game state
+        gameCards: [],
+        cards: [],
+        flippedCards: [],
+        currentPlayer: '',
+        matchedPairs: 0,
+        moves: 0,
+        scores: {},
+        activePlayers: [],
+        playerMetadata: {},
+        consecutiveMatches: {},
+        gameStartTime: null,
+        gameEndTime: null,
+        currentMoveStartTime: null,
+        celebrationAnimations: [],
+        isProcessingMove: false,
+        showMismatchFeedback: false,
+        lastMatchedPair: null,
+      }
+    }
+
+    case 'SET_CONFIG': {
+      // Update configuration field optimistically
+      const { field, value } = move.data as { field: string; value: any }
+      const clearPausedGame = !!state.pausedGamePhase
+
+      return {
+        ...state,
+        [field]: value,
+        // Update totalPairs if difficulty changes
+        ...(field === 'difficulty' ? { totalPairs: value } : {}),
+        // Clear paused game if config changed
+        ...(clearPausedGame
+          ? { pausedGamePhase: undefined, pausedGameState: undefined, originalConfig: undefined }
+          : {}),
+      }
+    }
+
+    case 'RESUME_GAME': {
+      // Resume paused game
+      if (!state.pausedGamePhase || !state.pausedGameState) {
+        return state // No paused game, no-op
+      }
+
+      return {
+        ...state,
+        gamePhase: state.pausedGamePhase,
+        gameCards: state.pausedGameState.gameCards,
+        cards: state.pausedGameState.gameCards,
+        currentPlayer: state.pausedGameState.currentPlayer,
+        matchedPairs: state.pausedGameState.matchedPairs,
+        moves: state.pausedGameState.moves,
+        scores: state.pausedGameState.scores,
+        activePlayers: state.pausedGameState.activePlayers,
+        playerMetadata: state.pausedGameState.playerMetadata,
+        consecutiveMatches: state.pausedGameState.consecutiveMatches,
+        gameStartTime: state.pausedGameState.gameStartTime,
+        // Clear paused state
+        pausedGamePhase: undefined,
+        pausedGameState: undefined,
+      }
+    }
+
+    default:
+      return state
+  }
+}
+
+// Provider component for ROOM-BASED play (with network sync)
+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()
+
+  // Get active player IDs directly as strings (UUIDs)
+  const activePlayers = Array.from(activePlayerIds)
+
+  // 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
+
+  // Arcade session integration WITH room sync
+  const {
+    state,
+    sendMove,
+    connected: _connected,
+    exitSession,
+  } = useArcadeSession<MemoryPairsState>({
+    userId: viewerId || '',
+    roomId: roomData?.id, // CRITICAL: Pass roomId for network sync across room members
+    initialState,
+    applyMove: applyMoveOptimistically,
+  })
+
+  // Handle mismatch feedback timeout
+  useEffect(() => {
+    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,
+          data: {},
+        })
+      }, 1500)
+
+      return () => clearTimeout(timeout)
+    }
+  }, [state.showMismatchFeedback, state.flippedCards.length, sendMove, state.currentPlayer])
+
+  // Computed values
+  const isGameActive = state.gamePhase === 'playing'
+
+  const canFlipCard = useCallback(
+    (cardId: string): boolean => {
+      console.log('[RoomProvider][canFlipCard] Checking card:', {
+        cardId,
+        isGameActive,
+        isProcessingMove: state.isProcessingMove,
+        currentPlayer: state.currentPlayer,
+        hasRoomData: !!roomData,
+        flippedCardsCount: state.flippedCards.length,
+      })
+
+      if (!isGameActive || state.isProcessingMove) {
+        console.log('[RoomProvider][canFlipCard] Blocked: game not active or processing')
+        return false
+      }
+
+      const card = state.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)) {
+        console.log('[RoomProvider][canFlipCard] Blocked: card already flipped')
+        return false
+      }
+
+      // Can't flip more than 2 cards
+      if (state.flippedCards.length >= 2) {
+        console.log('[RoomProvider][canFlipCard] Blocked: 2 cards already flipped')
+        return false
+      }
+
+      // Authorization check: Only allow flipping if it's your player's turn
+      if (roomData && state.currentPlayer) {
+        const currentPlayerData = players.get(state.currentPlayer)
+        console.log('[RoomProvider][canFlipCard] Authorization check:', {
+          currentPlayerId: state.currentPlayer,
+          currentPlayerFound: !!currentPlayerData,
+          currentPlayerIsLocal: currentPlayerData?.isLocal,
+        })
+
+        // Block if current player is explicitly marked as remote (isLocal === false)
+        if (currentPlayerData && currentPlayerData.isLocal === false) {
+          console.log(
+            '[RoomProvider][canFlipCard] BLOCKED: Current player is remote (not your turn)'
+          )
+          return false
+        }
+
+        // If player data not found in map, this might be an issue - allow for now but warn
+        if (!currentPlayerData) {
+          console.warn(
+            '[RoomProvider][canFlipCard] WARNING: Current player not found in players map, allowing move'
+          )
+        }
+      }
+
+      console.log('[RoomProvider][canFlipCard] ALLOWED: All checks passed')
+      return true
+    },
+    [
+      isGameActive,
+      state.isProcessingMove,
+      state.gameCards,
+      state.flippedCards,
+      state.currentPlayer,
+      roomData,
+      players,
+    ]
+  )
+
+  const currentGameStatistics: GameStatistics = useMemo(
+    () => ({
+      totalMoves: state.moves,
+      matchedPairs: state.matchedPairs,
+      totalPairs: state.totalPairs,
+      gameTime: state.gameStartTime ? (state.gameEndTime || Date.now()) - state.gameStartTime : 0,
+      accuracy: state.moves > 0 ? (state.matchedPairs / state.moves) * 100 : 0,
+      averageTimePerMove:
+        state.moves > 0 && state.gameStartTime
+          ? ((state.gameEndTime || Date.now()) - state.gameStartTime) / state.moves
+          : 0,
+    }),
+    [state.moves, state.matchedPairs, state.totalPairs, state.gameStartTime, state.gameEndTime]
+  )
+
+  // PAUSE/RESUME: Computed values for pause/resume functionality
+  const hasConfigChanged = useMemo(() => {
+    if (!state.originalConfig) return false
+    return (
+      state.gameType !== state.originalConfig.gameType ||
+      state.difficulty !== state.originalConfig.difficulty ||
+      state.turnTimer !== state.originalConfig.turnTimer
+    )
+  }, [state.gameType, state.difficulty, state.turnTimer, state.originalConfig])
+
+  const canResumeGame = useMemo(() => {
+    return !!state.pausedGamePhase && !!state.pausedGameState && !hasConfigChanged
+  }, [state.pausedGamePhase, state.pausedGameState, hasConfigChanged])
+
+  // Action creators - send moves to arcade session
+  const startGame = useCallback(() => {
+    // Must have at least one active player
+    if (activePlayers.length === 0) {
+      console.error('[RoomMemoryPairs] Cannot start game without active players')
+      return
+    }
+
+    // Capture player metadata from local players map
+    // This ensures all room members can display player info even if they don't own the players
+    const playerMetadata: { [playerId: string]: any } = {}
+    for (const playerId of activePlayers) {
+      const playerData = players.get(playerId)
+      if (playerData) {
+        playerMetadata[playerId] = {
+          id: playerId,
+          name: playerData.name,
+          emoji: playerData.emoji,
+          userId: viewerId || '',
+          color: playerData.color,
+        }
+      }
+    }
+
+    // Use current session state configuration (no local state!)
+    const cards = generateGameCards(state.gameType, state.difficulty)
+    // Use first active player as playerId for START_GAME move
+    const firstPlayer = activePlayers[0]
+    sendMove({
+      type: 'START_GAME',
+      playerId: firstPlayer,
+      data: {
+        cards,
+        activePlayers,
+        playerMetadata,
+      },
+    })
+  }, [state.gameType, state.difficulty, activePlayers, players, viewerId, sendMove])
+
+  const flipCard = useCallback(
+    (cardId: string) => {
+      console.log('[RoomProvider] flipCard called:', {
+        cardId,
+        viewerId,
+        currentPlayer: state.currentPlayer,
+        activePlayers: state.activePlayers,
+        gamePhase: state.gamePhase,
+        canFlip: canFlipCard(cardId),
+      })
+
+      if (!canFlipCard(cardId)) {
+        console.log('[RoomProvider] Cannot flip card - canFlipCard returned false')
+        return
+      }
+
+      const move = {
+        type: 'FLIP_CARD' as const,
+        playerId: state.currentPlayer, // Use the current player ID from game state (database player ID)
+        data: { cardId },
+      }
+      console.log('[RoomProvider] Sending FLIP_CARD move via sendMove:', move)
+      sendMove(move)
+    },
+    [canFlipCard, sendMove, viewerId, state.currentPlayer, state.activePlayers, state.gamePhase]
+  )
+
+  const resetGame = useCallback(() => {
+    // Must have at least one active player
+    if (activePlayers.length === 0) {
+      console.error('[RoomMemoryPairs] Cannot reset game without active players')
+      return
+    }
+
+    // Capture player metadata from local players map
+    const playerMetadata: { [playerId: string]: any } = {}
+    for (const playerId of activePlayers) {
+      const playerData = players.get(playerId)
+      if (playerData) {
+        playerMetadata[playerId] = {
+          id: playerId,
+          name: playerData.name,
+          emoji: playerData.emoji,
+          userId: viewerId || '',
+          color: playerData.color,
+        }
+      }
+    }
+
+    // Use current session state configuration (no local state!)
+    const cards = generateGameCards(state.gameType, state.difficulty)
+    // Use first active player as playerId for START_GAME move
+    const firstPlayer = activePlayers[0]
+    sendMove({
+      type: 'START_GAME',
+      playerId: firstPlayer,
+      data: {
+        cards,
+        activePlayers,
+        playerMetadata,
+      },
+    })
+  }, [state.gameType, state.difficulty, activePlayers, players, viewerId, sendMove])
+
+  const setGameType = useCallback(
+    (gameType: typeof state.gameType) => {
+      // Use first active player as playerId, or empty string if none
+      const playerId = activePlayers[0] || ''
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId,
+        data: { field: 'gameType', value: gameType },
+      })
+    },
+    [activePlayers, sendMove]
+  )
+
+  const setDifficulty = useCallback(
+    (difficulty: typeof state.difficulty) => {
+      const playerId = activePlayers[0] || ''
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId,
+        data: { field: 'difficulty', value: difficulty },
+      })
+    },
+    [activePlayers, sendMove]
+  )
+
+  const setTurnTimer = useCallback(
+    (turnTimer: typeof state.turnTimer) => {
+      const playerId = activePlayers[0] || ''
+      sendMove({
+        type: 'SET_CONFIG',
+        playerId,
+        data: { field: 'turnTimer', value: turnTimer },
+      })
+    },
+    [activePlayers, sendMove]
+  )
+
+  const goToSetup = useCallback(() => {
+    // Send GO_TO_SETUP move - synchronized across all room members
+    const playerId = activePlayers[0] || state.currentPlayer || ''
+    sendMove({
+      type: 'GO_TO_SETUP',
+      playerId,
+      data: {},
+    })
+  }, [activePlayers, state.currentPlayer, sendMove])
+
+  const resumeGame = useCallback(() => {
+    // PAUSE/RESUME: Resume paused game if config unchanged
+    if (!canResumeGame) {
+      console.warn('[RoomMemoryPairs] Cannot resume - no paused game or config changed')
+      return
+    }
+
+    const playerId = activePlayers[0] || state.currentPlayer || ''
+    sendMove({
+      type: 'RESUME_GAME',
+      playerId,
+      data: {},
+    })
+  }, [canResumeGame, activePlayers, state.currentPlayer, sendMove])
+
+  // NO MORE effectiveState merging! Just use session state directly with gameMode added
+  const effectiveState = { ...state, gameMode } as MemoryPairsState & { gameMode: GameMode }
+
+  const contextValue: MemoryPairsContextValue = {
+    state: effectiveState,
+    dispatch: () => {
+      // No-op - replaced with sendMove
+      console.warn('dispatch() is deprecated in arcade mode, use action creators instead')
+    },
+    isGameActive,
+    canFlipCard,
+    currentGameStatistics,
+    hasConfigChanged,
+    canResumeGame,
+    startGame,
+    resumeGame,
+    flipCard,
+    resetGame,
+    goToSetup,
+    setGameType,
+    setDifficulty,
+    setTurnTimer,
+    exitSession,
+    gameMode,
+    activePlayers,
+  }
+
+  return <MemoryPairsContext.Provider value={contextValue}>{children}</MemoryPairsContext.Provider>
+}

apps/web/src/app/games/matching/context/types.ts

@@ -40,6 +40,20 @@ export interface GameStatistics {
   averageTimePerMove: number
 }
 
+export interface PlayerMetadata {
+  id: string // Player ID
+  name: string
+  emoji: string
+  userId: string // Which user owns this player
+  color?: string
+}
+
+export interface GameConfiguration {
+  gameType: GameType
+  difficulty: Difficulty
+  turnTimer: number
+}
+
 export interface MemoryPairsState {
   // Core game data
   cards: GameCard[]
@@ -51,6 +65,22 @@ export interface MemoryPairsState {
   difficulty: Difficulty
   turnTimer: number // Seconds for two-player mode
 
+  // Paused game state - for Resume functionality
+  originalConfig?: GameConfiguration // Config when game started - used to detect changes
+  pausedGamePhase?: 'playing' | 'results' // Set when GO_TO_SETUP called from active game
+  pausedGameState?: {
+    // Snapshot of game state when paused
+    gameCards: GameCard[]
+    currentPlayer: Player
+    matchedPairs: number
+    moves: number
+    scores: PlayerScore
+    activePlayers: Player[]
+    playerMetadata: { [playerId: string]: PlayerMetadata }
+    consecutiveMatches: { [playerId: string]: number }
+    gameStartTime: number | null
+  }
+
   // Game progression
   gamePhase: GamePhase
   currentPlayer: Player
@@ -59,6 +89,7 @@ export interface MemoryPairsState {
   moves: number
   scores: PlayerScore
   activePlayers: Player[] // Track active player IDs
+  playerMetadata: { [playerId: string]: PlayerMetadata } // Player metadata snapshot for cross-user visibility
   consecutiveMatches: { [playerId: string]: number } // Track consecutive matches per player
 
   // Timing
@@ -101,13 +132,18 @@ export interface MemoryPairsContextValue {
   currentGameStatistics: GameStatistics
   gameMode: GameMode // Derived from global context
   activePlayers: Player[] // Active player IDs from arena
+  hasConfigChanged: boolean // True if current config differs from originalConfig
+  canResumeGame: boolean // True if there's a paused game and config hasn't changed
 
   // Actions
   startGame: () => void
+  resumeGame: () => void
   flipCard: (cardId: string) => void
   resetGame: () => void
   setGameType: (type: GameType) => void
   setDifficulty: (difficulty: Difficulty) => void
+  setTurnTimer: (timer: number) => void
+  goToSetup: () => void
   exitSession: () => void // Exit arcade session (no-op for non-arcade mode)
 }
 
@@ -133,14 +169,6 @@ export interface GameGridProps {
   disabled?: boolean
 }
 
-// Configuration interfaces
-export interface GameConfiguration {
-  gameMode: GameMode
-  gameType: GameType
-  difficulty: Difficulty
-  turnTimer: number
-}
-
 export interface MatchValidationResult {
   isValid: boolean
   reason?: string

apps/web/src/hooks/useArcadeSession.ts

@@ -48,8 +48,9 @@ export interface UseArcadeSessionReturn<TState> {
 
   /**
    * Send a game move (applies optimistically and sends to server)
+   * Note: playerId must be provided by caller (not omitted)
    */
-  sendMove: (move: Omit<GameMove, 'playerId' | 'timestamp'>) => void
+  sendMove: (move: Omit<GameMove, 'timestamp'>) => void
 
   /**
    * Exit the arcade session
@@ -149,10 +150,10 @@ export function useArcadeSession<TState>(
       // Apply optimistically
       optimistic.applyOptimisticMove(fullMove)
 
-      // Send to server
-      socketSendMove(userId, fullMove)
+      // Send to server with roomId for room-based games
+      socketSendMove(userId, fullMove, roomId)
     },
-    [userId, optimistic, socketSendMove]
+    [userId, roomId, optimistic, socketSendMove]
   )
 
   const exitSession = useCallback(() => {

apps/web/src/hooks/useArcadeSocket.ts

@@ -21,7 +21,7 @@ export interface UseArcadeSocketReturn {
   socket: Socket | null
   connected: boolean
   joinSession: (userId: string, roomId?: string) => void
-  sendMove: (userId: string, move: GameMove) => void
+  sendMove: (userId: string, move: GameMove, roomId?: string) => void
   exitSession: (userId: string) => void
   pingSession: (userId: string) => void
 }
@@ -119,12 +119,12 @@ export function useArcadeSocket(events: ArcadeSocketEvents = {}): UseArcadeSocke
   )
 
   const sendMove = useCallback(
-    (userId: string, move: GameMove) => {
+    (userId: string, move: GameMove, roomId?: string) => {
       if (!socket) {
         console.warn('[ArcadeSocket] Cannot send move - socket not connected')
         return
       }
-      const payload = { userId, move }
+      const payload = { userId, move, roomId }
       console.log(
         '[ArcadeSocket] Sending game-move event with payload:',
         JSON.stringify(payload, null, 2)

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

@@ -37,8 +37,35 @@ async function getUserIdFromGuestId(guestId: string): Promise<string | undefined
   return user?.id
 }
 
+/**
+ * Get arcade session by room ID (for room-based multiplayer games)
+ * Returns the shared session for all room members
+ * @param roomId - The room ID
+ */
+export async function getArcadeSessionByRoom(
+  roomId: string
+): Promise<schema.ArcadeSession | undefined> {
+  const [session] = await db
+    .select()
+    .from(schema.arcadeSessions)
+    .where(eq(schema.arcadeSessions.roomId, roomId))
+    .limit(1)
+
+  if (!session) return undefined
+
+  // Check if session has expired
+  if (session.expiresAt < new Date()) {
+    // Clean up expired room session
+    await db.delete(schema.arcadeSessions).where(eq(schema.arcadeSessions.roomId, roomId))
+    return undefined
+  }
+
+  return session
+}
+
 /**
  * Create a new arcade session
+ * For room-based games, checks if a session already exists for the room
  */
 export async function createArcadeSession(
   options: CreateSessionOptions
@@ -46,6 +73,19 @@ export async function createArcadeSession(
   const now = new Date()
   const expiresAt = new Date(now.getTime() + TTL_HOURS * 60 * 60 * 1000)
 
+  // For room-based games, check if session already exists for this room
+  if (options.roomId) {
+    const existingRoomSession = await getArcadeSessionByRoom(options.roomId)
+    if (existingRoomSession) {
+      console.log('[Session Manager] Room session already exists, returning existing:', {
+        roomId: options.roomId,
+        sessionUserId: existingRoomSession.userId,
+        version: existingRoomSession.version,
+      })
+      return existingRoomSession
+    }
+  }
+
   // Find or create user by guest ID
   let user = await db.query.users.findFirst({
     where: eq(schema.users.guestId, options.userId),
@@ -80,6 +120,12 @@ export async function createArcadeSession(
     version: 1,
   }
 
+  console.log('[Session Manager] Creating new session:', {
+    userId: user.id,
+    roomId: options.roomId,
+    gameName: options.gameName,
+  })
+
   const [session] = await db.insert(schema.arcadeSessions).values(newSession).returning()
   return session
 }
@@ -130,9 +176,18 @@ export async function getArcadeSession(guestId: string): Promise<schema.ArcadeSe
 
 /**
  * Apply a game move to the session (with validation)
+ * @param userId - The guest ID from the cookie
+ * @param move - The game move to apply
+ * @param roomId - Optional room ID for room-based games (enables shared session)
  */
-export async function applyGameMove(userId: string, move: GameMove): Promise<SessionUpdateResult> {
-  const session = await getArcadeSession(userId)
+export async function applyGameMove(
+  userId: string,
+  move: GameMove,
+  roomId?: string
+): Promise<SessionUpdateResult> {
+  // For room-based games, look up the shared room session
+  // For solo games, look up the user's personal session
+  const session = roomId ? await getArcadeSessionByRoom(roomId) : await getArcadeSession(userId)
 
   if (!session) {
     return {

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

@@ -25,11 +25,25 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
         return this.validateFlipCard(state, move.data.cardId, move.playerId, context)
 
       case 'START_GAME':
-        return this.validateStartGame(state, move.data.activePlayers, move.data.cards)
+        return this.validateStartGame(
+          state,
+          move.data.activePlayers,
+          move.data.cards,
+          move.data.playerMetadata
+        )
 
       case 'CLEAR_MISMATCH':
         return this.validateClearMismatch(state)
 
+      case 'GO_TO_SETUP':
+        return this.validateGoToSetup(state)
+
+      case 'SET_CONFIG':
+        return this.validateSetConfig(state, move.data.field, move.data.value)
+
+      case 'RESUME_GAME':
+        return this.validateResumeGame(state)
+
       default:
         return {
           valid: false,
@@ -183,7 +197,8 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
   private validateStartGame(
     state: MemoryPairsState,
     activePlayers: Player[],
-    cards?: GameCard[]
+    cards?: GameCard[],
+    playerMetadata?: { [playerId: string]: any }
   ): ValidationResult {
     // Allow starting a new game from any phase (for "New Game" button)
 
@@ -203,6 +218,7 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
       gameCards,
       cards: gameCards,
       activePlayers,
+      playerMetadata: playerMetadata || {}, // Store player metadata for cross-user visibility
       gamePhase: 'playing',
       gameStartTime: Date.now(),
       currentPlayer: activePlayers[0],
@@ -211,6 +227,15 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
       moves: 0,
       scores: activePlayers.reduce((acc, p) => ({ ...acc, [p]: 0 }), {}),
       consecutiveMatches: activePlayers.reduce((acc, p) => ({ ...acc, [p]: 0 }), {}),
+      // PAUSE/RESUME: Save original config so we can detect changes
+      originalConfig: {
+        gameType: state.gameType,
+        difficulty: state.difficulty,
+        turnTimer: state.turnTimer,
+      },
+      // Clear any paused game state (starting fresh)
+      pausedGamePhase: undefined,
+      pausedGameState: undefined,
     }
 
     return {
@@ -220,6 +245,16 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
   }
 
   private validateClearMismatch(state: MemoryPairsState): ValidationResult {
+    // Only clear if there's actually a mismatch showing
+    // This prevents race conditions where CLEAR_MISMATCH arrives after cards have already been cleared
+    if (!state.showMismatchFeedback || state.flippedCards.length === 0) {
+      // Nothing to clear - return current state unchanged
+      return {
+        valid: true,
+        newState: state,
+      }
+    }
+
     // Clear mismatched cards and feedback
     return {
       valid: true,
@@ -232,6 +267,218 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
     }
   }
 
+  /**
+   * STANDARD ARCADE PATTERN: GO_TO_SETUP
+   *
+   * Transitions the game back to setup phase, allowing players to reconfigure
+   * the game. This is synchronized across all room members.
+   *
+   * Can be called from any phase (setup, playing, results).
+   *
+   * PAUSE/RESUME: If called from 'playing' or 'results', saves game state
+   * to allow resuming later (if config unchanged).
+   *
+   * Pattern for all arcade games:
+   * - Validates the move is allowed
+   * - Sets gamePhase to 'setup'
+   * - Preserves current configuration (gameType, difficulty, etc.)
+   * - Saves game state for resume if coming from active game
+   * - Resets game progression state (scores, cards, etc.)
+   */
+  private validateGoToSetup(state: MemoryPairsState): ValidationResult {
+    // Determine if we're pausing an active game (for Resume functionality)
+    const isPausingGame = state.gamePhase === 'playing' || state.gamePhase === 'results'
+
+    return {
+      valid: true,
+      newState: {
+        ...state,
+        gamePhase: 'setup',
+
+        // Pause/Resume: Save game state if pausing from active game
+        pausedGamePhase: isPausingGame ? state.gamePhase : undefined,
+        pausedGameState: isPausingGame
+          ? {
+              gameCards: state.gameCards,
+              currentPlayer: state.currentPlayer,
+              matchedPairs: state.matchedPairs,
+              moves: state.moves,
+              scores: state.scores,
+              activePlayers: state.activePlayers,
+              playerMetadata: state.playerMetadata,
+              consecutiveMatches: state.consecutiveMatches,
+              gameStartTime: state.gameStartTime,
+            }
+          : undefined,
+
+        // Keep originalConfig if it exists (was set when game started)
+        // This allows detecting if config changed while paused
+
+        // Reset visible game progression
+        gameCards: [],
+        cards: [],
+        flippedCards: [],
+        currentPlayer: '',
+        matchedPairs: 0,
+        moves: 0,
+        scores: {},
+        activePlayers: [],
+        playerMetadata: {},
+        consecutiveMatches: {},
+        gameStartTime: null,
+        gameEndTime: null,
+        currentMoveStartTime: null,
+        celebrationAnimations: [],
+        isProcessingMove: false,
+        showMismatchFeedback: false,
+        lastMatchedPair: null,
+        // Preserve configuration - players can modify in setup
+        // gameType, difficulty, turnTimer stay as-is
+      },
+    }
+  }
+
+  /**
+   * STANDARD ARCADE PATTERN: SET_CONFIG
+   *
+   * Updates a configuration field during setup phase. This is synchronized
+   * across all room members in real-time, allowing collaborative setup.
+   *
+   * Pattern for all arcade games:
+   * - Only allowed during setup phase
+   * - Validates field name and value
+   * - Updates the configuration field
+   * - Other room members see the change immediately (optimistic + server validation)
+   *
+   * @param state Current game state
+   * @param field Configuration field name
+   * @param value New value for the field
+   */
+  private validateSetConfig(
+    state: MemoryPairsState,
+    field: 'gameType' | 'difficulty' | 'turnTimer',
+    value: any
+  ): ValidationResult {
+    // Can only change config during setup phase
+    if (state.gamePhase !== 'setup') {
+      return {
+        valid: false,
+        error: 'Cannot change configuration outside of setup phase',
+      }
+    }
+
+    // Validate field-specific values
+    switch (field) {
+      case 'gameType':
+        if (value !== 'abacus-numeral' && value !== 'complement-pairs') {
+          return { valid: false, error: `Invalid gameType: ${value}` }
+        }
+        break
+
+      case 'difficulty':
+        if (![6, 8, 12, 15].includes(value)) {
+          return { valid: false, error: `Invalid difficulty: ${value}` }
+        }
+        break
+
+      case 'turnTimer':
+        if (typeof value !== 'number' || value < 5 || value > 300) {
+          return { valid: false, error: `Invalid turnTimer: ${value}` }
+        }
+        break
+
+      default:
+        return { valid: false, error: `Unknown config field: ${field}` }
+    }
+
+    // PAUSE/RESUME: If there's a paused game and config is changing,
+    // clear the paused game state (can't resume anymore)
+    const clearPausedGame = !!state.pausedGamePhase
+
+    // Apply the configuration change
+    return {
+      valid: true,
+      newState: {
+        ...state,
+        [field]: value,
+        // Update totalPairs if difficulty changes
+        ...(field === 'difficulty' ? { totalPairs: value } : {}),
+        // Clear paused game if config changed
+        ...(clearPausedGame
+          ? { pausedGamePhase: undefined, pausedGameState: undefined, originalConfig: undefined }
+          : {}),
+      },
+    }
+  }
+
+  /**
+   * STANDARD ARCADE PATTERN: RESUME_GAME
+   *
+   * Resumes a paused game if configuration hasn't changed.
+   * Restores the saved game state from when GO_TO_SETUP was called.
+   *
+   * Pattern for all arcade games:
+   * - Validates there's a paused game
+   * - Validates config hasn't changed since pause
+   * - Restores game state and phase
+   * - Clears paused game state
+   */
+  private validateResumeGame(state: MemoryPairsState): ValidationResult {
+    // Must be in setup phase
+    if (state.gamePhase !== 'setup') {
+      return {
+        valid: false,
+        error: 'Can only resume from setup phase',
+      }
+    }
+
+    // Must have a paused game
+    if (!state.pausedGamePhase || !state.pausedGameState) {
+      return {
+        valid: false,
+        error: 'No paused game to resume',
+      }
+    }
+
+    // Config must match original (no changes while paused)
+    if (state.originalConfig) {
+      const configChanged =
+        state.gameType !== state.originalConfig.gameType ||
+        state.difficulty !== state.originalConfig.difficulty ||
+        state.turnTimer !== state.originalConfig.turnTimer
+
+      if (configChanged) {
+        return {
+          valid: false,
+          error: 'Cannot resume - configuration has changed',
+        }
+      }
+    }
+
+    // Restore the paused game
+    return {
+      valid: true,
+      newState: {
+        ...state,
+        gamePhase: state.pausedGamePhase,
+        gameCards: state.pausedGameState.gameCards,
+        cards: state.pausedGameState.gameCards,
+        currentPlayer: state.pausedGameState.currentPlayer,
+        matchedPairs: state.pausedGameState.matchedPairs,
+        moves: state.pausedGameState.moves,
+        scores: state.pausedGameState.scores,
+        activePlayers: state.pausedGameState.activePlayers,
+        playerMetadata: state.pausedGameState.playerMetadata,
+        consecutiveMatches: state.pausedGameState.consecutiveMatches,
+        gameStartTime: state.pausedGameState.gameStartTime,
+        // Clear paused state
+        pausedGamePhase: undefined,
+        pausedGameState: undefined,
+        // Keep originalConfig for potential future pauses
+      },
+    }
+  }
+
   isGameComplete(state: MemoryPairsState): boolean {
     return state.gamePhase === 'results' || state.matchedPairs === state.totalPairs
   }
@@ -255,6 +502,7 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
       moves: 0,
       scores: {},
       activePlayers: [],
+      playerMetadata: {}, // Initialize empty player metadata
       consecutiveMatches: {},
       gameStartTime: null,
       gameEndTime: null,
@@ -264,6 +512,10 @@ export class MatchingGameValidator implements GameValidator<MemoryPairsState, Ma
       isProcessingMove: false,
       showMismatchFeedback: false,
       lastMatchedPair: null,
+      // PAUSE/RESUME: Initialize paused game fields
+      originalConfig: undefined,
+      pausedGamePhase: undefined,
+      pausedGameState: undefined,
     }
   }
 }

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

@@ -33,6 +33,7 @@ export interface MatchingStartGameMove extends GameMove {
   data: {
     activePlayers: string[] // Player IDs (UUIDs)
     cards?: any[] // GameCard type from context
+    playerMetadata?: { [playerId: string]: any } // Player metadata for cross-user visibility
   }
 }
 
@@ -41,10 +42,32 @@ export interface MatchingClearMismatchMove extends GameMove {
   data: Record<string, never>
 }
 
+// Standard setup moves - pattern for all arcade games
+export interface MatchingGoToSetupMove extends GameMove {
+  type: 'GO_TO_SETUP'
+  data: Record<string, never>
+}
+
+export interface MatchingSetConfigMove extends GameMove {
+  type: 'SET_CONFIG'
+  data: {
+    field: 'gameType' | 'difficulty' | 'turnTimer'
+    value: any
+  }
+}
+
+export interface MatchingResumeGameMove extends GameMove {
+  type: 'RESUME_GAME'
+  data: Record<string, never>
+}
+
 export type MatchingGameMove =
   | MatchingFlipCardMove
   | MatchingStartGameMove
   | MatchingClearMismatchMove
+  | MatchingGoToSetupMove
+  | MatchingSetConfigMove
+  | MatchingResumeGameMove
 
 // Generic game state union
 export type GameState = MemoryPairsState // Add other game states as union later

package.json

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