@lugg/maps 1.0.0-beta.2 → 1.0.0-beta.20

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

@@ -1,26 +1,41 @@
 package com.luggmaps.core
 
 import android.annotation.SuppressLint
+import android.content.ComponentCallbacks2
 import android.content.Context
+import android.content.res.Configuration
 import android.view.View
 import android.widget.ImageView
 import androidx.core.graphics.createBitmap
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowInsetsCompat
 import com.facebook.react.uimanager.PixelUtil.dpToPx
 import com.google.android.gms.maps.CameraUpdateFactory
 import com.google.android.gms.maps.GoogleMap
 import com.google.android.gms.maps.GoogleMapOptions
 import com.google.android.gms.maps.MapView
 import com.google.android.gms.maps.OnMapReadyCallback
-import com.google.android.gms.maps.model.AdvancedMarker
-import com.google.android.gms.maps.model.AdvancedMarkerOptions
 import com.google.android.gms.maps.model.BitmapDescriptorFactory
+import com.google.android.gms.maps.model.CameraPosition
+import com.google.android.gms.maps.model.Circle
+import com.google.android.gms.maps.model.CircleOptions
+import com.google.android.gms.maps.model.GroundOverlay
+import com.google.android.gms.maps.model.GroundOverlayOptions
 import com.google.android.gms.maps.model.LatLng
+import com.google.android.gms.maps.model.LatLngBounds
 import com.google.android.gms.maps.model.MapColorScheme
 import com.google.android.gms.maps.model.Marker
+import com.google.android.gms.maps.model.MarkerOptions
 import com.google.android.gms.maps.model.Polygon
 import com.google.android.gms.maps.model.PolygonOptions
 import com.google.android.gms.maps.model.PolylineOptions
+import com.google.android.gms.maps.model.TileOverlayOptions
+import com.google.android.gms.maps.model.UrlTileProvider
 import com.luggmaps.LuggCalloutView
+import com.luggmaps.LuggCircleView
+import com.luggmaps.LuggCircleViewDelegate
+import com.luggmaps.LuggGroundOverlayView
+import com.luggmaps.LuggGroundOverlayViewDelegate
 import com.luggmaps.LuggMapWrapperView
 import com.luggmaps.LuggMarkerView
 import com.luggmaps.LuggMarkerViewDelegate
@@ -28,6 +43,16 @@ import com.luggmaps.LuggPolygonView
 import com.luggmaps.LuggPolygonViewDelegate
 import com.luggmaps.LuggPolylineView
 import com.luggmaps.LuggPolylineViewDelegate
+import com.luggmaps.LuggTileOverlayView
+import com.luggmaps.LuggTileOverlayViewDelegate
+import com.luggmaps.extensions.findViewByTag
+import java.net.URL
+import kotlin.math.atan
+import kotlin.math.ln
+import kotlin.math.log2
+import kotlin.math.pow
+import kotlin.math.sin
+import kotlin.math.sinh
 
 class GoogleMapProvider(private val context: Context) :
   MapProvider,
@@ -35,22 +60,33 @@ class GoogleMapProvider(private val context: Context) :
   LuggMarkerViewDelegate,
   LuggPolylineViewDelegate,
   LuggPolygonViewDelegate,
+  LuggCircleViewDelegate,
+  LuggGroundOverlayViewDelegate,
+  LuggTileOverlayViewDelegate,
   GoogleMap.OnCameraMoveStartedListener,
   GoogleMap.OnCameraMoveListener,
   GoogleMap.OnCameraIdleListener,
   GoogleMap.OnMapClickListener,
   GoogleMap.OnMapLongClickListener,
   GoogleMap.OnPolygonClickListener,
+  GoogleMap.OnCircleClickListener,
+  GoogleMap.OnGroundOverlayClickListener,
   GoogleMap.OnMarkerClickListener,
   GoogleMap.OnMarkerDragListener,
