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

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

@@ -1,6 +1,7 @@
 package com.luggmaps
 
 import android.annotation.SuppressLint
+import android.content.res.Configuration
 import android.view.View
 import android.view.View.VISIBLE
 import com.facebook.react.uimanager.ThemedReactContext
@@ -65,6 +66,7 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
   private var rotateEnabled: Boolean = true
   private var pitchEnabled: Boolean = true
   private var compassEnabled: Boolean = true
+  private var staticMode: Boolean = false
   private var userLocationEnabled: Boolean = false
   private var userLocationButtonEnabled: Boolean = false
   private var poiEnabled: Boolean = true
@@ -132,8 +134,13 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
   private fun initializeProvider() {
     if (provider != null || mapWrapperView == null) return
 
+    if (staticMode) {
+      applyStaticPlaceholder()
+    }
+
     val google = GoogleMapProvider(context)
     google.mapId = mapId
+    google.staticMode = staticMode
     google.delegate = this
     provider = google
 
@@ -154,6 +161,23 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
     }
   }
 
+  // Shown while the map loads, until the map covers it
+  private fun applyStaticPlaceholder() {
+    // A user-provided background acts as the placeholder
+    if (background != null) return
+
+    val isDark = when (theme) {
+      "dark" -> true
+
+      "light" -> false
+
+      else ->
+        (context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) ==
+          Configuration.UI_MODE_NIGHT_YES
+    }
+    mapWrapperView?.setBackgroundColor(if (isDark) COLOR_PLACEHOLDER_DARK else COLOR_PLACEHOLDER_LIGHT)
+  }
+
   // endregion
 
   // region MapProviderDelegate
@@ -251,6 +275,10 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
     provider?.setCompassEnabled(enabled)
   }
 
+  fun setStaticMode(enabled: Boolean) {
+    staticMode = enabled
+  }
+
   fun setUserLocationEnabled(enabled: Boolean) {
     if (userLocationEnabled == enabled) return
     userLocationEnabled = enabled
@@ -344,4 +372,9 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
   }
 
   // endregion
+
+  companion object {
+    private const val COLOR_PLACEHOLDER_LIGHT = 0xFFF2F2F7.toInt()
+    private const val COLOR_PLACEHOLDER_DARK = 0xFF2C2C2E.toInt()
+  }
 }

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

@@ -137,6 +137,15 @@ class LuggMapViewManager :
     view.setCompassEnabled(value)
   }
 
