@maydon_tech/react-native-nitro-maps 0.1.3 → 0.2.0

package/ios/Providers/GoogleMapProvider.swift

@@ -1,924 +0,0 @@
-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
-    }
-  }
-
-}