@lugg/maps 1.0.0-beta.9 → 1.0.0

package/ios/core/AppleStaticMapProvider.mm

@@ -0,0 +1,159 @@
+#import "AppleStaticMapProvider.h"
+
+using facebook::react::LuggMapViewPoiFilterMode;
+using facebook::react::LuggMapViewTheme;
+
+#import "../extensions/MKMapView+Zoom.h"
+#import "AppleMapProvider.h"
+#import "LuggAnnotationView.h"
+
+// Standard MKMarkerAnnotationView balloon size; standalone (off-map) views
+// don't size themselves
+static const CGSize kDefaultMarkerSize = {28, 33};
+
+// The rect the snapshot renders: the region for the requested zoom, expanded
+// on the short axis to the view's aspect ratio - the same fit MKMapView
+// applies in setRegion, so static and live maps frame alike. Passing this
+// exact rect to MKMapSnapshotter makes the projection exact.
+static MKMapRect LuggStaticFittedMapRect(CLLocationCoordinate2D center,
+                                         double zoom, CGSize size) {
+  MKCoordinateSpan span = LuggCoordinateSpanForZoomLevel(MIN(zoom, 28), center);
+  MKMapPoint topLeft = MKMapPointForCoordinate(CLLocationCoordinate2DMake(
+      MIN(center.latitude + span.latitudeDelta / 2, 90.0),
+      center.longitude - span.longitudeDelta / 2));
+  MKMapPoint bottomRight = MKMapPointForCoordinate(CLLocationCoordinate2DMake(
+      MAX(center.latitude - span.latitudeDelta / 2, -90.0),
+      center.longitude + span.longitudeDelta / 2));
+  MKMapRect rect =
+      MKMapRectMake(topLeft.x, topLeft.y, bottomRight.x - topLeft.x,
+                    bottomRight.y - topLeft.y);
+
+  double viewAspect = size.width / size.height;
+  double rectAspect = rect.size.width / rect.size.height;
+  if (rectAspect > viewAspect) {
+    double height = rect.size.width / viewAspect;
+    rect.origin.y -= (height - rect.size.height) / 2;
+    rect.size.height = height;
+  } else {
+    double width = rect.size.height * viewAspect;
+    rect.origin.x -= (width - rect.size.width) / 2;
+    rect.size.width = width;
+  }
+  return rect;
+}
+
+@implementation AppleStaticMapProvider {
+  MKMapSnapshotter *_snapshotter;
+
+  BOOL _poiEnabled;
+  LuggMapViewPoiFilterMode _poiFilterMode;
+  NSArray<NSString *> *_poiFilterCategories;
+}
+
+- (instancetype)init {
+  if (self = [super init]) {
+    _poiEnabled = YES;
+    _poiFilterMode = LuggMapViewPoiFilterMode::Including;
+    _poiFilterCategories = @[];
+  }
+  return self;
+}
+
+#pragma mark - StaticMapProviderBase
+
+- (MKMapRect)mapRectForSize:(CGSize)size {
+  return LuggStaticFittedMapRect(self.coordinate, self.zoom, size);
+}
+
+- (UIView *)newDefaultMarkerOverlayView {
+  MKAnnotationView *pin =
+      [[LuggMarkerAnnotationView alloc] initWithAnnotation:nil
+                                           reuseIdentifier:nil];
+  pin.bounds =
+      CGRectMake(0, 0, kDefaultMarkerSize.width, kDefaultMarkerSize.height);
+  return pin;
+}
+
+// Inverse of LuggStaticFittedMapRect: the pre-fit rect is square in map
+// points with side latitudeDelta * worldHeight / (360 * cos(lat)), and the
+// aspect fit scales it to the view's short side
+- (double)zoomForMapPointsPerPoint:(double)mapPointsPerPoint {
+  CGSize size = self.projectedSize;
+  double side = mapPointsPerPoint * MIN(size.width, size.height);
+  double latitudeDelta = side * 360.0 *
+                         cos(self.coordinate.latitude * M_PI / 180.0) /
+                         MKMapSizeWorld.height;
+  double zoom = 0.5 + log2(360.0 / latitudeDelta);
+  return MAX(MIN(zoom, 28.0), 0.0);
+}
+
+- (UITraitCollection *)snapshotTraitCollection {
+  UITraitCollection *base = self.wrapperView.traitCollection;
+  UIUserInterfaceStyle style;
+  switch (self.theme) {
+  case LuggMapViewTheme::Dark:
+    style = UIUserInterfaceStyleDark;
+    break;
+  case LuggMapViewTheme::Light:
+    style = UIUserInterfaceStyleLight;
+    break;
+  default:
+    return base;
+  }
+  return [UITraitCollection traitCollectionWithTraitsFromCollections:@[
+    base, [UITraitCollection traitCollectionWithUserInterfaceStyle:style]
+  ]];
+}
+
+- (void)renderBaseMap {
+  if (_snapshotter)
+    return;
+
+  MKMapSnapshotOptions *options = [[MKMapSnapshotOptions alloc] init];
+  options.mapRect = self.mapRect;
+  options.size = self.projectedSize;
+  options.mapType = LuggMKMapTypeFromMapType(self.mapType);
+  options.pointOfInterestFilter = LuggPointOfInterestFilter(
+      _poiEnabled, _poiFilterMode, _poiFilterCategories);
+  options.traitCollection = [self snapshotTraitCollection];
+
+  MKMapSnapshotter *snapshotter =
+      [[MKMapSnapshotter alloc] initWithOptions:options];
+  _snapshotter = snapshotter;
+
+  __weak AppleStaticMapProvider *weakSelf = self;
+  [snapshotter startWithQueue:dispatch_get_main_queue()
+            completionHandler:^(MKMapSnapshot *snapshot, NSError *error) {
+              AppleStaticMapProvider *strongSelf = weakSelf;
+              if (!strongSelf || strongSelf->_snapshotter != snapshotter)
+                return;
+              strongSelf->_snapshotter = nil;
+              if (error || !snapshot) {
+                // Keep the placeholder; resumeAnimations retries (e.g. back
+                // online)
+                return;
+              }
+              [strongSelf displayBaseImage:snapshot.image fromCache:NO];
+            }];
+}
+
+- (void)cancelBaseRender {
+  [_snapshotter cancel];
+  _snapshotter = nil;
+}
+
+#pragma mark - Props
+
+- (void)setPoiEnabled:(BOOL)enabled {
+  _poiEnabled = enabled;
+}
+
+- (void)setPoiFilterMode:(LuggMapViewPoiFilterMode)mode {
+  _poiFilterMode = mode;
+}
+
+- (void)setPoiFilterCategories:(NSArray<NSString *> *)categories {
+  _poiFilterCategories = categories;
+}
+
+@end