-  GoogleMap.InfoWindowAdapter {
+  GoogleMap.InfoWindowAdapter,
+  ComponentCallbacks2 {
 
   override var delegate: MapProviderDelegate? = null
   override val isMapReady: Boolean get() = _isMapReady
 
   var mapId: String = DEMO_MAP_ID
 
+  // Renders a non-interactive static map — lite mode when the view fits
+  // the lite bitmap cap, a gesture-less full map otherwise. Creation-time only.
+  var staticMode: Boolean = false
+
   private var wrapperView: LuggMapWrapperView? = null
+  private var currentNightMode: Int = context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
   private var mapView: MapView? = null
   private var googleMap: GoogleMap? = null
   private var _isMapReady = false
@@ -58,10 +94,16 @@ class GoogleMapProvider(private val context: Context) :
   private val pendingMarkerViews = mutableSetOf<LuggMarkerView>()
   private val pendingPolylineViews = mutableSetOf<LuggPolylineView>()
   private val pendingPolygonViews = mutableSetOf<LuggPolygonView>()
+  private val pendingCircleViews = mutableSetOf<LuggCircleView>()
+  private val pendingGroundOverlayViews = mutableSetOf<LuggGroundOverlayView>()
+  private val pendingTileOverlayViews = mutableSetOf<LuggTileOverlayView>()
   private val polylineAnimators = mutableMapOf<LuggPolylineView, PolylineAnimator>()
   private val polygonToViewMap = mutableMapOf<Polygon, LuggPolygonView>()
+  private val circleToViewMap = mutableMapOf<Circle, LuggCircleView>()
+  private val groundOverlayToViewMap = mutableMapOf<GroundOverlay, LuggGroundOverlayView>()
   private val markerToViewMap = mutableMapOf<Marker, LuggMarkerView>()
   private val liveMarkerViews = mutableSetOf<LuggMarkerView>()
+  private var staticProjectionReady = false
   private var activeNonBubbledMarker: Marker? = null
   private var tapLocation: LatLng? = null
 
@@ -75,6 +117,7 @@ class GoogleMapProvider(private val context: Context) :
   private var scrollEnabled: Boolean = true
   private var rotateEnabled: Boolean = true
   private var pitchEnabled: Boolean = true
+  private var compassEnabled: Boolean = true
   private var userLocationEnabled: Boolean = false
   private var userLocationButtonEnabled: Boolean = false
 
@@ -88,6 +131,10 @@ class GoogleMapProvider(private val context: Context) :
   // Edge Insets
   private var edgeInsets: EdgeInsets = EdgeInsets()
 
+  // Inset adjustment
+  private var insetAdjustment: String = "never"
+  private var systemInsets: EdgeInsets = EdgeInsets()
+
   // region MapProvider
 
   override fun initializeMap(wrapperView: View, latitude: Double, longitude: Double, zoom: Float) {
@@ -98,18 +145,45 @@ class GoogleMapProvider(private val context: Context) :
     initialZoom = zoom
 
     val wrapper = wrapperView as LuggMapWrapperView
+    wrapper.relayoutChildOnRequest = staticMode
     this.wrapperView = wrapper
 
-    val options = GoogleMapOptions().mapId(mapId)
+    context.applicationContext.registerComponentCallbacks(this)
+
+    // Static mode needs the view size to pick lite vs full map, so wait
+    // for the first layout if it hasn't happened yet
+    if (staticMode && (wrapper.width == 0 || wrapper.height == 0)) {
+      wrapper.onLayoutReady = { createMapView() }
+    } else {
+      createMapView()
+    }
+  }
+
+  private fun createMapView() {
+    if (mapView != null) return
+    val wrapper = wrapperView ?: return
+
+    // Lite mode renders the map as a single bitmap capped at ~2048px per
+    // dimension, centered in the view — bigger views get letterboxed. Fall
+    // back to a full map (gestures disabled) when the view exceeds the cap
+    val useLite = staticMode && maxOf(wrapper.width, wrapper.height) <= LITE_MODE_MAX_SIZE
+    val options = GoogleMapOptions().liteMode(useLite)
+    // Lite mode doesn't support map IDs (cloud-based styling); setting one
+    // makes the static map render blank
+    if (!useLite) options.mapId(mapId)
     mapView = MapView(context, options).also { view ->
       view.onCreate(null)
       view.onResume()
       view.getMapAsync(this)
       wrapper.addView(view)
     }
+    wrapper.onLayoutReady = null
   }
 
   override fun destroy() {
+    wrapperView?.onLayoutReady = null
+    detachWindowInsetsListener()
+    context.applicationContext.unregisterComponentCallbacks(this)
     dismissNonBubbledCallout()
     for (markerView in liveMarkerViews) {
       markerView.onUpdate = null
@@ -118,9 +192,14 @@ class GoogleMapProvider(private val context: Context) :
     pendingMarkerViews.clear()
     pendingPolylineViews.clear()
     pendingPolygonViews.clear()
+    pendingCircleViews.clear()
+    pendingGroundOverlayViews.clear()
+    pendingTileOverlayViews.clear()
     polylineAnimators.values.forEach { it.destroy() }
     polylineAnimators.clear()
     polygonToViewMap.clear()
+    circleToViewMap.clear()
+    groundOverlayToViewMap.clear()
     markerToViewMap.clear()
     wrapperView?.touchEventHandler = null
     wrapperView = null
@@ -130,6 +209,8 @@ class GoogleMapProvider(private val context: Context) :
     googleMap?.setOnMapClickListener(null)
     googleMap?.setOnMapLongClickListener(null)
     googleMap?.setOnPolygonClickListener(null)
+    googleMap?.setOnCircleClickListener(null)
+    googleMap?.setOnGroundOverlayClickListener(null)
     googleMap?.setOnMarkerClickListener(null)
     googleMap?.setOnMarkerDragListener(null)
     googleMap?.setInfoWindowAdapter(null)
@@ -145,7 +226,18 @@ class GoogleMapProvider(private val context: Context) :
     googleMap = map
     _isMapReady = true
 
-    val position = LatLng(initialLatitude, initialLongitude)
+    if (staticMode) {
+      // Tapping the map otherwise shows an "open in Google Maps" toolbar
+      map.uiSettings.isMapToolbarEnabled = false
+      // The projection is only valid once the map has rendered, and no
+      // camera events fire afterwards to correct live marker positions
+      map.setOnMapLoadedCallback {
+        staticProjectionReady = true
+        positionLiveMarkers()
+      }
+    }
+
+    val position = if (staticMode) staticCameraTarget() else LatLng(initialLatitude, initialLongitude)
     map.moveCamera(CameraUpdateFactory.newLatLngZoom(position, initialZoom))
 
     map.setOnCameraMoveStartedListener(this)
@@ -154,6 +246,8 @@ class GoogleMapProvider(private val context: Context) :
     map.setOnMapClickListener(this)
     map.setOnMapLongClickListener(this)
     map.setOnPolygonClickListener(this)
+    map.setOnCircleClickListener(this)
+    map.setOnGroundOverlayClickListener(this)
     map.setOnMarkerClickListener(this)
     map.setOnMarkerDragListener(this)
     map.setInfoWindowAdapter(this)
@@ -167,11 +261,15 @@ class GoogleMapProvider(private val context: Context) :
     applyUiSettings()
     applyZoomLimits()
     applyEdgeInsets()
+    applyInsetAdjustment()
     applyTheme()
     applyUserLocation()
     processPendingMarkers()
     processPendingPolylines()
     processPendingPolygons()
+    processPendingCircles()
+    processPendingGroundOverlays()
+    processPendingTileOverlays()
 
     delegate?.mapProviderDidReady()
   }
@@ -227,6 +325,22 @@ class GoogleMapProvider(private val context: Context) :
     }
   }
 
+  override fun onCircleClick(circle: Circle) {
+    val circleView = circleToViewMap[circle]
+    if (circleView?.tappable == true) {
+      circleView.emitPressEvent()
+    } else {
+      onMapClick(tapLocation ?: return)
+    }
+  }
+
+  override fun onGroundOverlayClick(groundOverlay: GroundOverlay) {
+    val view = groundOverlayToViewMap[groundOverlay]
+    if (view?.tappable == true) {
+      view.emitPressEvent()
+    }
+  }
+
   override fun onMarkerClick(marker: Marker): Boolean {
     dismissNonBubbledCallout()
 
@@ -236,10 +350,17 @@ class GoogleMapProvider(private val context: Context) :
 
       val calloutView = view.calloutView
       if (calloutView != null && !calloutView.bubbled && calloutView.hasCustomContent) {
-        googleMap?.animateCamera(CameraUpdateFactory.newLatLng(marker.position))
+        if (view.centerOnPress) {
+          googleMap?.animateCamera(CameraUpdateFactory.newLatLng(marker.position))
+        }
         showNonBubbledCallout(marker, calloutView)
         return true
       }
+
+      if (!view.centerOnPress) {
+        marker.showInfoWindow()
+        return true
+      }
     }
     return false
   }
