Fix black flash when removing/re-adding annotations (#12326)

## Summary

- Fixes
[MAPSIOS-2180](https://mapbox.atlassian.net/browse/MAPSIOS-2180):
Verizon reported a black flash when removing/re-adding polygon
annotations (regression in v11.17.0).
- Root cause: `removeGeoJSONSourceFeatures` is async (worker thread)
while `setLayerProperties` is sync (immediate). When annotations were
cleared, `syncLayer()` reset data-driven properties to literal style
defaults (e.g. `fill-color: #000000`) before features were actually
removed from the source — so for 1+ frames the still-visible features
rendered with the black default.
- Fix: in the "unused properties" reset path in `syncLayer()`, swap the
literal style default for a coalesce expression that reads each
feature's own stored value first (with the style default as fallback).
Stale features waiting on the async remove now keep their correct
colors; no black flash.

### Why minimal

A broader architectural refactor (coalesce expressions set once, manager
values merged into features, static data-driven/non-data-driven key sets
via stylegen) was prototyped and reviewed but carries meaningful scope
and risk for a hotfix affecting all annotation users and every
downstream (Flutter SDK, Nav SDK). Tracked as a follow-up in
[MAPSIOS-2185](https://mapbox.atlassian.net/browse/MAPSIOS-2185).

## Test plan

- [x] Unit tests: `AnnotationManagerImplTests` + all four
`*AnnotationManagerTests` suites pass locally on iPhone 16 Pro / iOS
18.6.
- [x] Run the `PolygonAnnotationExample` reproducer (rapid remove/re-add
cycle) — confirm no black flash.
- [ ] Verify polygon renders correctly after re-add (fill-color,
fill-opacity, fill-outline-color).
- [ ] Test with manager-level properties (e.g.
`polygonAnnotationManager.fillOpacity = 0.5`).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

[MAPSIOS-2180]:
https://mapbox.atlassian.net/browse/MAPSIOS-2180?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
[MAPSIOS-2185]:
https://mapbox.atlassian.net/browse/MAPSIOS-2185?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

cc @mapbox/maps-ios

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
GitOrigin-RevId: 0ffd039c5f6f563ededf18443e1b11c9695ad805

Author: 2 people

Sources/MapboxMaps/Annotations/AnnotationManagerImpl.swift

@@ -80,6 +80,13 @@ final class AnnotationManagerImpl<AnnotationType: Annotation & AnnotationInterna
     /// the subsequent sync.
     private var previouslySetLayerPropertyKeys: Set<String> = []
 
+    /// Keys that have been data-driven in any previous sync (monotonic — never shrinks
+    /// for the lifetime of the manager, bounded by the layer type's property count).
+    /// Keeping these keys routed through the data-driven coalesce path ensures stale
+    /// features (still visible while an async source removal is in flight) keep reading
+    /// their own stored values instead of snapping to literal defaults — MAPSIOS-2180.
+    private var previouslyDataDrivenLayerPropertyKeys: Set<String> = []
+
     private var draggedAnnotationIndex: Array<PointAnnotation>.Index?
     private var destroyOnce = Once()
     private var syncSourceOnce = Once(happened: true)
@@ -289,31 +296,31 @@ final class AnnotationManagerImpl<AnnotationType: Annotation & AnnotationInterna
 
         delegate?.syncImages()
 
-        // Construct the properties dictionary from the annotations
-        let dataDrivenLayerPropertyKeys = Set(annotations.flatMap(\.layerProperties.keys))
+        // Route both current-annotation keys and any previously-data-driven keys through the
+        // coalesce path. Keeping previously-seen keys ensures stale features (still visible
+        // while an async source removal is in flight) keep reading their own stored values
+        // instead of snapping to a literal default — MAPSIOS-2180 black flash.
+        let currentDataDrivenLayerPropertyKeys = Set(annotations.flatMap(\.layerProperties.keys))
+        let dataDrivenLayerPropertyKeys = currentDataDrivenLayerPropertyKeys
+            .union(previouslyDataDrivenLayerPropertyKeys)
 
-        /// The logic of the expression is the following
-        /// Firstly, it tries to get the the value for the given key from `layerProperties` in feature. Properties for the feature are set in <Type>Annotation.feature
-        /// Secondly, it tries to read the value from `layerProperties` dictionary from annotation manager.
-        /// In the end if the property is not set either on annotation or on annotation manager we just use default value from the style.gst
         let dataDrivenProperties = Dictionary(
-            uniqueKeysWithValues: dataDrivenLayerPropertyKeys.map { (key) -> (String, Any) in (key, [
-                "coalesce",
-                ["get", key, ["get", "layerProperties"]],
-                layerProperties[key] ?? StyleManager.layerPropertyDefaultValue(for: self.layerType, property: key).value
-            ] as [Any])})
+            uniqueKeysWithValues: dataDrivenLayerPropertyKeys.map { (key) -> (String, Any) in
+                (key, coalesceExpression(forKey: key))
+            })
 
-        // Merge the common layer properties
+        // Merge manager-level literals — data-driven coalesce wins on key collisions.
         let newLayerProperties = dataDrivenProperties.merging(layerProperties, uniquingKeysWith: { dataDriven, _ in dataDriven })
 
-        // Construct the properties dictionary to reset any properties that are no longer used
+        // Remaining unused keys are manager-only literals the user removed. Reset to literal
+        // style defaults — core maps doesn't always honor coalesce over non-data-driven paint properties.
         let unusedPropertyKeys = previouslySetLayerPropertyKeys.subtracting(newLayerProperties.keys)
         let unusedProperties = Dictionary(uniqueKeysWithValues: unusedPropertyKeys.map { (key) -> (String, Any) in
             (key, StyleManager.layerPropertyDefaultValue(for: self.layerType, property: key).value)
         })
 
-        // Store the new set of property keys
         previouslySetLayerPropertyKeys = Set(newLayerProperties.keys)
+        previouslyDataDrivenLayerPropertyKeys = dataDrivenLayerPropertyKeys
 
         // Merge the new and unused properties
         let allLayerProperties = newLayerProperties.merging(unusedProperties, uniquingKeysWith: { $1 })
@@ -331,6 +338,16 @@ final class AnnotationManagerImpl<AnnotationType: Annotation & AnnotationInterna
         }
     }
 
