Fix marker bitmap lifecycle crash, add cache regression tests, and bump OpenMapView docs/version to 0.13.1

Author: afarber

README.md

@@ -14,7 +14,7 @@ Add to your `build.gradle.kts`:
 
 ```kotlin
 dependencies {
-    implementation("de.afarber:openmapview:0.13.0")
+    implementation("de.afarber:openmapview:0.13.1")
 }
 ```
 

docs/PERFORMANCE.md

@@ -269,7 +269,7 @@ HttpClient(Android) {
 All requests include a user-agent header as required by OSM tile usage policy:
 
 ```kotlin
-header("User-Agent", "OpenMapView/0.13.0 (https://github.com/afarber/OpenMapView)")
+header("User-Agent", "OpenMapView/0.13.1 (https://github.com/afarber/OpenMapView)")
 ```
 
 ### Coroutine-Based Downloads

docs/REPLACING_GOOGLE_MAPS.md

@@ -107,7 +107,7 @@ dependencies {
 ```kotlin
 // Add to build.gradle.kts
 dependencies {
-    implementation("de.afarber:openmapview:0.13.0")
+    implementation("de.afarber:openmapview:0.13.1")
 }
 ```
 

gradle.properties

@@ -10,5 +10,5 @@ POM_DESCRIPTION=A modern, Kotlin-first MapView replacement for Android powered b
 POM_URL=https://github.com/afarber/OpenMapView
 GROUP=de.afarber
 # Version is automatically derived from the latest Git tag (vX.Y.Z)
-VERSION_NAME=0.1.0
+VERSION_NAME=0.13.1
 

openmapview/src/main/kotlin/de/afarber/openmapview/MapController.kt

@@ -235,7 +235,7 @@ class MapController(
                 MarkerIconFactory.getDefaultIcon(descriptor.hue)
             }
             is BitmapDescriptor.BitmapMarker -> {
-                descriptor.bitmap
+                descriptor.bitmap.takeUnless { it.isRecycled } ?: defaultMarkerIcon
             }
             is BitmapDescriptor.ResourceMarker -> {
                 try {

openmapview/src/main/kotlin/de/afarber/openmapview/MarkerIconFactory.kt

@@ -34,16 +34,23 @@ internal object MarkerIconFactory {
         // Normalize hue to 0-360 range
         val normalizedHue = hue % 360f
 
-        // Return cached icon if available
-        iconCache[normalizedHue]?.let { return it }
+        // Return cached icon if available. If a recycled bitmap somehow ended up in cache,
+        // drop it and regenerate below.
+        iconCache[normalizedHue]?.let { cached ->
+            if (!cached.isRecycled) {
+                return cached
+            }
+            iconCache.remove(normalizedHue)
+        }
 
         // Create new icon
         val bitmap = createMarkerIcon(normalizedHue)
 
-        // Add to cache with LRU eviction
+        // Add to cache with LRU eviction.
+        // Do not call recycle() here: returned icons may still be used by active map instances.
         if (iconCache.size >= MAX_CACHE_SIZE) {
             val firstKey = iconCache.keys.first()
-            iconCache.remove(firstKey)?.recycle()
+            iconCache.remove(firstKey)
         }
         iconCache[normalizedHue] = bitmap
 
@@ -109,10 +116,12 @@ internal object MarkerIconFactory {
     }
 
     /**
-     * Clears all cached icons to free memory.
+     * Clears all cached icons by dropping references only.
+     *
+     * We intentionally avoid recycling cached bitmaps because references can still be held
+     * by active map instances and recycled bitmaps would crash canvas drawing.
      */
     fun clearCache() {
-        iconCache.values.forEach { it.recycle() }
         iconCache.clear()
     }
 }

openmapview/src/test/kotlin/de/afarber/openmapview/MarkerIconFactoryTest.kt

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2025 Alexander Farber
+ * SPDX-License-Identifier: MIT
+ *
+ * This file is part of the OpenMapView project (https://github.com/afarber/OpenMapView)
+ */
+
+package de.afarber.openmapview
+
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotSame
+import org.junit.Assert.assertSame
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+@RunWith(RobolectricTestRunner::class)
+class MarkerIconFactoryTest {
+    @Test
+    fun getDefaultIcon_SameHue_ReturnsCachedBitmap() {
+        MarkerIconFactory.clearCache()
+
+        val icon1 = MarkerIconFactory.getDefaultIcon(0f)
+        val icon2 = MarkerIconFactory.getDefaultIcon(0f)
+
+        assertSame(icon1, icon2)
+        assertFalse(icon1.isRecycled)
+    }
+
+    @Test
+    fun clearCache_DoesNotRecycleBitmapInUse() {
+        MarkerIconFactory.clearCache()
+
+        val icon = MarkerIconFactory.getDefaultIcon(120f)
+        MarkerIconFactory.clearCache()
+
+        assertFalse(icon.isRecycled)
+    }
+
+    @Test
+    fun getDefaultIcon_AfterClearCache_ReturnsFreshBitmap() {
+        MarkerIconFactory.clearCache()
+
+        val first = MarkerIconFactory.getDefaultIcon(240f)
+        MarkerIconFactory.clearCache()
+        val second = MarkerIconFactory.getDefaultIcon(240f)
+
+        assertNotSame(first, second)
+        assertFalse(second.isRecycled)
+    }
+}