feat(map): draw nodes at one spot as one counted chip on both maps

androidApp/src/google/kotlin/org/meshtastic/app/map/MapView.kt

@@ -227,6 +227,7 @@ import org.meshtastic.feature.map.layers.MapLayerItem
 import org.meshtastic.feature.map.layers.opacityOf
 import org.meshtastic.feature.map.layers.toPickedMapFile
 import org.meshtastic.feature.map.mergeStationaryRuns
+import org.meshtastic.feature.map.stackCoincident
 import org.meshtastic.feature.map.terrain.GeoBounds
 import org.meshtastic.feature.map.terrain.MapterhornEndpoints
 import org.meshtastic.feature.map.tiles.mapAttributionText
@@ -243,6 +244,7 @@ import java.io.ByteArrayInputStream
 import java.io.InputStream
 import kotlin.coroutines.resume
 import kotlin.math.abs
+import kotlin.math.cos
 import kotlin.math.max
 import kotlin.math.roundToInt
 import android.graphics.Color as AndroidColor
@@ -318,6 +320,21 @@ private const val BOX_AUTHORING_MIN_CORNER_DELTA = 1e-4
 /** Above the raster basemap at -1, below every marker and shape the mesh draws at 0 and up. */
 private const val OVERLAY_Z_INDEX = -0.5f
 
+// A tapped cluster opens to at least this span, about street level, matching the Apple map's floor.
+private const val CLUSTER_FIT_MIN_SPAN_METERS = 140.0
+private val CLUSTER_FIT_PADDING = 64.dp
+private const val METERS_PER_DEGREE = 111_320.0
+
+/** These bounds grown, about their center, to at least [meters] across. */
+private fun LatLngBounds.atLeastSpan(meters: Double): LatLngBounds {
+    val halfLatitude = meters / 2 / METERS_PER_DEGREE
+    val halfLongitude = halfLatitude / cos(Math.toRadians(center.latitude)).coerceAtLeast(MIN_COS_LATITUDE)
+    return including(LatLng(center.latitude + halfLatitude, center.longitude + halfLongitude))
+        .including(LatLng(center.latitude - halfLatitude, center.longitude - halfLongitude))
+}
+
+private const val MIN_COS_LATITUDE = 0.01
+
 /** Below the offline vector layer's own water/roads/boundaries (-0.75f) so those still draw on top of the shading. */
 private const val TERRAIN_HILLSHADE_Z_INDEX = -0.9f
 