package/ios/core/GMSPolylineAnimator.m

@@ -148,13 +148,25 @@ static const NSUInteger kMaxGradientSpans = 512;
   }
 
   GMSMutablePath *path = [GMSMutablePath path];
-  for (CLLocation *location in self.coordinates) {
-    [path addCoordinate:location.coordinate];
+  CLLocationCoordinate2D lastCoord = self.coordinates.firstObject.coordinate;
+  [path addCoordinate:lastCoord];
+  for (NSUInteger i = 1; i < self.coordinates.count; i++) {
+    CLLocationCoordinate2D coord = self.coordinates[i].coordinate;
+    if (coord.latitude == lastCoord.latitude && coord.longitude == lastCoord.longitude) {
+      continue;
+    }
+    [path addCoordinate:coord];
+    lastCoord = coord;
   }
+
+  // Clear stale spans before swapping the path so Google Maps never rebuilds
+  // span models against a path with fewer segments (GMSModelStyleBuilder
+  // couldNotInstantiate -> EXC_BAD_ACCESS). Reassign spans once the new path is set.
+  _polyline.spans = nil;
   _polyline.path = path;
 
-  if (self.strokeColors.count > 1) {
-    _polyline.spans = [self createGradientSpans];
+  if (path.count > 1 && self.strokeColors.count > 1) {
+    _polyline.spans = [self createGradientSpansForSegmentCount:path.count - 1];
   } else {
     _polyline.strokeColor = self.strokeColors.firstObject ?: [UIColor blackColor];
   }
@@ -222,35 +234,44 @@ static const NSUInteger kMaxGradientSpans = 512;
   }
 
   if (headDist <= tailDist) {
+    _polyline.spans = nil;
     _polyline.path = [GMSMutablePath path];
     return;
   }
 
-  CGFloat visibleLength = headDist - tailDist;
   NSUInteger startIndex = [self indexForDistance:tailDist];
   NSUInteger endIndex = [self indexForDistance:headDist];
 
   GMSMutablePath *path = [GMSMutablePath path];
-  NSMutableArray<GMSStyleSpan *> *spans = [NSMutableArray array];
 
-  CLLocationCoordinate2D startCoord = [self coordinateAtDistance:tailDist];
-  [path addCoordinate:startCoord];
+  CLLocationCoordinate2D lastCoord = [self coordinateAtDistance:tailDist];
+  [path addCoordinate:lastCoord];
 
   for (NSUInteger i = startIndex + 1; i <= endIndex; i++) {
-    [path addCoordinate:self.coordinates[i].coordinate];
+    CLLocationCoordinate2D coord = self.coordinates[i].coordinate;
+    if (coord.latitude == lastCoord.latitude && coord.longitude == lastCoord.longitude) {
+      continue;
+    }
+    [path addCoordinate:coord];
+    lastCoord = coord;
   }
 
   CLLocationCoordinate2D endCoord = [self coordinateAtDistance:headDist];
-  CLLocationCoordinate2D lastAdded =
-      (endIndex < self.coordinates.count) ? self.coordinates[endIndex].coordinate : endCoord;
-  if (endCoord.latitude != lastAdded.latitude || endCoord.longitude != lastAdded.longitude) {
+  if (endCoord.latitude != lastCoord.latitude || endCoord.longitude != lastCoord.longitude) {
     [path addCoordinate:endCoord];
   }
 
   NSUInteger pathCount = path.count;
-  NSUInteger segmentCount = pathCount - 1;
+  NSUInteger segmentCount = (pathCount > 1) ? pathCount - 1 : 0;
+
+  if (segmentCount == 0) {
+    _polyline.spans = nil;
+    _polyline.path = path;
+    return;
+  }
 
   if (self.strokeColors.count <= 1) {
+    _polyline.spans = nil;
     _polyline.path = path;
     _polyline.strokeColor = self.strokeColors.firstObject ?: [UIColor blackColor];
     return;
@@ -259,6 +280,7 @@ static const NSUInteger kMaxGradientSpans = 512;
   NSUInteger spanCount = MIN(segmentCount, kMaxAnimationSpans);
   double segmentsPerSpan = (double)segmentCount / spanCount;
 
+  NSMutableArray<GMSStyleSpan *> *spans = [NSMutableArray array];
   for (NSUInteger i = 0; i < spanCount; i++) {
     CGFloat gradientPos = ((CGFloat)i + 0.5) / spanCount;
     UIColor *color = [self colorAtGradientPosition:gradientPos];
@@ -266,13 +288,16 @@ static const NSUInteger kMaxGradientSpans = 512;
     [spans addObject:[GMSStyleSpan spanWithStyle:style segments:segmentsPerSpan]];
   }
 
+  // Clear stale spans before swapping the path so Google Maps never rebuilds
+  // span models against a path with fewer segments (GMSModelStyleBuilder
+  // couldNotInstantiate -> EXC_BAD_ACCESS). Reassign spans once the new path is set.
+  _polyline.spans = nil;
   _polyline.path = path;
   _polyline.spans = spans;
 }
 
-- (NSArray<GMSStyleSpan *> *)createGradientSpans {
+- (NSArray<GMSStyleSpan *> *)createGradientSpansForSegmentCount:(NSUInteger)segmentCount {
   NSMutableArray<GMSStyleSpan *> *spans = [NSMutableArray array];
-  NSUInteger segmentCount = self.coordinates.count - 1;
   NSUInteger spanCount = MIN(segmentCount, kMaxGradientSpans);
   double segmentsPerSpan = (double)segmentCount / spanCount;
 

package/ios/core/GoogleMapProvider.h

@@ -3,6 +3,16 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/// Resolves a mapId prop value ("" or "DEMO_MAP_ID" -> demo map ID),
+/// shared by the live and static Google providers.
+GMSMapID *LuggGMSMapIDFromString(NSString *_Nullable mapId);
+
+GMSMapViewType
+LuggGMSMapTypeFromMapType(facebook::react::LuggMapViewMapType mapType);
+
+UIUserInterfaceStyle
+LuggInterfaceStyleFromTheme(facebook::react::LuggMapViewTheme theme);
+
 @interface GoogleMapProvider : NSObject <MapProvider, GMSMapViewDelegate>
 
 @property(nonatomic, copy, nullable) NSString *mapId;

package/ios/core/GoogleMapProvider.mm

@@ -17,6 +17,39 @@ using facebook::react::LuggMapViewTheme;
 
 static NSString *const kDemoMapId = @"DEMO_MAP_ID";
 
+GMSMapID *LuggGMSMapIDFromString(NSString *_Nullable mapId) {
+  if (mapId.length == 0 || [mapId isEqualToString:kDemoMapId]) {
+    return [GMSMapID demoMapID];
+  }
+  return [GMSMapID mapIDWithIdentifier:mapId];
+}
+
+GMSMapViewType
+LuggGMSMapTypeFromMapType(facebook::react::LuggMapViewMapType mapType) {
+  switch (mapType) {
+  case LuggMapViewMapType::Satellite:
+    return kGMSTypeSatellite;
+  case LuggMapViewMapType::Terrain:
+    return kGMSTypeTerrain;
+  case LuggMapViewMapType::Hybrid:
+    return kGMSTypeHybrid;
+  default:
+    return kGMSTypeNormal;
+  }
+}
+
+UIUserInterfaceStyle
+LuggInterfaceStyleFromTheme(facebook::react::LuggMapViewTheme theme) {
+  switch (theme) {
+  case LuggMapViewTheme::Dark:
+    return UIUserInterfaceStyleDark;
+  case LuggMapViewTheme::Light:
+    return UIUserInterfaceStyleLight;
+  default:
+    return UIUserInterfaceStyleUnspecified;
+  }
+}
+
 @interface GoogleMapProvider () <
     LuggMarkerViewDelegate, LuggCalloutViewDelegate, LuggPolylineViewDelegate,
     LuggPolygonViewDelegate, LuggCircleViewDelegate,
@@ -53,6 +86,7 @@ static NSString *const kDemoMapId = @"DEMO_MAP_ID";
 }
 
 @synthesize delegate = _delegate;
+@synthesize staticMode = _staticMode;
 
 - (instancetype)init {
   if (self = [super init]) {
@@ -89,13 +123,6 @@ static NSString *const kDemoMapId = @"DEMO_MAP_ID";
   if (_mapView)
     return;
 
-  GMSMapID *gmsMapId;
-  if ([_mapId isEqualToString:kDemoMapId] || _mapId.length == 0) {
-    gmsMapId = [GMSMapID demoMapID];
-  } else {
-    gmsMapId = [GMSMapID mapIDWithIdentifier:_mapId];
-  }
-
   GMSCameraPosition *camera =
       [GMSCameraPosition cameraWithLatitude:coordinate.latitude
                                   longitude:coordinate.longitude
@@ -104,7 +131,7 @@ static NSString *const kDemoMapId = @"DEMO_MAP_ID";
   GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
   options.frame = wrapperView.bounds;
   options.camera = camera;
-  options.mapID = gmsMapId;
+  options.mapID = LuggGMSMapIDFromString(_mapId);
 
   _mapView = [[GMSMapView alloc] initWithOptions:options];
   _mapView.autoresizingMask =
@@ -142,10 +169,18 @@ static NSString *const kDemoMapId = @"DEMO_MAP_ID";
   [_circleToViewMap removeAllObjects];
   [_markerToViewMap removeAllObjects];
   [_groundOverlayToViewMap removeAllObjects];
-  [_mapView clear];
+  [self destroyMapView];
+  _isMapReady = NO;
+}
+
+- (void)destroyMapView {
+  if (!_mapView)
+    return;
+
+  _mapView.delegate = nil;
   [_mapView removeFromSuperview];
+  [_mapView clear];
   _mapView = nil;
-  _isMapReady = NO;
 }
 
 #pragma mark - Props
@@ -166,6 +201,10 @@ static NSString *const kDemoMapId = @"DEMO_MAP_ID";
   _mapView.settings.tiltGestures = enabled;
 }
 
+- (void)setCompassEnabled:(BOOL)enabled {
+  _mapView.settings.compassButton = enabled;
+}
+
 - (void)setUserLocationEnabled:(BOOL)enabled {
   _mapView.myLocationEnabled = enabled;
 }
@@ -187,23 +226,7 @@ static NSString *const kDemoMapId = @"DEMO_MAP_ID";
 }
 
 - (void)setMapType:(LuggMapViewMapType)mapType {
-  if (!_mapView)
-    return;
-
-  switch (mapType) {
-  case LuggMapViewMapType::Satellite:
-    _mapView.mapType = kGMSTypeSatellite;
-    break;
-  case LuggMapViewMapType::Terrain:
-    _mapView.mapType = kGMSTypeTerrain;
-    break;
-  case LuggMapViewMapType::Hybrid:
-    _mapView.mapType = kGMSTypeHybrid;
-    break;
-  default:
-    _mapView.mapType = kGMSTypeNormal;
-    break;
-  }
+  _mapView.mapType = LuggGMSMapTypeFromMapType(mapType);
 }
 
 - (void)setTheme:(LuggMapViewTheme)theme {
@@ -212,20 +235,7 @@ static NSString *const kDemoMapId = @"DEMO_MAP_ID";
 }
 
 - (void)applyTheme {
-  if (!_mapView)
-    return;
-
-  switch (_theme) {
-  case LuggMapViewTheme::Dark:
-    _mapView.overrideUserInterfaceStyle = UIUserInterfaceStyleDark;
-    break;
-  case LuggMapViewTheme::Light:
-    _mapView.overrideUserInterfaceStyle = UIUserInterfaceStyleLight;
-    break;
-  default:
-    _mapView.overrideUserInterfaceStyle = UIUserInterfaceStyleUnspecified;
-    break;
-  }
+  _mapView.overrideUserInterfaceStyle = LuggInterfaceStyleFromTheme(_theme);
 }
 
 - (void)setMinZoom:(double)minZoom {
@@ -1125,9 +1135,11 @@ static NSString *const kDemoMapId = @"DEMO_MAP_ID";
     return;
 
   float targetZoom = zoom > 0 ? (float)zoom : _mapView.camera.zoom;
-  GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:latitude
-                                                          longitude:longitude
-                                                               zoom:targetZoom];
+  GMSCameraPosition *camera = [GMSCameraPosition
+      cameraWithTarget:CLLocationCoordinate2DMake(latitude, longitude)
+                  zoom:targetZoom
+               bearing:_mapView.camera.bearing
+          viewingAngle:_mapView.camera.viewingAngle];
   if (duration < 0) {
     [_mapView animateToCameraPosition:camera];
   } else if (duration > 0) {

package/ios/core/GoogleStaticMapProvider.h

@@ -0,0 +1,21 @@
+#import "StaticMapProviderBase.h"
+#import <GoogleMaps/GoogleMaps.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Static Google map. The Google Maps SDK has no async snapshotter, so the
+ * base map briefly warms up on a live, tiles-only GMSMapView inserted below
+ * the overlays, then is swapped with a rendered image and the map view is
+ * pooled for reuse. Markers and shapes are overlay views (shared with
+ * Apple static maps) that reveal with the base map, so the warmup map
+ * never renders its own markers. Warmup cost scales with how many static
+ * maps mount at once - bound that with list props (windowSize etc.).
+ */
+@interface GoogleStaticMapProvider : StaticMapProviderBase <GMSMapViewDelegate>
+
+@property(nonatomic, copy, nullable) NSString *mapId;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/core/GoogleStaticMapProvider.mm

@@ -0,0 +1,213 @@
+#import "GoogleStaticMapProvider.h"
+
+#import "../extensions/UIView+Snapshot.h"
+#import "GoogleMapProvider.h"
+
+// Static maps churn through GMSMapViews as list rows warm up, and both
+// creating one and tearing one down are expensive main-thread operations
+// (renderer setup/teardown). Detached map views are pooled and reused so a
+// warmup usually only costs a camera move plus tile load. Keyed by map ID,
+// which is fixed at GMSMapView creation.
+static const NSUInteger kStaticMapViewPoolCapacity = 6;
+
+static NSMutableDictionary<NSString *, NSMutableArray<GMSMapView *> *> *
+StaticMapViewPool(void) {
+  static NSMutableDictionary<NSString *, NSMutableArray<GMSMapView *> *> *pool;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    pool = [NSMutableDictionary dictionary];
+    [[NSNotificationCenter defaultCenter]
+        addObserverForName:UIApplicationDidReceiveMemoryWarningNotification
+                    object:nil
+                     queue:[NSOperationQueue mainQueue]
+                usingBlock:^(NSNotification *notification) {
+                  [pool removeAllObjects];
+                }];
+  });
+  return pool;
+}
+
+static GMSMapView *_Nullable DequeueStaticMapView(NSString *mapId) {
+  NSMutableArray<GMSMapView *> *views = StaticMapViewPool()[mapId];
+  GMSMapView *mapView = views.lastObject;
+  [views removeLastObject];
+  return mapView;
+}
+
+static void EnqueueStaticMapView(NSString *mapId, GMSMapView *mapView) {
+  NSMutableDictionary<NSString *, NSMutableArray<GMSMapView *> *> *pool =
+      StaticMapViewPool();
+  NSMutableArray<GMSMapView *> *views = pool[mapId];
+  if (!views) {
+    views = [NSMutableArray array];
+    pool[mapId] = views;
+  }
+  if (views.count >= kStaticMapViewPoolCapacity)
+    return;
+  [views addObject:mapView];
+}
+
+@implementation GoogleStaticMapProvider {
+  GMSMapView *_warmupMapView;
+  BOOL _tilesRendered;
+  BOOL _swapScheduled;
+}
+
+#pragma mark - StaticMapProviderBase
+
+- (MKMapRect)mapRectForSize:(CGSize)size {
+  // GMSMapView shows the world 256 * 2^zoom points wide, centered on the
+  // camera target - the same web mercator MKMapPoint uses, so overlays
+  // project onto the warmed-up tiles exactly
+  double zoom =
+      MAX(MIN(self.zoom, (double)kGMSMaxZoomLevel), (double)kGMSMinZoomLevel);
+  double mapPointsPerPoint = MKMapSizeWorld.width / (256.0 * pow(2.0, zoom));
+  double width = size.width * mapPointsPerPoint;
+  double height = size.height * mapPointsPerPoint;
+  MKMapPoint center = MKMapPointForCoordinate(self.coordinate);
+  return MKMapRectMake(center.x - width / 2, center.y - height / 2, width,
+                       height);
+}
+
+- (UIView *)newDefaultMarkerOverlayView {
+  return
+      [[UIImageView alloc] initWithImage:[GMSMarker markerImageWithColor:nil]];
+}
+
+// Inverse of mapRectForSize
+- (double)zoomForMapPointsPerPoint:(double)mapPointsPerPoint {
+  double zoom = log2(MKMapSizeWorld.width / (256.0 * mapPointsPerPoint));
+  return MAX(MIN(zoom, (double)kGMSMaxZoomLevel), (double)kGMSMinZoomLevel);
+}
+
+- (void)renderBaseMap {
+  if (_warmupMapView) {
+    // Retry a swap that couldn't run (e.g. view was off-window)
+    [self scheduleSwap];
+    return;
+  }
+  [self startWarmup];
+}
+
+- (void)cancelBaseRender {
+  [self destroyWarmupMapView];
+}
+
+#pragma mark - Warmup
+
+// "" resolves to the demo map ID (see LuggGMSMapIDFromString), so both
+// share a pool bucket
+- (NSString *)poolKey {
+  return self.mapId.length > 0 ? self.mapId : @"DEMO_MAP_ID";
+}
+
+- (void)startWarmup {
+  UIView *wrapperView = self.wrapperView;
+  if (!wrapperView)
+    return;
+
+  _tilesRendered = NO;
+
+  GMSMapView *mapView = DequeueStaticMapView([self poolKey]);
+  if (mapView) {
+    mapView.frame = wrapperView.bounds;
+    [mapView moveCamera:[GMSCameraUpdate setTarget:self.coordinate
+                                              zoom:(float)self.zoom]];
+  } else {
+    GMSCameraPosition *camera =
+        [GMSCameraPosition cameraWithLatitude:self.coordinate.latitude
+                                    longitude:self.coordinate.longitude
+                                         zoom:(float)self.zoom];
+
+    GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
+    options.frame = wrapperView.bounds;
+    options.camera = camera;
+    options.mapID = LuggGMSMapIDFromString(self.mapId);
+
+    mapView = [[GMSMapView alloc] initWithOptions:options];
+  }
+
+  mapView.autoresizingMask =
+      UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+  mapView.delegate = self;
+  mapView.userInteractionEnabled = NO;
+  mapView.preferredFrameRate = kGMSFrameRateConservative;
+  mapView.paddingAdjustmentBehavior = kGMSMapViewPaddingAdjustmentBehaviorNever;
+  // Frames the camera like the inset-shifted projection (and clears stale
+  // padding on pooled views)
+  mapView.padding = self.edgeInsets;
+  mapView.mapType = LuggGMSMapTypeFromMapType(self.mapType);
+  mapView.overrideUserInterfaceStyle = LuggInterfaceStyleFromTheme(self.theme);
+
+  _warmupMapView = mapView;
+  [wrapperView insertSubview:mapView atIndex:0];
+}
+
+- (void)destroyWarmupMapView {
+  if (!_warmupMapView)
+    return;
+  _warmupMapView.delegate = nil;
+  [_warmupMapView removeFromSuperview];
+  EnqueueStaticMapView([self poolKey], _warmupMapView);
+  _warmupMapView = nil;
+}
+
+// Once tiles are fully rendered, swap the live map with its image and
+// release the map view. The image render and map teardown are expensive,
+// so they run outside scroll tracking; the live map keeps displaying (and
+// loading tiles) until then.
+- (void)scheduleSwap {
+  if (_swapScheduled || !_warmupMapView || !_tilesRendered ||
+      !_warmupMapView.window)
+    return;
+
+  _swapScheduled = YES;
+  __weak GoogleStaticMapProvider *weakSelf = self;
+  [[NSRunLoop mainRunLoop] performInModes:@[ NSDefaultRunLoopMode ]
+                                    block:^{
+                                      GoogleStaticMapProvider *strongSelf =
+                                          weakSelf;
+                                      if (!strongSelf)
+                                        return;
+                                      strongSelf->_swapScheduled = NO;
+                                      [strongSelf performSwap];
+                                    }];
+}
+
+- (void)performSwap {
+  // Tiles can invalidate (or the view leave the window) between scheduling
+  // and this runloop pass; the next tile callback or resumeAnimations
+  // retries
+  if (!_warmupMapView || !_tilesRendered || !_warmupMapView.window)
+    return;
+
+  UIImageView *imageView = [_warmupMapView lugg_snapshotImageView];
+  if (!imageView)
+    return;
+
+  [self displayBaseImage:imageView.image fromCache:NO];
+  [self destroyWarmupMapView];
+}
+
+#pragma mark - GMSMapViewDelegate
+
+- (void)mapViewDidStartTileRendering:(GMSMapView *)mapView {
+  _tilesRendered = NO;
+}
+
+- (void)mapViewDidFinishTileRendering:(GMSMapView *)mapView {
+  _tilesRendered = YES;
+  // The visible warmup map is fully rendered; show the overlays now
+  // instead of waiting for the swap, which is deferred while scrolling
+  [self revealOverlays];
+  [self scheduleSwap];
+}
+
+- (void)mapViewSnapshotReady:(GMSMapView *)mapView {
+  // Stable per the SDK: tiles loaded, labels and overlays rendered
+  _tilesRendered = YES;
+  [self revealOverlays];
+  [self scheduleSwap];
+}
+
+@end