From 682d5affb09b66e99131cd20b2f498b374bba45b Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Mon, 6 Jul 2026 22:47:23 +0800
Subject: [PATCH 01/17] feat(mapview): add staticMode prop for static maps in
 lists

---
 .../src/main/java/com/luggmaps/LuggMapView.kt |   6 +
 .../java/com/luggmaps/LuggMapViewManager.kt   |   5 +
 .../com/luggmaps/core/GoogleMapProvider.kt    |  10 +-
 docs/MAPVIEW.md                               |  34 ++++
 example/bare/ios/Podfile.lock                 |   6 +-
 example/bare/src/App.tsx                      |  18 +-
 example/bare/src/screens/StaticMapsScreen.tsx |  14 ++
 example/expo/app/index.tsx                    |  11 +-
 example/expo/app/static-maps.tsx              |  14 ++
 example/shared/src/index.ts                   |   1 +
 example/shared/src/screens/HomeScreen.tsx     |  14 +-
 .../shared/src/screens/StaticMapsScreen.tsx   | 161 ++++++++++++++++++
 example/shared/src/sheets/ControlSheet.tsx    |   8 +
 ios/LuggMapView.mm                            |   4 +
 ios/core/AppleMapProvider.mm                  |  52 +++++-
 ios/core/GoogleMapProvider.mm                 |  52 +++++-
 ios/core/MapProviderDelegate.h                |   4 +
 ios/extensions/UIView+Snapshot.h              |  16 ++
 ios/extensions/UIView+Snapshot.m              |  24 +++
 src/MapView.tsx                               |   2 +
 src/MapView.types.ts                          |   9 +
 src/MapView.web.tsx                           |  14 +-
 src/fabric/LuggMapViewNativeComponent.ts      |   1 +
 23 files changed, 463 insertions(+), 17 deletions(-)
 create mode 100644 example/bare/src/screens/StaticMapsScreen.tsx
 create mode 100644 example/expo/app/static-maps.tsx
 create mode 100644 example/shared/src/screens/StaticMapsScreen.tsx
 create mode 100644 ios/extensions/UIView+Snapshot.h
 create mode 100644 ios/extensions/UIView+Snapshot.m

diff --git a/android/src/main/java/com/luggmaps/LuggMapView.kt b/android/src/main/java/com/luggmaps/LuggMapView.kt
index b60b7b4..0f9ff83 100644
--- a/android/src/main/java/com/luggmaps/LuggMapView.kt
+++ b/android/src/main/java/com/luggmaps/LuggMapView.kt
@@ -65,6 +65,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
@@ -134,6 +135,7 @@ class LuggMapView(private val reactContext: ThemedReactContext) :
 
     val google = GoogleMapProvider(context)
     google.mapId = mapId
+    google.staticMode = staticMode
     google.delegate = this
     provider = google
 
@@ -251,6 +253,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
diff --git a/android/src/main/java/com/luggmaps/LuggMapViewManager.kt b/android/src/main/java/com/luggmaps/LuggMapViewManager.kt
index eadd0eb..5875f92 100644
--- a/android/src/main/java/com/luggmaps/LuggMapViewManager.kt
+++ b/android/src/main/java/com/luggmaps/LuggMapViewManager.kt
@@ -137,6 +137,11 @@ class LuggMapViewManager :
     view.setCompassEnabled(value)
   }
 
