@maydon_tech/react-native-nitro-maps 0.1.0

package/ios/Providers/GoogleMapProvider.swift

@@ -0,0 +1,924 @@
+import Foundation
+import GoogleMaps
+import GoogleMapsUtils
+import UIKit
+
+/// Google Maps implementation of MapProviderProtocol
+class GoogleMapProvider: MapProviderProtocol {
+
+  // MARK: - Constants
+  
+  private static let defaultLatitude: Double = 41.2995
+  private static let defaultLongitude: Double = 69.2401
+  
+  // MARK: - Properties
+
+  let gmsMapView: GMSMapView
+  var mapView: UIView { return gmsMapView }
+
+  private var mapDelegate: GoogleMapDelegate?
+
+  // MARK: - Injected Dependencies (DIP)
+  
+  private let clusteringManager: ClusteringManagerProtocol
+  private let selectionHandler: MarkerSelectionHandling
+
+  // Rendered markers
+  private(set) var renderedClusterMarkers: [GMSMarker] = []
+  private var renderedSingleMarkers: [String: GMSMarker] = [:]
+  private var nonClusteredMarkers: [String: GMSMarker] = [:]
+  private var hiddenNonClusteredIds: Set<String> = []  // Non-clustered markers hidden due to overlap
+  private var clusterableMarkerData: [String: MarkerData] = [:]
+
+  private var selectedMarkerId: String?
+
+  private static let defaultMarkerSize: CGFloat = 44
+
+  // MARK: - Clustering Render Item
+
+  /// A renderable item produced by the clustering pipeline.
+  /// Used by both `supercluster` and `hideOnOverlap` strategies.
+  private struct RenderItem {
+    enum Kind {
+      case cluster(NitroClusterEngine.ClusterDataResult)
+      case single(markerId: String)
+    }
+    let coordinate: CLLocationCoordinate2D
+    let kind: Kind
+    let iconSize: CGSize
+    let priority: Int  // Higher = more important (clusters > singles)
+  }
+
+  // MARK: - Protocol Properties
+
+  var initialRegion: Region? = Region(latitude: defaultLatitude, longitude: defaultLongitude, latitudeDelta: 0.15, longitudeDelta: 0.15) {
+    didSet {
+      // Only move to initial region on first set, not on every re-render
+      guard oldValue == nil else { return }
+      updateCameraToInitialRegion()
+    }
+  }
+
+  var showsUserLocation: Bool? {
+    didSet { gmsMapView.isMyLocationEnabled = showsUserLocation ?? false }
+  }
+
+  var zoomEnabled: Bool? {
+    didSet { gmsMapView.settings.zoomGestures = zoomEnabled ?? true }
+  }
+
+  var scrollEnabled: Bool? {
+    didSet { gmsMapView.settings.scrollGestures = scrollEnabled ?? true }
+  }
+
+  var rotateEnabled: Bool? {
+    didSet { gmsMapView.settings.rotateGestures = rotateEnabled ?? true }
+  }
+
+  var pitchEnabled: Bool? {
+    didSet { gmsMapView.settings.tiltGestures = pitchEnabled ?? true }
+  }
+
+  var mapType: MapType? {
+    didSet { gmsMapView.mapType = convertMapType(mapType) }
+  }
+
+  var showsMyLocationButton: Bool? {
+    didSet {
+      gmsMapView.settings.myLocationButton = showsMyLocationButton ?? false
+    }
+  }
+
+  var clusterConfig: ClusterConfig? {
+    didSet {
+      #if DEBUG
+      NSLog("[Clustering] didSet clusterConfig strategy=%@",
+            clusterConfig?.strategy.stringValue ?? "nil")
+      #endif
+      updateClusterConfig()
+    }
+  }
+
+  var customMapStyle: [MapStyleElement]? {
+    didSet { applyMapStyle() }
+  }
+
+  var darkMode: Bool? {
+    didSet { applyDarkMode() }
+  }
+
+  // MARK: - Callbacks
+
+  var onPress: ((MapPressEvent) -> Void)?
+  var onLongPress: ((MapPressEvent) -> Void)?
+  var onMapReady: (() -> Void)?
+  var onRegionChange: ((RegionChangeEvent) -> Void)?
+  var onRegionChangeComplete: ((RegionChangeEvent) -> Void)?
+  var onMarkerPress: ((MarkerPressEvent) -> Void)?
+  var onMarkerDragStart: ((MarkerDragEvent) -> Void)?
+  var onMarkerDrag: ((MarkerDragEvent) -> Void)?
+  var onMarkerDragEnd: ((MarkerDragEvent) -> Void)?
+  var onClusterPress: ((ClusterPressEvent) -> Void)?
+  var onError: ((MapError) -> Void)?
+
+  // MARK: - Initialization
+  
+  /// Creates a GoogleMapProvider with injected dependencies.
+  /// Uses default production implementations if none provided.
+  ///
+  /// - Parameters:
+  ///   - clusteringManager: Clustering logic handler (default: ClusteringManager)
+  ///   - selectionHandler: Marker selection handler (default: MarkerSelectionHandler.shared)
+  init(
+    clusteringManager: ClusteringManagerProtocol = ClusteringManager(),
+    selectionHandler: MarkerSelectionHandling = MarkerSelectionHandler.shared
+  ) {
+    self.clusteringManager = clusteringManager
+    self.selectionHandler = selectionHandler
+    
+    let camera = GMSCameraPosition.camera(
+      withLatitude: Self.defaultLatitude,
+      longitude: Self.defaultLongitude,
+      zoom: 10
+    )
+
+    // Use GMSMapViewOptions (required for Google Maps SDK v10.0+)
+    let options = GMSMapViewOptions()
+    options.camera = camera
+    options.frame = .zero
+    
+    let mapView = GMSMapView(options: options)
+    mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+    self.gmsMapView = mapView
+
+    setupIconLoadNotification()
+  }
+
+  deinit {
+    NotificationCenter.default.removeObserver(self)
+  }
+
+  // MARK: - Lifecycle
+
+  func setup() {
+    mapDelegate = GoogleMapDelegate(provider: self)
+    gmsMapView.delegate = mapDelegate
+  }
+
+  /// Listen for async icon load completion to update markers
+  private func setupIconLoadNotification() {
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(handleIconLoaded(_:)),
+      name: Notification.Name("MarkerIconLoaded"),
+      object: nil
+    )
+  }
+
+  @objc private func handleIconLoaded(_ notification: Notification) {
+    guard notification.userInfo?["icon"] is UIImage else {
+      return
+    }
+
+    // The cache has already been updated, so just refresh visible markers
+    DispatchQueue.main.async { [weak self] in
+      self?.refreshVisibleMarkerIcons()
+    }
+  }
+
+  /// Refresh icons for visible markers (used after async icon load)
+  private func refreshVisibleMarkerIcons() {
+    // Only refresh image-style markers as they use async loading
+    for (id, gmsMarker) in renderedSingleMarkers {
+      if let markerData = clusterableMarkerData[id],
+         markerData.config.style == MarkerStyle.image {
+        // Re-fetch icon from cache (now should have the loaded image)
+        if let icon = MarkerIconFactory.createIcon(for: markerData) {
+          gmsMarker.icon = icon
+        }
+      }
+    }
+
+    for (id, gmsMarker) in nonClusteredMarkers {
+      if let markerData = clusterableMarkerData[id],
+         markerData.config.style == MarkerStyle.image {
+        if let icon = MarkerIconFactory.createIcon(for: markerData) {
+          gmsMarker.icon = icon
+        }
+      }
+    }
+  }
+
+  func updateSettings() {
+    // Props are already applied via didSet. Just trigger clustering
+    // to reconcile any pending state.
+    performClustering()
+  }
+
+  // MARK: - Cluster Configuration
+
+  private func updateClusterConfig() {
+    #if DEBUG
+    NSLog("[Clustering] updateClusterConfig called")
+    #endif
+    clusteringManager.clusterConfig = clusterConfig
+    performClustering()
+  }
+
+  // MARK: - Clustering
+
+  /// Debounced clustering — fires after 100ms of silence (used on idle / config changes)
+  func performClustering() {
+    // FIX #4: Use the single debounce in ClusteringManager
+    // instead of a second timer here.
+    clusteringManager.debounce { [weak self] in
+      self?.performClusteringImmediate()
+    }
+  }
+
+  /// Throttled clustering — fires at most once per interval during continuous gestures.
+  /// Unlike debounce, throttle fires immediately then blocks subsequent calls for the interval.
+  private var throttleTimer: Timer?
+
+  func performClusteringThrottled() {
+    // If throttle timer is active, skip — we already have a pending call
+    guard throttleTimer == nil else { return }
+
+    // Fire immediately
+    performClusteringImmediate()
+
+    // Read interval from config (ms → seconds), default 150ms
+    let intervalMs = clusterConfig?.throttleInterval ?? 150
+    let intervalSec = intervalMs / 1000.0
+
+    // Block subsequent calls for the interval
+    throttleTimer = Timer.scheduledTimer(withTimeInterval: intervalSec, repeats: false) { [weak self] _ in
+      self?.throttleTimer = nil
+    }
+  }
+
+  private func performClusteringImmediate() {
+    guard gmsMapView.frame.size.width > 0 && gmsMapView.frame.size.height > 0
+    else {
+      return
+    }
+
+    let enabled = clusterConfig?.enabled ?? true
+    guard enabled else {
+      clearRenderedMarkersToPool()
+      renderAllMarkersIndividually()
+      return
+    }
+
+    // --- Phase 1: Spatial grouping (C++ Supercluster engine) ---
+    let visibleRegion = gmsMapView.projection.visibleRegion()
+    let zoom = gmsMapView.camera.zoom
+    let mapSize = gmsMapView.frame.size
+
+    let bounds = GMSCoordinateBounds(region: visibleRegion)
+
+    // Expand bounds by renderBuffer (fraction of viewport size)
+    let padding = clusterConfig?.renderBuffer ?? 0
+    let latSpan = bounds.northEast.latitude - bounds.southWest.latitude
+    let lonSpan = bounds.northEast.longitude - bounds.southWest.longitude
+    let queryMinLat = bounds.southWest.latitude - latSpan * padding
+    let queryMaxLat = bounds.northEast.latitude + latSpan * padding
+    let queryMinLon = bounds.southWest.longitude - lonSpan * padding
+    let queryMaxLon = bounds.northEast.longitude + lonSpan * padding
+
+    #if DEBUG
+    NSLog("[Clustering] zoom=%.6f SW=(%.6f,%.6f) NE=(%.6f,%.6f) padding=%.2f",
+          Double(zoom),
+          bounds.southWest.latitude, bounds.southWest.longitude,
+          bounds.northEast.latitude, bounds.northEast.longitude,
+          padding)
+    #endif
+
+    let result = clusteringManager.cluster(
+      minLat: queryMinLat,
+      maxLat: queryMaxLat,
+      minLon: queryMinLon,
+      maxLon: queryMaxLon,
+      zoom: Double(zoom),
+      mapSize: mapSize
+    )
+
+    let minClusterSize = Int(clusterConfig?.minimumClusterSize ?? 2)
+    let strategy = clusterConfig?.strategy ?? .supercluster
+
+    // --- Phase 2: Build renderable items from engine output ---
+    var renderItems: [RenderItem] = []
+    renderItems.reserveCapacity(result.clusters.count + result.singleMarkers.count)
+
+    // Process clusters
+    for cluster in result.clusters {
+      let containsSelected = selectedMarkerId != nil && cluster.markerIds.contains(selectedMarkerId!)
+      let adjustedCount = containsSelected ? cluster.count - 1 : cluster.count
+      guard adjustedCount >= minClusterSize else { continue }
+
+      let adjustedCluster = containsSelected
+        ? NitroClusterEngine.ClusterDataResult(
+            coordinate: cluster.coordinate,
+            markerIds: cluster.markerIds.filter { $0 != selectedMarkerId },
+            count: adjustedCount,
+            iconSize: cluster.iconSize
+          )
+        : cluster
+
+      let icon = clusteringManager.clusterIcon(forCount: adjustedCount)
+      let size = icon?.size ?? CGSize(width: 44, height: 44)
+
+      renderItems.append(RenderItem(
+        coordinate: cluster.coordinate,
+        kind: .cluster(adjustedCluster),
+        iconSize: size,
+        priority: adjustedCount + 10000
+      ))
+    }
+
+    // Process single markers
+    for single in result.singleMarkers {
+      let id = single.markerId
+      if id == selectedMarkerId { continue }
+      if nonClusteredMarkers[id] != nil { continue }
+      guard let data = clusterableMarkerData[id] else { continue }
+
+      let icon = MarkerIconFactory.createIcon(for: data)
+      let size = icon?.size ?? CGSize(width: 27, height: 43)
+
+      renderItems.append(RenderItem(
+        coordinate: CLLocationCoordinate2D(
+          latitude: single.latitude,
+          longitude: single.longitude
+        ),
+        kind: .single(markerId: id),
+        iconSize: size,
+        priority: 0
+      ))
+    }
+
+    // --- Phase 2b: Apply strategy ---
+    var visibleItems = renderItems
+
+    #if DEBUG
+    var clusterDetails: [String] = []
+    for item in renderItems {
+      if case .cluster(let c) = item.kind {
+        clusterDetails.append(String(format: "%d@(%.4f,%.4f)", c.count, c.coordinate.latitude, c.coordinate.longitude))
+      }
+    }
+    let singleCount = renderItems.count - clusterDetails.count
+    let detailStr = clusterDetails.joined(separator: " ")
+    NSLog("[Clustering] items=%d singles=%d clusters: %@",
+          renderItems.count, singleCount, detailStr)
+    #endif
+
+    if strategy == .hideonoverlap {
+      visibleItems = resolveOverlaps(
+        items: renderItems,
+        zoom: Double(zoom),
+        mapWidth: mapSize.width
+      )
+      #if DEBUG
+      NSLog("[Clustering] hideOnOverlap: %d → %d items",
+            renderItems.count, visibleItems.count)
+      #endif
+    }
+    // For .supercluster strategy: render all items as-is (overlaps tolerated)
+
+    // --- Phase 3: Render — add new markers BEFORE removing old ones ---
+    // This prevents the visual flash that occurs when markers are destroyed
+    // then recreated. By adding first, the map is never empty.
+    let isFirstRender = renderedClusterMarkers.isEmpty && renderedSingleMarkers.isEmpty
+
+    // Stash old markers for removal after new ones are on the map
+    let oldClusterMarkers = renderedClusterMarkers
+    let oldSingleMarkers = renderedSingleMarkers
+    renderedClusterMarkers = []
+    renderedSingleMarkers = [:]
+
+    // Restore previously hidden non-clustered markers
+    for id in hiddenNonClusteredIds {
+      nonClusteredMarkers[id]?.map = gmsMapView
+    }
+    hiddenNonClusteredIds.removeAll()
+
+    // Render new items (add to map)
+    for (renderIndex, item) in visibleItems.enumerated() {
+      switch item.kind {
+      case .cluster(let clusterData):
+        let marker = GMSMarker()
+        marker.position = clusterData.coordinate
+        marker.groundAnchor = CGPoint(x: 0.5, y: 0.5)
+
+        if let icon = clusteringManager.clusterIcon(forCount: clusterData.count) {
+          marker.icon = icon
+        }
+
+        marker.userData = ClusterUserData(
+          markerIds: clusterData.markerIds,
+          count: clusterData.count
+        )
+
+        // Larger clusters render on top for consistent visual ordering
+        marker.zIndex = Int32(clusterData.count + 1000)
+
+        // Only animate on the very first render, not on pan/zoom re-renders
+        if isFirstRender, let animationStyle = clusterConfig?.animationStyle {
+          applyClusterAnimation(marker, style: animationStyle)
+        }
+
+        marker.map = gmsMapView
+        renderedClusterMarkers.append(marker)
+
+      case .single(let markerId):
+        guard let data = clusterableMarkerData[markerId] else { continue }
+        // Reuse the existing GMSMarker if this markerId was already rendered.
+        // This avoids the remove+add cycle that causes visual flashing.
+        if let existing = oldSingleMarkers[markerId] {
+          updateGMSMarkerProperties(existing, from: data)
+          existing.zIndex = Int32(renderIndex)
+          renderedSingleMarkers[markerId] = existing
+        } else {
+          let marker = GMSMarker()
+          configureGMSMarker(marker, from: data)
+          marker.zIndex = Int32(renderIndex)
+          marker.map = gmsMapView
+          renderedSingleMarkers[markerId] = marker
+        }
+      }
+    }
+
+    // NOW remove old markers (after new ones are visible)
+    for marker in oldClusterMarkers {
+      marker.map = nil
+    }
+    for (id, marker) in oldSingleMarkers {
+      // Skip markers that were reused in the new render
+      if renderedSingleMarkers[id] != nil { continue }
+      marker.map = nil
+    }
+
+    // Handle non-clustered markers with hideOnOverlap
+    if strategy == .hideonoverlap {
+      hideOverlappingNonClusteredMarkers(
+        visibleItems: visibleItems,
+        zoom: Double(zoom),
+        mapWidth: mapSize.width
+      )
+    }
+  }
+
+  // MARK: - Overlap Resolution (hideOnOverlap strategy)
+
+  /// Removes lower-priority items that visually overlap higher-priority items.
+  /// Uses Mercator projection math — no GMSProjection dependency.
+  private func resolveOverlaps(
+    items: [RenderItem],
+    zoom: Double,
+    mapWidth: CGFloat
+  ) -> [RenderItem] {
+    let sorted = items.sorted { $0.priority > $1.priority }
+    var visible: [RenderItem] = []
+    visible.reserveCapacity(sorted.count)
+
+    let worldSize = 256.0 * pow(2.0, zoom)
+
+    for item in sorted {
+      var hasOverlap = false
+      for existing in visible {
+        if itemsOverlap(item, existing, worldSize: worldSize) {
+          hasOverlap = true
+          break
+        }
+      }
+      if !hasOverlap {
+        visible.append(item)
+      }
+    }
+
+    return visible
+  }
+
+  /// Hides non-clustered markers that overlap with already-rendered items.
+  private func hideOverlappingNonClusteredMarkers(
+    visibleItems: [RenderItem],
+    zoom: Double,
+    mapWidth: CGFloat
+  ) {
+    let worldSize = 256.0 * pow(2.0, zoom)
+
+    for (id, ncMarker) in nonClusteredMarkers {
+      let data = clusterableMarkerData[id]
+      let icon = data.flatMap { MarkerIconFactory.createIcon(for: $0) }
+      let size = icon?.size ?? CGSize(width: Self.defaultMarkerSize, height: Self.defaultMarkerSize)
+
+      let ncItem = RenderItem(
+        coordinate: ncMarker.position,
+        kind: .single(markerId: id),
+        iconSize: size,
+        priority: 0
+      )
+
+      var hasOverlap = false
+      for existing in visibleItems {
+        if itemsOverlap(ncItem, existing, worldSize: worldSize) {
+          hasOverlap = true
+          break
+        }
+      }
+
+      if hasOverlap {
+        ncMarker.map = nil
+        hiddenNonClusteredIds.insert(id)
+      }
+    }
+  }
+
+  /// Checks if two render items overlap in screen space using Mercator projection.
+  private func itemsOverlap(_ a: RenderItem, _ b: RenderItem, worldSize: Double) -> Bool {
+    let dx: Double = mercatorX(a.coordinate.longitude, worldSize: worldSize)
+                   - mercatorX(b.coordinate.longitude, worldSize: worldSize)
+    let dy: Double = mercatorY(a.coordinate.latitude, worldSize: worldSize)
+                   - mercatorY(b.coordinate.latitude, worldSize: worldSize)
+    let minSepX: Double = Double(a.iconSize.width + b.iconSize.width) / 2.0
+    let minSepY: Double = Double(a.iconSize.height + b.iconSize.height) / 2.0
+    return Swift.abs(dx) < minSepX && Swift.abs(dy) < minSepY
+  }
+
+  // MARK: - Mercator Math Helpers
+
+  private func mercatorX(_ longitude: Double, worldSize: Double) -> Double {
+    return (longitude + 180.0) / 360.0 * worldSize
+  }
+
+  private func mercatorY(_ latitude: Double, worldSize: Double) -> Double {
+    let latRad = latitude * .pi / 180.0
+    return (1.0 - log(tan(latRad) + 1.0 / cos(latRad)) / .pi) / 2.0 * worldSize
+  }
+
+  /// Always create a fresh GMSMarker.
+  /// Google Maps SDK has a known bug where reused markers render at incorrect
+  /// positions after being removed and re-added to the map. Creating fresh
+  /// markers avoids this issue entirely.
+  private func getMarkerFromPool() -> GMSMarker {
+    return GMSMarker()
+  }
+
+  /// Dispose of a marker by removing it from the map.
+  /// We intentionally do NOT pool markers due to the Google Maps SDK reuse bug.
+  private func returnMarkerToPool(_ marker: GMSMarker) {
+    marker.map = nil
+  }
+
+  private func clearRenderedMarkersToPool() {
+    for marker in renderedClusterMarkers {
+      returnMarkerToPool(marker)
+    }
+    renderedClusterMarkers.removeAll()
+
+    for (_, marker) in renderedSingleMarkers {
+      returnMarkerToPool(marker)
+    }
+    renderedSingleMarkers.removeAll()
+  }
+
+  private func renderAllMarkersIndividually() {
+    for (_, markerData) in clusterableMarkerData {
+      if renderedSingleMarkers[markerData.id] == nil {
+        let marker = getMarkerFromPool()
+        configureGMSMarker(marker, from: markerData)
+        marker.map = gmsMapView
+        renderedSingleMarkers[markerData.id] = marker
+      }
+    }
+  }
+
+  /// Configure a GMSMarker with marker data (for initial setup)
+  private func configureGMSMarker(_ gmsMarker: GMSMarker, from markerData: MarkerData) {
+    gmsMarker.position = CLLocationCoordinate2D(
+      latitude: markerData.coordinate.latitude,
+      longitude: markerData.coordinate.longitude
+    )
+    gmsMarker.title = markerData.title
+    gmsMarker.snippet = markerData.description
+    gmsMarker.isDraggable = markerData.draggable
+    gmsMarker.opacity = Float(markerData.opacity)
+    gmsMarker.rotation = markerData.rotation
+    gmsMarker.zIndex = Int32(markerData.zIndex)
+    gmsMarker.groundAnchor = CGPoint(
+      x: markerData.anchor.x,
+      y: markerData.anchor.y
+    )
+    gmsMarker.userData = markerData.id
+    gmsMarker.icon = MarkerIconFactory.createIcon(for: markerData)
+
+    switch markerData.animation {
+    case .pop:
+      gmsMarker.appearAnimation = .pop
+    case .fadein:
+      gmsMarker.appearAnimation = .fadeIn
+    case .none:
+      gmsMarker.appearAnimation = .none
+    }
+  }
+
+  private func applyClusterAnimation(
+    _ marker: GMSMarker,
+    style: ClusterAnimationStyle
+  ) {
+    switch style {
+    case .bounce, .spring:
+      marker.appearAnimation = .pop
+    case .fade:
+      marker.appearAnimation = .fadeIn
+    case .scale, .default:
+      marker.appearAnimation = .pop
+    }
+  }
+
+  // MARK: - Marker Management
+
+  func addMarker(_ marker: MarkerData) {
+    // FIX #3: NitroMap dispatches to main. Provider assumes main thread.
+    addMarkerSync(marker)
+  }
+
+  func addMarkers(_ markers: [MarkerData]) {
+    for marker in markers {
+      addMarkerSync(marker)
+    }
+    performClustering()
+  }
+
+  private func addMarkerSync(_ markerData: MarkerData) {
+    removeMarkerSync(markerData.id)
+
+    // ALL markers go into the clustering engine so it knows their positions
+    // and sizes for overlap prevention
+    clusterableMarkerData[markerData.id] = markerData
+    clusteringManager.addMarker(markerData)
+
+    if !markerData.clusteringEnabled || !(clusterConfig?.enabled ?? true) {
+      // Non-clustered markers also get a direct GMSMarker on the map
+      let marker = getMarkerFromPool()
+      configureGMSMarker(marker, from: markerData)
+      marker.map = gmsMapView
+      nonClusteredMarkers[markerData.id] = marker
+    }
+  }
+
+  func updateMarker(_ marker: MarkerData) {
+    updateMarkerInPlace(marker)
+  }
+
+  /// Update marker in-place without triggering full re-clustering
+  /// This prevents texture allocation exhaustion by reusing existing GMSMarker objects
+  private func updateMarkerInPlace(_ markerData: MarkerData) {
+    let id = markerData.id
+
+    // Update stored data
+    if let existing = clusterableMarkerData[id] {
+      clusterableMarkerData[id] = markerData
+
+      // Only re-index in the C++ engine if coordinate changed.
+      // Cosmetic updates (selection, clusteringEnabled, icon style) don't
+      // need a spatial re-index and must NOT set markersChanged_ = true,
+      // which would force a full hierarchy rebuild.
+      let coordChanged =
+        existing.coordinate.latitude != markerData.coordinate.latitude ||
+        existing.coordinate.longitude != markerData.coordinate.longitude
+      if coordChanged {
+        clusteringManager.removeMarker(id)
+        clusteringManager.addMarker(markerData)
+      }
+    }
+
+    // Update rendered marker in-place (no remove/re-add)
+    if let gmsMarker = renderedSingleMarkers[id] {
+      updateGMSMarkerProperties(gmsMarker, from: markerData)
+    } else if let gmsMarker = nonClusteredMarkers[id] {
+      updateGMSMarkerProperties(gmsMarker, from: markerData)
+    }
+    // If marker not in any dict, it will be created with new data when clustering runs
+  }
+
+  /// Update GMSMarker properties in-place without creating a new marker object
+  private func updateGMSMarkerProperties(_ gmsMarker: GMSMarker, from markerData: MarkerData) {
+    gmsMarker.position = CLLocationCoordinate2D(
+      latitude: markerData.coordinate.latitude,
+      longitude: markerData.coordinate.longitude
+    )
+    gmsMarker.title = markerData.title
+    gmsMarker.snippet = markerData.description
+    gmsMarker.isDraggable = markerData.draggable
+    gmsMarker.opacity = Float(markerData.opacity)
+    gmsMarker.rotation = markerData.rotation
+    gmsMarker.zIndex = Int32(markerData.zIndex)
+    gmsMarker.groundAnchor = CGPoint(
+      x: markerData.anchor.x,
+      y: markerData.anchor.y
+    )
+
+    // Only regenerate icon if needed - cache will handle deduplication
+    if let newIcon = MarkerIconFactory.createIcon(for: markerData) {
+      gmsMarker.icon = newIcon
+    }
+  }
+
+  func removeMarker(_ id: String) {
+    removeMarkerSync(id)
+    performClustering()
+  }
+
+  private func removeMarkerSync(_ id: String) {
+    clusteringManager.removeMarker(id)
+    clusterableMarkerData.removeValue(forKey: id)
+
+    if let marker = renderedSingleMarkers[id] {
+      marker.map = nil
+      renderedSingleMarkers.removeValue(forKey: id)
+    }
+
+    if let marker = nonClusteredMarkers[id] {
+      marker.map = nil
+      nonClusteredMarkers.removeValue(forKey: id)
+    }
+  }
+
+  func clearMarkers() {
+    clearMarkersSync()
+  }
+
+  private func clearMarkersSync() {
+    clusteringManager.clearMarkers()
+    clusterableMarkerData.removeAll()
+    clearRenderedMarkersToPool()
+
+    for (_, marker) in nonClusteredMarkers {
+      returnMarkerToPool(marker)
+    }
+    nonClusteredMarkers.removeAll()
+  }
+
+  func selectMarker(_ id: String) {
+    // Deselect previous marker if exists
+    if let previousId = selectedMarkerId, previousId != id {
+      updateMarkerSelectionState(previousId, selected: false)
+    }
+
+    // Select new marker
+    selectedMarkerId = id
+    updateMarkerSelectionState(id, selected: true)
+
+    // Get marker position and animate to it
+    var markerPosition: CLLocationCoordinate2D?
+
+    if let marker = renderedSingleMarkers[id] {
+      gmsMapView.selectedMarker = marker
+      markerPosition = marker.position
+    } else if let marker = nonClusteredMarkers[id] {
+      gmsMapView.selectedMarker = marker
+      markerPosition = marker.position
+    } else if let markerData = clusterableMarkerData[id] {
+      // Marker is inside a cluster — create a temporary single marker
+      let marker = GMSMarker()
+      configureGMSMarker(marker, from: markerData)
+      marker.map = gmsMapView
+      renderedSingleMarkers[id] = marker
+      gmsMapView.selectedMarker = marker
+      markerPosition = marker.position
+      performClustering()
+    }
+
+    // Animate camera to marker position
+    if let position = markerPosition {
+      let camera = GMSCameraPosition.camera(
+        withLatitude: position.latitude,
+        longitude: position.longitude,
+        zoom: gmsMapView.camera.zoom
+      )
+      CATransaction.begin()
+      CATransaction.setAnimationDuration(0.3)
+      gmsMapView.animate(to: camera)
+      CATransaction.commit()
+    }
+  }
+
+  /// Update a marker's visual selection state by regenerating its icon
+  private func updateMarkerSelectionState(_ id: String, selected: Bool) {
+    guard let data = clusterableMarkerData[id] else { return }
+    
+    // Use injected handler to create updated marker data with selection state
+    guard let updatedData = selectionHandler.updateSelectionState(for: data, selected: selected) else {
+      return
+    }
+    
+    // Update stored data
+    clusterableMarkerData[id] = updatedData
+    clusteringManager.removeMarker(id)
+    clusteringManager.addMarker(updatedData)
+    
+    // Regenerate icon and apply to GMSMarker
+    if let gmsMarker = renderedSingleMarkers[id] {
+      gmsMarker.icon = MarkerIconFactory.createIcon(for: updatedData)
+    } else if let gmsMarker = nonClusteredMarkers[id] {
+      gmsMarker.icon = MarkerIconFactory.createIcon(for: updatedData)
+    }
+  }
+
+  // MARK: - Clustering Control
+
+  func setClusteringEnabled(_ enabled: Bool) {
+    self.clusterConfig = ClusterConfig.withEnabled(enabled, existing: clusterConfig)
+    performClustering()
+  }
+
+  func refreshClusters() {
+    performClustering()
+  }
+
+  // MARK: - Map Style
+
+  func setMapStyle(_ style: [MapStyleElement]?) {
+    customMapStyle = style
+  }
+
+  func setDarkMode(_ enabled: Bool) {
+    darkMode = enabled
+  }
+
+  private func applyMapStyle() {
+    guard let styleElements = customMapStyle, !styleElements.isEmpty else {
+      gmsMapView.mapStyle = nil
+      return
+    }
+
+    do {
+      let jsonArray = styleElements.map { element -> [String: Any] in
+        var dict: [String: Any] = [:]
+        if let featureType = element.featureType {
+          dict["featureType"] = featureType
+        }
+        if let elementType = element.elementType {
+          dict["elementType"] = elementType
+        }
+
+        dict["stylers"] = element.stylers.map { styler -> [String: Any] in
+          var s: [String: Any] = [:]
+          if let color = styler.color { s["color"] = color }
+          if let visibility = styler.visibility { s["visibility"] = visibility }
+          if let weight = styler.weight { s["weight"] = weight }
+          if let saturation = styler.saturation { s["saturation"] = saturation }
+          if let lightness = styler.lightness { s["lightness"] = lightness }
+          if let gamma = styler.gamma { s["gamma"] = gamma }
+          return s
+        }
+        return dict
+      }
+
+      let jsonData = try JSONSerialization.data(withJSONObject: jsonArray)
+      let jsonString = String(data: jsonData, encoding: .utf8) ?? "[]"
+      gmsMapView.mapStyle = try GMSMapStyle(jsonString: jsonString)
+    } catch {
+      // FIX #12: Surface errors via onError instead of silent print
+      onError?(MapError(code: "STYLE_ERROR", message: "Failed to apply map style: \(error.localizedDescription)"))
+    }
+  }
+
+  private func applyDarkMode() {
+    if let isDark = darkMode {
+      gmsMapView.overrideUserInterfaceStyle = isDark ? .dark : .light
+    }
+  }
+
+  // MARK: - Helper Methods
+
+  private func updateCameraToInitialRegion() {
+    guard let region = initialRegion else { return }
+
+    let camera = GMSCameraPosition.camera(
+      withLatitude: region.latitude,
+      longitude: region.longitude,
+      zoom: calculateZoom(for: region)
+    )
+    gmsMapView.animate(to: camera)
+  }
+
+  func calculateZoom(for region: Region) -> Float {
+    // FIX #5: Use MapStyleProvider's logarithmic calculation
+    return Float(MapStyleProvider.shared.zoomFromDeltas(
+      latDelta: region.latitudeDelta,
+      lonDelta: region.longitudeDelta
+    ))
+  }
+
+  private func convertMapType(_ type: MapType?) -> GMSMapViewType {
+    switch type {
+    case .satellite: return .satellite
+    case .hybrid: return .hybrid
+    case .standard, .none: return .normal
+    }
+  }
+
+}