@lugg/maps 1.0.0-beta.8 → 1.0.0

package/android/src/main/java/com/luggmaps/core/PolylineAnimator.kt

@@ -15,18 +15,44 @@ import kotlin.math.min
 class PolylineAnimator {
   companion object {
     private const val MAX_ANIMATION_SPANS = 16
+    private const val MAX_GRADIENT_SPANS = 512
+
+    // Cap polyline updates to ~60fps; every update crosses Binder into the
+    // maps renderer, and 120Hz displays double that churn (CONSUMER-APP-44Y)
+    private const val MIN_UPDATE_INTERVAL_NANOS = 16_000_000L
   }
 
   var polyline: Polyline? = null
   var coordinates: List<LatLng> = emptyList()
     set(value) {
+      // Structural equality: Fabric delivers a new list instance on every
+      // commit, so identity checks never match and the full route would be
+      // re-parceled across Binder even when unchanged
+      if (field == value) return
       field = value
+      dirty = true
       if (animated && animator != null) {
         computeCumulativeDistances()
       }
     }
   var strokeColors: List<Int> = listOf(Color.BLACK)
+    set(value) {
+      if (field == value) return
+      field = value
+      dirty = true
+    }
   var strokeWidth: Float = 1f
+    set(value) {
+      if (field == value) return
+      field = value
+      polyline?.width = value
+    }
+  var zIndex: Float = 0f
+    set(value) {
+      if (field == value) return
+      field = value
+      polyline?.zIndex = value
+    }
   var animatedOptions: AnimatedOptions = AnimatedOptions()
     set(value) {
       if (field == value) return
@@ -50,8 +76,11 @@ class PolylineAnimator {
 
   private var animator: ValueAnimator? = null
   private var animationProgress: Float = 0f
+  private var lastUpdateNanos: Long = 0L
+  private var lastAppliedColor: Int? = null
   private var cumulativeDistances: FloatArray = floatArrayOf()
   private var totalLength: Float = 0f
+  private var dirty: Boolean = true
 
   // Reusable collections to avoid per-frame allocations
   private val reusablePoints = ArrayList<LatLng>()
@@ -72,16 +101,21 @@ class PolylineAnimator {
 
   fun update() {
     if (animated) return
+    if (!dirty) return
 
     val poly = polyline ?: return
     if (coordinates.size < 2) return
 
+    dirty = false
     poly.points = coordinates
 
     if (strokeColors.size > 1) {
-      poly.setSpans(createGradientSpans())
+      applyGradientSpans(poly)
+      lastAppliedColor = null
     } else {
-      poly.color = strokeColors.firstOrNull() ?: Color.BLACK
+      val color = strokeColors.firstOrNull() ?: Color.BLACK
+      poly.color = color
+      lastAppliedColor = color
     }
   }
 
@@ -100,6 +134,9 @@ class PolylineAnimator {
       interpolator = LinearInterpolator()
       addUpdateListener { animation ->
         animationProgress = animation.animatedValue as Float
+        val now = System.nanoTime()
+        if (now - lastUpdateNanos < MIN_UPDATE_INTERVAL_NANOS) return@addUpdateListener
+        lastUpdateNanos = now
         updateAnimatedPolyline()
       }
       start()
@@ -171,6 +208,7 @@ class PolylineAnimator {
   private fun stopAnimation() {
     animator?.cancel()
     animator = null
+    lastUpdateNanos = 0L
   }
 
   fun pause() {
@@ -209,8 +247,10 @@ class PolylineAnimator {
     }
 
     if (headDist <= tailDist) {
-      poly.points = listOf(coordinates.firstOrNull() ?: LatLng(0.0, 0.0))
+      val point = coordinates.firstOrNull() ?: LatLng(0.0, 0.0)
       poly.color = strokeColors.firstOrNull() ?: Color.BLACK
+      lastAppliedColor = null
+      poly.points = listOf(point, point)
       return
     }
 
@@ -234,11 +274,13 @@ class PolylineAnimator {
 
     if (reusablePoints.size < 2) return
 
-    poly.points = ArrayList(reusablePoints)
-
-    if (strokeColors.size <= 1) {
+    if (strokeColors.size > 1) {
+      // Clear spans before setting points to prevent IndexOutOfBoundsException
+      // when the new points list is shorter than what existing spans reference
       poly.color = strokeColors.firstOrNull() ?: Color.BLACK
-    } else {
+      lastAppliedColor = null
+      poly.points = reusablePoints
+
       val segmentCount = reusablePoints.size - 1
       val spanCount = min(segmentCount, MAX_ANIMATION_SPANS)
       val segmentsPerSpan = segmentCount.toDouble() / spanCount
@@ -250,16 +292,28 @@ class PolylineAnimator {
         reusableSpans.add(StyleSpan(StrokeStyle.colorBuilder(color).build(), segmentsPerSpan))
       }
       poly.setSpans(reusableSpans)
+    } else {
+      val color = strokeColors.firstOrNull() ?: Color.BLACK
+      if (lastAppliedColor != color) {
+        poly.color = color
+        lastAppliedColor = color
+      }
+      poly.points = reusablePoints
     }
   }
 
-  private fun createGradientSpans(): List<StyleSpan> {
+  private fun applyGradientSpans(poly: Polyline) {
     val segmentCount = coordinates.size - 1
-    return (0 until segmentCount).map { i ->
-      val position = i.toFloat() / segmentCount
+    val spanCount = min(segmentCount, MAX_GRADIENT_SPANS)
+    val segmentsPerSpan = segmentCount.toDouble() / spanCount
+
+    reusableSpans.clear()
+    for (i in 0 until spanCount) {
+      val position = (i + 0.5f) / spanCount
       val color = colorAtGradientPosition(position)
-      StyleSpan(StrokeStyle.colorBuilder(color).build())
+      reusableSpans.add(StyleSpan(StrokeStyle.colorBuilder(color).build(), segmentsPerSpan))
     }
+    poly.setSpans(reusableSpans)
   }
 
   private fun colorAtGradientPosition(position: Float): Int {

package/ios/LuggMapView.mm

@@ -7,7 +7,9 @@
 #import "LuggPolylineView.h"
 #import "LuggTileOverlayView.h"
 #import "core/AppleMapProvider.h"
+#import "core/AppleStaticMapProvider.h"
 #import "core/GoogleMapProvider.h"
+#import "core/GoogleStaticMapProvider.h"
 #import "core/MapProviderDelegate.h"
 #import "events/CameraIdleEvent.h"
 #import "events/CameraMoveEvent.h"
@@ -25,6 +27,19 @@
 using namespace facebook::react;
 using namespace luggmaps::events;
 
+// Static snapshots cached across view recycling, keyed by the user-provided
+// staticKey plus the map settings that affect appearance.
+static NSCache<NSString *, UIImage *> *StaticSnapshotCache(void) {
+  static NSCache<NSString *, UIImage *> *cache;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    cache = [[NSCache alloc] init];
+    cache.countLimit = 100;
+    cache.totalCostLimit = 64 * 1024 * 1024; // bytes
+  });
+  return cache;
+}
+
 @interface LuggMapView () <RCTLuggMapViewViewProtocol, MapProviderDelegate>
 @end
 
@@ -39,6 +54,10 @@ using namespace luggmaps::events;
   BOOL _scrollEnabled;
   BOOL _rotateEnabled;
   BOOL _pitchEnabled;
+  BOOL _compassEnabled;
+  BOOL _staticMode;
+  NSString *_staticKey;
+  BOOL _staticSnapshotDone;
   BOOL _userLocationEnabled;
   LuggMapViewMapType _mapType;
   LuggMapViewTheme _theme;
@@ -68,6 +87,9 @@ using namespace luggmaps::events;
     _scrollEnabled = YES;
     _rotateEnabled = YES;
     _pitchEnabled = YES;
+    _compassEnabled = YES;
+    _staticMode = NO;
+    _staticKey = @"";
     _userLocationEnabled = NO;
     _poiEnabled = NO;
     _poiFilterMode = LuggMapViewPoiFilterMode::Including;
@@ -168,17 +190,118 @@ using namespace luggmaps::events;
   [super didMoveToWindow];
   if (self.window) {
     if (!_provider && _mapWrapperView) {
-      [self initializeProvider];
+      if (_staticMode) {
+        [self startStaticContent];
+      } else {
+        [self initializeProvider];
+      }
     }
     [_provider resumeAnimations];
   } else {
+    // A static map mid-warmup may hold an expensive live map view. Destroy
+    // it off-window and re-render on return instead of letting paused maps
+    // pile up across screen switches and all resume at once
+    if (_staticMode && _provider && !_staticSnapshotDone) {
+      [_provider destroy];
+      _provider = nil;
+      _initialized = NO;
+    }
     [_provider pauseAnimations];
   }
 }
 
+// Shown while the map warms up, until the live map or snapshot covers it
+- (void)applyStaticPlaceholderBackground {
+  const auto &viewProps =
+      *std::static_pointer_cast<LuggMapViewProps const>(_props);
+  if (viewProps.backgroundColor) {
+    // A user-provided background acts as the placeholder
+    return;
+  }
+
+  switch (_theme) {
+  case LuggMapViewTheme::Dark:
+    _mapWrapperView.overrideUserInterfaceStyle = UIUserInterfaceStyleDark;
+    break;
+  case LuggMapViewTheme::Light:
+    _mapWrapperView.overrideUserInterfaceStyle = UIUserInterfaceStyleLight;
+    break;
+  default:
+    _mapWrapperView.overrideUserInterfaceStyle =
+        UIUserInterfaceStyleUnspecified;
+    break;
+  }
+  _mapWrapperView.backgroundColor = UIColor.secondarySystemBackgroundColor;
+}
+
+- (nullable NSString *)staticSnapshotCacheKey {
+  if (_staticKey.length == 0 || !_mapWrapperView)
+    return nil;
+
+  CGSize size = _mapWrapperView.bounds.size;
+  if (size.width <= 0 || size.height <= 0)
+    return nil;
+
+  // 'system' theme snapshots depend on the current appearance
+  NSInteger style = _theme == LuggMapViewTheme::System
+                        ? (NSInteger)self.traitCollection.userInterfaceStyle
+                        : -(NSInteger)_theme;
+
+  // Camera is part of the key so a reused staticKey with a different
+  // location/zoom can't serve a stale snapshot. The provider's camera (when
+  // available) reflects imperative camera changes, so a re-rendered
+  // snapshot is keyed on what it actually shows.
+  const auto &viewProps =
+      *std::static_pointer_cast<LuggMapViewProps const>(_props);
+  double latitude = viewProps.initialCoordinate.latitude;
+  double longitude = viewProps.initialCoordinate.longitude;
+  double zoom = viewProps.initialZoom;
+  if ([_provider isKindOfClass:[StaticMapProviderBase class]]) {
+    StaticMapProviderBase *staticProvider = (StaticMapProviderBase *)_provider;
+    latitude = staticProvider.coordinate.latitude;
+    longitude = staticProvider.coordinate.longitude;
+    zoom = staticProvider.zoom;
+  }
+
+  return [NSString
+      stringWithFormat:@"%@|%d|%@|%d|%ld|%.0fx%.0f|%.6f,%.6f,%.2f|%@",
+                       _staticKey, (int)_providerType, _mapId, (int)_mapType,
+                       (long)style, size.width, size.height, latitude,
+                       longitude, zoom, NSStringFromUIEdgeInsets(_edgeInsets)];
+}
+
+- (void)startStaticContent {
+  [self applyStaticPlaceholderBackground];
+
+  // Both static providers render fully async: the placeholder shows until
+  // the snapshotter (Apple) or a brief live-map warmup (Google) delivers
+  // the base map, which reveals together with the marker/shape overlays
+  [self initializeProvider];
+}
+
+// staticKey identifies the map's content; when it changes (e.g. a recycled
+// list row bound to a new item), any live warmup or displayed snapshot is
+// stale and the static lifecycle restarts. Without this, an in-flight
+// warmup caches the old item's map under the new key.
+- (void)resetStaticContent {
+  _staticSnapshotDone = NO;
+
+  if (_provider) {
+    [_provider destroy];
+    _provider = nil;
+    _initialized = NO;
+  }
+
+  if (self.window) {
+    [self startStaticContent];
+  }
+}
+
 - (void)prepareForRecycle {
   [super prepareForRecycle];
 
+  _staticSnapshotDone = NO;
+
   [_provider destroy];
   _provider = nil;
   _mapWrapperView = nil;
@@ -195,7 +318,12 @@ using namespace luggmaps::events;
       *std::static_pointer_cast<LuggMapViewProps const>(_props);
 
   if (_providerType == LuggMapViewProvider::Apple) {
-    _provider = [[AppleMapProvider alloc] init];
+    _provider = _staticMode ? [[AppleStaticMapProvider alloc] init]
+                            : [[AppleMapProvider alloc] init];
+  } else if (_staticMode) {
+    GoogleStaticMapProvider *google = [[GoogleStaticMapProvider alloc] init];
+    google.mapId = _mapId;
+    _provider = google;
   } else {
     GoogleMapProvider *google = [[GoogleMapProvider alloc] init];
     google.mapId = _mapId;
@@ -203,6 +331,7 @@ using namespace luggmaps::events;
   }
 
   _provider.delegate = self;
+  _provider.staticMode = _staticMode;
 
   CLLocationCoordinate2D coordinate =
       CLLocationCoordinate2DMake(viewProps.initialCoordinate.latitude,
@@ -212,6 +341,16 @@ using namespace luggmaps::events;
                initialCoordinate:coordinate
                      initialZoom:viewProps.initialZoom];
 
+  // After initializeMapInView so the cache key reads the provider's camera;
+  // the base render is async and picks up the cached image
+  if (_staticMode) {
+    NSString *cacheKey = [self staticSnapshotCacheKey];
+    if (cacheKey) {
+      ((StaticMapProviderBase *)_provider).cachedBaseImage =
+          [StaticSnapshotCache() objectForKey:cacheKey];
+    }
+  }
+
   // Apply cached props after map view is created
   [self applyProps];
   [_provider setEdgeInsets:_edgeInsets oldEdgeInsets:UIEdgeInsetsZero];
@@ -242,6 +381,19 @@ using namespace luggmaps::events;
   ReadyEvent::emit<LuggMapViewEventEmitter>(_eventEmitter);
 }
 
+- (void)mapProviderDidFinishStaticSnapshot {
+  _staticSnapshotDone = YES;
+}
+
+- (void)mapProviderDidCaptureStaticImage:(UIImage *)image {
+  NSString *key = [self staticSnapshotCacheKey];
+  if (key) {
+    NSUInteger cost = (NSUInteger)(image.size.width * image.scale *
+                                   image.size.height * image.scale * 4);
+    [StaticSnapshotCache() setObject:image forKey:key cost:cost];
+  }
+}
+
 - (void)mapProviderDidMoveCamera:(double)latitude
                        longitude:(double)longitude
                             zoom:(double)zoom
@@ -281,6 +433,7 @@ using namespace luggmaps::events;
   [_provider setScrollEnabled:_scrollEnabled];
   [_provider setRotateEnabled:_rotateEnabled];
   [_provider setPitchEnabled:_pitchEnabled];
+  [_provider setCompassEnabled:_compassEnabled];
   [_provider setUserLocationEnabled:_userLocationEnabled];
   [_provider setMapType:_mapType];
   [_provider setTheme:_theme];
@@ -300,6 +453,12 @@ using namespace luggmaps::events;
       *std::static_pointer_cast<LuggMapViewProps const>(_props);
 
   _providerType = newViewProps.provider;
+  _staticMode = newViewProps.staticMode;
+
+  NSString *newStaticKey =
+      [NSString stringWithUTF8String:newViewProps.staticKey.c_str()];
+  BOOL staticKeyChanged = ![newStaticKey isEqualToString:_staticKey];
+  _staticKey = newStaticKey;
 
   NSString *newMapId =
       [NSString stringWithUTF8String:newViewProps.mapId.c_str()];
@@ -323,6 +482,10 @@ using namespace luggmaps::events;
     _pitchEnabled = newViewProps.pitchEnabled;
     [_provider setPitchEnabled:_pitchEnabled];
   }
+  if (newViewProps.compassEnabled != prevViewProps.compassEnabled) {
+    _compassEnabled = newViewProps.compassEnabled;
+    [_provider setCompassEnabled:_compassEnabled];
+  }
   if (newViewProps.userLocationEnabled != prevViewProps.userLocationEnabled) {
     _userLocationEnabled = newViewProps.userLocationEnabled;
     [_provider setUserLocationEnabled:_userLocationEnabled];
@@ -374,6 +537,11 @@ using namespace luggmaps::events;
   }
 
   [super updateProps:props oldProps:oldProps];
+
+  // After super so the snapshot cache key sees the new camera props
+  if (staticKeyChanged && _staticMode && _mapWrapperView) {
+    [self resetStaticContent];
+  }
 }
 
 #pragma mark - Commands

package/ios/LuggMapWrapperView.h

@@ -4,6 +4,11 @@
 NS_ASSUME_NONNULL_BEGIN
 
 @interface LuggMapWrapperView : RCTViewComponentView
+
+/// Called after layout; lets the static snapshotter start (or restart)
+/// once the wrapper has a real size, since a snapshot can't autoresize
+@property(nonatomic, copy, nullable) void (^layoutHandler)(void);
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/LuggMapWrapperView.mm

@@ -29,6 +29,24 @@ using namespace facebook::react;
   return self;
 }
 
+- (void)layoutSubviews {
+  [super layoutSubviews];
+  if (self.layoutHandler) {
+    self.layoutHandler();
+  }
+}
+
+- (void)prepareForRecycle {
+  [super prepareForRecycle];
+
+  // Static placeholder styling is applied outside of props
+  // (LuggMapView applyStaticPlaceholderBackground) and would otherwise
+  // leak into the next map that reuses this recycled view
+  self.backgroundColor = nil;
+  self.overrideUserInterfaceStyle = UIUserInterfaceStyleUnspecified;
+  self.layoutHandler = nil;
+}
+
 Class<RCTComponentViewProtocol> LuggMapWrapperViewCls(void) {
   return LuggMapWrapperView.class;
 }

package/ios/LuggMarkerView.mm

@@ -287,6 +287,8 @@ using namespace luggmaps::events;
   _iconView.layer.anchorPoint = CGPointMake(0.5, 0.5);
   _iconView.frame = CGRectMake(0, 0, _iconView.bounds.size.width,
                                _iconView.bounds.size.height);
+  // Static providers hide the icon view until positioned
+  _iconView.hidden = NO;
 }
 
 - (void)showCallout {

package/ios/core/AppleMapProvider.h

@@ -3,6 +3,14 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+/// POI filter for the given props, shared by the live map view and the
+/// static snapshotter. Returns nil for "show everything".
+MKPointOfInterestFilter *_Nullable LuggPointOfInterestFilter(
+    BOOL poiEnabled, facebook::react::LuggMapViewPoiFilterMode filterMode,
+    NSArray<NSString *> *filterCategories);
+
+MKMapType LuggMKMapTypeFromMapType(facebook::react::LuggMapViewMapType mapType);
+
 @interface LuggAppleMapViewContent : MKMapView
 @end
 

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
@@ -245,6 +255,10 @@ static double tileToLng(NSInteger x, NSInteger z) {
   _mapView.pitchEnabled = enabled;
 }
 
+- (void)setCompassEnabled:(BOOL)enabled {
+  _mapView.showsCompass = enabled;
+}
+
 - (void)setUserLocationEnabled:(BOOL)enabled {
   _mapView.showsUserLocation = enabled;
 }
@@ -338,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 {
@@ -395,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:
@@ -832,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;
     }
@@ -1361,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;
   }
 
@@ -1774,11 +1791,11 @@ static MKPointOfInterestCategory poiCategoryFromString(NSString *string) {
   } else if (duration > 0) {
     CLLocationCoordinate2D center =
         CLLocationCoordinate2DMake(latitude, longitude);
-    MKCoordinateRegion region = [_mapView regionForCenterCoordinate:center
-                                                          zoomLevel:targetZoom];
+    MKMapCamera *camera = [_mapView cameraForCenterCoordinate:center
+                                                    zoomLevel:targetZoom];
     [UIView animateWithDuration:duration / 1000.0
                      animations:^{
-                       [self->_mapView setRegion:region animated:NO];
+                       [self->_mapView setCamera:camera animated:NO];
                      }];
   } else {
     [_mapView

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