@alepot55/chessboardjs 2.2.2 → 2.3.0

package/dist/chessboard.cjs.js

@@ -1072,11 +1072,84 @@ const TRANSITION_FUNCTIONS = Object.freeze({
  * @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,
@@ -1084,15 +1157,45 @@ const DEFAULT_CONFIG$1 = Object.freeze({
     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',
@@ -1187,6 +1290,7 @@ class ChessboardConfig {
         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;
@@ -1201,12 +1305,27 @@ class ChessboardConfig {
         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);
@@ -1310,6 +1429,111 @@ class ChessboardConfig {
         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
@@ -1415,6 +1639,7 @@ class ChessboardConfig {
             position: this.position,
             orientation: this.orientation,
             mode: this.mode,
+            flipMode: this.flipMode,
             size: this.size,
             draggable: this.draggable,
             hints: this.hints,
@@ -1422,11 +1647,26 @@ class ChessboardConfig {
             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,
@@ -1631,6 +1871,121 @@ class Piece {
         }
     }
 
+    /**
+     * 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;
@@ -1664,15 +2019,105 @@ class Piece {
             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; }
         
@@ -1712,41 +2157,319 @@ class Piece {
         }
     }
 
-    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}`);
         }
     }
 
@@ -1867,9 +2590,9 @@ class Square {
     }
 
     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) {
@@ -1981,7 +2704,7 @@ class Square {
     }
 
     getColor() {
-        return this.piece.getColor();
+        return this.piece ? this.piece.getColor() : null;
     }
 
     check() {
@@ -4639,25 +5362,11 @@ class MoveService {
             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);
     }
 
     /**
@@ -4667,27 +5376,19 @@ class MoveService {
      */
     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;
         }
         
@@ -4728,53 +5429,41 @@ class MoveService {
      */
     _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);
     }
 
     /**
@@ -4790,43 +5479,34 @@ class MoveService {
         const toRank = to.row;
         const fromFile = from.col;
         const toFile = to.col;
-        
-        console.log(`Validating pawn move: ${from.id} -> ${to.id} (${color})`);
-        console.log(`Ranks: ${fromRank} -> ${toRank}, Files: ${fromFile} -> ${toFile}`);
-        
-        // Direction of pawn movement
+
         const direction = color === 'w' ? 1 : -1;
         const rankDiff = toRank - fromRank;
         const fileDiff = Math.abs(toFile - fromFile);
-        
+
         // Pawn can only move forward
         if (rankDiff * direction <= 0) {
-            console.log('Invalid: Pawn cannot move backward or stay in place');
             return false;
         }
-        
-        // Pawn can only move 1 rank at a time (except for double move from starting position)
+
+        // 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;
     }
 
@@ -4867,24 +5547,17 @@ class MoveService {
      * @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);
             }
         });
         
@@ -4911,40 +5584,28 @@ class MoveService {
     _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;
     }
 
@@ -5180,50 +5841,61 @@ class PieceService {
             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;
     }
 
@@ -5242,12 +5914,22 @@ class PieceService {
             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
         );
     }
 
@@ -5261,8 +5943,8 @@ class PieceService {
      */
     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;
         }
@@ -5274,6 +5956,12 @@ class PieceService {
         }
 
         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
@@ -7652,7 +8340,8 @@ let Chessboard$1 = class Chessboard {
             this._handleConstructorError(error);
         }
         this._undoneMoves = [];
-        this._updateBoardPieces(true, true); // Forza popolamento DOM subito
+        this._destroyed = false;
+        this._animationTimeouts = [];
     }
 
     /**
@@ -7764,6 +8453,11 @@ let Chessboard$1 = class Chessboard {
         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');
+        }
     }
 
     /**
@@ -7792,9 +8486,7 @@ let Chessboard$1 = class Chessboard {
      * 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)
@@ -7814,9 +8506,7 @@ let Chessboard$1 = class Chessboard {
      * @private
      */
     _buildSquares() {
-        console.log('CHIAMATO: _buildSquares');
         if (this._isUndoRedo) {
-            console.log('SKIP _buildSquares per undo/redo');
             return;
         }
         if (this.boardService && this.boardService.removeSquares) {
@@ -8029,6 +8719,14 @@ let Chessboard$1 = class Chessboard {
         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?
@@ -8036,24 +8734,22 @@ let Chessboard$1 = class Chessboard {
                 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) {
@@ -8106,12 +8802,9 @@ let Chessboard$1 = class Chessboard {
         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;
@@ -8143,12 +8836,9 @@ let Chessboard$1 = class Chessboard {
 
         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);
@@ -8169,10 +8859,9 @@ let Chessboard$1 = class Chessboard {
      * @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;
         }
 
@@ -8235,33 +8924,24 @@ let Chessboard$1 = class Chessboard {
      * @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);
         }
     }
@@ -8274,7 +8954,23 @@ let Chessboard$1 = class Chessboard {
      * @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);
@@ -8290,12 +8986,13 @@ let Chessboard$1 = class Chessboard {
                 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(
@@ -8320,9 +9017,43 @@ let Chessboard$1 = class Chessboard {
      * @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 = {};
 
@@ -8348,35 +9079,16 @@ let Chessboard$1 = class Chessboard {
         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] = [];
@@ -8386,10 +9098,9 @@ let Chessboard$1 = class Chessboard {
                 }
             }
 
-            // 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;
@@ -8405,58 +9116,140 @@ let Chessboard$1 = class Chessboard {
                     }
                 }
                 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++;
         });
     }
 
@@ -8484,10 +9277,6 @@ let Chessboard$1 = class Chessboard {
             }
         });
 
-        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
@@ -8501,8 +9290,6 @@ let Chessboard$1 = class Chessboard {
             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
@@ -8524,7 +9311,6 @@ let Chessboard$1 = class Chessboard {
 
             if (availableDestination) {
                 const [toSquare, expectedId] = availableDestination;
-                console.log(`MOVE: ${currentPieceId} from ${fromSquare} to ${toSquare}`);
                 moves.push({
                     piece: currentPieceId,
                     from: fromSquare,
@@ -8534,8 +9320,6 @@ let Chessboard$1 = class Chessboard {
                 });
                 processedSquares.add(toSquare);
             } else {
-                // This piece needs to be removed
-                console.log(`REMOVE: ${currentPieceId} from ${fromSquare}`);
                 removes.push({
                     piece: currentPieceId,
                     square: fromSquare,
@@ -8547,7 +9331,6 @@ let Chessboard$1 = class Chessboard {
         // 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,
@@ -8573,26 +9356,13 @@ let Chessboard$1 = class Chessboard {
      * @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
@@ -8605,9 +9375,7 @@ let Chessboard$1 = class Chessboard {
 
         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
@@ -8618,45 +9386,33 @@ let Chessboard$1 = class Chessboard {
             }
         };
 
-        // 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++;
         });
     }
@@ -8672,23 +9428,16 @@ let Chessboard$1 = class Chessboard {
         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
         );
     }
 
@@ -8699,12 +9448,7 @@ let Chessboard$1 = class Chessboard {
      * @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);
     }
 
     /**
@@ -8714,18 +9458,13 @@ let Chessboard$1 = class Chessboard {
      * @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
         );
     }
 
@@ -8825,7 +9564,7 @@ let Chessboard$1 = class Chessboard {
         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 });
     }
     /**
@@ -8840,10 +9579,13 @@ let Chessboard$1 = class Chessboard {
             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;
     }
 
@@ -8880,6 +9622,32 @@ let Chessboard$1 = class Chessboard {
         }
         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
@@ -8894,10 +9662,10 @@ let Chessboard$1 = class Chessboard {
      * @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();
     }
@@ -8958,45 +9726,355 @@ let Chessboard$1 = class Chessboard {
         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();
     }
@@ -9114,7 +10192,40 @@ let Chessboard$1 = class Chessboard {
     /**
      * 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
      */
@@ -9130,7 +10241,11 @@ let Chessboard$1 = class Chessboard {
      * 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 ---
     /**
@@ -9165,17 +10280,10 @@ let Chessboard$1 = class Chessboard {
     }
 
     /**
-     * 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) {
@@ -9438,34 +10546,21 @@ let Chessboard$1 = class Chessboard {
     // 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 }); }