+  @ReactProp(name = "staticMode", defaultBoolean = false)
+  override fun setStaticMode(view: LuggMapView, value: Boolean) {
+    view.setStaticMode(value)
+  }
+
+  // iOS only - lite mode doesn't need snapshot caching
+  @ReactProp(name = "staticKey")
+  override fun setStaticKey(view: LuggMapView, value: String?) = Unit
+
   @ReactProp(name = "userLocationEnabled", defaultBoolean = false)
   override fun setUserLocationEnabled(view: LuggMapView, value: Boolean) {
     view.setUserLocationEnabled(value)

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

@@ -10,11 +10,30 @@ class LuggMapWrapperView(context: ThemedReactContext) : ReactViewGroup(context)
 
   var touchEventHandler: ((MotionEvent) -> Unit)? = null
 
+  // React Native never runs an Android layout pass on Yoga-managed views, so
+  // a child's requestLayout (e.g. a lite mode MapView displaying its bitmap
+  // once loaded) would otherwise never result in a measure/layout. Live maps
+  // don't need this - their GL surface renders continuously once sized.
+  var relayoutChildOnRequest: Boolean = false
+
+  // Invoked on layout once the view has a non-zero size, so the map
+  // provider can create a map sized to the view
+  var onLayoutReady: (() -> Unit)? = null
+
+  private val measureAndLayoutChild = Runnable { layoutChild(width, height) }
+
   override fun dispatchTouchEvent(event: MotionEvent): Boolean {
     touchEventHandler?.invoke(event)
     return super.dispatchTouchEvent(event)
   }
 
+  override fun requestLayout() {
+    super.requestLayout()
+    if (relayoutChildOnRequest) {
+      post(measureAndLayoutChild)
+    }
+  }
+
   override fun onLayout(
     changed: Boolean,
     left: Int,
@@ -23,8 +42,14 @@ class LuggMapWrapperView(context: ThemedReactContext) : ReactViewGroup(context)
     bottom: Int
   ) {
     super.onLayout(changed, left, top, right, bottom)
-    val w = right - left
-    val h = bottom - top
+    layoutChild(right - left, bottom - top)
+    if (right - left > 0 && bottom - top > 0) {
+      onLayoutReady?.invoke()
+    }
+  }
+
+  private fun layoutChild(w: Int, h: Int) {
+    if (w <= 0 || h <= 0) return
     getChildAt(0)?.let {
       it.measure(
         MeasureSpec.makeMeasureSpec(w, MeasureSpec.EXACTLY),

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

@@ -48,7 +48,9 @@ import com.luggmaps.LuggTileOverlayViewDelegate
 import com.luggmaps.extensions.findViewByTag
 import java.net.URL
 import kotlin.math.atan
+import kotlin.math.ln
 import kotlin.math.pow
+import kotlin.math.sin
 import kotlin.math.sinh
 
 class GoogleMapProvider(private val context: Context) :
@@ -78,6 +80,10 @@ class GoogleMapProvider(private val context: Context) :
 
   var mapId: String = DEMO_MAP_ID
 
+  // Renders a non-interactive static map — lite mode when the view fits
+  // the lite bitmap cap, a gesture-less full map otherwise. Creation-time only.
+  var staticMode: Boolean = false
+
   private var wrapperView: LuggMapWrapperView? = null
   private var currentNightMode: Int = context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
   private var mapView: MapView? = null
@@ -96,6 +102,7 @@ class GoogleMapProvider(private val context: Context) :
   private val groundOverlayToViewMap = mutableMapOf<GroundOverlay, LuggGroundOverlayView>()
   private val markerToViewMap = mutableMapOf<Marker, LuggMarkerView>()
   private val liveMarkerViews = mutableSetOf<LuggMarkerView>()
+  private var staticProjectionReady = false
   private var activeNonBubbledMarker: Marker? = null
   private var tapLocation: LatLng? = null
 
@@ -137,20 +144,43 @@ class GoogleMapProvider(private val context: Context) :
     initialZoom = zoom
 
     val wrapper = wrapperView as LuggMapWrapperView
+    wrapper.relayoutChildOnRequest = staticMode
     this.wrapperView = wrapper
 
     context.applicationContext.registerComponentCallbacks(this)
 
-    val options = GoogleMapOptions().mapId(mapId)
+    // Static mode needs the view size to pick lite vs full map, so wait
+    // for the first layout if it hasn't happened yet
+    if (staticMode && (wrapper.width == 0 || wrapper.height == 0)) {
+      wrapper.onLayoutReady = { createMapView() }
+    } else {
+      createMapView()
+    }
+  }
+
+  private fun createMapView() {
+    if (mapView != null) return
+    val wrapper = wrapperView ?: return
+
+    // Lite mode renders the map as a single bitmap capped at ~2048px per
+    // dimension, centered in the view — bigger views get letterboxed. Fall
+    // back to a full map (gestures disabled) when the view exceeds the cap
+    val useLite = staticMode && maxOf(wrapper.width, wrapper.height) <= LITE_MODE_MAX_SIZE
+    val options = GoogleMapOptions().liteMode(useLite)
+    // Lite mode doesn't support map IDs (cloud-based styling); setting one
+    // makes the static map render blank
+    if (!useLite) options.mapId(mapId)
     mapView = MapView(context, options).also { view ->
       view.onCreate(null)
       view.onResume()
       view.getMapAsync(this)
       wrapper.addView(view)
     }
+    wrapper.onLayoutReady = null
   }
 
   override fun destroy() {
+    wrapperView?.onLayoutReady = null
     detachWindowInsetsListener()
     context.applicationContext.unregisterComponentCallbacks(this)
     dismissNonBubbledCallout()
@@ -195,7 +225,18 @@ class GoogleMapProvider(private val context: Context) :
     googleMap = map
     _isMapReady = true
 
-    val position = LatLng(initialLatitude, initialLongitude)
+    if (staticMode) {
+      // Tapping the map otherwise shows an "open in Google Maps" toolbar
+      map.uiSettings.isMapToolbarEnabled = false
+      // The projection is only valid once the map has rendered, and no
+      // camera events fire afterwards to correct live marker positions
+      map.setOnMapLoadedCallback {
+        staticProjectionReady = true
+        positionLiveMarkers()
+      }
+    }
+
+    val position = if (staticMode) staticCameraTarget() else LatLng(initialLatitude, initialLongitude)
     map.moveCamera(CameraUpdateFactory.newLatLngZoom(position, initialZoom))
 
     map.setOnCameraMoveStartedListener(this)
@@ -442,21 +483,25 @@ class GoogleMapProvider(private val context: Context) :
 
   override fun setZoomEnabled(enabled: Boolean) {
     zoomEnabled = enabled
+    if (staticMode) return
     googleMap?.uiSettings?.isZoomGesturesEnabled = enabled
   }
 
   override fun setScrollEnabled(enabled: Boolean) {
     scrollEnabled = enabled
+    if (staticMode) return
     googleMap?.uiSettings?.isScrollGesturesEnabled = enabled
   }
 
   override fun setRotateEnabled(enabled: Boolean) {
     rotateEnabled = enabled
+    if (staticMode) return
     googleMap?.uiSettings?.isRotateGesturesEnabled = enabled
   }
 
   override fun setPitchEnabled(enabled: Boolean) {
     pitchEnabled = enabled
+    if (staticMode) return
     googleMap?.uiSettings?.isTiltGesturesEnabled = enabled
   }
 
@@ -511,6 +556,11 @@ class GoogleMapProvider(private val context: Context) :
   }
 
   override fun setEdgeInsets(edgeInsets: EdgeInsets) {
+    if (staticMode) {
+      setStaticEdgeInsets(edgeInsets)
+      return
+    }
+
     val oldInsets = this.edgeInsets
     this.edgeInsets = edgeInsets
     applyEdgeInsets()
@@ -524,6 +574,11 @@ class GoogleMapProvider(private val context: Context) :
   }
 
   override fun setEdgeInsets(edgeInsets: EdgeInsets, duration: Int) {
+    if (staticMode) {
+      setStaticEdgeInsets(edgeInsets)
+      return
+    }
+
     val map = googleMap
     val oldInsets = this.edgeInsets
     this.edgeInsets = edgeInsets
@@ -737,6 +792,10 @@ class GoogleMapProvider(private val context: Context) :
 
     val contentView = markerView.contentView
     contentView.pointerEvents = com.facebook.react.uimanager.PointerEvents.NONE
+    // Until the lite map's projection is valid, hide the marker instead of
+    // flashing it at a wrong position; onMapLoaded positions and shows it
+    contentView.visibility =
+      if (staticMode && !staticProjectionReady) View.INVISIBLE else View.VISIBLE
     (contentView.parent as? android.view.ViewGroup)?.removeView(contentView)
     wrapper.addView(contentView)
     liveMarkerViews.add(markerView)
@@ -768,10 +827,12 @@ class GoogleMapProvider(private val context: Context) :
 
   private fun positionLiveMarker(markerView: LuggMarkerView) {
     val map = googleMap ?: return
+    if (staticMode && !staticProjectionReady) return
     val contentView = markerView.contentView
     val point = map.projection.toScreenLocation(LatLng(markerView.latitude, markerView.longitude))
     contentView.translationX = point.x - contentView.width * markerView.anchorX
     contentView.translationY = point.y - contentView.height * markerView.anchorY
+    contentView.visibility = View.VISIBLE
   }
 
   // endregion
@@ -813,7 +874,7 @@ class GoogleMapProvider(private val context: Context) :
       strokeColors = polylineView.strokeColors
       strokeWidth = polylineView.strokeWidth.dpToPx()
       animatedOptions = polylineView.animatedOptions
-      animated = polylineView.animated
+      animated = polylineView.animated && !staticMode
       update()
     }
   }
@@ -842,7 +903,8 @@ class GoogleMapProvider(private val context: Context) :
       strokeColors = polylineView.strokeColors
       strokeWidth = polylineView.strokeWidth.dpToPx()
       animatedOptions = polylineView.animatedOptions
-      animated = polylineView.animated
+      // Static maps render once; show the full polyline instead of animating
+      animated = polylineView.animated && !staticMode
       update()
     }
 
@@ -1204,6 +1266,12 @@ class GoogleMapProvider(private val context: Context) :
 
   private fun applyUiSettings() {
     googleMap?.uiSettings?.apply {
+      if (staticMode) {
+        // The non-lite fallback is a full map; keep it behaving like a
+        // static image (lite mode ignores gestures anyway)
+        setAllGesturesEnabled(false)
+        return
+      }
       isZoomGesturesEnabled = zoomEnabled
       isScrollGesturesEnabled = scrollEnabled
       isRotateGesturesEnabled = rotateEnabled
@@ -1244,10 +1312,43 @@ class GoogleMapProvider(private val context: Context) :
 
   private fun applyEdgeInsets(duration: Int = 0) {
     val combined = combinedEdgeInsets()
-    googleMap?.setPadding(combined.left, combined.top, combined.right, combined.bottom)
+    // Lite mode misrenders padding: the static image is drawn only within
+    // the padded viewport instead of the full view. The camera target shift
+    // (staticCameraTarget) compensates for insets instead.
+    if (!staticMode) {
+      googleMap?.setPadding(combined.left, combined.top, combined.right, combined.bottom)
+    }
     applyWatermarkTranslation(combined, duration)
   }
 
+  // Insets are applied by shifting the camera target so the coordinate
+  // centers in the inset viewport like a live map would (see
+  // applyEdgeInsets for why padding can't be used)
+  private fun setStaticEdgeInsets(edgeInsets: EdgeInsets) {
+    val oldInsets = this.edgeInsets
+    this.edgeInsets = edgeInsets
+    applyEdgeInsets()
+
+    val map = googleMap
+    if (map != null && oldInsets != edgeInsets) {
+      map.moveCamera(CameraUpdateFactory.newLatLngZoom(staticCameraTarget(), initialZoom))
+      positionLiveMarkers()
+    }
+  }
+
+  private fun staticCameraTarget(): LatLng {
+    val offsetX = (edgeInsets.left - edgeInsets.right) / 2.0
+    val offsetY = (edgeInsets.top - edgeInsets.bottom) / 2.0
+    if (offsetX == 0.0 && offsetY == 0.0) return LatLng(initialLatitude, initialLongitude)
+
+    // Web mercator world size in px at the initial zoom
+    val worldSize = 256f.dpToPx().toDouble() * 2.0.pow(initialZoom.toDouble())
+    val sinLat = sin(Math.toRadians(initialLatitude))
+    val x = (initialLongitude + 180.0) / 360.0 - offsetX / worldSize
+    val y = 0.5 - ln((1.0 + sinLat) / (1.0 - sinLat)) / (4.0 * Math.PI) - offsetY / worldSize
+    return LatLng(Math.toDegrees(atan(sinh(Math.PI * (1.0 - 2.0 * y)))), x * 360.0 - 180.0)
+  }
+
   private fun applyWatermarkTranslation(insets: EdgeInsets, duration: Int = 0) {
     val view = mapView ?: return
     view.findViewByTag("GoogleWatermark")?.let { watermark ->
@@ -1324,5 +1425,9 @@ class GoogleMapProvider(private val context: Context) :
 
   companion object {
     const val DEMO_MAP_ID = "DEMO_MAP_ID"
+
+    // Undocumented cap on the lite mode bitmap (2048 minus a 2px border,
+    // measured empirically)
+    private const val LITE_MODE_MAX_SIZE = 2046
   }
 }

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
 
@@ -40,6 +55,9 @@ using namespace luggmaps::events;
   BOOL _rotateEnabled;
   BOOL _pitchEnabled;
   BOOL _compassEnabled;
+  BOOL _staticMode;
+  NSString *_staticKey;
+  BOOL _staticSnapshotDone;
   BOOL _userLocationEnabled;
   LuggMapViewMapType _mapType;
   LuggMapViewTheme _theme;
@@ -70,6 +88,8 @@ using namespace luggmaps::events;
     _rotateEnabled = YES;
     _pitchEnabled = YES;
     _compassEnabled = YES;
+    _staticMode = NO;
+    _staticKey = @"";
     _userLocationEnabled = NO;
     _poiEnabled = NO;
     _poiFilterMode = LuggMapViewPoiFilterMode::Including;
@@ -170,17 +190,110 @@ 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
+  const auto &viewProps =
+      *std::static_pointer_cast<LuggMapViewProps const>(_props);
+
+  return [NSString
+      stringWithFormat:@"%@|%d|%@|%d|%ld|%.0fx%.0f|%.6f,%.6f,%.2f|%@",
+                       _staticKey, (int)_providerType, _mapId, (int)_mapType,
+                       (long)style, size.width, size.height,
+                       viewProps.initialCoordinate.latitude,
+                       viewProps.initialCoordinate.longitude,
+                       viewProps.initialZoom,
+                       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;
@@ -197,14 +310,28 @@ 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;
     _provider = google;
   }
 
+  if (_staticMode) {
+    NSString *cacheKey = [self staticSnapshotCacheKey];
+    if (cacheKey) {
+      ((StaticMapProviderBase *)_provider).cachedBaseImage =
+          [StaticSnapshotCache() objectForKey:cacheKey];
+    }
+  }
+
   _provider.delegate = self;
+  _provider.staticMode = _staticMode;
 
   CLLocationCoordinate2D coordinate =
       CLLocationCoordinate2DMake(viewProps.initialCoordinate.latitude,
@@ -244,6 +371,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
@@ -303,6 +443,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()];
@@ -381,6 +527,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