feat!: rewrite android maps utils

.gemini/skills/android-maps-utils/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: maps-utils-android
+description: Guide for integrating the Google Maps Utility Library for Android (android-maps-utils) into an application. Use when users ask to add features like Marker Clustering, Heatmaps, GeoJSON, KML, or Polyline encoding/decoding.
+---
+
+# Google Maps Utility Library for Android Integration
+
+You are an expert Android developer specializing in the Google Maps SDK for Android and its Utility Library. Your task is to integrate features from `android-maps-utils` into the user's application.
+
+## 1. Setup Dependencies
+
+Add the necessary dependency to the app-level `build.gradle.kts` file:
+
+```kotlin
+dependencies {
+    // Google Maps Utility Library
+    implementation("com.google.maps.android:android-maps-utils:4.1.1") // x-release-please-version
+}
+```
+
+## 2. Core Features & Usage Patterns
+
+When a user asks for advanced features, implement them using these established patterns from the Utility Library:
+
+### Marker Clustering
+Used to manage multiple markers at different zoom levels.
+1. Create a `ClusterItem` data class.
+2. Initialize a `ClusterManager` inside `onMapReady`.
+3. Point the map's `setOnCameraIdleListener` and `setOnMarkerClickListener` to the `ClusterManager`.
+4. Add items using `clusterManager.addItem()`.
+
+### Heatmaps
+Used to represent the density of data points.
+1. Provide a `Collection<LatLng>` or `Collection<WeightedLatLng>`.
+2. Create a `HeatmapTileProvider` with the builder `HeatmapTileProvider.Builder().data(list).build()`.
+3. Add the overlay to the map: `map.addTileOverlay(TileOverlayOptions().tileProvider(provider))`.
+
+### GeoJSON and KML
+Used to import geographic data from external files.
+* **GeoJSON:** `val layer = GeoJsonLayer(map, R.raw.geojson_file, context); layer.addLayerToMap()`
+* **KML:** `val layer = KmlLayer(map, R.raw.kml_file, context); layer.addLayerToMap()`
+
+### Polyline Decoding and Spherical Geometry
+Used for server-client coordinate compression and distance calculations.
+* **Decoding:** `PolyUtil.decode(encodedPathString)`
+* **Distance:** `SphericalUtil.computeDistanceBetween(latLng1, latLng2)`
+
+## 3. Best Practices
+1. **Performance:** For massive datasets (e.g., parsing huge GeoJSON files), do not block the main thread. Parse on a background dispatcher and only call `layer.addLayerToMap()` on the UI thread.
+2. **Custom Renderers:** If the user wants custom cluster icons, extend `DefaultClusterRenderer` and override `onBeforeClusterItemRendered` and `onBeforeClusterRendered`.

.geminiignore

@@ -0,0 +1,40 @@
+# Ignore build and generated directories
+build/
+**/build/
+.gradle/
+.idea/
+.kotlin/
+.vscode/
+
+# Ignore outputs
+*.apk
+*.ap_
+*.aab
+*.dex
+*.class
+
+# Ignore large media assets (images, fonts, etc) unless specifically required
+**/*.png
+**/*.jpg
+**/*.jpeg
+**/*.gif
+**/*.webp
+**/*.svg
+**/*.mp4
+**/*.mp3
+**/*.wav
+**/*.ttf
+**/*.woff
+**/*.woff2
+**/*.otf
+
+# Ignore temporary and cache files
+tmp/
+**/tmp/
+*.log
+*.tmp
+*.bak
+*.swp
+*~.nib
+local.properties
+.DS_Store

.github/blunderbuss.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2026 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

.github/dependabot.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2026 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

.github/header-checker-lint.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2026 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

.github/stale.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2026 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2026 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

.github/workflows/lint-report.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2026 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -36,6 +36,9 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
+      - name: Create dummy secrets.properties
+        run: echo "MAPS_API_KEY=dummy" > secrets.properties
+
       - name: Run Android Lint
         run: ./gradlew lint
 

.github/workflows/report.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2026 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -42,6 +42,9 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v4
 
+      - name: Create dummy secrets.properties
+        run: echo "MAPS_API_KEY=dummy" > secrets.properties
+
       - name: Build modules
         run: ./gradlew build jacocoTestDebugUnitTestReport --stacktrace
 
@@ -56,4 +59,4 @@ jobs:
           min-coverage-changed-files: 60
           title: Code Coverage
           debug-mode: false
-          update-comment: true
+          update-comment: true

.github/workflows/test.yml

@@ -42,5 +42,8 @@ jobs:
     - name: Setup Gradle
       uses: gradle/actions/setup-gradle@v4
 
+    - name: Create dummy secrets.properties
+      run: echo "MAPS_API_KEY=dummy" > secrets.properties
+
     - name: Build modules