@@ -353,8 +474,8 @@ class GoogleMapProvider(private val context: Context) :
     val map = googleMap ?: return
 
     val point = map.projection.toScreenLocation(marker.position)
-    contentView.translationX = point.x - contentView.width * calloutView.anchorX
-    contentView.translationY = point.y - contentView.height * calloutView.anchorY
+    contentView.translationX = point.x - contentView.width / 2f + calloutView.offsetX
+    contentView.translationY = point.y - markerView.scaledContentHeight * markerView.anchorY - contentView.height + calloutView.offsetY
   }
 
   // endregion
@@ -363,24 +484,33 @@ class GoogleMapProvider(private val context: Context) :
 
   override fun setZoomEnabled(enabled: Boolean) {
     zoomEnabled = enabled
+    if (staticMode) return
     googleMap?.uiSettings?.isZoomGesturesEnabled = enabled
   }
 
   override fun setScrollEnabled(enabled: Boolean) {
     scrollEnabled = enabled
+    if (staticMode) return
     googleMap?.uiSettings?.isScrollGesturesEnabled = enabled
   }
 
   override fun setRotateEnabled(enabled: Boolean) {
     rotateEnabled = enabled
+    if (staticMode) return
     googleMap?.uiSettings?.isRotateGesturesEnabled = enabled
   }
 
   override fun setPitchEnabled(enabled: Boolean) {
     pitchEnabled = enabled
+    if (staticMode) return
     googleMap?.uiSettings?.isTiltGesturesEnabled = enabled
   }
 
+  override fun setCompassEnabled(enabled: Boolean) {
+    compassEnabled = enabled
+    googleMap?.uiSettings?.isCompassEnabled = enabled
+  }
+
   @SuppressLint("MissingPermission")
   override fun setUserLocationEnabled(enabled: Boolean) {
     userLocationEnabled = enabled
@@ -398,6 +528,15 @@ class GoogleMapProvider(private val context: Context) :
     googleMap?.uiSettings?.isMyLocationButtonEnabled = enabled
   }
 
+  override fun setMapType(value: String) {
+    googleMap?.mapType = when (value) {
+      "satellite" -> GoogleMap.MAP_TYPE_SATELLITE
+      "terrain" -> GoogleMap.MAP_TYPE_TERRAIN
+      "hybrid" -> GoogleMap.MAP_TYPE_HYBRID
+      else -> GoogleMap.MAP_TYPE_NORMAL
+    }
+  }
+
   override fun setTheme(value: String) {
     theme = value
     applyTheme()
@@ -418,6 +557,11 @@ class GoogleMapProvider(private val context: Context) :
   }
 
   override fun setEdgeInsets(edgeInsets: EdgeInsets) {
+    if (staticMode) {
+      setStaticEdgeInsets(edgeInsets)
+      return
+    }
+
     val oldInsets = this.edgeInsets
     this.edgeInsets = edgeInsets
     applyEdgeInsets()
@@ -431,13 +575,18 @@ class GoogleMapProvider(private val context: Context) :
   }
 
   override fun setEdgeInsets(edgeInsets: EdgeInsets, duration: Int) {
+    if (staticMode) {
+      setStaticEdgeInsets(edgeInsets)
+      return
+    }
+
     val map = googleMap
     val oldInsets = this.edgeInsets
     this.edgeInsets = edgeInsets
 
     if (map != null && oldInsets != edgeInsets) {
       val cameraUpdate = CameraUpdateFactory.newCameraPosition(map.cameraPosition)
-      applyEdgeInsets()
+      applyEdgeInsets(duration)
       when {
         duration < 0 -> map.animateCamera(cameraUpdate)
         duration > 0 -> map.animateCamera(cameraUpdate, duration, null)
@@ -448,6 +597,17 @@ class GoogleMapProvider(private val context: Context) :
     }
   }
 
+  override fun setInsetAdjustment(value: String) {
+    insetAdjustment = value
+    applyInsetAdjustment()
+  }
+
+  override fun setPoiEnabled(enabled: Boolean) {}
+
+  override fun setPoiFilterMode(mode: String) {}
+
+  override fun setPoiFilterCategories(categories: List<String>) {}
+
   // endregion
 
   // region MarkerViewDelegate
@@ -469,6 +629,30 @@ class GoogleMapProvider(private val context: Context) :
     syncMarkerView(markerView)
   }
 
