@maydon_tech/react-native-nitro-maps 0.1.4 → 0.2.1

package/android/src/main/kotlin/com/margelo/nitro/nitromap/providers/google/GoogleMapProvider.kt

@@ -0,0 +1,815 @@
+package com.margelo.nitro.nitromap.providers.google
+
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import android.content.res.Resources
+import android.util.Log
+import android.view.View
+import com.google.android.gms.maps.CameraUpdateFactory
+import com.google.android.gms.maps.GoogleMap
+import com.google.android.gms.maps.model.CameraPosition
+import com.google.android.gms.maps.model.LatLng
+import com.google.android.gms.maps.model.LatLngBounds
+import com.google.android.gms.maps.model.Marker
+import com.google.android.gms.maps.model.Polyline
+import com.google.android.gms.maps.model.Polygon
+import com.google.android.gms.maps.model.Circle
+import com.google.android.gms.maps.model.MapColorScheme
+import com.google.android.gms.maps.model.MapStyleOptions
+import android.os.Bundle
+import com.margelo.nitro.nitromap.*
+import com.margelo.nitro.nitromap.markers.MarkerIconFactory
+import com.margelo.nitro.nitromap.providers.MapProviderInterface
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import java.util.concurrent.ConcurrentLinkedQueue
+import kotlin.math.abs
+import kotlin.math.ln
+import kotlin.math.pow
+import kotlin.math.roundToInt
+
+/**
+ * Google Maps implementation of the map provider.
+ *
+ * The core challenge: GoogleMap is ASYNC — available only after getMapAsync().
+ * All operations use withMap {} to queue commands until the map is ready.
+ *
+ * This class holds all map data (markers, overlays, settings) in Kotlin data structures
+ * that survive MapView detach/reattach cycles. Only native GoogleMap objects are recreated.
+ */
+class GoogleMapProvider(internal val context: Context) : MapProviderInterface {
+
+    companion object {
+        private const val TAG = "NitroMap"
+        private const val DEFAULT_LATITUDE = 41.2995
+        private const val DEFAULT_LONGITUDE = 69.2401
+        private const val DEFAULT_ZOOM = 10f
+        private const val BASE_ALTITUDE = 40_000_000.0 // meters at zoom 0, matches iOS
+
+    }
+
+    // MARK: - MapView Lifecycle (absorbed from NitroMap facade)
+
+    private var mapView: NitroMapView? = null
+    private var savedState: Bundle? = null
+
+    override fun createMapView(context: Context): View {
+        val mv = NitroMapView(context)
+        mv.onCreate(savedState)
+        mv.onStart()
+        mv.onResume()
+        mapView = mv
+        return mv
+    }
+
+    override fun onViewAttached(view: View) {
+        val mv = view as NitroMapView
+        mv.getMapAsync { googleMap ->
+            onMapReady(googleMap, mv)
+        }
+    }
+
+    override fun onViewDetaching() {
+        mapView?.let { mv ->
+            val state = Bundle()
+            mv.onSaveInstanceState(state)
+            savedState = state
+            mv.onPause()
+            mv.onStop()
+        }
+        onMapDetaching()
+        mapView = null
+    }
+
+    override fun onViewDestroying() {
+        onMapDestroying()
+        mapView?.let { mv ->
+            mv.onPause()
+            mv.onStop()
+            mv.onDestroy()
+        }
+        mapView = null
+        savedState = null
+    }
+
+    // MARK: - GoogleMap Reference + Command Queue
+
+    var googleMap: GoogleMap? = null
+        private set
+    @Volatile
+    private var isMapReady = false
+    // C-1: Thread-safe queue — accessed from JS thread (add) and main thread (flush)
+    private val pendingCommands = ConcurrentLinkedQueue<(GoogleMap) -> Unit>()
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    // C-3: Structured coroutine scope — cancelled on destroy to prevent leaks
+    val providerScope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
+
+    // Icon factory — created lazily on first onMapReady, cleared on destroy
+    var iconFactory: MarkerIconFactory? = null
+        private set
+
+    /**
+     * Execute a command on GoogleMap, always on the main thread.
+     * If map isn't ready, queue it. When onMapReady fires, all queued commands
+     * are flushed in order on the main thread.
+     *
+     * IMPORTANT: GoogleMap API calls MUST run on the main thread.
+     * Methods called from JS arrive on a background thread (NativeRunnable),
+     * so we always post to mainHandler.
+     */
+    fun withMap(command: (GoogleMap) -> Unit) {
+        val map = googleMap
+        if (map != null && isMapReady) {
+            if (Looper.myLooper() == Looper.getMainLooper()) {
+                command(map)
+            } else {
+                mainHandler.post { command(map) }
+            }
+        } else {
+            // C-1: ConcurrentLinkedQueue.add is thread-safe
+            pendingCommands.add(command)
+        }
+    }
+
+    // MARK: - Delegate
+
+    private var delegate: GoogleMapDelegate? = null
+
+    // MARK: - State (survives detach/reattach)
+
+    // Stored prop values — applied to new GoogleMap on reattach.
+    // Props with withMap {} setters are live-applied when changed by React.
+    // applyAllSettings() bulk-applies all stored values on map ready / reattach.
+
+    // M-7: Track whether initialRegion has been applied to prevent reapply on reattach
+    private var initialRegionApplied = false
+
+    override var initialRegion: Region? = Region(DEFAULT_LATITUDE, DEFAULT_LONGITUDE, 0.15, 0.15)
+
+    override var region: Region? = null
+        set(value) {
+            field = value
+            if (value == null) return
+            withMap { map ->
+                val currentPos = map.cameraPosition.target
+                val latDiff = abs(currentPos.latitude - value.latitude)
+                val lonDiff = abs(currentPos.longitude - value.longitude)
+                if (latDiff < 0.0001 && lonDiff < 0.0001) return@withMap
+                val camera = CameraPosition.Builder()
+                    .target(LatLng(value.latitude, value.longitude))
+                    .zoom(calculateZoom(value))
+                    .build()
+                map.animateCamera(CameraUpdateFactory.newCameraPosition(camera))
+            }
+        }
+
+    override var showsUserLocation: Boolean? = null
+
+    override var zoomEnabled: Boolean? = null
+        set(value) { field = value; withMap { it.uiSettings.isZoomGesturesEnabled = value ?: true } }
+
+    override var scrollEnabled: Boolean? = null
+        set(value) { field = value; withMap { it.uiSettings.isScrollGesturesEnabled = value ?: true } }
+
+    override var rotateEnabled: Boolean? = null
+        set(value) { field = value; withMap { it.uiSettings.isRotateGesturesEnabled = value ?: true } }
+
+    override var pitchEnabled: Boolean? = null
+        set(value) { field = value; withMap { it.uiSettings.isTiltGesturesEnabled = value ?: true } }
+
+    override var mapType: MapType? = null
+        set(value) { field = value; withMap { it.mapType = convertMapType(value) } }
+
+    override var customMapStyle: Array<MapStyleElement>? = null
+        set(value) { field = value; withMap { applyMapStyleInternal(it) } }
+
+    override var clusterConfig: ClusterConfig? = null
+        set(value) { field = value; updateClusterConfig() }
+
+    override var mapPadding: EdgePadding = EdgePadding(0.0, 0.0, 0.0, 0.0)
+        set(value) {
+            field = value
+            // M-6: Standardize on context.resources.displayMetrics.density
+            val density = context.resources.displayMetrics.density
+            withMap {
+                it.setPadding(
+                    (value.left * density).roundToInt(),
+                    (value.top * density).roundToInt(),
+                    (value.right * density).roundToInt(),
+                    (value.bottom * density).roundToInt()
+                )
+            }
+        }
+
+    override var showsTraffic: Boolean? = null
+        set(value) { field = value; withMap { it.isTrafficEnabled = value ?: false } }
+
+    override var showsBuildings: Boolean? = null
+        set(value) { field = value; withMap { it.isBuildingsEnabled = value ?: true } }
+
+    override var showsCompass: Boolean? = null
+        set(value) { field = value; withMap { it.uiSettings.isCompassEnabled = value ?: true } }
+
+    // L-2: Align with iOS default (1.0, not 0.0)
+    override var minZoom: Double = 1.0
+        set(value) { field = value; withMap { it.setMinZoomPreference(value.toFloat()) } }
+
+    // L-1: Align with facade default (22.0, not 21.0)
+    override var maxZoom: Double = 22.0
+        set(value) { field = value; withMap { it.setMaxZoomPreference(value.toFloat()) } }
+
+    override var darkMode: Boolean? = null
+        set(value) { field = value; withMap { applyMapStyleInternal(it) } }
+
+    override var userTrackingMode: UserTrackingMode? = null
+    override var userLocationImage: String = ""
+    override var userLocationSize: Double = 40.0
+    override var userLocationAnchor: Point? = null
+        set(value) {
+            field = value
+            // Update anchor on existing custom marker (parity with iOS)
+            customUserLocationMarker?.setAnchor(
+                value?.x?.toFloat() ?: 0.5f,
+                value?.y?.toFloat() ?: 0.5f
+            )
+        }
+
+    // Marker/overlay data — survives detach, re-applied on reattach
+    val markerData = mutableMapOf<String, MarkerData>()
+    val polylineData = mutableMapOf<String, PolylineData>()
+    val renderedPolylines = mutableMapOf<String, Polyline>()
+    val polygonData = mutableMapOf<String, PolygonData>()
+    val renderedPolygons = mutableMapOf<String, Polygon>()
+    val circleData = mutableMapOf<String, CircleData>()
+    val renderedCircles = mutableMapOf<String, Circle>()
+
+    var selectedMarkerId: String? = null
+
+    // User location state (used by GoogleMapProvider+UserLocation.kt)
+    var lastKnownUserLocation: android.location.Location? = null
+    var lastKnownHeading: Float? = null
+    var customUserLocationMarker: Marker? = null
+    var cachedUserLocationImageUrl: String = ""
+    var userLocationImageBitmap: android.graphics.Bitmap? = null
+    var userLocationPositionAnimator: android.animation.ValueAnimator? = null
+    var userLocationRotationAnimator: android.animation.ValueAnimator? = null
+
+    /**
+     * Set to true while updateUserLocation is animating the camera for follow mode.
+     * Cleared in onCameraIdle. When true, clustering is skipped because the
+     * zoom level hasn't changed — only the center shifted slightly to follow the user.
+     */
+    @Volatile var isFollowingUserCamera: Boolean = false
+
+    /**
+     * M-3: Set to true when markers are added/removed. Cleared after clustering runs.
+     * When isFollowingUserCamera is true, clustering is only skipped if this is false
+     * (i.e., no marker changes since last cluster run).
+     */
+    @Volatile var clusteringDirty: Boolean = false
+    var lastClusteredZoom: Float = -1f
+
+    // Clustering state (used by GoogleMapProvider+Clustering.kt)
+    var clusteringManager: com.margelo.nitro.nitromap.clustering.ClusteringManager? = null
+    val renderedClusterMarkers = mutableListOf<Marker>()
+    val renderedSingleMarkers = mutableMapOf<String, Marker>()
+    val nonClusteredMarkers = mutableMapOf<String, Marker>()
+    val hiddenNonClusteredIds = mutableSetOf<String>()
+    // H-3: Removed clusterableMarkerData — markerData is now the single source of truth.
+    // All markers are fed to the clustering engine; non-clusterable ones also get direct markers.
+    var throttleActive = false
+    var currentMapView: android.view.View? = null
+
+    // MARK: - Callbacks (set by NitroMap from JS props)
+
+    override var onPress: ((MapPressEvent) -> Unit)? = null
+    override var onLongPress: ((MapPressEvent) -> Unit)? = null
+    override var onMapReadyCallback: (() -> Unit)? = null
+    override var onRegionChange: ((RegionChangeEvent) -> Unit)? = null
+    override var onRegionChangeComplete: ((RegionChangeEvent) -> Unit)? = null
+    override var onMarkerPress: ((MarkerPressEvent) -> Unit)? = null
+    override var onMarkerDragStart: ((MarkerDragEvent) -> Unit)? = null
+    override var onMarkerDrag: ((MarkerDragEvent) -> Unit)? = null
+    override var onMarkerDragEnd: ((MarkerDragEvent) -> Unit)? = null
+    override var onClusterPress: ((ClusterPressEvent) -> Unit)? = null
+    override var onError: ((MapError) -> Unit)? = null
+    override var onMapIdle: (() -> Unit)? = null
+    override var onPolylinePress: ((String) -> Unit)? = null
+    override var onPolygonPress: ((String) -> Unit)? = null
+    override var onCirclePress: ((String) -> Unit)? = null
+    override var onUserLocationChange: ((UserLocationChangeEvent) -> Unit)? = null
+    override var onUserTrackingModeChange: ((UserTrackingMode) -> Unit)? = null
+    override var onUserLocationError: ((MapError) -> Unit)? = null
+
+    // MARK: - Map Lifecycle
+
+    fun onMapReady(map: GoogleMap, mapView: View? = null) {
+        googleMap = map
+        isMapReady = true
+        currentMapView = mapView
+
+        // Create icon factory (holds an LruCache — keep alive across onMapReady calls)
+        if (iconFactory == null) {
+            // C-3: Pass providerScope so async image loads are cancelled on destroy
+            iconFactory = MarkerIconFactory(context, providerScope).also { factory ->
+                factory.onIconLoaded = { markerId, icon ->
+                    // When async URL image loads, update the rendered marker icon in-place
+                    renderedSingleMarkers[markerId]?.setIcon(icon)
+                    nonClusteredMarkers[markerId]?.setIcon(icon)
+                }
+            }
+        }
+
+        // Create clustering manager (keep alive across onMapReady calls)
+        if (clusteringManager == null) {
+            clusteringManager = com.margelo.nitro.nitromap.clustering.ClusteringManager().also {
+                it.setDensity(context.resources.displayMetrics.density)
+                it.clusterConfig = clusterConfig
+            }
+        }
+
+        // Set up delegate for all listeners
+        delegate = GoogleMapDelegate(this)
+        delegate?.setupListeners(map)
+
+        // Apply all stored settings
+        applyAllSettings(map)
+
+        // C-1: Drain thread-safe queue (poll returns null when empty)
+        var commandCount = 0
+        while (true) {
+            val cmd = pendingCommands.poll() ?: break
+            cmd(map)
+            commandCount++
+        }
+
+        // Fire JS callback
+        onMapReadyCallback?.invoke()
+
+        Log.d(TAG, "GoogleMap ready, flushed $commandCount queued commands")
+    }
+
+    /**
+     * Called on view detach — releases GoogleMap ref but keeps data.
+     */
+    fun onMapDetaching() {
+        // Clear native object references (they're invalidated anyway)
+        renderedPolylines.clear()
+        renderedPolygons.clear()
+        renderedCircles.clear()
+        renderedClusterMarkers.clear()
+        renderedSingleMarkers.clear()
+        nonClusteredMarkers.clear()
+        hiddenNonClusteredIds.clear()
+        customUserLocationMarker = null
+
+        // Cancel user location animators to prevent updates after detach
+        userLocationPositionAnimator?.cancel()
+        userLocationRotationAnimator?.cancel()
+
+        // Drain stale commands — they reference the old GoogleMap instance
+        pendingCommands.clear()
+
+        // Release GoogleMap ref
+        googleMap = null
+        isMapReady = false
+        delegate = null
+        currentMapView = null
+
+        Log.d(TAG, "Map detaching — GoogleMap ref released, data preserved")
+    }
+
+    /**
+     * Called on dispose() — full cleanup.
+     */
+    fun onMapDestroying() {
+        onMapDetaching()
+
+        // M-4: Cancel user location animators to prevent leaks
+        userLocationPositionAnimator?.cancel()
+        userLocationPositionAnimator = null
+        userLocationRotationAnimator?.cancel()
+        userLocationRotationAnimator = null
+
+        // C-3: Cancel all coroutines to prevent leaks
+        providerScope.cancel()
+
+        // Clear all data
+        markerData.clear()
+        polylineData.clear()
+        polygonData.clear()
+        circleData.clear()
+        pendingCommands.clear()
+        iconFactory?.clearCache()
+        iconFactory = null
+        clusteringManager?.destroy()
+        clusteringManager = null
+
+        // Null all callbacks to prevent leaks
+        onPress = null
+        onLongPress = null
+        onMapReadyCallback = null
+        onRegionChange = null
+        onRegionChangeComplete = null
+        onMarkerPress = null
+        onMarkerDragStart = null
+        onMarkerDrag = null
+        onMarkerDragEnd = null
+        onClusterPress = null
+        onError = null
+        onMapIdle = null
+        onPolylinePress = null
+        onPolygonPress = null
+        onCirclePress = null
+        onUserLocationChange = null
+        onUserTrackingModeChange = null
+        onUserLocationError = null
+
+        Log.d(TAG, "Map destroying — full cleanup complete")
+    }
+
+    // MARK: - Apply Settings
+
+    /**
+     * Applies all currently stored prop values to a (possibly new) GoogleMap instance.
+     * Called after onMapReady and after view reattach.
+     */
+    private fun applyAllSettings(map: GoogleMap) {
+        // UiSettings
+        map.uiSettings.isZoomGesturesEnabled = zoomEnabled ?: true
+        map.uiSettings.isScrollGesturesEnabled = scrollEnabled ?: true
+        map.uiSettings.isRotateGesturesEnabled = rotateEnabled ?: true
+        map.uiSettings.isTiltGesturesEnabled = pitchEnabled ?: true
+        map.uiSettings.isCompassEnabled = showsCompass ?: true
+        map.uiSettings.isMyLocationButtonEnabled = false // Always hidden
+
+        // Map type
+        map.mapType = convertMapType(mapType)
+
+        // Zoom limits
+        map.setMinZoomPreference(minZoom.toFloat())
+        map.setMaxZoomPreference(maxZoom.toFloat())
+
+        // Traffic + buildings
+        map.isTrafficEnabled = showsTraffic ?: false
+        map.isBuildingsEnabled = showsBuildings ?: true
+
+        // User location — show native blue dot when no custom image is set
+        if (userLocationImage.isEmpty()) {
+            try {
+                map.isMyLocationEnabled = showsUserLocation ?: false
+            } catch (e: SecurityException) {
+                Log.w(TAG, "Location permission not granted")
+            }
+        }
+
+        // H-4: mapPadding is non-nullable EdgePadding — no null check needed
+        // M-6: Standardize on context.resources.displayMetrics.density
+        val density = context.resources.displayMetrics.density
+        map.setPadding(
+            (mapPadding.left * density).roundToInt(),
+            (mapPadding.top * density).roundToInt(),
+            (mapPadding.right * density).roundToInt(),
+            (mapPadding.bottom * density).roundToInt()
+        )
+
+        // Camera — use region if set, otherwise initialRegion (only on first apply)
+        val targetRegion = if (region != null) {
+            region
+        } else if (!initialRegionApplied) {
+            // M-7: Only apply initialRegion once (matches iOS guard oldValue == nil)
+            initialRegionApplied = true
+            initialRegion
+        } else {
+            null
+        }
+        if (targetRegion != null) {
+            val camera = CameraPosition.Builder()
+                .target(LatLng(targetRegion.latitude, targetRegion.longitude))
+                .zoom(calculateZoom(targetRegion))
+                .build()
+            map.moveCamera(CameraUpdateFactory.newCameraPosition(camera))
+        }
+
+        // Map style (custom style takes priority over dark mode)
+        applyMapStyleInternal(map)
+
+        // Re-apply markers (after detach/reattach, native Marker objects are gone)
+        reapplyMarkers()
+
+        // Re-apply overlays (polylines, polygons, circles)
+        reapplyOverlays()
+    }
+
+    // MARK: - Map Style Helpers
+
+    /**
+     * Applies the current map style to the GoogleMap.
+     * Priority: customMapStyle > darkMode > default (null).
+     */
+    private fun applyMapStyleInternal(map: GoogleMap) {
+        // Custom style takes priority
+        val styleElements = customMapStyle
+        if (styleElements != null && styleElements.isNotEmpty()) {
+            try {
+                val jsonString = mapStyleElementsToJson(styleElements)
+                val success = map.setMapStyle(MapStyleOptions(jsonString))
+                if (!success) {
+                    Log.w(TAG, "Map style parsing failed")
+                    onError?.invoke(MapError("STYLE_ERROR", "Map style parsing failed"))
+                }
+                return
+            } catch (e: Exception) {
+                Log.e(TAG, "Failed to apply custom map style", e)
+                onError?.invoke(MapError("STYLE_ERROR", "Failed to apply map style: ${e.message}"))
+            }
+        }
+
+        // Dark mode fallback — use native MapColorScheme (SDK 19.0.0+)
+        if (darkMode == true) {
+            map.setMapStyle(null) // clear any custom JSON style
+            map.setMapColorScheme(MapColorScheme.DARK)
+            return
+        }
+
+        // Clear style — reset to light
+        map.setMapStyle(null)
+        map.setMapColorScheme(MapColorScheme.LIGHT)
+    }
+
+    private fun mapStyleElementsToJson(elements: Array<MapStyleElement>): String {
+        val sb = StringBuilder("[")
+        elements.forEachIndexed { index, element ->
+            if (index > 0) sb.append(",")
+            sb.append("{")
+            val parts = mutableListOf<String>()
+            element.featureType?.let { parts.add("\"featureType\":\"$it\"") }
+            element.elementType?.let { parts.add("\"elementType\":\"$it\"") }
+
+            val stylerParts = element.stylers.map { styler ->
+                val s = mutableListOf<String>()
+                styler.color?.let { s.add("\"color\":\"$it\"") }
+                styler.visibility?.let { s.add("\"visibility\":\"$it\"") }
+                styler.weight?.let { s.add("\"weight\":$it") }
+                styler.saturation?.let { s.add("\"saturation\":$it") }
+                styler.lightness?.let { s.add("\"lightness\":$it") }
+                styler.gamma?.let { s.add("\"gamma\":$it") }
+                "{${s.joinToString(",")}}"
+            }
+            parts.add("\"stylers\":[${stylerParts.joinToString(",")}]")
+
+            sb.append(parts.joinToString(","))
+            sb.append("}")
+        }
+        sb.append("]")
+        return sb.toString()
+    }
+
+    // MARK: - Interface Method Delegations
+    // These delegate to internal extension functions defined in separate files,
+    // allowing the extension file organization while satisfying the interface contract.
+
+    // Markers (delegated to GoogleMapProvider+Markers.kt)
+    override fun addMarker(marker: MarkerData) = addMarkerInternal(marker)
+    override fun addMarkers(markers: Array<MarkerData>) = addMarkersInternal(markers)
+    override fun updateMarker(marker: MarkerData) = updateMarkerInternal(marker)
+    override fun removeMarker(id: String) = removeMarkerInternal(id)
+    override fun clearMarkers() = clearMarkersInternal()
+    override fun selectMarker(id: String) = selectMarkerInternal(id)
+    override fun deselectMarker() = deselectMarkerInternal()
+
+    // Overlays (delegated to GoogleMapProvider+Overlays.kt)
+    override fun addPolyline(polyline: PolylineData) = addPolylineInternal(polyline)
+    override fun updatePolyline(polyline: PolylineData) = updatePolylineInternal(polyline)
+    override fun removePolyline(id: String) = removePolylineInternal(id)
+    override fun clearPolylines() = clearPolylinesInternal()
+    override fun addPolygon(polygon: PolygonData) = addPolygonInternal(polygon)
+    override fun updatePolygon(polygon: PolygonData) = updatePolygonInternal(polygon)
+    override fun removePolygon(id: String) = removePolygonInternal(id)
+    override fun clearPolygons() = clearPolygonsInternal()
+    override fun addCircle(circle: CircleData) = addCircleInternal(circle)
+    override fun updateCircle(circle: CircleData) = updateCircleInternal(circle)
+    override fun removeCircle(id: String) = removeCircleInternal(id)
+    override fun clearCircles() = clearCirclesInternal()
+
+    // Clustering (delegated to GoogleMapProvider+Clustering.kt)
+    override fun setClusteringEnabled(enabled: Boolean) = setClusteringEnabledInternal(enabled)
+    override fun refreshClusters() = refreshClustersInternal()
+
+    // User Location (delegated to GoogleMapProvider+UserLocation.kt)
+    override fun updateUserLocation(location: android.location.Location, heading: Float?) = updateUserLocationInternal(location, heading)
+    override fun setupCustomUserLocationMarker(context: Context) = setupCustomUserLocationMarkerInternal(context)
+    override fun centerOnUserLocation() = centerOnUserLocationInternal()
+
+    // MARK: - User Location Disable
+
+    override fun disableUserLocation() {
+        customUserLocationMarker?.remove()
+        customUserLocationMarker = null
+        withMap { map ->
+            try { map.isMyLocationEnabled = false } catch (_: SecurityException) {}
+        }
+    }
+
+    // MARK: - Camera Methods (matches iOS GoogleMapProvider+Camera.swift)
+
+    override fun animateToRegion(region: Region, duration: Double?) {
+        withMap { map ->
+            val camera = CameraPosition.Builder()
+                .target(LatLng(region.latitude, region.longitude))
+                .zoom(calculateZoom(region))
+                .build()
+            // L-6: Default to 500ms to match spec (iOS uses 500ms)
+            map.animateCamera(
+                CameraUpdateFactory.newCameraPosition(camera),
+                (duration?.toInt() ?: 500),
+                null
+            )
+        }
+    }
+
+    override fun fitToCoordinates(coordinates: Array<Coordinate>, edgePadding: EdgePadding?, animated: Boolean?) {
+        if (coordinates.isEmpty()) return
+
+        if (coordinates.size == 1) {
+            val first = coordinates[0]
+            animateToRegion(
+                Region(first.latitude, first.longitude, 0.05, 0.05),
+                if (animated != false) 300.0 else 0.0
+            )
+            return
+        }
+
+        withMap { map ->
+            val builder = LatLngBounds.Builder()
+            coordinates.forEach {
+                builder.include(LatLng(it.latitude, it.longitude))
+            }
+            val bounds = builder.build()
+
+            // Per-edge padding via temporary setPadding + restore
+            // M-6: Standardize on context.resources.displayMetrics.density
+            val density = context.resources.displayMetrics.density
+            val topPx = ((edgePadding?.top ?: 50.0) * density).toInt()
+            val leftPx = ((edgePadding?.left ?: 50.0) * density).toInt()
+            val bottomPx = ((edgePadding?.bottom ?: 50.0) * density).toInt()
+            val rightPx = ((edgePadding?.right ?: 50.0) * density).toInt()
+
+            // Save current padding, apply fit padding, then restore
+            // H-4: mapPadding is non-nullable — no null check needed
+            map.setPadding(leftPx, topPx, rightPx, bottomPx)
+            val update = CameraUpdateFactory.newLatLngBounds(bounds, 0)
+
+            val restorePadding = {
+                map.setPadding(
+                    (mapPadding.left * density).roundToInt(),
+                    (mapPadding.top * density).roundToInt(),
+                    (mapPadding.right * density).roundToInt(),
+                    (mapPadding.bottom * density).roundToInt()
+                )
+            }
+
+            if (animated != false) {
+                map.animateCamera(update, object : GoogleMap.CancelableCallback {
+                    override fun onFinish() { restorePadding() }
+                    override fun onCancel() { restorePadding() }
+                })
+            } else {
+                map.moveCamera(update)
+                restorePadding()
+            }
+        }
+    }
+
+    override fun fitToSuppliedMarkers(markerIds: Array<String>, edgePadding: EdgePadding?, animated: Boolean?) {
+        val coords = markerIds.mapNotNull { id ->
+            markerData[id]?.coordinate
+        }.toTypedArray()
+        if (coords.isEmpty()) return
+        fitToCoordinates(coords, edgePadding, animated)
+    }
+
+    override fun animateCamera(camera: Camera, duration: Double?) {
+        withMap { map ->
+            val cameraPos = CameraPosition.Builder()
+                .target(LatLng(camera.center.latitude, camera.center.longitude))
+                .zoom(camera.zoom.toFloat())
+                .bearing(camera.heading.toFloat())
+                .tilt(camera.pitch.toFloat())
+                .build()
+            map.animateCamera(
+                CameraUpdateFactory.newCameraPosition(cameraPos),
+                (duration?.toInt() ?: 300),
+                null
+            )
+        }
+    }
+
+    override fun setCamera(camera: Camera) {
+        withMap { map ->
+            val cameraPos = CameraPosition.Builder()
+                .target(LatLng(camera.center.latitude, camera.center.longitude))
+                .zoom(camera.zoom.toFloat())
+                .bearing(camera.heading.toFloat())
+                .tilt(camera.pitch.toFloat())
+                .build()
+            map.moveCamera(CameraUpdateFactory.newCameraPosition(cameraPos))
+        }
+    }
+
+    override fun getCamera(): Camera {
+        val map = googleMap
+        return if (map != null) {
+            val pos = map.cameraPosition
+            Camera(
+                center = Coordinate(pos.target.latitude, pos.target.longitude),
+                pitch = pos.tilt.toDouble(),
+                heading = pos.bearing.toDouble(),
+                altitude = altitudeFromZoom(pos.zoom.toDouble()),
+                zoom = pos.zoom.toDouble()
+            )
+        } else {
+            Camera(
+                center = Coordinate(0.0, 0.0),
+                pitch = 0.0,
+                heading = 0.0,
+                altitude = 0.0,
+                zoom = 0.0
+            )
+        }
+    }
+
+    override fun getMapBoundaries(): MapBoundaries? {
+        val map = googleMap ?: return null
+
+        val bounds = map.projection.visibleRegion.latLngBounds
+        return MapBoundaries(
+            northEast = Coordinate(bounds.northeast.latitude, bounds.northeast.longitude),
+            southWest = Coordinate(bounds.southwest.latitude, bounds.southwest.longitude)
+        )
+    }
+
+    override fun pointForCoordinate(coordinate: Coordinate): Point {
+        val map = googleMap ?: return Point(0.0, 0.0)
+        val screenPoint = map.projection.toScreenLocation(
+            LatLng(coordinate.latitude, coordinate.longitude)
+        )
+        return Point(screenPoint.x.toDouble(), screenPoint.y.toDouble())
+    }
+
+    override fun coordinateForPoint(point: Point): Coordinate {
+        val map = googleMap ?: return Coordinate(0.0, 0.0)
+        val latLng = map.projection.fromScreenLocation(
+            android.graphics.Point(point.x.toInt(), point.y.toInt())
+        )
+        return Coordinate(latLng.latitude, latLng.longitude)
+    }
+
+    // MARK: - Helper Methods
+
+    fun getCurrentRegion(): Region {
+        val map = googleMap ?: return Region(DEFAULT_LATITUDE, DEFAULT_LONGITUDE, 0.15, 0.15)
+
+        val bounds = map.projection.visibleRegion.latLngBounds
+        val center = map.cameraPosition.target
+
+        return Region(
+            latitude = center.latitude,
+            longitude = center.longitude,
+            latitudeDelta = bounds.northeast.latitude - bounds.southwest.latitude,
+            longitudeDelta = bounds.northeast.longitude - bounds.southwest.longitude
+        )
+    }
+
+    fun calculateZoom(region: Region): Float {
+        val latDelta = region.latitudeDelta
+        val lonDelta = region.longitudeDelta
+        val delta = maxOf(latDelta, lonDelta)
+        if (delta <= 0) return DEFAULT_ZOOM
+
+        // Same formula as iOS MapStyleProvider.zoomFromDeltas
+        val zoom = ln(360.0 / delta) / ln(2.0)
+        return zoom.coerceIn(minZoom, maxZoom).toFloat()
+    }
+
+    /**
+     * Converts zoom level to approximate altitude in meters.
+     * Matches iOS MapStyleProvider.altitudeFromZoom.
+     */
+    fun altitudeFromZoom(zoom: Double): Double {
+        val clamped = zoom.coerceIn(0.0, 21.0)
+        return BASE_ALTITUDE / 2.0.pow(clamped)
+    }
+
+    private fun convertMapType(type: MapType?): Int {
+        return when (type) {
+            MapType.SATELLITE -> GoogleMap.MAP_TYPE_SATELLITE
+            MapType.HYBRID -> GoogleMap.MAP_TYPE_HYBRID
+            MapType.STANDARD, null -> GoogleMap.MAP_TYPE_NORMAL
+        }
+    }
+}