-      run: ./gradlew build jacocoTestDebugUnitTestReport --stacktrace
+      run: ./gradlew build jacocoTestDebugUnitTestReport --stacktrace

.gitignore

@@ -13,6 +13,10 @@ project.properties
 secrets.properties
 .kotlin
 
+# Build artifacts
+build-logic/convention/bin
+lint-checks/bin
+
 # This covers new IDEs, like Antigravity
 .vscode/
-**/bin/
+**/bin/

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+    "java.compile.nullAnalysis.mode": "automatic",
+    "java.configuration.updateBuildConfiguration": "interactive"
+}

CONTRIBUTING.md

@@ -26,3 +26,9 @@ information on using pull requests.
 
 This project follows
 [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
+
+## Using AI to Contribute
+
+This repository provides an official Gemini Skill to help AI agents navigate and contribute to the project effectively. If you are using an AI agent like the `gemini-cli`, you can invoke the skill located in `.gemini/skills/android-maps-utils` to learn how to interact with the codebase.
+
+Additionally, the `.geminiignore` file prevents AI tools from consuming large or irrelevant files to preserve context limits. You can also reference the generic `llm-integration-prompt.md` to feed into web-based LLMs for general assistance.

README.md

@@ -176,6 +176,10 @@ If you wish to disable this, you can do so by removing the initializer in your `
 
 Contributions are welcome and encouraged! If you'd like to contribute, send us a [pull request] and refer to our [code of conduct] and [contributing guide].
 
+### Using AI
+This repository provides an official Gemini Skill and an `llm-integration-prompt.md` to help AI agents navigate the codebase and provide assistance. Refer to the [contributing guide] for more details on AI usage.
+
+
 ## Terms of Service
 
 This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform [Terms of Service].

build-logic/convention/build.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 Google LLC
+ * Copyright 2026 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

build-logic/convention/src/main/kotlin/PublishingConventionPlugin.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Google LLC
+ * Copyright 2026 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -89,7 +89,7 @@ class PublishingConventionPlugin : Plugin<Project> {
                 developers {
                     developer {
                         id.set("google")
-                        name.set("Google Inc.")
+                        name.set("Google LLC")
                     }
                 }
                 organization {

build-logic/settings.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 Google LLC
+ * Copyright 2026 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

build.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 Google LLC
+ * Copyright 2026 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -47,4 +47,12 @@ allprojects {
     // {x-release-please-start-version}
     version = "4.0.0"
     // {x-release-please-end}
-}
+
+    plugins.withId("java") {
+        configure<JavaPluginExtension> {
+            toolchain {
+                languageVersion.set(JavaLanguageVersion.of(17))
+            }
+        }
+    }
+}

clustering/build.gradle.kts

@@ -0,0 +1,94 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+plugins {
+    id("kotlin-android")
+    id("org.jetbrains.dokka")
+    id("android.maps.utils.PublishingConventionPlugin")
+}
+
+android {
+    lint {
+        sarifOutput = layout.buildDirectory.file("reports/lint-results.sarif").get().asFile
+    }
+    defaultConfig {
+        compileSdk = libs.versions.compileSdk.get().toInt()
+        minSdk = 23
+        testOptions.targetSdk = libs.versions.targetSdk.get().toInt()
+        consumerProguardFiles("consumer-rules.pro")
+    }
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+    resourcePrefix = "amu_"
+
+    installation {
+        timeOutInMs = 10 * 60 * 1000 // 10 minutes
+        installOptions("-d", "-t")
+    }
+
+    kotlin {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_17)
+        }
+        jvmToolchain(17)
+    }
+
+    testOptions {
+        animationsDisabled = true
+        unitTests.isIncludeAndroidResources = true
+        unitTests.isReturnDefaultValues = true
+    }
+    namespace = "com.google.maps.android.clustering"
+}
+
+dependencies {
+    implementation(project(":ui"))
+    implementation(project(":library"))
+    implementation(project(":data"))
+    api(libs.play.services.maps)
+    implementation(libs.kotlinx.coroutines.android)
+    implementation(libs.appcompat)
+    implementation(libs.core.ktx)
+    lintPublish(project(":lint-checks"))
+    testImplementation(libs.junit)
+    testImplementation(libs.robolectric)
+    testImplementation(libs.kxml2)
+    testImplementation(libs.mockk)
+    testImplementation(libs.kotlin.test)
+    testImplementation(libs.truth)
+    implementation(libs.kotlin.stdlib.jdk8)
+
+    testImplementation(libs.mockk)
+    testImplementation(libs.kotlinx.coroutines.test)
+    testImplementation(libs.robolectric)
+    testImplementation(libs.mockito.core)
+}
+
+tasks.register("instrumentTest") {
+    dependsOn("connectedCheck")
+}
+
+if (System.getenv("JITPACK") != null) {
+    apply(plugin = "maven")
+}

clustering/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile