fix review

src/Avalonia.Base/Animation/Animation.cs

@@ -138,7 +138,8 @@ namespace Avalonia.Animation
         /// Gets or sets the playback behavior for this animation.
         /// When set to <see cref="PlaybackBehavior.Auto"/>, manually started animations and
         /// animations targeting <see cref="Visual.IsVisibleProperty"/> always play,
-        /// while style-applied animations pause when the control is not visible.
+        /// while style-applied animations pause when the control is not effectively visible
+        /// (see <see cref="Visual.IsEffectivelyVisible"/>).
         /// </summary>
         public PlaybackBehavior PlaybackBehavior
         {

src/Avalonia.Base/Animation/PlaybackBehavior.cs

@@ -1,7 +1,8 @@
 namespace Avalonia.Animation
 {
     /// <summary>
-    /// Determines whether an animation pauses when its target control is not visible.
+    /// Determines whether an animation pauses when its target control is not effectively visible
+    /// (see <see cref="Visual.IsEffectivelyVisible"/>).
     /// </summary>
     public enum PlaybackBehavior
     {
@@ -9,17 +10,19 @@ namespace Avalonia.Animation
         /// The system decides based on context. Manually started animations
         /// (via <see cref="Animation.RunAsync(Animatable, System.Threading.CancellationToken)"/>)
         /// and animations that target <see cref="Visual.IsVisibleProperty"/> always play.
-        /// Style-applied animations pause when the control is not effectively visible.
+        /// Style-applied animations pause when the control is not effectively visible
+        /// (see <see cref="Visual.IsEffectivelyVisible"/>).
         /// </summary>
         Auto,
 
         /// <summary>
-        /// The animation always plays regardless of the control's visibility state.
+        /// The animation always plays regardless of the control's effective visibility state.
         /// </summary>
         Always,
 
         /// <summary>
-        /// The animation pauses when the control is not effectively visible.
+        /// The animation pauses when the control is not effectively visible
+        /// (see <see cref="Visual.IsEffectivelyVisible"/>).
         /// </summary>
         OnlyIfVisible,
     }

tests/Avalonia.Base.UnitTests/Animation/AnimationIterationTests.cs

@@ -1014,17 +1014,17 @@ namespace Avalonia.Base.UnitTests.Animation
         }
 
         [Fact]
-        public void Width_Animation_Progresses_After_IsVisible_Set_True_On_Invisible_Control()
+        public void Width_Animation_Resumes_After_IsVisible_Set_True_On_Invisible_Control()
         {
-            // Tests the expand scenario with a double property: the control starts invisible,
-            // and the animation drives Width from 0 to 100. With the pause-on-invisible
-            // behavior, the animation clock should still advance after the control becomes
-            // visible (even if made visible by the same logical expand action).
+            // Tests the expand scenario with OnlyIfVisible: the control starts invisible
+            // and the animation is paused. Once IsVisible is set to true externally,
+            // the animation resumes and completes.
             var animation = new Animation()
             {
                 Duration = TimeSpan.FromSeconds(0.3),
                 Easing = new LinearEasing(),
                 FillMode = FillMode.Forward,
+                PlaybackBehavior = PlaybackBehavior.OnlyIfVisible,
                 Children =
                 {
                     new KeyFrame()
@@ -1046,12 +1046,15 @@ namespace Avalonia.Base.UnitTests.Animation
             var clock = new TestClock();
             var animationRun = animation.RunAsync(border, clock, TestContext.Current.CancellationToken);
 
+            // Animation is paused because control is invisible.
             clock.Step(TimeSpan.Zero);
+            Assert.Equal(0d, border.Width);
+            Assert.False(animationRun.IsCompleted);
 
             // Simulate what the expand handler does: set IsVisible = true externally.
             border.IsVisible = true;
 
-            // The animation should now be able to make progress.
+            // The animation should now resume and complete.
             clock.Step(TimeSpan.FromSeconds(0.3));
             Assert.True(animationRun.IsCompleted);
             Assert.Equal(100d, border.Width);