fix: address overlay animation review feedback

Author: piotr-graczyk-dev

README.md

@@ -164,6 +164,8 @@ When no animation prop is set, the default is `system`: each provider keeps its
 
 Explicit configs use milliseconds. `duration` defaults to `180`, `delay` defaults to `0`, and both values are clamped to `0..3000` before they reach the native provider. `reduceMotion` defaults to `system`, which disables explicit animations when the platform Reduced Motion setting asks for it; use `never` only when the app intentionally ignores that setting for this overlay.
 
+On iOS with `provider="google"`, marker and cluster entering animations can reduce UI-thread frame rate when a large viewport refresh adds many markers at once. The provider caps animated markers per refresh and may show the remaining markers immediately to preserve map gesture performance. For very large marker sets, prefer clustering, shorter durations, or `markerEnteringAnimation={false}` / `clusterEnteringAnimation={false}` when smooth gestures are more important than entrance motion.
+
 ### Capability matrix
 
 | Capability                 | `apple` iOS                                                 | `google` iOS                               | `google` Android                           | Future providers     |

docs/architecture.md

@@ -103,6 +103,8 @@ Map and overlay callbacks are wired through Nitro listeners on the HybridView. C
 
 Marker and marker-cluster entering animations follow the same descriptor model. The public API accepts `false`, `system`, or a serializable preset config; the React wrapper normalizes that into native descriptors. Native provider adapters execute the animation when a marker render element appears in the render diff. Updating animation config for an already retained marker does not restart the animation; the new config is used the next time that marker is added again.
 