+  override fun showCalloutForMarkerView(markerView: LuggMarkerView) {
+    val marker = markerView.marker ?: return
+    val calloutView = markerView.calloutView
+
+    if (calloutView != null && calloutView.hasCustomContent) {
+      dismissNonBubbledCallout()
+      if (calloutView.bubbled) {
+        marker.showInfoWindow()
+      } else {
+        showNonBubbledCallout(marker, calloutView)
+      }
+      return
+    }
+
+    if (!markerView.title.isNullOrEmpty()) {
+      marker.showInfoWindow()
+    }
+  }
+
+  override fun hideCalloutForMarkerView(markerView: LuggMarkerView) {
+    dismissNonBubbledCallout()
+    markerView.marker?.hideInfoWindow()
+  }
+
   // endregion
 
   // region PolylineViewDelegate
@@ -477,6 +661,10 @@ class GoogleMapProvider(private val context: Context) :
     syncPolylineView(polylineView)
   }
 
+  override fun polylineViewDidDrop(polylineView: LuggPolylineView) {
+    teardownPolyline(polylineView)
+  }
+
   // endregion
 
   // region PolygonViewDelegate
@@ -487,6 +675,30 @@ class GoogleMapProvider(private val context: Context) :
 
   // endregion
 
+  // region CircleViewDelegate
+
+  override fun circleViewDidUpdate(circleView: LuggCircleView) {
+    syncCircleView(circleView)
+  }
+
+  // endregion
+
+  // region GroundOverlayViewDelegate
+
+  override fun groundOverlayViewDidUpdate(groundOverlayView: LuggGroundOverlayView) {
+    syncGroundOverlayView(groundOverlayView)
+  }
+
+  // endregion
+
+  // region TileOverlayViewDelegate
+
+  override fun tileOverlayViewDidUpdate(tileOverlayView: LuggTileOverlayView) {
+    syncTileOverlayView(tileOverlayView)
+  }
+
+  // endregion
+
   // region Marker Management
 
   override fun addMarkerView(markerView: LuggMarkerView) {
@@ -546,12 +758,12 @@ class GoogleMapProvider(private val context: Context) :
     val map = googleMap ?: return
 
     val position = LatLng(markerView.latitude, markerView.longitude)
-    val options = AdvancedMarkerOptions()
+    val options = MarkerOptions()
       .position(position)
       .title(markerView.title)
       .snippet(markerView.description)
 
-    val marker = map.addMarker(options) as AdvancedMarker
+    val marker = map.addMarker(options) ?: return
     marker.setAnchor(markerView.anchorX, markerView.anchorY)
     marker.zIndex = markerView.zIndex
     marker.rotation = markerView.rotate
@@ -569,9 +781,8 @@ class GoogleMapProvider(private val context: Context) :
     }
   }
 
-  // Workaround: AdvancedMarker.iconView is buggy on Android, so we manually add the custom
-  // content view to the wrapper and position it via screen projection instead. The underlying
-  // marker uses a transparent bitmap matching the content size so taps still trigger onMarkerClick.
+  // Live marker: content view is added to the wrapper and positioned via screen projection.
+  // The underlying marker uses a transparent bitmap matching the content size so taps still trigger onMarkerClick.
   private fun showLiveMarker(markerView: LuggMarkerView) {
     val wrapper = wrapperView ?: return
 
@@ -582,6 +793,10 @@ class GoogleMapProvider(private val context: Context) :
 
     val contentView = markerView.contentView
     contentView.pointerEvents = com.facebook.react.uimanager.PointerEvents.NONE
+    // Until the lite map's projection is valid, hide the marker instead of
+    // flashing it at a wrong position; onMapLoaded positions and shows it
+    contentView.visibility =
+      if (staticMode && !staticProjectionReady) View.INVISIBLE else View.VISIBLE
     (contentView.parent as? android.view.ViewGroup)?.removeView(contentView)
     wrapper.addView(contentView)
     liveMarkerViews.add(markerView)
@@ -613,10 +828,12 @@ class GoogleMapProvider(private val context: Context) :
 
   private fun positionLiveMarker(markerView: LuggMarkerView) {
     val map = googleMap ?: return
+    if (staticMode && !staticProjectionReady) return
     val contentView = markerView.contentView
     val point = map.projection.toScreenLocation(LatLng(markerView.latitude, markerView.longitude))
     contentView.translationX = point.x - contentView.width * markerView.anchorX
     contentView.translationY = point.y - contentView.height * markerView.anchorY
+    contentView.visibility = View.VISIBLE
   }
 
   // endregion
@@ -629,8 +846,12 @@ class GoogleMapProvider(private val context: Context) :
   }
 
   override fun removePolylineView(polylineView: LuggPolylineView) {
-    polylineAnimators[polylineView]?.destroy()
-    polylineAnimators.remove(polylineView)
+    teardownPolyline(polylineView)
+  }
+
+  private fun teardownPolyline(polylineView: LuggPolylineView) {
+    pendingPolylineViews.remove(polylineView)
+    polylineAnimators.remove(polylineView)?.destroy()
     polylineView.polyline?.remove()
     polylineView.polyline = null
   }