+  @ReactProp(name = "staticMode", defaultBoolean = false)
+  override fun setStaticMode(view: LuggMapView, value: Boolean) {
+    view.setStaticMode(value)
+  }
+
   @ReactProp(name = "userLocationEnabled", defaultBoolean = false)
   override fun setUserLocationEnabled(view: LuggMapView, value: Boolean) {
     view.setUserLocationEnabled(value)
diff --git a/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt b/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
index a1c5655..9f11994 100644
--- a/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
+++ b/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
@@ -78,6 +78,9 @@ class GoogleMapProvider(private val context: Context) :
 
   var mapId: String = DEMO_MAP_ID
 
+  // Renders the map in lite mode (static bitmap). 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
@@ -141,7 +144,7 @@ class GoogleMapProvider(private val context: Context) :
 
     context.applicationContext.registerComponentCallbacks(this)
 
-    val options = GoogleMapOptions().mapId(mapId)
+    val options = GoogleMapOptions().mapId(mapId).liteMode(staticMode)
     mapView = MapView(context, options).also { view ->
       view.onCreate(null)
       view.onResume()
@@ -195,6 +198,11 @@ class GoogleMapProvider(private val context: Context) :
     googleMap = map
     _isMapReady = true
 
+    if (staticMode) {
+      // Lite mode shows an "open in Google Maps" toolbar on tap by default
+      map.uiSettings.isMapToolbarEnabled = false
+    }
+
     val position = LatLng(initialLatitude, initialLongitude)
     map.moveCamera(CameraUpdateFactory.newLatLngZoom(position, initialZoom))
 
diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index 6611e54..e844ee1 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -33,6 +33,7 @@ import { MapView } from '@lugg/maps';
 | `rotateEnabled` | `boolean` | `true` | Enable rotation gestures |
 | `pitchEnabled` | `boolean` | `true` | Enable pitch/tilt gestures |
 | `compassEnabled` | `boolean` | `true` | Show compass on the map (rotate control on web) |
+| `staticMode` | `boolean` | `false` | Render as a non-interactive [static map](#static-maps). Ideal for list views |
 | `edgeInsets` | `EdgeInsets` | - | Map content edge insets |
 | `userLocationEnabled` | `boolean` | `false` | Show current user location on the map |
 | `userLocationButtonEnabled` | `boolean` | `false` | Show native my-location button (Android only) |
@@ -46,6 +47,39 @@ import { MapView } from '@lugg/maps';
 | `onCameraIdle` | `(event: MapCameraEvent) => void` | - | Called when camera stops moving |
 | `onReady` | `() => void` | - | Called when map is loaded and ready |
 
+## Static Maps
+
+Set `staticMode` to render a non-interactive map optimized for list views, where
+mounting many live maps is expensive:
+
+- **Android (Google)** - uses [lite mode](https://developers.google.com/maps/documentation/android-sdk/lite),
+  which renders a static bitmap instead of a live GL surface.
+- **iOS (Apple/Google)** - the live map is replaced with a rendered snapshot
+  image once tiles finish loading, releasing the map's rendering resources.
+
+```tsx
+<Pressable onPress={() => openPlace(place)}>
+  <View style={{ height: 140 }} pointerEvents="none">
+    <MapView
+      staticMode
+      style={StyleSheet.absoluteFill}
+      initialCoordinate={place.coordinate}
+      initialZoom={14}
+    >
+      <Marker coordinate={place.coordinate} />
+    </MapView>
+  </View>
+</Pressable>
+```
+
+Notes:
+
+- `staticMode` is creation-time only and cannot be toggled after the map is created.
+- The map renders once with its initial camera and children. Camera commands
+  and prop updates after the snapshot are ignored on iOS.
+- For taps, wrap the map in a `Pressable` with `pointerEvents="none"` on the
+  map container (as above) instead of relying on `onPress`.
+
 ## Types
 
 ### MapProvider
diff --git a/example/bare/ios/Podfile.lock b/example/bare/ios/Podfile.lock
index dff7863..b227082 100644
--- a/example/bare/ios/Podfile.lock
+++ b/example/bare/ios/Podfile.lock
@@ -6,7 +6,7 @@ PODS:
   - hermes-engine (250829098.0.10):
     - hermes-engine/Pre-built (= 250829098.0.10)
   - hermes-engine/Pre-built (250829098.0.10)
-  - LuggMaps (1.0.0-beta.16):
+  - LuggMaps (1.0.0-beta.17):
     - GoogleMaps
     - hermes-engine
     - RCTRequired
@@ -2427,7 +2427,7 @@ SPEC CHECKSUMS:
   FBLazyVector: 24e62c765683b8d89006a88a2c8f5cf019f0074d
   GoogleMaps: 0608099d4870cac8754bdba9b6953db543432438
   hermes-engine: a43fcac5345a0a468667778019547c5fd282c6e2
-  LuggMaps: 7f6539e8b1f2d1c328f6c9634cc0544a78b39076
+  LuggMaps: 345524788dd8a9e80267d4b8a3daa23861ccedad
   RCTDeprecation: a4c521821fab57cbb125b36effe84d897d0dfa12
   RCTRequired: 9f3a7e5645d4bc3f551593de7550bb66ab6e42bc
   RCTSwiftUI: 239ed2eb9e73de5a6f518810630f0c95e01c8702
@@ -2510,4 +2510,4 @@ SPEC CHECKSUMS:
 
 PODFILE CHECKSUM: a8c918957730cfd546eb917e7563885b57095460
 
-COCOAPODS: 1.15.2
+COCOAPODS: 1.16.2
diff --git a/example/bare/src/App.tsx b/example/bare/src/App.tsx
index 4df0a24..c1d4ac1 100644
--- a/example/bare/src/App.tsx
+++ b/example/bare/src/App.tsx
@@ -13,10 +13,12 @@ import type { MarkerPressEvent } from '@lugg/maps';
 import { HomeScreen, type MarkerData } from '@lugg/shared-example';
 
 import { DetailScreen } from './screens/DetailScreen';
+import { StaticMapsScreen } from './screens/StaticMapsScreen';
 
 export type RootStackParamList = {
   Home: undefined;
   Detail: { name: string };
+  StaticMaps: undefined;
 };
 
 const Stack = createNativeStackNavigator<RootStackParamList>();
@@ -31,7 +33,16 @@ function Home({ navigation }: HomeProps) {
     [navigation]
   );
 
-  return <HomeScreen onMarkerPress={handleMarkerPress} />;
+  const handleShowStaticMaps = useCallback(() => {
+    navigation.navigate('StaticMaps');
+  }, [navigation]);
+
+  return (
+    <HomeScreen
+      onMarkerPress={handleMarkerPress}
+      onShowStaticMaps={handleShowStaticMaps}
+    />
+  );
 }
 
 export default function App() {
@@ -46,6 +57,11 @@ export default function App() {
           options={{ headerShown: false }}
         />
         <Stack.Screen name="Detail" component={DetailScreen} />
+        <Stack.Screen
+          name="StaticMaps"
+          component={StaticMapsScreen}
+          options={{ title: 'Static Maps' }}
+        />
       </Stack.Navigator>
     </NavigationContainer>
   );
diff --git a/example/bare/src/screens/StaticMapsScreen.tsx b/example/bare/src/screens/StaticMapsScreen.tsx
new file mode 100644
index 0000000..59d374c
--- /dev/null
+++ b/example/bare/src/screens/StaticMapsScreen.tsx
@@ -0,0 +1,14 @@
+import type { NativeStackScreenProps } from '@react-navigation/native-stack';
+import { StaticMapsScreen as SharedStaticMapsScreen } from '@lugg/shared-example';
+
+import type { RootStackParamList } from '../App';
+
+type Props = NativeStackScreenProps<RootStackParamList, 'StaticMaps'>;
+
+export function StaticMapsScreen({ navigation }: Props) {
+  return (
+    <SharedStaticMapsScreen
+      onSelect={(place) => navigation.navigate('Detail', { name: place.name })}
+    />
+  );
+}
diff --git a/example/expo/app/index.tsx b/example/expo/app/index.tsx
index 753549b..23a9a2c 100644
--- a/example/expo/app/index.tsx
+++ b/example/expo/app/index.tsx
@@ -13,5 +13,14 @@ export default function MapScreen() {
     [router]
   );
 
-  return <HomeScreen onMarkerPress={handleMarkerPress} />;
+  const handleShowStaticMaps = useCallback(() => {
+    router.push('/static-maps');
+  }, [router]);
+
+  return (
+    <HomeScreen
+      onMarkerPress={handleMarkerPress}
+      onShowStaticMaps={handleShowStaticMaps}
+    />
+  );
 }
diff --git a/example/expo/app/static-maps.tsx b/example/expo/app/static-maps.tsx
new file mode 100644
index 0000000..59d1527
--- /dev/null
+++ b/example/expo/app/static-maps.tsx
@@ -0,0 +1,14 @@
+import { useRouter } from 'expo-router';
+import { StaticMapsScreen } from '@lugg/shared-example';
+
+export default function StaticMaps() {
+  const router = useRouter();
+
+  return (
+    <StaticMapsScreen
+      onSelect={(place) =>
+        router.push({ pathname: '/detail', params: { name: place.name } })
+      }
+    />
+  );
+}
diff --git a/example/shared/src/index.ts b/example/shared/src/index.ts
index e5c844c..36e233b 100644
--- a/example/shared/src/index.ts
+++ b/example/shared/src/index.ts
@@ -4,3 +4,4 @@ export * from './utils';
 export * from './markers';
 export * from './screens/HomeScreen';
 export * from './screens/MarkerDetailScreen';
+export * from './screens/StaticMapsScreen';
diff --git a/example/shared/src/screens/HomeScreen.tsx b/example/shared/src/screens/HomeScreen.tsx
index c2012bb..7d87e6a 100644
--- a/example/shared/src/screens/HomeScreen.tsx
+++ b/example/shared/src/screens/HomeScreen.tsx
@@ -42,23 +42,30 @@ const bottomEdgeInsets = (bottom: number) => ({
 
 interface HomeProps {
   onMarkerPress?: (e: MarkerPressEvent, marker: MarkerData) => void;
+  onShowStaticMaps?: () => void;
 }
 
-export const HomeScreen = ({ onMarkerPress }: HomeProps) => {
+export const HomeScreen = ({ onMarkerPress, onShowStaticMaps }: HomeProps) => {
   const apiKey = process.env.GOOGLE_MAPS_API_KEY;
 
   return (
     <TrueSheetProvider>
       <ReanimatedTrueSheetProvider>
         <MapProvider apiKey={apiKey}>
-          <HomeContent onMarkerPress={onMarkerPress} />
+          <HomeContent
+            onMarkerPress={onMarkerPress}
+            onShowStaticMaps={onShowStaticMaps}
+          />
         </MapProvider>
       </ReanimatedTrueSheetProvider>
     </TrueSheetProvider>
   );
 };
 
-const HomeContent = ({ onMarkerPress: onMarkerPressProp }: HomeProps) => {
+const HomeContent = ({
+  onMarkerPress: onMarkerPressProp,
+  onShowStaticMaps,
+}: HomeProps) => {
   const mapRef = useRef<MapRef>(null);
   const controlSheetRef = useRef<ControlSheetRef>(null);
   const mapTypeSheetRef = useRef<MapTypeSheetRef>(null);
@@ -277,6 +284,7 @@ const HomeContent = ({ onMarkerPress: onMarkerPressProp }: HomeProps) => {
           setProvider((p) => (p === 'google' ? 'apple' : 'google'))
         }
         onLoadGeojson={() => geojsonSheetRef.current?.present()}
+        onShowStaticMaps={onShowStaticMaps}
         onDidPresent={handleSheetEvent}
         onDetentChange={handleSheetEvent}
       />
diff --git a/example/shared/src/screens/StaticMapsScreen.tsx b/example/shared/src/screens/StaticMapsScreen.tsx
new file mode 100644
index 0000000..26ba60a
--- /dev/null
+++ b/example/shared/src/screens/StaticMapsScreen.tsx
@@ -0,0 +1,161 @@
+import { useState } from 'react';
+import { FlatList, Platform, Pressable, StyleSheet, View } from 'react-native';
+import {
+  MapProvider,
+  MapView,
+  Marker,
+  type Coordinate,
+  type MapProviderType,
+} from '@lugg/maps';
+
+import { Button, ThemedText } from '../components';
+import { sizes, useTheme } from '../theme';
+
+export interface StaticPlace {
+  id: string;
+  name: string;
+  description: string;
+  coordinate: Coordinate;
+}
+
+const PLACES: StaticPlace[] = [
+  {
+    id: 'golden-gate-bridge',
+    name: 'Golden Gate Bridge',
+    description: 'Iconic suspension bridge over the Golden Gate strait',
+    coordinate: { latitude: 37.8199, longitude: -122.4783 },
+  },
+  {
+    id: 'alcatraz',
+    name: 'Alcatraz Island',
+    description: 'Historic island prison in San Francisco Bay',
+    coordinate: { latitude: 37.827, longitude: -122.423 },
+  },
+  {
+    id: 'ferry-building',
+    name: 'Ferry Building',
+    description: 'Marketplace and transit hub on the Embarcadero',
+    coordinate: { latitude: 37.7955, longitude: -122.3937 },
+  },
+  {
+    id: 'golden-gate-park',
+    name: 'Golden Gate Park',
+    description: 'Large urban park with gardens and museums',
+    coordinate: { latitude: 37.7694, longitude: -122.4862 },
+  },
+  {
+    id: 'coit-tower',
+    name: 'Coit Tower',
+    description: 'Art deco tower on Telegraph Hill',
+    coordinate: { latitude: 37.8024, longitude: -122.4058 },
+  },
+  {
+    id: 'twin-peaks',
+    name: 'Twin Peaks',
+    description: 'Hills with panoramic views of the city',
+    coordinate: { latitude: 37.7544, longitude: -122.4477 },
+  },
+];
+
+interface StaticMapsScreenProps {
+  onSelect?: (place: StaticPlace) => void;
+}
+
+const PlaceCard = ({
+  place,
+  provider,
+  onSelect,
+}: {
+  place: StaticPlace;
+  provider: MapProviderType;
+  onSelect?: (place: StaticPlace) => void;
+}) => {
+  const { colors } = useTheme();
+
+  return (
+    <Pressable
+      style={({ pressed }) => [
+        styles.card,
+        { backgroundColor: colors.background, borderColor: colors.border },
+        pressed && styles.cardPressed,
+      ]}
+      onPress={() => onSelect?.(place)}
+    >
+      <View style={styles.map} pointerEvents="none">
+        <MapView
+          key={provider}
+          staticMode
+          style={StyleSheet.absoluteFill}
+          provider={provider}
+          initialCoordinate={place.coordinate}
+          initialZoom={14}
+        >
+          <Marker coordinate={place.coordinate} />
+        </MapView>
+      </View>
+      <View style={styles.cardContent}>
+        <ThemedText variant="title" style={styles.cardTitle}>
+          {place.name}
+        </ThemedText>
+        <ThemedText variant="caption">{place.description}</ThemedText>
+      </View>
+    </Pressable>
+  );
+};
+
+export const StaticMapsScreen = ({ onSelect }: StaticMapsScreenProps) => {
+  const apiKey = process.env.GOOGLE_MAPS_API_KEY;
+  const { colors } = useTheme();
+
+  const [provider, setProvider] = useState<MapProviderType>(
+    Platform.OS === 'ios' ? 'apple' : 'google'
+  );
+
+  return (
+    <MapProvider apiKey={apiKey}>
+      <FlatList
+        style={{ backgroundColor: colors.background }}
+        contentContainerStyle={styles.list}
+        data={PLACES}
+        keyExtractor={(place) => place.id}
+        ListHeaderComponent={
+          <Button
+            title={provider === 'google' ? 'Apple Maps' : 'Google Maps'}
+            disabled={Platform.OS !== 'ios'}
+            onPress={() =>
+              setProvider((p) => (p === 'google' ? 'apple' : 'google'))
+            }
+          />
+        }
+        renderItem={({ item }) => (
+          <PlaceCard place={item} provider={provider} onSelect={onSelect} />
+        )}
+      />
+    </MapProvider>
+  );
+};
+
+const styles = StyleSheet.create({
+  list: {
+    padding: sizes.lg,
+    gap: sizes.lg,
+  },
+  card: {
+    borderRadius: sizes.radiusLg,
+    borderWidth: StyleSheet.hairlineWidth,
+    overflow: 'hidden',
+  },
+  cardPressed: {
+    opacity: 0.7,
+  },
+  map: {
+    height: 140,
+  },
+  cardContent: {
+    padding: sizes.lg,
+    gap: sizes.xs,
+  },
+  cardTitle: {
+    fontSize: sizes.fontLg,
+  },
+});
diff --git a/example/shared/src/sheets/ControlSheet.tsx b/example/shared/src/sheets/ControlSheet.tsx
index b213aa8..4d0577f 100644
--- a/example/shared/src/sheets/ControlSheet.tsx
+++ b/example/shared/src/sheets/ControlSheet.tsx
@@ -32,6 +32,7 @@ interface ControlSheetProps {
   onToggleMap: () => void;
   onToggleProvider: () => void;
   onLoadGeojson: () => void;
+  onShowStaticMaps?: () => void;
   onDidPresent?: (event: DetentChangeEvent) => void;
   onDetentChange?: (event: DetentChangeEvent) => void;
 }
@@ -58,6 +59,7 @@ export const ControlSheet = forwardRef<ControlSheetRef, ControlSheetProps>(
       onToggleMap,
       onToggleProvider,
       onLoadGeojson,
+      onShowStaticMaps,
       onDidPresent,
       onDetentChange,
     },
@@ -136,6 +138,12 @@ export const ControlSheet = forwardRef<ControlSheetRef, ControlSheetProps>(
             title={hasGeojson ? 'GeoJSON (loaded)' : 'Load GeoJSON'}
             onPress={onLoadGeojson}
           />
+          <Button
+            style={styles.sheetButton}
+            title="Static Maps"
+            disabled={!onShowStaticMaps}
+            onPress={() => onShowStaticMaps?.()}
+          />
         </View>
       </ReanimatedTrueSheet>
     );
diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index bf3db75..1e127f7 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -40,6 +40,7 @@ @implementation LuggMapView {
   BOOL _rotateEnabled;
   BOOL _pitchEnabled;
   BOOL _compassEnabled;
+  BOOL _staticMode;
   BOOL _userLocationEnabled;
   LuggMapViewMapType _mapType;
   LuggMapViewTheme _theme;
@@ -70,6 +71,7 @@ - (instancetype)initWithFrame:(CGRect)frame {
     _rotateEnabled = YES;
     _pitchEnabled = YES;
     _compassEnabled = YES;
+    _staticMode = NO;
     _userLocationEnabled = NO;
     _poiEnabled = NO;
     _poiFilterMode = LuggMapViewPoiFilterMode::Including;
@@ -205,6 +207,7 @@ - (void)initializeProvider {
   }
 
   _provider.delegate = self;
+  _provider.staticMode = _staticMode;
 
   CLLocationCoordinate2D coordinate =
       CLLocationCoordinate2DMake(viewProps.initialCoordinate.latitude,
@@ -303,6 +306,7 @@ - (void)updateProps:(Props::Shared const &)props
       *std::static_pointer_cast<LuggMapViewProps const>(_props);
 
   _providerType = newViewProps.provider;
+  _staticMode = newViewProps.staticMode;
 
   NSString *newMapId =
       [NSString stringWithUTF8String:newViewProps.mapId.c_str()];
diff --git a/ios/core/AppleMapProvider.mm b/ios/core/AppleMapProvider.mm
index 25e5748..90dede4 100644
--- a/ios/core/AppleMapProvider.mm
+++ b/ios/core/AppleMapProvider.mm
@@ -13,6 +13,7 @@
 #import "../LuggPolylineView.h"
 #import "../LuggTileOverlayView.h"
 #import "../extensions/MKMapView+Zoom.h"
+#import "../extensions/UIView+Snapshot.h"
 #import "LuggAnnotationView.h"
 #import "MKPolylineAnimator.h"
 
@@ -119,6 +120,8 @@ @implementation AppleMapProvider {
   LuggAppleMapViewContent *_mapView;
   BOOL _isMapReady;
   BOOL _isDragging;
+  UIImageView *_staticImageView;
+  BOOL _needsStaticSnapshot;
   double _minZoom;
   double _maxZoom;
   NSMapTable<id<MKOverlay>, LuggPolylineView *> *_overlayToPolylineMap;
@@ -145,6 +148,7 @@ @implementation AppleMapProvider {
 }
 
 @synthesize delegate = _delegate;
+@synthesize staticMode = _staticMode;
 
 - (instancetype)init {
   if (self = [super init]) {
@@ -182,6 +186,10 @@ - (void)initializeMapInView:(UIView *)wrapperView
   _mapView.delegate = self;
   _mapView.insetsLayoutMarginsFromSafeArea = NO;
 
+  if (_staticMode) {
+    _mapView.userInteractionEnabled = NO;
+  }
+
   [self applyZoomRange];
 
   _tapGesture =
@@ -212,6 +220,14 @@ - (void)initializeMapInView:(UIView *)wrapperView
 }
 
 - (void)destroy {
+  [_staticImageView removeFromSuperview];
+  _staticImageView = nil;
+  _needsStaticSnapshot = NO;
+  [self destroyMapView];
+  _isMapReady = NO;
+}
+
+- (void)destroyMapView {
   [self dismissNonBubbledCallout];
   [self stopEdgeInsetsAnimation];
   if (_tapGesture) {
@@ -222,9 +238,32 @@ - (void)destroy {
     [_mapView removeGestureRecognizer:_longPressGesture];
     _longPressGesture = nil;
   }
+  _mapView.delegate = nil;
   [_mapView removeFromSuperview];
   _mapView = nil;
-  _isMapReady = NO;
+}
+
+// Static mode: once tiles are fully rendered, swap the live map with a
+// snapshot image and release the map view.
+- (void)swapMapWithStaticImage {
+  if (_staticImageView || !_mapView)
+    return;
+
+  if (!_mapView.window) {
+    _needsStaticSnapshot = YES;
+    return;
+  }
+  _needsStaticSnapshot = NO;
+
+  UIImageView *imageView = [_mapView lugg_snapshotImageView];
+  if (!imageView)
+    return;
+
+  _staticImageView = imageView;
+  [_wrapperView insertSubview:imageView aboveSubview:_mapView];
+
+  [self pauseAnimations];
+  [self destroyMapView];
 }
 
 #pragma mark - Props
@@ -766,6 +805,13 @@ - (void)mapView:(MKMapView *)mapView regionDidChangeAnimated:(BOOL)animated {
                               gesture:wasDragging];
 }
 
+- (void)mapViewDidFinishRenderingMap:(MKMapView *)mapView
+                       fullyRendered:(BOOL)fullyRendered {
+  if (_staticMode && fullyRendered) {
+    [self swapMapWithStaticImage];
+  }
+}
+
 - (MKAnnotationView *)mapView:(MKMapView *)mapView
             viewForAnnotation:(id<MKAnnotation>)annotation {
   if (![annotation isKindOfClass:[AppleMarkerAnnotation class]]) {
@@ -1752,6 +1798,10 @@ - (void)pauseAnimations {
 }
 
 - (void)resumeAnimations {
+  if (_needsStaticSnapshot) {
+    [self swapMapWithStaticImage];
+    return;
+  }
   for (LuggPolylineView *polylineView in _overlayToPolylineMap
            .objectEnumerator) {
     MKPolylineAnimator *renderer = (MKPolylineAnimator *)polylineView.renderer;
diff --git a/ios/core/GoogleMapProvider.mm b/ios/core/GoogleMapProvider.mm
index 40805ee..5acc8e1 100644
--- a/ios/core/GoogleMapProvider.mm
+++ b/ios/core/GoogleMapProvider.mm
@@ -12,6 +12,7 @@
 #import "../LuggPolygonView.h"
 #import "../LuggPolylineView.h"
 #import "../LuggTileOverlayView.h"
+#import "../extensions/UIView+Snapshot.h"
 #import "GMSPolylineAnimator.h"
 #import "PolylineAnimatorBase.h"
 
@@ -28,6 +29,8 @@ @implementation GoogleMapProvider {
   GMSMapView *_mapView;
   BOOL _isMapReady;
   BOOL _isDragging;
+  UIImageView *_staticImageView;
+  BOOL _needsStaticSnapshot;
   LuggMapViewTheme _theme;
   UIEdgeInsets _edgeInsets;
   NSMutableArray<LuggMarkerView *> *_pendingMarkerViews;
@@ -53,6 +56,7 @@ @implementation GoogleMapProvider {
 }
 
 @synthesize delegate = _delegate;
+@synthesize staticMode = _staticMode;
 
 - (instancetype)init {
   if (self = [super init]) {
@@ -113,6 +117,11 @@ - (void)initializeMapInView:(UIView *)wrapperView
   _mapView.paddingAdjustmentBehavior =
       kGMSMapViewPaddingAdjustmentBehaviorNever;
 
+  if (_staticMode) {
+    _mapView.userInteractionEnabled = NO;
+    _mapView.preferredFrameRate = kGMSFrameRateConservative;
+  }
+
   _wrapperView = wrapperView;
   [wrapperView addSubview:_mapView];
 
@@ -130,6 +139,9 @@ - (void)initializeMapInView:(UIView *)wrapperView
 }
 
 - (void)destroy {
+  [_staticImageView removeFromSuperview];
+  _staticImageView = nil;
+  _needsStaticSnapshot = NO;
   [self stopEdgeInsetsAnimation];
   [_pendingMarkerViews removeAllObjects];
   [_pendingPolylineViews removeAllObjects];
@@ -142,10 +154,38 @@ - (void)destroy {
   [_circleToViewMap removeAllObjects];
   [_markerToViewMap removeAllObjects];
   [_groundOverlayToViewMap removeAllObjects];
+  [self destroyMapView];
+  _isMapReady = NO;
+}
+
+- (void)destroyMapView {
+  _mapView.delegate = nil;
   [_mapView clear];
   [_mapView removeFromSuperview];
   _mapView = nil;
-  _isMapReady = NO;
+}
+
+// Static mode: once the map is fully rendered, swap the live map with a
+// snapshot image and release the map view.
+- (void)swapMapWithStaticImage {
+  if (_staticImageView || !_mapView)
+    return;
+
+  if (!_mapView.window) {
+    _needsStaticSnapshot = YES;
+    return;
+  }
+  _needsStaticSnapshot = NO;
+
+  UIImageView *imageView = [_mapView lugg_snapshotImageView];
+  if (!imageView)
+    return;
+
+  _staticImageView = imageView;
+  [_wrapperView insertSubview:imageView aboveSubview:_mapView];
+
+  [self pauseAnimations];
+  [self destroyMapView];
 }
 
 #pragma mark - Props
@@ -307,6 +347,12 @@ - (void)stopEdgeInsetsAnimation {
 
 #pragma mark - GMSMapViewDelegate
 
+- (void)mapViewSnapshotReady:(GMSMapView *)mapView {
+  if (_staticMode) {
+    [self swapMapWithStaticImage];
+  }
+}
+
 - (void)mapView:(GMSMapView *)mapView willMove:(BOOL)gesture {
   _isDragging = gesture;
   if (_isDragging) {
@@ -1114,6 +1160,10 @@ - (void)pauseAnimations {
 }
 
 - (void)resumeAnimations {
+  if (_needsStaticSnapshot) {
+    [self swapMapWithStaticImage];
+    return;
+  }
   for (GMSPolylineAnimator *animator in _polylineAnimators.objectEnumerator) {
     [animator resume];
   }
diff --git a/ios/core/MapProviderDelegate.h b/ios/core/MapProviderDelegate.h
index 87193ab..a3d8017 100644
--- a/ios/core/MapProviderDelegate.h
+++ b/ios/core/MapProviderDelegate.h
@@ -36,6 +36,10 @@ NS_ASSUME_NONNULL_BEGIN
 @property(nonatomic, weak, nullable) id<MapProviderDelegate> delegate;
 @property(nonatomic, readonly) BOOL isMapReady;
 
+// Non-interactive static map. Must be set before initializeMapInView.
+// Once fully rendered, the live map is replaced with a snapshot image.
+@property(nonatomic, assign) BOOL staticMode;
+
 - (void)initializeMapInView:(UIView *)wrapperView
           initialCoordinate:(CLLocationCoordinate2D)coordinate
                 initialZoom:(double)zoom;
diff --git a/ios/extensions/UIView+Snapshot.h b/ios/extensions/UIView+Snapshot.h
new file mode 100644
index 0000000..a71d43c
--- /dev/null
+++ b/ios/extensions/UIView+Snapshot.h
@@ -0,0 +1,16 @@
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface UIView (LuggSnapshot)
+
+/**
+ * Renders the view hierarchy into an image view matching this view's
+ * frame and autoresizing behavior. Returns nil if the view has no size
+ * or the snapshot could not be rendered.
+ */
+- (nullable UIImageView *)lugg_snapshotImageView;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/extensions/UIView+Snapshot.m b/ios/extensions/UIView+Snapshot.m
new file mode 100644
index 0000000..b8143c0
--- /dev/null
+++ b/ios/extensions/UIView+Snapshot.m
@@ -0,0 +1,24 @@
+#import "UIView+Snapshot.h"
+
+@implementation UIView (LuggSnapshot)
+
+- (nullable UIImageView *)lugg_snapshotImageView {
+  CGRect bounds = self.bounds;
+  if (bounds.size.width <= 0 || bounds.size.height <= 0)
+    return nil;
+
+  UIGraphicsImageRenderer *renderer =
+      [[UIGraphicsImageRenderer alloc] initWithBounds:bounds];
+  UIImage *image = [renderer
+      imageWithActions:^(UIGraphicsImageRendererContext *context) {
+        [self drawViewHierarchyInRect:bounds afterScreenUpdates:YES];
+      }];
+
+  UIImageView *imageView = [[UIImageView alloc] initWithFrame:self.frame];
+  imageView.autoresizingMask =
+      UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+  imageView.image = image;
+  return imageView;
+}
+
+@end
diff --git a/src/MapView.tsx b/src/MapView.tsx
index 69cb7e7..34dea0e 100644
--- a/src/MapView.tsx
+++ b/src/MapView.tsx
@@ -94,6 +94,7 @@ export class MapView
       rotateEnabled,
       pitchEnabled,
       compassEnabled,
+      staticMode,
       edgeInsets,
       userLocationEnabled,
       userLocationButtonEnabled,
@@ -126,6 +127,7 @@ export class MapView
         rotateEnabled={rotateEnabled}
         pitchEnabled={pitchEnabled}
         compassEnabled={compassEnabled}
+        staticMode={staticMode}
         edgeInsets={edgeInsets}
         userLocationEnabled={userLocationEnabled}
         userLocationButtonEnabled={userLocationButtonEnabled}
diff --git a/src/MapView.types.ts b/src/MapView.types.ts
index 41986ad..4f367ce 100644
--- a/src/MapView.types.ts
+++ b/src/MapView.types.ts
@@ -210,6 +210,15 @@ export interface MapViewProps extends ViewProps {
    * @default true
    */
   compassEnabled?: boolean;
+  /**
+   * Render the map as a non-interactive, static map.
+   * Uses Google Maps lite mode on Android. On iOS, the map is replaced
+   * with a rendered snapshot once tiles finish loading, releasing the
+   * live map resources. Ideal for maps inside list views.
+   * Cannot be changed after the map is created.
+   * @default false
+   */
+  staticMode?: boolean;
   /**
    * Map content edge insets
    */
diff --git a/src/MapView.web.tsx b/src/MapView.web.tsx
index b0fe5d8..12b7189 100644
--- a/src/MapView.web.tsx
+++ b/src/MapView.web.tsx
@@ -111,6 +111,7 @@ export const MapView = memo(
       scrollEnabled = true,
       pitchEnabled = true,
       compassEnabled = true,
+      staticMode = false,
       edgeInsets,
       userLocationEnabled,
       theme = 'system',
@@ -446,12 +447,13 @@ export const MapView = memo(
         ? 'hybrid'
         : 'roadmap';
 
-    const gestureHandling =
-      scrollEnabled === false && zoomEnabled === false
-        ? 'none'
-        : scrollEnabled === false
-        ? 'cooperative'
-        : 'auto';
+    const gestureHandling = staticMode
+      ? 'none'
+      : scrollEnabled === false && zoomEnabled === false
+      ? 'none'
+      : scrollEnabled === false
+      ? 'cooperative'
+      : 'auto';
 
     const colorScheme =
       theme === 'dark'
diff --git a/src/fabric/LuggMapViewNativeComponent.ts b/src/fabric/LuggMapViewNativeComponent.ts
index d747825..d264289 100644
--- a/src/fabric/LuggMapViewNativeComponent.ts
+++ b/src/fabric/LuggMapViewNativeComponent.ts
@@ -76,6 +76,7 @@ export interface NativeProps extends ViewProps {
   rotateEnabled?: WithDefault<boolean, true>;
   pitchEnabled?: WithDefault<boolean, true>;
   compassEnabled?: WithDefault<boolean, true>;
+  staticMode?: boolean;
   edgeInsets?: EdgeInsets;
   userLocationEnabled?: boolean;
   userLocationButtonEnabled?: boolean;

From 69facf3dee9da102516ffc81cd3f4a36129e039d Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Mon, 6 Jul 2026 23:11:28 +0800
Subject: [PATCH 02/17] perf(ios): throttle static map warmup, opaque
 snapshots; expand example list

---
 docs/MAPVIEW.md                               |  6 ++
 example/bare/ios/Podfile.lock                 |  2 +-
 .../shared/src/screens/StaticMapsScreen.tsx   | 83 ++++++++++++++++-
 ios/LuggMapView.mm                            | 46 +++++++++-
 ios/core/AppleMapProvider.mm                  |  2 +
 ios/core/GoogleMapProvider.mm                 |  2 +
 ios/core/LuggStaticMapWarmupQueue.h           | 26 ++++++
 ios/core/LuggStaticMapWarmupQueue.m           | 89 +++++++++++++++++++
 ios/core/MapProviderDelegate.h                |  1 +
 ios/extensions/UIView+Snapshot.m              |  5 +-
 10 files changed, 256 insertions(+), 6 deletions(-)
 create mode 100644 ios/core/LuggStaticMapWarmupQueue.h
 create mode 100644 ios/core/LuggStaticMapWarmupQueue.m

diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index e844ee1..6d79246 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -79,6 +79,12 @@ Notes:
   and prop updates after the snapshot are ignored on iOS.
 - For taps, wrap the map in a `Pressable` with `pointerEvents="none"` on the
   map container (as above) instead of relying on `onPress`.
+- On iOS, static map warmup is throttled - only a couple of live maps render
+  at a time and each is released once its snapshot is taken, so rows fill in
+  progressively.
+- In long lists, limit how many rows mount at once (e.g. `windowSize`,
+  `initialNumToRender`, `maxToRenderPerBatch` on `FlatList`) - every mounted
+  static map holds its snapshot image in memory.
 
 ## Types
 
diff --git a/example/bare/ios/Podfile.lock b/example/bare/ios/Podfile.lock
index b227082..5894af3 100644
--- a/example/bare/ios/Podfile.lock
+++ b/example/bare/ios/Podfile.lock
@@ -2510,4 +2510,4 @@ SPEC CHECKSUMS:
 
 PODFILE CHECKSUM: a8c918957730cfd546eb917e7563885b57095460
 
-COCOAPODS: 1.16.2
+COCOAPODS: 1.15.2
diff --git a/example/shared/src/screens/StaticMapsScreen.tsx b/example/shared/src/screens/StaticMapsScreen.tsx
index 26ba60a..a278ecc 100644
--- a/example/shared/src/screens/StaticMapsScreen.tsx
+++ b/example/shared/src/screens/StaticMapsScreen.tsx
@@ -8,17 +8,39 @@ import {
   type MapProviderType,
 } from '@lugg/maps';
 
-import { Button, ThemedText } from '../components';
+import {
+  Button,
+  MarkerIcon,
+  MarkerImage,
+  MarkerText,
+  ThemedText,
+} from '../components';
 import { sizes, useTheme } from '../theme';
 
+type StaticMarkerType = 'default' | 'icon' | 'text' | 'image' | 'multiple';
+
+const MARKER_TYPES: StaticMarkerType[] = [
+  'default',
+  'icon',
+  'text',
+  'image',
+  'multiple',
+];
+
 export interface StaticPlace {
   id: string;
   name: string;
   description: string;
   coordinate: Coordinate;
+  markerType: StaticMarkerType;
+  markerText: string;
+  imageUrl: string;
 }
 
-const PLACES: StaticPlace[] = [
+const BASE_PLACES: Omit<
+  StaticPlace,
+  'markerType' | 'markerText' | 'imageUrl'
+>[] = [
   {
     id: 'golden-gate-bridge',
     name: 'Golden Gate Bridge',
@@ -57,6 +79,60 @@ const PLACES: StaticPlace[] = [
   },
 ];
 
+// Large list for performance testing - cycles the base places with
+// shifted coordinates so every map renders a unique region, and cycles
+// marker use-cases so snapshots cover default, custom, and live markers
+const PLACES: StaticPlace[] = Array.from({ length: 100 }, (_, i) => {
+  const base = BASE_PLACES[i % BASE_PLACES.length]!;
+  const shift = Math.floor(i / BASE_PLACES.length) * 0.015;
+  return {
+    ...base,
+    id: `${base.id}-${i}`,
+    name: `${i + 1}. ${base.name}`,
+    coordinate: {
+      latitude: base.coordinate.latitude + shift,
+      longitude: base.coordinate.longitude - shift,
+    },
+    markerType: MARKER_TYPES[i % MARKER_TYPES.length]!,
+    markerText: `${i + 1}`,
+    imageUrl: `https://i.pravatar.cc/100?img=${(i % 70) + 1}`,
+  };
+});
+
+const PlaceMarkers = ({ place }: { place: StaticPlace }) => {
+  const { coordinate, markerType, markerText, imageUrl } = place;
+
+  switch (markerType) {
+    case 'icon':
+      return <MarkerIcon coordinate={coordinate} />;
+    case 'text':
+      return <MarkerText coordinate={coordinate} text={markerText} />;
+    case 'image':
+      return <MarkerImage coordinate={coordinate} source={{ uri: imageUrl }} />;
+    case 'multiple':
+      return (
+        <>
+          <Marker coordinate={coordinate} />
+          <MarkerText
+            coordinate={{
+              latitude: coordinate.latitude + 0.003,
+              longitude: coordinate.longitude - 0.004,
+            }}
+            text={markerText}
+          />
+          <MarkerIcon
+            coordinate={{
+              latitude: coordinate.latitude - 0.002,
+              longitude: coordinate.longitude + 0.004,
+            }}
+          />
+        </>
+      );
+    default:
+      return <Marker coordinate={coordinate} />;
+  }
+};
+
 interface StaticMapsScreenProps {
   onSelect?: (place: StaticPlace) => void;
 }
@@ -90,7 +166,7 @@ const PlaceCard = ({
           initialCoordinate={place.coordinate}
           initialZoom={14}
         >
-          <Marker coordinate={place.coordinate} />
+          <PlaceMarkers place={place} />
         </MapView>
       </View>
       <View style={styles.cardContent}>
@@ -98,6 +174,7 @@ const PlaceCard = ({
           {place.name}
         </ThemedText>
         <ThemedText variant="caption">{place.description}</ThemedText>
+        <ThemedText variant="caption">Marker: {place.markerType}</ThemedText>
       </View>
     </Pressable>
   );
diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index 1e127f7..2f99777 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -8,6 +8,7 @@
 #import "LuggTileOverlayView.h"
 #import "core/AppleMapProvider.h"
 #import "core/GoogleMapProvider.h"
+#import "core/LuggStaticMapWarmupQueue.h"
 #import "core/MapProviderDelegate.h"
 #import "events/CameraIdleEvent.h"
 #import "events/CameraMoveEvent.h"
@@ -41,6 +42,8 @@ @implementation LuggMapView {
   BOOL _pitchEnabled;
   BOOL _compassEnabled;
   BOOL _staticMode;
+  BOOL _waitingForWarmupSlot;
+  BOOL _holdingWarmupSlot;
   BOOL _userLocationEnabled;
   LuggMapViewMapType _mapType;
   LuggMapViewTheme _theme;
@@ -172,17 +175,54 @@ - (void)didMoveToWindow {
   [super didMoveToWindow];
   if (self.window) {
     if (!_provider && _mapWrapperView) {
-      [self initializeProvider];
+      if (_staticMode) {
+        [self requestStaticWarmup];
+      } else {
+        [self initializeProvider];
+      }
     }
     [_provider resumeAnimations];
   } else {
+    if (_waitingForWarmupSlot) {
+      [[LuggStaticMapWarmupQueue sharedQueue] cancelOwner:self];
+      _waitingForWarmupSlot = NO;
+    }
     [_provider pauseAnimations];
   }
 }
 
+- (void)requestStaticWarmup {
+  if (_waitingForWarmupSlot || _holdingWarmupSlot)
+    return;
+
+  _waitingForWarmupSlot = YES;
+  __weak LuggMapView *weakSelf = self;
+  [[LuggStaticMapWarmupQueue sharedQueue]
+      requestSlotForOwner:self
+               completion:^{
+                 LuggMapView *strongSelf = weakSelf;
+                 if (!strongSelf)
+                   return;
+                 strongSelf->_waitingForWarmupSlot = NO;
+                 strongSelf->_holdingWarmupSlot = YES;
+                 [strongSelf initializeProvider];
+               }];
+}
+
+- (void)releaseWarmupSlot {
+  if (_holdingWarmupSlot) {
+    _holdingWarmupSlot = NO;
+    [[LuggStaticMapWarmupQueue sharedQueue] releaseSlotForOwner:self];
+  }
+}
+
 - (void)prepareForRecycle {
   [super prepareForRecycle];
 
+  [[LuggStaticMapWarmupQueue sharedQueue] cancelOwner:self];
+  _waitingForWarmupSlot = NO;
+  [self releaseWarmupSlot];
+
   [_provider destroy];
   _provider = nil;
   _mapWrapperView = nil;
@@ -247,6 +287,10 @@ - (void)mapProviderDidReady {
   ReadyEvent::emit<LuggMapViewEventEmitter>(_eventEmitter);
 }
 
+- (void)mapProviderDidFinishStaticSnapshot {
+  [self releaseWarmupSlot];
+}
+
 - (void)mapProviderDidMoveCamera:(double)latitude
                        longitude:(double)longitude
                             zoom:(double)zoom
diff --git a/ios/core/AppleMapProvider.mm b/ios/core/AppleMapProvider.mm
index 90dede4..1029aae 100644
--- a/ios/core/AppleMapProvider.mm
+++ b/ios/core/AppleMapProvider.mm
@@ -264,6 +264,8 @@ - (void)swapMapWithStaticImage {
 
   [self pauseAnimations];
   [self destroyMapView];
+
+  [_delegate mapProviderDidFinishStaticSnapshot];
 }
 
 #pragma mark - Props
diff --git a/ios/core/GoogleMapProvider.mm b/ios/core/GoogleMapProvider.mm
index 5acc8e1..4a0c831 100644
--- a/ios/core/GoogleMapProvider.mm
+++ b/ios/core/GoogleMapProvider.mm
@@ -186,6 +186,8 @@ - (void)swapMapWithStaticImage {
 
   [self pauseAnimations];
   [self destroyMapView];
+
+  [_delegate mapProviderDidFinishStaticSnapshot];
 }
 
 #pragma mark - Props
diff --git a/ios/core/LuggStaticMapWarmupQueue.h b/ios/core/LuggStaticMapWarmupQueue.h
new file mode 100644
index 0000000..5cbdac6
--- /dev/null
+++ b/ios/core/LuggStaticMapWarmupQueue.h
@@ -0,0 +1,26 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Serializes static map warmup so only a few live maps exist at a time.
+ * Static maps briefly need a live map view to render their snapshot;
+ * without throttling, a list mounting many rows creates them all at once
+ * and stalls the main thread.
+ */
+@interface LuggStaticMapWarmupQueue : NSObject
+
++ (instancetype)sharedQueue;
+
+/// Calls completion when a warmup slot is available (possibly immediately).
+- (void)requestSlotForOwner:(id)owner completion:(dispatch_block_t)completion;
+
+/// Removes any pending request for the owner.
+- (void)cancelOwner:(id)owner;
+
+/// Frees the owner's slot and starts the next pending warmup.
+- (void)releaseSlotForOwner:(id)owner;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/core/LuggStaticMapWarmupQueue.m b/ios/core/LuggStaticMapWarmupQueue.m
new file mode 100644
index 0000000..d332474
--- /dev/null
+++ b/ios/core/LuggStaticMapWarmupQueue.m
@@ -0,0 +1,89 @@
+#import "LuggStaticMapWarmupQueue.h"
+
+static const NSUInteger kMaxConcurrentWarmups = 2;
+// Slot is force-released if a map never finishes rendering (e.g. offline)
+// so it can't starve the queue. The live map is left in place.
+static const int64_t kWarmupTimeoutSeconds = 10;
+
+@interface LuggWarmupRequest : NSObject
+@property(nonatomic, weak) id owner;
+@property(nonatomic, copy) dispatch_block_t completion;
+@end
+
+@implementation LuggWarmupRequest
+@end
+
+@implementation LuggStaticMapWarmupQueue {
+  NSMutableArray<LuggWarmupRequest *> *_pending;
+  NSHashTable<id> *_active;
+}
+
++ (instancetype)sharedQueue {
+  static LuggStaticMapWarmupQueue *queue;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    queue = [[LuggStaticMapWarmupQueue alloc] init];
+  });
+  return queue;
+}
+
+- (instancetype)init {
+  if (self = [super init]) {
+    _pending = [NSMutableArray array];
+    _active = [NSHashTable weakObjectsHashTable];
+  }
+  return self;
+}
+
+- (void)requestSlotForOwner:(id)owner completion:(dispatch_block_t)completion {
+  LuggWarmupRequest *request = [[LuggWarmupRequest alloc] init];
+  request.owner = owner;
+  request.completion = completion;
+  [_pending addObject:request];
+  [self drain];
+}
+
+- (void)cancelOwner:(id)owner {
+  NSMutableArray<LuggWarmupRequest *> *remaining = [NSMutableArray array];
+  for (LuggWarmupRequest *request in _pending) {
+    if (request.owner != nil && request.owner != owner) {
+      [remaining addObject:request];
+    }
+  }
+  _pending = remaining;
+}
+
+- (void)releaseSlotForOwner:(id)owner {
+  if (![_active containsObject:owner])
+    return;
+  [_active removeObject:owner];
+  [self drain];
+}
+
+- (void)drain {
+  while (_active.count < kMaxConcurrentWarmups && _pending.count > 0) {
+    LuggWarmupRequest *request = _pending.firstObject;
+    [_pending removeObjectAtIndex:0];
+    id owner = request.owner;
+    if (!owner)
+      continue;
+    [_active addObject:owner];
+    [self scheduleTimeoutForOwner:owner];
+    request.completion();
+  }
+}
+
+- (void)scheduleTimeoutForOwner:(id)owner {
+  __weak LuggStaticMapWarmupQueue *weakSelf = self;
+  __weak id weakOwner = owner;
+  dispatch_after(
+      dispatch_time(DISPATCH_TIME_NOW, kWarmupTimeoutSeconds * NSEC_PER_SEC),
+      dispatch_get_main_queue(), ^{
+        id strongOwner = weakOwner;
+        if (strongOwner) {
+          [weakSelf releaseSlotForOwner:strongOwner];
+        }
+      });
+}
+
+@end
diff --git a/ios/core/MapProviderDelegate.h b/ios/core/MapProviderDelegate.h
index a3d8017..96db39f 100644
--- a/ios/core/MapProviderDelegate.h
+++ b/ios/core/MapProviderDelegate.h
@@ -13,6 +13,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 @protocol MapProviderDelegate <NSObject>
 - (void)mapProviderDidReady;
+- (void)mapProviderDidFinishStaticSnapshot;
 - (void)mapProviderDidMoveCamera:(double)latitude
                        longitude:(double)longitude
                             zoom:(double)zoom
diff --git a/ios/extensions/UIView+Snapshot.m b/ios/extensions/UIView+Snapshot.m
index b8143c0..27410c4 100644
--- a/ios/extensions/UIView+Snapshot.m
+++ b/ios/extensions/UIView+Snapshot.m
@@ -7,8 +7,11 @@ - (nullable UIImageView *)lugg_snapshotImageView {
   if (bounds.size.width <= 0 || bounds.size.height <= 0)
     return nil;
 
+  UIGraphicsImageRendererFormat *format =
+      [UIGraphicsImageRendererFormat preferredFormat];
+  format.opaque = YES;
   UIGraphicsImageRenderer *renderer =
-      [[UIGraphicsImageRenderer alloc] initWithBounds:bounds];
+      [[UIGraphicsImageRenderer alloc] initWithBounds:bounds format:format];
   UIImage *image = [renderer
       imageWithActions:^(UIGraphicsImageRendererContext *context) {
         [self drawViewHierarchyInRect:bounds afterScreenUpdates:YES];

From e2e65fc3f37680d0b78a3d0e7e1eebd2daade51c Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Tue, 7 Jul 2026 00:05:23 +0800
Subject: [PATCH 03/17] perf(ios): async static snapshots, staticKey cache,
 warmup placeholder

---
 .../src/main/java/com/luggmaps/LuggMapView.kt | 27 +++++
 .../java/com/luggmaps/LuggMapViewManager.kt   |  4 +
 docs/MAPVIEW.md                               | 16 ++-
 example/bare/ios/Podfile.lock                 |  2 +-
 .../shared/src/screens/StaticMapsScreen.tsx   |  1 +
 ios/LuggMapView.mm                            | 98 ++++++++++++++++++-
 ios/core/AppleMapProvider.mm                  | 33 +++++--
 ios/core/GoogleMapProvider.mm                 | 33 +++++--
 ios/core/LuggStaticMapWarmupQueue.m           | 28 +++++-
 ios/core/MapProviderDelegate.h                |  1 +
 ios/extensions/UIView+Snapshot.h              |  6 +-
 ios/extensions/UIView+Snapshot.m              |  2 +-
 src/MapView.tsx                               |  2 +
 src/MapView.types.ts                          |  9 ++
 src/fabric/LuggMapViewNativeComponent.ts      |  1 +
 15 files changed, 241 insertions(+), 22 deletions(-)

diff --git a/android/src/main/java/com/luggmaps/LuggMapView.kt b/android/src/main/java/com/luggmaps/LuggMapView.kt
index 0f9ff83..4c66b59 100644
--- a/android/src/main/java/com/luggmaps/LuggMapView.kt
+++ b/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
@@ -133,6 +134,10 @@ 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
@@ -156,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
@@ -350,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()
+  }
 }
diff --git a/android/src/main/java/com/luggmaps/LuggMapViewManager.kt b/android/src/main/java/com/luggmaps/LuggMapViewManager.kt
index 5875f92..1ef6873 100644
--- a/android/src/main/java/com/luggmaps/LuggMapViewManager.kt
+++ b/android/src/main/java/com/luggmaps/LuggMapViewManager.kt
@@ -142,6 +142,10 @@ class LuggMapViewManager :
     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)
diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index 6d79246..490e589 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -34,6 +34,7 @@ import { MapView } from '@lugg/maps';
 | `pitchEnabled` | `boolean` | `true` | Enable pitch/tilt gestures |
 | `compassEnabled` | `boolean` | `true` | Show compass on the map (rotate control on web) |
 | `staticMode` | `boolean` | `false` | Render as a non-interactive [static map](#static-maps). Ideal for list views |
+| `staticKey` | `string` | - | Stable identity for the static snapshot cache (iOS). See [Static Maps](#static-maps) |
 | `edgeInsets` | `EdgeInsets` | - | Map content edge insets |
 | `userLocationEnabled` | `boolean` | `false` | Show current user location on the map |
 | `userLocationButtonEnabled` | `boolean` | `false` | Show native my-location button (Android only) |
@@ -62,6 +63,7 @@ mounting many live maps is expensive:
   <View style={{ height: 140 }} pointerEvents="none">
     <MapView
       staticMode
+      staticKey={place.id}
       style={StyleSheet.absoluteFill}
       initialCoordinate={place.coordinate}
       initialZoom={14}
@@ -79,9 +81,17 @@ Notes:
   and prop updates after the snapshot are ignored on iOS.
 - For taps, wrap the map in a `Pressable` with `pointerEvents="none"` on the
   map container (as above) instead of relying on `onPress`.
-- On iOS, static map warmup is throttled - only a couple of live maps render
-  at a time and each is released once its snapshot is taken, so rows fill in
-  progressively.
+- On iOS, static map rendering is paced to never compete with scroll
+  gestures, so rows fill in progressively while scrolling stays smooth.
+- While a static map loads, a theme-aware placeholder background is shown.
+  Set a `backgroundColor` style on the `MapView` to use your own.
+- Set `staticKey` (e.g. your list item's id) to cache snapshots across
+  list recycling on iOS - scrolling back to a row reuses its snapshot
+  instead of rendering a live map again. The key must uniquely identify the
+  map's content, including markers; the cache is evicted on memory pressure.
+- Alternatively, keeping rows mounted (larger `windowSize` with
+  `removeClippedSubviews`) avoids re-rendering entirely at the cost of
+  holding every row's snapshot in memory.
 - In long lists, limit how many rows mount at once (e.g. `windowSize`,
   `initialNumToRender`, `maxToRenderPerBatch` on `FlatList`) - every mounted
   static map holds its snapshot image in memory.
diff --git a/example/bare/ios/Podfile.lock b/example/bare/ios/Podfile.lock
index 5894af3..b227082 100644
--- a/example/bare/ios/Podfile.lock
+++ b/example/bare/ios/Podfile.lock
@@ -2510,4 +2510,4 @@ SPEC CHECKSUMS:
 
 PODFILE CHECKSUM: a8c918957730cfd546eb917e7563885b57095460
 
-COCOAPODS: 1.15.2
+COCOAPODS: 1.16.2
diff --git a/example/shared/src/screens/StaticMapsScreen.tsx b/example/shared/src/screens/StaticMapsScreen.tsx
index a278ecc..f9de5df 100644
--- a/example/shared/src/screens/StaticMapsScreen.tsx
+++ b/example/shared/src/screens/StaticMapsScreen.tsx
@@ -161,6 +161,7 @@ const PlaceCard = ({
         <MapView
           key={provider}
           staticMode
+          staticKey={place.id}
           style={StyleSheet.absoluteFill}
           provider={provider}
           initialCoordinate={place.coordinate}
diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index 2f99777..7a87bdb 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -26,6 +26,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. Evicted on memory
+// pressure.
+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;
+  });
+  return cache;
+}
+
 @interface LuggMapView () <RCTLuggMapViewViewProtocol, MapProviderDelegate>
 @end
 
@@ -42,6 +55,8 @@ @implementation LuggMapView {
   BOOL _pitchEnabled;
   BOOL _compassEnabled;
   BOOL _staticMode;
+  NSString *_staticKey;
+  UIImageView *_staticCachedImageView;
   BOOL _waitingForWarmupSlot;
   BOOL _holdingWarmupSlot;
   BOOL _userLocationEnabled;
@@ -75,6 +90,7 @@ - (instancetype)initWithFrame:(CGRect)frame {
     _pitchEnabled = YES;
     _compassEnabled = YES;
     _staticMode = NO;
+    _staticKey = @"";
     _userLocationEnabled = NO;
     _poiEnabled = NO;
     _poiFilterMode = LuggMapViewPoiFilterMode::Including;
@@ -176,7 +192,10 @@ - (void)didMoveToWindow {
   if (self.window) {
     if (!_provider && _mapWrapperView) {
       if (_staticMode) {
-        [self requestStaticWarmup];
+        [self applyStaticPlaceholderBackground];
+        if (![self showCachedStaticSnapshot]) {
+          [self requestStaticWarmup];
+        }
       } else {
         [self initializeProvider];
       }
@@ -191,6 +210,72 @@ - (void)didMoveToWindow {
   }
 }
 
+// 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;
+
+  return [NSString stringWithFormat:@"%@|%d|%@|%d|%ld|%.0fx%.0f", _staticKey,
+                                    (int)_providerType, _mapId, (int)_mapType,
+                                    (long)style, size.width, size.height];
+}
+
+- (BOOL)showCachedStaticSnapshot {
+  if (_staticCachedImageView)
+    return YES;
+
+  NSString *key = [self staticSnapshotCacheKey];
+  if (!key)
+    return NO;
+
+  UIImage *image = [StaticSnapshotCache() objectForKey:key];
+  if (!image)
+    return NO;
+
+  UIImageView *imageView =
+      [[UIImageView alloc] initWithFrame:_mapWrapperView.bounds];
+  imageView.autoresizingMask =
+      UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+  imageView.image = image;
+  [_mapWrapperView addSubview:imageView];
+  _staticCachedImageView = imageView;
+
+  ReadyEvent::emit<LuggMapViewEventEmitter>(_eventEmitter);
+  return YES;
+}
+
 - (void)requestStaticWarmup {
   if (_waitingForWarmupSlot || _holdingWarmupSlot)
     return;
@@ -223,6 +308,9 @@ - (void)prepareForRecycle {
   _waitingForWarmupSlot = NO;
   [self releaseWarmupSlot];
 
+  [_staticCachedImageView removeFromSuperview];
+  _staticCachedImageView = nil;
+
   [_provider destroy];
   _provider = nil;
   _mapWrapperView = nil;
@@ -291,6 +379,13 @@ - (void)mapProviderDidFinishStaticSnapshot {
   [self releaseWarmupSlot];
 }
 
+- (void)mapProviderDidCaptureStaticImage:(UIImage *)image {
+  NSString *key = [self staticSnapshotCacheKey];
+  if (key) {
+    [StaticSnapshotCache() setObject:image forKey:key];
+  }
+}
+
 - (void)mapProviderDidMoveCamera:(double)latitude
                        longitude:(double)longitude
                             zoom:(double)zoom
@@ -351,6 +446,7 @@ - (void)updateProps:(Props::Shared const &)props
 
   _providerType = newViewProps.provider;
   _staticMode = newViewProps.staticMode;
+  _staticKey = [NSString stringWithUTF8String:newViewProps.staticKey.c_str()];
 
   NSString *newMapId =
       [NSString stringWithUTF8String:newViewProps.mapId.c_str()];
diff --git a/ios/core/AppleMapProvider.mm b/ios/core/AppleMapProvider.mm
index 1029aae..59c8807 100644
--- a/ios/core/AppleMapProvider.mm
+++ b/ios/core/AppleMapProvider.mm
@@ -120,8 +120,9 @@ @implementation AppleMapProvider {
   LuggAppleMapViewContent *_mapView;
   BOOL _isMapReady;
   BOOL _isDragging;
-  UIImageView *_staticImageView;
+  UIImageView *_staticSnapshotView;
   BOOL _needsStaticSnapshot;
+  BOOL _staticSwapScheduled;
   double _minZoom;
   double _maxZoom;
   NSMapTable<id<MKOverlay>, LuggPolylineView *> *_overlayToPolylineMap;
@@ -220,8 +221,8 @@ - (void)initializeMapInView:(UIView *)wrapperView
 }
 
 - (void)destroy {
-  [_staticImageView removeFromSuperview];
-  _staticImageView = nil;
+  [_staticSnapshotView removeFromSuperview];
+  _staticSnapshotView = nil;
   _needsStaticSnapshot = NO;
   [self destroyMapView];
   _isMapReady = NO;
@@ -244,9 +245,11 @@ - (void)destroyMapView {
 }
 
 // Static mode: once tiles are fully rendered, swap the live map with a
-// snapshot image and release the map view.
+// snapshot image and release the map view. The snapshot render and map
+// teardown are expensive, so they run outside scroll tracking; the live
+// map keeps displaying until then.
 - (void)swapMapWithStaticImage {
-  if (_staticImageView || !_mapView)
+  if (_staticSnapshotView || _staticSwapScheduled || !_mapView)
     return;
 
   if (!_mapView.window) {
@@ -255,16 +258,34 @@ - (void)swapMapWithStaticImage {
   }
   _needsStaticSnapshot = NO;
 
+  _staticSwapScheduled = YES;
+  [[NSRunLoop mainRunLoop] performInModes:@[ NSDefaultRunLoopMode ]
+                                    block:^{
+                                      self->_staticSwapScheduled = NO;
+                                      [self performStaticSwap];
+                                    }];
+}
+
+- (void)performStaticSwap {
+  if (_staticSnapshotView || !_mapView)
+    return;
+
+  if (!_mapView.window) {
+    _needsStaticSnapshot = YES;
+    return;
+  }
+
   UIImageView *imageView = [_mapView lugg_snapshotImageView];
   if (!imageView)
     return;
 
-  _staticImageView = imageView;
+  _staticSnapshotView = imageView;
   [_wrapperView insertSubview:imageView aboveSubview:_mapView];
 
   [self pauseAnimations];
   [self destroyMapView];
 
+  [_delegate mapProviderDidCaptureStaticImage:imageView.image];
   [_delegate mapProviderDidFinishStaticSnapshot];
 }
 
diff --git a/ios/core/GoogleMapProvider.mm b/ios/core/GoogleMapProvider.mm
index 4a0c831..21103f1 100644
--- a/ios/core/GoogleMapProvider.mm
+++ b/ios/core/GoogleMapProvider.mm
@@ -29,8 +29,9 @@ @implementation GoogleMapProvider {
   GMSMapView *_mapView;
   BOOL _isMapReady;
   BOOL _isDragging;
-  UIImageView *_staticImageView;
+  UIImageView *_staticSnapshotView;
   BOOL _needsStaticSnapshot;
+  BOOL _staticSwapScheduled;
   LuggMapViewTheme _theme;
   UIEdgeInsets _edgeInsets;
   NSMutableArray<LuggMarkerView *> *_pendingMarkerViews;
@@ -139,8 +140,8 @@ - (void)initializeMapInView:(UIView *)wrapperView
 }
 
 - (void)destroy {
-  [_staticImageView removeFromSuperview];
-  _staticImageView = nil;
+  [_staticSnapshotView removeFromSuperview];
+  _staticSnapshotView = nil;
   _needsStaticSnapshot = NO;
   [self stopEdgeInsetsAnimation];
   [_pendingMarkerViews removeAllObjects];
@@ -166,9 +167,11 @@ - (void)destroyMapView {
 }
 
 // Static mode: once the map is fully rendered, swap the live map with a
-// snapshot image and release the map view.
+// snapshot image and release the map view. The snapshot render and map
+// teardown are expensive, so they run outside scroll tracking; the live
+// map keeps displaying until then.
 - (void)swapMapWithStaticImage {
-  if (_staticImageView || !_mapView)
+  if (_staticSnapshotView || _staticSwapScheduled || !_mapView)
     return;
 
   if (!_mapView.window) {
@@ -177,16 +180,34 @@ - (void)swapMapWithStaticImage {
   }
   _needsStaticSnapshot = NO;
 
+  _staticSwapScheduled = YES;
+  [[NSRunLoop mainRunLoop] performInModes:@[ NSDefaultRunLoopMode ]
+                                    block:^{
+                                      self->_staticSwapScheduled = NO;
+                                      [self performStaticSwap];
+                                    }];
+}
+
+- (void)performStaticSwap {
+  if (_staticSnapshotView || !_mapView)
+    return;
+
+  if (!_mapView.window) {
+    _needsStaticSnapshot = YES;
+    return;
+  }
+
   UIImageView *imageView = [_mapView lugg_snapshotImageView];
   if (!imageView)
     return;
 
-  _staticImageView = imageView;
+  _staticSnapshotView = imageView;
   [_wrapperView insertSubview:imageView aboveSubview:_mapView];
 
   [self pauseAnimations];
   [self destroyMapView];
 
+  [_delegate mapProviderDidCaptureStaticImage:imageView.image];
   [_delegate mapProviderDidFinishStaticSnapshot];
 }
 
diff --git a/ios/core/LuggStaticMapWarmupQueue.m b/ios/core/LuggStaticMapWarmupQueue.m
index d332474..50dbafd 100644
--- a/ios/core/LuggStaticMapWarmupQueue.m
+++ b/ios/core/LuggStaticMapWarmupQueue.m
@@ -1,6 +1,8 @@
 #import "LuggStaticMapWarmupQueue.h"
 
-static const NSUInteger kMaxConcurrentWarmups = 2;
+// No concurrency cap - warmups are paced by the runloop instead (one grant
+// per pass, outside scroll tracking)
+static const NSUInteger kMaxConcurrentWarmups = NSUIntegerMax;
 // Slot is force-released if a map never finishes rendering (e.g. offline)
 // so it can't starve the queue. The live map is left in place.
 static const int64_t kWarmupTimeoutSeconds = 10;
@@ -16,6 +18,7 @@ @implementation LuggWarmupRequest
 @implementation LuggStaticMapWarmupQueue {
   NSMutableArray<LuggWarmupRequest *> *_pending;
   NSHashTable<id> *_active;
+  BOOL _drainScheduled;
 }
 
 + (instancetype)sharedQueue {
@@ -60,7 +63,29 @@ - (void)releaseSlotForOwner:(id)owner {
   [self drain];
 }
 
+// Grants run in NSDefaultRunLoopMode - not serviced while the user is
+// actively dragging - and one per runloop pass, so map creation never
+// competes with scroll gestures for the main thread.
 - (void)drain {
+  if (_drainScheduled || _pending.count == 0 ||
+      _active.count >= kMaxConcurrentWarmups)
+    return;
+
+  _drainScheduled = YES;
+  __weak LuggStaticMapWarmupQueue *weakSelf = self;
+  [[NSRunLoop mainRunLoop]
+      performInModes:@[ NSDefaultRunLoopMode ]
+               block:^{
+                 LuggStaticMapWarmupQueue *strongSelf = weakSelf;
+                 if (!strongSelf)
+                   return;
+                 strongSelf->_drainScheduled = NO;
+                 [strongSelf grantNext];
+                 [strongSelf drain];
+               }];
+}
+
+- (void)grantNext {
   while (_active.count < kMaxConcurrentWarmups && _pending.count > 0) {
     LuggWarmupRequest *request = _pending.firstObject;
     [_pending removeObjectAtIndex:0];
@@ -70,6 +95,7 @@ - (void)drain {
     [_active addObject:owner];
     [self scheduleTimeoutForOwner:owner];
     request.completion();
+    return;
   }
 }
 
diff --git a/ios/core/MapProviderDelegate.h b/ios/core/MapProviderDelegate.h
index 96db39f..e421319 100644
--- a/ios/core/MapProviderDelegate.h
+++ b/ios/core/MapProviderDelegate.h
@@ -14,6 +14,7 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol MapProviderDelegate <NSObject>
 - (void)mapProviderDidReady;
 - (void)mapProviderDidFinishStaticSnapshot;
+- (void)mapProviderDidCaptureStaticImage:(UIImage *)image;
 - (void)mapProviderDidMoveCamera:(double)latitude
                        longitude:(double)longitude
                             zoom:(double)zoom
diff --git a/ios/extensions/UIView+Snapshot.h b/ios/extensions/UIView+Snapshot.h
index a71d43c..73a44a9 100644
--- a/ios/extensions/UIView+Snapshot.h
+++ b/ios/extensions/UIView+Snapshot.h
@@ -5,9 +5,9 @@ NS_ASSUME_NONNULL_BEGIN
 @interface UIView (LuggSnapshot)
 
 /**
- * Renders the view hierarchy into an image view matching this view's
- * frame and autoresizing behavior. Returns nil if the view has no size
- * or the snapshot could not be rendered.
+ * Renders the currently presented content into an image view matching
+ * this view's frame and autoresizing behavior. Returns nil if the view
+ * has no size or the snapshot could not be rendered.
  */
 - (nullable UIImageView *)lugg_snapshotImageView;
 
diff --git a/ios/extensions/UIView+Snapshot.m b/ios/extensions/UIView+Snapshot.m
index 27410c4..986868b 100644
--- a/ios/extensions/UIView+Snapshot.m
+++ b/ios/extensions/UIView+Snapshot.m
@@ -14,7 +14,7 @@ - (nullable UIImageView *)lugg_snapshotImageView {
       [[UIGraphicsImageRenderer alloc] initWithBounds:bounds format:format];
   UIImage *image = [renderer
       imageWithActions:^(UIGraphicsImageRendererContext *context) {
-        [self drawViewHierarchyInRect:bounds afterScreenUpdates:YES];
+        [self drawViewHierarchyInRect:bounds afterScreenUpdates:NO];
       }];
 
   UIImageView *imageView = [[UIImageView alloc] initWithFrame:self.frame];
diff --git a/src/MapView.tsx b/src/MapView.tsx
index 34dea0e..715a917 100644
--- a/src/MapView.tsx
+++ b/src/MapView.tsx
@@ -95,6 +95,7 @@ export class MapView
       pitchEnabled,
       compassEnabled,
       staticMode,
+      staticKey,
       edgeInsets,
       userLocationEnabled,
       userLocationButtonEnabled,
@@ -128,6 +129,7 @@ export class MapView
         pitchEnabled={pitchEnabled}
         compassEnabled={compassEnabled}
         staticMode={staticMode}
+        staticKey={staticKey}
         edgeInsets={edgeInsets}
         userLocationEnabled={userLocationEnabled}
         userLocationButtonEnabled={userLocationButtonEnabled}
diff --git a/src/MapView.types.ts b/src/MapView.types.ts
index 4f367ce..dace9b7 100644
--- a/src/MapView.types.ts
+++ b/src/MapView.types.ts
@@ -219,6 +219,15 @@ export interface MapViewProps extends ViewProps {
    * @default false
    */
   staticMode?: boolean;
+  /**
+   * Stable identity for the static snapshot cache (iOS). When set, a map
+   * remounted with the same key (and same size, provider, and map settings)
+   * reuses its cached snapshot instead of rendering a live map again -
+   * e.g. set it to your list item's id. The key must uniquely identify the
+   * map's content, including markers and other children.
+   * Only used with staticMode.
+   */
+  staticKey?: string;
   /**
    * Map content edge insets
    */
diff --git a/src/fabric/LuggMapViewNativeComponent.ts b/src/fabric/LuggMapViewNativeComponent.ts
index d264289..c81f874 100644
--- a/src/fabric/LuggMapViewNativeComponent.ts
+++ b/src/fabric/LuggMapViewNativeComponent.ts
@@ -77,6 +77,7 @@ export interface NativeProps extends ViewProps {
   pitchEnabled?: WithDefault<boolean, true>;
   compassEnabled?: WithDefault<boolean, true>;
   staticMode?: boolean;
+  staticKey?: string;
   edgeInsets?: EdgeInsets;
   userLocationEnabled?: boolean;
   userLocationButtonEnabled?: boolean;

From 63dcba3c8bb8a165045fc5077bd19fe002345e0e Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Tue, 7 Jul 2026 03:25:36 +0800
Subject: [PATCH 04/17] fix(ios): guard MKPolylineAnimator against background
 draw races

drawMapRect: runs on MapKit's background render queues; snapshot
polyline/distances/colors so main-thread updates can't cause
out-of-bounds reads or use-after-free of the color cache
---
 ios/core/MKPolylineAnimator.m | 110 +++++++++++++++++++++-------------
 1 file changed, 67 insertions(+), 43 deletions(-)

diff --git a/ios/core/MKPolylineAnimator.m b/ios/core/MKPolylineAnimator.m
index 59a91d0..437d50a 100644
--- a/ios/core/MKPolylineAnimator.m
+++ b/ios/core/MKPolylineAnimator.m
@@ -35,8 +35,9 @@ @implementation MKPolylineAnimator {
   NSArray<NSNumber *> *_cumulativeDistances;
   CGFloat _totalLength;
   CGColorSpaceRef _colorSpace;
-  RGBAComponents *_colorCache;
-  NSUInteger _colorCacheCount;
+  // Immutable snapshot read by background draws; rebuilt (never mutated)
+  // on the main thread
+  NSData *_colorCacheData;
 }
 
 - (id)initWithPolyline:(MKPolyline *)polyline {
@@ -61,7 +62,6 @@ - (void)setAnimatedOptions:(PolylineAnimatedOptions *)animatedOptions {
 
 - (void)dealloc {
   [self stopAnimation];
-  free(_colorCache);
   if (_colorSpace) {
     CGColorSpaceRelease(_colorSpace);
     _colorSpace = NULL;
@@ -123,20 +123,25 @@ - (void)resume {
   _displayLink.paused = NO;
 }
 
-- (NSUInteger)indexForDistance:(CGFloat)distance {
+- (NSUInteger)indexForDistance:(CGFloat)distance
+                   inDistances:(NSArray<NSNumber *> *)distances {
+  if (distances.count < 2) {
+    return 0;
+  }
+
   NSUInteger left = 0;
-  NSUInteger right = _cumulativeDistances.count - 1;
+  NSUInteger right = distances.count - 1;
 
   while (left < right) {
     NSUInteger mid = (left + right + 1) / 2;
-    if (_cumulativeDistances[mid].doubleValue <= distance) {
+    if (distances[mid].doubleValue <= distance) {
       left = mid;
     } else {
       right = mid - 1;
     }
   }
 
-  return MIN(left, _cumulativeDistances.count - 2);
+  return MIN(left, distances.count - 2);
 }
 
 - (CGFloat)applyEasing:(CGFloat)t {
@@ -208,44 +213,52 @@ - (void)setStrokeColors:(NSArray<UIColor *> *)strokeColors {
 }
 
 - (void)rebuildColorCache {
-  free(_colorCache);
-  _colorCache = NULL;
-  _colorCacheCount = _strokeColors.count;
-  if (_colorCacheCount == 0) return;
-
-  _colorCache = (RGBAComponents *)malloc(sizeof(RGBAComponents) * _colorCacheCount);
-  for (NSUInteger i = 0; i < _colorCacheCount; i++) {
-    [_strokeColors[i] getRed:&_colorCache[i].r
-                       green:&_colorCache[i].g
-                        blue:&_colorCache[i].b
-                       alpha:&_colorCache[i].a];
+  NSUInteger count = _strokeColors.count;
+  if (count == 0) {
+    _colorCacheData = nil;
+    return;
+  }
+
+  NSMutableData *data =
+      [NSMutableData dataWithLength:sizeof(RGBAComponents) * count];
+  RGBAComponents *cache = (RGBAComponents *)data.mutableBytes;
+  for (NSUInteger i = 0; i < count; i++) {
+    [_strokeColors[i] getRed:&cache[i].r
+                       green:&cache[i].g
+                        blue:&cache[i].b
+                       alpha:&cache[i].a];
   }
+  _colorCacheData = data;
 }
 
 - (void)colorAtGradientPosition:(CGFloat)position rgba:(RGBAComponents *)out {
-  if (_colorCacheCount == 0) {
+  NSData *cacheData = _colorCacheData;
+  const RGBAComponents *cache = (const RGBAComponents *)cacheData.bytes;
+  NSUInteger count = cacheData.length / sizeof(RGBAComponents);
+
+  if (count == 0) {
     CGFloat r, g, b, a;
     [self.strokeColor getRed:&r green:&g blue:&b alpha:&a];
     *out = (RGBAComponents){r, g, b, a};
     return;
   }
-  if (_colorCacheCount == 1) {
-    *out = _colorCache[0];
+  if (count == 1) {
+    *out = cache[0];
     return;
   }
 
   position = MAX(0, MIN(1, position));
-  CGFloat scaledPos = position * (_colorCacheCount - 1);
+  CGFloat scaledPos = position * (count - 1);
   NSUInteger index = (NSUInteger)scaledPos;
   CGFloat t = scaledPos - index;
 
-  if (index >= _colorCacheCount - 1) {
-    *out = _colorCache[_colorCacheCount - 1];
+  if (index >= count - 1) {
+    *out = cache[count - 1];
     return;
   }
 
-  RGBAComponents c1 = _colorCache[index];
-  RGBAComponents c2 = _colorCache[index + 1];
+  RGBAComponents c1 = cache[index];
+  RGBAComponents c2 = cache[index + 1];
   out->r = c1.r + (c2.r - c1.r) * t;
   out->g = c1.g + (c2.g - c1.g) * t;
   out->b = c1.b + (c2.b - c1.b) * t;
@@ -272,13 +285,20 @@ - (void)drawMapRect:(MKMapRect)mapRect
   CGContextSetLineCap(context, self.lineCap);
   CGContextSetLineJoin(context, self.lineJoin);
 
-  NSUInteger segmentCount = _polyline.pointCount - 1;
-  if (segmentCount == 0) {
+  // drawMapRect: runs on MapKit's background render queues while
+  // updatePolyline: swaps these ivars on the main thread; snapshot them so
+  // one frame draws from a consistent pair
+  MKPolyline *polyline = _polyline;
+  NSArray<NSNumber *> *distances = _cumulativeDistances;
+  CGFloat totalLength = _totalLength;
+
+  if (polyline.pointCount < 2) {
     return;
   }
+  NSUInteger segmentCount = polyline.pointCount - 1;
 
   // Snake animation: grow from start, then shrink from start
-  if (_animated && _polyline.pointCount > 1 && _totalLength > 0) {
+  if (_animated && distances.count > 1 && totalLength > 0) {
     CGFloat trailLength = MAX(0.01, MIN(1.0, _animatedOptions.trailLength));
     CGFloat maxProgress = (trailLength < 1.0) ? 1.0 : 2.0;
     CGFloat progress = MIN(_animationProgress, maxProgress);
@@ -287,15 +307,15 @@ - (void)drawMapRect:(MKMapRect)mapRect
     CGFloat headDist, tailDist;
 
     if (trailLength < 1.0) {
-      headDist = easedProgress * _totalLength;
-      tailDist = MAX(0, headDist - _totalLength * trailLength);
+      headDist = easedProgress * totalLength;
+      tailDist = MAX(0, headDist - totalLength * trailLength);
     } else if (easedProgress <= 1.0) {
       tailDist = 0;
-      headDist = easedProgress * _totalLength;
+      headDist = easedProgress * totalLength;
     } else {
       CGFloat shrinkProgress = easedProgress - 1.0;
-      tailDist = shrinkProgress * _totalLength;
-      headDist = _totalLength;
+      tailDist = shrinkProgress * totalLength;
+      headDist = totalLength;
     }
 
     if (headDist <= tailDist) {
@@ -303,19 +323,23 @@ - (void)drawMapRect:(MKMapRect)mapRect
     }
 
     CGFloat visibleLength = headDist - tailDist;
-    NSUInteger startIndex = [self indexForDistance:tailDist];
-    NSUInteger endIndex = [self indexForDistance:headDist];
+    NSUInteger startIndex = [self indexForDistance:tailDist inDistances:distances];
+    NSUInteger endIndex = [self indexForDistance:headDist inDistances:distances];
+
+    // distances may lag behind the polyline (or vice versa) for a frame;
+    // never index past either
+    NSUInteger maxSegment = MIN(segmentCount, distances.count - 1);
 
-    for (NSUInteger i = startIndex; i <= endIndex && i < segmentCount; i++) {
-      CGFloat segStartDist = _cumulativeDistances[i].doubleValue;
-      CGFloat segEndDist = _cumulativeDistances[i + 1].doubleValue;
+    for (NSUInteger i = startIndex; i <= endIndex && i < maxSegment; i++) {
+      CGFloat segStartDist = distances[i].doubleValue;
+      CGFloat segEndDist = distances[i + 1].doubleValue;
 
       if (segEndDist <= tailDist || segStartDist >= headDist) {
         continue;
       }
 
-      CGPoint segStart = [self pointForMapPoint:_polyline.points[i]];
-      CGPoint segEnd = [self pointForMapPoint:_polyline.points[i + 1]];
+      CGPoint segStart = [self pointForMapPoint:polyline.points[i]];
+      CGPoint segEnd = [self pointForMapPoint:polyline.points[i + 1]];
 
       CGPoint drawStart = segStart;
       CGPoint drawEnd = segEnd;
@@ -368,8 +392,8 @@ - (void)drawMapRect:(MKMapRect)mapRect
   // Static gradient rendering
   if (_strokeColors && _strokeColors.count > 1) {
     for (NSUInteger i = 0; i < segmentCount; i++) {
-      CGPoint startPoint = [self pointForMapPoint:_polyline.points[i]];
-      CGPoint endPoint = [self pointForMapPoint:_polyline.points[i + 1]];
+      CGPoint startPoint = [self pointForMapPoint:polyline.points[i]];
+      CGPoint endPoint = [self pointForMapPoint:polyline.points[i + 1]];
 
       CGFloat gradientStart = (CGFloat)i / segmentCount;
       CGFloat gradientEnd = (CGFloat)(i + 1) / segmentCount;

From b01a98d0a4583e4854deb2cf4b6bc61fa517a958 Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Tue, 7 Jul 2026 04:29:51 +0800
Subject: [PATCH 05/17] fix(mapview): low-risk static mode fixes from review

- reset static content on staticKey change (prevents stale/poisoned
  snapshot cache with in-place list recycling)
- re-arm snapshot swap on zero-size capture instead of giving up
- bound snapshot cache by memory; include camera in cache key
- reset recycled wrapper placeholder styling
- web: disable POI clicks, keyboard, and press handlers in staticMode
---
 docs/MAPVIEW.md               |  9 ++++--
 ios/LuggMapView.mm            | 57 ++++++++++++++++++++++++++++++-----
 ios/LuggMapWrapperView.mm     | 10 ++++++
 ios/core/AppleMapProvider.mm  |  6 +++-
 ios/core/GoogleMapProvider.mm |  6 +++-
 src/MapView.web.tsx           | 10 +++---
 6 files changed, 83 insertions(+), 15 deletions(-)

diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index 490e589..c6c5543 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -57,6 +57,8 @@ mounting many live maps is expensive:
   which renders a static bitmap instead of a live GL surface.
 - **iOS (Apple/Google)** - the live map is replaced with a rendered snapshot
   image once tiles finish loading, releasing the map's rendering resources.
+- **Web (Google)** - gestures, POI clicks, keyboard interaction, and press
+  events are disabled; the map itself stays live.
 
 ```tsx
 <Pressable onPress={() => openPlace(place)}>
@@ -87,8 +89,11 @@ Notes:
   Set a `backgroundColor` style on the `MapView` to use your own.
 - Set `staticKey` (e.g. your list item's id) to cache snapshots across
   list recycling on iOS - scrolling back to a row reuses its snapshot
-  instead of rendering a live map again. The key must uniquely identify the
-  map's content, including markers; the cache is evicted on memory pressure.
+  instead of rendering a live map again. The camera and map settings are
+  part of the cache key automatically; the key must uniquely identify the
+  rest of the map's content (e.g. markers). Changing `staticKey` discards
+  the current snapshot and re-renders. The cache is bounded by count and
+  total memory.
 - Alternatively, keeping rows mounted (larger `windowSize` with
   `removeClippedSubviews`) avoids re-rendering entirely at the cost of
   holding every row's snapshot in memory.
diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index 7a87bdb..ea6a55e 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -27,14 +27,14 @@
 using namespace luggmaps::events;
 
 // Static snapshots cached across view recycling, keyed by the user-provided
-// staticKey plus the map settings that affect appearance. Evicted on memory
-// pressure.
+// 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;
 }
@@ -247,9 +247,18 @@ - (nullable NSString *)staticSnapshotCacheKey {
                         ? (NSInteger)self.traitCollection.userInterfaceStyle
                         : -(NSInteger)_theme;
 
-  return [NSString stringWithFormat:@"%@|%d|%@|%d|%ld|%.0fx%.0f", _staticKey,
-                                    (int)_providerType, _mapId, (int)_mapType,
-                                    (long)style, size.width, size.height];
+  // 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];
 }
 
 - (BOOL)showCachedStaticSnapshot {
@@ -301,6 +310,29 @@ - (void)releaseWarmupSlot {
   }
 }
 
+// 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 {
+  [_staticCachedImageView removeFromSuperview];
+  _staticCachedImageView = nil;
+
+  if (_provider) {
+    [self releaseWarmupSlot];
+    [_provider destroy];
+    _provider = nil;
+    _initialized = NO;
+  }
+
+  if (self.window) {
+    [self applyStaticPlaceholderBackground];
+    if (![self showCachedStaticSnapshot]) {
+      [self requestStaticWarmup];
+    }
+  }
+}
+
 - (void)prepareForRecycle {
   [super prepareForRecycle];
 
@@ -382,7 +414,9 @@ - (void)mapProviderDidFinishStaticSnapshot {
 - (void)mapProviderDidCaptureStaticImage:(UIImage *)image {
   NSString *key = [self staticSnapshotCacheKey];
   if (key) {
-    [StaticSnapshotCache() setObject:image forKey:key];
+    NSUInteger cost = (NSUInteger)(image.size.width * image.scale *
+                                   image.size.height * image.scale * 4);
+    [StaticSnapshotCache() setObject:image forKey:key cost:cost];
   }
 }
 
@@ -446,7 +480,11 @@ - (void)updateProps:(Props::Shared const &)props
 
   _providerType = newViewProps.provider;
   _staticMode = newViewProps.staticMode;
-  _staticKey = [NSString stringWithUTF8String:newViewProps.staticKey.c_str()];
+
+  NSString *newStaticKey =
+      [NSString stringWithUTF8String:newViewProps.staticKey.c_str()];
+  BOOL staticKeyChanged = ![newStaticKey isEqualToString:_staticKey];
+  _staticKey = newStaticKey;
 
   NSString *newMapId =
       [NSString stringWithUTF8String:newViewProps.mapId.c_str()];
@@ -525,6 +563,11 @@ - (void)updateProps:(Props::Shared const &)props
   }
 
   [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
diff --git a/ios/LuggMapWrapperView.mm b/ios/LuggMapWrapperView.mm
index 78f2853..f6e3cd0 100644
--- a/ios/LuggMapWrapperView.mm
+++ b/ios/LuggMapWrapperView.mm
@@ -29,6 +29,16 @@ - (instancetype)initWithFrame:(CGRect)frame {
   return self;
 }
 
+- (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;
+}
+
 Class<RCTComponentViewProtocol> LuggMapWrapperViewCls(void) {
   return LuggMapWrapperView.class;
 }
diff --git a/ios/core/AppleMapProvider.mm b/ios/core/AppleMapProvider.mm
index 59c8807..abb2b77 100644
--- a/ios/core/AppleMapProvider.mm
+++ b/ios/core/AppleMapProvider.mm
@@ -276,8 +276,12 @@ - (void)performStaticSwap {
   }
 
   UIImageView *imageView = [_mapView lugg_snapshotImageView];
-  if (!imageView)
+  if (!imageView) {
+    // Zero-size bounds; re-arm so resumeAnimations retries instead of
+    // silently keeping the live map forever
+    _needsStaticSnapshot = YES;
     return;
+  }
 
   _staticSnapshotView = imageView;
   [_wrapperView insertSubview:imageView aboveSubview:_mapView];
diff --git a/ios/core/GoogleMapProvider.mm b/ios/core/GoogleMapProvider.mm
index 21103f1..5552a51 100644
--- a/ios/core/GoogleMapProvider.mm
+++ b/ios/core/GoogleMapProvider.mm
@@ -198,8 +198,12 @@ - (void)performStaticSwap {
   }
 
   UIImageView *imageView = [_mapView lugg_snapshotImageView];
-  if (!imageView)
+  if (!imageView) {
+    // Zero-size bounds; re-arm so resumeAnimations retries instead of
+    // silently keeping the live map forever
+    _needsStaticSnapshot = YES;
     return;
+  }
 
   _staticSnapshotView = imageView;
   [_wrapperView insertSubview:imageView aboveSubview:_mapView];
diff --git a/src/MapView.web.tsx b/src/MapView.web.tsx
index 12b7189..5a01144 100644
--- a/src/MapView.web.tsx
+++ b/src/MapView.web.tsx
@@ -369,7 +369,7 @@ export const MapView = memo(
     }, []);
 
     useEffect(() => {
-      if (!map || !onLongPress) return;
+      if (!map || !onLongPress || staticMode) return;
       const listeners = [
         map.addListener('mousedown', handleMouseDown),
         map.addListener('mouseup', handleMouseUp),
@@ -378,7 +378,7 @@ export const MapView = memo(
         listeners.forEach((l) => google.maps.event.removeListener(l));
         handleMouseUp();
       };
-    }, [map, onLongPress, handleMouseDown, handleMouseUp]);
+    }, [map, onLongPress, staticMode, handleMouseDown, handleMouseUp]);
 
     const handleDragStart = useCallback(() => {
       handleMouseUp();
@@ -491,10 +491,12 @@ export const MapView = memo(
             gestureHandling={gestureHandling}
             colorScheme={colorScheme}
             disableDefaultUI
-            rotateControl={compassEnabled}
+            rotateControl={staticMode ? false : compassEnabled}
+            clickableIcons={!staticMode}
+            keyboardShortcuts={!staticMode}
             isFractionalZoomEnabled
             tilt={pitchEnabled === false ? 0 : undefined}
-            onClick={handleClick}
+            onClick={staticMode ? undefined : handleClick}
             onDragstart={handleDragStart}
             onDragend={handleDragEnd}
             onCameraChanged={handleCameraChanged}

From 4b25e18d2e1cc68ac95fba14b4b6329259f8eb6a Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Tue, 7 Jul 2026 23:53:49 +0800
Subject: [PATCH 06/17] fix(ios): gate static snapshot on full tile render

---
 ios/core/AppleMapProvider.mm  | 18 ++++++++++++++++--
 ios/core/GoogleMapProvider.mm | 22 ++++++++++++++++++++--
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/ios/core/AppleMapProvider.mm b/ios/core/AppleMapProvider.mm
index abb2b77..6e45bd3 100644
--- a/ios/core/AppleMapProvider.mm
+++ b/ios/core/AppleMapProvider.mm
@@ -123,6 +123,7 @@ @implementation AppleMapProvider {
   UIImageView *_staticSnapshotView;
   BOOL _needsStaticSnapshot;
   BOOL _staticSwapScheduled;
+  BOOL _tilesRendered;
   double _minZoom;
   double _maxZoom;
   NSMapTable<id<MKOverlay>, LuggPolylineView *> *_overlayToPolylineMap;
@@ -181,6 +182,7 @@ - (void)initializeMapInView:(UIView *)wrapperView
   if (_mapView)
     return;
 
+  _tilesRendered = NO;
   _mapView = [[LuggAppleMapViewContent alloc] initWithFrame:wrapperView.bounds];
   _mapView.autoresizingMask =
       UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
@@ -252,7 +254,9 @@ - (void)swapMapWithStaticImage {
   if (_staticSnapshotView || _staticSwapScheduled || !_mapView)
     return;
 
-  if (!_mapView.window) {
+  // Re-arm instead of capturing a half-loaded map; the next
+  // didFinishRenderingMap re-triggers the swap
+  if (!_mapView.window || !_tilesRendered) {
     _needsStaticSnapshot = YES;
     return;
   }
@@ -270,7 +274,8 @@ - (void)performStaticSwap {
   if (_staticSnapshotView || !_mapView)
     return;
 
-  if (!_mapView.window) {
+  // Tiles can invalidate between scheduling and this runloop pass
+  if (!_mapView.window || !_tilesRendered) {
     _needsStaticSnapshot = YES;
     return;
   }
@@ -832,8 +837,17 @@ - (void)mapView:(MKMapView *)mapView regionDidChangeAnimated:(BOOL)animated {
                               gesture:wasDragging];
 }
 
+- (void)mapViewWillStartLoadingMap:(MKMapView *)mapView {
+  _tilesRendered = NO;
+}
+
+- (void)mapViewWillStartRenderingMap:(MKMapView *)mapView {
+  _tilesRendered = NO;
+}
+
 - (void)mapViewDidFinishRenderingMap:(MKMapView *)mapView
                        fullyRendered:(BOOL)fullyRendered {
+  _tilesRendered = fullyRendered;
   if (_staticMode && fullyRendered) {
     [self swapMapWithStaticImage];
   }
diff --git a/ios/core/GoogleMapProvider.mm b/ios/core/GoogleMapProvider.mm
index 5552a51..4aced8a 100644
--- a/ios/core/GoogleMapProvider.mm
+++ b/ios/core/GoogleMapProvider.mm
@@ -32,6 +32,7 @@ @implementation GoogleMapProvider {
   UIImageView *_staticSnapshotView;
   BOOL _needsStaticSnapshot;
   BOOL _staticSwapScheduled;
+  BOOL _tilesRendered;
   LuggMapViewTheme _theme;
   UIEdgeInsets _edgeInsets;
   NSMutableArray<LuggMarkerView *> *_pendingMarkerViews;
@@ -111,6 +112,7 @@ - (void)initializeMapInView:(UIView *)wrapperView
   options.camera = camera;
   options.mapID = gmsMapId;
 
+  _tilesRendered = NO;
   _mapView = [[GMSMapView alloc] initWithOptions:options];
   _mapView.autoresizingMask =
       UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
@@ -174,7 +176,9 @@ - (void)swapMapWithStaticImage {
   if (_staticSnapshotView || _staticSwapScheduled || !_mapView)
     return;
 
-  if (!_mapView.window) {
+  // Re-arm instead of capturing a half-loaded map; the next
+  // didFinishTileRendering re-triggers the swap
+  if (!_mapView.window || !_tilesRendered) {
     _needsStaticSnapshot = YES;
     return;
   }
@@ -192,7 +196,8 @@ - (void)performStaticSwap {
   if (_staticSnapshotView || !_mapView)
     return;
 
-  if (!_mapView.window) {
+  // Tiles can invalidate between scheduling and this runloop pass
+  if (!_mapView.window || !_tilesRendered) {
     _needsStaticSnapshot = YES;
     return;
   }
@@ -374,7 +379,20 @@ - (void)stopEdgeInsetsAnimation {
 
 #pragma mark - GMSMapViewDelegate
 
+- (void)mapViewDidStartTileRendering:(GMSMapView *)mapView {
+  _tilesRendered = NO;
+}
+
+- (void)mapViewDidFinishTileRendering:(GMSMapView *)mapView {
+  _tilesRendered = YES;
+  if (_staticMode && _needsStaticSnapshot) {
+    [self swapMapWithStaticImage];
+  }
+}
+
 - (void)mapViewSnapshotReady:(GMSMapView *)mapView {
+  // Stable per the SDK: tiles loaded, labels and overlays rendered
+  _tilesRendered = YES;
   if (_staticMode) {
     [self swapMapWithStaticImage];
   }

From a20653ec60c8dc69ba260511edb442010e2b9a4b Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Tue, 7 Jul 2026 23:58:33 +0800
Subject: [PATCH 07/17] fix(polyline): render animated polylines as static on
 static maps

---
 android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt | 5 +++--
 docs/MAPVIEW.md                                              | 2 ++
 ios/core/AppleMapProvider.mm                                 | 5 +++--
 ios/core/GoogleMapProvider.mm                                | 5 +++--
 4 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt b/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
index 9f11994..25fc953 100644
--- a/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
+++ b/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
@@ -821,7 +821,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()
     }
   }
@@ -850,7 +850,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()
     }
 
diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index c6c5543..24f46f9 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -83,6 +83,8 @@ Notes:
   and prop updates after the snapshot are ignored on iOS.
 - For taps, wrap the map in a `Pressable` with `pointerEvents="none"` on the
   map container (as above) instead of relying on `onPress`.
+- `animated` polylines render as complete static polylines, so the snapshot
+  never freezes a mid-animation frame.
 - On iOS, static map rendering is paced to never compete with scroll
   gestures, so rows fill in progressively while scrolling stays smooth.
 - While a static map loads, a theme-aware placeholder background is shown.
diff --git a/ios/core/AppleMapProvider.mm b/ios/core/AppleMapProvider.mm
index 6e45bd3..70c2e71 100644
--- a/ios/core/AppleMapProvider.mm
+++ b/ios/core/AppleMapProvider.mm
@@ -923,7 +923,8 @@ - (MKOverlayRenderer *)mapView:(MKMapView *)mapView
         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;
     }
@@ -1452,7 +1453,7 @@ - (void)syncPolylineView:(LuggPolylineView *)polylineView {
     renderer.strokeColors =
         polylineView.strokeColors.count > 1 ? polylineView.strokeColors : nil;
     renderer.animatedOptions = polylineView.animatedOptions;
-    renderer.animated = polylineView.animated;
+    renderer.animated = polylineView.animated && !_staticMode;
     return;
   }
 
diff --git a/ios/core/GoogleMapProvider.mm b/ios/core/GoogleMapProvider.mm
index 4aced8a..cdc46a5 100644
--- a/ios/core/GoogleMapProvider.mm
+++ b/ios/core/GoogleMapProvider.mm
@@ -835,7 +835,7 @@ - (void)syncPolylineView:(LuggPolylineView *)polylineView {
     animator.coordinates = polylineView.coordinates;
     animator.strokeColors = polylineView.strokeColors;
     animator.animatedOptions = polylineView.animatedOptions;
-    animator.animated = polylineView.animated;
+    animator.animated = polylineView.animated && !_staticMode;
     [animator update];
   }
 }
@@ -865,7 +865,8 @@ - (void)addPolylineViewToMap:(LuggPolylineView *)polylineView {
   animator.coordinates = polylineView.coordinates;
   animator.strokeColors = polylineView.strokeColors;
   animator.animatedOptions = polylineView.animatedOptions;
-  animator.animated = polylineView.animated;
+  // Static maps snapshot an arbitrary frame; render the full polyline
+  animator.animated = polylineView.animated && !_staticMode;
   [animator update];
 
   [_polylineAnimators setObject:animator forKey:polylineView];

From 83f7dc35d4f693c52941fb042c2998322fca058a Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 00:11:41 +0800
Subject: [PATCH 08/17] fix(android): render lite mode static maps (no mapId,
 honor child requestLayout)

---
 .../java/com/luggmaps/LuggMapWrapperView.kt   | 22 +++++++++++++++++--
 .../com/luggmaps/core/GoogleMapProvider.kt    |  9 +++++++-
 docs/MAPVIEW.md                               |  3 ++-
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/android/src/main/java/com/luggmaps/LuggMapWrapperView.kt b/android/src/main/java/com/luggmaps/LuggMapWrapperView.kt
index 8139e44..b8064a0 100644
--- a/android/src/main/java/com/luggmaps/LuggMapWrapperView.kt
+++ b/android/src/main/java/com/luggmaps/LuggMapWrapperView.kt
@@ -10,11 +10,26 @@ 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
+
+  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 +38,11 @@ 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)
+  }
+
+  private fun layoutChild(w: Int, h: Int) {
+    if (w <= 0 || h <= 0) return
     getChildAt(0)?.let {
       it.measure(
         MeasureSpec.makeMeasureSpec(w, MeasureSpec.EXACTLY),
diff --git a/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt b/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
index 25fc953..368d944 100644
--- a/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
+++ b/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
@@ -140,11 +140,15 @@ 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).liteMode(staticMode)
+    // Lite mode doesn't support map IDs (cloud-based styling); setting one
+    // makes the static map render blank
+    val options = GoogleMapOptions().liteMode(staticMode)
+    if (!staticMode) options.mapId(mapId)
     mapView = MapView(context, options).also { view ->
       view.onCreate(null)
       view.onResume()
@@ -201,6 +205,9 @@ class GoogleMapProvider(private val context: Context) :
     if (staticMode) {
       // Lite mode shows an "open in Google Maps" toolbar on tap by default
       map.uiSettings.isMapToolbarEnabled = false
+      // The projection is only valid once the lite map has rendered, and no
+      // camera events fire afterwards to correct live marker positions
+      map.setOnMapLoadedCallback { positionLiveMarkers() }
     }
 
     val position = LatLng(initialLatitude, initialLongitude)
diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index 24f46f9..8ae2148 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -54,7 +54,8 @@ Set `staticMode` to render a non-interactive map optimized for list views, where
 mounting many live maps is expensive:
 
 - **Android (Google)** - uses [lite mode](https://developers.google.com/maps/documentation/android-sdk/lite),
-  which renders a static bitmap instead of a live GL surface.
+  which renders a static bitmap instead of a live GL surface. Lite mode does
+  not support cloud-based styling, so `mapId` is ignored on static maps.
 - **iOS (Apple/Google)** - the live map is replaced with a rendered snapshot
   image once tiles finish loading, releasing the map's rendering resources.
 - **Web (Google)** - gestures, POI clicks, keyboard interaction, and press

From 483c7f37acded77bae3c801365c640ce29fbcddd Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 00:31:51 +0800
Subject: [PATCH 09/17] perf(ios): destroy off-window static maps mid-warmup,
 cap warmup concurrency

---
 ios/LuggMapView.mm                  | 13 +++++++++++++
 ios/core/LuggStaticMapWarmupQueue.m |  7 ++++---
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index ea6a55e..287ebc3 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -57,6 +57,7 @@ @implementation LuggMapView {
   BOOL _staticMode;
   NSString *_staticKey;
   UIImageView *_staticCachedImageView;
+  BOOL _staticSnapshotDone;
   BOOL _waitingForWarmupSlot;
   BOOL _holdingWarmupSlot;
   BOOL _userLocationEnabled;
@@ -206,6 +207,15 @@ - (void)didMoveToWindow {
       [[LuggStaticMapWarmupQueue sharedQueue] cancelOwner:self];
       _waitingForWarmupSlot = NO;
     }
+    // A static map mid-warmup holds an expensive live map view. Destroy it
+    // off-window and re-warm on return instead of letting paused maps pile
+    // up across screen switches and all resume at once
+    if (_staticMode && _provider && !_staticSnapshotDone) {
+      [self releaseWarmupSlot];
+      [_provider destroy];
+      _provider = nil;
+      _initialized = NO;
+    }
     [_provider pauseAnimations];
   }
 }
@@ -317,6 +327,7 @@ - (void)releaseWarmupSlot {
 - (void)resetStaticContent {
   [_staticCachedImageView removeFromSuperview];
   _staticCachedImageView = nil;
+  _staticSnapshotDone = NO;
 
   if (_provider) {
     [self releaseWarmupSlot];
@@ -342,6 +353,7 @@ - (void)prepareForRecycle {
 
   [_staticCachedImageView removeFromSuperview];
   _staticCachedImageView = nil;
+  _staticSnapshotDone = NO;
 
   [_provider destroy];
   _provider = nil;
@@ -408,6 +420,7 @@ - (void)mapProviderDidReady {
 }
 
 - (void)mapProviderDidFinishStaticSnapshot {
+  _staticSnapshotDone = YES;
   [self releaseWarmupSlot];
 }
 
diff --git a/ios/core/LuggStaticMapWarmupQueue.m b/ios/core/LuggStaticMapWarmupQueue.m
index 50dbafd..83f7c7e 100644
--- a/ios/core/LuggStaticMapWarmupQueue.m
+++ b/ios/core/LuggStaticMapWarmupQueue.m
@@ -1,8 +1,9 @@
 #import "LuggStaticMapWarmupQueue.h"
 
-// No concurrency cap - warmups are paced by the runloop instead (one grant
-// per pass, outside scroll tracking)
-static const NSUInteger kMaxConcurrentWarmups = NSUIntegerMax;
+// Bounds how many live warmup maps exist at once - peak memory scales with
+// this. Grants are additionally paced by the runloop (one per pass, outside
+// scroll tracking)
+static const NSUInteger kMaxConcurrentWarmups = 3;
 // Slot is force-released if a map never finishes rendering (e.g. offline)
 // so it can't starve the queue. The live map is left in place.
 static const int64_t kWarmupTimeoutSeconds = 10;

From dfacf208f4cd87726d5a32b1c3481eee7bf852b7 Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 01:27:46 +0800
Subject: [PATCH 10/17] perf(ios): render apple static maps async with
 MKMapSnapshotter

No live MKMapView is created - the base map renders off the main thread
and keeps loading while scrolling, like Android lite mode. Markers are
live views positioned via mercator projection; shapes are drawn onto a
CoreGraphics overlay. Removes the old snapshot-swap path from
AppleMapProvider (now Google-only via the warmup queue).
---
 docs/MAPVIEW.md                     |  19 +-
 ios/LuggMapView.mm                  |  40 +-
 ios/LuggMapWrapperView.h            |   5 +
 ios/LuggMapWrapperView.mm           |   8 +
 ios/core/AppleMapProvider.h         |   8 +
 ios/core/AppleMapProvider.mm        | 133 +----
 ios/core/AppleStaticMapProvider.h   |  26 +
 ios/core/AppleStaticMapProvider.mm  | 820 ++++++++++++++++++++++++++++
 ios/core/LuggStaticMapWarmupQueue.h |   7 +-
 ios/extensions/MKMapView+Zoom.h     |  13 +
 ios/extensions/MKMapView+Zoom.m     |  32 +-
 11 files changed, 973 insertions(+), 138 deletions(-)
 create mode 100644 ios/core/AppleStaticMapProvider.h
 create mode 100644 ios/core/AppleStaticMapProvider.mm

diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index 8ae2148..26b53cb 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -56,8 +56,16 @@ mounting many live maps is expensive:
 - **Android (Google)** - uses [lite mode](https://developers.google.com/maps/documentation/android-sdk/lite),
   which renders a static bitmap instead of a live GL surface. Lite mode does
   not support cloud-based styling, so `mapId` is ignored on static maps.
-- **iOS (Apple/Google)** - the live map is replaced with a rendered snapshot
-  image once tiles finish loading, releasing the map's rendering resources.
+- **iOS (Apple)** - rendered with `MKMapSnapshotter`, which loads the base
+  map entirely off the main thread (no live map view is ever created), so
+  static maps keep loading while scrolling. Markers stay live views
+  positioned over the snapshot; polylines, polygons, circles, and ground
+  overlays are drawn onto it. Tile overlays are not supported.
+- **iOS (Google)** - the SDK has no async snapshotter, so a live map is
+  created briefly and replaced with a rendered snapshot image once tiles
+  finish loading, releasing the map's rendering resources. Rendering is
+  paced to never compete with scroll gestures, so rows fill in only
+  between scrolls.
 - **Web (Google)** - gestures, POI clicks, keyboard interaction, and press
   events are disabled; the map itself stays live.
 
@@ -86,13 +94,14 @@ Notes:
   map container (as above) instead of relying on `onPress`.
 - `animated` polylines render as complete static polylines, so the snapshot
   never freezes a mid-animation frame.
-- On iOS, static map rendering is paced to never compete with scroll
-  gestures, so rows fill in progressively while scrolling stays smooth.
+- On iOS Apple Maps, markers are live views over the snapshot - marker
+  content that loads asynchronously (e.g. remote images) appears when
+  ready, and marker prop updates still apply.
 - While a static map loads, a theme-aware placeholder background is shown.
   Set a `backgroundColor` style on the `MapView` to use your own.
 - Set `staticKey` (e.g. your list item's id) to cache snapshots across
   list recycling on iOS - scrolling back to a row reuses its snapshot
-  instead of rendering a live map again. The camera and map settings are
+  instead of rendering the map again. The camera and map settings are
   part of the cache key automatically; the key must uniquely identify the
   rest of the map's content (e.g. markers). Changing `staticKey` discards
   the current snapshot and re-renders. The cache is bounded by count and
diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index 287ebc3..a36b1b1 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -7,6 +7,7 @@
 #import "LuggPolylineView.h"
 #import "LuggTileOverlayView.h"
 #import "core/AppleMapProvider.h"
+#import "core/AppleStaticMapProvider.h"
 #import "core/GoogleMapProvider.h"
 #import "core/LuggStaticMapWarmupQueue.h"
 #import "core/MapProviderDelegate.h"
@@ -193,10 +194,7 @@ - (void)didMoveToWindow {
   if (self.window) {
     if (!_provider && _mapWrapperView) {
       if (_staticMode) {
-        [self applyStaticPlaceholderBackground];
-        if (![self showCachedStaticSnapshot]) {
-          [self requestStaticWarmup];
-        }
+        [self startStaticContent];
       } else {
         [self initializeProvider];
       }
@@ -295,6 +293,24 @@ - (BOOL)showCachedStaticSnapshot {
   return YES;
 }
 
+- (void)startStaticContent {
+  [self applyStaticPlaceholderBackground];
+
+  // Apple static maps render through MKMapSnapshotter - fully async like
+  // Android's lite mode - so they start immediately (even mid-scroll) with
+  // no warmup pacing. The provider reuses a cached base image itself.
+  if (_providerType == LuggMapViewProvider::Apple) {
+    [self initializeProvider];
+    return;
+  }
+
+  // Google has no snapshotter API; a live map warms up briefly, paced by
+  // the warmup queue so it never competes with scroll gestures
+  if (![self showCachedStaticSnapshot]) {
+    [self requestStaticWarmup];
+  }
+}
+
 - (void)requestStaticWarmup {
   if (_waitingForWarmupSlot || _holdingWarmupSlot)
     return;
@@ -337,10 +353,7 @@ - (void)resetStaticContent {
   }
 
   if (self.window) {
-    [self applyStaticPlaceholderBackground];
-    if (![self showCachedStaticSnapshot]) {
-      [self requestStaticWarmup];
-    }
+    [self startStaticContent];
   }
 }
 
@@ -371,7 +384,16 @@ - (void)initializeProvider {
       *std::static_pointer_cast<LuggMapViewProps const>(_props);
 
   if (_providerType == LuggMapViewProvider::Apple) {
-    _provider = [[AppleMapProvider alloc] init];
+    if (_staticMode) {
+      AppleStaticMapProvider *apple = [[AppleStaticMapProvider alloc] init];
+      NSString *cacheKey = [self staticSnapshotCacheKey];
+      if (cacheKey) {
+        apple.cachedBaseImage = [StaticSnapshotCache() objectForKey:cacheKey];
+      }
+      _provider = apple;
+    } else {
+      _provider = [[AppleMapProvider alloc] init];
+    }
   } else {
     GoogleMapProvider *google = [[GoogleMapProvider alloc] init];
     google.mapId = _mapId;
diff --git a/ios/LuggMapWrapperView.h b/ios/LuggMapWrapperView.h
index a4ffc41..bf8e9c3 100644
--- a/ios/LuggMapWrapperView.h
+++ b/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
diff --git a/ios/LuggMapWrapperView.mm b/ios/LuggMapWrapperView.mm
index f6e3cd0..d31483b 100644
--- a/ios/LuggMapWrapperView.mm
+++ b/ios/LuggMapWrapperView.mm
@@ -29,6 +29,13 @@ - (instancetype)initWithFrame:(CGRect)frame {
   return self;
 }
 
+- (void)layoutSubviews {
+  [super layoutSubviews];
+  if (self.layoutHandler) {
+    self.layoutHandler();
+  }
+}
+
 - (void)prepareForRecycle {
   [super prepareForRecycle];
 
@@ -37,6 +44,7 @@ - (void)prepareForRecycle {
   // leak into the next map that reuses this recycled view
   self.backgroundColor = nil;
   self.overrideUserInterfaceStyle = UIUserInterfaceStyleUnspecified;
+  self.layoutHandler = nil;
 }
 
 Class<RCTComponentViewProtocol> LuggMapWrapperViewCls(void) {
diff --git a/ios/core/AppleMapProvider.h b/ios/core/AppleMapProvider.h
index 48fd662..b483d12 100644
--- a/ios/core/AppleMapProvider.h
+++ b/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
 
diff --git a/ios/core/AppleMapProvider.mm b/ios/core/AppleMapProvider.mm
index 70c2e71..569e6fd 100644
--- a/ios/core/AppleMapProvider.mm
+++ b/ios/core/AppleMapProvider.mm
@@ -13,7 +13,6 @@
 #import "../LuggPolylineView.h"
 #import "../LuggTileOverlayView.h"
 #import "../extensions/MKMapView+Zoom.h"
-#import "../extensions/UIView+Snapshot.h"
 #import "LuggAnnotationView.h"
 #import "MKPolylineAnimator.h"
 
@@ -120,10 +119,6 @@ @implementation AppleMapProvider {
   LuggAppleMapViewContent *_mapView;
   BOOL _isMapReady;
   BOOL _isDragging;
-  UIImageView *_staticSnapshotView;
-  BOOL _needsStaticSnapshot;
-  BOOL _staticSwapScheduled;
-  BOOL _tilesRendered;
   double _minZoom;
   double _maxZoom;
   NSMapTable<id<MKOverlay>, LuggPolylineView *> *_overlayToPolylineMap;
@@ -182,7 +177,6 @@ - (void)initializeMapInView:(UIView *)wrapperView
   if (_mapView)
     return;
 
-  _tilesRendered = NO;
   _mapView = [[LuggAppleMapViewContent alloc] initWithFrame:wrapperView.bounds];
   _mapView.autoresizingMask =
       UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
@@ -223,9 +217,6 @@ - (void)initializeMapInView:(UIView *)wrapperView
 }
 
 - (void)destroy {
-  [_staticSnapshotView removeFromSuperview];
-  _staticSnapshotView = nil;
-  _needsStaticSnapshot = NO;
   [self destroyMapView];
   _isMapReady = NO;
 }
@@ -246,58 +237,6 @@ - (void)destroyMapView {
   _mapView = nil;
 }
 
-// Static mode: once tiles are fully rendered, swap the live map with a
-// snapshot image and release the map view. The snapshot render and map
-// teardown are expensive, so they run outside scroll tracking; the live
-// map keeps displaying until then.
-- (void)swapMapWithStaticImage {
-  if (_staticSnapshotView || _staticSwapScheduled || !_mapView)
-    return;
-
-  // Re-arm instead of capturing a half-loaded map; the next
-  // didFinishRenderingMap re-triggers the swap
-  if (!_mapView.window || !_tilesRendered) {
-    _needsStaticSnapshot = YES;
-    return;
-  }
-  _needsStaticSnapshot = NO;
-
-  _staticSwapScheduled = YES;
-  [[NSRunLoop mainRunLoop] performInModes:@[ NSDefaultRunLoopMode ]
-                                    block:^{
-                                      self->_staticSwapScheduled = NO;
-                                      [self performStaticSwap];
-                                    }];
-}
-
-- (void)performStaticSwap {
-  if (_staticSnapshotView || !_mapView)
-    return;
-
-  // Tiles can invalidate between scheduling and this runloop pass
-  if (!_mapView.window || !_tilesRendered) {
-    _needsStaticSnapshot = YES;
-    return;
-  }
-
-  UIImageView *imageView = [_mapView lugg_snapshotImageView];
-  if (!imageView) {
-    // Zero-size bounds; re-arm so resumeAnimations retries instead of
-    // silently keeping the live map forever
-    _needsStaticSnapshot = YES;
-    return;
-  }
-
-  _staticSnapshotView = imageView;
-  [_wrapperView insertSubview:imageView aboveSubview:_mapView];
-
-  [self pauseAnimations];
-  [self destroyMapView];
-
-  [_delegate mapProviderDidCaptureStaticImage:imageView.image];
-  [_delegate mapProviderDidFinishStaticSnapshot];
-}
-
 #pragma mark - Props
 
 - (void)setZoomEnabled:(BOOL)enabled {
@@ -413,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 {
@@ -470,26 +412,25 @@ - (void)setPoiFilterCategories:(NSArray<NSString *> *)categories {
   [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:
@@ -837,22 +778,6 @@ - (void)mapView:(MKMapView *)mapView regionDidChangeAnimated:(BOOL)animated {
                               gesture:wasDragging];
 }
 
-- (void)mapViewWillStartLoadingMap:(MKMapView *)mapView {
-  _tilesRendered = NO;
-}
-
-- (void)mapViewWillStartRenderingMap:(MKMapView *)mapView {
-  _tilesRendered = NO;
-}
-
-- (void)mapViewDidFinishRenderingMap:(MKMapView *)mapView
-                       fullyRendered:(BOOL)fullyRendered {
-  _tilesRendered = fullyRendered;
-  if (_staticMode && fullyRendered) {
-    [self swapMapWithStaticImage];
-  }
-}
-
 - (MKAnnotationView *)mapView:(MKMapView *)mapView
             viewForAnnotation:(id<MKAnnotation>)annotation {
   if (![annotation isKindOfClass:[AppleMarkerAnnotation class]]) {
@@ -1840,10 +1765,6 @@ - (void)pauseAnimations {
 }
 
 - (void)resumeAnimations {
-  if (_needsStaticSnapshot) {
-    [self swapMapWithStaticImage];
-    return;
-  }
   for (LuggPolylineView *polylineView in _overlayToPolylineMap
            .objectEnumerator) {
     MKPolylineAnimator *renderer = (MKPolylineAnimator *)polylineView.renderer;
diff --git a/ios/core/AppleStaticMapProvider.h b/ios/core/AppleStaticMapProvider.h
new file mode 100644
index 0000000..e3b5f8d
--- /dev/null
+++ b/ios/core/AppleStaticMapProvider.h
@@ -0,0 +1,26 @@
+#import "MapProviderDelegate.h"
+#import <MapKit/MapKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Static (non-interactive) Apple map rendered with MKMapSnapshotter -
+ * the iOS equivalent of Android's lite mode. 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.
+ *
+ * Markers are live views positioned over the snapshot via a mercator
+ * projection (mirroring Android's live markers on lite maps), so
+ * async marker content (e.g. remote images) appears when it loads.
+ * Polylines, polygons, circles and ground overlays are drawn into a
+ * single CoreGraphics overlay view. Tile overlays are not supported.
+ */
+@interface AppleStaticMapProvider : NSObject <MapProvider>
+
+/// Previously captured base map for the same cache key; when set, the
+/// snapshotter is skipped and the image is shown immediately.
+@property(nonatomic, strong, nullable) UIImage *cachedBaseImage;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/core/AppleStaticMapProvider.mm b/ios/core/AppleStaticMapProvider.mm
new file mode 100644
index 0000000..0336786
--- /dev/null
+++ b/ios/core/AppleStaticMapProvider.mm
@@ -0,0 +1,820 @@
+#import "AppleStaticMapProvider.h"
+
+using facebook::react::LuggMapViewInsetAdjustment;
+using facebook::react::LuggMapViewMapType;
+using facebook::react::LuggMapViewPoiFilterMode;
+using facebook::react::LuggMapViewTheme;
+
+#import "../LuggCircleView.h"
+#import "../LuggGroundOverlayView.h"
+#import "../LuggMapWrapperView.h"
+#import "../LuggMarkerView.h"
+#import "../LuggPolygonView.h"
+#import "../LuggPolylineView.h"
+#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};
+
+#pragma mark - Projection
+
+// 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 below 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;
+}
+
+static CGPoint LuggStaticPointForCoordinate(MKMapRect mapRect, CGSize size,
+                                            CLLocationCoordinate2D coordinate) {
+  MKMapPoint point = MKMapPointForCoordinate(coordinate);
+  return CGPointMake(
+      (point.x - mapRect.origin.x) / mapRect.size.width * size.width,
+      (point.y - mapRect.origin.y) / mapRect.size.height * size.height);
+}
+
+#pragma mark - Shape overlay
+
+// Draws polylines, polygons, circles and ground overlays over the base
+// snapshot with CoreGraphics; MKMapSnapshotter renders map tiles only
+@interface LuggStaticShapeOverlayView : UIView
+@property(nonatomic, assign) MKMapRect mapRect;
+@property(nonatomic, assign) BOOL projectionReady;
+@property(nonatomic, strong) NSMutableArray<LuggPolylineView *> *polylineViews;
+@property(nonatomic, strong) NSMutableArray<LuggPolygonView *> *polygonViews;
+@property(nonatomic, strong) NSMutableArray<LuggCircleView *> *circleViews;
+@property(nonatomic, strong)
+    NSMutableArray<LuggGroundOverlayView *> *groundOverlayViews;
+@property(nonatomic, strong)
+    NSMapTable<LuggGroundOverlayView *, UIImage *> *groundOverlayImages;
+@end
+
+@implementation LuggStaticShapeOverlayView
+
+- (instancetype)initWithFrame:(CGRect)frame {
+  if (self = [super initWithFrame:frame]) {
+    self.opaque = NO;
+    self.backgroundColor = UIColor.clearColor;
+    self.userInteractionEnabled = NO;
+    self.contentMode = UIViewContentModeRedraw;
+    _polylineViews = [NSMutableArray array];
+    _polygonViews = [NSMutableArray array];
+    _circleViews = [NSMutableArray array];
+    _groundOverlayViews = [NSMutableArray array];
+    _groundOverlayImages = [NSMapTable weakToStrongObjectsMapTable];
+  }
+  return self;
+}
+
+static NSInteger shapeZIndex(UIView *shape) {
+  if ([shape isKindOfClass:[LuggPolylineView class]])
+    return ((LuggPolylineView *)shape).zIndex;
+  if ([shape isKindOfClass:[LuggPolygonView class]])
+    return ((LuggPolygonView *)shape).zIndex;
+  if ([shape isKindOfClass:[LuggCircleView class]])
+    return ((LuggCircleView *)shape).zIndex;
+  if ([shape isKindOfClass:[LuggGroundOverlayView class]])
+    return ((LuggGroundOverlayView *)shape).zIndex;
+  return 0;
+}
+
+- (CGPoint)pointForCoordinate:(CLLocationCoordinate2D)coordinate {
+  return LuggStaticPointForCoordinate(_mapRect, self.bounds.size, coordinate);
+}
+
+- (void)addPath:(CGContextRef)context
+           ring:(NSArray<CLLocation *> *)coordinates {
+  for (NSUInteger i = 0; i < coordinates.count; i++) {
+    CGPoint point = [self pointForCoordinate:coordinates[i].coordinate];
+    if (i == 0) {
+      CGContextMoveToPoint(context, point.x, point.y);
+    } else {
+      CGContextAddLineToPoint(context, point.x, point.y);
+    }
+  }
+}
+
+- (void)drawPolyline:(LuggPolylineView *)polylineView
+           inContext:(CGContextRef)context {
+  NSArray<CLLocation *> *coordinates = polylineView.coordinates;
+  UIColor *color = polylineView.strokeColors.firstObject;
+  if (coordinates.count < 2 || !color || polylineView.strokeWidth <= 0)
+    return;
+
+  CGContextSaveGState(context);
+  [self addPath:context ring:coordinates];
+  CGContextSetLineWidth(context, polylineView.strokeWidth);
+  CGContextSetLineCap(context, kCGLineCapRound);
+  CGContextSetLineJoin(context, kCGLineJoinRound);
+  CGContextSetStrokeColorWithColor(context, color.CGColor);
+  CGContextStrokePath(context);
+  CGContextRestoreGState(context);
+}
+
+- (void)drawPolygon:(LuggPolygonView *)polygonView
+          inContext:(CGContextRef)context {
+  NSArray<CLLocation *> *coordinates = polygonView.coordinates;
+  if (coordinates.count < 3)
+    return;
+
+  CGContextSaveGState(context);
+
+  if (polygonView.fillColor) {
+    [self addPath:context ring:coordinates];
+    CGContextClosePath(context);
+    for (NSArray<CLLocation *> *hole in polygonView.holes) {
+      [self addPath:context ring:hole];
+      CGContextClosePath(context);
+    }
+    CGContextSetFillColorWithColor(context, polygonView.fillColor.CGColor);
+    CGContextEOFillPath(context);
+  }
+
+  if (polygonView.strokeColor && polygonView.strokeWidth > 0) {
+    [self addPath:context ring:coordinates];
+    CGContextClosePath(context);
+    for (NSArray<CLLocation *> *hole in polygonView.holes) {
+      [self addPath:context ring:hole];
+      CGContextClosePath(context);
+    }
+    CGContextSetLineWidth(context, polygonView.strokeWidth);
+    CGContextSetLineJoin(context, kCGLineJoinRound);
+    CGContextSetStrokeColorWithColor(context, polygonView.strokeColor.CGColor);
+    CGContextStrokePath(context);
+  }
+
+  CGContextRestoreGState(context);
+}
+
+- (void)drawCircle:(LuggCircleView *)circleView
+         inContext:(CGContextRef)context {
+  if (circleView.radius <= 0)
+    return;
+
+  CGPoint center = [self pointForCoordinate:circleView.center];
+  double pointsPerMapPoint = self.bounds.size.width / _mapRect.size.width;
+  double radius = circleView.radius *
+                  MKMapPointsPerMeterAtLatitude(circleView.center.latitude) *
+                  pointsPerMapPoint;
+  CGRect ellipse =
+      CGRectMake(center.x - radius, center.y - radius, radius * 2, radius * 2);
+
+  CGContextSaveGState(context);
+  if (circleView.fillColor) {
+    CGContextSetFillColorWithColor(context, circleView.fillColor.CGColor);
+    CGContextFillEllipseInRect(context, ellipse);
+  }
+  if (circleView.strokeColor && circleView.strokeWidth > 0) {
+    CGContextSetLineWidth(context, circleView.strokeWidth);
+    CGContextSetStrokeColorWithColor(context, circleView.strokeColor.CGColor);
+    CGContextStrokeEllipseInRect(context, ellipse);
+  }
+  CGContextRestoreGState(context);
+}
+
+- (void)drawGroundOverlay:(LuggGroundOverlayView *)groundOverlayView {
+  UIImage *image = [_groundOverlayImages objectForKey:groundOverlayView];
+  if (!image)
+    return;
+
+  CGPoint topLeft =
+      [self pointForCoordinate:CLLocationCoordinate2DMake(
+                                   groundOverlayView.northeast.latitude,
+                                   groundOverlayView.southwest.longitude)];
+  CGPoint bottomRight =
+      [self pointForCoordinate:CLLocationCoordinate2DMake(
+                                   groundOverlayView.southwest.latitude,
+                                   groundOverlayView.northeast.longitude)];
+  CGRect rect = CGRectMake(topLeft.x, topLeft.y, bottomRight.x - topLeft.x,
+                           bottomRight.y - topLeft.y);
+  [image drawInRect:rect
+          blendMode:kCGBlendModeNormal
+              alpha:groundOverlayView.opacity];
+}
+
+- (void)drawRect:(CGRect)rect {
+  if (!_projectionReady)
+    return;
+
+  CGContextRef context = UIGraphicsGetCurrentContext();
+  if (!context)
+    return;
+
+  NSMutableArray<UIView *> *shapes = [NSMutableArray array];
+  [shapes addObjectsFromArray:_groundOverlayViews];
+  [shapes addObjectsFromArray:_polygonViews];
+  [shapes addObjectsFromArray:_circleViews];
+  [shapes addObjectsFromArray:_polylineViews];
+  NSArray<UIView *> *ordered =
+      [shapes sortedArrayWithOptions:NSSortStable
+                     usingComparator:^NSComparisonResult(UIView *a, UIView *b) {
+                       NSInteger za = shapeZIndex(a), zb = shapeZIndex(b);
+                       if (za < zb)
+                         return NSOrderedAscending;
+                       if (za > zb)
+                         return NSOrderedDescending;
+                       return NSOrderedSame;
+                     }];
+
+  for (UIView *shape in ordered) {
+    if ([shape isKindOfClass:[LuggGroundOverlayView class]]) {
+      [self drawGroundOverlay:(LuggGroundOverlayView *)shape];
+    } else if ([shape isKindOfClass:[LuggPolygonView class]]) {
+      [self drawPolygon:(LuggPolygonView *)shape inContext:context];
+    } else if ([shape isKindOfClass:[LuggCircleView class]]) {
+      [self drawCircle:(LuggCircleView *)shape inContext:context];
+    } else if ([shape isKindOfClass:[LuggPolylineView class]]) {
+      [self drawPolyline:(LuggPolylineView *)shape inContext:context];
+    }
+  }
+}
+
+@end
+
+#pragma mark - Provider
+
+@interface AppleStaticMapProvider () <
+    LuggMarkerViewDelegate, LuggPolylineViewDelegate, LuggPolygonViewDelegate,
+    LuggCircleViewDelegate, LuggGroundOverlayViewDelegate>
+@end
+
+@implementation AppleStaticMapProvider {
+  UIView *_wrapperView;
+  CLLocationCoordinate2D _coordinate;
+  double _zoom;
+  BOOL _isMapReady;
+
+  MKMapRect _mapRect;
+  CGSize _projectedSize;
+  BOOL _projectionReady;
+
+  MKMapSnapshotter *_snapshotter;
+  UIImageView *_baseImageView;
+  BOOL _snapshotDone;
+
+  LuggStaticShapeOverlayView *_shapeOverlayView;
+  NSMutableArray<LuggMarkerView *> *_markerViews;
+  NSMapTable<LuggMarkerView *, MKAnnotationView *> *_defaultMarkerOverlays;
+
+  LuggMapViewMapType _mapType;
+  LuggMapViewTheme _theme;
+  BOOL _poiEnabled;
+  LuggMapViewPoiFilterMode _poiFilterMode;
+  NSArray<NSString *> *_poiFilterCategories;
+}
+
+@synthesize delegate = _delegate;
+@synthesize staticMode = _staticMode;
+
+- (instancetype)init {
+  if (self = [super init]) {
+    _markerViews = [NSMutableArray array];
+    _defaultMarkerOverlays = [NSMapTable weakToStrongObjectsMapTable];
+    _mapType = LuggMapViewMapType::Standard;
+    _theme = LuggMapViewTheme::System;
+    _poiEnabled = YES;
+    _poiFilterMode = LuggMapViewPoiFilterMode::Including;
+    _poiFilterCategories = @[];
+  }
+  return self;
+}
+
+- (BOOL)isMapReady {
+  return _isMapReady;
+}
+
+#pragma mark - MapProvider
+
+- (void)initializeMapInView:(UIView *)wrapperView
+          initialCoordinate:(CLLocationCoordinate2D)coordinate
+                initialZoom:(double)zoom {
+  if (_wrapperView)
+    return;
+
+  _wrapperView = wrapperView;
+  _coordinate = coordinate;
+  _zoom = zoom;
+
+  _shapeOverlayView =
+      [[LuggStaticShapeOverlayView alloc] initWithFrame:wrapperView.bounds];
+  _shapeOverlayView.autoresizingMask =
+      UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+  [wrapperView addSubview:_shapeOverlayView];
+
+  [self updateProjection];
+
+  __weak AppleStaticMapProvider *weakSelf = self;
+  if ([wrapperView isKindOfClass:[LuggMapWrapperView class]]) {
+    ((LuggMapWrapperView *)wrapperView).layoutHandler = ^{
+      [weakSelf wrapperDidLayout];
+    };
+  }
+
+  _isMapReady = YES;
+
+  // Start after the current mount pass so map settings props applied right
+  // after this call shape the snapshot options
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [weakSelf startSnapshotIfNeeded];
+  });
+}
+
+- (void)destroy {
+  [_snapshotter cancel];
+  _snapshotter = nil;
+
+  if ([_wrapperView isKindOfClass:[LuggMapWrapperView class]]) {
+    ((LuggMapWrapperView *)_wrapperView).layoutHandler = nil;
+  }
+
+  for (LuggMarkerView *markerView in _markerViews) {
+    markerView.delegate = nil;
+    UIView *iconView = markerView.iconView;
+    if (iconView.superview == _wrapperView) {
+      [iconView removeFromSuperview];
+    }
+    [markerView resetIconViewTransform];
+  }
+  [_markerViews removeAllObjects];
+  for (MKAnnotationView *pin in _defaultMarkerOverlays.objectEnumerator) {
+    [pin removeFromSuperview];
+  }
+  [_defaultMarkerOverlays removeAllObjects];
+
+  for (LuggPolylineView *view in _shapeOverlayView.polylineViews) {
+    view.delegate = nil;
+  }
+  for (LuggPolygonView *view in _shapeOverlayView.polygonViews) {
+    view.delegate = nil;
+  }
+  for (LuggCircleView *view in _shapeOverlayView.circleViews) {
+    view.delegate = nil;
+  }
+  for (LuggGroundOverlayView *view in _shapeOverlayView.groundOverlayViews) {
+    view.delegate = nil;
+  }
+  [_shapeOverlayView removeFromSuperview];
+  _shapeOverlayView = nil;
+
+  [_baseImageView removeFromSuperview];
+  _baseImageView = nil;
+
+  _snapshotDone = NO;
+  _projectionReady = NO;
+  _wrapperView = nil;
+  _isMapReady = NO;
+}
+
+#pragma mark - Snapshot
+
+- (void)updateProjection {
+  CGSize size = _wrapperView.bounds.size;
+  if (size.width <= 0 || size.height <= 0)
+    return;
+
+  _projectedSize = size;
+  _mapRect = LuggStaticFittedMapRect(_coordinate, _zoom, size);
+  _projectionReady = YES;
+
+  _shapeOverlayView.mapRect = _mapRect;
+  _shapeOverlayView.projectionReady = YES;
+  [_shapeOverlayView setNeedsDisplay];
+
+  for (LuggMarkerView *markerView in _markerViews) {
+    [self positionMarkerOverlay:markerView];
+  }
+}
+
+// A snapshot can't autoresize like a live map; when the wrapper gets its
+// first real size (or resizes later) recompute the projection and
+// (re)render the base image at the new size
+- (void)wrapperDidLayout {
+  CGSize size = _wrapperView.bounds.size;
+  if (size.width <= 0 || size.height <= 0 ||
+      CGSizeEqualToSize(size, _projectedSize))
+    return;
+
+  BOOL hadRender = _snapshotDone || _snapshotter != nil;
+  [self updateProjection];
+
+  if (hadRender) {
+    [_snapshotter cancel];
+    _snapshotter = nil;
+    _snapshotDone = NO;
+    self.cachedBaseImage = nil;
+  }
+  [self startSnapshotIfNeeded];
+}
+
+- (UITraitCollection *)snapshotTraitCollection {
+  UITraitCollection *base = _wrapperView.traitCollection;
+  UIUserInterfaceStyle style;
+  switch (_theme) {
+  case LuggMapViewTheme::Dark:
+    style = UIUserInterfaceStyleDark;
+    break;
+  case LuggMapViewTheme::Light:
+    style = UIUserInterfaceStyleLight;
+    break;
+  default:
+    return base;
+  }
+  return [UITraitCollection traitCollectionWithTraitsFromCollections:@[
+    base, [UITraitCollection traitCollectionWithUserInterfaceStyle:style]
+  ]];
+}
+
+- (void)startSnapshotIfNeeded {
+  if (_snapshotDone || _snapshotter || !_projectionReady || !_wrapperView)
+    return;
+
+  if (self.cachedBaseImage) {
+    [self displayBaseImage:self.cachedBaseImage fromCache:YES];
+    return;
+  }
+
+  MKMapSnapshotOptions *options = [[MKMapSnapshotOptions alloc] init];
+  options.mapRect = _mapRect;
+  options.size = _projectedSize;
+  options.mapType = LuggMKMapTypeFromMapType(_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)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache {
+  if (!_baseImageView) {
+    _baseImageView = [[UIImageView alloc] initWithFrame:_wrapperView.bounds];
+    _baseImageView.autoresizingMask =
+        UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+    [_wrapperView insertSubview:_baseImageView atIndex:0];
+  }
+  _baseImageView.image = image;
+  _snapshotDone = YES;
+
+  if (!fromCache) {
+    [_delegate mapProviderDidCaptureStaticImage:image];
+  }
+  [_delegate mapProviderDidFinishStaticSnapshot];
+  [_delegate mapProviderDidReady];
+}
+
+#pragma mark - Props
+
+- (void)setMapType:(LuggMapViewMapType)mapType {
+  _mapType = mapType;
+}
+
+- (void)setTheme:(LuggMapViewTheme)theme {
+  _theme = theme;
+}
+
+- (void)setPoiEnabled:(BOOL)enabled {
+  _poiEnabled = enabled;
+}
+
+- (void)setPoiFilterMode:(LuggMapViewPoiFilterMode)mode {
+  _poiFilterMode = mode;
+}
+
+- (void)setPoiFilterCategories:(NSArray<NSString *> *)categories {
+  _poiFilterCategories = categories;
+}
+
+// Interaction and camera props don't apply to a static snapshot
+- (void)setInsetAdjustment:(LuggMapViewInsetAdjustment)insetAdjustment {
+}
+- (void)setZoomEnabled:(BOOL)enabled {
+}
+- (void)setScrollEnabled:(BOOL)enabled {
+}
+- (void)setRotateEnabled:(BOOL)enabled {
+}
+- (void)setPitchEnabled:(BOOL)enabled {
+}
+- (void)setCompassEnabled:(BOOL)enabled {
+}
+- (void)setUserLocationEnabled:(BOOL)enabled {
+}
+- (void)setMinZoom:(double)minZoom {
+}
+- (void)setMaxZoom:(double)maxZoom {
+}
+- (void)setEdgeInsets:(UIEdgeInsets)edgeInsets
+        oldEdgeInsets:(UIEdgeInsets)oldEdgeInsets {
+}
+- (void)setEdgeInsets:(UIEdgeInsets)edgeInsets
+        oldEdgeInsets:(UIEdgeInsets)oldEdgeInsets
+             duration:(double)duration {
+}
+
+#pragma mark - Markers
+
+// Markers are live views over the snapshot (like Android lite mode's live
+// markers), so async content such as remote images shows up when it loads
+
+- (void)addMarkerView:(LuggMarkerView *)markerView {
+  markerView.delegate = self;
+  if (![_markerViews containsObject:markerView]) {
+    [_markerViews addObject:markerView];
+  }
+  [self syncMarkerView:markerView];
+}
+
+- (void)removeMarkerView:(LuggMarkerView *)markerView {
+  markerView.delegate = nil;
+  [_markerViews removeObject:markerView];
+
+  MKAnnotationView *pin = [_defaultMarkerOverlays objectForKey:markerView];
+  if (pin) {
+    [pin removeFromSuperview];
+    [_defaultMarkerOverlays removeObjectForKey:markerView];
+  }
+
+  UIView *iconView = markerView.iconView;
+  if (iconView.superview == _wrapperView) {
+    [iconView removeFromSuperview];
+  }
+  [markerView resetIconViewTransform];
+}
+
+- (void)syncMarkerView:(LuggMarkerView *)markerView {
+  if (!_wrapperView)
+    return;
+
+  MKAnnotationView *pin = [_defaultMarkerOverlays objectForKey:markerView];
+
+  if (markerView.hasCustomView) {
+    if (pin) {
+      [pin removeFromSuperview];
+      [_defaultMarkerOverlays removeObjectForKey:markerView];
+    }
+    UIView *iconView = markerView.iconView;
+    if (iconView.superview != _wrapperView) {
+      [iconView removeFromSuperview];
+      iconView.userInteractionEnabled = NO;
+      [_wrapperView addSubview:iconView];
+    }
+  } else {
+    UIView *iconView = markerView.iconView;
+    if (iconView.superview == _wrapperView) {
+      [iconView removeFromSuperview];
+      [markerView resetIconViewTransform];
+    }
+    if (!pin) {
+      pin = [[LuggMarkerAnnotationView alloc] initWithAnnotation:nil
+                                                 reuseIdentifier:nil];
+      pin.userInteractionEnabled = NO;
+      pin.bounds =
+          CGRectMake(0, 0, kDefaultMarkerSize.width, kDefaultMarkerSize.height);
+      [_wrapperView addSubview:pin];
+      [_defaultMarkerOverlays setObject:pin forKey:markerView];
+    }
+  }
+
+  [self positionMarkerOverlay:markerView];
+}
+
+- (void)positionMarkerOverlay:(LuggMarkerView *)markerView {
+  if (!_projectionReady)
+    return;
+
+  CGPoint point = LuggStaticPointForCoordinate(_mapRect, _projectedSize,
+                                               markerView.coordinate);
+
+  if (markerView.hasCustomView) {
+    UIView *iconView = markerView.iconView;
+    CGSize size = iconView.bounds.size;
+    if (size.width <= 0 || size.height <= 0) {
+      // Not laid out yet; markerViewDidLayout re-runs this
+      return;
+    }
+    CGFloat scale = markerView.scale;
+    CGFloat radians = markerView.rotate * M_PI / 180.0;
+    iconView.layer.anchorPoint = markerView.anchor;
+    iconView.transform =
+        CGAffineTransformConcat(CGAffineTransformMakeScale(scale, scale),
+                                CGAffineTransformMakeRotation(radians));
+    // center positions the layer's anchorPoint, so the marker's anchor
+    // lands exactly on the projected coordinate
+    iconView.center = point;
+    iconView.layer.zPosition = markerView.zIndex;
+  } else {
+    MKAnnotationView *pin = [_defaultMarkerOverlays objectForKey:markerView];
+    pin.layer.anchorPoint = CGPointMake(0.5, 1.0);
+    pin.center = point;
+    pin.layer.zPosition = markerView.zIndex;
+  }
+}
+
+#pragma mark - LuggMarkerViewDelegate
+
+- (void)markerViewDidLayout:(LuggMarkerView *)markerView {
+  [self syncMarkerView:markerView];
+}
+
+- (void)markerViewDidUpdate:(LuggMarkerView *)markerView {
+  [self syncMarkerView:markerView];
+}
+
+#pragma mark - Shapes
+
+- (void)addPolylineView:(LuggPolylineView *)polylineView {
+  polylineView.delegate = self;
+  if (![_shapeOverlayView.polylineViews containsObject:polylineView]) {
+    [_shapeOverlayView.polylineViews addObject:polylineView];
+  }
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)removePolylineView:(LuggPolylineView *)polylineView {
+  polylineView.delegate = nil;
+  [_shapeOverlayView.polylineViews removeObject:polylineView];
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)syncPolylineView:(LuggPolylineView *)polylineView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)polylineViewDidUpdate:(LuggPolylineView *)polylineView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)addPolygonView:(LuggPolygonView *)polygonView {
+  polygonView.delegate = self;
+  if (![_shapeOverlayView.polygonViews containsObject:polygonView]) {
+    [_shapeOverlayView.polygonViews addObject:polygonView];
+  }
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)removePolygonView:(LuggPolygonView *)polygonView {
+  polygonView.delegate = nil;
+  [_shapeOverlayView.polygonViews removeObject:polygonView];
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)syncPolygonView:(LuggPolygonView *)polygonView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)polygonViewDidUpdate:(LuggPolygonView *)polygonView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)addCircleView:(LuggCircleView *)circleView {
+  circleView.delegate = self;
+  if (![_shapeOverlayView.circleViews containsObject:circleView]) {
+    [_shapeOverlayView.circleViews addObject:circleView];
+  }
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)removeCircleView:(LuggCircleView *)circleView {
+  circleView.delegate = nil;
+  [_shapeOverlayView.circleViews removeObject:circleView];
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)syncCircleView:(LuggCircleView *)circleView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)circleViewDidUpdate:(LuggCircleView *)circleView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)addGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
+  groundOverlayView.delegate = self;
+  if (![_shapeOverlayView.groundOverlayViews
+          containsObject:groundOverlayView]) {
+    [_shapeOverlayView.groundOverlayViews addObject:groundOverlayView];
+  }
+  [self loadGroundOverlayImage:groundOverlayView];
+}
+
+- (void)removeGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
+  groundOverlayView.delegate = nil;
+  [_shapeOverlayView.groundOverlayViews removeObject:groundOverlayView];
+  [_shapeOverlayView.groundOverlayImages removeObjectForKey:groundOverlayView];
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)syncGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
+  [self loadGroundOverlayImage:groundOverlayView];
+}
+
+- (void)groundOverlayViewDidUpdate:(LuggGroundOverlayView *)groundOverlayView {
+  [self loadGroundOverlayImage:groundOverlayView];
+}
+
+- (void)loadGroundOverlayImage:(LuggGroundOverlayView *)groundOverlayView {
+  NSURL *url = [NSURL URLWithString:groundOverlayView.imageUri];
+  if (!url)
+    return;
+
+  __weak AppleStaticMapProvider *weakSelf = self;
+  __weak LuggGroundOverlayView *weakOverlayView = groundOverlayView;
+  dispatch_async(
+      dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+        NSData *data = [NSData dataWithContentsOfURL:url];
+        UIImage *image = data ? [UIImage imageWithData:data] : nil;
+        dispatch_async(dispatch_get_main_queue(), ^{
+          AppleStaticMapProvider *strongSelf = weakSelf;
+          LuggGroundOverlayView *overlayView = weakOverlayView;
+          if (!strongSelf || !overlayView || !image)
+            return;
+          LuggStaticShapeOverlayView *shapeView = strongSelf->_shapeOverlayView;
+          if (![shapeView.groundOverlayViews containsObject:overlayView])
+            return;
+          [shapeView.groundOverlayImages setObject:image forKey:overlayView];
+          [shapeView setNeedsDisplay];
+        });
+      });
+}
+
+// Tile overlays need a live map to fetch and compose tiles; unsupported on
+// static Apple maps
+- (void)addTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
+}
+- (void)removeTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
+}
+- (void)syncTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
+}
+
+#pragma mark - Lifecycle
+
+- (void)pauseAnimations {
+}
+
+- (void)resumeAnimations {
+  // Retry a failed or cancelled snapshot (e.g. device back online)
+  [self startSnapshotIfNeeded];
+}
+
+#pragma mark - Commands
+
+// Static maps render once with their initial camera
+
+- (void)moveCamera:(double)latitude
+         longitude:(double)longitude
+              zoom:(double)zoom
+          duration:(double)duration {
+}
+
+- (void)fitCoordinates:(NSArray *)coordinates
+         edgeInsetsTop:(double)edgeInsetsTop
+        edgeInsetsLeft:(double)edgeInsetsLeft
+      edgeInsetsBottom:(double)edgeInsetsBottom
+       edgeInsetsRight:(double)edgeInsetsRight
+              duration:(double)duration {
+}
+
+@end
diff --git a/ios/core/LuggStaticMapWarmupQueue.h b/ios/core/LuggStaticMapWarmupQueue.h
index 5cbdac6..8353597 100644
--- a/ios/core/LuggStaticMapWarmupQueue.h
+++ b/ios/core/LuggStaticMapWarmupQueue.h
@@ -4,9 +4,10 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  * Serializes static map warmup so only a few live maps exist at a time.
- * Static maps briefly need a live map view to render their snapshot;
- * without throttling, a list mounting many rows creates them all at once
- * and stalls the main thread.
+ * Google static maps briefly need a live map view to render their snapshot
+ * (the SDK has no async snapshotter); without throttling, a list mounting
+ * many rows creates them all at once and stalls the main thread. Apple
+ * static maps render through MKMapSnapshotter and don't use this queue.
  */
 @interface LuggStaticMapWarmupQueue : NSObject
 
diff --git a/ios/extensions/MKMapView+Zoom.h b/ios/extensions/MKMapView+Zoom.h
index 5da5197..d02d850 100644
--- a/ios/extensions/MKMapView+Zoom.h
+++ b/ios/extensions/MKMapView+Zoom.h
@@ -2,6 +2,19 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Coordinate span for a Google-style zoom level, shared by the live map
+/// (MKMapView region) and the static snapshotter (no map view)
+MKCoordinateSpan LuggCoordinateSpanForZoomLevel(
+    double zoomLevel, CLLocationCoordinate2D centerCoordinate);
+
+#ifdef __cplusplus
+}
+#endif
+
 @interface MKMapView (Zoom)
 
 - (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
diff --git a/ios/extensions/MKMapView+Zoom.m b/ios/extensions/MKMapView+Zoom.m
index 9dd42a9..1110f55 100644
--- a/ios/extensions/MKMapView+Zoom.m
+++ b/ios/extensions/MKMapView+Zoom.m
@@ -1,22 +1,24 @@
 #import "MKMapView+Zoom.h"
 
-@implementation MKMapView (Zoom)
+// Google Maps: zoom level defines how many 256px tiles fit the world
+// At zoom 0, 1 tile = 360 degrees
+// Each zoom level doubles the number of tiles (halves the degrees per tile)
+// Offset of ~0.5 adjusts for difference between Google Maps and MKMapView
+// rendering
+MKCoordinateSpan LuggCoordinateSpanForZoomLevel(
+    double zoomLevel, CLLocationCoordinate2D centerCoordinate) {
+  double adjustedZoom = zoomLevel - 0.5;
+  double latitudeDelta = 360.0 / pow(2, adjustedZoom);
 
-- (MKCoordinateSpan)coordinateSpanForZoomLevel:(double)zoomLevel centerCoordinate:(CLLocationCoordinate2D)centerCoordinate
-{
-    // Google Maps: zoom level defines how many 256px tiles fit the world
-    // At zoom 0, 1 tile = 360 degrees
-    // Each zoom level doubles the number of tiles (halves the degrees per tile)
-    // Offset of ~0.5 adjusts for difference between Google Maps and MKMapView rendering
-    double adjustedZoom = zoomLevel - 0.5;
-    double latitudeDelta = 360.0 / pow(2, adjustedZoom);
-    
-    // Adjust longitude delta for latitude (Mercator projection)
-    double longitudeDelta = latitudeDelta / cos(centerCoordinate.latitude * M_PI / 180.0);
-    
-    return MKCoordinateSpanMake(latitudeDelta, longitudeDelta);
+  // Adjust longitude delta for latitude (Mercator projection)
+  double longitudeDelta =
+      latitudeDelta / cos(centerCoordinate.latitude * M_PI / 180.0);
+
+  return MKCoordinateSpanMake(latitudeDelta, longitudeDelta);
 }
 
+@implementation MKMapView (Zoom)
+
 #pragma mark - Public Methods
 
 // Constant for altitude/zoom conversion (meters at zoom level 0)
@@ -48,7 +50,7 @@ - (MKCoordinateRegion)regionForCenterCoordinate:(CLLocationCoordinate2D)centerCo
                                       zoomLevel:(double)zoomLevel
 {
     zoomLevel = MIN(zoomLevel, 28);
-    MKCoordinateSpan span = [self coordinateSpanForZoomLevel:zoomLevel centerCoordinate:centerCoordinate];
+    MKCoordinateSpan span = LuggCoordinateSpanForZoomLevel(zoomLevel, centerCoordinate);
     return MKCoordinateRegionMake(centerCoordinate, span);
 }
 

From 73a24220f06ceaa45c9b8be021259d10a6f61120 Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 01:27:53 +0800
Subject: [PATCH 11/17] perf(ios): pool GMSMapViews for static map warmups

Creating and tearing down a GMSMapView are expensive main-thread
operations; detached static maps are pooled (capacity 3, keyed by map
ID) and reused, so a warmup usually only costs a camera move plus tile
load. Pool drains on memory warnings.
---
 ios/core/GoogleMapProvider.mm | 102 ++++++++++++++++++++++++++++------
 1 file changed, 86 insertions(+), 16 deletions(-)

diff --git a/ios/core/GoogleMapProvider.mm b/ios/core/GoogleMapProvider.mm
index cdc46a5..571b83a 100644
--- a/ios/core/GoogleMapProvider.mm
+++ b/ios/core/GoogleMapProvider.mm
@@ -18,6 +18,58 @@
 
 static NSString *const kDemoMapId = @"DEMO_MAP_ID";
 
+// 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 = 3;
+
+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;
+
+  // Reset state that a fresh provider won't reapply (its prop setters
+  // no-op on default values)
+  [mapView clear];
+  mapView.selectedMarker = nil;
+  mapView.myLocationEnabled = NO;
+  mapView.padding = UIEdgeInsetsZero;
+  [mapView setMinZoom:kGMSMinZoomLevel maxZoom:kGMSMaxZoomLevel];
+  [views addObject:mapView];
+}
+
 @interface GoogleMapProvider () <
     LuggMarkerViewDelegate, LuggCalloutViewDelegate, LuggPolylineViewDelegate,
     LuggPolygonViewDelegate, LuggCircleViewDelegate,
@@ -95,25 +147,36 @@ - (void)initializeMapInView:(UIView *)wrapperView
   if (_mapView)
     return;
 
-  GMSMapID *gmsMapId;
-  if ([_mapId isEqualToString:kDemoMapId] || _mapId.length == 0) {
-    gmsMapId = [GMSMapID demoMapID];
+  _tilesRendered = NO;
+
+  GMSMapView *pooledMapView =
+      _staticMode ? DequeueStaticMapView(_mapId) : nil;
+  if (pooledMapView) {
+    _mapView = pooledMapView;
+    _mapView.frame = wrapperView.bounds;
+    [_mapView moveCamera:[GMSCameraUpdate setTarget:coordinate
+                                               zoom:(float)zoom]];
   } else {
-    gmsMapId = [GMSMapID mapIDWithIdentifier:_mapId];
-  }
+    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
-                                       zoom:zoom];
+    GMSCameraPosition *camera =
+        [GMSCameraPosition cameraWithLatitude:coordinate.latitude
+                                    longitude:coordinate.longitude
+                                         zoom:zoom];
 
-  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
-  options.frame = wrapperView.bounds;
-  options.camera = camera;
-  options.mapID = gmsMapId;
+    GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
+    options.frame = wrapperView.bounds;
+    options.camera = camera;
+    options.mapID = gmsMapId;
+
+    _mapView = [[GMSMapView alloc] initWithOptions:options];
+  }
 
-  _tilesRendered = NO;
-  _mapView = [[GMSMapView alloc] initWithOptions:options];
   _mapView.autoresizingMask =
       UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
   _mapView.delegate = self;
@@ -162,9 +225,16 @@ - (void)destroy {
 }
 
 - (void)destroyMapView {
+  if (!_mapView)
+    return;
+
   _mapView.delegate = nil;
-  [_mapView clear];
   [_mapView removeFromSuperview];
+  if (_staticMode) {
+    EnqueueStaticMapView(_mapId, _mapView);
+  } else {
+    [_mapView clear];
+  }
   _mapView = nil;
 }
 

From f8bba1a22f2553db09089e61dbf07769148f15ff Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 01:59:52 +0800
Subject: [PATCH 12/17] perf(ios): render google static map markers as live
 overlays, async base warmup

Extract Apple static provider's overlay machinery (projection, live
marker views, CG shape overlay) into StaticMapProviderBase and add
GoogleStaticMapProvider: markers/shapes show immediately without a
warmup slot; only the base map warms up on a pooled, tiles-only
GMSMapView below the overlays, then swaps to an image. Strips static
mode from GoogleMapProvider and warmup bookkeeping from LuggMapView.
---
 docs/MAPVIEW.md                     |  37 +-
 ios/LuggMapView.mm                  | 117 +----
 ios/core/AppleStaticMapProvider.h   |  20 +-
 ios/core/AppleStaticMapProvider.mm  | 716 +--------------------------
 ios/core/GoogleMapProvider.h        |  10 +
 ios/core/GoogleMapProvider.mm       | 240 ++-------
 ios/core/GoogleStaticMapProvider.h  |  21 +
 ios/core/GoogleStaticMapProvider.mm | 232 +++++++++
 ios/core/LuggStaticMapWarmupQueue.h |  11 +-
 ios/core/StaticMapProviderBase.h    |  63 +++
 ios/core/StaticMapProviderBase.mm   | 725 ++++++++++++++++++++++++++++
 11 files changed, 1164 insertions(+), 1028 deletions(-)
 create mode 100644 ios/core/GoogleStaticMapProvider.h
 create mode 100644 ios/core/GoogleStaticMapProvider.mm
 create mode 100644 ios/core/StaticMapProviderBase.h
 create mode 100644 ios/core/StaticMapProviderBase.mm

diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index 26b53cb..8aaa835 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -56,16 +56,18 @@ mounting many live maps is expensive:
 - **Android (Google)** - uses [lite mode](https://developers.google.com/maps/documentation/android-sdk/lite),
   which renders a static bitmap instead of a live GL surface. Lite mode does
   not support cloud-based styling, so `mapId` is ignored on static maps.
-- **iOS (Apple)** - rendered with `MKMapSnapshotter`, which loads the base
-  map entirely off the main thread (no live map view is ever created), so
+- **iOS (Apple)** - the base map is rendered with `MKMapSnapshotter`, which
+  loads entirely off the main thread (no live map view is ever created), so
   static maps keep loading while scrolling. Markers stay live views
-  positioned over the snapshot; polylines, polygons, circles, and ground
+  positioned over the base map; polylines, polygons, circles, and ground
   overlays are drawn onto it. Tile overlays are not supported.
-- **iOS (Google)** - the SDK has no async snapshotter, so a live map is
-  created briefly and replaced with a rendered snapshot image once tiles
-  finish loading, releasing the map's rendering resources. Rendering is
-  paced to never compete with scroll gestures, so rows fill in only
-  between scrolls.
+- **iOS (Google)** - markers and shapes render as live overlay views
+  immediately, exactly like Apple static maps. Only the base map needs the
+  SDK (which has no async snapshotter): a live, tiles-only map warms up
+  briefly under the overlays and is replaced with a rendered image once
+  tiles finish loading, releasing the map's rendering resources. Warmups
+  are paced to never compete with scroll gestures, so base maps fill in
+  between scrolls while markers show right away.
 - **Web (Google)** - gestures, POI clicks, keyboard interaction, and press
   events are disabled; the map itself stays live.
 
@@ -94,18 +96,17 @@ Notes:
   map container (as above) instead of relying on `onPress`.
 - `animated` polylines render as complete static polylines, so the snapshot
   never freezes a mid-animation frame.
-- On iOS Apple Maps, markers are live views over the snapshot - marker
-  content that loads asynchronously (e.g. remote images) appears when
-  ready, and marker prop updates still apply.
+- On iOS, markers are live views over the base map - marker content that
+  loads asynchronously (e.g. remote images) appears when ready, and marker
+  prop updates still apply.
 - While a static map loads, a theme-aware placeholder background is shown.
   Set a `backgroundColor` style on the `MapView` to use your own.
-- Set `staticKey` (e.g. your list item's id) to cache snapshots across
-  list recycling on iOS - scrolling back to a row reuses its snapshot
-  instead of rendering the map again. The camera and map settings are
-  part of the cache key automatically; the key must uniquely identify the
-  rest of the map's content (e.g. markers). Changing `staticKey` discards
-  the current snapshot and re-renders. The cache is bounded by count and
-  total memory.
+- Set `staticKey` (e.g. your list item's id) to cache base map images
+  across list recycling on iOS - scrolling back to a row reuses its image
+  instead of rendering the map again (markers and shapes stay live and
+  re-render from props). The camera and map settings are part of the
+  cache key automatically. Changing `staticKey` discards the current
+  image and re-renders. The cache is bounded by count and total memory.
 - Alternatively, keeping rows mounted (larger `windowSize` with
   `removeClippedSubviews`) avoids re-rendering entirely at the cost of
   holding every row's snapshot in memory.
diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index a36b1b1..d14d7c0 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -9,7 +9,7 @@
 #import "core/AppleMapProvider.h"
 #import "core/AppleStaticMapProvider.h"
 #import "core/GoogleMapProvider.h"
-#import "core/LuggStaticMapWarmupQueue.h"
+#import "core/GoogleStaticMapProvider.h"
 #import "core/MapProviderDelegate.h"
 #import "events/CameraIdleEvent.h"
 #import "events/CameraMoveEvent.h"
@@ -57,10 +57,7 @@ @implementation LuggMapView {
   BOOL _compassEnabled;
   BOOL _staticMode;
   NSString *_staticKey;
-  UIImageView *_staticCachedImageView;
   BOOL _staticSnapshotDone;
-  BOOL _waitingForWarmupSlot;
-  BOOL _holdingWarmupSlot;
   BOOL _userLocationEnabled;
   LuggMapViewMapType _mapType;
   LuggMapViewTheme _theme;
@@ -201,15 +198,10 @@ - (void)didMoveToWindow {
     }
     [_provider resumeAnimations];
   } else {
-    if (_waitingForWarmupSlot) {
-      [[LuggStaticMapWarmupQueue sharedQueue] cancelOwner:self];
-      _waitingForWarmupSlot = NO;
-    }
-    // A static map mid-warmup holds an expensive live map view. Destroy it
-    // off-window and re-warm on return instead of letting paused maps pile
-    // up across screen switches and all resume at once
+    // 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) {
-      [self releaseWarmupSlot];
       [_provider destroy];
       _provider = nil;
       _initialized = NO;
@@ -269,71 +261,14 @@ - (nullable NSString *)staticSnapshotCacheKey {
                                     viewProps.initialZoom];
 }
 
-- (BOOL)showCachedStaticSnapshot {
-  if (_staticCachedImageView)
-    return YES;
-
-  NSString *key = [self staticSnapshotCacheKey];
-  if (!key)
-    return NO;
-
-  UIImage *image = [StaticSnapshotCache() objectForKey:key];
-  if (!image)
-    return NO;
-
-  UIImageView *imageView =
-      [[UIImageView alloc] initWithFrame:_mapWrapperView.bounds];
-  imageView.autoresizingMask =
-      UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
-  imageView.image = image;
-  [_mapWrapperView addSubview:imageView];
-  _staticCachedImageView = imageView;
-
-  ReadyEvent::emit<LuggMapViewEventEmitter>(_eventEmitter);
-  return YES;
-}
-
 - (void)startStaticContent {
   [self applyStaticPlaceholderBackground];
 
-  // Apple static maps render through MKMapSnapshotter - fully async like
-  // Android's lite mode - so they start immediately (even mid-scroll) with
-  // no warmup pacing. The provider reuses a cached base image itself.
-  if (_providerType == LuggMapViewProvider::Apple) {
-    [self initializeProvider];
-    return;
-  }
-
-  // Google has no snapshotter API; a live map warms up briefly, paced by
-  // the warmup queue so it never competes with scroll gestures
-  if (![self showCachedStaticSnapshot]) {
-    [self requestStaticWarmup];
-  }
-}
-
-- (void)requestStaticWarmup {
-  if (_waitingForWarmupSlot || _holdingWarmupSlot)
-    return;
-
-  _waitingForWarmupSlot = YES;
-  __weak LuggMapView *weakSelf = self;
-  [[LuggStaticMapWarmupQueue sharedQueue]
-      requestSlotForOwner:self
-               completion:^{
-                 LuggMapView *strongSelf = weakSelf;
-                 if (!strongSelf)
-                   return;
-                 strongSelf->_waitingForWarmupSlot = NO;
-                 strongSelf->_holdingWarmupSlot = YES;
-                 [strongSelf initializeProvider];
-               }];
-}
-
-- (void)releaseWarmupSlot {
-  if (_holdingWarmupSlot) {
-    _holdingWarmupSlot = NO;
-    [[LuggStaticMapWarmupQueue sharedQueue] releaseSlotForOwner:self];
-  }
+  // Both static providers render fully async: markers and shapes show up
+  // as overlay views immediately, and the base map arrives when the
+  // snapshotter (Apple) or a paced warmup (Google) finishes - so static
+  // maps keep loading while the user scrolls
+  [self initializeProvider];
 }
 
 // staticKey identifies the map's content; when it changes (e.g. a recycled
@@ -341,12 +276,9 @@ - (void)releaseWarmupSlot {
 // stale and the static lifecycle restarts. Without this, an in-flight
 // warmup caches the old item's map under the new key.
 - (void)resetStaticContent {
-  [_staticCachedImageView removeFromSuperview];
-  _staticCachedImageView = nil;
   _staticSnapshotDone = NO;
 
   if (_provider) {
-    [self releaseWarmupSlot];
     [_provider destroy];
     _provider = nil;
     _initialized = NO;
@@ -360,12 +292,6 @@ - (void)resetStaticContent {
 - (void)prepareForRecycle {
   [super prepareForRecycle];
 
-  [[LuggStaticMapWarmupQueue sharedQueue] cancelOwner:self];
-  _waitingForWarmupSlot = NO;
-  [self releaseWarmupSlot];
-
-  [_staticCachedImageView removeFromSuperview];
-  _staticCachedImageView = nil;
   _staticSnapshotDone = NO;
 
   [_provider destroy];
@@ -384,22 +310,26 @@ - (void)initializeProvider {
       *std::static_pointer_cast<LuggMapViewProps const>(_props);
 
   if (_providerType == LuggMapViewProvider::Apple) {
-    if (_staticMode) {
-      AppleStaticMapProvider *apple = [[AppleStaticMapProvider alloc] init];
-      NSString *cacheKey = [self staticSnapshotCacheKey];
-      if (cacheKey) {
-        apple.cachedBaseImage = [StaticSnapshotCache() objectForKey:cacheKey];
-      }
-      _provider = apple;
-    } else {
-      _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;
 
@@ -443,7 +373,6 @@ - (void)mapProviderDidReady {
 
 - (void)mapProviderDidFinishStaticSnapshot {
   _staticSnapshotDone = YES;
-  [self releaseWarmupSlot];
 }
 
 - (void)mapProviderDidCaptureStaticImage:(UIImage *)image {
diff --git a/ios/core/AppleStaticMapProvider.h b/ios/core/AppleStaticMapProvider.h
index e3b5f8d..57bb271 100644
--- a/ios/core/AppleStaticMapProvider.h
+++ b/ios/core/AppleStaticMapProvider.h
@@ -1,25 +1,13 @@
-#import "MapProviderDelegate.h"
-#import <MapKit/MapKit.h>
+#import "StaticMapProviderBase.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- * Static (non-interactive) Apple map rendered with MKMapSnapshotter -
- * the iOS equivalent of Android's lite mode. The base map renders fully
- * asynchronously (no live MKMapView is ever created), so static maps
+ * 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.
- *
- * Markers are live views positioned over the snapshot via a mercator
- * projection (mirroring Android's live markers on lite maps), so
- * async marker content (e.g. remote images) appears when it loads.
- * Polylines, polygons, circles and ground overlays are drawn into a
- * single CoreGraphics overlay view. Tile overlays are not supported.
  */
-@interface AppleStaticMapProvider : NSObject <MapProvider>
-
-/// Previously captured base map for the same cache key; when set, the
-/// snapshotter is skipped and the image is shown immediately.
-@property(nonatomic, strong, nullable) UIImage *cachedBaseImage;
+@interface AppleStaticMapProvider : StaticMapProviderBase
 
 @end
 
diff --git a/ios/core/AppleStaticMapProvider.mm b/ios/core/AppleStaticMapProvider.mm
index 0336786..362904b 100644
--- a/ios/core/AppleStaticMapProvider.mm
+++ b/ios/core/AppleStaticMapProvider.mm
@@ -1,16 +1,8 @@
 #import "AppleStaticMapProvider.h"
 
-using facebook::react::LuggMapViewInsetAdjustment;
-using facebook::react::LuggMapViewMapType;
 using facebook::react::LuggMapViewPoiFilterMode;
 using facebook::react::LuggMapViewTheme;
 
-#import "../LuggCircleView.h"
-#import "../LuggGroundOverlayView.h"
-#import "../LuggMapWrapperView.h"
-#import "../LuggMarkerView.h"
-#import "../LuggPolygonView.h"
-#import "../LuggPolylineView.h"
 #import "../extensions/MKMapView+Zoom.h"
 #import "AppleMapProvider.h"
 #import "LuggAnnotationView.h"
@@ -19,12 +11,10 @@
 // don't size themselves
 static const CGSize kDefaultMarkerSize = {28, 33};
 
-#pragma mark - Projection
-
 // 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 below exact.
+// exact rect to MKMapSnapshotter makes the projection exact.
 static MKMapRect LuggStaticFittedMapRect(CLLocationCoordinate2D center,
                                          double zoom, CGSize size) {
   MKCoordinateSpan span = LuggCoordinateSpanForZoomLevel(MIN(zoom, 28), center);
@@ -52,253 +42,16 @@ static MKMapRect LuggStaticFittedMapRect(CLLocationCoordinate2D center,
   return rect;
 }
 
-static CGPoint LuggStaticPointForCoordinate(MKMapRect mapRect, CGSize size,
-                                            CLLocationCoordinate2D coordinate) {
-  MKMapPoint point = MKMapPointForCoordinate(coordinate);
-  return CGPointMake(
-      (point.x - mapRect.origin.x) / mapRect.size.width * size.width,
-      (point.y - mapRect.origin.y) / mapRect.size.height * size.height);
-}
-
-#pragma mark - Shape overlay
-
-// Draws polylines, polygons, circles and ground overlays over the base
-// snapshot with CoreGraphics; MKMapSnapshotter renders map tiles only
-@interface LuggStaticShapeOverlayView : UIView
-@property(nonatomic, assign) MKMapRect mapRect;
-@property(nonatomic, assign) BOOL projectionReady;
-@property(nonatomic, strong) NSMutableArray<LuggPolylineView *> *polylineViews;
-@property(nonatomic, strong) NSMutableArray<LuggPolygonView *> *polygonViews;
-@property(nonatomic, strong) NSMutableArray<LuggCircleView *> *circleViews;
-@property(nonatomic, strong)
-    NSMutableArray<LuggGroundOverlayView *> *groundOverlayViews;
-@property(nonatomic, strong)
-    NSMapTable<LuggGroundOverlayView *, UIImage *> *groundOverlayImages;
-@end
-
-@implementation LuggStaticShapeOverlayView
-
-- (instancetype)initWithFrame:(CGRect)frame {
-  if (self = [super initWithFrame:frame]) {
-    self.opaque = NO;
-    self.backgroundColor = UIColor.clearColor;
-    self.userInteractionEnabled = NO;
-    self.contentMode = UIViewContentModeRedraw;
-    _polylineViews = [NSMutableArray array];
-    _polygonViews = [NSMutableArray array];
-    _circleViews = [NSMutableArray array];
-    _groundOverlayViews = [NSMutableArray array];
-    _groundOverlayImages = [NSMapTable weakToStrongObjectsMapTable];
-  }
-  return self;
-}
-
-static NSInteger shapeZIndex(UIView *shape) {
-  if ([shape isKindOfClass:[LuggPolylineView class]])
-    return ((LuggPolylineView *)shape).zIndex;
-  if ([shape isKindOfClass:[LuggPolygonView class]])
-    return ((LuggPolygonView *)shape).zIndex;
-  if ([shape isKindOfClass:[LuggCircleView class]])
-    return ((LuggCircleView *)shape).zIndex;
-  if ([shape isKindOfClass:[LuggGroundOverlayView class]])
-    return ((LuggGroundOverlayView *)shape).zIndex;
-  return 0;
-}
-
-- (CGPoint)pointForCoordinate:(CLLocationCoordinate2D)coordinate {
-  return LuggStaticPointForCoordinate(_mapRect, self.bounds.size, coordinate);
-}
-
-- (void)addPath:(CGContextRef)context
-           ring:(NSArray<CLLocation *> *)coordinates {
-  for (NSUInteger i = 0; i < coordinates.count; i++) {
-    CGPoint point = [self pointForCoordinate:coordinates[i].coordinate];
-    if (i == 0) {
-      CGContextMoveToPoint(context, point.x, point.y);
-    } else {
-      CGContextAddLineToPoint(context, point.x, point.y);
-    }
-  }
-}
-
-- (void)drawPolyline:(LuggPolylineView *)polylineView
-           inContext:(CGContextRef)context {
-  NSArray<CLLocation *> *coordinates = polylineView.coordinates;
-  UIColor *color = polylineView.strokeColors.firstObject;
-  if (coordinates.count < 2 || !color || polylineView.strokeWidth <= 0)
-    return;
-
-  CGContextSaveGState(context);
-  [self addPath:context ring:coordinates];
-  CGContextSetLineWidth(context, polylineView.strokeWidth);
-  CGContextSetLineCap(context, kCGLineCapRound);
-  CGContextSetLineJoin(context, kCGLineJoinRound);
-  CGContextSetStrokeColorWithColor(context, color.CGColor);
-  CGContextStrokePath(context);
-  CGContextRestoreGState(context);
-}
-
-- (void)drawPolygon:(LuggPolygonView *)polygonView
-          inContext:(CGContextRef)context {
-  NSArray<CLLocation *> *coordinates = polygonView.coordinates;
-  if (coordinates.count < 3)
-    return;
-
-  CGContextSaveGState(context);
-
-  if (polygonView.fillColor) {
-    [self addPath:context ring:coordinates];
-    CGContextClosePath(context);
-    for (NSArray<CLLocation *> *hole in polygonView.holes) {
-      [self addPath:context ring:hole];
-      CGContextClosePath(context);
-    }
-    CGContextSetFillColorWithColor(context, polygonView.fillColor.CGColor);
-    CGContextEOFillPath(context);
-  }
-
-  if (polygonView.strokeColor && polygonView.strokeWidth > 0) {
-    [self addPath:context ring:coordinates];
-    CGContextClosePath(context);
-    for (NSArray<CLLocation *> *hole in polygonView.holes) {
-      [self addPath:context ring:hole];
-      CGContextClosePath(context);
-    }
-    CGContextSetLineWidth(context, polygonView.strokeWidth);
-    CGContextSetLineJoin(context, kCGLineJoinRound);
-    CGContextSetStrokeColorWithColor(context, polygonView.strokeColor.CGColor);
-    CGContextStrokePath(context);
-  }
-
-  CGContextRestoreGState(context);
-}
-
-- (void)drawCircle:(LuggCircleView *)circleView
-         inContext:(CGContextRef)context {
-  if (circleView.radius <= 0)
-    return;
-
-  CGPoint center = [self pointForCoordinate:circleView.center];
-  double pointsPerMapPoint = self.bounds.size.width / _mapRect.size.width;
-  double radius = circleView.radius *
-                  MKMapPointsPerMeterAtLatitude(circleView.center.latitude) *
-                  pointsPerMapPoint;
-  CGRect ellipse =
-      CGRectMake(center.x - radius, center.y - radius, radius * 2, radius * 2);
-
-  CGContextSaveGState(context);
-  if (circleView.fillColor) {
-    CGContextSetFillColorWithColor(context, circleView.fillColor.CGColor);
-    CGContextFillEllipseInRect(context, ellipse);
-  }
-  if (circleView.strokeColor && circleView.strokeWidth > 0) {
-    CGContextSetLineWidth(context, circleView.strokeWidth);
-    CGContextSetStrokeColorWithColor(context, circleView.strokeColor.CGColor);
-    CGContextStrokeEllipseInRect(context, ellipse);
-  }
-  CGContextRestoreGState(context);
-}
-
-- (void)drawGroundOverlay:(LuggGroundOverlayView *)groundOverlayView {
-  UIImage *image = [_groundOverlayImages objectForKey:groundOverlayView];
-  if (!image)
-    return;
-
-  CGPoint topLeft =
-      [self pointForCoordinate:CLLocationCoordinate2DMake(
-                                   groundOverlayView.northeast.latitude,
-                                   groundOverlayView.southwest.longitude)];
-  CGPoint bottomRight =
-      [self pointForCoordinate:CLLocationCoordinate2DMake(
-                                   groundOverlayView.southwest.latitude,
-                                   groundOverlayView.northeast.longitude)];
-  CGRect rect = CGRectMake(topLeft.x, topLeft.y, bottomRight.x - topLeft.x,
-                           bottomRight.y - topLeft.y);
-  [image drawInRect:rect
-          blendMode:kCGBlendModeNormal
-              alpha:groundOverlayView.opacity];
-}
-
-- (void)drawRect:(CGRect)rect {
-  if (!_projectionReady)
-    return;
-
-  CGContextRef context = UIGraphicsGetCurrentContext();
-  if (!context)
-    return;
-
-  NSMutableArray<UIView *> *shapes = [NSMutableArray array];
-  [shapes addObjectsFromArray:_groundOverlayViews];
-  [shapes addObjectsFromArray:_polygonViews];
-  [shapes addObjectsFromArray:_circleViews];
-  [shapes addObjectsFromArray:_polylineViews];
-  NSArray<UIView *> *ordered =
-      [shapes sortedArrayWithOptions:NSSortStable
-                     usingComparator:^NSComparisonResult(UIView *a, UIView *b) {
-                       NSInteger za = shapeZIndex(a), zb = shapeZIndex(b);
-                       if (za < zb)
-                         return NSOrderedAscending;
-                       if (za > zb)
-                         return NSOrderedDescending;
-                       return NSOrderedSame;
-                     }];
-
-  for (UIView *shape in ordered) {
-    if ([shape isKindOfClass:[LuggGroundOverlayView class]]) {
-      [self drawGroundOverlay:(LuggGroundOverlayView *)shape];
-    } else if ([shape isKindOfClass:[LuggPolygonView class]]) {
-      [self drawPolygon:(LuggPolygonView *)shape inContext:context];
-    } else if ([shape isKindOfClass:[LuggCircleView class]]) {
-      [self drawCircle:(LuggCircleView *)shape inContext:context];
-    } else if ([shape isKindOfClass:[LuggPolylineView class]]) {
-      [self drawPolyline:(LuggPolylineView *)shape inContext:context];
-    }
-  }
-}
-
-@end
-
-#pragma mark - Provider
-
-@interface AppleStaticMapProvider () <
-    LuggMarkerViewDelegate, LuggPolylineViewDelegate, LuggPolygonViewDelegate,
-    LuggCircleViewDelegate, LuggGroundOverlayViewDelegate>
-@end
-
 @implementation AppleStaticMapProvider {
-  UIView *_wrapperView;
-  CLLocationCoordinate2D _coordinate;
-  double _zoom;
-  BOOL _isMapReady;
-
-  MKMapRect _mapRect;
-  CGSize _projectedSize;
-  BOOL _projectionReady;
-
   MKMapSnapshotter *_snapshotter;
-  UIImageView *_baseImageView;
-  BOOL _snapshotDone;
 
-  LuggStaticShapeOverlayView *_shapeOverlayView;
-  NSMutableArray<LuggMarkerView *> *_markerViews;
-  NSMapTable<LuggMarkerView *, MKAnnotationView *> *_defaultMarkerOverlays;
-
-  LuggMapViewMapType _mapType;
-  LuggMapViewTheme _theme;
   BOOL _poiEnabled;
   LuggMapViewPoiFilterMode _poiFilterMode;
   NSArray<NSString *> *_poiFilterCategories;
 }
 
-@synthesize delegate = _delegate;
-@synthesize staticMode = _staticMode;
-
 - (instancetype)init {
   if (self = [super init]) {
-    _markerViews = [NSMutableArray array];
-    _defaultMarkerOverlays = [NSMapTable weakToStrongObjectsMapTable];
-    _mapType = LuggMapViewMapType::Standard;
-    _theme = LuggMapViewTheme::System;
     _poiEnabled = YES;
     _poiFilterMode = LuggMapViewPoiFilterMode::Including;
     _poiFilterCategories = @[];
@@ -306,137 +59,25 @@ - (instancetype)init {
   return self;
 }
 
-- (BOOL)isMapReady {
-  return _isMapReady;
-}
-
-#pragma mark - MapProvider
-
-- (void)initializeMapInView:(UIView *)wrapperView
-          initialCoordinate:(CLLocationCoordinate2D)coordinate
-                initialZoom:(double)zoom {
-  if (_wrapperView)
-    return;
-
-  _wrapperView = wrapperView;
-  _coordinate = coordinate;
-  _zoom = zoom;
-
-  _shapeOverlayView =
-      [[LuggStaticShapeOverlayView alloc] initWithFrame:wrapperView.bounds];
-  _shapeOverlayView.autoresizingMask =
-      UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
-  [wrapperView addSubview:_shapeOverlayView];
-
-  [self updateProjection];
-
-  __weak AppleStaticMapProvider *weakSelf = self;
-  if ([wrapperView isKindOfClass:[LuggMapWrapperView class]]) {
-    ((LuggMapWrapperView *)wrapperView).layoutHandler = ^{
-      [weakSelf wrapperDidLayout];
-    };
-  }
-
-  _isMapReady = YES;
-
-  // Start after the current mount pass so map settings props applied right
-  // after this call shape the snapshot options
-  dispatch_async(dispatch_get_main_queue(), ^{
-    [weakSelf startSnapshotIfNeeded];
-  });
-}
-
-- (void)destroy {
-  [_snapshotter cancel];
-  _snapshotter = nil;
-
-  if ([_wrapperView isKindOfClass:[LuggMapWrapperView class]]) {
-    ((LuggMapWrapperView *)_wrapperView).layoutHandler = nil;
-  }
-
-  for (LuggMarkerView *markerView in _markerViews) {
-    markerView.delegate = nil;
-    UIView *iconView = markerView.iconView;
-    if (iconView.superview == _wrapperView) {
-      [iconView removeFromSuperview];
-    }
-    [markerView resetIconViewTransform];
-  }
-  [_markerViews removeAllObjects];
-  for (MKAnnotationView *pin in _defaultMarkerOverlays.objectEnumerator) {
-    [pin removeFromSuperview];
-  }
-  [_defaultMarkerOverlays removeAllObjects];
-
-  for (LuggPolylineView *view in _shapeOverlayView.polylineViews) {
-    view.delegate = nil;
-  }
-  for (LuggPolygonView *view in _shapeOverlayView.polygonViews) {
-    view.delegate = nil;
-  }
-  for (LuggCircleView *view in _shapeOverlayView.circleViews) {
-    view.delegate = nil;
-  }
-  for (LuggGroundOverlayView *view in _shapeOverlayView.groundOverlayViews) {
-    view.delegate = nil;
-  }
-  [_shapeOverlayView removeFromSuperview];
-  _shapeOverlayView = nil;
-
-  [_baseImageView removeFromSuperview];
-  _baseImageView = nil;
-
-  _snapshotDone = NO;
-  _projectionReady = NO;
-  _wrapperView = nil;
-  _isMapReady = NO;
-}
-
-#pragma mark - Snapshot
-
-- (void)updateProjection {
-  CGSize size = _wrapperView.bounds.size;
-  if (size.width <= 0 || size.height <= 0)
-    return;
-
-  _projectedSize = size;
-  _mapRect = LuggStaticFittedMapRect(_coordinate, _zoom, size);
-  _projectionReady = YES;
+#pragma mark - StaticMapProviderBase
 
-  _shapeOverlayView.mapRect = _mapRect;
-  _shapeOverlayView.projectionReady = YES;
-  [_shapeOverlayView setNeedsDisplay];
-
-  for (LuggMarkerView *markerView in _markerViews) {
-    [self positionMarkerOverlay:markerView];
-  }
+- (MKMapRect)mapRectForSize:(CGSize)size {
+  return LuggStaticFittedMapRect(self.coordinate, self.zoom, size);
 }
 
-// A snapshot can't autoresize like a live map; when the wrapper gets its
-// first real size (or resizes later) recompute the projection and
-// (re)render the base image at the new size
-- (void)wrapperDidLayout {
-  CGSize size = _wrapperView.bounds.size;
-  if (size.width <= 0 || size.height <= 0 ||
-      CGSizeEqualToSize(size, _projectedSize))
-    return;
-
-  BOOL hadRender = _snapshotDone || _snapshotter != nil;
-  [self updateProjection];
-
-  if (hadRender) {
-    [_snapshotter cancel];
-    _snapshotter = nil;
-    _snapshotDone = NO;
-    self.cachedBaseImage = nil;
-  }
-  [self startSnapshotIfNeeded];
+- (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 = _wrapperView.traitCollection;
+  UITraitCollection *base = self.wrapperView.traitCollection;
   UIUserInterfaceStyle style;
-  switch (_theme) {
+  switch (self.theme) {
   case LuggMapViewTheme::Dark:
     style = UIUserInterfaceStyleDark;
     break;
@@ -451,19 +92,14 @@ - (UITraitCollection *)snapshotTraitCollection {
   ]];
 }
 
-- (void)startSnapshotIfNeeded {
-  if (_snapshotDone || _snapshotter || !_projectionReady || !_wrapperView)
+- (void)renderBaseMap {
+  if (_snapshotter)
     return;
 
-  if (self.cachedBaseImage) {
-    [self displayBaseImage:self.cachedBaseImage fromCache:YES];
-    return;
-  }
-
   MKMapSnapshotOptions *options = [[MKMapSnapshotOptions alloc] init];
-  options.mapRect = _mapRect;
-  options.size = _projectedSize;
-  options.mapType = LuggMKMapTypeFromMapType(_mapType);
+  options.mapRect = self.mapRect;
+  options.size = self.projectedSize;
+  options.mapType = LuggMKMapTypeFromMapType(self.mapType);
   options.pointOfInterestFilter = LuggPointOfInterestFilter(
       _poiEnabled, _poiFilterMode, _poiFilterCategories);
   options.traitCollection = [self snapshotTraitCollection];
@@ -488,33 +124,13 @@ - (void)startSnapshotIfNeeded {
             }];
 }
 
-- (void)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache {
-  if (!_baseImageView) {
-    _baseImageView = [[UIImageView alloc] initWithFrame:_wrapperView.bounds];
-    _baseImageView.autoresizingMask =
-        UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
-    [_wrapperView insertSubview:_baseImageView atIndex:0];
-  }
-  _baseImageView.image = image;
-  _snapshotDone = YES;
-
-  if (!fromCache) {
-    [_delegate mapProviderDidCaptureStaticImage:image];
-  }
-  [_delegate mapProviderDidFinishStaticSnapshot];
-  [_delegate mapProviderDidReady];
+- (void)cancelBaseRender {
+  [_snapshotter cancel];
+  _snapshotter = nil;
 }
 
 #pragma mark - Props
 
-- (void)setMapType:(LuggMapViewMapType)mapType {
-  _mapType = mapType;
-}
-
-- (void)setTheme:(LuggMapViewTheme)theme {
-  _theme = theme;
-}
-
 - (void)setPoiEnabled:(BOOL)enabled {
   _poiEnabled = enabled;
 }
@@ -527,294 +143,4 @@ - (void)setPoiFilterCategories:(NSArray<NSString *> *)categories {
   _poiFilterCategories = categories;
 }
 
-// Interaction and camera props don't apply to a static snapshot
-- (void)setInsetAdjustment:(LuggMapViewInsetAdjustment)insetAdjustment {
-}
-- (void)setZoomEnabled:(BOOL)enabled {
-}
-- (void)setScrollEnabled:(BOOL)enabled {
-}
-- (void)setRotateEnabled:(BOOL)enabled {
-}
-- (void)setPitchEnabled:(BOOL)enabled {
-}
-- (void)setCompassEnabled:(BOOL)enabled {
-}
-- (void)setUserLocationEnabled:(BOOL)enabled {
-}
-- (void)setMinZoom:(double)minZoom {
-}
-- (void)setMaxZoom:(double)maxZoom {
-}
-- (void)setEdgeInsets:(UIEdgeInsets)edgeInsets
-        oldEdgeInsets:(UIEdgeInsets)oldEdgeInsets {
-}
-- (void)setEdgeInsets:(UIEdgeInsets)edgeInsets
-        oldEdgeInsets:(UIEdgeInsets)oldEdgeInsets
-             duration:(double)duration {
-}
-
-#pragma mark - Markers
-
-// Markers are live views over the snapshot (like Android lite mode's live
-// markers), so async content such as remote images shows up when it loads
-
-- (void)addMarkerView:(LuggMarkerView *)markerView {
-  markerView.delegate = self;
-  if (![_markerViews containsObject:markerView]) {
-    [_markerViews addObject:markerView];
-  }
-  [self syncMarkerView:markerView];
-}
-
-- (void)removeMarkerView:(LuggMarkerView *)markerView {
-  markerView.delegate = nil;
-  [_markerViews removeObject:markerView];
-
-  MKAnnotationView *pin = [_defaultMarkerOverlays objectForKey:markerView];
-  if (pin) {
-    [pin removeFromSuperview];
-    [_defaultMarkerOverlays removeObjectForKey:markerView];
-  }
-
-  UIView *iconView = markerView.iconView;
-  if (iconView.superview == _wrapperView) {
-    [iconView removeFromSuperview];
-  }
-  [markerView resetIconViewTransform];
-}
-
-- (void)syncMarkerView:(LuggMarkerView *)markerView {
-  if (!_wrapperView)
-    return;
-
-  MKAnnotationView *pin = [_defaultMarkerOverlays objectForKey:markerView];
-
-  if (markerView.hasCustomView) {
-    if (pin) {
-      [pin removeFromSuperview];
-      [_defaultMarkerOverlays removeObjectForKey:markerView];
-    }
-    UIView *iconView = markerView.iconView;
-    if (iconView.superview != _wrapperView) {
-      [iconView removeFromSuperview];
-      iconView.userInteractionEnabled = NO;
-      [_wrapperView addSubview:iconView];
-    }
-  } else {
-    UIView *iconView = markerView.iconView;
-    if (iconView.superview == _wrapperView) {
-      [iconView removeFromSuperview];
-      [markerView resetIconViewTransform];
-    }
-    if (!pin) {
-      pin = [[LuggMarkerAnnotationView alloc] initWithAnnotation:nil
-                                                 reuseIdentifier:nil];
-      pin.userInteractionEnabled = NO;
-      pin.bounds =
-          CGRectMake(0, 0, kDefaultMarkerSize.width, kDefaultMarkerSize.height);
-      [_wrapperView addSubview:pin];
-      [_defaultMarkerOverlays setObject:pin forKey:markerView];
-    }
-  }
-
-  [self positionMarkerOverlay:markerView];
-}
-
-- (void)positionMarkerOverlay:(LuggMarkerView *)markerView {
-  if (!_projectionReady)
-    return;
-
-  CGPoint point = LuggStaticPointForCoordinate(_mapRect, _projectedSize,
-                                               markerView.coordinate);
-
-  if (markerView.hasCustomView) {
-    UIView *iconView = markerView.iconView;
-    CGSize size = iconView.bounds.size;
-    if (size.width <= 0 || size.height <= 0) {
-      // Not laid out yet; markerViewDidLayout re-runs this
-      return;
-    }
-    CGFloat scale = markerView.scale;
-    CGFloat radians = markerView.rotate * M_PI / 180.0;
-    iconView.layer.anchorPoint = markerView.anchor;
-    iconView.transform =
-        CGAffineTransformConcat(CGAffineTransformMakeScale(scale, scale),
-                                CGAffineTransformMakeRotation(radians));
-    // center positions the layer's anchorPoint, so the marker's anchor
-    // lands exactly on the projected coordinate
-    iconView.center = point;
-    iconView.layer.zPosition = markerView.zIndex;
-  } else {
-    MKAnnotationView *pin = [_defaultMarkerOverlays objectForKey:markerView];
-    pin.layer.anchorPoint = CGPointMake(0.5, 1.0);
-    pin.center = point;
-    pin.layer.zPosition = markerView.zIndex;
-  }
-}
-
-#pragma mark - LuggMarkerViewDelegate
-
-- (void)markerViewDidLayout:(LuggMarkerView *)markerView {
-  [self syncMarkerView:markerView];
-}
-
-- (void)markerViewDidUpdate:(LuggMarkerView *)markerView {
-  [self syncMarkerView:markerView];
-}
-
-#pragma mark - Shapes
-
-- (void)addPolylineView:(LuggPolylineView *)polylineView {
-  polylineView.delegate = self;
-  if (![_shapeOverlayView.polylineViews containsObject:polylineView]) {
-    [_shapeOverlayView.polylineViews addObject:polylineView];
-  }
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)removePolylineView:(LuggPolylineView *)polylineView {
-  polylineView.delegate = nil;
-  [_shapeOverlayView.polylineViews removeObject:polylineView];
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)syncPolylineView:(LuggPolylineView *)polylineView {
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)polylineViewDidUpdate:(LuggPolylineView *)polylineView {
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)addPolygonView:(LuggPolygonView *)polygonView {
-  polygonView.delegate = self;
-  if (![_shapeOverlayView.polygonViews containsObject:polygonView]) {
-    [_shapeOverlayView.polygonViews addObject:polygonView];
-  }
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)removePolygonView:(LuggPolygonView *)polygonView {
-  polygonView.delegate = nil;
-  [_shapeOverlayView.polygonViews removeObject:polygonView];
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)syncPolygonView:(LuggPolygonView *)polygonView {
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)polygonViewDidUpdate:(LuggPolygonView *)polygonView {
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)addCircleView:(LuggCircleView *)circleView {
-  circleView.delegate = self;
-  if (![_shapeOverlayView.circleViews containsObject:circleView]) {
-    [_shapeOverlayView.circleViews addObject:circleView];
-  }
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)removeCircleView:(LuggCircleView *)circleView {
-  circleView.delegate = nil;
-  [_shapeOverlayView.circleViews removeObject:circleView];
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)syncCircleView:(LuggCircleView *)circleView {
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)circleViewDidUpdate:(LuggCircleView *)circleView {
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)addGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
-  groundOverlayView.delegate = self;
-  if (![_shapeOverlayView.groundOverlayViews
-          containsObject:groundOverlayView]) {
-    [_shapeOverlayView.groundOverlayViews addObject:groundOverlayView];
-  }
-  [self loadGroundOverlayImage:groundOverlayView];
-}
-
-- (void)removeGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
-  groundOverlayView.delegate = nil;
-  [_shapeOverlayView.groundOverlayViews removeObject:groundOverlayView];
-  [_shapeOverlayView.groundOverlayImages removeObjectForKey:groundOverlayView];
-  [_shapeOverlayView setNeedsDisplay];
-}
-
-- (void)syncGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
-  [self loadGroundOverlayImage:groundOverlayView];
-}
-
-- (void)groundOverlayViewDidUpdate:(LuggGroundOverlayView *)groundOverlayView {
-  [self loadGroundOverlayImage:groundOverlayView];
-}
-
-- (void)loadGroundOverlayImage:(LuggGroundOverlayView *)groundOverlayView {
-  NSURL *url = [NSURL URLWithString:groundOverlayView.imageUri];
-  if (!url)
-    return;
-
-  __weak AppleStaticMapProvider *weakSelf = self;
-  __weak LuggGroundOverlayView *weakOverlayView = groundOverlayView;
-  dispatch_async(
-      dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
-        NSData *data = [NSData dataWithContentsOfURL:url];
-        UIImage *image = data ? [UIImage imageWithData:data] : nil;
-        dispatch_async(dispatch_get_main_queue(), ^{
-          AppleStaticMapProvider *strongSelf = weakSelf;
-          LuggGroundOverlayView *overlayView = weakOverlayView;
-          if (!strongSelf || !overlayView || !image)
-            return;
-          LuggStaticShapeOverlayView *shapeView = strongSelf->_shapeOverlayView;
-          if (![shapeView.groundOverlayViews containsObject:overlayView])
-            return;
-          [shapeView.groundOverlayImages setObject:image forKey:overlayView];
-          [shapeView setNeedsDisplay];
-        });
-      });
-}
-
-// Tile overlays need a live map to fetch and compose tiles; unsupported on
-// static Apple maps
-- (void)addTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
-}
-- (void)removeTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
-}
-- (void)syncTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
-}
-
-#pragma mark - Lifecycle
-
-- (void)pauseAnimations {
-}
-
-- (void)resumeAnimations {
-  // Retry a failed or cancelled snapshot (e.g. device back online)
-  [self startSnapshotIfNeeded];
-}
-
-#pragma mark - Commands
-
-// Static maps render once with their initial camera
-
-- (void)moveCamera:(double)latitude
-         longitude:(double)longitude
-              zoom:(double)zoom
-          duration:(double)duration {
-}
-
-- (void)fitCoordinates:(NSArray *)coordinates
-         edgeInsetsTop:(double)edgeInsetsTop
-        edgeInsetsLeft:(double)edgeInsetsLeft
-      edgeInsetsBottom:(double)edgeInsetsBottom
-       edgeInsetsRight:(double)edgeInsetsRight
-              duration:(double)duration {
-}
-
 @end
diff --git a/ios/core/GoogleMapProvider.h b/ios/core/GoogleMapProvider.h
index 96e36bd..6dadf2b 100644
--- a/ios/core/GoogleMapProvider.h
+++ b/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;
diff --git a/ios/core/GoogleMapProvider.mm b/ios/core/GoogleMapProvider.mm
index 571b83a..9efd849 100644
--- a/ios/core/GoogleMapProvider.mm
+++ b/ios/core/GoogleMapProvider.mm
@@ -12,62 +12,42 @@
 #import "../LuggPolygonView.h"
 #import "../LuggPolylineView.h"
 #import "../LuggTileOverlayView.h"
-#import "../extensions/UIView+Snapshot.h"
 #import "GMSPolylineAnimator.h"
 #import "PolylineAnimatorBase.h"
 
 static NSString *const kDemoMapId = @"DEMO_MAP_ID";
 
-// 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 = 3;
-
-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;
+GMSMapID *LuggGMSMapIDFromString(NSString *_Nullable mapId) {
+  if (mapId.length == 0 || [mapId isEqualToString:kDemoMapId]) {
+    return [GMSMapID demoMapID];
+  }
+  return [GMSMapID mapIDWithIdentifier:mapId];
 }
 
-static GMSMapView *_Nullable DequeueStaticMapView(NSString *mapId) {
-  NSMutableArray<GMSMapView *> *views = StaticMapViewPool()[mapId];
-  GMSMapView *mapView = views.lastObject;
-  [views removeLastObject];
-  return mapView;
+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;
+  }
 }
 
-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;
+UIUserInterfaceStyle LuggInterfaceStyleFromTheme(
+    facebook::react::LuggMapViewTheme theme) {
+  switch (theme) {
+  case LuggMapViewTheme::Dark:
+    return UIUserInterfaceStyleDark;
+  case LuggMapViewTheme::Light:
+    return UIUserInterfaceStyleLight;
+  default:
+    return UIUserInterfaceStyleUnspecified;
   }
-  if (views.count >= kStaticMapViewPoolCapacity)
-    return;
-
-  // Reset state that a fresh provider won't reapply (its prop setters
-  // no-op on default values)
-  [mapView clear];
-  mapView.selectedMarker = nil;
-  mapView.myLocationEnabled = NO;
-  mapView.padding = UIEdgeInsetsZero;
-  [mapView setMinZoom:kGMSMinZoomLevel maxZoom:kGMSMaxZoomLevel];
-  [views addObject:mapView];
 }
 
 @interface GoogleMapProvider () <
@@ -81,10 +61,6 @@ @implementation GoogleMapProvider {
   GMSMapView *_mapView;
   BOOL _isMapReady;
   BOOL _isDragging;
-  UIImageView *_staticSnapshotView;
-  BOOL _needsStaticSnapshot;
-  BOOL _staticSwapScheduled;
-  BOOL _tilesRendered;
   LuggMapViewTheme _theme;
   UIEdgeInsets _edgeInsets;
   NSMutableArray<LuggMarkerView *> *_pendingMarkerViews;
@@ -147,47 +123,23 @@ - (void)initializeMapInView:(UIView *)wrapperView
   if (_mapView)
     return;
 
-  _tilesRendered = NO;
-
-  GMSMapView *pooledMapView =
-      _staticMode ? DequeueStaticMapView(_mapId) : nil;
-  if (pooledMapView) {
-    _mapView = pooledMapView;
-    _mapView.frame = wrapperView.bounds;
-    [_mapView moveCamera:[GMSCameraUpdate setTarget:coordinate
-                                               zoom:(float)zoom]];
-  } else {
-    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
-                                         zoom:zoom];
+  GMSCameraPosition *camera =
+      [GMSCameraPosition cameraWithLatitude:coordinate.latitude
+                                  longitude:coordinate.longitude
+                                       zoom:zoom];
 
-    GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
-    options.frame = wrapperView.bounds;
-    options.camera = camera;
-    options.mapID = gmsMapId;
-
-    _mapView = [[GMSMapView alloc] initWithOptions:options];
-  }
+  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
+  options.frame = wrapperView.bounds;
+  options.camera = camera;
+  options.mapID = LuggGMSMapIDFromString(_mapId);
 
+  _mapView = [[GMSMapView alloc] initWithOptions:options];
   _mapView.autoresizingMask =
       UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
   _mapView.delegate = self;
   _mapView.paddingAdjustmentBehavior =
       kGMSMapViewPaddingAdjustmentBehaviorNever;
 
-  if (_staticMode) {
-    _mapView.userInteractionEnabled = NO;
-    _mapView.preferredFrameRate = kGMSFrameRateConservative;
-  }
-
   _wrapperView = wrapperView;
   [wrapperView addSubview:_mapView];
 
@@ -205,9 +157,6 @@ - (void)initializeMapInView:(UIView *)wrapperView
 }
 
 - (void)destroy {
-  [_staticSnapshotView removeFromSuperview];
-  _staticSnapshotView = nil;
-  _needsStaticSnapshot = NO;
   [self stopEdgeInsetsAnimation];
   [_pendingMarkerViews removeAllObjects];
   [_pendingPolylineViews removeAllObjects];
@@ -230,66 +179,10 @@ - (void)destroyMapView {
 
   _mapView.delegate = nil;
   [_mapView removeFromSuperview];
-  if (_staticMode) {
-    EnqueueStaticMapView(_mapId, _mapView);
-  } else {
-    [_mapView clear];
-  }
+  [_mapView clear];
   _mapView = nil;
 }
 
-// Static mode: once the map is fully rendered, swap the live map with a
-// snapshot image and release the map view. The snapshot render and map
-// teardown are expensive, so they run outside scroll tracking; the live
-// map keeps displaying until then.
-- (void)swapMapWithStaticImage {
-  if (_staticSnapshotView || _staticSwapScheduled || !_mapView)
-    return;
-
-  // Re-arm instead of capturing a half-loaded map; the next
-  // didFinishTileRendering re-triggers the swap
-  if (!_mapView.window || !_tilesRendered) {
-    _needsStaticSnapshot = YES;
-    return;
-  }
-  _needsStaticSnapshot = NO;
-
-  _staticSwapScheduled = YES;
-  [[NSRunLoop mainRunLoop] performInModes:@[ NSDefaultRunLoopMode ]
-                                    block:^{
-                                      self->_staticSwapScheduled = NO;
-                                      [self performStaticSwap];
-                                    }];
-}
-
-- (void)performStaticSwap {
-  if (_staticSnapshotView || !_mapView)
-    return;
-
-  // Tiles can invalidate between scheduling and this runloop pass
-  if (!_mapView.window || !_tilesRendered) {
-    _needsStaticSnapshot = YES;
-    return;
-  }
-
-  UIImageView *imageView = [_mapView lugg_snapshotImageView];
-  if (!imageView) {
-    // Zero-size bounds; re-arm so resumeAnimations retries instead of
-    // silently keeping the live map forever
-    _needsStaticSnapshot = YES;
-    return;
-  }
-
-  _staticSnapshotView = imageView;
-  [_wrapperView insertSubview:imageView aboveSubview:_mapView];
-
-  [self pauseAnimations];
-  [self destroyMapView];
-
-  [_delegate mapProviderDidCaptureStaticImage:imageView.image];
-  [_delegate mapProviderDidFinishStaticSnapshot];
-}
-
 #pragma mark - Props
 
 - (void)setZoomEnabled:(BOOL)enabled {
@@ -333,23 +226,7 @@ - (void)setPoiFilterCategories:(NSArray<NSString *> *)categories {
 }
 
 - (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 {
@@ -358,20 +235,7 @@ - (void)setTheme:(LuggMapViewTheme)theme {
 }
 
 - (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 {
@@ -449,25 +313,6 @@ - (void)stopEdgeInsetsAnimation {
 
 #pragma mark - GMSMapViewDelegate
 
-- (void)mapViewDidStartTileRendering:(GMSMapView *)mapView {
-  _tilesRendered = NO;
-}
-
-- (void)mapViewDidFinishTileRendering:(GMSMapView *)mapView {
-  _tilesRendered = YES;
-  if (_staticMode && _needsStaticSnapshot) {
-    [self swapMapWithStaticImage];
-  }
-}
-
-- (void)mapViewSnapshotReady:(GMSMapView *)mapView {
-  // Stable per the SDK: tiles loaded, labels and overlays rendered
-  _tilesRendered = YES;
-  if (_staticMode) {
-    [self swapMapWithStaticImage];
-  }
-}
-
 - (void)mapView:(GMSMapView *)mapView willMove:(BOOL)gesture {
   _isDragging = gesture;
   if (_isDragging) {
@@ -905,7 +750,7 @@ - (void)syncPolylineView:(LuggPolylineView *)polylineView {
     animator.coordinates = polylineView.coordinates;
     animator.strokeColors = polylineView.strokeColors;
     animator.animatedOptions = polylineView.animatedOptions;
-    animator.animated = polylineView.animated && !_staticMode;
+    animator.animated = polylineView.animated;
     [animator update];
   }
 }
@@ -935,8 +780,7 @@ - (void)addPolylineViewToMap:(LuggPolylineView *)polylineView {
   animator.coordinates = polylineView.coordinates;
   animator.strokeColors = polylineView.strokeColors;
   animator.animatedOptions = polylineView.animatedOptions;
-  // Static maps snapshot an arbitrary frame; render the full polyline
-  animator.animated = polylineView.animated && !_staticMode;
+  animator.animated = polylineView.animated;
   [animator update];
 
   [_polylineAnimators setObject:animator forKey:polylineView];
@@ -1276,10 +1120,6 @@ - (void)pauseAnimations {
 }
 
 - (void)resumeAnimations {
-  if (_needsStaticSnapshot) {
-    [self swapMapWithStaticImage];
-    return;
-  }
   for (GMSPolylineAnimator *animator in _polylineAnimators.objectEnumerator) {
     [animator resume];
   }
diff --git a/ios/core/GoogleStaticMapProvider.h b/ios/core/GoogleStaticMapProvider.h
new file mode 100644
index 0000000..a200f96
--- /dev/null
+++ b/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. Warmups are paced by LuggStaticMapWarmupQueue so they
+ * never compete with scroll gestures; markers and shapes are overlay views
+ * (shared with Apple static maps) that appear immediately, without waiting
+ * for a warmup slot.
+ */
+@interface GoogleStaticMapProvider : StaticMapProviderBase <GMSMapViewDelegate>
+
+@property(nonatomic, copy, nullable) NSString *mapId;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/core/GoogleStaticMapProvider.mm b/ios/core/GoogleStaticMapProvider.mm
new file mode 100644
index 0000000..d868a1f
--- /dev/null
+++ b/ios/core/GoogleStaticMapProvider.mm
@@ -0,0 +1,232 @@
+#import "GoogleStaticMapProvider.h"
+
+#import "../extensions/UIView+Snapshot.h"
+#import "GoogleMapProvider.h"
+#import "LuggStaticMapWarmupQueue.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 = 3;
+
+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 _waitingForWarmupSlot;
+  BOOL _holdingWarmupSlot;
+  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;
+  }
+  if (_waitingForWarmupSlot)
+    return;
+
+  _waitingForWarmupSlot = YES;
+  __weak GoogleStaticMapProvider *weakSelf = self;
+  [[LuggStaticMapWarmupQueue sharedQueue]
+      requestSlotForOwner:self
+               completion:^{
+                 GoogleStaticMapProvider *strongSelf = weakSelf;
+                 if (!strongSelf)
+                   return;
+                 strongSelf->_waitingForWarmupSlot = NO;
+                 strongSelf->_holdingWarmupSlot = YES;
+                 [strongSelf startWarmup];
+               }];
+}
+
+- (void)cancelBaseRender {
+  if (_waitingForWarmupSlot) {
+    [[LuggStaticMapWarmupQueue sharedQueue] cancelOwner:self];
+    _waitingForWarmupSlot = NO;
+  }
+  [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) {
+    [self releaseWarmupSlot];
+    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;
+  mapView.mapType = LuggGMSMapTypeFromMapType(self.mapType);
+  mapView.overrideUserInterfaceStyle = LuggInterfaceStyleFromTheme(self.theme);
+
+  _warmupMapView = mapView;
+  [wrapperView insertSubview:mapView atIndex:0];
+}
+
+- (void)destroyWarmupMapView {
+  if (_warmupMapView) {
+    _warmupMapView.delegate = nil;
+    [_warmupMapView removeFromSuperview];
+    EnqueueStaticMapView([self poolKey], _warmupMapView);
+    _warmupMapView = nil;
+  }
+  [self releaseWarmupSlot];
+}
+
+- (void)releaseWarmupSlot {
+  if (_holdingWarmupSlot) {
+    _holdingWarmupSlot = NO;
+    [[LuggStaticMapWarmupQueue sharedQueue] releaseSlotForOwner:self];
+  }
+}
+
+// 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;
+  [self scheduleSwap];
+}
+
+- (void)mapViewSnapshotReady:(GMSMapView *)mapView {
+  // Stable per the SDK: tiles loaded, labels and overlays rendered
+  _tilesRendered = YES;
+  [self scheduleSwap];
+}
+
+@end
diff --git a/ios/core/LuggStaticMapWarmupQueue.h b/ios/core/LuggStaticMapWarmupQueue.h
index 8353597..f56e36b 100644
--- a/ios/core/LuggStaticMapWarmupQueue.h
+++ b/ios/core/LuggStaticMapWarmupQueue.h
@@ -3,11 +3,12 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /**
- * Serializes static map warmup so only a few live maps exist at a time.
- * Google static maps briefly need a live map view to render their snapshot
- * (the SDK has no async snapshotter); without throttling, a list mounting
- * many rows creates them all at once and stalls the main thread. Apple
- * static maps render through MKMapSnapshotter and don't use this queue.
+ * Serializes static map base warmup so only a few live maps exist at a
+ * time. Google static maps briefly need a live map view to render their
+ * base image (the SDK has no async snapshotter); without throttling, a
+ * list mounting many rows creates them all at once and stalls the main
+ * thread. Apple static maps render through MKMapSnapshotter and don't use
+ * this queue.
  */
 @interface LuggStaticMapWarmupQueue : NSObject
 
diff --git a/ios/core/StaticMapProviderBase.h b/ios/core/StaticMapProviderBase.h
new file mode 100644
index 0000000..bf459af
--- /dev/null
+++ b/ios/core/StaticMapProviderBase.h
@@ -0,0 +1,63 @@
+#import "MapProviderDelegate.h"
+#import <MapKit/MapKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Projects a coordinate into view points for a static map covering mapRect
+CGPoint LuggStaticPointForCoordinate(MKMapRect mapRect, CGSize size,
+                                     CLLocationCoordinate2D coordinate);
+
+/**
+ * Shared behavior for static (non-interactive) map providers - the iOS
+ * equivalent of Android's lite mode. The base map renders asynchronously
+ * (subclass-specific), so static maps keep loading while the user scrolls
+ * without blocking the main thread.
+ *
+ * Markers are live views positioned over the base map via a mercator
+ * projection (mirroring Android's live markers on lite maps), so async
+ * marker content (e.g. remote images) appears when it loads - immediately,
+ * without waiting for the base map. Polylines, polygons, circles and
+ * ground overlays are drawn into a single CoreGraphics overlay view.
+ * Tile overlays are not supported.
+ */
+@interface StaticMapProviderBase : NSObject <MapProvider>
+
+/// Previously captured base map for the same cache key; when set, the base
+/// render is skipped and the image is shown immediately.
+@property(nonatomic, strong, nullable) UIImage *cachedBaseImage;
+
+// State for subclasses
+@property(nonatomic, readonly, nullable) UIView *wrapperView;
+@property(nonatomic, readonly) CLLocationCoordinate2D coordinate;
+@property(nonatomic, readonly) double zoom;
+@property(nonatomic, readonly) MKMapRect mapRect;
+@property(nonatomic, readonly) CGSize projectedSize;
+@property(nonatomic, readonly) BOOL projectionReady;
+@property(nonatomic, readonly) facebook::react::LuggMapViewMapType mapType;
+@property(nonatomic, readonly) facebook::react::LuggMapViewTheme theme;
+
+/// Shows the base image below the overlays, emits the static snapshot
+/// delegate callbacks and marks the base render done.
+- (void)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache;
+
+#pragma mark - Subclass hooks
+
+/// The map rect the base render covers for the given view size; must match
+/// the SDK's camera framing so overlays align with the base map exactly.
+- (MKMapRect)mapRectForSize:(CGSize)size;
+
+/// Overlay view shown for markers without a custom child view.
+- (UIView *)newDefaultMarkerOverlayView;
+
+/// Starts rendering the base map for the current projection (guaranteed
+/// projectionReady, no cached image). Called after mount (once initial
+/// props have applied), after a resize, and from resumeAnimations to retry
+/// a failed or cancelled render (e.g. device back online).
+- (void)renderBaseMap;
+
+/// Cancels an in-flight base render (resize or teardown).
+- (void)cancelBaseRender;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/core/StaticMapProviderBase.mm b/ios/core/StaticMapProviderBase.mm
new file mode 100644
index 0000000..a902c2a
--- /dev/null
+++ b/ios/core/StaticMapProviderBase.mm
@@ -0,0 +1,725 @@
+#import "StaticMapProviderBase.h"
+
+using facebook::react::LuggMapViewInsetAdjustment;
+using facebook::react::LuggMapViewMapType;
+using facebook::react::LuggMapViewPoiFilterMode;
+using facebook::react::LuggMapViewTheme;
+
+#import "../LuggCircleView.h"
+#import "../LuggGroundOverlayView.h"
+#import "../LuggMapWrapperView.h"
+#import "../LuggMarkerView.h"
+#import "../LuggPolygonView.h"
+#import "../LuggPolylineView.h"
+
+#pragma mark - Projection
+
+CGPoint LuggStaticPointForCoordinate(MKMapRect mapRect, CGSize size,
+                                     CLLocationCoordinate2D coordinate) {
+  MKMapPoint point = MKMapPointForCoordinate(coordinate);
+  return CGPointMake(
+      (point.x - mapRect.origin.x) / mapRect.size.width * size.width,
+      (point.y - mapRect.origin.y) / mapRect.size.height * size.height);
+}
+
+#pragma mark - Shape overlay
+
+// Draws polylines, polygons, circles and ground overlays over the base
+// map with CoreGraphics; the base render is map tiles only
+@interface LuggStaticShapeOverlayView : UIView
+@property(nonatomic, assign) MKMapRect mapRect;
+@property(nonatomic, assign) BOOL projectionReady;
+@property(nonatomic, strong) NSMutableArray<LuggPolylineView *> *polylineViews;
+@property(nonatomic, strong) NSMutableArray<LuggPolygonView *> *polygonViews;
+@property(nonatomic, strong) NSMutableArray<LuggCircleView *> *circleViews;
+@property(nonatomic, strong)
+    NSMutableArray<LuggGroundOverlayView *> *groundOverlayViews;
+@property(nonatomic, strong)
+    NSMapTable<LuggGroundOverlayView *, UIImage *> *groundOverlayImages;
+@end
+
+@implementation LuggStaticShapeOverlayView
+
+- (instancetype)initWithFrame:(CGRect)frame {
+  if (self = [super initWithFrame:frame]) {
+    self.opaque = NO;
+    self.backgroundColor = UIColor.clearColor;
+    self.userInteractionEnabled = NO;
+    self.contentMode = UIViewContentModeRedraw;
+    _polylineViews = [NSMutableArray array];
+    _polygonViews = [NSMutableArray array];
+    _circleViews = [NSMutableArray array];
+    _groundOverlayViews = [NSMutableArray array];
+    _groundOverlayImages = [NSMapTable weakToStrongObjectsMapTable];
+  }
+  return self;
+}
+
+static NSInteger shapeZIndex(UIView *shape) {
+  if ([shape isKindOfClass:[LuggPolylineView class]])
+    return ((LuggPolylineView *)shape).zIndex;
+  if ([shape isKindOfClass:[LuggPolygonView class]])
+    return ((LuggPolygonView *)shape).zIndex;
+  if ([shape isKindOfClass:[LuggCircleView class]])
+    return ((LuggCircleView *)shape).zIndex;
+  if ([shape isKindOfClass:[LuggGroundOverlayView class]])
+    return ((LuggGroundOverlayView *)shape).zIndex;
+  return 0;
+}
+
+- (CGPoint)pointForCoordinate:(CLLocationCoordinate2D)coordinate {
+  return LuggStaticPointForCoordinate(_mapRect, self.bounds.size, coordinate);
+}
+
+- (void)addPath:(CGContextRef)context
+           ring:(NSArray<CLLocation *> *)coordinates {
+  for (NSUInteger i = 0; i < coordinates.count; i++) {
+    CGPoint point = [self pointForCoordinate:coordinates[i].coordinate];
+    if (i == 0) {
+      CGContextMoveToPoint(context, point.x, point.y);
+    } else {
+      CGContextAddLineToPoint(context, point.x, point.y);
+    }
+  }
+}
+
+- (void)drawPolyline:(LuggPolylineView *)polylineView
+           inContext:(CGContextRef)context {
+  NSArray<CLLocation *> *coordinates = polylineView.coordinates;
+  UIColor *color = polylineView.strokeColors.firstObject;
+  if (coordinates.count < 2 || !color || polylineView.strokeWidth <= 0)
+    return;
+
+  CGContextSaveGState(context);
+  [self addPath:context ring:coordinates];
+  CGContextSetLineWidth(context, polylineView.strokeWidth);
+  CGContextSetLineCap(context, kCGLineCapRound);
+  CGContextSetLineJoin(context, kCGLineJoinRound);
+  CGContextSetStrokeColorWithColor(context, color.CGColor);
+  CGContextStrokePath(context);
+  CGContextRestoreGState(context);
+}
+
+- (void)drawPolygon:(LuggPolygonView *)polygonView
+          inContext:(CGContextRef)context {
+  NSArray<CLLocation *> *coordinates = polygonView.coordinates;
+  if (coordinates.count < 3)
+    return;
+
+  CGContextSaveGState(context);
+
+  if (polygonView.fillColor) {
+    [self addPath:context ring:coordinates];
+    CGContextClosePath(context);
+    for (NSArray<CLLocation *> *hole in polygonView.holes) {
+      [self addPath:context ring:hole];
+      CGContextClosePath(context);
+    }
+    CGContextSetFillColorWithColor(context, polygonView.fillColor.CGColor);
+    CGContextEOFillPath(context);
+  }
+
+  if (polygonView.strokeColor && polygonView.strokeWidth > 0) {
+    [self addPath:context ring:coordinates];
+    CGContextClosePath(context);
+    for (NSArray<CLLocation *> *hole in polygonView.holes) {
+      [self addPath:context ring:hole];
+      CGContextClosePath(context);
+    }
+    CGContextSetLineWidth(context, polygonView.strokeWidth);
+    CGContextSetLineJoin(context, kCGLineJoinRound);
+    CGContextSetStrokeColorWithColor(context, polygonView.strokeColor.CGColor);
+    CGContextStrokePath(context);
+  }
+
+  CGContextRestoreGState(context);
+}
+
+- (void)drawCircle:(LuggCircleView *)circleView
+         inContext:(CGContextRef)context {
+  if (circleView.radius <= 0)
+    return;
+
+  CGPoint center = [self pointForCoordinate:circleView.center];
+  double pointsPerMapPoint = self.bounds.size.width / _mapRect.size.width;
+  double radius = circleView.radius *
+                  MKMapPointsPerMeterAtLatitude(circleView.center.latitude) *
+                  pointsPerMapPoint;
+  CGRect ellipse =
+      CGRectMake(center.x - radius, center.y - radius, radius * 2, radius * 2);
+
+  CGContextSaveGState(context);
+  if (circleView.fillColor) {
+    CGContextSetFillColorWithColor(context, circleView.fillColor.CGColor);
+    CGContextFillEllipseInRect(context, ellipse);
+  }
+  if (circleView.strokeColor && circleView.strokeWidth > 0) {
+    CGContextSetLineWidth(context, circleView.strokeWidth);
+    CGContextSetStrokeColorWithColor(context, circleView.strokeColor.CGColor);
+    CGContextStrokeEllipseInRect(context, ellipse);
+  }
+  CGContextRestoreGState(context);
+}
+
+- (void)drawGroundOverlay:(LuggGroundOverlayView *)groundOverlayView {
+  UIImage *image = [_groundOverlayImages objectForKey:groundOverlayView];
+  if (!image)
+    return;
+
+  CGPoint topLeft =
+      [self pointForCoordinate:CLLocationCoordinate2DMake(
+                                   groundOverlayView.northeast.latitude,
+                                   groundOverlayView.southwest.longitude)];
+  CGPoint bottomRight =
+      [self pointForCoordinate:CLLocationCoordinate2DMake(
+                                   groundOverlayView.southwest.latitude,
+                                   groundOverlayView.northeast.longitude)];
+  CGRect rect = CGRectMake(topLeft.x, topLeft.y, bottomRight.x - topLeft.x,
+                           bottomRight.y - topLeft.y);
+  [image drawInRect:rect
+          blendMode:kCGBlendModeNormal
+              alpha:groundOverlayView.opacity];
+}
+
+- (void)drawRect:(CGRect)rect {
+  if (!_projectionReady)
+    return;
+
+  CGContextRef context = UIGraphicsGetCurrentContext();
+  if (!context)
+    return;
+
+  NSMutableArray<UIView *> *shapes = [NSMutableArray array];
+  [shapes addObjectsFromArray:_groundOverlayViews];
+  [shapes addObjectsFromArray:_polygonViews];
+  [shapes addObjectsFromArray:_circleViews];
+  [shapes addObjectsFromArray:_polylineViews];
+  NSArray<UIView *> *ordered =
+      [shapes sortedArrayWithOptions:NSSortStable
+                     usingComparator:^NSComparisonResult(UIView *a, UIView *b) {
+                       NSInteger za = shapeZIndex(a), zb = shapeZIndex(b);
+                       if (za < zb)
+                         return NSOrderedAscending;
+                       if (za > zb)
+                         return NSOrderedDescending;
+                       return NSOrderedSame;
+                     }];
+
+  for (UIView *shape in ordered) {
+    if ([shape isKindOfClass:[LuggGroundOverlayView class]]) {
+      [self drawGroundOverlay:(LuggGroundOverlayView *)shape];
+    } else if ([shape isKindOfClass:[LuggPolygonView class]]) {
+      [self drawPolygon:(LuggPolygonView *)shape inContext:context];
+    } else if ([shape isKindOfClass:[LuggCircleView class]]) {
+      [self drawCircle:(LuggCircleView *)shape inContext:context];
+    } else if ([shape isKindOfClass:[LuggPolylineView class]]) {
+      [self drawPolyline:(LuggPolylineView *)shape inContext:context];
+    }
+  }
+}
+
+@end
+
+#pragma mark - Provider base
+
+@interface StaticMapProviderBase () <
+    LuggMarkerViewDelegate, LuggPolylineViewDelegate, LuggPolygonViewDelegate,
+    LuggCircleViewDelegate, LuggGroundOverlayViewDelegate>
+@end
+
+@implementation StaticMapProviderBase {
+  BOOL _isMapReady;
+  BOOL _baseRenderDone;
+
+  UIImageView *_baseImageView;
+  LuggStaticShapeOverlayView *_shapeOverlayView;
+  NSMutableArray<LuggMarkerView *> *_markerViews;
+  NSMapTable<LuggMarkerView *, UIView *> *_defaultMarkerOverlays;
+}
+
+@synthesize delegate = _delegate;
+@synthesize staticMode = _staticMode;
+
+- (instancetype)init {
+  if (self = [super init]) {
+    _markerViews = [NSMutableArray array];
+    _defaultMarkerOverlays = [NSMapTable weakToStrongObjectsMapTable];
+    _mapType = LuggMapViewMapType::Standard;
+    _theme = LuggMapViewTheme::System;
+  }
+  return self;
+}
+
+- (BOOL)isMapReady {
+  return _isMapReady;
+}
+
+#pragma mark - MapProvider
+
+- (void)initializeMapInView:(UIView *)wrapperView
+          initialCoordinate:(CLLocationCoordinate2D)coordinate
+                initialZoom:(double)zoom {
+  if (_wrapperView)
+    return;
+
+  _wrapperView = wrapperView;
+  _coordinate = coordinate;
+  _zoom = zoom;
+
+  _shapeOverlayView =
+      [[LuggStaticShapeOverlayView alloc] initWithFrame:wrapperView.bounds];
+  _shapeOverlayView.autoresizingMask =
+      UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+  [wrapperView addSubview:_shapeOverlayView];
+
+  [self updateProjection];
+
+  __weak StaticMapProviderBase *weakSelf = self;
+  if ([wrapperView isKindOfClass:[LuggMapWrapperView class]]) {
+    ((LuggMapWrapperView *)wrapperView).layoutHandler = ^{
+      [weakSelf wrapperDidLayout];
+    };
+  }
+
+  _isMapReady = YES;
+
+  // Start after the current mount pass so map settings props applied right
+  // after this call shape the base render
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [weakSelf renderBaseMapIfNeeded];
+  });
+}
+
+- (void)destroy {
+  [self cancelBaseRender];
+
+  if ([_wrapperView isKindOfClass:[LuggMapWrapperView class]]) {
+    ((LuggMapWrapperView *)_wrapperView).layoutHandler = nil;
+  }
+
+  for (LuggMarkerView *markerView in _markerViews) {
+    markerView.delegate = nil;
+    UIView *iconView = markerView.iconView;
+    if (iconView.superview == _wrapperView) {
+      [iconView removeFromSuperview];
+    }
+    [markerView resetIconViewTransform];
+  }
+  [_markerViews removeAllObjects];
+  for (UIView *pin in _defaultMarkerOverlays.objectEnumerator) {
+    [pin removeFromSuperview];
+  }
+  [_defaultMarkerOverlays removeAllObjects];
+
+  for (LuggPolylineView *view in _shapeOverlayView.polylineViews) {
+    view.delegate = nil;
+  }
+  for (LuggPolygonView *view in _shapeOverlayView.polygonViews) {
+    view.delegate = nil;
+  }
+  for (LuggCircleView *view in _shapeOverlayView.circleViews) {
+    view.delegate = nil;
+  }
+  for (LuggGroundOverlayView *view in _shapeOverlayView.groundOverlayViews) {
+    view.delegate = nil;
+  }
+  [_shapeOverlayView removeFromSuperview];
+  _shapeOverlayView = nil;
+
+  [_baseImageView removeFromSuperview];
+  _baseImageView = nil;
+
+  _baseRenderDone = NO;
+  _projectionReady = NO;
+  _wrapperView = nil;
+  _isMapReady = NO;
+}
+
+#pragma mark - Base render
+
+- (void)updateProjection {
+  CGSize size = _wrapperView.bounds.size;
+  if (size.width <= 0 || size.height <= 0)
+    return;
+
+  _projectedSize = size;
+  _mapRect = [self mapRectForSize:size];
+  _projectionReady = YES;
+
+  _shapeOverlayView.mapRect = _mapRect;
+  _shapeOverlayView.projectionReady = YES;
+  [_shapeOverlayView setNeedsDisplay];
+
+  for (LuggMarkerView *markerView in _markerViews) {
+    [self positionMarkerOverlay:markerView];
+  }
+}
+
+// A static map can't autoresize like a live map; when the wrapper gets its
+// first real size (or resizes later) recompute the projection and
+// (re)render the base map at the new size
+- (void)wrapperDidLayout {
+  CGSize size = _wrapperView.bounds.size;
+  if (size.width <= 0 || size.height <= 0 ||
+      CGSizeEqualToSize(size, _projectedSize))
+    return;
+
+  [self updateProjection];
+
+  // Any in-flight or completed base render targets the old size
+  [self cancelBaseRender];
+  _baseRenderDone = NO;
+  self.cachedBaseImage = nil;
+
+  [self renderBaseMapIfNeeded];
+}
+
+- (void)renderBaseMapIfNeeded {
+  if (_baseRenderDone || !_projectionReady || !_wrapperView)
+    return;
+
+  if (self.cachedBaseImage) {
+    [self displayBaseImage:self.cachedBaseImage fromCache:YES];
+    return;
+  }
+
+  [self renderBaseMap];
+}
+
+- (void)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache {
+  if (!_baseImageView) {
+    _baseImageView = [[UIImageView alloc] initWithFrame:_wrapperView.bounds];
+    _baseImageView.autoresizingMask =
+        UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+    [_wrapperView insertSubview:_baseImageView atIndex:0];
+  }
+  _baseImageView.image = image;
+  _baseRenderDone = YES;
+
+  if (!fromCache) {
+    [_delegate mapProviderDidCaptureStaticImage:image];
+  }
+  [_delegate mapProviderDidFinishStaticSnapshot];
+  [_delegate mapProviderDidReady];
+}
+
+#pragma mark - Subclass hooks
+
+- (MKMapRect)mapRectForSize:(CGSize)size {
+  return MKMapRectNull;
+}
+
+- (UIView *)newDefaultMarkerOverlayView {
+  return [[UIView alloc] init];
+}
+
+- (void)renderBaseMap {
+}
+
+- (void)cancelBaseRender {
+}
+
+#pragma mark - Props
+
+- (void)setMapType:(LuggMapViewMapType)mapType {
+  _mapType = mapType;
+}
+
+- (void)setTheme:(LuggMapViewTheme)theme {
+  _theme = theme;
+}
+
+// Interaction and camera props don't apply to a static map
+- (void)setInsetAdjustment:(LuggMapViewInsetAdjustment)insetAdjustment {
+}
+- (void)setZoomEnabled:(BOOL)enabled {
+}
+- (void)setScrollEnabled:(BOOL)enabled {
+}
+- (void)setRotateEnabled:(BOOL)enabled {
+}
+- (void)setPitchEnabled:(BOOL)enabled {
+}
+- (void)setCompassEnabled:(BOOL)enabled {
+}
+- (void)setUserLocationEnabled:(BOOL)enabled {
+}
+- (void)setMinZoom:(double)minZoom {
+}
+- (void)setMaxZoom:(double)maxZoom {
+}
+- (void)setPoiEnabled:(BOOL)enabled {
+}
+- (void)setPoiFilterMode:(LuggMapViewPoiFilterMode)mode {
+}
+- (void)setPoiFilterCategories:(NSArray<NSString *> *)categories {
+}
+- (void)setEdgeInsets:(UIEdgeInsets)edgeInsets
+        oldEdgeInsets:(UIEdgeInsets)oldEdgeInsets {
+}
+- (void)setEdgeInsets:(UIEdgeInsets)edgeInsets
+        oldEdgeInsets:(UIEdgeInsets)oldEdgeInsets
+             duration:(double)duration {
+}
+
+#pragma mark - Markers
+
+// Markers are live views over the base map (like Android lite mode's live
+// markers), so async content such as remote images shows up when it loads
+
+- (void)addMarkerView:(LuggMarkerView *)markerView {
+  markerView.delegate = self;
+  if (![_markerViews containsObject:markerView]) {
+    [_markerViews addObject:markerView];
+  }
+  [self syncMarkerView:markerView];
+}
+
+- (void)removeMarkerView:(LuggMarkerView *)markerView {
+  markerView.delegate = nil;
+  [_markerViews removeObject:markerView];
+
+  UIView *pin = [_defaultMarkerOverlays objectForKey:markerView];
+  if (pin) {
+    [pin removeFromSuperview];
+    [_defaultMarkerOverlays removeObjectForKey:markerView];
+  }
+
+  UIView *iconView = markerView.iconView;
+  if (iconView.superview == _wrapperView) {
+    [iconView removeFromSuperview];
+  }
+  [markerView resetIconViewTransform];
+}
+
+- (void)syncMarkerView:(LuggMarkerView *)markerView {
+  if (!_wrapperView)
+    return;
+
+  UIView *pin = [_defaultMarkerOverlays objectForKey:markerView];
+
+  if (markerView.hasCustomView) {
+    if (pin) {
+      [pin removeFromSuperview];
+      [_defaultMarkerOverlays removeObjectForKey:markerView];
+    }
+    UIView *iconView = markerView.iconView;
+    if (iconView.superview != _wrapperView) {
+      [iconView removeFromSuperview];
+      iconView.userInteractionEnabled = NO;
+      [_wrapperView addSubview:iconView];
+    }
+  } else {
+    UIView *iconView = markerView.iconView;
+    if (iconView.superview == _wrapperView) {
+      [iconView removeFromSuperview];
+      [markerView resetIconViewTransform];
+    }
+    if (!pin) {
+      pin = [self newDefaultMarkerOverlayView];
+      pin.userInteractionEnabled = NO;
+      [_wrapperView addSubview:pin];
+      [_defaultMarkerOverlays setObject:pin forKey:markerView];
+    }
+  }
+
+  [self positionMarkerOverlay:markerView];
+}
+
+- (void)positionMarkerOverlay:(LuggMarkerView *)markerView {
+  if (!_projectionReady)
+    return;
+
+  CGPoint point = LuggStaticPointForCoordinate(_mapRect, _projectedSize,
+                                               markerView.coordinate);
+
+  if (markerView.hasCustomView) {
+    UIView *iconView = markerView.iconView;
+    CGSize size = iconView.bounds.size;
+    if (size.width <= 0 || size.height <= 0) {
+      // Not laid out yet; markerViewDidLayout re-runs this
+      return;
+    }
+    CGFloat scale = markerView.scale;
+    CGFloat radians = markerView.rotate * M_PI / 180.0;
+    iconView.layer.anchorPoint = markerView.anchor;
+    iconView.transform =
+        CGAffineTransformConcat(CGAffineTransformMakeScale(scale, scale),
+                                CGAffineTransformMakeRotation(radians));
+    // center positions the layer's anchorPoint, so the marker's anchor
+    // lands exactly on the projected coordinate
+    iconView.center = point;
+    iconView.layer.zPosition = markerView.zIndex;
+  } else {
+    UIView *pin = [_defaultMarkerOverlays objectForKey:markerView];
+    pin.layer.anchorPoint = CGPointMake(0.5, 1.0);
+    pin.center = point;
+    pin.layer.zPosition = markerView.zIndex;
+  }
+}
+
+#pragma mark - LuggMarkerViewDelegate
+
+- (void)markerViewDidLayout:(LuggMarkerView *)markerView {
+  [self syncMarkerView:markerView];
+}
+
+- (void)markerViewDidUpdate:(LuggMarkerView *)markerView {
+  [self syncMarkerView:markerView];
+}
+
+#pragma mark - Shapes
+
+- (void)addPolylineView:(LuggPolylineView *)polylineView {
+  polylineView.delegate = self;
+  if (![_shapeOverlayView.polylineViews containsObject:polylineView]) {
+    [_shapeOverlayView.polylineViews addObject:polylineView];
+  }
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)removePolylineView:(LuggPolylineView *)polylineView {
+  polylineView.delegate = nil;
+  [_shapeOverlayView.polylineViews removeObject:polylineView];
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)syncPolylineView:(LuggPolylineView *)polylineView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)polylineViewDidUpdate:(LuggPolylineView *)polylineView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)addPolygonView:(LuggPolygonView *)polygonView {
+  polygonView.delegate = self;
+  if (![_shapeOverlayView.polygonViews containsObject:polygonView]) {
+    [_shapeOverlayView.polygonViews addObject:polygonView];
+  }
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)removePolygonView:(LuggPolygonView *)polygonView {
+  polygonView.delegate = nil;
+  [_shapeOverlayView.polygonViews removeObject:polygonView];
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)syncPolygonView:(LuggPolygonView *)polygonView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)polygonViewDidUpdate:(LuggPolygonView *)polygonView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)addCircleView:(LuggCircleView *)circleView {
+  circleView.delegate = self;
+  if (![_shapeOverlayView.circleViews containsObject:circleView]) {
+    [_shapeOverlayView.circleViews addObject:circleView];
+  }
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)removeCircleView:(LuggCircleView *)circleView {
+  circleView.delegate = nil;
+  [_shapeOverlayView.circleViews removeObject:circleView];
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)syncCircleView:(LuggCircleView *)circleView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)circleViewDidUpdate:(LuggCircleView *)circleView {
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)addGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
+  groundOverlayView.delegate = self;
+  if (![_shapeOverlayView.groundOverlayViews
+          containsObject:groundOverlayView]) {
+    [_shapeOverlayView.groundOverlayViews addObject:groundOverlayView];
+  }
+  [self loadGroundOverlayImage:groundOverlayView];
+}
+
+- (void)removeGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
+  groundOverlayView.delegate = nil;
+  [_shapeOverlayView.groundOverlayViews removeObject:groundOverlayView];
+  [_shapeOverlayView.groundOverlayImages removeObjectForKey:groundOverlayView];
+  [_shapeOverlayView setNeedsDisplay];
+}
+
+- (void)syncGroundOverlayView:(LuggGroundOverlayView *)groundOverlayView {
+  [self loadGroundOverlayImage:groundOverlayView];
+}
+
+- (void)groundOverlayViewDidUpdate:(LuggGroundOverlayView *)groundOverlayView {
+  [self loadGroundOverlayImage:groundOverlayView];
+}
+
+- (void)loadGroundOverlayImage:(LuggGroundOverlayView *)groundOverlayView {
+  NSURL *url = [NSURL URLWithString:groundOverlayView.imageUri];
+  if (!url)
+    return;
+
+  __weak StaticMapProviderBase *weakSelf = self;
+  __weak LuggGroundOverlayView *weakOverlayView = groundOverlayView;
+  dispatch_async(
+      dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+        NSData *data = [NSData dataWithContentsOfURL:url];
+        UIImage *image = data ? [UIImage imageWithData:data] : nil;
+        dispatch_async(dispatch_get_main_queue(), ^{
+          StaticMapProviderBase *strongSelf = weakSelf;
+          LuggGroundOverlayView *overlayView = weakOverlayView;
+          if (!strongSelf || !overlayView || !image)
+            return;
+          LuggStaticShapeOverlayView *shapeView = strongSelf->_shapeOverlayView;
+          if (![shapeView.groundOverlayViews containsObject:overlayView])
+            return;
+          [shapeView.groundOverlayImages setObject:image forKey:overlayView];
+          [shapeView setNeedsDisplay];
+        });
+      });
+}
+
+// Tile overlays need a live map to fetch and compose tiles; unsupported on
+// static maps
+- (void)addTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
+}
+- (void)removeTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
+}
+- (void)syncTileOverlayView:(LuggTileOverlayView *)tileOverlayView {
+}
+
+#pragma mark - Lifecycle
+
+- (void)pauseAnimations {
+}
+
+- (void)resumeAnimations {
+  // Retry a failed or cancelled base render (e.g. device back online)
+  [self renderBaseMapIfNeeded];
+}
+
+#pragma mark - Commands
+
+// Static maps render once with their initial camera
+
+- (void)moveCamera:(double)latitude
+         longitude:(double)longitude
+              zoom:(double)zoom
+          duration:(double)duration {
+}
+
+- (void)fitCoordinates:(NSArray *)coordinates
+         edgeInsetsTop:(double)edgeInsetsTop
+        edgeInsetsLeft:(double)edgeInsetsLeft
+      edgeInsetsBottom:(double)edgeInsetsBottom
+       edgeInsetsRight:(double)edgeInsetsRight
+              duration:(double)duration {
+}
+
+@end

From 359a140c55b4ed7ee064f48cc81f18bad291e1de Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 04:22:58 +0800
Subject: [PATCH 13/17] fix(android): hide live markers until lite map
 projection is valid

Live (non-rasterized) markers were positioned with a garbage projection
before the lite map rendered, flashing off-position until onMapLoaded
corrected them. Keep them invisible until positioned correctly.
---
 .../main/java/com/luggmaps/core/GoogleMapProvider.kt | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt b/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
index 368d944..1e37240 100644
--- a/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
+++ b/android/src/main/java/com/luggmaps/core/GoogleMapProvider.kt
@@ -99,6 +99,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 liteProjectionReady = false
   private var activeNonBubbledMarker: Marker? = null
   private var tapLocation: LatLng? = null
 
@@ -207,7 +208,10 @@ class GoogleMapProvider(private val context: Context) :
       map.uiSettings.isMapToolbarEnabled = false
       // The projection is only valid once the lite map has rendered, and no
       // camera events fire afterwards to correct live marker positions
-      map.setOnMapLoadedCallback { positionLiveMarkers() }
+      map.setOnMapLoadedCallback {
+        liteProjectionReady = true
+        positionLiveMarkers()
+      }
     }
 
     val position = LatLng(initialLatitude, initialLongitude)
@@ -752,6 +756,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 && !liteProjectionReady) View.INVISIBLE else View.VISIBLE
     (contentView.parent as? android.view.ViewGroup)?.removeView(contentView)
     wrapper.addView(contentView)
     liveMarkerViews.add(markerView)
@@ -783,10 +791,12 @@ class GoogleMapProvider(private val context: Context) :
 
   private fun positionLiveMarker(markerView: LuggMarkerView) {
     val map = googleMap ?: return
+    if (staticMode && !liteProjectionReady) 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

From ff263fa42267ce8249f7c3de3727fde9e694c7e9 Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 04:29:25 +0800
Subject: [PATCH 14/17] fix(ios): reveal static map overlays only once the base
 map displays

Markers and shapes no longer show over the placeholder while the base
map loads; they stay hidden and appear together with it, matching
Android lite mode.
---
 docs/MAPVIEW.md                    | 19 +++++++++----------
 ios/LuggMapView.mm                 |  6 +++---
 ios/LuggMarkerView.mm              |  2 ++
 ios/core/GoogleStaticMapProvider.h |  4 ++--
 ios/core/StaticMapProviderBase.h   |  9 +++++----
 ios/core/StaticMapProviderBase.mm  | 13 +++++++++++++
 6 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index 8aaa835..3d55fc7 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -61,13 +61,12 @@ mounting many live maps is expensive:
   static maps keep loading while scrolling. Markers stay live views
   positioned over the base map; polylines, polygons, circles, and ground
   overlays are drawn onto it. Tile overlays are not supported.
-- **iOS (Google)** - markers and shapes render as live overlay views
-  immediately, exactly like Apple static maps. Only the base map needs the
-  SDK (which has no async snapshotter): a live, tiles-only map warms up
-  briefly under the overlays and is replaced with a rendered image once
-  tiles finish loading, releasing the map's rendering resources. Warmups
-  are paced to never compete with scroll gestures, so base maps fill in
-  between scrolls while markers show right away.
+- **iOS (Google)** - markers and shapes render as live overlay views,
+  exactly like Apple static maps. Only the base map needs the SDK (which
+  has no async snapshotter): a live, tiles-only map warms up briefly under
+  the overlays and is replaced with a rendered image once tiles finish
+  loading, releasing the map's rendering resources. Warmups are paced to
+  never compete with scroll gestures, so rows fill in between scrolls.
 - **Web (Google)** - gestures, POI clicks, keyboard interaction, and press
   events are disabled; the map itself stays live.
 
@@ -96,9 +95,9 @@ Notes:
   map container (as above) instead of relying on `onPress`.
 - `animated` polylines render as complete static polylines, so the snapshot
   never freezes a mid-animation frame.
-- On iOS, markers are live views over the base map - marker content that
-  loads asynchronously (e.g. remote images) appears when ready, and marker
-  prop updates still apply.
+- On iOS, markers are live views over the base map, revealed together with
+  it - marker content that loads asynchronously (e.g. remote images)
+  appears when ready, and marker prop updates still apply.
 - While a static map loads, a theme-aware placeholder background is shown.
   Set a `backgroundColor` style on the `MapView` to use your own.
 - Set `staticKey` (e.g. your list item's id) to cache base map images
diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index d14d7c0..3c7ef58 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -264,9 +264,9 @@ - (nullable NSString *)staticSnapshotCacheKey {
 - (void)startStaticContent {
   [self applyStaticPlaceholderBackground];
 
-  // Both static providers render fully async: markers and shapes show up
-  // as overlay views immediately, and the base map arrives when the
-  // snapshotter (Apple) or a paced warmup (Google) finishes - so static
+  // Both static providers render fully async: the placeholder shows until
+  // the snapshotter (Apple) or a paced warmup (Google) delivers the base
+  // map, which reveals together with the marker/shape overlays - so static
   // maps keep loading while the user scrolls
   [self initializeProvider];
 }
diff --git a/ios/LuggMarkerView.mm b/ios/LuggMarkerView.mm
index 44a8b2b..44fe1ad 100644
--- a/ios/LuggMarkerView.mm
+++ b/ios/LuggMarkerView.mm
@@ -287,6 +287,8 @@ - (void)resetIconViewTransform {
   _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 {
diff --git a/ios/core/GoogleStaticMapProvider.h b/ios/core/GoogleStaticMapProvider.h
index a200f96..4f28186 100644
--- a/ios/core/GoogleStaticMapProvider.h
+++ b/ios/core/GoogleStaticMapProvider.h
@@ -9,8 +9,8 @@ NS_ASSUME_NONNULL_BEGIN
  * the overlays, then is swapped with a rendered image and the map view is
  * pooled for reuse. Warmups are paced by LuggStaticMapWarmupQueue so they
  * never compete with scroll gestures; markers and shapes are overlay views
- * (shared with Apple static maps) that appear immediately, without waiting
- * for a warmup slot.
+ * (shared with Apple static maps) that reveal with the base map, so the
+ * warmup map never renders its own markers.
  */
 @interface GoogleStaticMapProvider : StaticMapProviderBase <GMSMapViewDelegate>
 
diff --git a/ios/core/StaticMapProviderBase.h b/ios/core/StaticMapProviderBase.h
index bf459af..704bc26 100644
--- a/ios/core/StaticMapProviderBase.h
+++ b/ios/core/StaticMapProviderBase.h
@@ -15,10 +15,11 @@ CGPoint LuggStaticPointForCoordinate(MKMapRect mapRect, CGSize size,
  *
  * Markers are live views positioned over the base map via a mercator
  * projection (mirroring Android's live markers on lite maps), so async
- * marker content (e.g. remote images) appears when it loads - immediately,
- * without waiting for the base map. Polylines, polygons, circles and
- * ground overlays are drawn into a single CoreGraphics overlay view.
- * Tile overlays are not supported.
+ * marker content (e.g. remote images) still updates when it loads.
+ * Polylines, polygons, circles and ground overlays are drawn into a
+ * single CoreGraphics overlay view. All overlays stay hidden over the
+ * placeholder and reveal together with the base map. Tile overlays are
+ * not supported.
  */
 @interface StaticMapProviderBase : NSObject <MapProvider>
 
diff --git a/ios/core/StaticMapProviderBase.mm b/ios/core/StaticMapProviderBase.mm
index a902c2a..34d0e75 100644
--- a/ios/core/StaticMapProviderBase.mm
+++ b/ios/core/StaticMapProviderBase.mm
@@ -270,6 +270,8 @@ - (void)initializeMapInView:(UIView *)wrapperView
       [[LuggStaticShapeOverlayView alloc] initWithFrame:wrapperView.bounds];
   _shapeOverlayView.autoresizingMask =
       UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+  // Overlays stay hidden over the placeholder and reveal with the base map
+  _shapeOverlayView.hidden = YES;
   [wrapperView addSubview:_shapeOverlayView];
 
   [self updateProjection];
@@ -396,6 +398,12 @@ - (void)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache {
   _baseImageView.image = image;
   _baseRenderDone = YES;
 
+  // Reveal markers and shapes now that the base map is displayed
+  _shapeOverlayView.hidden = NO;
+  for (LuggMarkerView *markerView in _markerViews) {
+    [self positionMarkerOverlay:markerView];
+  }
+
   if (!fromCache) {
     [_delegate mapProviderDidCaptureStaticImage:image];
   }
@@ -507,6 +515,8 @@ - (void)syncMarkerView:(LuggMarkerView *)markerView {
     if (iconView.superview != _wrapperView) {
       [iconView removeFromSuperview];
       iconView.userInteractionEnabled = NO;
+      // Hidden until the base map displays; positionMarkerOverlay shows it
+      iconView.hidden = YES;
       [_wrapperView addSubview:iconView];
     }
   } else {
@@ -518,6 +528,7 @@ - (void)syncMarkerView:(LuggMarkerView *)markerView {
     if (!pin) {
       pin = [self newDefaultMarkerOverlayView];
       pin.userInteractionEnabled = NO;
+      pin.hidden = YES;
       [_wrapperView addSubview:pin];
       [_defaultMarkerOverlays setObject:pin forKey:markerView];
     }
@@ -550,11 +561,13 @@ - (void)positionMarkerOverlay:(LuggMarkerView *)markerView {
     // lands exactly on the projected coordinate
     iconView.center = point;
     iconView.layer.zPosition = markerView.zIndex;
+    iconView.hidden = !_baseRenderDone;
   } else {
     UIView *pin = [_defaultMarkerOverlays objectForKey:markerView];
     pin.layer.anchorPoint = CGPointMake(0.5, 1.0);
     pin.center = point;
     pin.layer.zPosition = markerView.zIndex;
+    pin.hidden = !_baseRenderDone;
   }
 }
 

From b24222a48f0d780682fc7aae081870f36f417707 Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 04:38:18 +0800
Subject: [PATCH 15/17] perf(ios): drop static map warmup throttle, raise pool
 to 6

Google static maps now warm up as soon as rows mount instead of queuing
behind a 3-slot, scroll-gated warmup queue. Apps bound concurrent work
via list props (windowSize etc.).
---
 docs/MAPVIEW.md                     |   5 +-
 ios/LuggMapView.mm                  |   5 +-
 ios/core/GoogleStaticMapProvider.h  |   8 +-
 ios/core/GoogleStaticMapProvider.mm |  49 +++---------
 ios/core/LuggStaticMapWarmupQueue.h |  28 -------
 ios/core/LuggStaticMapWarmupQueue.m | 116 ----------------------------
 6 files changed, 18 insertions(+), 193 deletions(-)
 delete mode 100644 ios/core/LuggStaticMapWarmupQueue.h
 delete mode 100644 ios/core/LuggStaticMapWarmupQueue.m

diff --git a/docs/MAPVIEW.md b/docs/MAPVIEW.md
index 3d55fc7..9652f44 100644
--- a/docs/MAPVIEW.md
+++ b/docs/MAPVIEW.md
@@ -65,8 +65,9 @@ mounting many live maps is expensive:
   exactly like Apple static maps. Only the base map needs the SDK (which
   has no async snapshotter): a live, tiles-only map warms up briefly under
   the overlays and is replaced with a rendered image once tiles finish
-  loading, releasing the map's rendering resources. Warmups are paced to
-  never compete with scroll gestures, so rows fill in between scrolls.
+  loading, releasing the map's rendering resources. Warmup work scales
+  with how many rows mount at once - bound it with your list's
+  `windowSize` / `initialNumToRender` / `maxToRenderPerBatch`.
 - **Web (Google)** - gestures, POI clicks, keyboard interaction, and press
   events are disabled; the map itself stays live.
 
diff --git a/ios/LuggMapView.mm b/ios/LuggMapView.mm
index 3c7ef58..a764e21 100644
--- a/ios/LuggMapView.mm
+++ b/ios/LuggMapView.mm
@@ -265,9 +265,8 @@ - (void)startStaticContent {
   [self applyStaticPlaceholderBackground];
 
   // Both static providers render fully async: the placeholder shows until
-  // the snapshotter (Apple) or a paced warmup (Google) delivers the base
-  // map, which reveals together with the marker/shape overlays - so static
-  // maps keep loading while the user scrolls
+  // the snapshotter (Apple) or a brief live-map warmup (Google) delivers
+  // the base map, which reveals together with the marker/shape overlays
   [self initializeProvider];
 }
 
diff --git a/ios/core/GoogleStaticMapProvider.h b/ios/core/GoogleStaticMapProvider.h
index 4f28186..e8af010 100644
--- a/ios/core/GoogleStaticMapProvider.h
+++ b/ios/core/GoogleStaticMapProvider.h
@@ -7,10 +7,10 @@ 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. Warmups are paced by LuggStaticMapWarmupQueue so they
- * never compete with scroll gestures; 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.
+ * 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>
 
diff --git a/ios/core/GoogleStaticMapProvider.mm b/ios/core/GoogleStaticMapProvider.mm
index d868a1f..901fea7 100644
--- a/ios/core/GoogleStaticMapProvider.mm
+++ b/ios/core/GoogleStaticMapProvider.mm
@@ -2,14 +2,13 @@
 
 #import "../extensions/UIView+Snapshot.h"
 #import "GoogleMapProvider.h"
-#import "LuggStaticMapWarmupQueue.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 = 3;
+static const NSUInteger kStaticMapViewPoolCapacity = 6;
 
 static NSMutableDictionary<NSString *, NSMutableArray<GMSMapView *> *> *
 StaticMapViewPool(void) {
@@ -50,8 +49,6 @@ static void EnqueueStaticMapView(NSString *mapId, GMSMapView *mapView) {
 
 @implementation GoogleStaticMapProvider {
   GMSMapView *_warmupMapView;
-  BOOL _waitingForWarmupSlot;
-  BOOL _holdingWarmupSlot;
   BOOL _tilesRendered;
   BOOL _swapScheduled;
 }
@@ -83,28 +80,10 @@ - (void)renderBaseMap {
     [self scheduleSwap];
     return;
   }
-  if (_waitingForWarmupSlot)
-    return;
-
-  _waitingForWarmupSlot = YES;
-  __weak GoogleStaticMapProvider *weakSelf = self;
-  [[LuggStaticMapWarmupQueue sharedQueue]
-      requestSlotForOwner:self
-               completion:^{
-                 GoogleStaticMapProvider *strongSelf = weakSelf;
-                 if (!strongSelf)
-                   return;
-                 strongSelf->_waitingForWarmupSlot = NO;
-                 strongSelf->_holdingWarmupSlot = YES;
-                 [strongSelf startWarmup];
-               }];
+  [self startWarmup];
 }
 
 - (void)cancelBaseRender {
-  if (_waitingForWarmupSlot) {
-    [[LuggStaticMapWarmupQueue sharedQueue] cancelOwner:self];
-    _waitingForWarmupSlot = NO;
-  }
   [self destroyWarmupMapView];
 }
 
@@ -118,10 +97,8 @@ - (NSString *)poolKey {
 
 - (void)startWarmup {
   UIView *wrapperView = self.wrapperView;
-  if (!wrapperView) {
-    [self releaseWarmupSlot];
+  if (!wrapperView)
     return;
-  }
 
   _tilesRendered = NO;
 
@@ -159,20 +136,12 @@ - (void)startWarmup {
 }
 
 - (void)destroyWarmupMapView {
-  if (_warmupMapView) {
-    _warmupMapView.delegate = nil;
-    [_warmupMapView removeFromSuperview];
-    EnqueueStaticMapView([self poolKey], _warmupMapView);
-    _warmupMapView = nil;
-  }
-  [self releaseWarmupSlot];
-}
-
-- (void)releaseWarmupSlot {
-  if (_holdingWarmupSlot) {
-    _holdingWarmupSlot = NO;
-    [[LuggStaticMapWarmupQueue sharedQueue] releaseSlotForOwner:self];
-  }
+  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
diff --git a/ios/core/LuggStaticMapWarmupQueue.h b/ios/core/LuggStaticMapWarmupQueue.h
deleted file mode 100644
index f56e36b..0000000
--- a/ios/core/LuggStaticMapWarmupQueue.h
+++ /dev/null
@@ -1,28 +0,0 @@
-#import <Foundation/Foundation.h>
-
-NS_ASSUME_NONNULL_BEGIN
-
-/**
- * Serializes static map base warmup so only a few live maps exist at a
- * time. Google static maps briefly need a live map view to render their
- * base image (the SDK has no async snapshotter); without throttling, a
- * list mounting many rows creates them all at once and stalls the main
- * thread. Apple static maps render through MKMapSnapshotter and don't use
- * this queue.
- */
-@interface LuggStaticMapWarmupQueue : NSObject
-
-+ (instancetype)sharedQueue;
-
-/// Calls completion when a warmup slot is available (possibly immediately).
-- (void)requestSlotForOwner:(id)owner completion:(dispatch_block_t)completion;
-
-/// Removes any pending request for the owner.
-- (void)cancelOwner:(id)owner;
-
-/// Frees the owner's slot and starts the next pending warmup.
-- (void)releaseSlotForOwner:(id)owner;
-
-@end
-
-NS_ASSUME_NONNULL_END
diff --git a/ios/core/LuggStaticMapWarmupQueue.m b/ios/core/LuggStaticMapWarmupQueue.m
deleted file mode 100644
index 83f7c7e..0000000
--- a/ios/core/LuggStaticMapWarmupQueue.m
+++ /dev/null
@@ -1,116 +0,0 @@
-#import "LuggStaticMapWarmupQueue.h"
-
-// Bounds how many live warmup maps exist at once - peak memory scales with
-// this. Grants are additionally paced by the runloop (one per pass, outside
-// scroll tracking)
-static const NSUInteger kMaxConcurrentWarmups = 3;
-// Slot is force-released if a map never finishes rendering (e.g. offline)
-// so it can't starve the queue. The live map is left in place.
-static const int64_t kWarmupTimeoutSeconds = 10;
-
-@interface LuggWarmupRequest : NSObject
-@property(nonatomic, weak) id owner;
-@property(nonatomic, copy) dispatch_block_t completion;
-@end
-
-@implementation LuggWarmupRequest
-@end
-
-@implementation LuggStaticMapWarmupQueue {
-  NSMutableArray<LuggWarmupRequest *> *_pending;
-  NSHashTable<id> *_active;
-  BOOL _drainScheduled;
-}
-
-+ (instancetype)sharedQueue {
-  static LuggStaticMapWarmupQueue *queue;
-  static dispatch_once_t onceToken;
-  dispatch_once(&onceToken, ^{
-    queue = [[LuggStaticMapWarmupQueue alloc] init];
-  });
-  return queue;
-}
-
-- (instancetype)init {
-  if (self = [super init]) {
-    _pending = [NSMutableArray array];
-    _active = [NSHashTable weakObjectsHashTable];
-  }
-  return self;
-}
-
-- (void)requestSlotForOwner:(id)owner completion:(dispatch_block_t)completion {
-  LuggWarmupRequest *request = [[LuggWarmupRequest alloc] init];
-  request.owner = owner;
-  request.completion = completion;
-  [_pending addObject:request];
-  [self drain];
-}
-
-- (void)cancelOwner:(id)owner {
-  NSMutableArray<LuggWarmupRequest *> *remaining = [NSMutableArray array];
-  for (LuggWarmupRequest *request in _pending) {
-    if (request.owner != nil && request.owner != owner) {
-      [remaining addObject:request];
-    }
-  }
-  _pending = remaining;
-}
-
-- (void)releaseSlotForOwner:(id)owner {
-  if (![_active containsObject:owner])
-    return;
-  [_active removeObject:owner];
-  [self drain];
-}
-
-// Grants run in NSDefaultRunLoopMode - not serviced while the user is
-// actively dragging - and one per runloop pass, so map creation never
-// competes with scroll gestures for the main thread.
-- (void)drain {
-  if (_drainScheduled || _pending.count == 0 ||
-      _active.count >= kMaxConcurrentWarmups)
-    return;
-
-  _drainScheduled = YES;
-  __weak LuggStaticMapWarmupQueue *weakSelf = self;
-  [[NSRunLoop mainRunLoop]
-      performInModes:@[ NSDefaultRunLoopMode ]
-               block:^{
-                 LuggStaticMapWarmupQueue *strongSelf = weakSelf;
-                 if (!strongSelf)
-                   return;
-                 strongSelf->_drainScheduled = NO;
-                 [strongSelf grantNext];
-                 [strongSelf drain];
-               }];
-}
-
-- (void)grantNext {
-  while (_active.count < kMaxConcurrentWarmups && _pending.count > 0) {
-    LuggWarmupRequest *request = _pending.firstObject;
-    [_pending removeObjectAtIndex:0];
-    id owner = request.owner;
-    if (!owner)
-      continue;
-    [_active addObject:owner];
-    [self scheduleTimeoutForOwner:owner];
-    request.completion();
-    return;
-  }
-}
-
-- (void)scheduleTimeoutForOwner:(id)owner {
-  __weak LuggStaticMapWarmupQueue *weakSelf = self;
-  __weak id weakOwner = owner;
-  dispatch_after(
-      dispatch_time(DISPATCH_TIME_NOW, kWarmupTimeoutSeconds * NSEC_PER_SEC),
-      dispatch_get_main_queue(), ^{
-        id strongOwner = weakOwner;
-        if (strongOwner) {
-          [weakSelf releaseSlotForOwner:strongOwner];
-        }
-      });
-}
-
-@end

From e497c7f292ff4f98b63bd9d4b86aa44af33c8958 Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 04:44:11 +0800
Subject: [PATCH 16/17] fix(ios): reveal google static overlays when tiles
 render, not at swap

The swap is deferred while scrolling, so markers stayed hidden over an
already-rendered warmup map. Decouple the overlay reveal from the swap.
---
 ios/core/GoogleStaticMapProvider.mm |  4 ++++
 ios/core/StaticMapProviderBase.h    |  5 +++++
 ios/core/StaticMapProviderBase.mm   | 23 +++++++++++++++--------
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/ios/core/GoogleStaticMapProvider.mm b/ios/core/GoogleStaticMapProvider.mm
index 901fea7..8efcf2a 100644
--- a/ios/core/GoogleStaticMapProvider.mm
+++ b/ios/core/GoogleStaticMapProvider.mm
@@ -189,12 +189,16 @@ - (void)mapViewDidStartTileRendering:(GMSMapView *)mapView {
 
 - (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];
 }
 
diff --git a/ios/core/StaticMapProviderBase.h b/ios/core/StaticMapProviderBase.h
index 704bc26..f77b8f2 100644
--- a/ios/core/StaticMapProviderBase.h
+++ b/ios/core/StaticMapProviderBase.h
@@ -41,6 +41,11 @@ CGPoint LuggStaticPointForCoordinate(MKMapRect mapRect, CGSize size,
 /// delegate callbacks and marks the base render done.
 - (void)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache;
 
+/// 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.
+- (void)revealOverlays;
+
 #pragma mark - Subclass hooks
 
 /// The map rect the base render covers for the given view size; must match
diff --git a/ios/core/StaticMapProviderBase.mm b/ios/core/StaticMapProviderBase.mm
index 34d0e75..c697e14 100644
--- a/ios/core/StaticMapProviderBase.mm
+++ b/ios/core/StaticMapProviderBase.mm
@@ -230,6 +230,7 @@ @interface StaticMapProviderBase () <
 @implementation StaticMapProviderBase {
   BOOL _isMapReady;
   BOOL _baseRenderDone;
+  BOOL _overlaysRevealed;
 
   UIImageView *_baseImageView;
   LuggStaticShapeOverlayView *_shapeOverlayView;
@@ -332,6 +333,7 @@ - (void)destroy {
   _baseImageView = nil;
 
   _baseRenderDone = NO;
+  _overlaysRevealed = NO;
   _projectionReady = NO;
   _wrapperView = nil;
   _isMapReady = NO;
@@ -397,12 +399,7 @@ - (void)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache {
   }
   _baseImageView.image = image;
   _baseRenderDone = YES;
-
-  // Reveal markers and shapes now that the base map is displayed
-  _shapeOverlayView.hidden = NO;
-  for (LuggMarkerView *markerView in _markerViews) {
-    [self positionMarkerOverlay:markerView];
-  }
+  [self revealOverlays];
 
   if (!fromCache) {
     [_delegate mapProviderDidCaptureStaticImage:image];
@@ -411,6 +408,16 @@ - (void)displayBaseImage:(UIImage *)image fromCache:(BOOL)fromCache {
   [_delegate mapProviderDidReady];
 }
 
+- (void)revealOverlays {
+  if (_overlaysRevealed)
+    return;
+  _overlaysRevealed = YES;
+  _shapeOverlayView.hidden = NO;
+  for (LuggMarkerView *markerView in _markerViews) {
+    [self positionMarkerOverlay:markerView];
+  }
+}
+
 #pragma mark - Subclass hooks
 
 - (MKMapRect)mapRectForSize:(CGSize)size {
@@ -561,13 +568,13 @@ - (void)positionMarkerOverlay:(LuggMarkerView *)markerView {
     // lands exactly on the projected coordinate
     iconView.center = point;
     iconView.layer.zPosition = markerView.zIndex;
-    iconView.hidden = !_baseRenderDone;
+    iconView.hidden = !_overlaysRevealed;
   } else {
     UIView *pin = [_defaultMarkerOverlays objectForKey:markerView];
     pin.layer.anchorPoint = CGPointMake(0.5, 1.0);
     pin.center = point;
     pin.layer.zPosition = markerView.zIndex;
-    pin.hidden = !_baseRenderDone;
+    pin.hidden = !_overlaysRevealed;
   }
 }
 

From 95d0215770ca045e8c010a26c9840228f3914d7d Mon Sep 17 00:00:00 2001
From: Jovanni Lo <lodev09@gmail.com>
Date: Wed, 8 Jul 2026 04:51:37 +0800
Subject: [PATCH 17/17] chore(example): add constellation polyline with dot
 markers to static maps

---
 .../shared/src/screens/StaticMapsScreen.tsx   | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/example/shared/src/screens/StaticMapsScreen.tsx b/example/shared/src/screens/StaticMapsScreen.tsx
index f9de5df..c83ea4f 100644
--- a/example/shared/src/screens/StaticMapsScreen.tsx
+++ b/example/shared/src/screens/StaticMapsScreen.tsx
@@ -4,6 +4,7 @@ import {
   MapProvider,
   MapView,
   Marker,
+  Polyline,
   type Coordinate,
   type MapProviderType,
 } from '@lugg/maps';
@@ -99,6 +100,45 @@ const PLACES: StaticPlace[] = Array.from({ length: 100 }, (_, i) => {
   };
 });
 
+const seedFromId = (id: string) =>
+  id.split('').reduce((acc, ch) => acc + ch.charCodeAt(0), 0);
+
+// Deterministic pseudo-random scatter of 2-4 points, stable across
+// re-renders so static snapshots stay valid. Clustered west of the
+// coordinate so it doesn't overlap the center markers
+const constellationPoints = (
+  coordinate: Coordinate,
+  seed: number
+): Coordinate[] => {
+  const count = 2 + (seed % 3);
+  return Array.from({ length: count }, (_, i) => {
+    const angle = seed + i * 2.4;
+    const radius = 0.002 + ((seed + i) % 4) * 0.001;
+    return {
+      latitude: coordinate.latitude + Math.sin(angle) * radius * 0.8,
+      longitude: coordinate.longitude - 0.009 + Math.cos(angle) * radius * 1.2,
+    };
+  });
+};
+
+const PlaceConstellation = ({ place }: { place: StaticPlace }) => {
+  const points = constellationPoints(place.coordinate, seedFromId(place.id));
+  return (
+    <>
+      <Polyline
+        coordinates={points}
+        strokeWidth={3}
+        strokeColors={['#007aff']}
+      />
+      {points.map((point, index) => (
+        <Marker key={index} coordinate={point} anchor={{ x: 0.5, y: 0.5 }}>
+          <View style={styles.dot} />
+        </Marker>
+      ))}
+    </>
+  );
+};
+
 const PlaceMarkers = ({ place }: { place: StaticPlace }) => {
   const { coordinate, markerType, markerText, imageUrl } = place;
 
@@ -168,6 +208,7 @@ const PlaceCard = ({
           initialZoom={14}
         >
           <PlaceMarkers place={place} />
+          <PlaceConstellation place={place} />
         </MapView>
       </View>
       <View style={styles.cardContent}>
@@ -236,4 +277,12 @@ const styles = StyleSheet.create({
   cardTitle: {
     fontSize: sizes.fontLg,
   },
+  dot: {
+    width: 10,
+    height: 10,
+    borderRadius: 5,
+    backgroundColor: '#007aff',
+    borderWidth: 2,
+    borderColor: 'white',
+  },
 });