+    /// Builds the coalesce expression used for data-driven layer properties:
+    /// feature's own `layerProperties` first, then the manager-level value, then the style default.
+    private func coalesceExpression(forKey key: String) -> [Any] {
+        return [
+            "coalesce",
+            ["get", key, ["get", "layerProperties"]],
+            layerProperties[key] ?? StyleManager.layerPropertyDefaultValue(for: self.layerType, property: key).value
+        ]
+    }
+
     // MARK: - User interaction handling
 
     typealias TokenPair = (AnyCancelable, AnyCancelable)

Tests/MapboxMapsTests/Annotations/AnnotationManagerImplTests.swift

@@ -209,14 +209,79 @@ final class AnnotationManagerImplTests: XCTestCase {
         XCTAssertEqual(props2["x"] as? String, "X")
         XCTAssertEqual(props2["bar"] as? String, "qux")
 
-        // resets to default
+        // `icon-allow-overlap` was never set by any annotation in this test, so it resets
+        // to the literal style default — not a coalesce expression.
         let def = StyleManager.layerPropertyDefaultValue(for: .symbol, property: "icon-allow-overlap").value as? Bool
         XCTAssertEqual(props2["icon-allow-overlap"] as? Bool, def)
 
         try checkExpression(key: "text-field", props: props2)
         XCTAssertEqual(props2.count, 6)
     }
 
+    // Regression test for MAPSIOS-2180: when a key that was data-driven (some annotation
+    // carried it in its own layerProperties) becomes unused, it must reset as a coalesce
+    // expression so that stale features awaiting the async source removal keep rendering
+    // their own stored values instead of a literal default (which would cause a black flash
+    // for fill-color).
+    func testDataDrivenKeyResetsAsCoalesceExpression() throws {
+        // Annotation with a per-annotation data-driven property
+        me.annotations = [
+            PointAnnotation(id: "foo", coordinate: .init(latitude: 0, longitude: 0))
+                .textSize(10)
+        ]
+        harness.triggerDisplayLink()
+        style.setLayerPropertiesStub.reset()
+
+        // Remove all annotations — the key is now unused but was data-driven last sync
+        me.annotations = []
+        harness.triggerDisplayLink()
+
+        let props = try XCTUnwrap(style.setLayerPropertiesStub.invocations.last?.parameters.properties)
+        let resetValue = try XCTUnwrap(props["text-size"] as? [Any])
+        XCTAssertEqual(resetValue[0] as? String, "coalesce", "data-driven reset should be a coalesce expression")
+        let lookup = try XCTUnwrap(resetValue[1] as? [Any])
+        XCTAssertEqual(lookup[0] as? String, "get")
+        XCTAssertEqual(lookup[1] as? String, "text-size")
+    }
+
+    // Pins the contract that `previouslyDataDrivenLayerPropertyKeys` accumulates across syncs:
+    // once a key has been data-driven, its coalesce expression keeps being pushed to the layer
+    // on subsequent syncs — even for syncs whose current annotations no longer carry it, and
+    // even across intervening annotations with entirely different properties.
+    func testDataDrivenKeysAccumulateAcrossSyncs() throws {
+        // Sync 1: annotation carries text-size
+        me.annotations = [
+            PointAnnotation(id: "a", coordinate: .init(latitude: 0, longitude: 0))
+                .textSize(10)
+        ]
+        harness.triggerDisplayLink()
+
+        // Sync 2: annotations removed
+        me.annotations = []
+        harness.triggerDisplayLink()
+
+        // Sync 3: different annotation with a different data-driven property (text-field)
+        me.annotations = [
+            PointAnnotation(id: "b", coordinate: .init(latitude: 0, longitude: 0))
+                .textField("x")
+        ]
+        harness.triggerDisplayLink()
+
+        // Sync 4: annotations removed again
+        style.setLayerPropertiesStub.reset()
+        me.annotations = []
+        harness.triggerDisplayLink()
+
+        // At sync 4, BOTH text-size (from sync 1) and text-field (from sync 3) must still be
+        // pushed as coalesce expressions — the accumulation is what keeps stale features
+        // rendering their own colors during async removes for any key that has ever been data-driven.
+        let props = try XCTUnwrap(style.setLayerPropertiesStub.invocations.last?.parameters.properties)
+        let textSize = try XCTUnwrap(props["text-size"] as? [Any])
+        XCTAssertEqual(textSize[0] as? String, "coalesce", "text-size coalesce should persist after later syncs")
+        let textField = try XCTUnwrap(props["text-field"] as? [Any])
+        XCTAssertEqual(textField[0] as? String, "coalesce", "text-field coalesce should persist after later syncs")
+    }
+
     @available(*, deprecated)
     func testHandleTap() throws {
         let delegate = Delegate()