@alepot55/chessboardjs 2.3.6 → 2.3.8

package/dist/chessboard.cjs.js

@@ -349,7 +349,7 @@ class PieceError extends ChessboardError {
 }
 
 /**
- * Service for input validation and data sanitization
+ * ValidationService - Handles input validation and data sanitization
  * @module services/ValidationService
  * @since 2.0.0
  */
@@ -398,45 +398,39 @@ const SIZE_CONSTRAINTS = Object.freeze({
 /**
  * Service responsible for validating inputs and data
  * Implements caching for performance optimization
- * @class
+ * @class ValidationService
  */
 class ValidationService {
     /**
-     * Creates a new ValidationService instance
+     * Create a new ValidationService instance
      */
     constructor() {
-        // Cache for validation results to improve performance
         this._validationCache = new Map();
         this._cacheMaxSize = 1000;
-        
-        // Compile patterns for reuse
         this._patterns = VALIDATION_PATTERNS;
         this._validValues = VALID_VALUES;
         this._constraints = SIZE_CONSTRAINTS;
     }
 
     /**
-     * Validates a square identifier with caching
+     * Validate a square identifier with caching
      * @param {string} square - Square to validate (e.g., 'e4')
      * @returns {boolean} True if valid
      */
     isValidSquare(square) {
         const cacheKey = `square:${square}`;
-        
         if (this._validationCache.has(cacheKey)) {
             return this._validationCache.get(cacheKey);
         }
-        
-        const isValid = typeof square === 'string' && 
-                        square.length === 2 && 
-                        this._patterns.square.test(square);
-        
+        const isValid = typeof square === 'string' &&
+            square.length === 2 &&
+            this._patterns.square.test(square);
         this._cacheValidationResult(cacheKey, isValid);
         return isValid;
     }
 
     /**
-     * Validates a piece identifier with enhanced format support
+     * Validate a piece identifier with enhanced format support
      * @param {string} piece - Piece to validate (e.g., 'wK', 'bp')
      * @returns {boolean} True if valid
      */
@@ -444,28 +438,22 @@ class ValidationService {
         if (typeof piece !== 'string' || piece.length !== 2) {
             return false;
         }
-        
         const cacheKey = `piece:${piece}`;
-        
         if (this._validationCache.has(cacheKey)) {
             return this._validationCache.get(cacheKey);
         }
-        
         const [first, second] = piece.split('');
-        
-        // Check both formats: [type][color] and [color][type]
-        const format1 = PIECE_TYPES.includes(first.toLowerCase()) && 
-                       PIECE_COLORS.includes(second);
-        const format2 = PIECE_COLORS.includes(first) && 
-                       PIECE_TYPES.includes(second.toLowerCase());
-        
+        const format1 = PIECE_TYPES.includes(first.toLowerCase()) &&
+            PIECE_COLORS.includes(second);
+        const format2 = PIECE_COLORS.includes(first) &&
+            PIECE_TYPES.includes(second.toLowerCase());
         const isValid = format1 || format2;
         this._cacheValidationResult(cacheKey, isValid);
         return isValid;
     }
 
     /**
-     * Validates a FEN string with comprehensive checks
+     * Validate a FEN string with comprehensive checks
      * @param {string} fen - FEN string to validate
      * @returns {boolean} True if valid
      */
@@ -473,86 +461,64 @@ class ValidationService {
         if (typeof fen !== 'string') {
             return false;
         }
-        
         const cacheKey = `fen:${fen}`;
-        
         if (this._validationCache.has(cacheKey)) {
             return this._validationCache.get(cacheKey);
         }
-        
-        // Basic pattern check
         if (!this._patterns.fen.test(fen)) {
             this._cacheValidationResult(cacheKey, false);
             return false;
         }
-        
-        // Additional FEN validation
         const isValid = this._validateFenStructure(fen);
         this._cacheValidationResult(cacheKey, isValid);
         return isValid;
     }
 
     /**
-     * Validates FEN structure in detail
+     * Validate FEN structure in detail
      * @private
      * @param {string} fen - FEN string to validate
      * @returns {boolean} True if valid
      */
     _validateFenStructure(fen) {
         const parts = fen.split(' ');
-        
         if (parts.length !== 6) {
             return false;
         }
-        
-        // Validate piece placement
         const ranks = parts[0].split('/');
         if (ranks.length !== 8) {
             return false;
         }
-        
-        // Validate each rank
         for (const rank of ranks) {
             if (!this._validateRank(rank)) {
                 return false;
             }
         }
-        
-        // Validate active color
         if (!['w', 'b'].includes(parts[1])) {
             return false;
         }
-        
-        // Validate castling rights
         if (!/^[KQkq-]*$/.test(parts[2])) {
             return false;
         }
-        
-        // Validate en passant target
         if (parts[3] !== '-' && !this.isValidSquare(parts[3])) {
             return false;
         }
-        
-        // Validate halfmove clock and fullmove number
         const halfmove = parseInt(parts[4], 10);
         const fullmove = parseInt(parts[5], 10);
-        
-        return !isNaN(halfmove) && !isNaN(fullmove) && 
-               halfmove >= 0 && fullmove >= 1;
+        return !isNaN(halfmove) && !isNaN(fullmove) &&
+            halfmove >= 0 && fullmove >= 1;
     }
 
     /**
-     * Validates a single rank in FEN notation
+     * Validate a single rank in FEN notation
      * @private
      * @param {string} rank - Rank to validate
      * @returns {boolean} True if valid
      */
     _validateRank(rank) {
         let squares = 0;
-        
         for (let i = 0; i < rank.length; i++) {
             const char = rank[i];
-            
             if (/[1-8]/.test(char)) {
                 squares += parseInt(char, 10);
             } else if (/[prnbqkPRNBQK]/.test(char)) {
@@ -561,12 +527,11 @@ class ValidationService {
                 return false;
             }
         }
-        
         return squares === 8;
     }
 
     /**
-     * Validates a move string with comprehensive format support
+     * Validate a move string with comprehensive format support
      * @param {string} move - Move string to validate (e.g., 'e2e4', 'e7e8q')
      * @returns {boolean} True if valid
      */
@@ -574,20 +539,17 @@ class ValidationService {
         if (typeof move !== 'string') {
             return false;
         }
-        
         const cacheKey = `move:${move}`;
-        
         if (this._validationCache.has(cacheKey)) {
             return this._validationCache.get(cacheKey);
         }
-        
         const isValid = this._validateMoveFormat(move);
         this._cacheValidationResult(cacheKey, isValid);
         return isValid;
     }
 
     /**
-     * Validates move format in detail
+     * Validate move format in detail
      * @private
      * @param {string} move - Move string to validate
      * @returns {boolean} True if valid
@@ -596,21 +558,15 @@ class ValidationService {
         if (move.length < 4 || move.length > 5) {
             return false;
         }
-        
-        const from = move.slice(0, 2);
-        const to = move.slice(2, 4);
-        const promotion = move.slice(4, 5);
-        
+        const from = move.substring(0, 2);
+        const to = move.substring(2, 4);
         if (!this.isValidSquare(from) || !this.isValidSquare(to)) {
             return false;
         }
-        
-        if (promotion && !this._validValues.promotionPieces.includes(promotion)) {
+        if (move.length === 5 && !/[qrnb]/i.test(move[4])) {
             return false;
         }
-        
-        // Additional move validation (e.g., source and target different)
-        return from !== to;
+        return true;
     }
 
     /**
@@ -640,11 +596,9 @@ class ValidationService {
         if (size === 'auto') {
             return true;
         }
-        
         if (typeof size === 'number') {
             return size >= this._constraints.min && size <= this._constraints.max;
         }
-        
         return false;
     }
 
@@ -654,9 +608,9 @@ class ValidationService {
      * @returns {boolean} True if valid
      */
     isValidTime(time) {
-        return typeof time === 'number' && 
-               time >= 0 && 
-               time <= this._constraints.maxTime;
+        return typeof time === 'number' &&
+            time >= 0 &&
+            time <= this._constraints.maxTime;
     }
 
     /**
@@ -674,10 +628,10 @@ class ValidationService {
      * @returns {boolean} True if valid
      */
     isValidElementId(id) {
-        return typeof id === 'string' && 
-               id.length > 0 && 
-               id.length <= 100 && // Reasonable length limit
-               /^[a-zA-Z][\w:-]*$/.test(id); // Valid HTML ID format
+        return typeof id === 'string' &&
+            id.length > 0 &&
+            id.length <= 100 && // Reasonable length limit
+            /^[a-zA-Z][\w:-]*$/.test(id); // Valid HTML ID format
     }
 
     /**
@@ -717,24 +671,20 @@ class ValidationService {
         if (typeof color !== 'string') {
             return false;
         }
-        
         // Check for hex colors
         if (this._patterns.color.test(color)) {
             return true;
         }
-        
         // Check for named colors (basic set)
         const namedColors = ['white', 'black', 'red', 'green', 'blue', 'yellow', 'cyan', 'magenta'];
         if (namedColors.includes(color.toLowerCase())) {
             return true;
         }
-        
         // Check for rgb/rgba format
         if (/^rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)$/.test(color) ||
             /^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*[0-1](\.\d+)?\s*\)$/.test(color)) {
             return true;
         }
-        
         return false;
     }
 
@@ -747,8 +697,8 @@ class ValidationService {
     validateSquare(square) {
         if (!this.isValidSquare(square)) {
             throw new ValidationError(
-                ERROR_MESSAGES.invalid_square + square, 
-                'square', 
+                ERROR_MESSAGES.invalid_square + square,
+                'square',
                 square
             );
         }
@@ -764,8 +714,8 @@ class ValidationService {
     validatePiece(piece) {
         if (!this.isValidPiece(piece)) {
             throw new ValidationError(
-                ERROR_MESSAGES.invalid_piece + piece, 
-                'piece', 
+                ERROR_MESSAGES.invalid_piece + piece,
+                'piece',
                 piece
             );
         }
@@ -781,8 +731,8 @@ class ValidationService {
     validateFen(fen) {
         if (!this.isValidFen(fen)) {
             throw new ValidationError(
-                ERROR_MESSAGES.invalid_fen + fen, 
-                'fen', 
+                ERROR_MESSAGES.invalid_fen + fen,
+                'fen',
                 fen
             );
         }
@@ -798,8 +748,8 @@ class ValidationService {
     validateMove(move) {
         if (!this.isValidMove(move)) {
             throw new ValidationError(
-                ERROR_MESSAGES.invalid_move + move, 
-                'move', 
+                ERROR_MESSAGES.invalid_move + move,
+                'move',
                 move
             );
         }
@@ -815,16 +765,15 @@ class ValidationService {
     validateOrientation(orientation) {
         if (!this.isValidOrientation(orientation)) {
             throw new ValidationError(
-                ERROR_MESSAGES.invalid_orientation + orientation, 
-                'orientation', 
+                ERROR_MESSAGES.invalid_orientation + orientation,
+                'orientation',
                 orientation
             );
         }
-        
         // Normalize to 'w' or 'b'
-        return orientation === 'white' ? 'w' : 
-               orientation === 'black' ? 'b' : 
-               orientation;
+        return orientation === 'white' ? 'w' :
+            orientation === 'black' ? 'b' :
+                orientation;
     }
 
     /**
@@ -836,16 +785,15 @@ class ValidationService {
     validateColor(color) {
         if (!this.isValidColor(color)) {
             throw new ValidationError(
-                ERROR_MESSAGES.invalid_color + color, 
-                'color', 
+                ERROR_MESSAGES.invalid_color + color,
+                'color',
                 color
             );
         }
-        
         // Normalize to 'w' or 'b'
-        return color === 'white' ? 'w' : 
-               color === 'black' ? 'b' : 
-               color;
+        return color === 'white' ? 'w' :
+            color === 'black' ? 'b' :
+                color;
     }
 
     /**
@@ -857,8 +805,8 @@ class ValidationService {
     validateSize(size) {
         if (!this.isValidSize(size)) {
             throw new ValidationError(
-                ERROR_MESSAGES.invalid_size + size, 
-                'size', 
+                ERROR_MESSAGES.invalid_size + size,
+                'size',
                 size
             );
         }
@@ -874,36 +822,29 @@ class ValidationService {
     validateConfig(config) {
         if (!config || typeof config !== 'object') {
             throw new ValidationError(
-                'Configuration must be an object', 
-                'config', 
+                'Configuration must be an object',
+                'config',
                 config
             );
         }
-        
         const errors = [];
-        
         // Validate required fields
         if (!config.id && !config.id_div) {
             errors.push('Configuration must include id or id_div');
         }
-        
         // Validate optional fields
         if (config.orientation && !this.isValidOrientation(config.orientation)) {
             errors.push(ERROR_MESSAGES.invalid_orientation + config.orientation);
         }
-        
         if (config.size && !this.isValidSize(config.size)) {
             errors.push(ERROR_MESSAGES.invalid_size + config.size);
         }
-        
         if (config.movableColors && !this.isValidMovableColors(config.movableColors)) {
             errors.push(ERROR_MESSAGES.invalid_color + config.movableColors);
         }
-        
         if (config.dropOffBoard && !this.isValidDropOffBoard(config.dropOffBoard)) {
             errors.push(ERROR_MESSAGES.invalid_dropOffBoard + config.dropOffBoard);
         }
-                
         // Validate callbacks
         const callbacks = ['onMove', 'onMoveEnd', 'onChange', 'onDragStart', 'onDragMove', 'onDrop', 'onSnapbackEnd'];
         for (const callback of callbacks) {
@@ -911,7 +852,6 @@ class ValidationService {
                 errors.push(`Invalid ${callback} callback`);
             }
         }
-        
         // Validate colors
         const colorFields = ['whiteSquare', 'blackSquare', 'highlight', 'hintColor'];
         for (const field of colorFields) {
@@ -919,15 +859,13 @@ class ValidationService {
                 errors.push(`Invalid ${field} color: ${config[field]}`);
             }
         }
-        
         if (errors.length > 0) {
             throw new ValidationError(
-                `Configuration validation failed: ${errors.join(', ')}`, 
-                'config', 
+                `Configuration validation failed: ${errors.join(', ')}`,
+                'config',
                 config
             );
         }
-        
         return config;
     }
 
@@ -943,7 +881,6 @@ class ValidationService {
             const firstKey = this._validationCache.keys().next().value;
             this._validationCache.delete(firstKey);
         }
-        
         this._validationCache.set(key, result);
     }
 
@@ -975,7 +912,6 @@ class ValidationService {
         return validations.map(validation => {
             try {
                 const { type, value } = validation;
-                
                 switch (type) {
                     case 'square':
                         return { valid: this.isValidSquare(value), value };
@@ -1990,180 +1926,155 @@ let Move$1 = class Move {
 };
 
 /**
- * Service for managing animations and transitions
+ * AnimationService - Gestione centralizzata delle animazioni e transizioni per la scacchiera
  * @module services/AnimationService
  * @since 2.0.0
  */
 
 /**
- * Service responsible for coordinating animations and transitions
- * @class
+ * Service responsabile del coordinamento delle animazioni e delle transizioni
+ * @class AnimationService
  */
 class AnimationService {
     /**
-     * Creates a new AnimationService instance
-     * @param {ChessboardConfig} config - Board configuration
+     * Crea una nuova istanza di AnimationService
+     * @param {Object} config - Configurazione della scacchiera
      */
     constructor(config) {
+        /** @type {Object} */
         this.config = config;
+        /** @type {Map<number, {element: HTMLElement, animate: Function, callback?: Function}>} */
         this.activeAnimations = new Map();
+        /** @type {number} */
         this.animationId = 0;
     }
 
     /**
-     * Creates a timing function for animations
-     * @param {string} [type='ease'] - Animation type
-     * @returns {Function} Timing function
+     * Crea una funzione di timing per le animazioni
+     * @param {string} [type='ease'] - Tipo di easing
+     * @returns {Function} Funzione di timing
      */
     createTimingFunction(type = 'ease') {
         return (elapsed, duration) => {
-            const x = elapsed / duration;
-
+            const x = duration > 0 ? Math.max(0, Math.min(1, elapsed / duration)) : 1;
             switch (type) {
-                case 'linear':
-                    return x;
-                case 'ease':
-                    return (x ** 2) * (3 - 2 * x);
-                case 'ease-in':
-                    return x ** 2;
-                case 'ease-out':
-                    return -1 * (x - 1) ** 2 + 1;
-                case 'ease-in-out':
-                    return (x < 0.5) ? 2 * x ** 2 : 4 * x - 2 * x ** 2 - 1;
-                default:
-                    return x;
+                case 'linear': return x;
+                case 'ease': return (x ** 2) * (3 - 2 * x);
+                case 'ease-in': return x ** 2;
+                case 'ease-out': return -1 * (x - 1) ** 2 + 1;
+                case 'ease-in-out': return (x < 0.5) ? 2 * x ** 2 : 4 * x - 2 * x ** 2 - 1;
+                default: return x;
             }
         };
     }
 
     /**
-     * Animates an element with given properties
-     * @param {HTMLElement} element - Element to animate
-     * @param {Object} properties - Properties to animate
-     * @param {number} duration - Animation duration in milliseconds
-     * @param {string} [easing='ease'] - Easing function
-     * @param {Function} [callback] - Callback when animation completes
-     * @returns {number} Animation ID
+     * Anima un elemento HTML con le proprietà specificate
+     * @param {HTMLElement} element - Elemento da animare
+     * @param {Object} properties - Proprietà da animare (es: {left: 100, top: 50, opacity: 1})
+     * @param {number} duration - Durata in ms
+     * @param {string} [easing='ease'] - Tipo di easing
+     * @param {Function} [callback] - Callback al termine
+     * @returns {number} ID dell'animazione
      */
     animate(element, properties, duration, easing = 'ease', callback) {
+        if (!element || typeof properties !== 'object' || typeof duration !== 'number') {
+            throw new Error('AnimationService.animate: parametri non validi');
+        }
         const animationId = ++this.animationId;
         const timingFunction = this.createTimingFunction(easing);
         const startTime = performance.now();
         const startValues = {};
-
-        // Store initial values
         Object.keys(properties).forEach(prop => {
             startValues[prop] = this._getInitialValue(element, prop);
         });
-
         const animate = (currentTime) => {
             const elapsed = currentTime - startTime;
             const progress = Math.min(elapsed / duration, 1);
             const easedProgress = timingFunction(elapsed, duration);
-
-            // Apply animated values
             Object.keys(properties).forEach(prop => {
                 const startValue = startValues[prop];
                 const endValue = properties[prop];
                 const currentValue = this._interpolateValue(startValue, endValue, easedProgress);
                 this._applyValue(element, prop, currentValue);
             });
-
             if (progress < 1 && this.activeAnimations.has(animationId)) {
                 requestAnimationFrame(animate);
             } else {
                 this.activeAnimations.delete(animationId);
-                if (callback) callback();
+                if (typeof callback === 'function') callback();
             }
         };
-
         this.activeAnimations.set(animationId, { element, animate, callback });
         requestAnimationFrame(animate);
-
         return animationId;
     }
 
     /**
-     * Cancels an animation
-     * @param {number} animationId - Animation ID to cancel
+     * Annulla una animazione attiva
+     * @param {number} animationId - ID dell'animazione
      */
     cancel(animationId) {
-        if (this.activeAnimations.has(animationId)) {
-            this.activeAnimations.delete(animationId);
-        }
+        this.activeAnimations.delete(animationId);
     }
 
     /**
-     * Cancels all animations
+     * Annulla tutte le animazioni attive
      */
     cancelAll() {
         this.activeAnimations.clear();
     }
 
     /**
-     * Gets initial value for a property
+     * Ottiene il valore iniziale di una proprietà
      * @private
-     * @param {HTMLElement} element - Element
-     * @param {string} property - Property name
-     * @returns {number} Initial value
+     * @param {HTMLElement} element
+     * @param {string} property
+     * @returns {number}
      */
     _getInitialValue(element, property) {
         if (!element || !element.style) return 0;
         switch (property) {
-            case 'opacity':
-                return parseFloat(getComputedStyle(element).opacity) || 1;
-            case 'left':
-                return parseFloat(element.style.left) || 0;
-            case 'top':
-                return parseFloat(element.style.top) || 0;
-            case 'scale':
-                return 1;
-            default:
-                return 0;
+            case 'opacity': return parseFloat(getComputedStyle(element).opacity) || 1;
+            case 'left': return parseFloat(element.style.left) || 0;
+            case 'top': return parseFloat(element.style.top) || 0;
+            case 'scale': return 1;
+            default: return 0;
         }
     }
 
     /**
-     * Interpolates between two values
+     * Interpola tra due valori
      * @private
-     * @param {number} start - Start value
-     * @param {number} end - End value
-     * @param {number} progress - Progress (0-1)
-     * @returns {number} Interpolated value
+     * @param {number} start
+     * @param {number} end
+     * @param {number} progress
+     * @returns {number}
      */
     _interpolateValue(start, end, progress) {
         return start + (end - start) * progress;
     }
 
     /**
-     * Applies animated value to element
+     * Applica il valore animato all'elemento
      * @private
-     * @param {HTMLElement} element - Element
-     * @param {string} property - Property name
-     * @param {number} value - Value to apply
+     * @param {HTMLElement} element
+     * @param {string} property
+     * @param {number} value
      */
     _applyValue(element, property, value) {
         if (!element || !element.style) return;
         switch (property) {
-            case 'opacity':
-                element.style.opacity = value;
-                break;
-            case 'left':
-                element.style.left = value + 'px';
-                break;
-            case 'top':
-                element.style.top = value + 'px';
-                break;
-            case 'scale':
-                element.style.transform = `scale(${value})`;
-                break;
-            default:
-                element.style[property] = value;
+            case 'opacity': element.style.opacity = value; break;
+            case 'left': element.style.left = value + 'px'; break;
+            case 'top': element.style.top = value + 'px'; break;
+            case 'scale': element.style.transform = `scale(${value})`; break;
+            default: element.style[property] = value;
         }
     }
 
     /**
-     * Cleans up resources
+     * Cleanup risorse e animazioni
      */
     destroy() {
         this.cancelAll();
@@ -2171,7 +2082,7 @@ class AnimationService {
 }
 
 /**
- * Service for managing board setup and DOM operations
+ * BoardService - Handles board DOM setup, manipulation, and resource management
  * @module services/BoardService
  * @since 2.0.0
  */
@@ -2179,45 +2090,45 @@ class AnimationService {
 
 /**
  * Service responsible for board DOM manipulation and setup
- * @class
+ * @class BoardService
  */
 class BoardService {
     /**
-     * Creates a new BoardService instance
-     * @param {ChessboardConfig} config - Board configuration
+     * Create a new BoardService instance
+     * @param {Object} config - Board configuration
      */
     constructor(config) {
+        /** @type {Object} */
         this.config = config;
+        /** @type {HTMLElement|null} */
         this.element = null;
+        /** @type {Object.<string, Square>} */
         this.squares = {};
     }
 
     /**
-     * Builds the board DOM element and attaches it to the configured container
-     * @throws {DOMError} When the container element cannot be found
+     * Build the board DOM element and attach it to the configured container
+     * @throws {DOMError} If the container element cannot be found
      */
     buildBoard() {
-        console.log('BoardService.buildBoard: Looking for element with ID:', this.config.id_div);
-
         this.element = document.getElementById(this.config.id_div);
         if (!this.element) {
             throw new DOMError(ERROR_MESSAGES.invalid_id_div + this.config.id_div, this.config.id_div);
         }
-
         this.resize(this.config.size);
-        this.element.className = "board";
+        this.element.className = 'board';
     }
 
     /**
-     * Creates all 64 squares and adds them to the board
+     * Create all 64 squares and add them to the board
      * @param {Function} coordConverter - Function to convert row/col to real coordinates
      */
     buildSquares(coordConverter) {
+        if (!this.element) throw new DOMError('Board element not initialized', this.config.id_div);
         for (let row = 0; row < BOARD_SIZE.ROWS; row++) {
             for (let col = 0; col < BOARD_SIZE.COLS; col++) {
                 const [squareRow, squareCol] = coordConverter(row, col);
                 const square = new Square(squareRow, squareCol);
-
                 this.squares[square.getId()] = square;
                 this.element.appendChild(square.element);
             }
@@ -2225,20 +2136,17 @@ class BoardService {
     }
 
     /**
-     * Removes all squares from the board and cleans up their resources
-     * Best practice: always destroy JS objects and DOM nodes, and clear references.
+     * Remove all squares from the board and clean up their resources
      */
     removeSquares() {
         for (const square of Object.values(this.squares)) {
-            // Always call destroy to remove DOM and clear piece reference
             square.destroy();
         }
         this.squares = {};
     }
 
     /**
-     * Removes all content from the board element
-     * Best practice: clear DOM and force element to be re-fetched on next build.
+     * Remove all content from the board element
      */
     removeBoard() {
         if (this.element) {
@@ -2248,9 +2156,9 @@ class BoardService {
     }
 
     /**
-     * Resizes the board to the specified size
+     * Resize the board to the specified size
      * @param {number|string} value - Size in pixels or 'auto'
-     * @throws {ValidationError} When size value is invalid
+     * @throws {ValidationError} If size value is invalid
      */
     resize(value) {
         if (value === 'auto') {
@@ -2264,15 +2172,13 @@ class BoardService {
     }
 
     /**
-     * Calculates the optimal size when 'auto' is specified
+     * Calculate the optimal size when 'auto' is specified
      * @private
      * @returns {number} Calculated size in pixels
      */
     _calculateAutoSize() {
-        if (!this.element) return 400; // Default fallback
-
+        if (!this.element) return 400;
         const { offsetWidth, offsetHeight } = this.element;
-
         if (offsetWidth === 0) {
             return offsetHeight || 400;
         } else if (offsetHeight === 0) {
@@ -2283,8 +2189,8 @@ class BoardService {
     }
 
     /**
-     * Gets a square by its ID
-     * @param {string} squareId - Square identifier (API pubblica)
+     * Get a square by its ID
+     * @param {string} squareId - Square identifier
      * @returns {Square|null} The square or null if not found
      */
     getSquare(squareId) {
@@ -2292,26 +2198,37 @@ class BoardService {
     }
 
     /**
-     * Highlight a square (solo oggetto)
+     * Highlight a square
      * @param {Square} square
      * @param {Object} [opts]
      */
     highlightSquare(square, opts = {}) {
-        if (!square) throw new Error('highlightSquare richiede oggetto Square');
-        // ... logica esistente ...
+        if (!square) throw new Error('highlightSquare requires a Square object');
+        // Implement highlight logic or call square.highlight() if available
+        if (typeof square.highlight === 'function') {
+            square.highlight(opts);
+        } else {
+            square.element.classList.add('highlighted');
+        }
     }
+
     /**
-     * Dehighlight a square (solo oggetto)
+     * Remove highlight from a square
      * @param {Square} square
      * @param {Object} [opts]
      */
     dehighlightSquare(square, opts = {}) {
-        if (!square) throw new Error('dehighlightSquare richiede oggetto Square');
-        // ... logica esistente ...
+        if (!square) throw new Error('dehighlightSquare requires a Square object');
+        // Implement dehighlight logic or call square.dehighlight() if available
+        if (typeof square.dehighlight === 'function') {
+            square.dehighlight(opts);
+        } else {
+            square.element.classList.remove('highlighted');
+        }
     }
 
     /**
-     * Gets all squares
+     * Get all squares
      * @returns {Object.<string, Square>} All squares indexed by ID
      */
     getAllSquares() {
@@ -2319,7 +2236,7 @@ class BoardService {
     }
 
     /**
-     * Applies a method to all squares
+     * Apply a method to all squares
      * @param {string} methodName - Name of the method to call on each square
      * @param {...*} args - Arguments to pass to the method
      */
@@ -2332,7 +2249,7 @@ class BoardService {
     }
 
     /**
-     * Cleans up all resources
+     * Clean up all resources
      */
     destroy() {
         this.removeSquares();
@@ -2343,7 +2260,7 @@ class BoardService {
 }
 
 /**
- * Service for managing coordinate conversions and board orientation
+ * CoordinateService - Handles coordinate conversions and board orientation logic
  * @module services/CoordinateService
  * @since 2.0.0
  */
@@ -2351,19 +2268,20 @@ class BoardService {
 
 /**
  * Service responsible for coordinate conversions and board orientation
- * @class
+ * @class CoordinateService
  */
 class CoordinateService {
     /**
-     * Creates a new CoordinateService instance
-     * @param {ChessboardConfig} config - Board configuration
+     * Create a new CoordinateService instance
+     * @param {Object} config - Board configuration
      */
     constructor(config) {
+        /** @type {Object} */
         this.config = config;
     }
 
     /**
-     * Converts logical coordinates to real coordinates based on board orientation
+     * Convert logical coordinates to real coordinates based on board orientation
      * @param {number} row - Row index (0-7)
      * @param {number} col - Column index (0-7)
      * @returns {Array<number>} Real coordinates [row, col] (1-8)
@@ -2371,18 +2289,16 @@ class CoordinateService {
     realCoord(row, col) {
         let realRow = row;
         let realCol = col;
-        
         if (this.isWhiteOriented()) {
             realRow = 7 - row;
         } else {
             realCol = 7 - col;
         }
-        
         return [realRow + 1, realCol + 1];
     }
 
     /**
-     * Converts board coordinates to square ID
+     * Convert board coordinates to square ID
      * @param {number} row - Row index (0-7)
      * @param {number} col - Column index (0-7)
      * @returns {string} Square ID (e.g., 'e4')
@@ -2390,7 +2306,6 @@ class CoordinateService {
     getSquareID(row, col) {
         row = parseInt(row);
         col = parseInt(col);
-        
         if (this.isWhiteOriented()) {
             row = 8 - row;
             col = col + 1;
@@ -2398,7 +2313,6 @@ class CoordinateService {
             row = row + 1;
             col = 8 - col;
         }
-        
         if (col < 1 || col > 8 || row < 1 || row > 8) {
             throw new ValidationError(
                 `Invalid board coordinates: row=${row}, col=${col}`,
@@ -2406,13 +2320,12 @@ class CoordinateService {
                 { row, col }
             );
         }
-        
         const letter = BOARD_LETTERS[col - 1];
         return letter + row;
     }
 
     /**
-     * Converts square ID to board coordinates
+     * Convert square ID to board coordinates
      * @param {string} squareId - Square ID (e.g., 'e4')
      * @returns {Array<number>} Board coordinates [row, col] (0-7)
      */
@@ -2424,10 +2337,8 @@ class CoordinateService {
                 squareId
             );
         }
-        
         const letter = squareId[0];
         const number = parseInt(squareId[1]);
-        
         const col = BOARD_LETTERS.indexOf(letter);
         if (col === -1) {
             throw new ValidationError(
@@ -2436,7 +2347,6 @@ class CoordinateService {
                 squareId
             );
         }
-        
         if (number < 1 || number > 8) {
             throw new ValidationError(
                 ERROR_MESSAGES.invalid_square + squareId,
@@ -2444,9 +2354,7 @@ class CoordinateService {
                 squareId
             );
         }
-        
         let row, boardCol;
-        
         if (this.isWhiteOriented()) {
             row = 8 - number;
             boardCol = col;
@@ -2454,12 +2362,11 @@ class CoordinateService {
             row = number - 1;
             boardCol = 7 - col;
         }
-        
         return [row, boardCol];
     }
 
     /**
-     * Converts pixel coordinates to square ID
+     * Convert pixel coordinates to square ID
      * @param {number} x - X coordinate in pixels
      * @param {number} y - Y coordinate in pixels
      * @param {HTMLElement} boardElement - Board DOM element
@@ -2467,21 +2374,15 @@ class CoordinateService {
      */
     pixelToSquareID(x, y, boardElement) {
         if (!boardElement) return null;
-        
         const rect = boardElement.getBoundingClientRect();
         const { width, height } = rect;
-        
-        // Check if coordinates are within board bounds
         if (x < 0 || x >= width || y < 0 || y >= height) {
             return null;
         }
-        
         const squareWidth = width / 8;
         const squareHeight = height / 8;
-        
         const col = Math.floor(x / squareWidth);
         const row = Math.floor(y / squareHeight);
-        
         try {
             return this.getSquareID(row, col);
         } catch (error) {
@@ -2490,25 +2391,21 @@ class CoordinateService {
     }
 
     /**
-     * Converts square ID to pixel coordinates
+     * Convert square ID to pixel coordinates
      * @param {string} squareId - Square ID (e.g., 'e4')
      * @param {HTMLElement} boardElement - Board DOM element
      * @returns {Object|null} Pixel coordinates {x, y} or null if invalid
      */
     squareIDToPixel(squareId, boardElement) {
         if (!boardElement) return null;
-        
         try {
             const [row, col] = this.getCoordinatesFromSquareID(squareId);
             const rect = boardElement.getBoundingClientRect();
             const { width, height } = rect;
-            
             const squareWidth = width / 8;
             const squareHeight = height / 8;
-            
             const x = col * squareWidth;
             const y = row * squareHeight;
-            
             return { x, y };
         } catch (error) {
             return null;
@@ -2516,7 +2413,7 @@ class CoordinateService {
     }
 
     /**
-     * Gets the center pixel coordinates of a square
+     * Get the center pixel coordinates of a square
      * @param {string} squareId - Square ID (e.g., 'e4')
      * @param {HTMLElement} boardElement - Board DOM element
      * @returns {Object|null} Center coordinates {x, y} or null if invalid
@@ -2524,11 +2421,9 @@ class CoordinateService {
     getSquareCenter(squareId, boardElement) {
         const coords = this.squareIDToPixel(squareId, boardElement);
         if (!coords) return null;
-        
         const rect = boardElement.getBoundingClientRect();
         const squareWidth = rect.width / 8;
         const squareHeight = rect.height / 8;
-        
         return {
             x: coords.x + squareWidth / 2,
             y: coords.y + squareHeight / 2
@@ -2536,7 +2431,7 @@ class CoordinateService {
     }
 
     /**
-     * Calculates the distance between two squares
+     * Calculate the distance between two squares
      * @param {string} fromSquare - Source square ID
      * @param {string} toSquare - Target square ID
      * @returns {number} Distance between squares
@@ -2545,10 +2440,8 @@ class CoordinateService {
         try {
             const [fromRow, fromCol] = this.getCoordinatesFromSquareID(fromSquare);
             const [toRow, toCol] = this.getCoordinatesFromSquareID(toSquare);
-            
             const rowDiff = Math.abs(toRow - fromRow);
             const colDiff = Math.abs(toCol - fromCol);
-            
             return Math.sqrt(rowDiff * rowDiff + colDiff * colDiff);
         } catch (error) {
             return 0;
@@ -2556,7 +2449,7 @@ class CoordinateService {
     }
 
     /**
-     * Checks if the board is oriented from white's perspective
+     * Check if the board is oriented from white's perspective
      * @returns {boolean} True if white-oriented
      */
     isWhiteOriented() {
@@ -2564,7 +2457,7 @@ class CoordinateService {
     }
 
     /**
-     * Checks if the board is oriented from black's perspective
+     * Check if the board is oriented from black's perspective
      * @returns {boolean} True if black-oriented
      */
     isBlackOriented() {
@@ -2572,31 +2465,31 @@ class CoordinateService {
     }
 
     /**
-     * Flips the board orientation
+     * Flip the board orientation
      */
     flipOrientation() {
         this.config.orientation = this.isWhiteOriented() ? 'b' : 'w';
     }
 
     /**
-     * Sets the board orientation
-     * @param {string} orientation - 'w' for white, 'b' for black
-     * @throws {ValidationError} When orientation is invalid
+     * Set the board orientation
+     * @param {string} orientation - 'w', 'b', 'white', or 'black'
+     * @throws {ValidationError} If orientation is invalid
      */
     setOrientation(orientation) {
-        if (orientation !== 'w' && orientation !== 'b') {
+        const normalized = orientation === 'white' ? 'w' : orientation === 'black' ? 'b' : orientation;
+        if (normalized !== 'w' && normalized !== 'b') {
             throw new ValidationError(
                 ERROR_MESSAGES.invalid_orientation + orientation,
                 'orientation',
                 orientation
             );
         }
-        
-        this.config.orientation = orientation;
+        this.config.orientation = normalized;
     }
 
     /**
-     * Gets the current orientation
+     * Get the current orientation
      * @returns {string} Current orientation ('w' or 'b')
      */
     getOrientation() {
@@ -2604,50 +2497,21 @@ class CoordinateService {
     }
 
     /**
-     * Sets the orientation
-     * @param {string} orientation - New orientation ('w', 'b', 'white', 'black')
-     */
-    setOrientation(orientation) {
-        // Normalize orientation
-        const normalizedOrientation = orientation === 'white' ? 'w' : 
-                                     orientation === 'black' ? 'b' : orientation;
-        
-        if (normalizedOrientation !== 'w' && normalizedOrientation !== 'b') {
-            throw new ValidationError(
-                ERROR_MESSAGES.invalid_orientation + orientation,
-                'orientation',
-                orientation
-            );
-        }
-        
-        this.config.orientation = normalizedOrientation;
-    }
-
-    /**
-     * Flips the board orientation
-     */
-    flipOrientation() {
-        this.config.orientation = this.isWhiteOriented() ? 'b' : 'w';
-    }
-
-    /**
-     * Gets all square IDs in order
+     * Get all square IDs in order
      * @returns {Array<string>} Array of all square IDs
      */
     getAllSquareIDs() {
         const squares = [];
-        
         for (let row = 0; row < 8; row++) {
             for (let col = 0; col < 8; col++) {
                 squares.push(this.getSquareID(row, col));
             }
         }
-        
         return squares;
     }
 
     /**
-     * Gets squares in a specific rank (row)
+     * Get all squares in a specific rank (row)
      * @param {number} rank - Rank number (1-8)
      * @returns {Array<string>} Array of square IDs in the rank
      */
@@ -2659,19 +2523,16 @@ class CoordinateService {
                 rank
             );
         }
-        
         const squares = [];
-        
         for (let col = 0; col < 8; col++) {
             const row = this.isWhiteOriented() ? 8 - rank : rank - 1;
             squares.push(this.getSquareID(row, col));
         }
-        
         return squares;
     }
 
     /**
-     * Gets squares in a specific file (column)
+     * Get all squares in a specific file (column)
      * @param {string} file - File letter (a-h)
      * @returns {Array<string>} Array of square IDs in the file
      */
@@ -2684,13 +2545,10 @@ class CoordinateService {
                 file
             );
         }
-        
         const squares = [];
-        
         for (let row = 0; row < 8; row++) {
             squares.push(this.getSquareID(row, col));
         }
-        
         return squares;
     }
 }
@@ -3070,6 +2928,67 @@ const DragOptimizations = {
     }
 };
 
+/**
+ * ListenerManager - Utility per la gestione centralizzata dei listener DOM
+ * Permette di aggiungere, rimuovere e pulire tutti i listener in modo sicuro e senza duplicazioni.
+ * @module utils/listenerManager
+ * @since 2.0.0
+ */
+
+class ListenerManager {
+    constructor() {
+        /**
+         * Lista di tutti i listener registrati
+         * @type {Array<{element: EventTarget, type: string, handler: Function, options?: any}>}
+         */
+        this.listeners = [];
+    }
+
+    /**
+     * Aggiunge un listener e lo traccia per la rimozione automatica
+     * @param {EventTarget} element - Elemento su cui aggiungere il listener
+     * @param {string} type - Tipo di evento
+     * @param {Function} handler - Funzione handler
+     * @param {Object|boolean} [options] - Opzioni per addEventListener
+     */
+    add(element, type, handler, options) {
+        if (!element || !type || !handler) return;
+        element.addEventListener(type, handler, options);
+        this.listeners.push({ element, type, handler, options });
+    }
+
+    /**
+     * Rimuove un listener specifico
+     * @param {EventTarget} element
+     * @param {string} type
+     * @param {Function} handler
+     */
+    remove(element, type, handler) {
+        if (!element || !type || !handler) return;
+        element.removeEventListener(type, handler);
+        this.listeners = this.listeners.filter(
+            l => !(l.element === element && l.type === type && l.handler === handler)
+        );
+    }
+
+    /**
+     * Rimuove tutti i listener registrati
+     */
+    removeAll() {
+        for (const { element, type, handler, options } of this.listeners) {
+            element.removeEventListener(type, handler, options);
+        }
+        this.listeners = [];
+    }
+
+    /**
+     * Pulizia risorse
+     */
+    destroy() {
+        this.removeAll();
+    }
+}
+
 /**
  * Service for managing events and user interactions
  * @module services/EventService
@@ -3102,8 +3021,8 @@ class EventService {
         this.promoting = false;
         this.isAnimating = false;
 
-        // Event listeners storage for cleanup
-        this.eventListeners = new Map();
+        // Listener manager per gestione centralizzata
+        this.listenerManager = new ListenerManager();
     }
 
     /**
@@ -3113,8 +3032,8 @@ class EventService {
      * @param {Function} onPieceLeave - Callback for piece leave
      */
     addListeners(onSquareClick, onPieceHover, onPieceLeave) {
-        // Remove existing listeners to avoid duplicates
-        this.removeListeners();
+        // Rimuovi tutti i listener esistenti
+        this.listenerManager.removeAll();
 
         const squares = this.boardService.getAllSquares();
 
@@ -3132,8 +3051,6 @@ class EventService {
      * @param {Function} onPieceLeave - Leave callback
      */
     _addSquareListeners(square, onSquareClick, onPieceHover, onPieceLeave) {
-        const listeners = [];
-
         // Throttled hover handlers for performance
         const throttledHover = rafThrottle((e) => {
             if (!this.clicked && this.config.hints) {
@@ -3203,26 +3120,13 @@ class EventService {
             }
         };
 
-        // Add listeners
-        square.element.addEventListener('mouseover', throttledHover);
-        square.element.addEventListener('mouseout', throttledLeave);
-        square.element.addEventListener('click', handleClick);
-        // Touch: separa tap e drag
-        square.element.addEventListener('touchstart', handleTouchStart);
-        square.element.addEventListener('touchmove', handleTouchMove);
-        square.element.addEventListener('touchend', handleTouchEnd);
-
-        // Store listeners for cleanup
-        listeners.push(
-            { element: square.element, type: 'mouseover', handler: throttledHover },
-            { element: square.element, type: 'mouseout', handler: throttledLeave },
-            { element: square.element, type: 'click', handler: handleClick },
-            { element: square.element, type: 'touchstart', handler: handleTouchStart },
-            { element: square.element, type: 'touchmove', handler: handleTouchMove },
-            { element: square.element, type: 'touchend', handler: handleTouchEnd }
-        );
-
-        this.eventListeners.set(square.id, listeners);
+        // Usa ListenerManager per aggiungere tutti i listener
+        this.listenerManager.add(square.element, 'mouseover', throttledHover);
+        this.listenerManager.add(square.element, 'mouseout', throttledLeave);
+        this.listenerManager.add(square.element, 'click', handleClick);
+        this.listenerManager.add(square.element, 'touchstart', handleTouchStart);
+        this.listenerManager.add(square.element, 'touchmove', handleTouchMove);
+        this.listenerManager.add(square.element, 'touchend', handleTouchEnd);
     }
 
     /**
@@ -3239,18 +3143,14 @@ class EventService {
      */
     createDragFunction(square, piece, onDragStart, onDragMove, onDrop, onSnapback, onMove, onRemove) {
         return (event) => {
-            event.preventDefault();
-
             if (!this.config.draggable || !piece || this.isAnimating) {
                 return;
             }
 
             const originalFrom = square;
-            let isDragging = false;
             let from = originalFrom;
             let to = square;
             let previousHighlight = null;
-
             const img = piece.element;
 
             if (!this.moveService.canMove(from)) {
@@ -3261,6 +3161,15 @@ class EventService {
             const isTouch = event.type && event.type.startsWith('touch');
             const startX = event.clientX || (event.touches && event.touches[0]?.clientX) || 0;
             const startY = event.clientY || (event.touches && event.touches[0]?.clientY) || 0;
+            let dragStarted = false;
+
+            // --- Calculate offset between cursor/finger and piece top-left at drag start ---
+            const pieceRect = img.getBoundingClientRect();
+            const boardElement = this.boardService.element;
+            const boardRect = boardElement.getBoundingClientRect();
+            // Offset from cursor/finger to top-left of piece
+            const offsetX = startX - pieceRect.left;
+            const offsetY = startY - pieceRect.top;
 
             // --- Touch scroll lock helper ---
             const addScrollLock = () => {
@@ -3272,10 +3181,6 @@ class EventService {
 
             // --- MOVE HANDLER (mouse + touch unified) ---
             const moveAt = (event) => {
-                const boardElement = this.boardService.element;
-                const squareSize = boardElement.offsetWidth / 8;
-
-                // Get mouse/touch coordinates
                 let clientX, clientY;
                 if (event.touches && event.touches[0]) {
                     clientX = event.touches[0].clientX;
@@ -3284,77 +3189,54 @@ class EventService {
                     clientX = event.clientX;
                     clientY = event.clientY;
                 }
-
-                // Calculate position relative to board
-                const boardRect = boardElement.getBoundingClientRect();
-                const x = clientX - boardRect.left - (squareSize / 2);
-                const y = clientY - boardRect.top - (squareSize / 2);
-
+                // Position the piece so the cursor/finger stays at the same relative point
+                const x = clientX - boardRect.left - offsetX;
+                const y = clientY - boardRect.top - offsetY;
                 img.style.left = x + 'px';
                 img.style.top = y + 'px';
-
                 return true;
             };
 
             // --- DRAG MOVE (mouse + touch) ---
+            const moveThreshold = 5; // px
             const onPointerMove = (event) => {
-                // For touch, only handle the first finger
                 if (event.touches && event.touches.length > 1) return;
                 if (event.touches && !event.touches[0]) return;
-                if (event.type && event.type.startsWith('touch')) event.preventDefault();
-
                 const currentX = event.clientX || (event.touches && event.touches[0]?.clientX) || 0;
                 const currentY = event.clientY || (event.touches && event.touches[0]?.clientY) || 0;
                 const deltaX = Math.abs(currentX - startX);
                 const deltaY = Math.abs(currentY - startY);
-
-                // Start dragging if mouse/touch moved enough
-                if (!isDragging && (deltaX > 3 || deltaY > 3)) {
-                    isDragging = true;
-                    // Inizio drag: blocca update board
+                if (!dragStarted && (deltaX > moveThreshold || deltaY > moveThreshold)) {
+                    dragStarted = true;
+                    if (isTouch) addScrollLock();
                     if (this.chessboard) this.chessboard._isDragging = true;
-
-                    // Mostra hint all'inizio del drag se attivi
                     if (this.config.hints && typeof this.chessboard._boundOnPieceHover === 'function') {
                         this.chessboard._boundOnPieceHover(from);
                     }
-
-                    // Set up drag state
                     if (!this.config.clickable) {
                         this.clicked = null;
                         this.clicked = from;
                     } else if (!this.clicked) {
                         this.clicked = from;
                     }
-
-                    // Visual feedback
                     if (this.config.clickable) {
                         from.select();
                     }
-
-                    // Prepare piece for dragging
                     img.style.position = 'absolute';
                     img.style.zIndex = '100';
                     img.classList.add('dragging');
-
                     DragOptimizations.enableForDrag(img);
-
-                    // Lock scroll for touch
-                    if (isTouch) addScrollLock();
-
-                    // Call drag start callback
                     if (!onDragStart(square, piece)) {
                         return;
                     }
                 }
-
-                if (!isDragging) return;
-
+                // Only block scroll and call preventDefault after drag has started
+                if (dragStarted && isTouch && event.cancelable) {
+                    event.preventDefault();
+                }
+                if (!dragStarted) return;
                 if (!moveAt(event)) ;
-
                 // Update target square
-                const boardElement = this.boardService.element;
-                const boardRect = boardElement.getBoundingClientRect();
                 let clientX, clientY;
                 if (event.touches && event.touches[0]) {
                     clientX = event.touches[0].clientX;
@@ -3365,22 +3247,16 @@ class EventService {
                 }
                 const x = clientX - boardRect.left;
                 const y = clientY - boardRect.top;
-
                 let newTo = null;
                 if (x >= 0 && x <= boardRect.width && y >= 0 && y <= boardRect.height) {
                     const squareId = this.coordinateService.pixelToSquareID(x, y, boardElement);
                     newTo = squareId ? this.boardService.getSquare(squareId) : null;
                 }
-
                 to = newTo;
                 onDragMove(from, to, piece);
-
-                // Update visual feedback
-                if (to !== previousHighlight) {
-                    to?.highlight();
-                    previousHighlight?.dehighlight();
-                    previousHighlight = to;
-                }
+                if (to) to.highlight();
+                if (previousHighlight && previousHighlight !== to) previousHighlight.dehighlight();
+                previousHighlight = to;
             };
 
             // --- DRAG END (mouse + touch) ---
@@ -3391,26 +3267,19 @@ class EventService {
                 document.removeEventListener('touchmove', onPointerMove);
                 window.removeEventListener('touchend', onPointerUp);
                 if (isTouch) removeScrollLock();
-                // Fine drag: sblocca update board
                 if (this.chessboard) this.chessboard._isDragging = false;
-
-                // Rimuovi hint alla fine del drag se attivi
                 if (this.config.hints && typeof this.chessboard._boundOnPieceLeave === 'function') {
                     this.chessboard._boundOnPieceLeave(from);
                 }
-
-                if (!isDragging) {
+                if (!dragStarted) {
                     return;
                 }
-
                 img.style.zIndex = '20';
                 img.classList.remove('dragging');
                 img.style.willChange = 'auto';
-
                 // Handle drop
                 const dropResult = onDrop(originalFrom, to, piece);
                 const isTrashDrop = !to && (this.config.dropOffBoard === 'trash' || dropResult === 'trash');
-
                 if (isTrashDrop) {
                     this._handleTrashDrop(originalFrom, onRemove);
                 } else if (!to) {
@@ -3424,16 +3293,12 @@ class EventService {
                 }
             };
 
-            // --- Attach listeners (mouse + touch) ---
+            // Attach listeners (mouse + touch)
             window.addEventListener('mouseup', onPointerUp, { once: true });
             document.addEventListener('mousemove', onPointerMove);
             img.addEventListener('mouseup', onPointerUp, { once: true });
-            // Touch events
             window.addEventListener('touchend', onPointerUp, { once: true });
             document.addEventListener('touchmove', onPointerMove, { passive: false });
-
-            // Per robustezza: se il drag parte da touch, blocca subito lo scroll
-            if (isTouch) addScrollLock();
         };
     }
 
@@ -3926,33 +3791,21 @@ class EventService {
      * Removes all existing event listeners
      */
     removeListeners() {
-        this.eventListeners.forEach((listeners, squareId) => {
-            listeners.forEach(({ element, type, handler }) => {
-                element.removeEventListener(type, handler);
-            });
-        });
-
-        this.eventListeners.clear();
+        this.listenerManager.removeAll();
     }
 
     /**
      * Removes all event listeners
      */
     removeAllListeners() {
-        this.eventListeners.forEach((listeners, squareId) => {
-            listeners.forEach(({ element, type, handler }) => {
-                element.removeEventListener(type, handler);
-            });
-        });
-
-        this.eventListeners.clear();
+        this.listenerManager.removeAll();
     }
 
     /**
      * Cleans up resources
      */
     destroy() {
-        this.removeAllListeners();
+        this.listenerManager.destroy();
         this.clicked = null;
         this.promoting = false;
         this.isAnimating = false;
@@ -3960,7 +3813,7 @@ class EventService {
 }
 
 /**
- * Service for managing chess moves and move validation
+ * MoveService - Handles chess move management and validation
  * @module services/MoveService
  * @since 2.0.0
  */
@@ -3968,13 +3821,13 @@ class EventService {
 
 /**
  * Service responsible for move management and validation
- * @class
+ * @class MoveService
  */
 class MoveService {
     /**
-     * Creates a new MoveService instance
-     * @param {ChessboardConfig} config - Board configuration
-     * @param {PositionService} positionService - Position service instance
+     * Create a new MoveService instance
+     * @param {Object} config - Board configuration
+     * @param {Object} positionService - Position service instance
      */
     constructor(config, positionService) {
         this.config = config;
@@ -3984,43 +3837,32 @@ class MoveService {
     }
 
     /**
-     * Checks if a piece on a square can move
+     * Check if a piece on a square can move
      * @param {Square} square - Square to check
      * @returns {boolean} True if piece can move
      */
     canMove(square) {
         if (!square.piece) return false;
-
         const { movableColors, onlyLegalMoves } = this.config;
-
         if (movableColors === 'none') return false;
         if (movableColors === 'w' && square.piece.color === 'b') return false;
         if (movableColors === 'b' && square.piece.color === 'w') return false;
-
         if (!onlyLegalMoves) return true;
-
-        // Check if position service and game are available
-        if (!this.positionService || !this.positionService.getGame()) {
-            return false;
-        }
-
+        if (!this.positionService || !this.positionService.getGame()) return false;
         const game = this.positionService.getGame();
         return square.piece.color === game.turn();
     }
 
     /**
-     * Converts various move formats to a Move instance
+     * Convert various move formats to a Move instance
      * @param {string|Move|Object} move - Move in various formats
      * @param {Object} squares - All board squares
      * @returns {Move} Move instance
      * @throws {MoveError} When move format is invalid
      */
     convertMove(move, squares) {
-        if (move instanceof Move$1) {
-            return move;
-        }
+        if (move instanceof Move$1) return move;
         if (typeof move === 'object' && move.from && move.to) {
-            // Se sono id, converto in oggetti; se sono già oggetti, li uso direttamente
             const fromSquare = typeof move.from === 'string' ? squares[move.from] : move.from;
             const toSquare = typeof move.to === 'string' ? squares[move.to] : move.to;
             if (!fromSquare || !toSquare) throw new MoveError(ERROR_MESSAGES.invalid_move_format, move.from, move.to);
@@ -4039,13 +3881,12 @@ class MoveService {
     }
 
     /**
-     * Checks if a move is legal
+     * Check if a move is legal
      * @param {Move} move - Move to check
      * @returns {boolean} True if move is legal
      */
     isLegalMove(move) {
         const legalMoves = this.getLegalMoves(move.from.id);
-
         return legalMoves.some(legalMove =>
             legalMove.to === move.to.id &&
             move.promotion === legalMove.promotion
@@ -4053,180 +3894,100 @@ class MoveService {
     }
 
     /**
-     * Gets all legal moves for a square or the entire position
+     * Get all legal moves for a square or the entire position
      * @param {string} [from] - Square to get moves from (optional)
      * @param {boolean} [verbose=true] - Whether to return verbose move objects
      * @returns {Array} Array of legal moves
      */
     getLegalMoves(from = null, verbose = true) {
-        // Check if position service and game are available
-        if (!this.positionService || !this.positionService.getGame()) {
-            return [];
-        }
-
+        if (!this.positionService || !this.positionService.getGame()) return [];
         const game = this.positionService.getGame();
-
         if (!game) return [];
-
         const options = { verbose };
-        if (from) {
-            options.square = from;
-        }
-
+        if (from) options.square = from;
         return game.moves(options);
     }
 
     /**
-     * Gets legal moves with caching for performance
+     * Get legal moves with caching for performance
      * @param {Square} square - Square to get moves from
      * @returns {Array} Array of legal moves
      */
     getCachedLegalMoves(square) {
-        // Check if position service and game are available
-        if (!this.positionService || !this.positionService.getGame()) {
-            return [];
-        }
-
+        if (!this.positionService || !this.positionService.getGame()) return [];
         const game = this.positionService.getGame();
         if (!game) return [];
-
         const cacheKey = `${square.id}-${game.fen()}`;
         let moves = this._movesCache.get(cacheKey);
-
         if (!moves) {
             moves = game.moves({ square: square.id, verbose: true });
             this._movesCache.set(cacheKey, moves);
-
-            // Clear cache after a short delay to prevent memory buildup
-            if (this._cacheTimeout) {
-                clearTimeout(this._cacheTimeout);
-            }
-
+            if (this._cacheTimeout) clearTimeout(this._cacheTimeout);
             this._cacheTimeout = setTimeout(() => {
                 this._movesCache.clear();
             }, 1000);
         }
-
         return moves;
     }
 
     /**
-     * Executes a move on the game
-     * @param {Move} move - Move to execute (deve essere oggetto Move)
+     * Execute a move on the game
+     * @param {Move} move - Move to execute (must be a Move object)
      * @returns {Object|null} Move result from chess.js or null if invalid
      */
     executeMove(move) {
-        if (!(move instanceof Move$1)) throw new Error('executeMove richiede un oggetto Move');
-        if (!this.positionService || !this.positionService.getGame()) {
-            return null;
-        }
+        if (!(move instanceof Move$1)) throw new Error('executeMove requires a Move object');
+        if (!this.positionService || !this.positionService.getGame()) return null;
         const game = this.positionService.getGame();
         if (!game) return null;
-        const moveOptions = {
-            from: move.from.id,
-            to: move.to.id
-        };
-        if (move.hasPromotion()) {
-            moveOptions.promotion = move.promotion;
-        }
+        const moveOptions = { from: move.from.id, to: move.to.id };
+        if (move.hasPromotion()) moveOptions.promotion = move.promotion;
         const result = game.move(moveOptions);
         return result;
     }
 
     /**
-     * Determina se una mossa richiede promozione
-     * @param {Move} move - Deve essere oggetto Move
+     * Determine if a move requires promotion
+     * @param {Move} move - Must be a Move object
      * @returns {boolean}
      */
     requiresPromotion(move) {
-        if (!(move instanceof Move$1)) throw new Error('requiresPromotion richiede un oggetto Move');
-        console.log('Checking if move requires promotion:', move.from.id, '->', move.to.id);
-
-        if (!this.config.onlyLegalMoves) {
-            console.log('Not in legal moves mode, no promotion required');
-            return false;
-        }
-
+        if (!(move instanceof Move$1)) throw new Error('requiresPromotion requires a Move object');
+        if (!this.config.onlyLegalMoves) return false;
         const game = this.positionService.getGame();
-        if (!game) {
-            console.log('No game instance available');
-            return false;
-        }
-
+        if (!game) return false;
         const piece = game.get(move.from.id);
-        if (!piece || piece.type !== 'p') {
-            console.log('Not a pawn move, no promotion required');
-            return false;
-        }
-
+        if (!piece || piece.type !== 'p') return false;
         const targetRank = move.to.row;
-        if (targetRank !== 1 && targetRank !== 8) {
-            console.log('Not reaching promotion rank, no promotion required');
-            return false;
-        }
-
-        console.log('Pawn reaching promotion rank, validating move...');
-
-        // Additional validation: check if the pawn can actually reach this square
-        if (!this._isPawnMoveValid(move.from, move.to, piece.color)) {
-            console.log('Pawn move not valid, no promotion required');
-            return false;
-        }
-
-        // First check if the move is legal without promotion
-        const simpleMoveObj = {
-            from: move.from.id,
-            to: move.to.id
-        };
-
+        if (targetRank !== 1 && targetRank !== 8) return false;
+        if (!this._isPawnMoveValid(move.from, move.to, piece.color)) return false;
+        // Try move without promotion
+        const simpleMoveObj = { from: move.from.id, to: move.to.id };
         try {
-            console.log('Testing move without promotion:', simpleMoveObj);
-            // Test if the move is legal without promotion first
             const testMove = game.move(simpleMoveObj);
             if (testMove) {
-                // Move was successful, but check if it was a promotion
                 const wasPromotion = testMove.promotion;
-
-                // Undo the test move
                 game.undo();
-
-                console.log('Move successful without promotion, was promotion:', wasPromotion !== undefined);
-
-                // If it was a promotion, return true
                 return wasPromotion !== undefined;
             }
         } catch (error) {
-            console.log('Move failed without promotion, trying with promotion:', error.message);
-
-            // If simple move fails, try with promotion
-            const promotionMoveObj = {
-                from: move.from.id,
-                to: move.to.id,
-                promotion: 'q' // test with queen
-            };
-
+            // Try with promotion
+            const promotionMoveObj = { from: move.from.id, to: move.to.id, promotion: 'q' };
             try {
-                console.log('Testing move with promotion:', promotionMoveObj);
                 const testMove = game.move(promotionMoveObj);
                 if (testMove) {
-                    // Undo the test move
                     game.undo();
-                    console.log('Move successful with promotion, promotion required');
                     return true;
                 }
             } catch (promotionError) {
-                console.log('Move failed even with promotion:', promotionError.message);
-                // Move is not legal even with promotion
                 return false;
             }
         }
-
-        console.log('Move validation complete, no promotion required');
         return false;
     }
 
     /**
-     * Validates if a pawn move is theoretically possible
+     * Validate if a pawn move is theoretically possible
      * @private
      * @param {Square} from - Source square
      * @param {Square} to - Target square
@@ -4238,48 +3999,21 @@ class MoveService {
         const toRank = to.row;
         const fromFile = from.col;
         const toFile = to.col;
-
-        console.log(`Validating pawn move: ${from.id} -> ${to.id} (${color})`);
-        console.log(`Ranks: ${fromRank} -> ${toRank}, Files: ${fromFile} -> ${toFile}`);
-
-        // Direction of pawn movement
         const direction = color === 'w' ? 1 : -1;
         const rankDiff = toRank - fromRank;
         const fileDiff = Math.abs(toFile - fromFile);
-
-        // Pawn can only move forward
-        if (rankDiff * direction <= 0) {
-            console.log('Invalid: Pawn cannot move backward or stay in place');
-            return false;
-        }
-
-        // Pawn can only move 1 rank at a time (except for double move from starting position)
-        if (Math.abs(rankDiff) > 2) {
-            console.log('Invalid: Pawn cannot move more than 2 ranks');
-            return false;
-        }
-
-        // If moving 2 ranks, must be from starting position
+        if (rankDiff * direction <= 0) return false;
+        if (Math.abs(rankDiff) > 2) return false;
         if (Math.abs(rankDiff) === 2) {
             const startingRank = color === 'w' ? 2 : 7;
-            if (fromRank !== startingRank) {
-                console.log(`Invalid: Pawn cannot move 2 ranks from rank ${fromRank}`);
-                return false;
-            }
+            if (fromRank !== startingRank) return false;
         }
-
-        // Pawn can only move to adjacent files (diagonal capture) or same file (forward move)
-        if (fileDiff > 1) {
-            console.log('Invalid: Pawn cannot move more than 1 file');
-            return false;
-        }
-
-        console.log('Pawn move validation passed');
+        if (fileDiff > 1) return false;
         return true;
     }
 
     /**
-     * Handles promotion UI setup
+     * Handle promotion UI setup
      * @param {Move} move - Move requiring promotion
      * @param {Object} squares - All board squares
      * @param {Function} onPromotionSelect - Callback when promotion piece is selected
@@ -4288,55 +4022,33 @@ class MoveService {
      */
     setupPromotion(move, squares, onPromotionSelect, onPromotionCancel) {
         if (!this.requiresPromotion(move)) return false;
-
-        // Check if position service and game are available
-        if (!this.positionService || !this.positionService.getGame()) {
-            return false;
-        }
-
+        if (!this.positionService || !this.positionService.getGame()) return false;
         const game = this.positionService.getGame();
         const piece = game.get(move.from.id);
         const targetSquare = move.to;
-
-        // Clear any existing promotion UI
         Object.values(squares).forEach(square => {
             square.removePromotion();
             square.removeCover();
         });
-
-        // Always show promotion choices in a column
         this._showPromotionInColumn(targetSquare, piece, squares, onPromotionSelect, onPromotionCancel);
-
         return true;
     }
 
     /**
-     * Shows promotion choices in a column
+     * Show promotion choices in a column
      * @private
      */
     _showPromotionInColumn(targetSquare, piece, squares, onPromotionSelect, onPromotionCancel) {
-        console.log('Setting up promotion for', targetSquare.id, 'piece color:', piece.color);
-
-        // Set up promotion choices starting from border row
         PROMOTION_PIECES.forEach((pieceType, index) => {
             const choiceSquare = this._findPromotionSquare(targetSquare, index, squares);
-
             if (choiceSquare) {
                 const pieceId = pieceType + piece.color;
                 const piecePath = this._getPiecePathForPromotion(pieceId);
-
-                console.log('Setting up promotion choice:', pieceType, 'on square:', choiceSquare.id);
-
                 choiceSquare.putPromotion(piecePath, () => {
-                    console.log('Promotion choice selected:', pieceType);
                     onPromotionSelect(pieceType);
                 });
-            } else {
-                console.log('Could not find square for promotion choice:', pieceType, 'index:', index);
             }
         });
-
-        // Set up cover squares (for cancellation)
         Object.values(squares).forEach(square => {
             if (!square.hasPromotion()) {
                 square.putCover(() => {
@@ -4344,181 +4056,119 @@ class MoveService {
                 });
             }
         });
-
         return true;
     }
 
     /**
-     * Finds the appropriate square for a promotion piece
+     * Find the appropriate square for a promotion piece
      * @private
      * @param {Square} targetSquare - Target square of the promotion move
-     * @param {number} distance - Distance from target square
+     * @param {number} index - Distance from target square
      * @param {Object} squares - All board squares
      * @returns {Square|null} Square for promotion piece or null
      */
     _findPromotionSquare(targetSquare, index, squares) {
         const col = targetSquare.col;
         const baseRow = targetSquare.row;
-
-        console.log('Looking for promotion square - target:', targetSquare.id, 'index:', index, 'col:', col, 'baseRow:', baseRow);
-
-        // Calculate row based on index and promotion direction
-        // Start from the border row (1 or 8) and go inward
         let row;
         if (baseRow === 8) {
-            // White promotion: start from row 8 and go down
             row = 8 - index;
         } else if (baseRow === 1) {
-            // Black promotion: start from row 1 and go up
             row = 1 + index;
         } else {
-            console.log('Invalid promotion row:', baseRow);
             return null;
         }
-
-        console.log('Calculated row:', row);
-
-        // Ensure row is within bounds
-        if (row < 1 || row > 8) {
-            console.log('Row out of bounds:', row);
-            return null;
-        }
-
-        // Find square by row/col
+        if (row < 1 || row > 8) return null;
         for (const square of Object.values(squares)) {
             if (square.col === col && square.row === row) {
-                console.log('Found promotion square:', square.id);
                 return square;
             }
         }
-
-        console.log('No square found for col:', col, 'row:', row);
         return null;
     }
 
     /**
-     * Gets piece path for promotion UI
+     * Get piece path for promotion UI
      * @private
      * @param {string} pieceId - Piece identifier
      * @returns {string} Path to piece asset
      */
     _getPiecePathForPromotion(pieceId) {
-        // This would typically use the PieceService
-        // For now, we'll use a simple implementation
         const { piecesPath } = this.config;
-
         if (typeof piecesPath === 'string') {
             return `${piecesPath}/${pieceId}.svg`;
         }
-
-        // Fallback for other path types
         return `assets/pieces/${pieceId}.svg`;
     }
 
     /**
-     * Parses a move string into a move object
+     * Parse a move string into a move object
      * @param {string} moveString - Move string (e.g., 'e2e4', 'e7e8q')
      * @returns {Object|null} Move object or null if invalid
      */
     parseMove(moveString) {
-        if (typeof moveString !== 'string' || moveString.length < 4 || moveString.length > 5) {
-            return null;
-        }
-
+        if (typeof moveString !== 'string' || moveString.length < 4 || moveString.length > 5) return null;
         const from = moveString.slice(0, 2);
         const to = moveString.slice(2, 4);
         const promotion = moveString.slice(4, 5);
-
-        // Basic validation
-        if (!/^[a-h][1-8]$/.test(from) || !/^[a-h][1-8]$/.test(to)) {
-            return null;
-        }
-
-        if (promotion && !['q', 'r', 'b', 'n'].includes(promotion.toLowerCase())) {
-            return null;
-        }
-
-        return {
-            from: from,
-            to: to,
-            promotion: promotion || null
-        };
+        if (!/^[a-h][1-8]$/.test(from) || !/^[a-h][1-8]$/.test(to)) return null;
+        if (promotion && !['q', 'r', 'b', 'n'].includes(promotion.toLowerCase())) return null;
+        return { from, to, promotion: promotion || null };
     }
 
     /**
-     * Checks if a move is a castle move
+     * Check if a move is a castle move
      * @param {Object} gameMove - Game move object from chess.js
      * @returns {boolean} True if move is castle
      */
     isCastle(gameMove) {
-        return gameMove && (gameMove.isKingsideCastle() || gameMove.isQueensideCastle());
+        return gameMove && (gameMove.isKingsideCastle && gameMove.isKingsideCastle() || gameMove.isQueensideCastle && gameMove.isQueensideCastle());
     }
 
     /**
-     * Gets the rook move for a castle move
+     * Get the rook move for a castle move
      * @param {Object} gameMove - Game move object from chess.js
      * @returns {Object|null} Rook move object or null if not castle
      */
     getCastleRookMove(gameMove) {
-        if (!this.isCastle(gameMove)) {
-            return null;
-        }
-
+        if (!this.isCastle(gameMove)) return null;
         const isKingSide = gameMove.isKingsideCastle();
         const isWhite = gameMove.color === 'w';
-
         if (isKingSide) {
-            // King side castle
-            if (isWhite) {
-                return { from: 'h1', to: 'f1' };
-            } else {
-                return { from: 'h8', to: 'f8' };
-            }
+            return isWhite ? { from: 'h1', to: 'f1' } : { from: 'h8', to: 'f8' };
         } else {
-            // Queen side castle
-            if (isWhite) {
-                return { from: 'a1', to: 'd1' };
-            } else {
-                return { from: 'a8', to: 'd8' };
-            }
+            return isWhite ? { from: 'a1', to: 'd1' } : { from: 'a8', to: 'd8' };
         }
     }
 
     /**
-     * Checks if a move is en passant
+     * Check if a move is en passant
      * @param {Object} gameMove - Game move object from chess.js
      * @returns {boolean} True if move is en passant
      */
     isEnPassant(gameMove) {
-        return gameMove && gameMove.isEnPassant();
+        return gameMove && gameMove.isEnPassant && gameMove.isEnPassant();
     }
 
     /**
-     * Gets the captured pawn square for en passant
+     * Get the captured pawn square for en passant
      * @param {Object} gameMove - Game move object from chess.js
      * @returns {string|null} Square of captured pawn or null if not en passant
      */
     getEnPassantCapturedSquare(gameMove) {
-        if (!this.isEnPassant(gameMove)) {
-            return null;
-        }
-
+        if (!this.isEnPassant(gameMove)) return null;
         const toSquare = gameMove.to;
         const rank = parseInt(toSquare[1]);
         const file = toSquare[0];
-
-        // The captured pawn is on the same file but different rank
         if (gameMove.color === 'w') {
-            // White captures black pawn one rank below
             return file + (rank - 1);
         } else {
-            // Black captures white pawn one rank above
             return file + (rank + 1);
         }
     }
 
     /**
-     * Clears the moves cache
+     * Clear the moves cache
      */
     clearCache() {
         this._movesCache.clear();
@@ -4529,7 +4179,7 @@ class MoveService {
     }
 
     /**
-     * Cleans up resources
+     * Clean up resources
      */
     destroy() {
         this.clearCache();
@@ -4538,7 +4188,7 @@ class MoveService {
 }
 
 /**
- * Service for managing chess pieces and their operations
+ * PieceService - Handles chess piece management and operations
  * @module services/PieceService
  * @since 2.0.0
  */
@@ -4546,11 +4196,11 @@ class MoveService {
 
 /**
  * Service responsible for piece management and operations
- * @class
+ * @class PieceService
  */
 class PieceService {
     /**
-     * Creates a new PieceService instance
+     * Create a new PieceService instance
      * @param {ChessboardConfig} config - Board configuration
      */
     constructor(config) {
@@ -4558,14 +4208,13 @@ class PieceService {
     }
 
     /**
-     * Gets the path to a piece asset
+     * Get the path to a piece asset
      * @param {string} piece - Piece identifier (e.g., 'wK', 'bP')
      * @returns {string} Path to piece asset
      * @throws {ValidationError} When piecesPath configuration is invalid
      */
     getPiecePath(piece) {
         const { piecesPath } = this.config;
-
         if (typeof piecesPath === 'string') {
             return `${piecesPath}/${piece}.svg`;
         } else if (typeof piecesPath === 'object' && piecesPath !== null) {
@@ -4578,7 +4227,7 @@ class PieceService {
     }
 
     /**
-     * Converts various piece formats to a Piece instance
+     * Convert various piece formats to a Piece instance
      * @param {string|Piece} piece - Piece in various formats
      * @returns {Piece} Piece instance
      * @throws {PieceError} When piece format is invalid
@@ -4587,54 +4236,41 @@ class PieceService {
         if (piece instanceof Piece) {
             return piece;
         }
-
         if (typeof piece === 'string' && piece.length === 2) {
             const [first, second] = piece.split('');
             let type, color;
-
-            // Check format: [type][color] (e.g., 'pw')
             if (PIECE_TYPES.includes(first.toLowerCase()) && PIECE_COLORS.includes(second)) {
                 type = first.toLowerCase();
                 color = second;
-            }
-            // Check format: [color][type] (e.g., 'wP')
-            else if (PIECE_COLORS.includes(first) && PIECE_TYPES.includes(second.toLowerCase())) {
+            } else if (PIECE_COLORS.includes(first) && PIECE_TYPES.includes(second.toLowerCase())) {
                 color = first;
                 type = second.toLowerCase();
             } else {
                 throw new PieceError(ERROR_MESSAGES.invalid_piece + piece, piece);
             }
-
             const piecePath = this.getPiecePath(type + color);
             return new Piece(color, type, piecePath);
         }
-
         throw new PieceError(ERROR_MESSAGES.invalid_piece + piece, piece);
     }
 
     /**
-     * Adds a piece to a square with optional fade-in animation
-     * @param {Square} square - Target square (oggetto)
-     * @param {Piece} piece - Piece to add (oggetto)
+     * Add a piece to a square with optional fade-in animation
+     * @param {Square} square - Target square
+     * @param {Piece} piece - Piece to add
      * @param {boolean} [fade=true] - Whether to fade in the piece
      * @param {Function} dragFunction - Function to handle drag events
      * @param {Function} [callback] - Callback when animation completes
      */
     addPieceOnSquare(square, piece, fade = true, dragFunction, callback) {
-        if (!square || !piece) throw new Error('addPieceOnSquare richiede oggetti Square e Piece');
-        console.debug(`[PieceService] addPieceOnSquare: ${piece.id} to ${square.id}`);
+        if (!square || !piece) throw new Error('addPieceOnSquare requires Square and Piece objects');
         square.putPiece(piece);
-
-        // Imposta sempre il drag (touch e mouse)
         if (dragFunction) {
             piece.setDrag(dragFunction(square, piece));
         }
-        // Forza il drag touch se manca (debug/robustezza)
         if (!piece.element.ontouchstart) {
             piece.element.ontouchstart = dragFunction ? dragFunction(square, piece) : () => { };
-            console.debug(`[PieceService] Forzato ontouchstart su ${piece.id}`);
         }
-
         if (fade && this.config.fadeTime > 0) {
             piece.fadeIn(
                 this.config.fadeTime,
@@ -4645,28 +4281,24 @@ class PieceService {
         } else {
             if (callback) callback();
         }
-
         piece.visible();
     }
 
     /**
-     * Rimuove un pezzo da una casella
-     * @param {Square} square - Oggetto Square
+     * Remove a piece from a square
+     * @param {Square} square - Square object
      * @param {boolean} [fade=true]
      * @param {Function} [callback]
-     * @returns {Piece} Il pezzo rimosso
+     * @returns {Piece} The removed piece
      */
     removePieceFromSquare(square, fade = true, callback) {
-        if (!square) throw new Error('removePieceFromSquare richiede oggetto Square');
-        console.debug(`[PieceService] removePieceFromSquare: ${square.id}`);
+        if (!square) throw new Error('removePieceFromSquare requires a Square object');
         square.check();
-
         const piece = square.piece;
         if (!piece) {
             if (callback) callback();
             throw new PieceError(ERROR_MESSAGES.square_no_piece, null, square.getId());
         }
-
         if (fade && this.config.fadeTime > 0) {
             piece.fadeOut(
                 this.config.fadeTime,
@@ -4677,26 +4309,22 @@ class PieceService {
         } else {
             if (callback) callback();
         }
-
         square.removePiece();
         return piece;
     }
 
     /**
-     * Moves a piece to a new position with animation
+     * Move a piece to a new position with animation
      * @param {Piece} piece - Piece to move
      * @param {Square} targetSquare - Target square
      * @param {number} duration - Animation duration
      * @param {Function} [callback] - Callback function when animation completes
      */
     movePiece(piece, targetSquare, duration, callback) {
-        console.debug(`[PieceService] movePiece: ${piece.id} to ${targetSquare.id}`);
         if (!piece || !piece.element) {
-            console.warn(`[PieceService] movePiece: piece or element is null, skipping animation`);
             if (callback) callback();
             return;
         }
-
         piece.translate(
             targetSquare,
             duration,
@@ -4707,7 +4335,7 @@ class PieceService {
     }
 
     /**
-     * Handles piece translation with optional capture
+     * Handle piece translation with optional capture
      * @param {Move} move - Move object containing from/to squares and piece
      * @param {boolean} removeTarget - Whether to remove piece from target square
      * @param {boolean} animate - Whether to animate the move
@@ -4715,54 +4343,37 @@ class PieceService {
      * @param {Function} [callback] - Callback function when complete
      */
     translatePiece(move, removeTarget, animate, dragFunction = null, callback = null) {
-        console.debug(`[PieceService] translatePiece: ${move.piece.id} from ${move.from.id} to ${move.to.id}`);
         if (!move.piece) {
-            console.warn('PieceService.translatePiece: move.piece is null, skipping translation');
             if (callback) callback();
             return;
         }
-
         if (removeTarget) {
-            // Deselect the captured piece before removing it
             move.to.deselect();
             this.removePieceFromSquare(move.to, false);
         }
-
         const changeSquareCallback = () => {
-            // Check if piece still exists and is on the source square
             if (move.from.piece === move.piece) {
-                move.from.removePiece(true); // Preserve the piece when moving
+                move.from.removePiece(true);
             }
-
-            // Only put piece if destination square doesn't already have it
             if (move.to.piece !== move.piece) {
                 move.to.putPiece(move.piece);
-
-                // Re-attach drag handler if provided
                 if (dragFunction && this.config.draggable && move.piece.element) {
                     move.piece.setDrag(dragFunction(move.to, move.piece));
                 }
             }
-
             if (callback) callback();
         };
-
-        // Check if piece is currently being dragged
         const isDragging = move.piece.element && move.piece.element.classList.contains('dragging');
-
         if (isDragging) {
-            // If piece is being dragged, don't animate - just move it immediately
-            // The piece is already visually in the correct position from the drag
             changeSquareCallback();
         } else {
-            // Normal animation
             const duration = animate ? this.config.moveTime : 0;
             this.movePiece(move.piece, move.to, duration, changeSquareCallback);
         }
     }
 
     /**
-     * Snaps a piece back to its original position
+     * Snap a piece back to its original position
      * @param {Square} square - Square containing the piece
      * @param {boolean} [animate=true] - Whether to animate the snapback
      */
@@ -4772,7 +4383,6 @@ class PieceService {
         }
         const piece = square.piece;
         const duration = animate ? this.config.snapbackTime : 0;
-        console.debug(`[PieceService] snapbackPiece: ${piece.id} on ${square.id}`);
         piece.translate(
             square,
             duration,
@@ -4782,7 +4392,7 @@ class PieceService {
     }
 
     /**
-     * Centers a piece in its square with animation (after successful drop)
+     * Center a piece in its square with animation (after successful drop)
      * @param {Square} square - Square containing the piece to center
      * @param {boolean} animate - Whether to animate the centering
      */
@@ -4792,14 +4402,12 @@ class PieceService {
         }
         const piece = square.piece;
         const duration = animate ? this.config.dropCenterTime : 0;
-        console.debug(`[PieceService] centerPiece: ${piece.id} on ${square.id}`);
         piece.translate(
             square,
             duration,
             this._getTransitionTimingFunction(),
             this.config.dropCenterAnimation,
             () => {
-                // After animation, reset all drag-related styles
                 if (!piece.element) return;
                 piece.element.style.position = '';
                 piece.element.style.left = '';
@@ -4811,14 +4419,13 @@ class PieceService {
     }
 
     /**
-     * Gets the transition timing function for animations
+     * Get the transition timing function for animations
      * @private
      * @returns {Function} Timing function
      */
     _getTransitionTimingFunction() {
         return (elapsed, duration, type = 'ease') => {
             const x = elapsed / duration;
-
             switch (type) {
                 case 'linear':
                     return x;
@@ -4837,7 +4444,7 @@ class PieceService {
     }
 
     /**
-     * Cleans up resources
+     * Clean up resources
      */
     destroy() {
         // Cleanup any cached pieces or references
@@ -6828,7 +6435,7 @@ class Chess {
 }
 
 /**
- * Service for managing chess positions and FEN conversion
+ * PositionService - Handles chess position management and FEN conversion
  * @module services/PositionService
  * @since 2.0.0
  */
@@ -6836,11 +6443,11 @@ class Chess {
 
 /**
  * Service responsible for position management and FEN operations
- * @class
+ * @class PositionService
  */
 class PositionService {
     /**
-     * Creates a new PositionService instance
+     * Create a new PositionService instance
      * @param {ChessboardConfig} config - Board configuration
      */
     constructor(config) {
@@ -6849,7 +6456,7 @@ class PositionService {
     }
 
     /**
-     * Converts various position formats to FEN string
+     * Convert various position formats to FEN string
      * @param {string|Object} position - Position in various formats
      * @returns {string} FEN string representation
      * @throws {ValidationError} When position format is invalid
@@ -6865,7 +6472,7 @@ class PositionService {
     }
 
     /**
-     * Converts string position to FEN
+     * Convert string position to FEN
      * @private
      * @param {string} position - String position
      * @returns {string} FEN string
@@ -6874,35 +6481,29 @@ class PositionService {
         if (position === 'start') {
             return DEFAULT_STARTING_POSITION;
         }
-        
         if (this.validateFen(position)) {
             return position;
         }
-        
         if (STANDARD_POSITIONS[position]) {
             return STANDARD_POSITIONS[position];
         }
-        
         throw new ValidationError(ERROR_MESSAGES.invalid_position + position, 'position', position);
     }
 
     /**
-     * Converts object position to FEN
+     * Convert object position to FEN
      * @private
      * @param {Object} position - Object with square->piece mapping
      * @returns {string} FEN string
      */
     _convertObjectPosition(position) {
         const parts = [];
-        
         for (let row = 0; row < 8; row++) {
             const rowParts = [];
             let empty = 0;
-            
             for (let col = 0; col < 8; col++) {
                 const square = this._getSquareID(row, col);
                 const piece = position[square];
-                
                 if (piece) {
                     if (empty > 0) {
                         rowParts.push(empty);
@@ -6915,25 +6516,21 @@ class PositionService {
                     empty++;
                 }
             }
-            
             if (empty > 0) {
                 rowParts.push(empty);
             }
-            
             parts.push(rowParts.join(''));
         }
-        
         return parts.join('/') + ' w KQkq - 0 1';
     }
 
     /**
-     * Sets up the game with the given position
+     * Set up the game with the given position
      * @param {string|Object} position - Position to set
      * @param {Object} [options] - Additional options for game setup
      */
     setGame(position, options = {}) {
         const fen = this.convertFen(position);
-        
         if (this.game) {
             this.game.load(fen, options);
         } else {
@@ -6942,7 +6539,7 @@ class PositionService {
     }
 
     /**
-     * Gets the current game instance
+     * Get the current game instance
      * @returns {Chess} Current chess.js game instance
      */
     getGame() {
@@ -6950,7 +6547,7 @@ class PositionService {
     }
 
     /**
-     * Validates a FEN string
+     * Validate a FEN string
      * @param {string} fen - FEN string to validate
      * @returns {boolean} True if valid, false otherwise
      */
@@ -6959,7 +6556,7 @@ class PositionService {
     }
 
     /**
-     * Gets piece information for a specific square
+     * Get piece information for a specific square
      * @param {string} squareId - Square identifier
      * @returns {string|null} Piece ID or null if no piece
      */
@@ -6970,7 +6567,7 @@ class PositionService {
     }
 
     /**
-     * Checks if a specific piece is on a specific square
+     * Check if a specific piece is on a specific square
      * @param {string} piece - Piece ID to check
      * @param {string} square - Square to check
      * @returns {boolean} True if piece is on square
@@ -6980,7 +6577,7 @@ class PositionService {
     }
 
     /**
-     * Converts board coordinates to square ID
+     * Convert board coordinates to square ID
      * @private
      * @param {number} row - Row index (0-7)
      * @param {number} col - Column index (0-7)
@@ -6989,7 +6586,6 @@ class PositionService {
     _getSquareID(row, col) {
         row = parseInt(row);
         col = parseInt(col);
-        
         if (this.config.orientation === 'w') {
             row = 8 - row;
             col = col + 1;
@@ -6997,13 +6593,12 @@ class PositionService {
             row = row + 1;
             col = 8 - col;
         }
-        
         const letter = BOARD_LETTERS[col - 1];
         return letter + row;
     }
 
     /**
-     * Changes the turn in a FEN string
+     * Change the turn in a FEN string
      * @param {string} fen - Original FEN string
      * @param {string} color - New turn color ('w' or 'b')
      * @returns {string} Modified FEN string
@@ -7015,35 +6610,33 @@ class PositionService {
     }
 
     /**
-     * Gets the current position as an object
+     * Get the current position as an object
      * @returns {Object} Position object with piece placements
      */
     getPosition() {
         const position = {};
         const game = this.getGame();
-        
-        // Convert chess.js board to position object
-        const squares = ['a1', 'b1', 'c1', 'd1', 'e1', 'f1', 'g1', 'h1',
-                        'a2', 'b2', 'c2', 'd2', 'e2', 'f2', 'g2', 'h2',
-                        'a3', 'b3', 'c3', 'd3', 'e3', 'f3', 'g3', 'h3',
-                        'a4', 'b4', 'c4', 'd4', 'e4', 'f4', 'g4', 'h4',
-                        'a5', 'b5', 'c5', 'd5', 'e5', 'f5', 'g5', 'h5',
-                        'a6', 'b6', 'c6', 'd6', 'e6', 'f6', 'g6', 'h6',
-                        'a7', 'b7', 'c7', 'd7', 'e7', 'f7', 'g7', 'h7',
-                        'a8', 'b8', 'c8', 'd8', 'e8', 'f8', 'g8', 'h8'];
-        
+        const squares = [
+            'a1', 'b1', 'c1', 'd1', 'e1', 'f1', 'g1', 'h1',
+            'a2', 'b2', 'c2', 'd2', 'e2', 'f2', 'g2', 'h2',
+            'a3', 'b3', 'c3', 'd3', 'e3', 'f3', 'g3', 'h3',
+            'a4', 'b4', 'c4', 'd4', 'e4', 'f4', 'g4', 'h4',
+            'a5', 'b5', 'c5', 'd5', 'e5', 'f5', 'g5', 'h5',
+            'a6', 'b6', 'c6', 'd6', 'e6', 'f6', 'g6', 'h6',
+            'a7', 'b7', 'c7', 'd7', 'e7', 'f7', 'g7', 'h7',
+            'a8', 'b8', 'c8', 'd8', 'e8', 'f8', 'g8', 'h8'
+        ];
         for (const square of squares) {
             const piece = game.get(square);
             if (piece) {
                 position[square] = piece.type + piece.color;
             }
         }
-        
         return position;
     }
 
     /**
-     * Toggles the turn in a FEN string
+     * Toggle the turn in a FEN string
      * @param {string} fen - Original FEN string
      * @returns {string} Modified FEN string
      */
@@ -7054,7 +6647,7 @@ class PositionService {
     }
 
     /**
-     * Cleans up resources
+     * Clean up resources
      */
     destroy() {
         this.game = null;
@@ -7062,7 +6655,8 @@ class PositionService {
 }
 
 /**
- * Main Chessboard class - Orchestrates all services and components
+ * Chessboard - Main class orchestrating all services and components
+ * Implements the Facade pattern for the chessboard API
  * @module core/Chessboard
  * @since 2.0.0
  */
@@ -7070,12 +6664,11 @@ class PositionService {
 
 /**
  * Main Chessboard class responsible for coordinating all services
- * Implements the Facade pattern to provide a unified interface
- * @class
+ * @class Chessboard
  */
 let Chessboard$1 = class Chessboard {
     /**
-     * Creates a new Chessboard instance
+     * Create a new Chessboard instance
      * @param {Object} config - Configuration object
      * @throws {ConfigurationError} If configuration is invalid
      */
@@ -8335,7 +7928,7 @@ let Chessboard$1 = class Chessboard {
     getPiece(square) {
         // Sempre leggi lo stato aggiornato dal boardService
         const squareObj = typeof square === 'string' ? this.boardService.getSquare(square) : square;
-        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[getPiece] Parametro square non valido');
+        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[getPiece] Parameter square is invalid');
         // Forza sync prima di leggere
         this._updateBoardPieces(false, false);
         const piece = squareObj.piece;
@@ -8369,9 +7962,9 @@ let Chessboard$1 = class Chessboard {
             }
         }
         const squareObj = typeof square === 'string' ? this.boardService.getSquare(square) : square;
-        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[putPiece] Parametro square non valido');
+        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[putPiece] Parameter square is invalid');
         const pieceObj = this.pieceService.convertPiece(pieceStr);
-        if (!pieceObj || typeof pieceObj !== 'object' || !('type' in pieceObj)) throw new Error('[putPiece] Parametro piece non valido');
+        if (!pieceObj || typeof pieceObj !== 'object' || !('type' in pieceObj)) throw new Error('[putPiece] Parameter piece is invalid');
         // Aggiorna solo il motore chess.js
         const chessJsPiece = { type: pieceObj.type, color: pieceObj.color };
         const game = this.positionService.getGame();
@@ -8392,7 +7985,7 @@ let Chessboard$1 = class Chessboard {
     removePiece(square, opts = {}) {
         const animate = opts.animate !== undefined ? opts.animate : true;
         const squareObj = typeof square === 'string' ? this.boardService.getSquare(square) : square;
-        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[removePiece] Parametro square non valido');
+        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[removePiece] Parameter square is invalid');
         // Aggiorna solo il motore chess.js
         const game = this.positionService.getGame();
         game.remove(squareObj.id);
@@ -8468,7 +8061,7 @@ let Chessboard$1 = class Chessboard {
     highlight(square, opts = {}) {
         // API: accetta id, converte subito in oggetto
         const squareObj = typeof square === 'string' ? this.boardService.getSquare(square) : square;
-        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[highlight] Parametro square non valido');
+        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[highlight] Parameter square is invalid');
         if (this.boardService && this.boardService.highlightSquare) {
             this.boardService.highlightSquare(squareObj, opts);
         } else if (this.eventService && this.eventService.highlightSquare) {
@@ -8483,7 +8076,7 @@ let Chessboard$1 = class Chessboard {
     dehighlight(square, opts = {}) {
         // API: accetta id, converte subito in oggetto
         const squareObj = typeof square === 'string' ? this.boardService.getSquare(square) : square;
-        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[dehighlight] Parametro square non valido');
+        if (!squareObj || typeof squareObj !== 'object' || !('id' in squareObj)) throw new Error('[dehighlight] Parameter square is invalid');
         if (this.boardService && this.boardService.dehighlightSquare) {
             this.boardService.dehighlightSquare(squareObj, opts);
         } else if (this.eventService && this.eventService.dehighlightSquare) {
@@ -8552,9 +8145,47 @@ let Chessboard$1 = class Chessboard {
 
     // --- LIFECYCLE ---
     /**
-     * Destroy the board and cleanup
+     * Destroy the board and cleanup all resources
      */
-    destroy() { /* TODO: robust destroy logic */ }
+    destroy() {
+        // Remove event listeners
+        if (this.eventService && typeof this.eventService.removeListeners === 'function') {
+            this.eventService.removeListeners();
+        }
+        // Clear timeouts
+        if (this._updateTimeout) {
+            clearTimeout(this._updateTimeout);
+            this._updateTimeout = null;
+        }
+        // Destroy all services
+        [
+            'validationService',
+            'coordinateService',
+            'positionService',
+            'boardService',
+            'pieceService',
+            'animationService',
+            'moveService',
+            'eventService',
+        ].forEach(service => {
+            if (this[service] && typeof this[service].destroy === 'function') {
+                this[service].destroy();
+            }
+            this[service] = null;
+        });
+        // Nullify DOM references
+        this._performanceMonitor = null;
+        this._boundUpdateBoardPieces = null;
+        this._boundOnSquareClick = null;
+        this._boundOnPieceHover = null;
+        this._boundOnPieceLeave = null;
+        this._undoneMoves = null;
+        // Remove board DOM if possible
+        const boardContainer = document.getElementById(this.config?.id_div);
+        if (boardContainer) {
+            boardContainer.innerHTML = '';
+        }
+    }
     /**
      * Rebuild the board
      */