@alepot55/chessboardjs 2.2.2 → 2.3.0

package/dist/chessboard.iife.js

@@ -1071,11 +1071,84 @@ var ChessboardLib = (function (exports) {
      * @constant
      * @type {Object}
      */
+    /**
+     * Flip mode options
+     * @constant
+     * @type {Object}
+     */
+    const FLIP_MODES = Object.freeze({
+        visual: 'visual',      // CSS flexbox visual flip (instant, no piece animation)
+        animate: 'animate',    // Animate pieces to mirrored positions (smooth animation)
+        none: 'none'           // No visual change, only internal orientation
+    });
+
+    /**
+     * Movement style options - how pieces travel from source to destination
+     * @constant
+     * @type {Object}
+     */
+    const MOVE_STYLES = Object.freeze({
+        slide: 'slide',        // Linear movement (default) - piece slides in straight line
+        arc: 'arc',            // Arc trajectory - piece lifts up then comes down
+        hop: 'hop',            // Parabolic jump - like a knight hopping
+        teleport: 'teleport',  // Instant - no animation, piece appears at destination
+        fade: 'fade'           // Crossfade - fades out at source, fades in at destination
+    });
+
+    /**
+     * Capture animation options - what happens to captured pieces
+     * @constant
+     * @type {Object}
+     */
+    const CAPTURE_STYLES = Object.freeze({
+        fade: 'fade',          // Fade out (default)
+        shrink: 'shrink',      // Shrink then fade
+        instant: 'instant',    // Disappears immediately
+        explode: 'explode'     // Scale up and fade (dramatic effect)
+    });
+
+    /**
+     * Appearance animation options - how new pieces appear on the board
+     * @constant
+     * @type {Object}
+     */
+    const APPEARANCE_STYLES = Object.freeze({
+        fade: 'fade',          // Opacity + subtle scale (default)
+        pulse: 'pulse',        // Double pulse scale bounce
+        pop: 'pop',            // Scale 0→1.15→1 with spring easing
+        drop: 'drop',          // Drops from above with bounce
+        instant: 'instant'     // No animation
+    });
+
+    /**
+     * Landing effect options - what happens when piece reaches destination
+     * @constant
+     * @type {Object}
+     */
+    const LANDING_EFFECTS = Object.freeze({
+        none: 'none',          // No effect (default)
+        bounce: 'bounce',      // Slight bounce on landing
+        pulse: 'pulse',        // Quick scale pulse
+        settle: 'settle'       // Subtle settling animation
+    });
+
+    /**
+     * Drag style options - how pieces behave during drag
+     * @constant
+     * @type {Object}
+     */
+    const DRAG_STYLES = Object.freeze({
+        smooth: 'smooth',      // Piece follows cursor smoothly (default)
+        snap: 'snap',          // Piece snaps to cursor position
+        elastic: 'elastic'     // Slight elastic lag behind cursor
+    });
+
     const DEFAULT_CONFIG$1 = Object.freeze({
         id: 'board',
         position: 'start',
         orientation: 'w',
         mode: 'normal',
+        flipMode: 'visual',    // 'visual', 'animate', or 'none'
         size: 'auto',
         draggable: true,
         hints: true,
@@ -1083,15 +1156,45 @@ var ChessboardLib = (function (exports) {
         movableColors: 'both',
         moveHighlight: true,
         overHighlight: true,
-        moveAnimation: 'ease',
-        moveTime: 'fast',
-        dropOffBoard: 'snapback',
+
+        // Movement configuration
+        moveStyle: 'slide',          // 'slide', 'arc', 'hop', 'teleport', 'fade'
+        moveEasing: 'ease',          // CSS easing function
+        moveTime: 'fast',            // Duration: 'instant', 'veryFast', 'fast', 'normal', 'slow', 'verySlow' or ms
+        moveArcHeight: 0.3,          // Arc height as ratio of distance (for 'arc' and 'hop' styles)
+
+        // Capture configuration
+        captureStyle: 'fade',        // 'fade', 'shrink', 'instant', 'explode'
+        captureTime: 'fast',         // Duration for capture animation
+
+        // Appearance configuration
+        appearanceStyle: 'fade',     // 'fade', 'pulse', 'pop', 'drop', 'instant'
+        appearanceTime: 'fast',      // Duration for appearance animation
+
+        // Landing effect configuration
+        landingEffect: 'none',       // 'none', 'bounce', 'pulse', 'settle'
+        landingDuration: 150,        // Duration for landing effect in ms
+
+        // Drag configuration
+        dragStyle: 'smooth',         // 'smooth', 'snap', 'elastic'
+        dragScale: 1.05,             // Scale factor while dragging (1.0 = no scale)
+        dragOpacity: 0.9,            // Opacity while dragging
+
+        // Snapback configuration
         snapbackTime: 'fast',
-        snapbackAnimation: 'ease',
+        snapbackEasing: 'ease',
+
+        // Other timing
+        dropOffBoard: 'snapback',
         dropCenterTime: 'veryFast',
         dropCenterAnimation: 'ease',
         fadeTime: 'fast',
         fadeAnimation: 'ease',
+
+        // Legacy compatibility
+        moveAnimation: 'ease',
+        snapbackAnimation: 'ease',
+
         ratio: 0.9,
         piecesPath: '../assets/themes/default',
         animationStyle: 'simultaneous',
@@ -1186,6 +1289,7 @@ var ChessboardLib = (function (exports) {
             this.position = config.position;
             this.orientation = config.orientation;
             this.mode = config.mode;
+            this.flipMode = this._validateFlipMode(config.flipMode);
             this.dropOffBoard = config.dropOffBoard;
             this.size = config.size;
             this.movableColors = config.movableColors;
@@ -1200,12 +1304,27 @@ var ChessboardLib = (function (exports) {
             this.onDrop = this._validateCallback(config.onDrop);
             this.onSnapbackEnd = this._validateCallback(config.onSnapbackEnd);
 
-            // Animation properties
+            // Animation properties (legacy)
             this.moveAnimation = this._setTransitionFunction(config.moveAnimation);
             this.snapbackAnimation = this._setTransitionFunction(config.snapbackAnimation);
             this.dropCenterAnimation = this._setTransitionFunction(config.dropCenterAnimation);
             this.fadeAnimation = this._setTransitionFunction(config.fadeAnimation);
 
+            // Movement configuration (new system)
+            this.moveStyle = this._validateMoveStyle(config.moveStyle);
+            this.moveEasing = this._setTransitionFunction(config.moveEasing);
+            this.moveArcHeight = this._validateNumber(config.moveArcHeight, 0, 1, 'moveArcHeight');
+            this.captureStyle = this._validateCaptureStyle(config.captureStyle);
+            this.captureTime = this._setTime(config.captureTime);
+            this.appearanceStyle = this._validateAppearanceStyle(config.appearanceStyle);
+            this.appearanceTime = this._setTime(config.appearanceTime);
+            this.landingEffect = this._validateLandingEffect(config.landingEffect);
+            this.landingDuration = this._validateNumber(config.landingDuration, 0, 2000, 'landingDuration');
+            this.dragStyle = this._validateDragStyle(config.dragStyle);
+            this.dragScale = this._validateNumber(config.dragScale, 0.5, 2, 'dragScale');
+            this.dragOpacity = this._validateNumber(config.dragOpacity, 0.1, 1, 'dragOpacity');
+            this.snapbackEasing = this._setTransitionFunction(config.snapbackEasing);
+
             // Boolean properties
             this.hints = this._setBoolean(config.hints);
             this.clickable = this._setBoolean(config.clickable);
@@ -1309,6 +1428,111 @@ var ChessboardLib = (function (exports) {
             return delay;
         }
 
+        /**
+         * Validates flip mode
+         * @private
+         * @param {string} mode - Flip mode
+         * @returns {string} Validated mode
+         * @throws {ConfigurationError} If mode is invalid
+         */
+        _validateFlipMode(mode) {
+            if (!mode || !FLIP_MODES[mode]) {
+                throw new ConfigurationError(
+                    `Invalid flip mode: ${mode}. Valid options: ${Object.keys(FLIP_MODES).join(', ')}`,
+                    'flipMode',
+                    mode
+                );
+            }
+            return mode;
+        }
+
+        /**
+         * Validates move style
+         * @private
+         * @param {string} style - Move style
+         * @returns {string} Validated style
+         */
+        _validateMoveStyle(style) {
+            if (!style || !MOVE_STYLES[style]) {
+                console.warn(`Invalid move style: ${style}. Using 'slide'. Valid: ${Object.keys(MOVE_STYLES).join(', ')}`);
+                return 'slide';
+            }
+            return style;
+        }
+
+        /**
+         * Validates capture style
+         * @private
+         * @param {string} style - Capture style
+         * @returns {string} Validated style
+         */
+        _validateCaptureStyle(style) {
+            if (!style || !CAPTURE_STYLES[style]) {
+                console.warn(`Invalid capture style: ${style}. Using 'fade'. Valid: ${Object.keys(CAPTURE_STYLES).join(', ')}`);
+                return 'fade';
+            }
+            return style;
+        }
+
+        /**
+         * Validates appearance style
+         * @private
+         * @param {string} style - Appearance style
+         * @returns {string} Validated style
+         */
+        _validateAppearanceStyle(style) {
+            if (!style || !APPEARANCE_STYLES[style]) {
+                console.warn(`Invalid appearance style: ${style}. Using 'fade'. Valid: ${Object.keys(APPEARANCE_STYLES).join(', ')}`);
+                return 'fade';
+            }
+            return style;
+        }
+
+        /**
+         * Validates landing effect
+         * @private
+         * @param {string} effect - Landing effect
+         * @returns {string} Validated effect
+         */
+        _validateLandingEffect(effect) {
+            if (!effect || !LANDING_EFFECTS[effect]) {
+                console.warn(`Invalid landing effect: ${effect}. Using 'none'. Valid: ${Object.keys(LANDING_EFFECTS).join(', ')}`);
+                return 'none';
+            }
+            return effect;
+        }
+
+        /**
+         * Validates drag style
+         * @private
+         * @param {string} style - Drag style
+         * @returns {string} Validated style
+         */
+        _validateDragStyle(style) {
+            if (!style || !DRAG_STYLES[style]) {
+                console.warn(`Invalid drag style: ${style}. Using 'smooth'. Valid: ${Object.keys(DRAG_STYLES).join(', ')}`);
+                return 'smooth';
+            }
+            return style;
+        }
+
+        /**
+         * Validates a number within a range
+         * @private
+         * @param {number} value - Value to validate
+         * @param {number} min - Minimum value
+         * @param {number} max - Maximum value
+         * @param {string} name - Property name for error message
+         * @returns {number} Validated value
+         */
+        _validateNumber(value, min, max, name) {
+            if (typeof value !== 'number' || value < min || value > max) {
+                console.warn(`Invalid ${name}: ${value}. Must be between ${min} and ${max}.`);
+                return (min + max) / 2; // Return middle value as default
+            }
+            return value;
+        }
+
         /**
          * Sets a CSS custom property
          * @private
@@ -1414,6 +1638,7 @@ var ChessboardLib = (function (exports) {
                 position: this.position,
                 orientation: this.orientation,
                 mode: this.mode,
+                flipMode: this.flipMode,
                 size: this.size,
                 draggable: this.draggable,
                 hints: this.hints,
@@ -1421,11 +1646,26 @@ var ChessboardLib = (function (exports) {
                 movableColors: this.movableColors,
                 moveHighlight: this.moveHighlight,
                 overHighlight: this.overHighlight,
-                moveAnimation: this.moveAnimation,
+                // Movement configuration
+                moveStyle: this.moveStyle,
+                moveEasing: this.moveEasing,
                 moveTime: this.moveTime,
-                dropOffBoard: this.dropOffBoard,
+                moveArcHeight: this.moveArcHeight,
+                captureStyle: this.captureStyle,
+                captureTime: this.captureTime,
+                appearanceStyle: this.appearanceStyle,
+                appearanceTime: this.appearanceTime,
+                landingEffect: this.landingEffect,
+                landingDuration: this.landingDuration,
+                dragStyle: this.dragStyle,
+                dragScale: this.dragScale,
+                dragOpacity: this.dragOpacity,
                 snapbackTime: this.snapbackTime,
+                snapbackEasing: this.snapbackEasing,
+                // Legacy
+                moveAnimation: this.moveAnimation,
                 snapbackAnimation: this.snapbackAnimation,
+                dropOffBoard: this.dropOffBoard,
                 dropCenterTime: this.dropCenterTime,
                 dropCenterAnimation: this.dropCenterAnimation,
                 fadeTime: this.fadeTime,
@@ -1630,6 +1870,121 @@ var ChessboardLib = (function (exports) {
             }
         }
 
+        /**
+         * Animate piece appearance with configurable style
+         * @param {string} style - Appearance style: 'fade', 'pulse', 'pop', 'drop', 'instant'
+         * @param {number} duration - Animation duration in ms
+         * @param {Function} callback - Callback when complete
+         */
+        appearAnimate(style, duration, callback) {
+            if (!this.element) {
+                if (callback) callback();
+                return;
+            }
+
+            const element = this.element;
+            const cleanup = () => {
+                if (element) {
+                    element.style.opacity = '1';
+                    element.style.transform = '';
+                }
+                if (callback) callback();
+            };
+
+            const smoothDecel = 'cubic-bezier(0.33, 1, 0.68, 1)';
+            const springOvershoot = 'cubic-bezier(0.34, 1.56, 0.64, 1)';
+
+            switch (style) {
+                case 'instant':
+                    element.style.opacity = '1';
+                    cleanup();
+                    break;
+
+                case 'fade':
+                    if (element.animate) {
+                        element.style.opacity = '0';
+                        const anim = element.animate([
+                            { opacity: 0, transform: 'scale(0.95)' },
+                            { opacity: 1, transform: 'scale(1)' }
+                        ], { duration, easing: smoothDecel, fill: 'forwards' });
+                        anim.onfinish = () => {
+                            anim.cancel();
+                            cleanup();
+                        };
+                    } else {
+                        element.style.opacity = '0';
+                        element.style.transform = 'scale(0.95)';
+                        setTimeout(cleanup, duration);
+                    }
+                    break;
+
+                case 'pulse':
+                    if (element.animate) {
+                        element.style.opacity = '0';
+                        const anim = element.animate([
+                            { opacity: 0, transform: 'scale(0.6)', offset: 0 },
+                            { opacity: 1, transform: 'scale(1.12)', offset: 0.3 },
+                            { opacity: 1, transform: 'scale(0.92)', offset: 0.55 },
+                            { opacity: 1, transform: 'scale(1.06)', offset: 0.8 },
+                            { opacity: 1, transform: 'scale(1)', offset: 1 }
+                        ], { duration, easing: smoothDecel, fill: 'forwards' });
+                        anim.onfinish = () => {
+                            anim.cancel();
+                            cleanup();
+                        };
+                    } else {
+                        element.style.opacity = '0';
+                        element.style.transform = 'scale(0.6)';
+                        setTimeout(cleanup, duration);
+                    }
+                    break;
+
+                case 'pop':
+                    if (element.animate) {
+                        element.style.opacity = '0';
+                        const anim = element.animate([
+                            { opacity: 0, transform: 'scale(0)', offset: 0 },
+                            { opacity: 1, transform: 'scale(1.15)', offset: 0.6 },
+                            { opacity: 1, transform: 'scale(1)', offset: 1 }
+                        ], { duration, easing: springOvershoot, fill: 'forwards' });
+                        anim.onfinish = () => {
+                            anim.cancel();
+                            cleanup();
+                        };
+                    } else {
+                        element.style.opacity = '0';
+                        element.style.transform = 'scale(0)';
+                        setTimeout(cleanup, duration);
+                    }
+                    break;
+
+                case 'drop':
+                    if (element.animate) {
+                        element.style.opacity = '0';
+                        const anim = element.animate([
+                            { opacity: 0, transform: 'translateY(-15px) scale(0.95)', offset: 0 },
+                            { opacity: 1, transform: 'translateY(3px) scale(1.02)', offset: 0.5 },
+                            { opacity: 1, transform: 'translateY(-1px) scale(1)', offset: 0.75 },
+                            { opacity: 1, transform: 'translateY(0) scale(1)', offset: 1 }
+                        ], { duration, easing: smoothDecel, fill: 'forwards' });
+                        anim.onfinish = () => {
+                            anim.cancel();
+                            cleanup();
+                        };
+                    } else {
+                        element.style.opacity = '0';
+                        element.style.transform = 'translateY(-15px) scale(0.95)';
+                        setTimeout(cleanup, duration);
+                    }
+                    break;
+
+                default:
+                    this.appearAnimate('fade', duration, callback);
+                    return;
+            }
+        }
+
+        /** @deprecated Use appearAnimate() instead */
         fadeIn(duration, speed, transition_f, callback) {
             let start = performance.now();
             let opacity = 0;
@@ -1663,15 +2018,105 @@ var ChessboardLib = (function (exports) {
                 if (elapsed < duration) {
                     requestAnimationFrame(fade);
                 } else {
-                    if (!piece.element) { console.debug(`[Piece] fadeOut: ${piece.id} - element is null (end)`); if (callback) callback(); return; }
+                    if (!piece.element) { if (callback) callback(); return; }
                     piece.element.style.opacity = 0;
-                    console.debug(`[Piece] fadeOut complete: ${piece.id}`);
+                    // Remove element from DOM after fade completes
+                    if (piece.element.parentNode) {
+                        piece.element.parentNode.removeChild(piece.element);
+                    }
                     if (callback) callback();
                 }
             };
             fade();
         }
 
+        /**
+         * Animate piece capture with configurable style
+         * Uses fluid easing for smooth, connected animations
+         * @param {string} style - Capture style: 'fade', 'shrink', 'instant', 'explode'
+         * @param {number} duration - Animation duration in ms
+         * @param {Function} callback - Callback when complete
+         */
+        captureAnimate(style, duration, callback) {
+            if (!this.element) {
+                if (callback) callback();
+                return;
+            }
+
+            const element = this.element;
+            const cleanup = () => {
+                if (element && element.parentNode) {
+                    element.parentNode.removeChild(element);
+                }
+                if (callback) callback();
+            };
+
+            // Fluid easing functions
+            const smoothDecel = 'cubic-bezier(0.33, 1, 0.68, 1)';
+            const smoothAccel = 'cubic-bezier(0.32, 0, 0.67, 0)';
+
+            switch (style) {
+                case 'instant':
+                    cleanup();
+                    break;
+
+                case 'fade':
+                    if (element.animate) {
+                        // Smooth fade with subtle scale down
+                        const anim = element.animate([
+                            { opacity: 1, transform: 'scale(1)' },
+                            { opacity: 0, transform: 'scale(0.9)' }
+                        ], { duration, easing: smoothDecel, fill: 'forwards' });
+                        anim.onfinish = cleanup;
+                    } else {
+                        element.style.transition = `opacity ${duration}ms ease-out, transform ${duration}ms ease-out`;
+                        element.style.opacity = '0';
+                        element.style.transform = 'scale(0.9)';
+                        setTimeout(cleanup, duration);
+                    }
+                    break;
+
+                case 'shrink':
+                    if (element.animate) {
+                        // Smooth shrink with accelerating easing for "sucked in" feel
+                        const anim = element.animate([
+                            { transform: 'scale(1)', opacity: 1, offset: 0 },
+                            { transform: 'scale(0.7)', opacity: 0.6, offset: 0.6 },
+                            { transform: 'scale(0)', opacity: 0, offset: 1 }
+                        ], { duration, easing: smoothAccel, fill: 'forwards' });
+                        anim.onfinish = cleanup;
+                    } else {
+                        element.style.transition = `transform ${duration}ms ease-in, opacity ${duration}ms ease-in`;
+                        element.style.transform = 'scale(0)';
+                        element.style.opacity = '0';
+                        setTimeout(cleanup, duration);
+                    }
+                    break;
+
+                case 'explode':
+                    if (element.animate) {
+                        // Subtle expand with smooth deceleration - less dramatic
+                        const anim = element.animate([
+                            { transform: 'scale(1)', opacity: 1, offset: 0 },
+                            { transform: 'scale(1.15)', opacity: 0.5, offset: 0.5 },
+                            { transform: 'scale(1.25)', opacity: 0, offset: 1 }
+                        ], { duration, easing: smoothDecel, fill: 'forwards' });
+                        anim.onfinish = cleanup;
+                    } else {
+                        element.style.transition = `transform ${duration}ms ease-out, opacity ${duration}ms ease-out`;
+                        element.style.transform = 'scale(1.25)';
+                        element.style.opacity = '0';
+                        setTimeout(cleanup, duration);
+                    }
+                    break;
+
+                default:
+                    // Default to fade
+                    this.captureAnimate('fade', duration, callback);
+                    return;
+            }
+        }
+
         setDrag(f) {
             if (!this.element) { console.debug(`[Piece] setDrag: ${this.id} - element is null`); return; }
             
@@ -1711,41 +2156,319 @@ var ChessboardLib = (function (exports) {
             }
         }
 
-        translate(to, duration, transition_f, speed, callback = null) {
-            if (!this.element) { console.debug(`[Piece] translate: ${this.id} - element is null`); if (callback) callback(); return; }
-            let sourceRect = this.element.getBoundingClientRect();
-            let targetRect = to.getBoundingClientRect();
-            let x_start = sourceRect.left + sourceRect.width / 2;
-            let y_start = sourceRect.top + sourceRect.height / 2;
-            let x_end = targetRect.left + targetRect.width / 2;
-            let y_end = targetRect.top + targetRect.height / 2;
-            let dx = x_end - x_start;
-            let dy = y_end - y_start;
+        /**
+         * Translate piece to target position with configurable movement style
+         * Uses Chessground-style cubic easing for fluid, natural movement
+         * @param {HTMLElement} to - Target element
+         * @param {number} duration - Animation duration in ms
+         * @param {Function} transition_f - Transition function (unused, for compatibility)
+         * @param {number} speed - Speed factor (unused, for compatibility)
+         * @param {Function} callback - Callback when complete
+         * @param {Object} options - Movement options
+         * @param {string} options.style - Movement style: 'slide', 'arc', 'hop', 'teleport', 'fade'
+         * @param {string} options.easing - CSS easing function
+         * @param {number} options.arcHeight - Arc height ratio (for arc/hop styles)
+         * @param {string} options.landingEffect - Landing effect: 'none', 'bounce', 'pulse', 'settle'
+         * @param {number} options.landingDuration - Landing effect duration in ms
+         */
+        translate(to, duration, transition_f, speed, callback = null, options = {}) {
+            if (!this.element) {
+                console.debug(`[Piece] translate: ${this.id} - element is null`);
+                if (callback) callback();
+                return;
+            }
 
-            let keyframes = [
-                { transform: 'translate(0, 0)' },
-                { transform: `translate(${dx}px, ${dy}px)` }
-            ];
+            const style = options.style || 'slide';
+            const arcHeight = options.arcHeight || 0.3;
+            const landingEffect = options.landingEffect || 'none';
+            const landingDuration = options.landingDuration || 150;
+
+            // Map easing names to Chessground-style fluid cubic-bezier curves
+            // Default: smooth deceleration like Lichess/Chessground
+            const easingMap = {
+                'ease': 'cubic-bezier(0.33, 1, 0.68, 1)',           // Chessground default - smooth decel
+                'linear': 'linear',
+                'ease-in': 'cubic-bezier(0.32, 0, 0.67, 0)',       // Smooth acceleration
+                'ease-out': 'cubic-bezier(0.33, 1, 0.68, 1)',      // Smooth deceleration (same as default)
+                'ease-in-out': 'cubic-bezier(0.65, 0, 0.35, 1)'    // Smooth both ways
+            };
+            const easing = easingMap[options.easing] || easingMap['ease'];
+
+            // Handle teleport (instant)
+            if (style === 'teleport' || duration === 0) {
+                if (callback) callback();
+                return;
+            }
+
+            // Handle fade style
+            if (style === 'fade') {
+                this._translateFade(to, duration, easing, landingEffect, landingDuration, callback);
+                return;
+            }
+
+            // Calculate movement vectors
+            const sourceRect = this.element.getBoundingClientRect();
+            const targetRect = to.getBoundingClientRect();
+            const dx = (targetRect.left + targetRect.width / 2) - (sourceRect.left + sourceRect.width / 2);
+            const dy = (targetRect.top + targetRect.height / 2) - (sourceRect.top + sourceRect.height / 2);
+            const distance = Math.sqrt(dx * dx + dy * dy);
+
+            // Build keyframes based on style
+            let keyframes;
+            let animationEasing = easing;
+
+            switch (style) {
+                case 'arc':
+                    keyframes = this._buildArcKeyframes(dx, dy, distance, arcHeight);
+                    // Arc uses linear easing because the curve is in the keyframes
+                    animationEasing = 'linear';
+                    break;
+                case 'hop':
+                    keyframes = this._buildHopKeyframes(dx, dy, distance, arcHeight);
+                    // Hop uses ease-out for natural landing feel
+                    animationEasing = 'cubic-bezier(0.33, 1, 0.68, 1)';
+                    break;
+                case 'slide':
+                default:
+                    keyframes = [
+                        { transform: 'translate(0, 0)' },
+                        { transform: `translate(${dx}px, ${dy}px)` }
+                    ];
+            }
 
+            // Animate
             if (this.element.animate) {
-                let animation = this.element.animate(keyframes, {
+                const animation = this.element.animate(keyframes, {
                     duration: duration,
-                    easing: 'ease',
-                    fill: 'none'
+                    easing: animationEasing,
+                    fill: 'forwards'
                 });
 
                 animation.onfinish = () => {
-                    if (!this.element) { console.debug(`[Piece] translate.onfinish: ${this.id} - element is null`); if (callback) callback(); return; }
-                    if (callback) callback();
+                    if (!this.element) {
+                        if (callback) callback();
+                        return;
+                    }
+
+                    // Cancel animation and move piece in DOM first
+                    animation.cancel();
                     if (this.element) this.element.style = '';
-                    console.debug(`[Piece] translate complete: ${this.id}`);
+
+                    // Callback moves piece to new square in DOM
+                    if (callback) callback();
+
+                    // Apply landing effect AFTER piece is in new position
+                    if (landingEffect !== 'none') {
+                        // Small delay to ensure DOM is updated
+                        requestAnimationFrame(() => {
+                            this._applyLandingEffect(landingEffect, landingDuration);
+                        });
+                    }
                 };
             } else {
-                this.element.style.transition = `transform ${duration}ms ease`;
+                // Fallback for browsers without Web Animations API
+                this.element.style.transition = `transform ${duration}ms ${animationEasing}`;
                 this.element.style.transform = `translate(${dx}px, ${dy}px)`;
+                setTimeout(() => {
+                    if (!this.element) {
+                        if (callback) callback();
+                        return;
+                    }
+                    if (this.element) this.element.style = '';
+                    if (callback) callback();
+
+                    // Apply landing effect after DOM update
+                    if (landingEffect !== 'none') {
+                        requestAnimationFrame(() => {
+                            this._applyLandingEffect(landingEffect, landingDuration);
+                        });
+                    }
+                }, duration);
+            }
+        }
+
+        /**
+         * Build arc-shaped keyframes (smooth parabolic curve)
+         * Uses many keyframes for fluid motion without relying on easing
+         * @private
+         */
+        _buildArcKeyframes(dx, dy, distance, arcHeight) {
+            const lift = distance * arcHeight;
+            const steps = 10;
+            const keyframes = [];
+
+            for (let i = 0; i <= steps; i++) {
+                const t = i / steps;
+                // Smooth easing for horizontal movement (Chessground-style cubic)
+                const easedT = t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+                // Parabolic arc for vertical lift: peaks at t=0.5
+                const arcT = 4 * t * (1 - t); // Parabola: 0 at t=0, 1 at t=0.5, 0 at t=1
+
+                const x = dx * easedT;
+                const y = dy * easedT - lift * arcT;
+
+                keyframes.push({
+                    transform: `translate(${x}px, ${y}px)`,
+                    offset: t
+                });
+            }
+            return keyframes;
+        }
+
+        /**
+         * Build hop-shaped keyframes (knight-like jump with subtle scale)
+         * More aggressive vertical movement, subtle scale for emphasis
+         * @private
+         */
+        _buildHopKeyframes(dx, dy, distance, arcHeight) {
+            const lift = distance * arcHeight * 1.2;
+            const steps = 12;
+            const keyframes = [];
+
+            for (let i = 0; i <= steps; i++) {
+                const t = i / steps;
+                // Chessground-style cubic easing for smooth acceleration/deceleration
+                const easedT = t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+                // Sharp parabolic hop - peaks earlier for snappier feel
+                const hopT = Math.sin(t * Math.PI); // Sine for smooth hop curve
+                // Subtle scale: peaks at 1.03 at the top of the hop
+                const scale = 1 + 0.03 * hopT;
+
+                const x = dx * easedT;
+                const y = dy * easedT - lift * hopT;
+
+                keyframes.push({
+                    transform: `translate(${x}px, ${y}px) scale(${scale})`,
+                    offset: t
+                });
+            }
+            return keyframes;
+        }
+
+        /**
+         * Translate using fade effect (smooth crossfade with scale)
+         * @private
+         */
+        _translateFade(to, duration, easing, landingEffect, landingDuration, callback) {
+            const halfDuration = duration / 2;
+            // Use smooth deceleration for fade
+            const fadeEasing = 'cubic-bezier(0.33, 1, 0.68, 1)';
+
+            // Fade out with subtle scale down
+            if (this.element.animate) {
+                const fadeOut = this.element.animate([
+                    { opacity: 1, transform: 'scale(1)' },
+                    { opacity: 0, transform: 'scale(0.95)' }
+                ], { duration: halfDuration, easing: fadeEasing, fill: 'forwards' });
+
+                fadeOut.onfinish = () => {
+                    if (!this.element) {
+                        if (callback) callback();
+                        return;
+                    }
+                    // Move instantly (hidden)
+                    fadeOut.cancel();
+                    this.element.style.opacity = '0';
+                    this.element.style.transform = 'scale(0.95)';
+
+                    // Let parent move the piece in DOM, then fade in
+                    if (callback) callback();
+
+                    // Fade in at new position with subtle scale up
+                    requestAnimationFrame(() => {
+                        if (!this.element) return;
+                        const fadeIn = this.element.animate([
+                            { opacity: 0, transform: 'scale(0.95)' },
+                            { opacity: 1, transform: 'scale(1)' }
+                        ], { duration: halfDuration, easing: fadeEasing, fill: 'forwards' });
+
+                        fadeIn.onfinish = () => {
+                            if (this.element) {
+                                fadeIn.cancel();
+                                this.element.style.opacity = '';
+                                this.element.style.transform = '';
+                                this._applyLandingEffect(landingEffect, landingDuration);
+                            }
+                        };
+                    });
+                };
+            } else {
+                // Fallback
+                this.element.style.transition = `opacity ${halfDuration}ms ease, transform ${halfDuration}ms ease`;
+                this.element.style.opacity = '0';
+                this.element.style.transform = 'scale(0.95)';
+                setTimeout(() => {
+                    if (callback) callback();
+                    if (this.element) {
+                        this.element.style.opacity = '1';
+                        this.element.style.transform = 'scale(1)';
+                        setTimeout(() => {
+                            if (this.element) this.element.style = '';
+                        }, halfDuration);
+                    }
+                }, halfDuration);
+            }
+        }
+
+        /**
+         * Apply landing effect after movement completes
+         * Uses spring-like overshoot easing for natural, connected feel
+         * @private
+         */
+        _applyLandingEffect(effect, duration, callback) {
+            if (!this.element || effect === 'none') {
+                if (callback) callback();
+                return;
+            }
+
+            let keyframes;
+            // Overshoot easing for spring-like natural feel
+            let effectEasing = 'cubic-bezier(0.34, 1.56, 0.64, 1)';
+
+            switch (effect) {
+                case 'bounce':
+                    // Subtle bounce using spring easing - single smooth bounce
+                    keyframes = [
+                        { transform: 'translateY(0)', offset: 0 },
+                        { transform: 'translateY(-5px)', offset: 0.4 },
+                        { transform: 'translateY(0)', offset: 1 }
+                    ];
+                    // Use ease-out for natural deceleration
+                    effectEasing = 'cubic-bezier(0.33, 1, 0.68, 1)';
+                    break;
+                case 'pulse':
+                    // Subtle scale pulse - less aggressive, more refined
+                    keyframes = [
+                        { transform: 'scale(1)', offset: 0 },
+                        { transform: 'scale(1.08)', offset: 0.5 },
+                        { transform: 'scale(1)', offset: 1 }
+                    ];
+                    break;
+                case 'settle':
+                    // Minimal settle - piece "clicks" into place
+                    keyframes = [
+                        { transform: 'scale(1.02)', offset: 0 },
+                        { transform: 'scale(1)', offset: 1 }
+                    ];
+                    effectEasing = 'cubic-bezier(0.33, 1, 0.68, 1)';
+                    break;
+                default:
+                    if (callback) callback();
+                    return;
+            }
+
+            if (this.element.animate) {
+                const animation = this.element.animate(keyframes, {
+                    duration: duration,
+                    easing: effectEasing,
+                    fill: 'forwards'
+                });
+                animation.onfinish = () => {
+                    if (this.element) animation.cancel();
+                    if (callback) callback();
+                };
+            } else {
                 if (callback) callback();
-                if (this.element) this.element.style = '';
-                console.debug(`[Piece] translate complete (no animate): ${this.id}`);
             }
         }
 
@@ -1866,9 +2589,9 @@ var ChessboardLib = (function (exports) {
         }
 
         putPiece(piece) {
-            // If there's already a piece, remove it first, but preserve if moving
+            // If there's already a piece, destroy it to avoid orphaned DOM elements
             if (this.piece) {
-                this.removePiece(true);
+                this.removePiece(false);
             }
             this.piece = piece;
             if (piece && piece.element) {
@@ -1980,7 +2703,7 @@ var ChessboardLib = (function (exports) {
         }
 
         getColor() {
-            return this.piece.getColor();
+            return this.piece ? this.piece.getColor() : null;
         }
 
         check() {
@@ -4638,25 +5361,11 @@ var ChessboardLib = (function (exports) {
                 to: move.to.id
             };
             
-            console.log('executeMove - move.promotion:', move.promotion);
-            console.log('executeMove - move.hasPromotion():', move.hasPromotion());
-            
             if (move.hasPromotion()) {
                 moveOptions.promotion = move.promotion;
             }
-            
-            console.log('executeMove - moveOptions:', moveOptions);
-            
-            const result = game.move(moveOptions);
-            console.log('executeMove - result:', result);
-            
-            // Check what's actually on the board after the move
-            if (result) {
-                const pieceOnDestination = game.get(move.to.id);
-                console.log('executeMove - piece on destination after move:', pieceOnDestination);
-            }
-            
-            return result;
+
+            return game.move(moveOptions);
         }
 
         /**
@@ -4666,27 +5375,19 @@ var ChessboardLib = (function (exports) {
          */
         requiresPromotion(move) {
             const moveKey = `${move.from.id}->${move.to.id}`;
-            console.log('Checking if move requires promotion:', moveKey);
-            
-            // Get detailed stack trace
-            const stack = new Error().stack.split('\n');
-            console.log('Call stack:', stack[1]);
-            console.log('Caller:', stack[2]);
-            console.log('Caller 2:', stack[3]);
-            console.log('Caller 3:', stack[4]);
-            
-            // Track recently processed moves to prevent processing the same move multiple times
+
+            // Track recently processed moves - return cached result for duplicates
             const now = Date.now();
-            if (this._recentMoves.has(moveKey)) {
-                console.log('Move recently processed, skipping duplicate check');
-                return false; // Conservative: assume no promotion needed for duplicates
+            if (this._recentMoves.has(moveKey) &&
+                this._lastPromotionCheck === moveKey &&
+                this._lastPromotionResult !== null) {
+                return this._lastPromotionResult;
             }
-            
+
             // Debounce identical promotion checks within 100ms
-            if (this._lastPromotionCheck === moveKey && 
+            if (this._lastPromotionCheck === moveKey &&
                 this._lastPromotionResult !== null &&
                 now - this._lastPromotionTime < 100) {
-                console.log('Using cached promotion result:', this._lastPromotionResult);
                 return this._lastPromotionResult;
             }
             
@@ -4727,53 +5428,41 @@ var ChessboardLib = (function (exports) {
          */
         _doRequiresPromotion(move) {
             if (!this.config.onlyLegalMoves) {
-                console.log('Not in legal moves mode, no promotion required');
                 return false;
             }
-            
+
             const game = this.positionService.getGame();
             if (!game) {
-                console.log('No game instance available');
                 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;
             }
-            
+
             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 - promotion required');
-            
-            // Additional validation: check if the pawn can actually reach this square
+
+            // Validate pawn move
             if (!this._isPawnMoveValid(move.from, move.to, piece.color)) {
-                console.log('Pawn move not valid, no promotion required');
                 return false;
             }
-            
-            // If we get here, it's a pawn move to the promotion rank
-            // Check if it's a legal move by using the game's moves() method
+
+            // Check if it's a legal move
             const legalMoves = game.moves({ square: move.from.id, verbose: true });
             const matchingMove = legalMoves.find(m => m.to === move.to.id);
-            
+
             if (!matchingMove) {
-                console.log('Move not in legal moves list, no promotion required');
                 return false;
             }
-            
-            // If the legal move has a promotion flag or is to a promotion rank, promotion is required
-            const requiresPromotion = matchingMove.flags.includes('p') || 
-                                    (piece.color === 'w' && targetRank === 8) || 
-                                    (piece.color === 'b' && targetRank === 1);
-            
-            console.log('Promotion required:', requiresPromotion);
-            return requiresPromotion;
+
+            // Promotion is required if move has promotion flag or reaches promotion rank
+            return matchingMove.flags.includes('p') ||
+                   (piece.color === 'w' && targetRank === 8) ||
+                   (piece.color === 'b' && targetRank === 1);
         }
 
         /**
@@ -4789,43 +5478,34 @@ var ChessboardLib = (function (exports) {
             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)
+
+            // Pawn can only move 1-2 ranks
             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 (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;
                 }
             }
-            
-            // Pawn can only move to adjacent files (diagonal capture) or same file (forward move)
+
+            // Pawn can only move to adjacent files or same file
             if (fileDiff > 1) {
-                console.log('Invalid: Pawn cannot move more than 1 file');
                 return false;
             }
-            
-            console.log('Pawn move validation passed');
+
             return true;
         }
 
@@ -4866,24 +5546,17 @@ var ChessboardLib = (function (exports) {
          * @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);
                 }
             });
             
@@ -4910,40 +5583,28 @@ var ChessboardLib = (function (exports) {
         _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
             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;
         }
 
@@ -5179,50 +5840,61 @@ var ChessboardLib = (function (exports) {
                 piece.setDrag(dragFunction(square, piece));
             }
 
-            if (fade && this.config.fadeTime > 0) {
-                piece.fadeIn(
-                    this.config.fadeTime,
-                    this.config.fadeAnimation,
-                    this._getTransitionTimingFunction(),
-                    callback
-                );
+            if (fade) {
+                const appearanceStyle = this.config.appearanceStyle || 'fade';
+                const duration = this.config.appearanceTime || this.config.fadeTime || 200;
+
+                if (duration > 0 && appearanceStyle !== 'instant') {
+                    piece.appearAnimate(appearanceStyle, duration, () => {
+                        piece.visible();
+                        if (callback) callback();
+                    });
+                } else {
+                    piece.visible();
+                    if (callback) callback();
+                }
             } else {
+                piece.visible();
                 if (callback) callback();
             }
-
-            piece.visible();
         }
 
         /**
-         * Removes a piece from a square with optional fade-out animation
+         * Removes a piece from a square with configurable capture animation
          * @param {Square} square - Source square
-         * @param {boolean} [fade=true] - Whether to fade out the piece
+         * @param {boolean} [animate=true] - Whether to animate the removal
          * @param {Function} [callback] - Callback when animation completes
          * @returns {Piece} The removed piece
          * @throws {PieceError} When square has no piece to remove
          */
-        removePieceFromSquare(square, fade = true, callback) {
+        removePieceFromSquare(square, animate = true, callback) {
             console.debug(`[PieceService] removePieceFromSquare: ${square.id}`);
             square.check();
 
             const piece = square.piece;
             if (!piece) {
                 if (callback) callback();
-                throw new PieceError(ERROR_MESSAGES.square_no_piece, null, square.getId());
+                return null;
             }
 
-            if (fade && this.config.fadeTime > 0) {
-                piece.fadeOut(
-                    this.config.fadeTime,
-                    this.config.fadeAnimation,
-                    this._getTransitionTimingFunction(),
-                    callback
-                );
+            // Always remove piece reference synchronously to prevent stale state
+            // when a new update starts before the animation completes
+            square.piece = null;
+
+            const captureStyle = this.config.captureStyle || 'fade';
+            const duration = this.config.captureTime || this.config.fadeTime || 200;
+
+            if (animate && duration > 0) {
+                // Animate visual element, then destroy
+                piece.captureAnimate(captureStyle, duration, () => {
+                    piece.destroy();
+                    if (callback) callback();
+                });
             } else {
+                piece.destroy();
                 if (callback) callback();
             }
 
-            square.removePiece();
             return piece;
         }
 
@@ -5241,12 +5913,22 @@ var ChessboardLib = (function (exports) {
                 return;
             }
 
+            // Build movement options from config
+            const moveOptions = {
+                style: this.config.moveStyle || 'slide',
+                easing: this.config.moveEasing || this.config.moveAnimation || 'ease',
+                arcHeight: this.config.moveArcHeight || 0.3,
+                landingEffect: this.config.landingEffect || 'none',
+                landingDuration: this.config.landingDuration || 150
+            };
+
             piece.translate(
                 targetSquare,
                 duration,
                 this._getTransitionTimingFunction(),
                 this.config.moveAnimation,
-                callback
+                callback,
+                moveOptions
             );
         }
 
@@ -5260,8 +5942,8 @@ var ChessboardLib = (function (exports) {
          */
         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 (!move.piece || !move.piece.element) {
+                console.warn('PieceService.translatePiece: move.piece or element is null, skipping translation');
                 if (callback) callback();
                 return;
             }
@@ -5273,6 +5955,12 @@ var ChessboardLib = (function (exports) {
             }
 
             const changeSquareCallback = () => {
+                // If piece element was destroyed (e.g., by a newer update), skip
+                if (!move.piece.element || !move.piece.element.parentNode) {
+                    if (callback) callback();
+                    return;
+                }
+
                 // 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
@@ -7651,7 +8339,8 @@ var ChessboardLib = (function (exports) {
                 this._handleConstructorError(error);
             }
             this._undoneMoves = [];
-            this._updateBoardPieces(true, true); // Forza popolamento DOM subito
+            this._destroyed = false;
+            this._animationTimeouts = [];
         }
 
         /**
@@ -7763,6 +8452,11 @@ var ChessboardLib = (function (exports) {
             this._buildSquares();
             this._addListeners();
             this._updateBoardPieces(true, true); // Initial position load
+
+            // Apply flipped class if initial orientation is black
+            if (this.coordinateService.getOrientation() === 'b' && this.boardService.element) {
+                this.boardService.element.classList.add('flipped');
+            }
         }
 
         /**
@@ -7791,9 +8485,7 @@ var ChessboardLib = (function (exports) {
          * Best practice: always remove squares (destroy JS/DOM) before clearing the board container.
          */
         _buildBoard() {
-            console.log('CHIAMATO: _buildBoard');
             if (this._isUndoRedo) {
-                console.log('SKIP _buildBoard per undo/redo');
                 return;
             }
             // Forza la pulizia completa del contenitore board (DOM)
@@ -7813,9 +8505,7 @@ var ChessboardLib = (function (exports) {
          * @private
          */
         _buildSquares() {
-            console.log('CHIAMATO: _buildSquares');
             if (this._isUndoRedo) {
-                console.log('SKIP _buildSquares per undo/redo');
                 return;
             }
             if (this.boardService && this.boardService.removeSquares) {
@@ -8028,6 +8718,14 @@ var ChessboardLib = (function (exports) {
             const isEnPassant = this.moveService.isEnPassant(gameMove);
 
             if (animate && move.from.piece) {
+                // For simultaneous castle, start rook animation alongside the king
+                const isSimultaneousCastle = isCastle && this.config.animationStyle === 'simultaneous';
+                if (isSimultaneousCastle) {
+                    setTimeout(() => {
+                        this._handleCastleMove(gameMove, true);
+                    }, this.config.simultaneousAnimationDelay);
+                }
+
                 this.pieceService.translatePiece(
                     move,
                     !!move.to.piece, // was there a capture?
@@ -8035,24 +8733,22 @@ var ChessboardLib = (function (exports) {
                     this._createDragFunction.bind(this),
                     () => {
                         // After the main piece animation completes...
-                        if (isCastle) {
+                        // For sequential castle, animate rook AFTER king finishes
+                        // For simultaneous, rook was already animated above - don't animate again
+                        if (isCastle && !isSimultaneousCastle) {
                             this._handleSpecialMoveAnimation(gameMove);
                         } else if (isEnPassant) {
                             this._handleSpecialMoveAnimation(gameMove);
                         }
                         // Notify user that the move is fully complete
                         this.config.onMoveEnd(gameMove);
-                        // A final sync to ensure board is perfect
-                        this._updateBoardPieces(false);
+                        // For simultaneous castle, the rook callback will handle the final sync
+                        // to avoid interfering with the ongoing rook animation
+                        if (!isSimultaneousCastle) {
+                            this._updateBoardPieces(false);
+                        }
                     }
                 );
-
-                // For simultaneous castle, animate the rook alongside the king
-                if (isCastle && this.config.animationStyle === 'simultaneous') {
-                    setTimeout(() => {
-                        this._handleCastleMove(gameMove, true);
-                    }, this.config.simultaneousAnimationDelay);
-                }
             } else {
                 // If not animating, handle special moves immediately and update the board
                 if (isCastle) {
@@ -8105,12 +8801,9 @@ var ChessboardLib = (function (exports) {
             const rookToSquare = this.boardService.getSquare(rookMove.to);
 
             if (!rookFromSquare || !rookToSquare || !rookFromSquare.piece) {
-                console.warn('Castle rook move failed - squares or piece not found');
                 return;
             }
 
-            console.log(`Castle: moving rook from ${rookMove.from} to ${rookMove.to}`);
-
             if (animate) {
                 // Always use translatePiece for smooth sliding animation
                 const rookPiece = rookFromSquare.piece;
@@ -8142,12 +8835,9 @@ var ChessboardLib = (function (exports) {
 
             const capturedSquareObj = this.boardService.getSquare(capturedSquare);
             if (!capturedSquareObj || !capturedSquareObj.piece) {
-                console.warn('En passant captured square not found or empty');
                 return;
             }
 
-            console.log(`En passant: removing captured pawn from ${capturedSquare}`);
-
             if (animate) {
                 // Animate the captured pawn removal
                 this.pieceService.removePieceFromSquare(capturedSquareObj, true);
@@ -8168,10 +8858,9 @@ var ChessboardLib = (function (exports) {
          * @param {boolean} [isPositionLoad=false] - Whether this is a position load
          */
         _updateBoardPieces(animation = false, isPositionLoad = false) {
-            console.log('CHIAMATO: _updateBoardPieces', { animation, isPositionLoad, isUndoRedo: this._isUndoRedo });
+            if (this._destroyed) return;
             // Check if services are available
             if (!this.positionService || !this.moveService || !this.eventService) {
-                console.log('Cannot update board pieces - services not available');
                 return;
             }
 
@@ -8234,33 +8923,24 @@ var ChessboardLib = (function (exports) {
          * @param {boolean} [isPositionLoad=false] - Whether this is a position load (affects delay)
          */
         _doUpdateBoardPieces(animation = false, isPositionLoad = false) {
+            if (this._destroyed) return;
             // Skip update if we're in the middle of a promotion
             if (this._isPromoting) {
-                console.log('Skipping board update during promotion');
                 return;
             }
 
             // Check if services are available
             if (!this.positionService || !this.positionService.getGame()) {
-                console.log('Cannot update board pieces - position service not available');
                 return;
             }
 
             const squares = this.boardService.getAllSquares();
             const gameStateBefore = this.positionService.getGame().fen();
-
-            console.log('_doUpdateBoardPieces - current FEN:', gameStateBefore);
-            console.log('_doUpdateBoardPieces - animation:', animation, 'style:', this.config.animationStyle, 'isPositionLoad:', isPositionLoad);
-
-            // Determine which animation style to use
             const useSimultaneous = this.config.animationStyle === 'simultaneous';
-            console.log('_doUpdateBoardPieces - useSimultaneous:', useSimultaneous);
 
             if (useSimultaneous) {
-                console.log('Using simultaneous animation');
-                this._doSimultaneousUpdate(squares, gameStateBefore, isPositionLoad);
+                this._doSimultaneousUpdate(squares, gameStateBefore, isPositionLoad, animation);
             } else {
-                console.log('Using sequential animation');
                 this._doSequentialUpdate(squares, gameStateBefore, animation);
             }
         }
@@ -8273,7 +8953,23 @@ var ChessboardLib = (function (exports) {
          * @param {boolean} animation - Whether to animate
          */
         _doSequentialUpdate(squares, gameStateBefore, animation) {
-            // Mappa: squareId -> expectedPieceId
+            // Cancel running animations and clean orphaned elements
+            Object.values(squares).forEach(square => {
+                const imgs = square.element.querySelectorAll('img.piece');
+                imgs.forEach(img => {
+                    if (img.getAnimations) {
+                        img.getAnimations().forEach(anim => anim.cancel());
+                    }
+                    if (!square.piece || img !== square.piece.element) {
+                        img.remove();
+                    }
+                });
+                if (square.piece && square.piece.element) {
+                    square.piece.element.style = '';
+                    square.piece.element.style.opacity = '1';
+                }
+            });
+
             const expectedMap = {};
             Object.values(squares).forEach(square => {
                 expectedMap[square.id] = this.positionService.getGamePieceId(square.id);
@@ -8289,12 +8985,13 @@ var ChessboardLib = (function (exports) {
                     return;
                 }
 
-                // Se c'è un pezzo attuale ma non è quello atteso, rimuovilo
+                // Remove current piece if it doesn't match expected
                 if (currentPiece && currentPieceId !== expectedPieceId) {
-                    this.pieceService.removePieceFromSquare(square, animation);
+                    // Always remove synchronously to avoid race condition with addition
+                    this.pieceService.removePieceFromSquare(square, false);
                 }
 
-                // Se c'è un pezzo atteso ma non è quello attuale, aggiungilo
+                // Add expected piece if it doesn't match current
                 if (expectedPieceId && currentPieceId !== expectedPieceId) {
                     const newPiece = this.pieceService.convertPiece(expectedPieceId);
                     this.pieceService.addPieceOnSquare(
@@ -8319,9 +9016,43 @@ var ChessboardLib = (function (exports) {
          * @param {Object} squares - All squares
          * @param {string} gameStateBefore - Game state before update
          * @param {boolean} [isPositionLoad=false] - Whether this is a position load
+         * @param {boolean} [animation=true] - Whether to animate
          */
-        _doSimultaneousUpdate(squares, gameStateBefore, isPositionLoad = false) {
-            // Matching greedy per distanza minima, robusto
+        _doSimultaneousUpdate(squares, gameStateBefore, isPositionLoad = false, animation = true) {
+            // Increment generation to invalidate stale animation callbacks
+            this._updateGeneration = (this._updateGeneration || 0) + 1;
+            const generation = this._updateGeneration;
+
+            // Cancel pending animation timeouts from previous update
+            if (this._animationTimeouts) {
+                this._animationTimeouts.forEach(tid => clearTimeout(tid));
+                this._animationTimeouts = [];
+            }
+
+            // Cancel all running animations and force-sync DOM state
+            Object.values(squares).forEach(square => {
+                const imgs = square.element.querySelectorAll('img.piece');
+                imgs.forEach(img => {
+                    // Cancel all Web Animations on this element so onfinish callbacks don't fire
+                    if (img.getAnimations) {
+                        img.getAnimations().forEach(anim => anim.cancel());
+                    }
+                    // Remove orphaned images not matching current piece
+                    if (!square.piece || img !== square.piece.element) {
+                        img.remove();
+                    }
+                });
+                // Reset current piece element to clean state (remove animation artifacts)
+                if (square.piece && square.piece.element) {
+                    square.piece.element.style = '';
+                    square.piece.element.style.opacity = '1';
+                    // Ensure element is attached to correct square
+                    if (!square.element.contains(square.piece.element)) {
+                        square.element.appendChild(square.piece.element);
+                    }
+                }
+            });
+
             const currentMap = {};
             const expectedMap = {};
 
@@ -8347,35 +9078,16 @@ var ChessboardLib = (function (exports) {
             const animationDelay = isPositionLoad ? 0 : this.config.simultaneousAnimationDelay;
             let animationIndex = 0;
 
-            Object.keys(expectedMap).forEach(key => {
-                totalAnimations += Math.max((currentMap[key] || []).length, expectedMap[key].length);
-            });
-
-            if (totalAnimations === 0) {
-                this._addListeners();
-                const gameStateAfter = this.positionService.getGame().fen();
-                if (gameStateBefore !== gameStateAfter) {
-                    this.config.onChange(gameStateAfter);
-                }
-                return;
-            }
-
-            const onAnimationComplete = () => {
-                animationsCompleted++;
-                if (animationsCompleted === totalAnimations) {
-                    this._addListeners();
-                    const gameStateAfter = this.positionService.getGame().fen();
-                    if (gameStateBefore !== gameStateAfter) {
-                        this.config.onChange(gameStateAfter);
-                    }
-                }
-            };
+            // First pass: compute matching for all piece types
+            const allRemovals = [];
+            const allAdditions = [];
+            const allMoves = [];
 
             Object.keys(expectedMap).forEach(key => {
                 const fromList = (currentMap[key] || []).slice();
                 const toList = expectedMap[key].slice();
 
-                // 1. Costruisci matrice delle distanze
+                // Build distance matrix
                 const distances = [];
                 for (let i = 0; i < fromList.length; i++) {
                     distances[i] = [];
@@ -8385,10 +9097,9 @@ var ChessboardLib = (function (exports) {
                     }
                 }
 
-                // 2. Matching greedy: abbina i più vicini
+                // Greedy matching: pair closest pieces
                 const fromMatched = new Array(fromList.length).fill(false);
                 const toMatched = new Array(toList.length).fill(false);
-                const moves = [];
 
                 while (true) {
                     let minDist = Infinity, minI = -1, minJ = -1;
@@ -8404,58 +9115,140 @@ var ChessboardLib = (function (exports) {
                         }
                     }
                     if (minI === -1 || minJ === -1) break;
-                    // Se la posizione è la stessa, non fare nulla (pezzo unchanged)
+                    fromMatched[minI] = true;
+                    toMatched[minJ] = true;
+                    // Skip unchanged pieces (same square)
                     if (fromList[minI].square === toList[minJ].square) {
-                        fromMatched[minI] = true;
-                        toMatched[minJ] = true;
                         continue;
                     }
-                    // Altrimenti, sposta il pezzo
-                    moves.push({ from: fromList[minI].square, to: toList[minJ].square, piece: fromList[minI].square.piece });
-                    fromMatched[minI] = true;
-                    toMatched[minJ] = true;
+                    allMoves.push({ from: fromList[minI].square, to: toList[minJ].square, piece: fromList[minI].square.piece });
+                }
+
+                // Collect unmatched current pieces (to remove)
+                for (let i = 0; i < fromList.length; i++) {
+                    if (!fromMatched[i]) {
+                        allRemovals.push(fromList[i].square);
+                    }
+                }
+
+                // Collect unmatched expected pieces (to add)
+                for (let j = 0; j < toList.length; j++) {
+                    if (!toMatched[j]) {
+                        allAdditions.push({ square: toList[j].square, key });
+                    }
+                }
+            });
+
+            // Also count removals for pieces whose type doesn't exist in expectedMap
+            Object.keys(currentMap).forEach(key => {
+                if (!expectedMap[key]) {
+                    currentMap[key].forEach(entry => {
+                        allRemovals.push(entry.square);
+                    });
+                }
+            });
+
+            // Count only actual animations
+            totalAnimations = allRemovals.length + allAdditions.length + allMoves.length;
+
+            if (totalAnimations === 0) {
+                this._addListeners();
+                const gameStateAfter = this.positionService.getGame().fen();
+                if (gameStateBefore !== gameStateAfter) {
+                    this.config.onChange(gameStateAfter);
                 }
+                return;
+            }
 
-                // 3. Rimuovi i pezzi non abbinati (presenti solo in fromList)
-                for (let i = 0; i < fromList.length; i++) {
-                    if (!fromMatched[i]) {
-                        setTimeout(() => {
-                            this.pieceService.removePieceFromSquare(fromList[i].square, true, onAnimationComplete);
-                        }, animationIndex * animationDelay);
-                        animationIndex++;
-                    }
+            // Detach moving pieces from source squares BEFORE any removals/additions
+            // This prevents additions to a move's source square from destroying the piece
+            allMoves.forEach(move => {
+                if (move.from.piece === move.piece) {
+                    move.from.removePiece(true); // preserve element, just detach reference
                 }
+            });
 
-                // 4. Aggiungi i pezzi non abbinati (presenti solo in toList)
-                for (let j = 0; j < toList.length; j++) {
-                    if (!toMatched[j]) {
-                        setTimeout(() => {
-                            const newPiece = this.pieceService.convertPiece(key);
-                            this.pieceService.addPieceOnSquare(
-                                toList[j].square,
-                                newPiece,
-                                true,
-                                this._createDragFunction.bind(this),
-                                onAnimationComplete
-                            );
-                        }, animationIndex * animationDelay);
-                        animationIndex++;
+            // No animation: apply all changes synchronously
+            if (!animation) {
+                allRemovals.forEach(square => {
+                    this.pieceService.removePieceFromSquare(square, false);
+                });
+                allMoves.forEach(move => {
+                    this.pieceService.translatePiece(
+                        move, false, false, this._createDragFunction.bind(this)
+                    );
+                });
+                allAdditions.forEach(({ square, key }) => {
+                    const newPiece = this.pieceService.convertPiece(key);
+                    this.pieceService.addPieceOnSquare(
+                        square, newPiece, false, this._createDragFunction.bind(this)
+                    );
+                });
+                this._addListeners();
+                const gameStateAfter = this.positionService.getGame().fen();
+                if (gameStateBefore !== gameStateAfter) {
+                    this.config.onChange(gameStateAfter);
+                }
+                return;
+            }
+
+            // Animated path
+            if (!this._animationTimeouts) this._animationTimeouts = [];
+
+            const onAnimationComplete = () => {
+                // Ignore callbacks from stale/destroyed boards
+                if (this._destroyed || this._updateGeneration !== generation) return;
+                animationsCompleted++;
+                if (animationsCompleted === totalAnimations) {
+                    this._addListeners();
+                    const gameStateAfter = this.positionService.getGame().fen();
+                    if (gameStateBefore !== gameStateAfter) {
+                        this.config.onChange(gameStateAfter);
                     }
                 }
+            };
 
-                // 5. Anima i movimenti
-                moves.forEach(move => {
-                    setTimeout(() => {
-                        this.pieceService.translatePiece(
-                            move,
-                            false,
-                            true,
-                            this._createDragFunction.bind(this),
-                            onAnimationComplete
-                        );
-                    }, animationIndex * animationDelay);
-                    animationIndex++;
-                });
+            // Dispatch moves first (pieces already detached from source)
+            allMoves.forEach(move => {
+                const tid = setTimeout(() => {
+                    if (this._destroyed || this._updateGeneration !== generation) return;
+                    this.pieceService.translatePiece(
+                        move,
+                        false,
+                        true,
+                        this._createDragFunction.bind(this),
+                        onAnimationComplete
+                    );
+                }, animationIndex * animationDelay);
+                this._animationTimeouts.push(tid);
+                animationIndex++;
+            });
+
+            // Dispatch removals
+            allRemovals.forEach(square => {
+                const tid = setTimeout(() => {
+                    if (this._destroyed || this._updateGeneration !== generation) return;
+                    this.pieceService.removePieceFromSquare(square, true, onAnimationComplete);
+                }, animationIndex * animationDelay);
+                this._animationTimeouts.push(tid);
+                animationIndex++;
+            });
+
+            // Dispatch additions
+            allAdditions.forEach(({ square, key }) => {
+                const tid = setTimeout(() => {
+                    if (this._destroyed || this._updateGeneration !== generation) return;
+                    const newPiece = this.pieceService.convertPiece(key);
+                    this.pieceService.addPieceOnSquare(
+                        square,
+                        newPiece,
+                        true,
+                        this._createDragFunction.bind(this),
+                        onAnimationComplete
+                    );
+                }, animationIndex * animationDelay);
+                this._animationTimeouts.push(tid);
+                animationIndex++;
             });
         }
 
@@ -8483,10 +9276,6 @@ var ChessboardLib = (function (exports) {
                 }
             });
 
-            console.log('Position Analysis:');
-            console.log('Current pieces:', Array.from(currentPieces.entries()));
-            console.log('Expected pieces:', Array.from(expectedPieces.entries()));
-
             // Identify different types of changes
             const moves = []; // Pieces that can slide to new positions
             const removes = []; // Pieces that need to be removed
@@ -8500,8 +9289,6 @@ var ChessboardLib = (function (exports) {
                 const expectedPieceId = expectedPieces.get(square);
 
                 if (currentPieceId === expectedPieceId) {
-                    // Same piece type on same square - no movement needed
-                    console.log(`UNCHANGED: ${currentPieceId} stays on ${square}`);
                     unchanged.push({
                         piece: currentPieceId,
                         square: square
@@ -8523,7 +9310,6 @@ var ChessboardLib = (function (exports) {
 
                 if (availableDestination) {
                     const [toSquare, expectedId] = availableDestination;
-                    console.log(`MOVE: ${currentPieceId} from ${fromSquare} to ${toSquare}`);
                     moves.push({
                         piece: currentPieceId,
                         from: fromSquare,
@@ -8533,8 +9319,6 @@ var ChessboardLib = (function (exports) {
                     });
                     processedSquares.add(toSquare);
                 } else {
-                    // This piece needs to be removed
-                    console.log(`REMOVE: ${currentPieceId} from ${fromSquare}`);
                     removes.push({
                         piece: currentPieceId,
                         square: fromSquare,
@@ -8546,7 +9330,6 @@ var ChessboardLib = (function (exports) {
             // Third pass: handle pieces that need to be added
             expectedPieces.forEach((expectedPieceId, toSquare) => {
                 if (!processedSquares.has(toSquare)) {
-                    console.log(`ADD: ${expectedPieceId} to ${toSquare}`);
                     adds.push({
                         piece: expectedPieceId,
                         square: toSquare,
@@ -8572,26 +9355,13 @@ var ChessboardLib = (function (exports) {
          * @param {boolean} [isPositionLoad=false] - Whether this is a position load
          */
         _executeSimultaneousChanges(changeAnalysis, gameStateBefore, isPositionLoad = false) {
-            const { moves, removes, adds, unchanged } = changeAnalysis;
-
-            console.log(`Position changes analysis:`, {
-                moves: moves.length,
-                removes: removes.length,
-                adds: adds.length,
-                unchanged: unchanged.length
-            });
-
-            // Log unchanged pieces for debugging
-            if (unchanged.length > 0) {
-                console.log('Pieces staying in place:', unchanged.map(u => `${u.piece} on ${u.square}`));
-            }
+            const { moves, removes, adds } = changeAnalysis;
 
             let animationsCompleted = 0;
             const totalAnimations = moves.length + removes.length + adds.length;
 
             // If no animations are needed, complete immediately
             if (totalAnimations === 0) {
-                console.log('No animations needed, completing immediately');
                 this._addListeners();
 
                 // Trigger change event if position changed
@@ -8604,9 +9374,7 @@ var ChessboardLib = (function (exports) {
 
             const onAnimationComplete = () => {
                 animationsCompleted++;
-                console.log(`Animation completed: ${animationsCompleted}/${totalAnimations}`);
                 if (animationsCompleted === totalAnimations) {
-                    console.log('All simultaneous animations completed');
                     this._addListeners();
 
                     // Trigger change event if position changed
@@ -8617,45 +9385,33 @@ var ChessboardLib = (function (exports) {
                 }
             };
 
-            // Determine delay: 0 for position loads, configured delay for normal moves
             const animationDelay = isPositionLoad ? 0 : this.config.simultaneousAnimationDelay;
-            console.log(`Using animation delay: ${animationDelay}ms (position load: ${isPositionLoad})`);
-
             let animationIndex = 0;
 
-            // Process moves (pieces sliding to new positions)
+            // Process moves
             moves.forEach(move => {
                 const delay = animationIndex * animationDelay;
-                console.log(`Scheduling move ${move.piece} from ${move.from} to ${move.to} with delay ${delay}ms`);
-
                 setTimeout(() => {
                     this._animatePieceMove(move, onAnimationComplete);
                 }, delay);
-
                 animationIndex++;
             });
 
-            // Process removes (pieces disappearing)
+            // Process removes
             removes.forEach(remove => {
                 const delay = animationIndex * animationDelay;
-                console.log(`Scheduling removal of ${remove.piece} from ${remove.square} with delay ${delay}ms`);
-
                 setTimeout(() => {
                     this._animatePieceRemoval(remove, onAnimationComplete);
                 }, delay);
-
                 animationIndex++;
             });
 
-            // Process adds (pieces appearing)
+            // Process adds
             adds.forEach(add => {
                 const delay = animationIndex * animationDelay;
-                console.log(`Scheduling addition of ${add.piece} to ${add.square} with delay ${delay}ms`);
-
                 setTimeout(() => {
                     this._animatePieceAddition(add, onAnimationComplete);
                 }, delay);
-
                 animationIndex++;
             });
         }
@@ -8671,23 +9427,16 @@ var ChessboardLib = (function (exports) {
             const piece = fromSquare.piece;
 
             if (!piece) {
-                console.warn(`No piece found on ${move.from} for move animation`);
                 onComplete();
                 return;
             }
 
-            console.log(`Animating piece move: ${move.piece} from ${move.from} to ${move.to}`);
-
-            // Use translatePiece for smooth sliding animation
             this.pieceService.translatePiece(
                 { from: fromSquare, to: toSquare, piece: piece },
-                false, // Assume no capture for now
-                true, // Always animate
+                false,
+                true,
                 this._createDragFunction.bind(this),
-                () => {
-                    console.log(`Piece move animation completed: ${move.piece} to ${move.to}`);
-                    onComplete();
-                }
+                onComplete
             );
         }
 
@@ -8698,12 +9447,7 @@ var ChessboardLib = (function (exports) {
          * @param {Function} onComplete - Callback when animation completes
          */
         _animatePieceRemoval(remove, onComplete) {
-            console.log(`Animating piece removal: ${remove.piece} from ${remove.square}`);
-
-            this.pieceService.removePieceFromSquare(remove.squareObj, true, () => {
-                console.log(`Piece removal animation completed: ${remove.piece} from ${remove.square}`);
-                onComplete();
-            });
+            this.pieceService.removePieceFromSquare(remove.squareObj, true, onComplete);
         }
 
         /**
@@ -8713,18 +9457,13 @@ var ChessboardLib = (function (exports) {
          * @param {Function} onComplete - Callback when animation completes
          */
         _animatePieceAddition(add, onComplete) {
-            console.log(`Animating piece addition: ${add.piece} to ${add.square}`);
-
             const newPiece = this.pieceService.convertPiece(add.piece);
             this.pieceService.addPieceOnSquare(
                 add.squareObj,
                 newPiece,
                 true,
                 this._createDragFunction.bind(this),
-                () => {
-                    console.log(`Piece addition animation completed: ${add.piece} to ${add.square}`);
-                    onComplete();
-                }
+                onComplete
             );
         }
 
@@ -8824,7 +9563,7 @@ var ChessboardLib = (function (exports) {
             const animate = opts.animate !== undefined ? opts.animate : true;
             // Use the default starting position from config or fallback
             const startPosition = this.config && this.config.position ? this.config.position : 'start';
-            this._updateBoardPieces(animate);
+            // setPosition already calls _updateBoardPieces, don't call it twice
             return this.setPosition(startPosition, { animate });
         }
         /**
@@ -8839,10 +9578,13 @@ var ChessboardLib = (function (exports) {
                 return false;
             }
             if (this._clearVisualState) this._clearVisualState();
+
+            // Clear the game state
             this.positionService.getGame().clear();
-            if (this._updateBoardPieces) {
-                this._updateBoardPieces(animate, true);
-            }
+
+            // Let _updateBoardPieces handle removal (no manual loop to avoid race conditions)
+            this._updateBoardPieces(animate, true);
+
             return true;
         }
 
@@ -8879,6 +9621,32 @@ var ChessboardLib = (function (exports) {
             }
             return false;
         }
+        /**
+         * Move a piece from one square to another
+         * @param {string} moveStr - Move in format 'e2e4' or 'e7e8q' (with promotion)
+         * @param {Object} [opts]
+         * @param {boolean} [opts.animate=true]
+         * @returns {Object|boolean} Move result or false if invalid
+         */
+        movePiece(moveStr, opts = {}) {
+            const animate = opts.animate !== false;
+            if (typeof moveStr !== 'string' || moveStr.length < 4) {
+                return false;
+            }
+            const from = moveStr.slice(0, 2);
+            const to = moveStr.slice(2, 4);
+            const promotion = moveStr.length > 4 ? moveStr[4].toLowerCase() : undefined;
+
+            const moveObj = { from, to };
+            if (promotion) moveObj.promotion = promotion;
+
+            const result = this.positionService.getGame().move(moveObj);
+            if (result) {
+                this._updateBoardPieces(animate);
+            }
+            return result || false;
+        }
+
         /**
          * Get legal moves for a square
          * @param {string} square
@@ -8893,10 +9661,10 @@ var ChessboardLib = (function (exports) {
          * @returns {string|null}
          */
         getPiece(square) {
-            // Restituisce sempre 'wq' (colore prima, tipo dopo, lowercase) o null
-            const sq = this.boardService.getSquare(square);
-            if (!sq) return null;
-            const piece = sq.piece;
+            // Use game state as source of truth
+            // Returns piece in format 'wq' (color + type)
+            if (!this.positionService || !this.positionService.getGame()) return null;
+            const piece = this.positionService.getGame().get(square);
             if (!piece) return null;
             return (piece.color + piece.type).toLowerCase();
         }
@@ -8957,45 +9725,355 @@ var ChessboardLib = (function (exports) {
             if (!this.validationService.isValidSquare(square)) {
                 throw new Error(`[removePiece] Invalid square: ${square}`);
             }
-            const squareObj = this.boardService.getSquare(square);
-            if (!squareObj) return true;
-            if (!squareObj.piece) return true;
-            squareObj.piece = null;
+            if (!this.positionService || !this.positionService.getGame()) {
+                return false;
+            }
             const game = this.positionService.getGame();
-            game.remove(square);
+            // Remove from game state first (source of truth)
+            const removed = game.remove(square);
+            // Then update the board visually
+            const squareObj = this.boardService.getSquare(square);
+            if (squareObj) {
+                squareObj.piece = null;
+            }
             this._updateBoardPieces(animate);
-            return true;
+            return removed !== null;
         }
 
         // --- BOARD CONTROL ---
         /**
          * Flip the board orientation
          * @param {Object} [opts]
-         * @param {boolean} [opts.animate=true]
+         * @param {boolean} [opts.animate=true] - Enable animation (for 'animate' mode)
+         * @param {string} [opts.mode] - Override flip mode ('visual', 'animate', 'none')
          */
         flipBoard(opts = {}) {
+            const flipMode = opts.mode || this.config.flipMode || 'visual';
+
+            // Update internal orientation state
             if (this.coordinateService && this.coordinateService.flipOrientation) {
                 this.coordinateService.flipOrientation();
             }
-            if (this._buildBoard) this._buildBoard();
-            if (this._buildSquares) this._buildSquares();
-            if (this._addListeners) this._addListeners();
-            if (this._updateBoardPieces) this._updateBoardPieces(opts.animate !== false);
-            console.log('FEN dopo flip:', this.fen(), 'Orientamento:', this.coordinateService.getOrientation());
+
+            const boardElement = this.boardService.element;
+            const isFlipped = this.coordinateService.getOrientation() === 'b';
+
+            switch (flipMode) {
+                case 'visual':
+                    // CSS flexbox flip - instant, no piece animation needed
+                    this._flipVisual(boardElement, isFlipped);
+                    break;
+
+                case 'animate':
+                    // Animate pieces to mirrored positions
+                    this._flipAnimate(opts.animate !== false);
+                    break;
+
+                case 'none':
+                    // No visual change - only internal orientation updated
+                    // Useful for programmatic orientation without visual feedback
+                    break;
+
+                default:
+                    this._flipVisual(boardElement, isFlipped);
+            }
+        }
+
+        /**
+         * Visual flip using CSS flexbox (instant)
+         * @private
+         * @param {HTMLElement} boardElement - Board DOM element
+         * @param {boolean} isFlipped - Whether board should be flipped
+         */
+        _flipVisual(boardElement, isFlipped) {
+            if (!boardElement) return;
+
+            if (isFlipped) {
+                boardElement.classList.add('flipped');
+            } else {
+                boardElement.classList.remove('flipped');
+            }
+        }
+
+        /**
+         * Animate flip using FLIP technique (First-Last-Invert-Play)
+         * Same end state as visual mode (CSS flip), but pieces animate smoothly.
+         * @private
+         * @param {boolean} animate - Whether to animate the movement
+         */
+        _flipAnimate(animate) {
+            const boardElement = this.boardService.element;
+            if (!boardElement) return;
+
+            const squares = this.boardService.getAllSquares();
+
+            // FIRST: Record current visual position of every piece
+            const pieceRects = {};
+            for (const [id, square] of Object.entries(squares)) {
+                if (square.piece && square.piece.element) {
+                    pieceRects[id] = square.piece.element.getBoundingClientRect();
+                }
+            }
+
+            // LAST: Apply CSS flip (instant) - same as visual mode
+            const isFlipped = this.coordinateService.getOrientation() === 'b';
+            this._flipVisual(boardElement, isFlipped);
+
+            if (!animate || Object.keys(pieceRects).length === 0) return;
+
+            // INVERT + PLAY: Animate each piece from old position to new
+            const duration = this.config.moveTime || 200;
+            const easing = 'cubic-bezier(0.33, 1, 0.68, 1)';
+
+            for (const [id, oldRect] of Object.entries(pieceRects)) {
+                const square = squares[id];
+                if (!square || !square.piece || !square.piece.element) continue;
+
+                const piece = square.piece;
+                const newRect = piece.element.getBoundingClientRect();
+                const dx = oldRect.left - newRect.left;
+                const dy = oldRect.top - newRect.top;
+
+                if (Math.abs(dx) < 1 && Math.abs(dy) < 1) continue;
+
+                if (piece.element.animate) {
+                    const anim = piece.element.animate([
+                        { transform: `translate(${dx}px, ${dy}px)` },
+                        { transform: 'translate(0, 0)' }
+                    ], { duration, easing, fill: 'forwards' });
+                    anim.onfinish = () => {
+                        anim.cancel();
+                        if (piece.element) piece.element.style.transform = '';
+                    };
+                } else {
+                    // setTimeout fallback for jsdom / older browsers
+                    piece.element.style.transform = `translate(${dx}px, ${dy}px)`;
+                    setTimeout(() => {
+                        if (!piece.element) return;
+                        piece.element.style.transition = `transform ${duration}ms`;
+                        piece.element.style.transform = 'translate(0, 0)';
+                        setTimeout(() => {
+                            if (!piece.element) return;
+                            piece.element.style.transition = '';
+                            piece.element.style.transform = '';
+                        }, duration);
+                    }, 0);
+                }
+            }
+        }
+
+        /**
+         * Set the flip mode at runtime
+         * @param {'visual'|'animate'|'none'} mode - The flip mode to use
+         */
+        setFlipMode(mode) {
+            const validModes = ['visual', 'animate', 'none'];
+            if (!validModes.includes(mode)) {
+                console.warn(`Invalid flip mode: ${mode}. Valid options: ${validModes.join(', ')}`);
+                return;
+            }
+            this.config.flipMode = mode;
+        }
+
+        /**
+         * Get the current flip mode
+         * @returns {string} Current flip mode
+         */
+        getFlipMode() {
+            return this.config.flipMode || 'visual';
+        }
+
+        // --- MOVEMENT CONFIGURATION ---
+
+        /**
+         * Set the movement style
+         * @param {'slide'|'arc'|'hop'|'teleport'|'fade'} style - Movement style
+         */
+        setMoveStyle(style) {
+            const validStyles = ['slide', 'arc', 'hop', 'teleport', 'fade'];
+            if (!validStyles.includes(style)) {
+                console.warn(`Invalid move style: ${style}. Valid: ${validStyles.join(', ')}`);
+                return;
+            }
+            this.config.moveStyle = style;
+        }
+
+        /**
+         * Get the current movement style
+         * @returns {string} Current movement style
+         */
+        getMoveStyle() {
+            return this.config.moveStyle || 'slide';
+        }
+
+        /**
+         * Set the capture animation style
+         * @param {'fade'|'shrink'|'instant'|'explode'} style - Capture style
+         */
+        setCaptureStyle(style) {
+            const validStyles = ['fade', 'shrink', 'instant', 'explode'];
+            if (!validStyles.includes(style)) {
+                console.warn(`Invalid capture style: ${style}. Valid: ${validStyles.join(', ')}`);
+                return;
+            }
+            this.config.captureStyle = style;
+        }
+
+        /**
+         * Get the current capture style
+         * @returns {string} Current capture style
+         */
+        getCaptureStyle() {
+            return this.config.captureStyle || 'fade';
+        }
+
+        /**
+         * Set the appearance animation style
+         * @param {'fade'|'pulse'|'pop'|'drop'|'instant'} style - Appearance style
+         */
+        setAppearanceStyle(style) {
+            const validStyles = ['fade', 'pulse', 'pop', 'drop', 'instant'];
+            if (!validStyles.includes(style)) {
+                console.warn(`Invalid appearance style: ${style}. Valid: ${validStyles.join(', ')}`);
+                return;
+            }
+            this.config.appearanceStyle = style;
+        }
+
+        /**
+         * Get the current appearance style
+         * @returns {string} Current appearance style
+         */
+        getAppearanceStyle() {
+            return this.config.appearanceStyle || 'fade';
+        }
+
+        /**
+         * Set the landing effect
+         * @param {'none'|'bounce'|'pulse'|'settle'} effect - Landing effect
+         */
+        setLandingEffect(effect) {
+            const validEffects = ['none', 'bounce', 'pulse', 'settle'];
+            if (!validEffects.includes(effect)) {
+                console.warn(`Invalid landing effect: ${effect}. Valid: ${validEffects.join(', ')}`);
+                return;
+            }
+            this.config.landingEffect = effect;
+        }
+
+        /**
+         * Get the current landing effect
+         * @returns {string} Current landing effect
+         */
+        getLandingEffect() {
+            return this.config.landingEffect || 'none';
         }
+
+        /**
+         * Set the movement duration
+         * @param {number|string} duration - Duration in ms or preset name ('instant', 'veryFast', 'fast', 'normal', 'slow', 'verySlow')
+         */
+        setMoveTime(duration) {
+            const presets = { instant: 0, veryFast: 100, fast: 200, normal: 400, slow: 600, verySlow: 1000 };
+            if (typeof duration === 'string' && presets[duration] !== undefined) {
+                this.config.moveTime = presets[duration];
+            } else if (typeof duration === 'number' && duration >= 0) {
+                this.config.moveTime = duration;
+            } else {
+                console.warn(`Invalid move time: ${duration}`);
+            }
+        }
+
+        /**
+         * Get the current movement duration
+         * @returns {number} Duration in ms
+         */
+        getMoveTime() {
+            return this.config.moveTime;
+        }
+
+        /**
+         * Set the easing function for movements
+         * @param {string} easing - CSS easing function
+         */
+        setMoveEasing(easing) {
+            const validEasings = ['ease', 'linear', 'ease-in', 'ease-out', 'ease-in-out'];
+            if (!validEasings.includes(easing)) {
+                console.warn(`Invalid easing: ${easing}. Valid: ${validEasings.join(', ')}`);
+                return;
+            }
+            this.config.moveEasing = easing;
+        }
+
+        /**
+         * Configure multiple movement settings at once
+         * @param {Object} options - Movement configuration
+         * @param {string} [options.style] - Movement style
+         * @param {string} [options.captureStyle] - Capture animation style
+         * @param {string} [options.landingEffect] - Landing effect
+         * @param {number|string} [options.duration] - Movement duration
+         * @param {string} [options.easing] - Easing function
+         * @param {number} [options.arcHeight] - Arc height for arc/hop styles (0-1)
+         */
+        configureMovement(options) {
+            if (options.style) this.setMoveStyle(options.style);
+            if (options.captureStyle) this.setCaptureStyle(options.captureStyle);
+            if (options.appearanceStyle) this.setAppearanceStyle(options.appearanceStyle);
+            if (options.landingEffect) this.setLandingEffect(options.landingEffect);
+            if (options.duration !== undefined) this.setMoveTime(options.duration);
+            if (options.easing) this.setMoveEasing(options.easing);
+            if (options.arcHeight !== undefined) {
+                this.config.moveArcHeight = Math.max(0, Math.min(1, options.arcHeight));
+            }
+        }
+
+        /**
+         * Get all movement configuration
+         * @returns {Object} Current movement configuration
+         */
+        getMovementConfig() {
+            return {
+                style: this.config.moveStyle || 'slide',
+                captureStyle: this.config.captureStyle || 'fade',
+                appearanceStyle: this.config.appearanceStyle || 'fade',
+                landingEffect: this.config.landingEffect || 'none',
+                duration: this.config.moveTime,
+                easing: this.config.moveEasing || 'ease',
+                arcHeight: this.config.moveArcHeight || 0.3
+            };
+        }
+
         /**
          * Set the board orientation
          * @param {'w'|'b'} color
          * @param {Object} [opts]
-         * @param {boolean} [opts.animate=true]
+         * @param {boolean} [opts.animate=true] - Enable animation (for 'animate' mode)
+         * @param {string} [opts.mode] - Override flip mode ('visual', 'animate', 'none')
          */
         setOrientation(color, opts = {}) {
             if (this.validationService.isValidOrientation(color)) {
-                this.coordinateService.setOrientation(color);
-                if (this._buildBoard) this._buildBoard();
-                if (this._buildSquares) this._buildSquares();
-                if (this._addListeners) this._addListeners();
-                if (this._updateBoardPieces) this._updateBoardPieces(opts.animate !== false);
+                const currentOrientation = this.coordinateService.getOrientation();
+                if (currentOrientation !== color) {
+                    this.coordinateService.setOrientation(color);
+
+                    const flipMode = opts.mode || this.config.flipMode || 'visual';
+                    const boardElement = this.boardService.element;
+                    const isFlipped = color === 'b';
+
+                    switch (flipMode) {
+                        case 'visual':
+                            this._flipVisual(boardElement, isFlipped);
+                            break;
+                        case 'animate':
+                            this._flipAnimate(opts.animate !== false);
+                            break;
+                        case 'none':
+                            // No visual change
+                            break;
+                        default:
+                            this._flipVisual(boardElement, isFlipped);
+                    }
+                }
             }
             return this.coordinateService.getOrientation();
         }
@@ -9113,7 +10191,40 @@ var ChessboardLib = (function (exports) {
         /**
          * Destroy the board and cleanup
          */
-        destroy() { /* TODO: robust destroy logic */ }
+        destroy() {
+            this._destroyed = true;
+
+            // Remove all event listeners
+            if (this.eventService) {
+                this.eventService.removeAllListeners();
+                this.eventService.destroy();
+            }
+
+            // Clear all timeouts
+            if (this._updateTimeout) {
+                clearTimeout(this._updateTimeout);
+                this._updateTimeout = null;
+            }
+
+            // Clear all animation timeouts
+            if (this._animationTimeouts) {
+                this._animationTimeouts.forEach(tid => clearTimeout(tid));
+                this._animationTimeouts = [];
+            }
+
+            // Destroy services
+            if (this.moveService) this.moveService.destroy();
+            if (this.animationService && this.animationService.destroy) this.animationService.destroy();
+            if (this.pieceService && this.pieceService.destroy) this.pieceService.destroy();
+            if (this.boardService && this.boardService.destroy) this.boardService.destroy();
+            if (this.positionService && this.positionService.destroy) this.positionService.destroy();
+            if (this.coordinateService && this.coordinateService.destroy) this.coordinateService.destroy();
+            if (this.validationService) this.validationService.destroy();
+            if (this.config && this.config.destroy) this.config.destroy();
+
+            // Clear references
+            this._cleanup();
+        }
         /**
          * Rebuild the board
          */
@@ -9129,7 +10240,11 @@ var ChessboardLib = (function (exports) {
          * Set new config
          * @param {Object} newConfig
          */
-        setConfig(newConfig) { this.setConfig(newConfig); }
+        setConfig(newConfig) {
+            if (this.config && typeof this.config.update === 'function') {
+                this.config.update(newConfig);
+            }
+        }
 
         // --- ALIASES/DEPRECATED ---
         /**
@@ -9164,17 +10279,10 @@ var ChessboardLib = (function (exports) {
         }
 
         /**
-         * Gets the current position as an object
-         * @returns {Object} Position object
-         */
-        position() {
-            return this.positionService.getPosition();
-        }
-
-        /**
-         * Sets a new position
-         * @param {string|Object} position - New position
-         * @param {boolean} [animate=true] - Whether to animate
+         * Gets or sets the current position
+         * @param {string|Object} [position] - Position to set (FEN or object). If omitted, returns current position.
+         * @param {boolean} [animate=true] - Whether to animate when setting
+         * @returns {Object} Current position object (when getting)
          */
         position(position, animate = true) {
             if (position === undefined) {
@@ -9437,34 +10545,21 @@ var ChessboardLib = (function (exports) {
         // Ensure all public API methods from README are present and routed
         insert(square, piece) { return this.putPiece(piece, square); }
         get(square) { return this.getPiece(square); }
-        position(position, color) {
-            if (color) this.setOrientation(color);
-            return this.setPosition(position);
-        }
-        flip(animation = true) { return this.flipBoard({ animate: animation }); }
+        // Note: position() is defined above at line ~1684 with getter/setter functionality
         build() { return this._initialize(); }
         resize(value) { return this.resizeBoard(value); }
-        destroy() { return this._cleanup(); }
         piece(square) { return this.getPiece(square); }
-        highlight(square) { return true; }
-        dehighlight(square) { return true; }
-        turn() { return this.positionService.getGame().turn(); }
         ascii() { return this.positionService.getGame().ascii(); }
         board() { return this.positionService.getGame().board(); }
         getCastlingRights(color) { return this.positionService.getGame().getCastlingRights(color); }
         getComment() { return this.positionService.getGame().getComment(); }
         getComments() { return this.positionService.getGame().getComments(); }
-        history(options = {}) { return this.positionService.getGame().history(options); }
         lastMove() { return this.positionService.getGame().lastMove(); }
         moveNumber() { return this.positionService.getGame().moveNumber(); }
         moves(options = {}) { return this.positionService.getGame().moves(options); }
-        pgn(options = {}) { return this.positionService.getGame().pgn(options); }
         squareColor(squareId) { return this.boardService.getSquare(squareId).isWhite() ? 'light' : 'dark'; }
-        isCheckmate() { return this.positionService.getGame().isCheckmate(); }
-        isDraw() { return this.positionService.getGame().isDraw(); }
         isDrawByFiftyMoves() { return this.positionService.getGame().isDrawByFiftyMoves(); }
         isInsufficientMaterial() { return this.positionService.getGame().isInsufficientMaterial(); }
-        isGameOver() { return this.positionService.getGame().isGameOver(); }
         isStalemate() { return this.positionService.getGame().isStalemate(); }
         isThreefoldRepetition() { return this.positionService.getGame().isThreefoldRepetition(); }
         load(fen, options = {}, animation = true) { return this.setPosition(fen, { ...options, animate: animation }); }