+Google Maps on iOS is more sensitive to marker animation churn than MapKit. Large viewport refreshes can add many `GMSMarker` instances on the main thread, so the Google provider limits how many markers animate per refresh and reveals the rest immediately. This keeps gestures responsive, but very large marker sets may still need clustering, disabled entering animations, or a future provider-specific animation strategy.
+
 ## Data flow (target state)
 
 ```

example/App.tsx

@@ -16,6 +16,8 @@ import {
   StyleSheet,
   Text,
   View,
+  type AccessibilityRole,
+  type AccessibilityState,
   type StyleProp,
   type ViewStyle,
 } from 'react-native';
@@ -141,13 +143,19 @@ type ScalePressableProps = {
   style?: StyleProp<ViewStyle>;
   children: ReactNode;
   hitSlop?: number;
+  accessibilityRole?: AccessibilityRole;
+  accessibilityState?: AccessibilityState;
+  accessibilityLabel?: string;
 };
 
 const ScalePressable = memo(function ScalePressable({
   onPress,
   style,
   children,
   hitSlop,
+  accessibilityRole,
+  accessibilityState,
+  accessibilityLabel,
 }: ScalePressableProps) {
   const scale = useSharedValue(1);
 
@@ -158,6 +166,9 @@ const ScalePressable = memo(function ScalePressable({
   return (
     <AnimatedPressable
       hitSlop={hitSlop}
+      accessibilityRole={accessibilityRole}
+      accessibilityState={accessibilityState}
+      accessibilityLabel={accessibilityLabel}
       style={[style, animatedStyle]}
       onPress={onPress}
       onPressIn={() => {
@@ -341,6 +352,11 @@ const ScenarioDock = memo(function ScenarioDock({
                 <ScalePressable
                   key={option.id}
                   onPress={() => onSelectAnimation(option.id)}
+                  accessibilityRole="button"
+                  accessibilityState={{
+                    selected: option.id === animationOptionId,
+                  }}
+                  accessibilityLabel={`${option.label} entering animation`}
                   style={[
                     styles.optionChip,
                     option.id === animationOptionId && styles.optionChipActive,
@@ -581,7 +597,7 @@ export default function App() {
   const [scenarioIndex, setScenarioIndex] = useState(0);
   const [mapTypeIndex, setMapTypeIndex] = useState(0);
   const [providerIndex, setProviderIndex] = useState(0);
-  const [animationOptionIndex, setAnimationOptionIndex] = useState(2);
+  const [animationOptionIndex, setAnimationOptionIndex] = useState(0);
   const [status, setStatus] = useState('Waiting for map...');
   const [mapReady, setMapReady] = useState(false);
   const [dockExpanded, setDockExpanded] = useState(false);

package/ios/GoogleMapOverlayController.swift

@@ -4,12 +4,20 @@ import UIKit
 
 final class GoogleMapOverlayController {
   private static let clusterCellPoints: Double = 96
+  // GMSMarker entering animations are main-thread work; cap them per diff so
+  // bulk viewport refreshes do not block active Google Maps gestures.
+  private static let maximumAnimatedMarkersPerDiff = 96
 
   private enum MarkerPayload {
     case marker(String)
     case cluster(memberIds: [String], region: MKCoordinateRegion)
   }
 
+  private struct MarkerAnimationBatch {
+    let animation: ResolvedOverlayEnteringAnimation
+    var markers: [GMSMarker]
+  }
+
   private weak var mapView: GMSMapView?
   private var markers: [String: GMSMarker] = [:]
   private var markerVersions: [String: Int] = [:]
@@ -58,7 +66,10 @@ final class GoogleMapOverlayController {
     reapplyMarkers()
   }
 
-  func refreshViewportMarkers() {
+  func refreshViewportMarkers(
+    animateEntering: Bool = true,
+    animationBudget: Int = maximumAnimatedMarkersPerDiff
+  ) {
     guard let mapView, usesViewportPipeline else {
       return
     }
@@ -68,12 +79,20 @@ final class GoogleMapOverlayController {
       region: mapView.currentNitroRegion().toMKCoordinateRegion(),
       viewSize: mapView.bounds.size,
       apply: { [weak self] diff in
-        self?.applyDiff(diff)
+        self?.applyDiff(
+          diff,
+          animateEntering: animateEntering,
+          animationBudget: animationBudget
+        )
       }
     )
   }
 
-  func scheduleViewportRefresh(immediate: Bool = false) {
+  func scheduleViewportRefresh(
+    immediate: Bool = false,
+    animateEntering: Bool = true,
+    animationBudget: Int = maximumAnimatedMarkersPerDiff
+  ) {
     guard let mapView, usesViewportPipeline else {
       return
     }
@@ -84,7 +103,11 @@ final class GoogleMapOverlayController {
       viewSize: mapView.bounds.size,
       immediate: immediate,
       apply: { [weak self] diff in
-        self?.applyDiff(diff)
+        self?.applyDiff(
+          diff,
+          animateEntering: animateEntering,
+          animationBudget: animationBudget
+        )
       }
     )
   }
@@ -173,7 +196,11 @@ final class GoogleMapOverlayController {
     )
   }
 
-  private func applyDiff(_ diff: MarkerRenderDiff) {
+  private func applyDiff(
+    _ diff: MarkerRenderDiff,
+    animateEntering: Bool = true,
+    animationBudget: Int = maximumAnimatedMarkersPerDiff
+  ) {
     guard let mapView else {
       return
     }
@@ -183,16 +210,34 @@ final class GoogleMapOverlayController {
       markerVersions.removeValue(forKey: key)
     }
 
+    var animationBatches: [MarkerAnimationBatch] = []
+    var remainingAnimationBudget = animateEntering ? max(0, animationBudget) : 0
+
     for entry in diff.added {
       let marker = makeMarker(for: entry.element)
       let animation = enteringAnimation(for: entry.element)
-      OverlayEnteringAnimationResolver.prepareGoogleMarker(marker, animation: animation)
+      let shouldAnimate = animateEntering
+        && remainingAnimationBudget > 0
+        && OverlayEnteringAnimationResolver.canAnimateGoogleMarker(animation)
+
+      if shouldAnimate {
+        OverlayEnteringAnimationResolver.prepareGoogleMarker(marker, animation: animation)
+        if OverlayEnteringAnimationResolver.usesBatchedGoogleMarkerAnimation(animation) {
+          append(marker, animation: animation, to: &animationBatches)
+        }
+        remainingAnimationBudget -= 1
+      } else {
+        OverlayEnteringAnimationResolver.showGoogleMarkerWithoutAnimation(marker)
+      }
       marker.map = mapView
-      OverlayEnteringAnimationResolver.animateGoogleMarker(marker, animation: animation)
       markers[entry.key] = marker
       markerVersions[entry.key] = entry.version
     }
 
+    for batch in animationBatches {
+      OverlayEnteringAnimationResolver.animateGoogleMarkers(batch.markers, animation: batch.animation)
+    }
+
     for entry in diff.retained {
       guard let marker = markers[entry.key] else {
         continue
@@ -208,6 +253,18 @@ final class GoogleMapOverlayController {
     return marker
   }
 
+  private func append(
+    _ marker: GMSMarker,
+    animation: ResolvedOverlayEnteringAnimation,
+    to batches: inout [MarkerAnimationBatch]
+  ) {
+    for index in batches.indices where batches[index].animation == animation {
+      batches[index].markers.append(marker)
+      return
+    }
+    batches.append(MarkerAnimationBatch(animation: animation, markers: [marker]))
+  }
+
   private func enteringAnimation(
     for element: MarkerClusterEngine.Element
   ) -> ResolvedOverlayEnteringAnimation {

package/ios/GoogleMapProviderAdapter.swift

@@ -6,6 +6,9 @@ import QuartzCore
 import UIKit
 
 final class GoogleMapProviderAdapter: NSObject, MapProviderAdapter {
+  private static let liveGestureRefreshInterval: CFTimeInterval = 0.18
+  private static let liveGestureAnimationBudget = 24
+
   private var isProgrammaticUpdate = false
   private var pendingProgrammaticUpdateIDs: [Int] = []
   private var nextProgrammaticUpdateID = 0
@@ -30,7 +33,6 @@ final class GoogleMapProviderAdapter: NSObject, MapProviderAdapter {
   }
 
   lazy var view: GMSMapView = {
-    GoogleMapsAPIKey.configureIfNeeded()
     let camera = self.camera?.toGMSCameraPosition()
       ?? GMSCameraPosition(latitude: 0, longitude: 0, zoom: 10)
     let mapView: GMSMapView
@@ -55,7 +57,8 @@ final class GoogleMapProviderAdapter: NSObject, MapProviderAdapter {
     return mapView
   }()
 
-  init(googleMapId: String?) {
+  init(googleMapId: String?) throws {
+    try GoogleMapsAPIKey.configureIfNeeded()
     _googleMapId = googleMapId
     super.init()
   }
@@ -377,6 +380,7 @@ final class GoogleMapProviderAdapter: NSObject, MapProviderAdapter {
   private func startGestureMarkerRefresh() {
     isUserGestureMoving = true
     lastLiveMarkerRefreshTime = 0
+    refreshGestureMarkersIfNeeded()
   }
 
   private func refreshGestureMarkersIfNeeded() {
@@ -385,18 +389,20 @@ final class GoogleMapProviderAdapter: NSObject, MapProviderAdapter {
     }
 
     let now = CACurrentMediaTime()
-    guard now - lastLiveMarkerRefreshTime >= MarkerRenderPipeline.liveRefreshInterval else {
+    guard now - lastLiveMarkerRefreshTime >= Self.liveGestureRefreshInterval else {
       return
     }
 
     lastLiveMarkerRefreshTime = now
-    overlayController.refreshViewportMarkers()
+    overlayController.refreshViewportMarkers(
+      animateEntering: true,
+      animationBudget: Self.liveGestureAnimationBudget
+    )
   }
 
   private func stopGestureMarkerRefresh() {
     isUserGestureMoving = false
     lastLiveMarkerRefreshTime = 0
-    refreshVisibleMarkers()
   }
 
   private func animateToClusterRegion(_ region: MKCoordinateRegion) {
@@ -528,6 +534,7 @@ extension GoogleMapProviderAdapter: GMSMapViewDelegate {
 
   func mapView(_ mapView: GMSMapView, idleAt position: GMSCameraPosition) {
     stopGestureMarkerRefresh()
+    refreshVisibleMarkers()
     notifyRegionChange(complete: true)
     endProgrammaticUpdate()
     notifyMapReadyIfNeeded()

package/ios/GoogleMapsAPIKey.swift

@@ -4,13 +4,12 @@ import GoogleMaps
 enum GoogleMapsAPIKey {
   private static var configuredKey: String?
 
-  static func configureIfNeeded() {
+  static func configureIfNeeded() throws {
     let key = Bundle.main.object(forInfoDictionaryKey: "GoogleMapsIosApiKey") as? String
     guard let key = key?.trimmingCharacters(in: .whitespacesAndNewlines),
-          !key.isEmpty else {
-      preconditionFailure(
-        "react-native-nitro-maps: provider=\"google\" on iOS requires GoogleMapsIosApiKey in the host app Info.plist."
-      )
+          !key.isEmpty,
+          !key.hasPrefix("$(") else {
+      throw MapProviderConfigurationError.missingGoogleMapsIosApiKey
     }
 
     guard configuredKey != key else {
@@ -21,3 +20,17 @@ enum GoogleMapsAPIKey {
     configuredKey = key
   }
 }
+
+enum MapProviderConfigurationError: LocalizedError {
+  case missingGoogleMapsIosApiKey
+  case unsupportedIOSProvider(MapProvider)
+
+  var errorDescription: String? {
+    switch self {
+    case .missingGoogleMapsIosApiKey:
+      return "react-native-nitro-maps: provider=\"google\" on iOS requires GoogleMapsIosApiKey in the host app Info.plist."
+    case let .unsupportedIOSProvider(provider):
+      return "Map provider \"\(provider)\" is not supported on iOS."
+    }
+  }
+}

package/ios/HybridMapView.swift

@@ -334,9 +334,15 @@ final class HybridMapView: HybridMapViewSpec {
     case .apple:
       return AppleMapProviderAdapter()
     case .google:
-      return GoogleMapProviderAdapter(googleMapId: _googleMapId)
+      do {
+        return try GoogleMapProviderAdapter(googleMapId: _googleMapId)
+      } catch {
+        return UnavailableMapProviderAdapter(error: error)
+      }
     case .openstreetmap, .mapbox:
-      preconditionFailure("Map provider \"\(provider)\" is not supported on iOS.")
+      return UnavailableMapProviderAdapter(
+        error: MapProviderConfigurationError.unsupportedIOSProvider(provider)
+      )
     }
   }
 

package/ios/HybridMapViewDelegate.swift

@@ -126,21 +126,11 @@ final class HybridMapViewDelegate: NSObject, MKMapViewDelegate, UIGestureRecogni
           animation: marker.enteringAnimation,
           supportsScale: true
         )
-      } else if let cluster = view.annotation as? MapClusterAnnotation {
-        let animation: ResolvedOverlayEnteringAnimation
-        if cluster.enteringAnimation.kind == .system {
-          animation = ResolvedOverlayEnteringAnimation(
-            kind: .fade,
-            duration: 0.16,
-            delay: 0,
-            reduceMotion: .system
-          )
-        } else {
-          animation = cluster.enteringAnimation
-        }
+      } else if let cluster = view.annotation as? MapClusterAnnotation,
+                cluster.enteringAnimation.kind != .system {
         OverlayEnteringAnimationResolver.animateAnnotationView(
           view,
-          animation: animation,
+          animation: cluster.enteringAnimation,
           supportsScale: true
         )
       }