@@ -1270,14 +1287,16 @@ fun MapView(
     showClusterItemsDialog?.let { items ->
         ClusterMembersDialog(
             members =
-            items.map {
-                ClusterMemberEntry(
-                    nodeNum = it.node.num,
-                    title = it.nodeTitle,
-                    subtitle = it.nodeSnippet,
-                    node = it.node,
-                )
-            },
+            items
+                .flatMap { it.stackMembers.ifEmpty { listOf(it) } }
+                .map {
+                    ClusterMemberEntry(
+                        nodeNum = it.node.num,
+                        title = it.nodeTitle,
+                        subtitle = it.nodeSnippet,
+                        node = it.node,
+                    )
+                },
             onMemberClick = { nodeNum ->
                 navigateToNodeDetails(nodeNum)
                 showClusterItemsDialog = null
@@ -1324,16 +1343,20 @@ internal fun rememberNodeClusterItems(
     val unknownText = stringResource(Res.string.unknown)
     val nowText = stringResource(Res.string.now)
     return remember(nodes, myNodeNum, relativeTimeBucket, unknownText, nowText) {
-        nodes.map { node ->
+        fun itemFor(node: Node): NodeClusterItem {
             val latLng = LatLng((node.position.latitude_i ?: 0) * DEG_D, (node.position.longitude_i ?: 0) * DEG_D)
-            NodeClusterItem(
+            return NodeClusterItem(
                 node = node,
                 nodePosition = latLng,
                 nodeTitle = "${node.user.short_name} ${formatAgo(node.position.time, unknownText, nowText)}",
                 nodeSnippet = node.effectiveLongName,
                 myNodeNum = myNodeNum,
             )
         }
+        stackCoincident(nodes, myNodeNum).map { stack ->
+            val members = if (stack.count > 1) stack.members.map(::itemFor) else emptyList()
+            itemFor(stack.top).copy(stackMembers = members)
+        }
     }
 }
 
@@ -1359,10 +1382,12 @@ private fun MainMapContent(
     coroutineScope: CoroutineScope,
     onShowClusterItemsDialog: (List<NodeClusterItem>?) -> Unit,
 ) {
+    val clusterFitPaddingPx = with(LocalDensity.current) { CLUSTER_FIT_PADDING.roundToPx() }
     NodeClusterMarkers(
         nodeClusterItems = nodeClusterItems,
         mapFilterState = mapFilterState,
         navigateToNodeDetails = navigateToNodeDetails,
+        onStackClick = { onShowClusterItemsDialog(it) },
         onClusterClick = { cluster ->
             val items = cluster.items.toList()
             val allSameLocation = items.size > 1 && items.all { it.position == items.first().position }
@@ -1371,15 +1396,11 @@ private fun MainMapContent(
             } else {
                 val bounds = LatLngBounds.builder()
                 cluster.items.forEach { bounds.include(it.position) }
+                // Fit the members, as the Apple map does, rather than step one zoom level and leave a tight cluster
+                // needing several taps to break.
+                val fitted = bounds.build().atLeastSpan(CLUSTER_FIT_MIN_SPAN_METERS)
                 coroutineScope.launch {
-                    cameraPositionState.animate(
-                        CameraUpdateFactory.newCameraPosition(
-                            CameraPosition.Builder()
-                                .target(bounds.build().center)
-                                .zoom(cameraPositionState.position.zoom + 1)
-                                .build(),
-                        ),
-                    )
+                    cameraPositionState.animate(CameraUpdateFactory.newLatLngBounds(fitted, clusterFitPaddingPx))
                 }
                 Logger.d { "Cluster clicked! $cluster" }
             }

androidApp/src/google/kotlin/org/meshtastic/app/map/component/NodeClusterMarkers.kt

@@ -16,9 +16,18 @@
  */
 package org.meshtastic.app.map.component
 
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Badge
+import androidx.compose.material3.BadgedBox
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.key
+import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.platform.LocalConfiguration
+import androidx.compose.ui.unit.dp
 import com.google.maps.android.clustering.Cluster
 import com.google.maps.android.clustering.algo.NonHierarchicalDistanceBasedAlgorithm
 import com.google.maps.android.clustering.algo.NonHierarchicalViewBasedAlgorithm
@@ -30,9 +39,37 @@ import com.google.maps.android.compose.clustering.Clustering
 import com.google.maps.android.compose.clustering.ClusteringMarkerProperties
 import org.meshtastic.app.map.model.NodeClusterItem
 import org.meshtastic.feature.map.BaseMapViewModel
+import org.meshtastic.feature.map.stackBadgeLabel
 
 private const val MIN_CLUSTER_SIZE = 10
 
+// Matches the MapLibre map's precision fill, so both maps shade a degraded position alike.
+private const val PRECISION_FILL_ALPHA = 0.15f
+
+// BadgedBox draws the badge past its anchor's top end corner, and a marker is rasterized at its measured size, so the
+// marker is padded by this much above and to the sides to keep the badge unclipped. Never below: the marker anchors on
+// its bottom edge, and bottom padding would lift every chip off its point.
+private val STACK_BADGE_INSET = 12.dp
+
+/** A node's chip, with a Material 3 count badge when it stands for several nodes at one spot. */
+@Composable
+private fun StackedNodeChip(item: NodeClusterItem, modifier: Modifier = Modifier) {
+    Box(modifier.padding(start = STACK_BADGE_INSET, top = STACK_BADGE_INSET, end = STACK_BADGE_INSET)) {
+        BadgedBox(
+            badge = {
+                if (item.stackMembers.size > 1) {
+                    // Secondary rather than the default error color: a count of nodes is not an alert.
+                    Badge(containerColor = MaterialTheme.colorScheme.secondary) {
+                        Text(stackBadgeLabel(item.stackMembers.size))
+                    }
+                }
+            },
+        ) {
+            PulsingNodeChip(node = item.node)
+        }
+    }
+}
+
 /**
  * Threshold for switching to [NonHierarchicalViewBasedAlgorithm], matching that class's own KDoc describing itself as
  * being for "large numbers of items (>1000 markers)".
@@ -42,10 +79,9 @@ private const val VIEW_BASED_ALGORITHM_NODE_THRESHOLD = 1000
 /**
  * Renders node markers with clustering via the library's [Clustering] composable.
  *
- * Each unclustered node is composed as a [PulsingNodeChip] (`clusterItemContent`), with its z-index forwarded through
- * [ClusteringMarkerProperties]; cluster bubbles keep the library's default rendering. Native info windows
- * (title/snippet from [NodeClusterItem]) and click interactions are handled by the library renderer, and precision
- * circles are drawn for the currently-unclustered items via `clusterItemDecoration`.
+ * Each unclustered item is composed as a [PulsingNodeChip] (`clusterItemContent`), badged with a count when it stands
+ * for several nodes at one spot, with its z-index forwarded through [ClusteringMarkerProperties]; cluster bubbles keep
+ * the library's default rendering. Precision circles are drawn for every item, clustered or not.
  *
  * Requires maps-compose >= 8.4.0: earlier versions composed cluster items into a detached `ComposeView` that carried no
  * lifecycle/saved-state owners, crashing under the Navigation 3 hierarchy (fixed upstream in
@@ -65,31 +101,39 @@ fun NodeClusterMarkers(
     mapFilterState: BaseMapViewModel.MapFilterState,
     navigateToNodeDetails: (Int) -> Unit,
     onClusterClick: (Cluster<NodeClusterItem>) -> Boolean,
+    onStackClick: (List<NodeClusterItem>) -> Unit,
 ) {
     val configuration = LocalConfiguration.current
+    // One circle per stack, drawn whether or not the stack sits inside a cluster bubble, as the Apple and MapLibre maps
+    // do: the circle says where the nodes could be, which a count bubble does not.
+    if (mapFilterState.showPrecisionCircle) {
+        nodeClusterItems.forEach { item ->
+            val precisionMeters = item.getPrecisionMeters()
+            if (precisionMeters != null && precisionMeters > 0) {
+                key(item.node.num) {
+                    Circle(
+                        center = item.position,
+                        radius = precisionMeters,
+                        fillColor = Color(item.node.colors.second).copy(alpha = PRECISION_FILL_ALPHA),
+                        strokeColor = Color(item.node.colors.second),
+                        strokeWidth = 2f,
+                        zIndex = 0f,
+                    )
+                }
+            }
+        }
+    }
     Clustering(
         items = nodeClusterItems,
         onClusterClick = onClusterClick,
-        onClusterItemInfoWindowClick = { item -> navigateToNodeDetails(item.node.num) },
+        // A tap goes where the MapLibre map's does: a stack lists its nodes, a single node opens its details.
+        onClusterItemClick = { item ->
+            if (item.stackMembers.size > 1) onStackClick(item.stackMembers) else navigateToNodeDetails(item.node.num)
+            true
+        },
         clusterItemContent = { item ->
             ClusteringMarkerProperties(zIndex = item.zIndex)
-            PulsingNodeChip(node = item.node)
-        },
-        clusterItemDecoration = { item ->
-            if (mapFilterState.showPrecisionCircle) {
-                item.getPrecisionMeters()?.let { precisionMeters ->
-                    if (precisionMeters > 0) {
-                        Circle(
-                            center = item.position,
-                            radius = precisionMeters,
-                            fillColor = Color(item.node.colors.second).copy(alpha = 0.2f),
-                            strokeColor = Color(item.node.colors.second),
-                            strokeWidth = 2f,
-                            zIndex = 0f,
-                        )
-                    }
-                }
-            }
+            StackedNodeChip(item)
         },
         onClusterManager = { clusterManager ->
             // The library renderer extends DefaultClusterRenderer; raise its clustering threshold once.

androidApp/src/google/kotlin/org/meshtastic/app/map/model/NodeClusterItem.kt

@@ -28,6 +28,8 @@ data class NodeClusterItem(
     val nodeTitle: String,
     val nodeSnippet: String,
     val myNodeNum: Int? = null,
+    /** Every node at this spot, this one included, when more than one is; empty otherwise. */
+    val stackMembers: List<NodeClusterItem> = emptyList(),
 ) : ClusterItem {
     override val position: LatLng
         get() = nodePosition

androidApp/src/testGoogle/kotlin/org/meshtastic/app/map/MapNodeClusterItemsTest.kt

@@ -110,6 +110,25 @@ class MapNodeClusterItemsTest {
         assertNotSame(changedNodeItems, latestItems)
     }
 
+    @Test
+    fun `nodes at one spot become one item that carries every member`() = runComposeUiTest {
+        val spot = testNodes(count = 1).single().position
+        val nodes = testNodes(count = 4).mapIndexed { i, node -> if (i < 3) node.copy(position = spot) else node }
+        var latestItems: List<NodeClusterItem> = emptyList()
+
+        setContent {
+            val items = rememberNodeClusterItems(nodes = nodes, myNodeNum = 2, relativeTimeBucket = FIXED_TIME_BUCKET)
+            SideEffect { latestItems = items }
+        }
+        waitForIdle()
+
+        assertEquals(2, latestItems.size)
+        val stack = latestItems.first()
+        assertEquals(2, stack.node.num)
+        assertEquals(listOf(1, 2, 3), stack.stackMembers.map { it.node.num })
+        assertTrue(latestItems.last().stackMembers.isEmpty())
+    }
+
     @Test
     fun `relative time bucket advances at the next minute boundary`() = runTest {
         val startSeconds = FIXED_TIME_BUCKET * 60 + 30
@@ -144,8 +163,9 @@ class MapNodeClusterItemsTest {
             position =
             Position.Builder()
                 .also { wb ->
-                    wb.latitude_i = 210_000_000 + index
-                    wb.longitude_i = -1_570_000_000 + index
+                    // About 11 m apart, so no two fall within the 5 m that stacks nodes.
+                    wb.latitude_i = 210_000_000 + index * 1_000
+                    wb.longitude_i = -1_570_000_000 + index * 1_000
                     wb.time = 1_700_000_000
                 }
                 .build(),

docs/en/user/map-and-waypoints.md

@@ -2,7 +2,7 @@
 title: Map & Waypoints
 parent: User Guide
 nav_order: 6
-last_updated: 2026-10-21
+last_updated: 2026-10-24
 description: View node positions on the map, create and share waypoints, manage map layers and Site Planner, and control position sharing and privacy.
 aliases:
   - map
@@ -28,7 +28,9 @@ The map displays:
 
 ### Node Markers
 
-Each node that reports a position is shown as a **node chip** marker displaying the node's short name. The chip is colored by the node's own identity color (a stable color derived from its node number) — the same chip used in the node list, so a node looks the same everywhere. Marker color does **not** encode online/offline status. When a node's position updates live, its marker briefly pulses. Nearby markers are clustered as you zoom out. Tapping a cluster zooms in on it, and a cluster whose nodes all share one spot lists them instead.
+Each node that reports a position is shown as a **node chip** marker displaying the node's short name. The chip is colored by the node's own identity color (a stable color derived from its node number) — the same chip used in the node list, so a node looks the same everywhere. Marker color does **not** encode online/offline status. When a node's position updates live, its marker briefly pulses. Tapping a chip opens that node's details.
+
+Nodes within 5 m of each other, which is common when they share a reduced position precision or sit at one site, are drawn as one chip with a count on its corner, showing a favorite or your own node when one is there. Tapping it lists every node at that spot, favorites first. Nearby markers are clustered as you zoom out. Tapping a cluster zooms in to fit its nodes, and a cluster whose nodes all share one spot lists them instead. With **Show Precision Circles** on, each spot's circle stays visible inside a cluster too.
 
 ### Map Controls
 

feature/map-maplibre/src/commonMain/kotlin/org/meshtastic/feature/map/maplibre/MapGeometry.kt

@@ -39,55 +39,16 @@ private fun MapBounds.toBoundingBox(): BoundingBox = BoundingBox(
 )
 
 /**
- * The nodes clustering will leave standing on their own at [zoom].
+ * [nodes] ordered by how alone each one is: fewest neighbours within [radiusPx] first.
  *
- * Both the chips and the precision circles are only wanted for these. Clustering decides the split inside the source at
- * render time, and there is no API that reports it back, so this applies the same rule supercluster does: a point joins
- * a cluster when at least [minPoints] points fall within [radiusPx] of each other in tile pixels. Its own indexes are
- * built per whole zoom level, which is why the caller should pass a floored zoom — it also keeps this off the recompose
- * path for the fractional zoom of a pinch.
+ * This is the order to rasterize chips in. Clustering decides inside the source which nodes stand alone and there is no
+ * API that reports it back, but a node the source draws on its own has, by definition, few neighbours, so the ones that
+ * need a chip most sort to the front and the ones just past the cluster threshold come next rather than last. That
+ * makes the image budget run out on nodes buried mid-cluster, which are never drawn anyway.
  *
  * Distances are measured in Web Mercator world pixels, the space clustering itself works in, rather than in degrees — a
  * degree of longitude is a very different distance at the top of the map than at the equator.
  */
-fun unclusteredNodes(nodes: List<Node>, zoom: Int, radiusPx: Int, minPoints: Int, maxClusterZoom: Int): List<Node> {
-    // Past its ceiling the source stops clustering entirely, so everything stands alone.
-    if (zoom > maxClusterZoom || nodes.size < minPoints) return nodes
-
-    val worldSize = TILE_SIZE * 2.0.pow(zoom)
-    val pixels = nodes.map { it.worldPixel(worldSize) }
-    val cells = mutableMapOf<Pair<Int, Int>, MutableList<Int>>()
-    pixels.forEachIndexed { index, pixel -> cells.getOrPut(pixel.cell(radiusPx)) { mutableListOf() }.add(index) }
-
-    // Supercluster assigns greedily rather than counting neighbours: it walks the points, and the first one to claim a
-    // neighbourhood takes it. Counting instead called a node clustered whenever enough others were nearby, even where
-    // those others had already been taken by someone else and the node would in fact be drawn on its own — which left
-    // it with a bare dot and no chip.
-    val taken = BooleanArray(nodes.size)
-    val alone = mutableListOf<Node>()
-    pixels.indices.forEach { index ->
-        if (taken[index]) return@forEach
-        val neighbours = neighboursWithin(index, pixels, cells, radiusPx, taken)
-        if (neighbours.size >= minPoints) {
-            neighbours.forEach { taken[it] = true }
-        } else {
-            // Marked taken too: supercluster excludes every visited point from later neighbourhoods, clustered
-            // or not — a node already standing alone must not pad a later cluster up to the minimum.
-            taken[index] = true
-            alone += nodes[index]
-        }
-    }
-    return alone
-}
-
-/**
- * [nodes] ordered by how alone each one is: fewest neighbours within [radiusPx] first.
- *
- * This is the order to rasterize chips in. A node the source draws on its own has, by definition, few neighbours, so
- * the ones that need a chip most sort to the front — and the ones just past the cluster threshold, where
- * [unclusteredNodes] is most likely to have guessed wrong, come next rather than last. That makes the image budget run
- * out on nodes buried mid-cluster, which are never drawn anyway.
- */
 fun nodesByIsolation(nodes: List<Node>, zoom: Int, radiusPx: Int): List<Node> {
     val worldSize = TILE_SIZE * 2.0.pow(zoom)
     val pixels = nodes.map { it.worldPixel(worldSize) }