@@ -646,15 +867,13 @@ class GoogleMapProvider(private val context: Context) :
       return
     }
 
-    polylineView.polyline?.width = polylineView.strokeWidth.dpToPx()
-    polylineView.polyline?.zIndex = polylineView.zIndex
-
     polylineAnimators[polylineView]?.apply {
       coordinates = polylineView.coordinates
       strokeColors = polylineView.strokeColors
       strokeWidth = polylineView.strokeWidth.dpToPx()
+      zIndex = polylineView.zIndex
       animatedOptions = polylineView.animatedOptions
-      animated = polylineView.animated
+      animated = polylineView.animated && !staticMode
       update()
     }
   }
@@ -668,6 +887,8 @@ class GoogleMapProvider(private val context: Context) :
   private fun addPolylineViewToMap(polylineView: LuggPolylineView) {
     val map = googleMap ?: return
 
+    polylineAnimators.remove(polylineView)?.destroy()
+
     val options = PolylineOptions()
       .width(polylineView.strokeWidth.dpToPx())
       .zIndex(polylineView.zIndex)
@@ -680,8 +901,10 @@ class GoogleMapProvider(private val context: Context) :
       coordinates = polylineView.coordinates
       strokeColors = polylineView.strokeColors
       strokeWidth = polylineView.strokeWidth.dpToPx()
+      zIndex = polylineView.zIndex
       animatedOptions = polylineView.animatedOptions
-      animated = polylineView.animated
+      // Static maps render once; show the full polyline instead of animating
+      animated = polylineView.animated && !staticMode
       update()
     }
 
@@ -753,6 +976,218 @@ class GoogleMapProvider(private val context: Context) :
 
   // endregion
 
