feat(flow): add Kotlin Flow extensions for LocationManager and shape managers

[dkhawk]

This PR introduces comprehensive Kotlin Flow extensions to the maps-utils-ktx library, adding modern reactive APIs for shape collections, ClusterManager, and device location tracking.

All changes are fully backward-compatible and verified with robust unit/integration tests.

1. Fused & Device Location Flow Tracking 🗺️📍

Exposed two subscriber-driven Flow APIs on LocationManager for streaming coordinates:

• coarseLocationEvents(): Streams coarse WiFi/Cell coordinates (NETWORK_PROVIDER with fallback to PASSIVE_PROVIDER) under @RequiresPermission(Manifest.permission.ACCESS_COARSE_LOCATION).
• fineLocationEvents(): Streams precise satellite coordinates (GPS_PROVIDER) under @RequiresPermission(Manifest.permission.ACCESS_FINE_LOCATION).
• Automatic Subscriber Lifecycle: Setup requests start only when actively collected, and cleanly unregister (removeUpdates) immediately when collectors cancel or close, eliminating memory leaks.
• Hardware State Clean Closure: The flow channel is closed cleanly with a CancellationException if the user disables location providers (GPS/Network) mid-collection in Android Settings.
• Backward Compatibility: Fully overrides LocationListener to ensure seamless execution on minSdkVersion 23.

2. Shape Collection & Cluster Flow Extensions 📦

Added clean Flow wrappers for all listener callbacks in managers:

• ClusterManager: clusterClickEvents(), clusterItemClickEvents(), clusterInfoWindowClickEvents(), clusterInfoWindowLongClickEvents(), clusterItemInfoWindowClickEvents(), and clusterItemInfoWindowLongClickEvents().
• Collection Managers: Added clickEvents() to MarkerManager.Collection (including info window click/long-click flows), PolylineManager.Collection, PolygonManager.Collection, CircleManager.Collection, and GroundOverlayManager.Collection.
• API Compatibility Invariant: Completely preserved the legacy addPolyline and addPolygon inline helper extension functions to prevent any breaking regressions.

3. Adversarial Unit Tests 🧪

Authored a comprehensive unit test suite in maps-utils-ktx simulating concurrent edge-cases:

• LocationManagerTest.kt: Verifies registration, flow emissions, automatic unregistration, and hardens provider disabled closure (testCoarseLocationProviderDisabled).
• CollectionManagersTest.kt: Emulates the single-listener slot registration of the Maps SDK to verify that concurrent flow subscribers cleanly hijack and disconnect correctly (testConcurrentCollectionMarkerClick).
• ClusterManagerTest.kt: Thoroughly tests all 6 clustering flow events.

4. Working Samples in Demo App 📱

Updated the sample app MainActivity.kt and AndroidManifest.xml to prompt for runtime location permissions and demonstrate live consumption of LocationManager flows, ClusterManager flows, and Marker collection flows using repeatOnLifecycle collection blocks.

---

Verification Status

• 100% of compilation checks and unit tests pass successfully with zero failures!

---

🧠 Workspace Assist & Gemini Agentic Skill Package

This PR introduces an ecosystem-standard local Gemini Agentic Skill configuration under the .gemini/ directory. This establishes standard assist guidelines and style rules for the android-maps-ktx library to assist developers and autonomous coding assistants.

Skill Structure & Guides:

• .gemini/config.yaml / styleguide.md: Safety guidelines enforcing coroutine/Flow idioms, and safeguarding against single-subscriber callback slot hijacking.
• 📂 .gemini/skills/android-maps-ktx/: Core capability registration package:
  • SKILL.md: Scope of capabilities and triggers.
  • references/gotchas.md: Guide on multicasting flows via .shareIn() to prevent listener hijacking, and Android 15+ tuner demo mode safety.
  • references/location-flows.md: Guide on coarse/fine location flows, permissions, and adb coordinates injections.
  • references/clustering-flows.md: Guide on Views-based KTX clustering, camera glide, and badge sweeps.
  • references/collection-flows.md: Guide on custom overlay click flows, Azure marker popups, and circle color swapping visual confirmation.

[snippet-bot]

Here is the summary of changes.

You are about to add 11 region tags.

• app/src/main/java/com/google/maps/android/ktx/demo/snippets/ClusteringSnippets.kt:44, tag maps_android_ktx_flow_cluster_clicks
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/ClusteringSnippets.kt:64, tag maps_android_ktx_flow_cluster_item_clicks
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/CollectionSnippets.kt:41, tag maps_android_ktx_flow_marker_collection_clicks
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/CollectionSnippets.kt:59, tag maps_android_ktx_flow_circle_collection_clicks
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/ExistingKtxSnippets.kt:50, tag maps_android_ktx_coroutines_init
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/ExistingKtxSnippets.kt:69, tag maps_android_ktx_coroutines_animate
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/ExistingKtxSnippets.kt:89, tag maps_android_ktx_flow_camera_events
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/ExistingKtxSnippets.kt:106, tag maps_android_ktx_utils_polygon_contains
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/ExistingKtxSnippets.kt:120, tag maps_android_ktx_utils_geojson
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/LocationSnippets.kt:45, tag maps_android_ktx_flow_coarse_location
• app/src/main/java/com/google/maps/android/ktx/demo/snippets/LocationSnippets.kt:71, tag maps_android_ktx_flow_fine_location

---

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

• Refresh this comment

[github-advanced-security]

Android Lint found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.