@lugg/maps 1.0.0 → 1.1.1

package/LuggMaps.podspec

@@ -16,7 +16,20 @@ Pod::Spec.new do |s|
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
   s.private_header_files = "ios/**/*.h"
 
-  s.dependency "GoogleMaps"
+  # `$LuggMapsGoogleEnabled = false` in the Podfile drops the Google Maps SDK (Apple Maps only)
+  google_enabled = defined?($LuggMapsGoogleEnabled) ? $LuggMapsGoogleEnabled : true
+  s.pod_target_xcconfig = {
+    "GCC_PREPROCESSOR_DEFINITIONS" => "$(inherited) LUGG_GOOGLE_MAPS_ENABLED=#{google_enabled ? 1 : 0}"
+  }
+  if google_enabled
+    s.dependency "GoogleMaps"
+  else
+    unless defined?($LuggMapsGoogleDisabledLogged)
+      Pod::UI.puts "[LuggMaps] Google Maps SDK is disabled, Apple Maps only.".yellow
+      $LuggMapsGoogleDisabledLogged = true
+    end
+    s.exclude_files = "ios/core/Google*", "ios/core/GMS*"
+  end
   s.frameworks = "MapKit"
 
   install_modules_dependencies(s)

package/README.md

@@ -40,6 +40,16 @@ import { MapView, Marker } from '@lugg/maps';
 
 Google Maps needs an API key on every platform. See [Installation](https://maps.lodev09.com/installation) for Expo, iOS, Android, and web setup.
 
+## AI Skills
+
+Skills give your AI coding agent working knowledge of `@lugg/maps` - setup, camera control, markers and callouts, static maps, advanced patterns, and platform limitations - so it generates correct code without you explaining the library each time.
+
+```sh
+npx skills add lugg/maps
+```
+
+This installs the **Maps Usage** skill into your project. The source lives in [`skills/maps-usage`](skills/maps-usage).
+
 ## Contributing
 
 - [Development workflow](CONTRIBUTING.md#development-workflow)

package/android/src/main/java/com/luggmaps/LuggMapView.kt

@@ -131,7 +131,7 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
 
   // region Provider Initialization
 
-  private fun initializeProvider() {
+  private fun initializeProvider(latitude: Double = initialLatitude, longitude: Double = initialLongitude, zoom: Float = initialZoom) {
     if (provider != null || mapWrapperView == null) return
 
     if (staticMode) {
@@ -146,7 +146,7 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
 
     applyProps()
 
-    google.initializeMap(mapWrapperView!!, initialLatitude, initialLongitude, initialZoom)
+    google.initializeMap(mapWrapperView!!, latitude, longitude, zoom)
 
     // Flush children mounted before provider was created
     for (i in 0 until childCount) {
@@ -371,6 +371,19 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
     provider?.fitCoordinates(coordinates, edgeInsetsTop, edgeInsetsLeft, edgeInsetsBottom, edgeInsetsRight, duration)
   }
 
+  fun reload() {
+    val current = provider ?: return
+    val latitude = current.cameraLatitude
+    val longitude = current.cameraLongitude
+    val zoom = current.cameraZoom
+
+    current.destroy()
+    provider = null
+    if (isAttachedToWindow) {
+      initializeProvider(latitude, longitude, zoom)
+    }
+  }
+
   // endregion
 
   companion object {

package/android/src/main/java/com/luggmaps/LuggMapViewManager.kt

@@ -273,6 +273,10 @@ class LuggMapViewManager :
     )
   }
 
+  override fun reload(view: LuggMapView) {
+    view.reload()
+  }
+
   companion object {
     const val NAME = "LuggMapView"
   }

package/android/src/main/java/com/luggmaps/LuggMapWrapperView.kt

@@ -2,6 +2,7 @@ package com.luggmaps
 
 import android.annotation.SuppressLint
 import android.view.MotionEvent
+import android.view.View
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.views.view.ReactViewGroup
 
@@ -34,6 +35,14 @@ class LuggMapWrapperView(context: ThemedReactContext) : ReactViewGroup(context)
     }
   }
 
+  override fun onViewAdded(child: View) {
+    super.onViewAdded(child)
+    // A replacement map needs sizing even when Yoga's layout is unchanged.
+    if (indexOfChild(child) == 0) {
+      layoutChild(width, height)
+    }
+  }
+
   override fun onLayout(
     changed: Boolean,
     left: Int,

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

@@ -128,6 +128,7 @@ class GoogleMapProvider(private val context: Context) :
 
   // Theme
   private var theme: String = "system"
+  private var mapType: String = "standard"
 
   // Edge Insets
   private var edgeInsets: EdgeInsets = EdgeInsets()
@@ -183,7 +184,7 @@ class GoogleMapProvider(private val context: Context) :
       view.onCreate(null)
       view.onResume()
       view.getMapAsync(this)
-      wrapper.addView(view)
+      wrapper.addView(view, 0)
     }
     wrapper.onLayoutReady = null
   }
@@ -211,6 +212,9 @@ class GoogleMapProvider(private val context: Context) :
     groundOverlayToViewMap.clear()
     markerToViewMap.clear()
     wrapperView?.touchEventHandler = null
+    // The wrapper outlives the provider on reload; don't leave the dead map
+    // view in it
+    mapView?.let { wrapperView?.removeView(it) }
     wrapperView = null
     googleMap?.setOnCameraMoveStartedListener(null)
     googleMap?.setOnCameraMoveListener(null)
@@ -276,6 +280,7 @@ class GoogleMapProvider(private val context: Context) :
     applyZoomLimits()
     applyInsetAdjustment()
     applyTheme()
+    setMapType(mapType)
     applyUserLocation()
     processPendingMarkers()
     processPendingPolylines()
@@ -542,6 +547,7 @@ class GoogleMapProvider(private val context: Context) :
   }
 
   override fun setMapType(value: String) {
+    mapType = value
     googleMap?.mapType = when (value) {
       "satellite" -> GoogleMap.MAP_TYPE_SATELLITE
       "terrain" -> GoogleMap.MAP_TYPE_TERRAIN
@@ -1201,6 +1207,24 @@ class GoogleMapProvider(private val context: Context) :
 
   // endregion
 
+  // region Camera
+
+  // A static map's camera is inset-shifted (staticCameraTarget), so report
+  // the requested camera instead
+  private val liveCameraPosition: CameraPosition?
+    get() = if (staticMode) null else googleMap?.cameraPosition
+
+  override val cameraLatitude: Double
+    get() = liveCameraPosition?.target?.latitude ?: initialLatitude
+
+  override val cameraLongitude: Double
+    get() = liveCameraPosition?.target?.longitude ?: initialLongitude
+
+  override val cameraZoom: Float
+    get() = liveCameraPosition?.zoom ?: initialZoom
+
+  // endregion
+
   // region Lifecycle
 
   override fun pauseAnimations() {

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

@@ -58,6 +58,11 @@ interface MapProvider {
   fun addTileOverlayView(tileOverlayView: LuggTileOverlayView)
   fun removeTileOverlayView(tileOverlayView: LuggTileOverlayView)
 
+  // Current camera (the initial camera until the map is ready)
+  val cameraLatitude: Double
+  val cameraLongitude: Double
+  val cameraZoom: Float
+
   // Lifecycle
   fun pauseAnimations()
   fun resumeAnimations()

package/ios/LuggMapView.mm

@@ -8,8 +8,10 @@
 #import "LuggTileOverlayView.h"
 #import "core/AppleMapProvider.h"
 #import "core/AppleStaticMapProvider.h"
+#if LUGG_GOOGLE_MAPS_ENABLED
 #import "core/GoogleMapProvider.h"
 #import "core/GoogleStaticMapProvider.h"
+#endif
 #import "core/MapProviderDelegate.h"
 #import "events/CameraIdleEvent.h"
 #import "events/CameraMoveEvent.h"
@@ -311,15 +313,25 @@ static NSCache<NSString *, UIImage *> *StaticSnapshotCache(void) {
 #pragma mark - Provider Initialization
 
 - (void)initializeProvider {
-  if (_provider || !_mapWrapperView)
-    return;
-
   const auto &viewProps =
       *std::static_pointer_cast<LuggMapViewProps const>(_props);
+  [self
+      initializeProviderWithCoordinate:CLLocationCoordinate2DMake(
+                                           viewProps.initialCoordinate.latitude,
+                                           viewProps.initialCoordinate
+                                               .longitude)
+                                  zoom:viewProps.initialZoom];
+}
+
+- (void)initializeProviderWithCoordinate:(CLLocationCoordinate2D)coordinate
+                                    zoom:(double)zoom {
+  if (_provider || !_mapWrapperView)
+    return;
 
   if (_providerType == LuggMapViewProvider::Apple) {
     _provider = _staticMode ? [[AppleStaticMapProvider alloc] init]
                             : [[AppleMapProvider alloc] init];
+#if LUGG_GOOGLE_MAPS_ENABLED
   } else if (_staticMode) {
     GoogleStaticMapProvider *google = [[GoogleStaticMapProvider alloc] init];
     google.mapId = _mapId;
@@ -329,17 +341,21 @@ static NSCache<NSString *, UIImage *> *StaticSnapshotCache(void) {
     google.mapId = _mapId;
     _provider = google;
   }
+#else
+  } else {
+    NSLog(@"[LuggMaps] provider=\"google\" requested but the Google Maps SDK "
+          @"is excluded ($LuggMapsGoogleEnabled = false); using Apple Maps");
+    _provider = _staticMode ? [[AppleStaticMapProvider alloc] init]
+                            : [[AppleMapProvider alloc] init];
+  }
+#endif
 
   _provider.delegate = self;
   _provider.staticMode = _staticMode;
 
-  CLLocationCoordinate2D coordinate =
-      CLLocationCoordinate2DMake(viewProps.initialCoordinate.latitude,
-                                 viewProps.initialCoordinate.longitude);
-
   [_provider initializeMapInView:_mapWrapperView
                initialCoordinate:coordinate
-                     initialZoom:viewProps.initialZoom];
+                     initialZoom:zoom];
 
   // After initializeMapInView so the cache key reads the provider's camera;
   // the base render is async and picks up the cached image
@@ -582,6 +598,63 @@ static NSCache<NSString *, UIImage *> *StaticSnapshotCache(void) {
                   duration:duration];
 }
 
+// Loads the map again, e.g. to recover from missing tiles. A static map
+// drops its cached snapshot and renders the base map again in place.
+// Neither SDK can reload a live map's tiles, so the native map view is
+// recreated at the current camera (coordinate and zoom; heading and pitch
+// reset) with children re-added.
+- (void)reload {
+  if (_staticMode) {
+    _staticSnapshotDone = NO;
+    NSString *cacheKey = [self staticSnapshotCacheKey];
+    if (cacheKey) {
+      [StaticSnapshotCache() removeObjectForKey:cacheKey];
+    }
+    if ([_provider isKindOfClass:[StaticMapProviderBase class]]) {
+      [(StaticMapProviderBase *)_provider rerenderBaseMap];
+    }
+    return;
+  }
+
+  if (!_provider)
+    return;
+
+  CLLocationCoordinate2D coordinate = _provider.coordinate;
+  double zoom = _provider.zoom;
+  // Children keep their native marker/overlay objects from the old map;
+  // detach them so the new provider creates fresh ones on the flush
+  [self removeChildrenFromProvider];
+  [_provider destroy];
+  _provider = nil;
+  _initialized = NO;
+  [self initializeProviderWithCoordinate:coordinate zoom:zoom];
+  if ([_provider isKindOfClass:[AppleMapProvider class]]) {
+    // The captured camera already includes the previous inset offset.
+    [_provider moveCamera:coordinate.latitude
+                longitude:coordinate.longitude
+                     zoom:zoom
+                 duration:0];
+  }
+}
+
+- (void)removeChildrenFromProvider {
+  for (UIView *subview in self.subviews) {
+    if ([subview isKindOfClass:[LuggMarkerView class]]) {
+      [_provider removeMarkerView:(LuggMarkerView *)subview];
+    } else if ([subview isKindOfClass:[LuggPolylineView class]]) {
+      [_provider removePolylineView:(LuggPolylineView *)subview];
+    } else if ([subview isKindOfClass:[LuggPolygonView class]]) {
+      [_provider removePolygonView:(LuggPolygonView *)subview];
+    } else if ([subview isKindOfClass:[LuggCircleView class]]) {
+      [_provider removeCircleView:(LuggCircleView *)subview];
+    } else if ([subview isKindOfClass:[LuggGroundOverlayView class]]) {
+      [_provider removeGroundOverlayView:(LuggGroundOverlayView *)subview];
+    } else if ([subview isKindOfClass:[LuggTileOverlayView class]]) {
+      [_provider removeTileOverlayView:(LuggTileOverlayView *)subview];
+    }
+  }
+}
+
 - (void)handleCommand:(const NSString *)commandName args:(const NSArray *)args {
   RCTLuggMapViewHandleCommand(self, commandName, args);
 }

package/ios/core/AppleMapProvider.mm

@@ -15,6 +15,7 @@ using facebook::react::LuggMapViewTheme;
 #import "../extensions/MKMapView+Zoom.h"
 #import "LuggAnnotationView.h"
 #import "MKPolylineAnimator.h"
+#import "MapEdgeInsets.h"
 
 @interface AppleMarkerAnnotation : NSObject <MKAnnotation>
 @property(nonatomic, assign) CLLocationCoordinate2D coordinate;
@@ -221,6 +222,14 @@ static double tileToLng(NSInteger x, NSInteger z) {
   _isMapReady = NO;
 }
 
+- (CLLocationCoordinate2D)coordinate {
+  return _mapView.centerCoordinate;
+}
+
+- (double)zoom {
+  return _mapView.zoomLevel;
+}
+
 - (void)destroyMapView {
   [self dismissNonBubbledCallout];
   [self stopEdgeInsetsAnimation];
@@ -457,13 +466,11 @@ MKMapType LuggMKMapTypeFromMapType(LuggMapViewMapType mapType) {
 
 - (void)setEdgeInsets:(UIEdgeInsets)edgeInsets
         oldEdgeInsets:(UIEdgeInsets)oldEdgeInsets {
-  CGFloat oldOffsetX = (oldEdgeInsets.left - oldEdgeInsets.right) / 2.0;
-  CGFloat oldOffsetY = (oldEdgeInsets.top - oldEdgeInsets.bottom) / 2.0;
-  CGFloat newOffsetX = (edgeInsets.left - edgeInsets.right) / 2.0;
-  CGFloat newOffsetY = (edgeInsets.top - edgeInsets.bottom) / 2.0;
+  CGPoint oldOffset = LuggMapInsetOffset(oldEdgeInsets);
+  CGPoint newOffset = LuggMapInsetOffset(edgeInsets);
 
-  CGFloat deltaX = newOffsetX - oldOffsetX;
-  CGFloat deltaY = newOffsetY - oldOffsetY;
+  CGFloat deltaX = newOffset.x - oldOffset.x;
+  CGFloat deltaY = newOffset.y - oldOffset.y;
 
   _mapView.layoutMargins = edgeInsets;
   _edgeInsetsCurrent = edgeInsets;
@@ -506,16 +513,8 @@ MKMapType LuggMKMapTypeFromMapType(LuggMapViewMapType mapType) {
   CFTimeInterval elapsed = CACurrentMediaTime() - _edgeInsetsAnimationStart;
   CGFloat progress = MIN(elapsed / _edgeInsetsAnimationDuration, 1.0);
 
-  // Ease out cubic
-  CGFloat t = 1.0 - (1.0 - progress) * (1.0 - progress) * (1.0 - progress);
-
-  UIEdgeInsets current = UIEdgeInsetsMake(
-      _edgeInsetsFrom.top + (_edgeInsetsTo.top - _edgeInsetsFrom.top) * t,
-      _edgeInsetsFrom.left + (_edgeInsetsTo.left - _edgeInsetsFrom.left) * t,
-      _edgeInsetsFrom.bottom +
-          (_edgeInsetsTo.bottom - _edgeInsetsFrom.bottom) * t,
-      _edgeInsetsFrom.right +
-          (_edgeInsetsTo.right - _edgeInsetsFrom.right) * t);
+  UIEdgeInsets current =
+      LuggMapInsetsAtProgress(_edgeInsetsFrom, _edgeInsetsTo, progress);
 
   [self setEdgeInsets:current oldEdgeInsets:_edgeInsetsCurrent];
 

package/ios/core/AppleStaticMapProvider.mm

@@ -4,6 +4,7 @@ using facebook::react::LuggMapViewPoiFilterMode;
 using facebook::react::LuggMapViewTheme;
 
 #import "../extensions/MKMapView+Zoom.h"
+#import "../extensions/UIView+Snapshot.h"
 #import "AppleMapProvider.h"
 #import "LuggAnnotationView.h"
 
@@ -42,8 +43,13 @@ static MKMapRect LuggStaticFittedMapRect(CLLocationCoordinate2D center,
   return rect;
 }
 
+@interface AppleStaticMapProvider () <MKMapViewDelegate>
+@end
+
 @implementation AppleStaticMapProvider {
   MKMapSnapshotter *_snapshotter;
+  MKMapView *_warmupMapView;
+  BOOL _snapshotReady;
 
   BOOL _poiEnabled;
   LuggMapViewPoiFilterMode _poiFilterMode;
@@ -106,6 +112,12 @@ static MKMapRect LuggStaticFittedMapRect(CLLocationCoordinate2D center,
 }
 
 - (void)renderBaseMap {
+  // MKMapSnapshotter bakes attribution into the image without inset control.
+  if (!UIEdgeInsetsEqualToEdgeInsets(self.edgeInsets, UIEdgeInsetsZero)) {
+    [self renderInsetBaseMap];
+    return;
+  }
+
   if (_snapshotter)
     return;
 
@@ -140,6 +152,68 @@ static MKMapRect LuggStaticFittedMapRect(CLLocationCoordinate2D center,
 - (void)cancelBaseRender {
   [_snapshotter cancel];
   _snapshotter = nil;
+  _warmupMapView.delegate = nil;
+  [_warmupMapView removeFromSuperview];
+  _warmupMapView = nil;
+  _snapshotReady = NO;
+}
+
+#pragma mark - Inset snapshots
+
+- (void)renderInsetBaseMap {
+  if (_warmupMapView) {
+    if (!_snapshotReady || !_warmupMapView.window)
+      return;
+
+    UIImageView *imageView = [_warmupMapView lugg_snapshotImageView];
+    if (!imageView)
+      return;
+
+    [self displayBaseImage:imageView.image fromCache:NO];
+    [self cancelBaseRender];
+    return;
+  }
+
+  MKMapView *mapView =
+      [[MKMapView alloc] initWithFrame:self.wrapperView.bounds];
+  mapView.userInteractionEnabled = NO;
+  mapView.showsCompass = NO;
+  mapView.insetsLayoutMarginsFromSafeArea = NO;
+  mapView.layoutMargins = self.edgeInsets;
+  mapView.mapType = LuggMKMapTypeFromMapType(self.mapType);
+  mapView.pointOfInterestFilter = LuggPointOfInterestFilter(
+      _poiEnabled, _poiFilterMode, _poiFilterCategories);
+  mapView.overrideUserInterfaceStyle =
+      [self snapshotTraitCollection].userInterfaceStyle;
+  [mapView setVisibleMapRect:self.mapRect
+                 edgePadding:UIEdgeInsetsZero
+                    animated:NO];
+  _warmupMapView = mapView;
+  mapView.delegate = self;
+  [self.wrapperView insertSubview:mapView atIndex:0];
+}
+
+- (void)mapViewWillStartRenderingMap:(MKMapView *)mapView {
+  _snapshotReady = NO;
+}
+
+- (void)mapViewDidFinishRenderingMap:(MKMapView *)mapView
+                       fullyRendered:(BOOL)fullyRendered {
+  _snapshotReady = fullyRendered;
+  [self revealOverlays];
+  if (!fullyRendered)
+    return;
+
+  __weak AppleStaticMapProvider *weakSelf = self;
+  __weak MKMapView *weakMapView = mapView;
+  [[NSRunLoop mainRunLoop]
+      performInModes:@[ NSDefaultRunLoopMode ]
+               block:^{
+                 AppleStaticMapProvider *strongSelf = weakSelf;
+                 if (strongSelf && weakMapView &&
+                     strongSelf->_warmupMapView == weakMapView)
+                   [strongSelf renderInsetBaseMap];
+               }];
 }
 
 #pragma mark - Props

package/ios/core/GoogleMapProvider.mm

@@ -13,6 +13,7 @@ using facebook::react::LuggMapViewTheme;
 #import "../LuggPolylineView.h"
 #import "../LuggTileOverlayView.h"
 #import "GMSPolylineAnimator.h"
+#import "MapEdgeInsets.h"
 #import "PolylineAnimatorBase.h"
 
 static NSString *const kDemoMapId = @"DEMO_MAP_ID";
@@ -183,6 +184,14 @@ LuggInterfaceStyleFromTheme(facebook::react::LuggMapViewTheme theme) {
   _mapView = nil;
 }
 
+- (CLLocationCoordinate2D)coordinate {
+  return _mapView.camera.target;
+}
+
+- (double)zoom {
+  return _mapView.camera.zoom;
+}
+
 #pragma mark - Props
 
 - (void)setZoomEnabled:(BOOL)enabled {
@@ -288,16 +297,8 @@ LuggInterfaceStyleFromTheme(facebook::react::LuggMapViewTheme theme) {
   CFTimeInterval elapsed = CACurrentMediaTime() - _edgeInsetsAnimationStart;
   CGFloat progress = MIN(elapsed / _edgeInsetsAnimationDuration, 1.0);
 
-  // Ease out cubic
-  CGFloat t = 1.0 - (1.0 - progress) * (1.0 - progress) * (1.0 - progress);
-
-  UIEdgeInsets current = UIEdgeInsetsMake(
-      _edgeInsetsFrom.top + (_edgeInsetsTo.top - _edgeInsetsFrom.top) * t,
-      _edgeInsetsFrom.left + (_edgeInsetsTo.left - _edgeInsetsFrom.left) * t,
-      _edgeInsetsFrom.bottom +
-          (_edgeInsetsTo.bottom - _edgeInsetsFrom.bottom) * t,
-      _edgeInsetsFrom.right +
-          (_edgeInsetsTo.right - _edgeInsetsFrom.right) * t);
+  UIEdgeInsets current =
+      LuggMapInsetsAtProgress(_edgeInsetsFrom, _edgeInsetsTo, progress);
 
   _mapView.padding = current;
 

package/ios/core/GoogleStaticMapProvider.mm

@@ -49,7 +49,7 @@ static void EnqueueStaticMapView(NSString *mapId, GMSMapView *mapView) {
 
 @implementation GoogleStaticMapProvider {
   GMSMapView *_warmupMapView;
-  BOOL _tilesRendered;
+  BOOL _snapshotReady;
   BOOL _swapScheduled;
 }
 
@@ -106,7 +106,7 @@ static void EnqueueStaticMapView(NSString *mapId, GMSMapView *mapView) {
   if (!wrapperView)
     return;
 
-  _tilesRendered = NO;
+  _snapshotReady = NO;
 
   GMSMapView *mapView = DequeueStaticMapView([self poolKey]);
   if (mapView) {
@@ -152,12 +152,12 @@ static void EnqueueStaticMapView(NSString *mapId, GMSMapView *mapView) {
   _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.
+// Once the map is stable, 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 ||
+  if (_swapScheduled || !_warmupMapView || !_snapshotReady ||
       !_warmupMapView.window)
     return;
 
@@ -176,9 +176,9 @@ static void EnqueueStaticMapView(NSString *mapId, GMSMapView *mapView) {
 
 - (void)performSwap {
   // Tiles can invalidate (or the view leave the window) between scheduling
-  // and this runloop pass; the next tile callback or resumeAnimations
+  // and this runloop pass; the next snapshotReady or resumeAnimations
   // retries
-  if (!_warmupMapView || !_tilesRendered || !_warmupMapView.window)
+  if (!_warmupMapView || !_snapshotReady || !_warmupMapView.window)
     return;
 
   UIImageView *imageView = [_warmupMapView lugg_snapshotImageView];
@@ -192,20 +192,24 @@ static void EnqueueStaticMapView(NSString *mapId, GMSMapView *mapView) {
 #pragma mark - GMSMapViewDelegate
 
 - (void)mapViewDidStartTileRendering:(GMSMapView *)mapView {
-  _tilesRendered = NO;
+  _snapshotReady = NO;
 }
 
+// Fires for tiles that failed permanently too, so it can't gate the swap:
+// capturing here cached blank tiles under the static key with no way to
+// recover. The visible warmup map has rendered what it can; show the
+// overlays now instead of waiting for the swap, which is deferred while
+// scrolling
 - (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];
 }
 
+// Stable per the SDK: tiles loaded, labels and overlays rendered. The only
+// signal that the render is complete, so the only one that captures and
+// caches. Without it (e.g. offline) the live map stays until the view
+// leaves the window, and a fresh warmup runs on return.
 - (void)mapViewSnapshotReady:(GMSMapView *)mapView {
-  // Stable per the SDK: tiles loaded, labels and overlays rendered
-  _tilesRendered = YES;
+  _snapshotReady = YES;
   [self revealOverlays];
   [self scheduleSwap];
 }

package/ios/core/MapEdgeInsets.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+static inline CGPoint LuggMapInsetOffset(UIEdgeInsets insets) {
+  return CGPointMake((insets.left - insets.right) / 2.0,
+                     (insets.top - insets.bottom) / 2.0);
+}
+
+static inline UIEdgeInsets
+LuggMapInsetsAtProgress(UIEdgeInsets from, UIEdgeInsets to, CGFloat progress) {
+  // Ease out cubic
+  CGFloat t = 1.0 - (1.0 - progress) * (1.0 - progress) * (1.0 - progress);
+  return UIEdgeInsetsMake(from.top + (to.top - from.top) * t,
+                          from.left + (to.left - from.left) * t,
+                          from.bottom + (to.bottom - from.bottom) * t,
+                          from.right + (to.right - from.right) * t);
+}

package/ios/core/MapProviderDelegate.h

@@ -89,6 +89,10 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)removeTileOverlayView:(LuggTileOverlayView *)tileOverlayView;
 - (void)syncTileOverlayView:(LuggTileOverlayView *)tileOverlayView;
 
+// Current camera (the initial camera until the map is ready)
+@property(nonatomic, readonly) CLLocationCoordinate2D coordinate;
+@property(nonatomic, readonly) double zoom;
+
 // Lifecycle
 - (void)pauseAnimations;
 - (void)resumeAnimations;

package/ios/core/StaticMapProviderBase.h

@@ -42,6 +42,11 @@ CGPoint LuggStaticPointForCoordinate(MKMapRect mapRect, CGSize size,
 /// delegate callbacks and marks the base render done.
 - (void)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache;
 
+/// Discards any cached, displayed or in-flight base render and renders
+/// again at the current camera. The displayed image stays until the new
+/// one replaces it.
+- (void)rerenderBaseMap;
+
 /// Shows the marker and shape overlays (idempotent). Called automatically
 /// when the base image displays; subclasses whose base map is already
 /// visible earlier (e.g. a live warmup map) can call it sooner.