+  // region Circle Management
+
+  override fun addCircleView(circleView: LuggCircleView) {
+    circleView.delegate = this
+    syncCircleView(circleView)
+  }
+
+  override fun removeCircleView(circleView: LuggCircleView) {
+    circleView.circle?.let { circleToViewMap.remove(it) }
+    circleView.circle?.remove()
+    circleView.circle = null
+  }
+
+  private fun syncCircleView(circleView: LuggCircleView) {
+    if (googleMap == null) {
+      pendingCircleViews.add(circleView)
+      return
+    }
+
+    if (circleView.circle == null) {
+      addCircleViewToMap(circleView)
+      return
+    }
+
+    circleView.circle?.apply {
+      center = circleView.center
+      radius = circleView.radius
+      fillColor = circleView.fillColor
+      strokeColor = circleView.strokeColor
+      strokeWidth = circleView.strokeWidth.dpToPx()
+      zIndex = circleView.zIndex
+      isClickable = true
+    }
+  }
+
+  private fun processPendingCircles() {
+    if (googleMap == null) return
+    pendingCircleViews.forEach { addCircleViewToMap(it) }
+    pendingCircleViews.clear()
+  }
+
+  private fun addCircleViewToMap(circleView: LuggCircleView) {
+    val map = googleMap ?: return
+
+    val options = CircleOptions()
+      .center(circleView.center)
+      .radius(circleView.radius)
+      .fillColor(circleView.fillColor)
+      .strokeColor(circleView.strokeColor)
+      .strokeWidth(circleView.strokeWidth.dpToPx())
+      .zIndex(circleView.zIndex)
+      .clickable(true)
+
+    val circle = map.addCircle(options)
+    circleView.circle = circle
+    circleToViewMap[circle] = circleView
+  }
+
+  // endregion
+
+  // region Ground Overlay Management
+
+  override fun addGroundOverlayView(groundOverlayView: LuggGroundOverlayView) {
+    groundOverlayView.delegate = this
+    syncGroundOverlayView(groundOverlayView)
+  }
+
+  override fun removeGroundOverlayView(groundOverlayView: LuggGroundOverlayView) {
+    groundOverlayView.delegate = null
+    groundOverlayView.groundOverlay?.let { groundOverlayToViewMap.remove(it) }
+    groundOverlayView.groundOverlay?.remove()
+    groundOverlayView.groundOverlay = null
+  }
+
+  private fun syncGroundOverlayView(groundOverlayView: LuggGroundOverlayView) {
+    if (googleMap == null) {
+      pendingGroundOverlayViews.add(groundOverlayView)
+      return
+    }
+
+    val imageUri = groundOverlayView.imageUri
+    if (imageUri.isEmpty()) return
+
+    // Remove old overlay
+    groundOverlayView.groundOverlay?.let { groundOverlayToViewMap.remove(it) }
+    groundOverlayView.groundOverlay?.remove()
+    groundOverlayView.groundOverlay = null
+
+    // Load image async and add overlay
+    Thread {
+      try {
+        val connection = URL(imageUri).openConnection() as java.net.HttpURLConnection
+        connection.instanceFollowRedirects = true
+        connection.connect()
+        val bitmap = android.graphics.BitmapFactory.decodeStream(connection.inputStream)
+        connection.disconnect()
+        if (bitmap != null) {
+          mapView?.post {
+            addGroundOverlayToMap(groundOverlayView, bitmap)
+          }
+        }
+      } catch (_: Exception) {}
+    }.start()
+  }
+
+  private fun addGroundOverlayToMap(groundOverlayView: LuggGroundOverlayView, bitmap: android.graphics.Bitmap) {
+    val map = googleMap ?: return
+
+    val bounds = LatLngBounds(groundOverlayView.southwest, groundOverlayView.northeast)
+    val options = GroundOverlayOptions()
+      .image(BitmapDescriptorFactory.fromBitmap(bitmap))
+      .positionFromBounds(bounds)
+      .transparency(1f - groundOverlayView.overlayOpacity)
+      .bearing(groundOverlayView.bearing)
+      .zIndex(groundOverlayView.zIndex)
+      .clickable(groundOverlayView.tappable)
+
+    val overlay = map.addGroundOverlay(options)
+    if (overlay != null) {
+      groundOverlayView.groundOverlay = overlay
+      groundOverlayToViewMap[overlay] = groundOverlayView
+    }
+  }
+
+  private fun processPendingGroundOverlays() {
+    if (googleMap == null) return
+    pendingGroundOverlayViews.forEach { syncGroundOverlayView(it) }
+    pendingGroundOverlayViews.clear()
+  }
+
+  // endregion
+
+  // region Tile Overlay Management
+
+  override fun addTileOverlayView(tileOverlayView: LuggTileOverlayView) {
+    tileOverlayView.delegate = this
+    syncTileOverlayView(tileOverlayView)
+  }
+
+  override fun removeTileOverlayView(tileOverlayView: LuggTileOverlayView) {
+    tileOverlayView.delegate = null
+    tileOverlayView.tileOverlay?.remove()
+    tileOverlayView.tileOverlay = null
+  }
+
+  private fun syncTileOverlayView(tileOverlayView: LuggTileOverlayView) {
+    if (googleMap == null) {
+      pendingTileOverlayViews.add(tileOverlayView)
+      return
+    }
+
+    val urlTemplate = tileOverlayView.urlTemplate
+    if (urlTemplate.isEmpty()) return
+
+    // Remove old overlay
+    tileOverlayView.tileOverlay?.remove()
+    tileOverlayView.tileOverlay = null
+
+    val tileSize = tileOverlayView.tileSize
+    val hasBounds = tileOverlayView.hasBounds
+    val swLat = tileOverlayView.boundsSwLat
+    val swLng = tileOverlayView.boundsSwLng
+    val neLat = tileOverlayView.boundsNeLat
+    val neLng = tileOverlayView.boundsNeLng
+
+    val tileProvider = object : UrlTileProvider(tileSize, tileSize) {
+      override fun getTileUrl(x: Int, y: Int, zoom: Int): URL? {
+        if (hasBounds) {
+          val n = 2.0.pow(zoom.toDouble())
+          val tileSWLat = Math.toDegrees(atan(sinh(Math.PI * (1 - 2.0 * (y + 1) / n))))
+          val tileNELat = Math.toDegrees(atan(sinh(Math.PI * (1 - 2.0 * y / n))))
+          val tileSWLng = x / n * 360.0 - 180.0
+          val tileNELng = (x + 1) / n * 360.0 - 180.0
+
+          if (tileNELat < swLat ||
+            tileSWLat > neLat ||
+            tileNELng < swLng ||
+            tileSWLng > neLng
+          ) {
+            return null
+          }
+        }
+
+        val url = urlTemplate
+          .replace("{x}", x.toString())
+          .replace("{y}", y.toString())
+          .replace("{z}", zoom.toString())
+        return try {
+          URL(url)
+        } catch (_: Exception) {
+          null
+        }
+      }
+    }
+
+    val options = TileOverlayOptions()
+      .tileProvider(tileProvider)
+      .transparency(1f - tileOverlayView.overlayOpacity)
+      .zIndex(tileOverlayView.zIndex)
+
+    val overlay = googleMap?.addTileOverlay(options)
+    tileOverlayView.tileOverlay = overlay
+  }
+
+  private fun processPendingTileOverlays() {
+    if (googleMap == null) return
+    pendingTileOverlayViews.forEach { syncTileOverlayView(it) }
+    pendingTileOverlayViews.clear()
+  }
+
+  // endregion
+
   // region Lifecycle
 
   override fun pauseAnimations() {
@@ -768,10 +1203,25 @@ class GoogleMapProvider(private val context: Context) :
   // region Commands
 
   override fun moveCamera(latitude: Double, longitude: Double, zoom: Double, duration: Int) {
+    if (staticMode) {
+      // Static maps don't animate; re-center at the final camera
+      initialLatitude = latitude
+      initialLongitude = longitude
+      if (zoom > 0) initialZoom = zoom.toFloat()
+      val map = googleMap ?: return
+      map.moveCamera(CameraUpdateFactory.newLatLngZoom(staticCameraTarget(), initialZoom))
+      positionLiveMarkers()
+      return
+    }
+
     val map = googleMap ?: return
     val position = LatLng(latitude, longitude)
     val targetZoom = if (zoom > 0) zoom.toFloat() else map.cameraPosition.zoom
-    val cameraUpdate = CameraUpdateFactory.newLatLngZoom(position, targetZoom)
+    val cameraPosition = CameraPosition.Builder(map.cameraPosition)
+      .target(position)
+      .zoom(targetZoom)
+      .build()
+    val cameraUpdate = CameraUpdateFactory.newCameraPosition(cameraPosition)
     when {
       duration < 0 -> map.animateCamera(cameraUpdate)
       duration > 0 -> map.animateCamera(cameraUpdate, duration, null)
@@ -790,23 +1240,29 @@ class GoogleMapProvider(private val context: Context) :
     val map = googleMap ?: return
     if (coordinates.isEmpty()) return
 
-    val latLngs = coordinates.filterIsInstance<LatLng>()
-    if (latLngs.isEmpty()) return
-
-    val boundsBuilder = com.google.android.gms.maps.model.LatLngBounds.Builder()
-    latLngs.forEach { boundsBuilder.include(it) }
-    val bounds = boundsBuilder.build()
+    val latLongs = coordinates.filterIsInstance<LatLng>()
+    if (latLongs.isEmpty()) return
 
     val top = edgeInsetsTop.toFloat().dpToPx().toInt()
     val left = edgeInsetsLeft.toFloat().dpToPx().toInt()
     val bottom = edgeInsetsBottom.toFloat().dpToPx().toInt()
     val right = edgeInsetsRight.toFloat().dpToPx().toInt()
 
+    if (staticMode) {
+      fitStaticCoordinates(latLongs, top, left, bottom, right)
+      return
+    }
+
+    val boundsBuilder = LatLngBounds.Builder()
+    latLongs.forEach { boundsBuilder.include(it) }
+    val bounds = boundsBuilder.build()
+
+    val combined = combinedEdgeInsets()
     map.setPadding(
-      edgeInsets.left + left,
-      edgeInsets.top + top,
-      edgeInsets.right + right,
-      edgeInsets.bottom + bottom
+      combined.left + left,
+      combined.top + top,
+      combined.right + right,
+      combined.bottom + bottom
     )
 
     val cameraUpdate = CameraUpdateFactory.newLatLngBounds(bounds, 0)
@@ -817,7 +1273,7 @@ class GoogleMapProvider(private val context: Context) :
       else -> map.moveCamera(cameraUpdate)
     }
 
-    map.setPadding(edgeInsets.left, edgeInsets.top, edgeInsets.right, edgeInsets.bottom)
+    map.setPadding(combined.left, combined.top, combined.right, combined.bottom)
   }
 
   // endregion
@@ -826,10 +1282,17 @@ class GoogleMapProvider(private val context: Context) :
 
   private fun applyUiSettings() {
     googleMap?.uiSettings?.apply {
+      if (staticMode) {
+        // The non-lite fallback is a full map; keep it behaving like a
+        // static image (lite mode ignores gestures anyway)
+        setAllGesturesEnabled(false)
+        return
+      }
       isZoomGesturesEnabled = zoomEnabled
       isScrollGesturesEnabled = scrollEnabled
       isRotateGesturesEnabled = rotateEnabled
       isTiltGesturesEnabled = pitchEnabled
+      isCompassEnabled = compassEnabled
       isMyLocationButtonEnabled = userLocationButtonEnabled
     }
   }
@@ -841,17 +1304,190 @@ class GoogleMapProvider(private val context: Context) :
     }
   }
 
