@lugg/maps 1.0.0-beta.17 → 1.0.0-beta.19

package/ios/core/AppleMapProvider.mm

@@ -145,6 +145,7 @@ static double tileToLng(NSInteger x, NSInteger z) {
 }
 
 @synthesize delegate = _delegate;
+@synthesize staticMode = _staticMode;
 
 - (instancetype)init {
   if (self = [super init]) {
@@ -182,6 +183,10 @@ static double tileToLng(NSInteger x, NSInteger z) {
   _mapView.delegate = self;
   _mapView.insetsLayoutMarginsFromSafeArea = NO;
 
+  if (_staticMode) {
+    _mapView.userInteractionEnabled = NO;
+  }
+
   [self applyZoomRange];
 
   _tapGesture =
@@ -212,6 +217,11 @@ static double tileToLng(NSInteger x, NSInteger z) {
 }
 
 - (void)destroy {
+  [self destroyMapView];
+  _isMapReady = NO;
+}
+
+- (void)destroyMapView {
   [self dismissNonBubbledCallout];
   [self stopEdgeInsetsAnimation];
   if (_tapGesture) {
@@ -222,9 +232,9 @@ static double tileToLng(NSInteger x, NSInteger z) {
     [_mapView removeGestureRecognizer:_longPressGesture];
     _longPressGesture = nil;
   }
+  _mapView.delegate = nil;
   [_mapView removeFromSuperview];
   _mapView = nil;
-  _isMapReady = NO;
 }
 
 #pragma mark - Props
@@ -342,33 +352,36 @@ static MKPointOfInterestCategory poiCategoryFromString(NSString *string) {
   return map[string];
 }
 
-- (void)applyPoiFilter {
-  if (!_poiEnabled) {
-    _mapView.pointOfInterestFilter =
-        MKPointOfInterestFilter.filterExcludingAllCategories;
-    return;
+MKPointOfInterestFilter *_Nullable LuggPointOfInterestFilter(
+    BOOL poiEnabled, LuggMapViewPoiFilterMode filterMode,
+    NSArray<NSString *> *filterCategories) {
+  if (!poiEnabled) {
+    return MKPointOfInterestFilter.filterExcludingAllCategories;
   }
-  if (_poiFilterCategories.count > 0) {
+  if (filterCategories.count > 0) {
     NSMutableArray<MKPointOfInterestCategory> *categories =
         [NSMutableArray array];
-    for (NSString *name in _poiFilterCategories) {
+    for (NSString *name in filterCategories) {
       MKPointOfInterestCategory category = poiCategoryFromString(name);
       if (category) {
         [categories addObject:category];
       }
     }
     if (categories.count > 0) {
-      if (_poiFilterMode == LuggMapViewPoiFilterMode::Excluding) {
-        _mapView.pointOfInterestFilter = [[MKPointOfInterestFilter alloc]
+      if (filterMode == LuggMapViewPoiFilterMode::Excluding) {
+        return [[MKPointOfInterestFilter alloc]
             initExcludingCategories:categories];
-      } else {
-        _mapView.pointOfInterestFilter = [[MKPointOfInterestFilter alloc]
-            initIncludingCategories:categories];
       }
-      return;
+      return
+          [[MKPointOfInterestFilter alloc] initIncludingCategories:categories];
     }
   }
-  _mapView.pointOfInterestFilter = nil;
+  return nil;
+}
+
+- (void)applyPoiFilter {
+  _mapView.pointOfInterestFilter = LuggPointOfInterestFilter(
+      _poiEnabled, _poiFilterMode, _poiFilterCategories);
 }
 
 - (void)setInsetAdjustment:(LuggMapViewInsetAdjustment)insetAdjustment {
@@ -399,26 +412,25 @@ static MKPointOfInterestCategory poiCategoryFromString(NSString *string) {
   [self applyPoiFilter];
 }
 
-- (void)setMapType:(LuggMapViewMapType)mapType {
+MKMapType LuggMKMapTypeFromMapType(LuggMapViewMapType mapType) {
   switch (mapType) {
   case LuggMapViewMapType::Satellite:
-    _mapView.mapType = MKMapTypeSatellite;
-    break;
+    return MKMapTypeSatellite;
   case LuggMapViewMapType::Terrain:
-    _mapView.mapType = MKMapTypeStandard;
-    break;
+    return MKMapTypeStandard;
   case LuggMapViewMapType::Hybrid:
-    _mapView.mapType = MKMapTypeHybrid;
-    break;
+    return MKMapTypeHybrid;
   case LuggMapViewMapType::MutedStandard:
-    _mapView.mapType = MKMapTypeMutedStandard;
-    break;
+    return MKMapTypeMutedStandard;
   default:
-    _mapView.mapType = MKMapTypeStandard;
-    break;
+    return MKMapTypeStandard;
   }
 }
 
+- (void)setMapType:(LuggMapViewMapType)mapType {
+  _mapView.mapType = LuggMKMapTypeFromMapType(mapType);
+}
+
 - (void)setTheme:(LuggMapViewTheme)theme {
   switch (theme) {
   case LuggMapViewTheme::Dark:
@@ -836,7 +848,8 @@ static MKPointOfInterestCategory poiCategoryFromString(NSString *string) {
         renderer.strokeColors = colors;
       }
       renderer.animatedOptions = polylineView.animatedOptions;
-      renderer.animated = polylineView.animated;
+      // Static maps snapshot an arbitrary frame; render the full polyline
+      renderer.animated = polylineView.animated && !_staticMode;
       polylineView.renderer = renderer;
       return renderer;
     }
@@ -1365,7 +1378,7 @@ static MKPointOfInterestCategory poiCategoryFromString(NSString *string) {
     renderer.strokeColors =
         polylineView.strokeColors.count > 1 ? polylineView.strokeColors : nil;
     renderer.animatedOptions = polylineView.animatedOptions;
-    renderer.animated = polylineView.animated;
+    renderer.animated = polylineView.animated && !_staticMode;
     return;
   }
 

package/ios/core/AppleStaticMapProvider.h

@@ -0,0 +1,14 @@
+#import "StaticMapProviderBase.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Static Apple map rendered with MKMapSnapshotter. The base map renders
+ * fully asynchronously (no live MKMapView is ever created), so static maps
+ * keep loading while the user scrolls without blocking the main thread.
+ */
+@interface AppleStaticMapProvider : StaticMapProviderBase
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/core/AppleStaticMapProvider.mm

@@ -0,0 +1,146 @@
+#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;
+}
+
+- (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/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
@@ -191,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 {
@@ -216,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 {

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,207 @@
+#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]];
+}
+
+- (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