-  private fun applyEdgeInsets() {
-    googleMap?.setPadding(edgeInsets.left, edgeInsets.top, edgeInsets.right, edgeInsets.bottom)
+  private fun applyInsetAdjustment() {
+    if (insetAdjustment == "automatic") {
+      attachWindowInsetsListener()
+    } else {
+      detachWindowInsetsListener()
+      systemInsets = EdgeInsets()
+    }
+    applyEdgeInsets()
+  }
+
+  private fun combinedEdgeInsets(): EdgeInsets =
+    if (insetAdjustment == "automatic") {
+      EdgeInsets(
+        edgeInsets.top + systemInsets.top,
+        edgeInsets.left + systemInsets.left,
+        edgeInsets.bottom + systemInsets.bottom,
+        edgeInsets.right + systemInsets.right
+      )
+    } else {
+      edgeInsets
+    }
+
+  private fun applyEdgeInsets(duration: Int = 0) {
+    val combined = combinedEdgeInsets()
+    // Lite mode misrenders padding: the static image is drawn only within
+    // the padded viewport instead of the full view. The camera target shift
+    // (staticCameraTarget) compensates for insets instead.
+    if (!staticMode) {
+      googleMap?.setPadding(combined.left, combined.top, combined.right, combined.bottom)
+    }
+    applyWatermarkTranslation(combined, duration)
+  }
+
+  // Insets are applied by shifting the camera target so the coordinate
+  // centers in the inset viewport like a live map would (see
+  // applyEdgeInsets for why padding can't be used)
+  private fun setStaticEdgeInsets(edgeInsets: EdgeInsets) {
+    val oldInsets = this.edgeInsets
+    this.edgeInsets = edgeInsets
+    applyEdgeInsets()
+
+    val map = googleMap
+    if (map != null && oldInsets != edgeInsets) {
+      map.moveCamera(CameraUpdateFactory.newLatLngZoom(staticCameraTarget(), initialZoom))
+      positionLiveMarkers()
+    }
   }
 
+  private fun staticCameraTarget(): LatLng {
+    val offsetX = (edgeInsets.left - edgeInsets.right) / 2.0
+    val offsetY = (edgeInsets.top - edgeInsets.bottom) / 2.0
+    if (offsetX == 0.0 && offsetY == 0.0) return LatLng(initialLatitude, initialLongitude)
+
+    val worldSize = mercatorWorldSize(initialZoom)
+    return latLngFromMercator(
+      mercatorX(initialLongitude) - offsetX / worldSize,
+      mercatorY(initialLatitude) - offsetY / worldSize
+    )
+  }
+
+  // A static camera can't fit with map padding (lite mode misrenders it);
+  // compute the fitted camera in mercator space instead, shifting the
+  // center for asymmetric padding like edge insets
+  private fun fitStaticCoordinates(
+    coordinates: List<LatLng>,
+    top: Int,
+    left: Int,
+    bottom: Int,
+    right: Int
+  ) {
+    val map = googleMap ?: return
+    val wrapper = wrapperView ?: return
+    if (wrapper.width == 0 || wrapper.height == 0) return
+
+    var minX = Double.MAX_VALUE
+    var minY = Double.MAX_VALUE
+    var maxX = -Double.MAX_VALUE
+    var maxY = -Double.MAX_VALUE
+    for (coordinate in coordinates) {
+      val x = mercatorX(coordinate.longitude)
+      val y = mercatorY(coordinate.latitude)
+      minX = minOf(minX, x)
+      maxX = maxOf(maxX, x)
+      minY = minOf(minY, y)
+      maxY = maxOf(maxY, y)
+    }
+
+    val insets = combinedEdgeInsets()
+    val availWidth = (wrapper.width - insets.left - insets.right - left - right).coerceAtLeast(1)
+    val availHeight = (wrapper.height - insets.top - insets.bottom - top - bottom).coerceAtLeast(1)
+
+    // World size in px at which the bounds fit the padded viewport;
+    // infinite for coincident coordinates - keep the current zoom then
+    val fitWorldSize = minOf(availWidth / (maxX - minX), availHeight / (maxY - minY))
+    if (fitWorldSize.isFinite()) {
+      initialZoom = log2(fitWorldSize / 256f.dpToPx())
+        .toFloat()
+        .coerceIn(map.minZoomLevel, map.maxZoomLevel)
+    }
+
+    val worldSize = mercatorWorldSize(initialZoom)
+    val center = latLngFromMercator(
+      (minX + maxX) / 2.0 - (left - right) / 2.0 / worldSize,
+      (minY + maxY) / 2.0 - (top - bottom) / 2.0 / worldSize
+    )
+    initialLatitude = center.latitude
+    initialLongitude = center.longitude
+
+    map.moveCamera(CameraUpdateFactory.newLatLngZoom(staticCameraTarget(), initialZoom))
+    positionLiveMarkers()
+  }
+
+  // Web mercator world space in [0, 1]
+  private fun mercatorX(longitude: Double): Double = (longitude + 180.0) / 360.0
+
+  private fun mercatorY(latitude: Double): Double {
+    val sinLat = sin(Math.toRadians(latitude))
+    return 0.5 - ln((1.0 + sinLat) / (1.0 - sinLat)) / (4.0 * Math.PI)
+  }
+
+  private fun latLngFromMercator(x: Double, y: Double): LatLng =
+    LatLng(Math.toDegrees(atan(sinh(Math.PI * (1.0 - 2.0 * y)))), x * 360.0 - 180.0)
+
+  // World size in px at the given zoom
+  private fun mercatorWorldSize(zoom: Float): Double = 256f.dpToPx().toDouble() * 2.0.pow(zoom.toDouble())
+
+  private fun applyWatermarkTranslation(insets: EdgeInsets, duration: Int = 0) {
+    val view = mapView ?: return
+    view.findViewByTag("GoogleWatermark")?.let { watermark ->
+      val targetY = -insets.bottom.toFloat()
+      val targetX = insets.left.toFloat()
+      if (duration > 0) {
+        watermark.animate()
+          .translationY(targetY)
+          .translationX(targetX)
+          .setDuration(duration.toLong())
+          .start()
+      } else if (duration < 0) {
+        watermark.animate()
+          .translationY(targetY)
+          .translationX(targetX)
+          .start()
+      } else {
+        watermark.translationY = targetY
+        watermark.translationX = targetX
+      }
+    }
+  }
+
+  private fun attachWindowInsetsListener() {
+    val view = mapView ?: return
+    ViewCompat.setOnApplyWindowInsetsListener(view) { _, windowInsets ->
+      val insets = windowInsets.getInsets(WindowInsetsCompat.Type.systemBars())
+      systemInsets = EdgeInsets(insets.top, insets.left, insets.bottom, insets.right)
+      applyEdgeInsets()
+      windowInsets
+    }
+    ViewCompat.requestApplyInsets(view)
+  }
+
+  private fun detachWindowInsetsListener() {
+    mapView?.let { ViewCompat.setOnApplyWindowInsetsListener(it, null) }
+  }
+
+  override fun onConfigurationChanged(newConfig: Configuration) {
+    val newNightMode = newConfig.uiMode and Configuration.UI_MODE_NIGHT_MASK
+    if (newNightMode != currentNightMode) {
+      currentNightMode = newNightMode
+      applyTheme()
+    }
+  }
+
+  @Deprecated("Deprecated in Java")
+  override fun onLowMemory() {}
+
+  override fun onTrimMemory(level: Int) {}
+
   private fun applyTheme() {
     val colorScheme = when (theme) {
       "dark" -> MapColorScheme.DARK
       "light" -> MapColorScheme.LIGHT
       else -> MapColorScheme.FOLLOW_SYSTEM
     }
-    googleMap?.setMapColorScheme(colorScheme)
+    googleMap?.mapColorScheme = colorScheme
   }
 
   @SuppressLint("MissingPermission")
@@ -870,5 +1506,9 @@ class GoogleMapProvider(private val context: Context) :
 
   companion object {
     const val DEMO_MAP_ID = "DEMO_MAP_ID"
+
+    // Undocumented cap on the lite mode bitmap (2048 minus a 2px border,
+    // measured empirically)
+    private const val LITE_MODE_MAX_SIZE = 2046
   }
 }