@trackunit/react-map 0.1.24 → 0.1.27

package/index.cjs.js

@@ -4470,6 +4470,122 @@ function MapMarkerIcon({ name, size, title }) {
         }, title: title, children: jsxRuntime.jsx(reactComponents.Icon, { ariaHidden: true, name: name, size: "small" }) }));
 }
 
+const EMPTY_SET = new Set();
+/**
+ * Order-sensitive equality. The returned Set keeps a stable reference only when
+ * both membership AND nearest-first ordering are identical. A nearest-first swap
+ * within the same id set produces a new reference so consumers that cap to the
+ * N closest via iteration order see the updated ranking.
+ */
+const sameNearby = (a, b) => {
+    if (a === b)
+        return true;
+    if (a.size !== b.size)
+        return false;
+    const ai = a.values();
+    const bi = b.values();
+    for (let i = 0; i < a.size; i++) {
+        if (ai.next().value !== bi.next().value)
+            return false;
+    }
+    return true;
+};
+const computeNearby = (cursor, entities, zoom, tileSize, radiusPx) => {
+    if (entities.length === 0)
+        return EMPTY_SET;
+    // Project once per recompute: worldSize is constant for all entities at this
+    // camera, so hoist Math.pow(2, zoom) out of the per-entity loop.
+    const worldSize = tileSize * Math.pow(2, zoom);
+    const [cursorPx, cursorPy] = geoJsonUtils.lngLatToMercatorPxWS(cursor[0], cursor[1], worldSize);
+    const radiusSq = radiusPx * radiusPx;
+    const hits = [];
+    for (const entity of entities) {
+        const [px, py] = geoJsonUtils.lngLatToMercatorPxWS(entity.position[0], entity.position[1], worldSize);
+        const dx = px - cursorPx;
+        const dy = py - cursorPy;
+        // Shortest-path x-distance across the antimeridian: a cursor at 179.99° and
+        // an entity at −179.99° are ~0.02° apart on screen but raw Mercator dx is
+        // nearly worldSize. Taking min(|dx|, worldSize−|dx|) collapses that gap.
+        const absDx = Math.abs(dx);
+        const wrappedDx = Math.min(absDx, worldSize - absDx);
+        const distSq = wrappedDx * wrappedDx + dy * dy;
+        if (distSq <= radiusSq)
+            hits.push({ id: entity.id, distSq });
+    }
+    if (hits.length === 0)
+        return EMPTY_SET;
+    // Nearest-first so a consumer can cap to the N closest by iteration order.
+    hits.sort((a, b) => a.distSq - b.distSq);
+    return new Set(hits.map(hit => hit.id));
+};
+/**
+ * Reference/value equality for the recompute inputs. `entities` is compared by
+ * reference (the caller memoises it), keeping the per-render change check O(1)
+ * rather than deep-comparing the whole marker array on every frame.
+ */
+const sameInputs = (a, b) => a.entities === b.entities && a.zoom === b.zoom && a.tileSize === b.tileSize && a.radiusPx === b.radiusPx;
+/**
+ * The **Entities Near Cursor** primitive: returns a referentially-stable
+ * `ReadonlySet<string>` of entity ids whose projected position is within
+ * `radiusPx` CSS pixels of the projected cursor, nearest-first.
+ *
+ * It is the point-marker counterpart to **Shapes Under Cursor** and runs on the
+ * same pure Web Mercator substrate (`@trackunit/geo-json-utils`) fed by
+ * `useCameraState` + the RAF-throttled `pointermove` event — adapter-agnostic by
+ * construction (see ADR-0025). The hook owns radius geometry only; consumers
+ * decide why the ids are wanted (preload, highlight, …) and may cap the set to
+ * the nearest N via iteration order.
+ *
+ * The returned Set keeps a stable identity until either its membership or its
+ * nearest-first ordering changes, so wiring it straight into a memo or query
+ * does not churn while the cursor drifts within the same cluster of dots at the
+ * same relative distances. The host only re-renders when membership or ordering
+ * actually changes: the cursor lives in a ref and recomputes commit through an
+ * order-sensitive functional update that bails out (returns the previous Set)
+ * when nothing changed.
+ */
+const useEntitiesNearCursor = (api, options) => {
+    const { entities, radiusPx } = options;
+    const { zoom } = useCameraState(api);
+    const { tileSize } = api.state;
+    const [nearby, setNearby] = react.useState(EMPTY_SET);
+    // Latest cursor position and recompute inputs, read by the stable subscription
+    // and recompute without re-subscribing. Written only in effects / event
+    // handlers — never during render.
+    const cursorRef = react.useRef(null);
+    const inputsRef = react.useRef({ entities, zoom, tileSize, radiusPx });
+    const recompute = react.useCallback(() => {
+        const cursor = cursorRef.current;
+        const current = inputsRef.current;
+        const next = cursor === null
+            ? EMPTY_SET
+            : computeNearby(cursor, current.entities, current.zoom, current.tileSize, current.radiusPx);
+        // Membership-gated functional update: return the previous reference when the
+        // id set is unchanged so React bails out of the re-render and the output
+        // identity stays stable across cursor drift within the same cluster.
+        setNearby(prev => (sameNearby(prev, next) ? prev : next));
+    }, []);
+    // Keep the recompute inputs fresh and recompute when the camera, entities, or
+    // radius change while the cursor stays put (e.g. zooming under a stationary
+    // pointer brings new dots into radius). `useWatch` owns the effect, so this
+    // file never calls setState synchronously inside its own effect.
+    reactComponents.useWatch({
+        value: { entities, zoom, tileSize, radiusPx },
+        immediate: true,
+        isEqual: sameInputs,
+        onChange: latest => {
+            inputsRef.current = latest;
+            recompute();
+        },
+    });
+    // Track the cursor and recompute on each throttled move.
+    react.useEffect(() => api.on("pointermove", event => {
+        cursorRef.current = event.position;
+        recompute();
+    }), [api, recompute]);
+    return nearby;
+};
+
 const DEFAULT_DEBOUNCE_MS = 150;
 /**
  * Fires `onShouldPreload` for the currently hovered entity after a debounce
@@ -7461,14 +7577,17 @@ const degreesPerPixel = (zoom, tileSize) => 360 / (tileSize * Math.pow(2, zoom))
 const shapesUnderCursor = (position, features, options) => {
     const { zoom, tileSize, strokeWidthFor, visibleFillFor, layerGeodesic, featureStyles } = options;
     // Densify before boundary-distance and point-in-polygon math so stroke/fill
-    // hit-tests follow great-circle arcs on large polygons.
+    // hit-tests follow great-circle arcs on large polygons. Always defer to
+    // densifyGeodesicFeatures' per-feature resolution (geodesic override > layer
+    // default) rather than short-circuiting on layerGeodesic === false — that
+    // matches the Mapbox render path, so the hit-test geometry never diverges
+    // from the painted edge when a feature opts into geodesic under a non-geodesic
+    // layer. The util returns the original collection when nothing is densified.
     const featureCollection = {
         type: "FeatureCollection",
         features: Array.from(features),
     };
-    const densifiedFeatures = layerGeodesic !== false
-        ? reactMapAdapterShared.densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
-        : features;
+    const densifiedFeatures = reactMapAdapterShared.densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features;
     const degPerPx = degreesPerPixel(zoom, tileSize);
     const hits = [];
     for (const feature of densifiedFeatures) {
@@ -7580,14 +7699,16 @@ const promoteToFront = (order, id) => order.includes(id) ? [id, ...order.filter(
  * preserved and translucent fills do not compound under the winner.
  */
 const computePromotionGroupFills = (members, winnerId, restingPeerFills = new Map(), layerGeodesic = undefined, featureStyles = undefined) => {
-    // Densify before peer-vs-winner clip so promotion clips follow great-circle arcs.
+    // Densify before peer-vs-winner clip so promotion clips follow great-circle
+    // arcs. Always defer to densifyGeodesicFeatures' per-feature resolution
+    // (geodesic override > layer default) rather than short-circuiting on
+    // layerGeodesic === false — keeps the clip geometry in step with the render
+    // path. The util returns the original collection when nothing is densified.
     const featureCollection = {
         type: "FeatureCollection",
         features: Array.from(members),
     };
-    const densifiedMembers = layerGeodesic !== false
-        ? reactMapAdapterShared.densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
-        : members;
+    const densifiedMembers = reactMapAdapterShared.densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features;
     const geometries = new Map();
     for (const feature of densifiedMembers) {
         if (feature.id === undefined)
@@ -7627,14 +7748,16 @@ const computePromotionGroupFills = (members, winnerId, restingPeerFills = new Ma
 const computeFillTiling = (input) => {
     const { features, viewportBounds, resolveStackOrder, selectedFeatureId, suppressedFeatureIds, layerGeodesic, featureStyles, } = input;
     // Densify before any polygon/boundary math so clip geometry follows great-circle
-    // arcs on large polygons (mirrors the ADR-0024 precedent for edge labels).
+    // arcs on large polygons (mirrors the ADR-0024 precedent for edge labels). Always
+    // defer to densifyGeodesicFeatures' per-feature resolution (geodesic override >
+    // layer default) rather than short-circuiting on layerGeodesic === false — keeps
+    // the clip geometry in step with the Mapbox render path. The util returns the
+    // original collection when nothing is densified.
     const featureCollection = {
         type: "FeatureCollection",
         features: Array.from(features),
     };
-    const densifiedFeatures = layerGeodesic !== false
-        ? reactMapAdapterShared.densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
-        : features;
+    const densifiedFeatures = reactMapAdapterShared.densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features;
     const records = [];
     for (const feature of densifiedFeatures) {
         if (feature.id === undefined)
@@ -8111,7 +8234,6 @@ const DEG_TO_RAD = Math.PI / 180;
 const RAD_TO_DEG$1 = 180 / Math.PI;
 const DEFAULT_EDGE_LABEL_INSET_PX = 6;
 const LABEL_HEIGHT_PX = 20;
-const MAX_WEB_MERCATOR_LAT = 85.05112878;
 const EARTH_RADIUS_KM = 6371;
 const GEODESIC_PLACEMENT_MAX_SEGMENT_RAD = reactMapAdapterShared.GEODESIC_MAX_SEGMENT_KM / EARTH_RADIUS_KM;
 /**
@@ -8171,24 +8293,6 @@ const clipSegmentToRect = (x0, y0, x1, y1, xMin, yMin, xMax, yMax) => {
     }
     return [x0 + tMin * dx, y0 + tMin * dy, x0 + tMax * dx, y0 + tMax * dy];
 };
-/**
- * Inner implementations that accept a pre-computed worldSize.
- * Used by findBestEdgePosition to avoid recomputing Math.pow(2, zoom) on
- * every vertex when projecting dozens of geodesic sub-segments per frame.
- */
-const lngLatToMercatorPxWS = (lng, lat, worldSize) => {
-    const clampedLat = Math.max(-MAX_WEB_MERCATOR_LAT, Math.min(MAX_WEB_MERCATOR_LAT, lat));
-    const x = ((lng + 180) / 360) * worldSize;
-    const latRad = clampedLat * DEG_TO_RAD;
-    const y = (0.5 - Math.log(Math.tan(Math.PI / 4 + latRad / 2)) / (2 * Math.PI)) * worldSize;
-    return [x, y];
-};
-const mercatorPxToLngLatWS = (px, py, worldSize) => {
-    const lng = (px / worldSize) * 360 - 180;
-    const lat = Math.atan(Math.sinh(Math.PI * (1 - (2 * py) / worldSize))) * RAD_TO_DEG$1;
-    return [lng, lat];
-};
-const lngLatToWebMercatorPx = (lng, lat, zoom, tileSize = 256) => lngLatToMercatorPxWS(lng, lat, tileSize * Math.pow(2, zoom));
 /**
  * Determine which side of an edge the geometry interior lies on, in screen space.
  * Returns "above" if the label should extend above the edge (interior is below),
@@ -8539,8 +8643,8 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
     // edge — causing labels to float away from the line at mid-edge positions.
     // Clipping in pixel space ensures clip endpoints lie exactly on the
     // rendered edge, which fixes the floating at the midpoint of long edges.
-    const [pxViewMin, pyViewMin] = lngLatToMercatorPxWS(minLon, maxLat, worldSize);
-    const [pxViewMax, pyViewMax] = lngLatToMercatorPxWS(maxLon, minLat, worldSize);
+    const [pxViewMin, pyViewMin] = geoJsonUtils.lngLatToMercatorPxWS(minLon, maxLat, worldSize);
+    const [pxViewMax, pyViewMax] = geoJsonUtils.lngLatToMercatorPxWS(maxLon, minLat, worldSize);
     const viewportWidth = pxViewMax - pxViewMin;
     const viewportHeight = pyViewMax - pyViewMin;
     for (let edgeIdx = 0; edgeIdx < edges.length; edgeIdx++) {
@@ -8558,8 +8662,8 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
         const segmentClips = [];
         for (const segment of getPlacementSegments(edge[0], edge[1], geodesic)) {
             const { start, end } = segment;
-            const [startPxX, startPxY] = lngLatToMercatorPxWS(start[0], start[1], worldSize);
-            const [endPxX, endPxY] = lngLatToMercatorPxWS(end[0], end[1], worldSize);
+            const [startPxX, startPxY] = geoJsonUtils.lngLatToMercatorPxWS(start[0], start[1], worldSize);
+            const [endPxX, endPxY] = geoJsonUtils.lngLatToMercatorPxWS(end[0], end[1], worldSize);
             const clippedPx = clipSegmentToRect(startPxX, startPxY, endPxX, endPxY, pxViewMin, pyViewMin, pxViewMax, pyViewMax);
             if (!clippedPx)
                 continue;
@@ -8575,8 +8679,8 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
                 : [-rawDx / segPxLen, -rawDy / segPxLen];
             // Inverse-project pixel clip endpoints to geo for outward-side and
             // polygon-interior checks (qualitative, so approximately correct geo is fine).
-            const [ex0, ey0] = mercatorPxToLngLatWS(px0, py0, worldSize);
-            const [ex1, ey1] = mercatorPxToLngLatWS(px1, py1, worldSize);
+            const [ex0, ey0] = geoJsonUtils.mercatorPxToLngLatWS(px0, py0, worldSize);
+            const [ex1, ey1] = geoJsonUtils.mercatorPxToLngLatWS(px1, py1, worldSize);
             const midLat = (ey0 + ey1) / 2;
             const edgeOutwardSide = centroid !== null ? computeOutwardSide(ex0, ey0, ex1, ey1, centroid, midLat) : "above";
             if (isLabelInsidePolygon(ex0, ey0, ex1, ey1, features, centroid))
@@ -8713,7 +8817,7 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
         for (const matchingCandidate of candidates.filter(c => isSameEdge(previousEdgeIdentity, c.edge))) {
             if (matchingCandidate.pxLen <= 0)
                 continue;
-            const [prevAnchorAbsPx, prevAnchorAbsPy] = lngLatToMercatorPxWS(previousAnchorGeo[0], previousAnchorGeo[1], worldSize);
+            const [prevAnchorAbsPx, prevAnchorAbsPy] = geoJsonUtils.lngLatToMercatorPxWS(previousAnchorGeo[0], previousAnchorGeo[1], worldSize);
             const prevAnchorRelX = prevAnchorAbsPx - pxViewMin;
             const prevAnchorRelY = prevAnchorAbsPy - pyViewMin;
             const dx = prevAnchorRelX - matchingCandidate.readingStartPx[0];
@@ -8783,7 +8887,7 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
             // great-circle arc by computing the arc fraction via angular distance
             // from A. This places the label physically on the visible curved arc
             // rather than on the straight Mercator chord.
-            const [approxLng, approxLat] = mercatorPxToLngLatWS(anchorRelX + pxViewMin, anchorRelY + pyViewMin, worldSize);
+            const [approxLng, approxLat] = geoJsonUtils.mercatorPxToLngLatWS(anchorRelX + pxViewMin, anchorRelY + pyViewMin, worldSize);
             const tArc = Math.max(0, Math.min(1, reactMapAdapterShared.angularDistance(A[0], A[1], approxLng, approxLat) / delta));
             const geoAnchor = reactMapAdapterShared.intermediatePoint(A, B, tArc, delta);
             position = [geoAnchor[0], geoAnchor[1]];
@@ -8797,13 +8901,13 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
             const centerOffsetFactor = resolvedAnchor === "left" ? 1 : resolvedAnchor === "right" ? -1 : 0;
             const centerRelX = anchorRelX + centerOffsetFactor * halfLabelPx * best.directionPx[0];
             const centerRelY = anchorRelY + centerOffsetFactor * halfLabelPx * best.directionPx[1];
-            const [approxCenterLng, approxCenterLat] = mercatorPxToLngLatWS(centerRelX + pxViewMin, centerRelY + pyViewMin, worldSize);
+            const [approxCenterLng, approxCenterLat] = geoJsonUtils.mercatorPxToLngLatWS(centerRelX + pxViewMin, centerRelY + pyViewMin, worldSize);
             const tArcCenter = Math.max(0, Math.min(1, reactMapAdapterShared.angularDistance(A[0], A[1], approxCenterLng, approxCenterLat) / delta));
             const TANGENT_EPS = 0.001;
             const p0 = reactMapAdapterShared.intermediatePoint(A, B, Math.max(0, tArcCenter - TANGENT_EPS), delta);
             const p1 = reactMapAdapterShared.intermediatePoint(A, B, Math.min(1, tArcCenter + TANGENT_EPS), delta);
-            const [bx, by] = lngLatToMercatorPxWS(p0[0], p0[1], worldSize);
-            const [ax, ay] = lngLatToMercatorPxWS(p1[0], p1[1], worldSize);
+            const [bx, by] = geoJsonUtils.lngLatToMercatorPxWS(p0[0], p0[1], worldSize);
+            const [ax, ay] = geoJsonUtils.lngLatToMercatorPxWS(p1[0], p1[1], worldSize);
             const ddx = ax - bx;
             const ddy = ay - by;
             const tangentLen = Math.sqrt(ddx * ddx + ddy * ddy);
@@ -8820,13 +8924,13 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
         }
         else {
             // Co-located vertices — fall back to Mercator straight-line.
-            const [anchorLng, anchorLat] = mercatorPxToLngLatWS(anchorRelX + pxViewMin, anchorRelY + pyViewMin, worldSize);
+            const [anchorLng, anchorLat] = geoJsonUtils.mercatorPxToLngLatWS(anchorRelX + pxViewMin, anchorRelY + pyViewMin, worldSize);
             position = [anchorLng, anchorLat];
             resolvedDirectionPx = best.directionPx;
         }
     }
     else {
-        const [anchorLng, anchorLat] = mercatorPxToLngLatWS(anchorRelX + pxViewMin, anchorRelY + pyViewMin, worldSize);
+        const [anchorLng, anchorLat] = geoJsonUtils.mercatorPxToLngLatWS(anchorRelX + pxViewMin, anchorRelY + pyViewMin, worldSize);
         position = [anchorLng, anchorLat];
         resolvedDirectionPx = best.directionPx;
     }
@@ -9014,19 +9118,19 @@ const computeEdgeProperties = (start, end, geometry, zoom, tileSize, geodesic =
             const TANGENT_EPS = 0.001;
             const p0 = reactMapAdapterShared.intermediatePoint(start, end, 0.5 - TANGENT_EPS, delta);
             const p1 = reactMapAdapterShared.intermediatePoint(start, end, 0.5 + TANGENT_EPS, delta);
-            const [bx, by] = lngLatToWebMercatorPx(p0[0], p0[1], zoom, tileSize);
-            const [ax, ay] = lngLatToWebMercatorPx(p1[0], p1[1], zoom, tileSize);
+            const [bx, by] = geoJsonUtils.lngLatToWebMercatorPx(p0[0], p0[1], zoom, tileSize);
+            const [ax, ay] = geoJsonUtils.lngLatToWebMercatorPx(p1[0], p1[1], zoom, tileSize);
             angleDeg = normalizeReadableAngle(Math.atan2(ay - by, ax - bx) * RAD_TO_DEG);
         }
         else {
-            const [startPx, startPy] = lngLatToWebMercatorPx(start[0], start[1], zoom, tileSize);
-            const [endPx, endPy] = lngLatToWebMercatorPx(end[0], end[1], zoom, tileSize);
+            const [startPx, startPy] = geoJsonUtils.lngLatToWebMercatorPx(start[0], start[1], zoom, tileSize);
+            const [endPx, endPy] = geoJsonUtils.lngLatToWebMercatorPx(end[0], end[1], zoom, tileSize);
             angleDeg = normalizeReadableAngle(Math.atan2(endPy - startPy, endPx - startPx) * RAD_TO_DEG);
         }
     }
     else {
-        const [startPx, startPy] = lngLatToWebMercatorPx(start[0], start[1], zoom, tileSize);
-        const [endPx, endPy] = lngLatToWebMercatorPx(end[0], end[1], zoom, tileSize);
+        const [startPx, startPy] = geoJsonUtils.lngLatToWebMercatorPx(start[0], start[1], zoom, tileSize);
+        const [endPx, endPy] = geoJsonUtils.lngLatToWebMercatorPx(end[0], end[1], zoom, tileSize);
         angleDeg = normalizeReadableAngle(Math.atan2(endPy - startPy, endPx - startPx) * RAD_TO_DEG);
     }
     const pixelLength = geoJsonUtils.edgePixelLength(start[0], start[1], end[0], end[1], zoom, midLat, tileSize);
@@ -10031,6 +10135,8 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
     }, [suppressedFillIdsByHandle]);
     const debounceTimerRef = react.useRef(null);
     const idleRecomputeTimerRef = react.useRef(null);
+    /** Pending deferred selection re-tile (double-rAF handle); see selection effect. */
+    const selectionRecomputeRafRef = react.useRef(null);
     // Currently emitted overrides — used for hit-testing visible fills in handleSettle.
     const prevFillOverridesRef = react.useRef(EMPTY_OVERRIDES);
     const prevZIndexOverridesRef = react.useRef(EMPTY_ZINDEX_OVERRIDES);
@@ -10285,8 +10391,30 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
             return;
         recompute();
     }, [recompute, tilingContentKey]);
+    // Selection forces the selected feature to the front of its overlap group,
+    // which requires a resting re-tile (computeFillTiling depends on
+    // selectedFeatureId via resolveStackOrder). For large layers that re-tile is
+    // expensive (~600ms for 200 polygons over global bounds) and must NOT block
+    // the interaction's first paint — e.g. a panel opening on the clicked feature.
+    // Defer it past the next paint with a double rAF so the click commits and
+    // paints immediately, then the selected polygon restacks one frame later.
+    // Rapid selections coalesce: each schedule cancels the previous pending one.
     react.useEffect(() => {
-        recompute();
+        if (selectionRecomputeRafRef.current !== null) {
+            cancelAnimationFrame(selectionRecomputeRafRef.current);
+        }
+        selectionRecomputeRafRef.current = requestAnimationFrame(() => {
+            selectionRecomputeRafRef.current = requestAnimationFrame(() => {
+                selectionRecomputeRafRef.current = null;
+                recompute();
+            });
+        });
+        return () => {
+            if (selectionRecomputeRafRef.current !== null) {
+                cancelAnimationFrame(selectionRecomputeRafRef.current);
+                selectionRecomputeRafRef.current = null;
+            }
+        };
     }, [recompute, selectedFeatureId]);
     // Suppression changes must trigger a recompute so EMPTY_FILL entries are
     // added / removed even when the map is idle (covers the decorations-vs-tiling
@@ -10538,7 +10666,24 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
     const [viewportStyleOverrides, setViewportStyleOverrides] = react.useState(new Map());
     const [fillGeometryOverrides, setFillGeometryOverrides] = react.useState(new Map());
     const [zIndexOverrides, setZIndexOverrides] = react.useState(new Map());
+    // Mirror the authoritative hovered entity into a ref. The settle channel fires
+    // on a ~120ms debounce (outside React's render cycle) and needs to read the
+    // current hover synchronously.
+    const hoveredEntityRef = react.useRef(layers.interaction.hoveredEntity);
+    react.useEffect(() => {
+        hoveredEntityRef.current = layers.interaction.hoveredEntity;
+    }, [layers.interaction.hoveredEntity]);
     const onSettledHover = react.useCallback((handleId, featureId) => {
+        // Z-order truth: markers and clusters render above shapes (DOM/symbol portals
+        // over the polygon canvas). When a point entity is the current hovered entity
+        // it is the authoritative top hit under the cursor, so the shape settle — which
+        // is not itself position-gated against the marker layer — must not overwrite it.
+        // Without this guard, moving onto an asset pill that overlaps a site would leave
+        // the covered site as `hoveredEntity` (a stale cross-channel hover write). We read
+        // the single source of truth (`hoveredEntity`) rather than a parallel guard flag.
+        const hovered = hoveredEntityRef.current;
+        if (hovered !== null && (hovered.type === "marker" || hovered.type === "cluster"))
+            return;
         // Fill tiling only fires on polygonal features — shapeType is always "polygon".
         layers.hover({ type: "shape", id: featureId, handleId, shapeType: "polygon" });
     }, [layers]);
@@ -10600,17 +10745,27 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
         });
     }, [layers.handles, adaptiveByLayer, viewportStyleOverrides, fillGeometryOverrides, zIndexOverrides, queryAt]);
     const { renderedSourceIds, hasSourceReadiness, readyRevision } = useLayerHandleSync(layerPort, enrichedHandles, layers.interaction, decorationLayers);
-    const hoveredEntityRef = react.useRef(layers.interaction.hoveredEntity);
-    react.useEffect(() => {
-        hoveredEntityRef.current = layers.interaction.hoveredEntity;
-    }, [layers.interaction.hoveredEntity]);
     const coordinatedSelect = react.useCallback((entity) => {
-        if (entity !== null && hoveredEntityRef.current !== null) {
-            layers.select(hoveredEntityRef.current);
-        }
-        else {
+        const hovered = hoveredEntityRef.current;
+        if (entity === null || hovered === null) {
             layers.select(entity);
+            return;
+        }
+        // Default to the entity the click actually carried — it is the freshest,
+        // most direct signal of what the user hit, and it hit-tests per element
+        // for markers/clusters/routes. The single exception is a shape-on-shape
+        // conflict: the adapter resolves polygon clicks with its own z-order and
+        // full (unclipped) hit areas, so it cannot honor the fill-tiling ownership
+        // model that decides which overlapping site is visually on top (ADR-0021).
+        // There the settle-resolved hovered shape is the precise winner, so we
+        // trust it instead. This is also why an asset pill overlapping a site
+        // selects the asset: a marker click is never a shape, so it bypasses the
+        // exception even when a stale site shape is still the hovered entity.
+        if (entity.type === "shape" && hovered.type === "shape") {
+            layers.select(hovered);
+            return;
         }
+        layers.select(entity);
     }, [layers]);
     const fitOnDblClick = useDblClickFit(api, layers.handles);
     const handleDblClick = react.useCallback((entity) => {
@@ -11671,6 +11826,7 @@ exports.useControlStack = useControlStack;
 exports.useControls = useControls;
 exports.useDefaultControls = useDefaultControls;
 exports.useDirectionIndicator = useDirectionIndicator;
+exports.useEntitiesNearCursor = useEntitiesNearCursor;
 exports.useExpandedIds = useExpandedIds;
 exports.useFitFeatureBounds = useFitFeatureBounds;
 exports.useFitToContent = useFitToContent;

package/index.esm.js

@@ -15,7 +15,7 @@ import { useModal, Modal as Modal$1, ModalHeader, ModalBody } from '@trackunit/r
 import { z } from 'zod';
 import { PieChart } from 'react-minimal-pie-chart';
 import { tailwindPalette } from '@trackunit/ui-design-tokens';
-import { validateBboxWithFallback, extractPositionsFromGeometry, geoJsonPositionSchema, validateFeatureCollection, EMPTY_FEATURE_COLLECTION, validateBbox, projectPolygonalToWebMercator, geoJsonPolygonDifference, unprojectPolygonalFromWebMercator, distanceToGeoJsonPolygonBoundary, getGeoJsonPolygonIntersection, isFullyContainedInGeoJsonGeometry, isGeoJsonPointInPolygon, isBboxInsideFeatureCollection, extractEdges, computeGeometryCentroid, isPositionInsideRing, edgePixelLength } from '@trackunit/geo-json-utils';
+import { lngLatToMercatorPxWS, validateBboxWithFallback, extractPositionsFromGeometry, geoJsonPositionSchema, validateFeatureCollection, EMPTY_FEATURE_COLLECTION, validateBbox, projectPolygonalToWebMercator, geoJsonPolygonDifference, unprojectPolygonalFromWebMercator, distanceToGeoJsonPolygonBoundary, getGeoJsonPolygonIntersection, isFullyContainedInGeoJsonGeometry, isGeoJsonPointInPolygon, isBboxInsideFeatureCollection, extractEdges, computeGeometryCentroid, mercatorPxToLngLatWS, isPositionInsideRing, lngLatToWebMercatorPx, edgePixelLength } from '@trackunit/geo-json-utils';
 import { darkenColor, lightenColor } from '@trackunit/react-map-color-utils';
 
 var defaultTranslations = {
@@ -4469,6 +4469,122 @@ function MapMarkerIcon({ name, size, title }) {
         }, title: title, children: jsx(Icon, { ariaHidden: true, name: name, size: "small" }) }));
 }
 
+const EMPTY_SET = new Set();
+/**
+ * Order-sensitive equality. The returned Set keeps a stable reference only when
+ * both membership AND nearest-first ordering are identical. A nearest-first swap
+ * within the same id set produces a new reference so consumers that cap to the
+ * N closest via iteration order see the updated ranking.
+ */
+const sameNearby = (a, b) => {
+    if (a === b)
+        return true;
+    if (a.size !== b.size)
+        return false;
+    const ai = a.values();
+    const bi = b.values();
+    for (let i = 0; i < a.size; i++) {
+        if (ai.next().value !== bi.next().value)
+            return false;
+    }
+    return true;
+};
+const computeNearby = (cursor, entities, zoom, tileSize, radiusPx) => {
+    if (entities.length === 0)
+        return EMPTY_SET;
+    // Project once per recompute: worldSize is constant for all entities at this
+    // camera, so hoist Math.pow(2, zoom) out of the per-entity loop.
+    const worldSize = tileSize * Math.pow(2, zoom);
+    const [cursorPx, cursorPy] = lngLatToMercatorPxWS(cursor[0], cursor[1], worldSize);
+    const radiusSq = radiusPx * radiusPx;
+    const hits = [];
+    for (const entity of entities) {
+        const [px, py] = lngLatToMercatorPxWS(entity.position[0], entity.position[1], worldSize);
+        const dx = px - cursorPx;
+        const dy = py - cursorPy;
+        // Shortest-path x-distance across the antimeridian: a cursor at 179.99° and
+        // an entity at −179.99° are ~0.02° apart on screen but raw Mercator dx is
+        // nearly worldSize. Taking min(|dx|, worldSize−|dx|) collapses that gap.
+        const absDx = Math.abs(dx);
+        const wrappedDx = Math.min(absDx, worldSize - absDx);
+        const distSq = wrappedDx * wrappedDx + dy * dy;
+        if (distSq <= radiusSq)
+            hits.push({ id: entity.id, distSq });
+    }
+    if (hits.length === 0)
+        return EMPTY_SET;
+    // Nearest-first so a consumer can cap to the N closest by iteration order.
+    hits.sort((a, b) => a.distSq - b.distSq);
+    return new Set(hits.map(hit => hit.id));
+};
+/**
+ * Reference/value equality for the recompute inputs. `entities` is compared by
+ * reference (the caller memoises it), keeping the per-render change check O(1)
+ * rather than deep-comparing the whole marker array on every frame.
+ */
+const sameInputs = (a, b) => a.entities === b.entities && a.zoom === b.zoom && a.tileSize === b.tileSize && a.radiusPx === b.radiusPx;
+/**
+ * The **Entities Near Cursor** primitive: returns a referentially-stable
+ * `ReadonlySet<string>` of entity ids whose projected position is within
+ * `radiusPx` CSS pixels of the projected cursor, nearest-first.
+ *
+ * It is the point-marker counterpart to **Shapes Under Cursor** and runs on the
+ * same pure Web Mercator substrate (`@trackunit/geo-json-utils`) fed by
+ * `useCameraState` + the RAF-throttled `pointermove` event — adapter-agnostic by
+ * construction (see ADR-0025). The hook owns radius geometry only; consumers
+ * decide why the ids are wanted (preload, highlight, …) and may cap the set to
+ * the nearest N via iteration order.
+ *
+ * The returned Set keeps a stable identity until either its membership or its
+ * nearest-first ordering changes, so wiring it straight into a memo or query
+ * does not churn while the cursor drifts within the same cluster of dots at the
+ * same relative distances. The host only re-renders when membership or ordering
+ * actually changes: the cursor lives in a ref and recomputes commit through an
+ * order-sensitive functional update that bails out (returns the previous Set)
+ * when nothing changed.
+ */
+const useEntitiesNearCursor = (api, options) => {
+    const { entities, radiusPx } = options;
+    const { zoom } = useCameraState(api);
+    const { tileSize } = api.state;
+    const [nearby, setNearby] = useState(EMPTY_SET);
+    // Latest cursor position and recompute inputs, read by the stable subscription
+    // and recompute without re-subscribing. Written only in effects / event
+    // handlers — never during render.
+    const cursorRef = useRef(null);
+    const inputsRef = useRef({ entities, zoom, tileSize, radiusPx });
+    const recompute = useCallback(() => {
+        const cursor = cursorRef.current;
+        const current = inputsRef.current;
+        const next = cursor === null
+            ? EMPTY_SET
+            : computeNearby(cursor, current.entities, current.zoom, current.tileSize, current.radiusPx);
+        // Membership-gated functional update: return the previous reference when the
+        // id set is unchanged so React bails out of the re-render and the output
+        // identity stays stable across cursor drift within the same cluster.
+        setNearby(prev => (sameNearby(prev, next) ? prev : next));
+    }, []);
+    // Keep the recompute inputs fresh and recompute when the camera, entities, or
+    // radius change while the cursor stays put (e.g. zooming under a stationary
+    // pointer brings new dots into radius). `useWatch` owns the effect, so this
+    // file never calls setState synchronously inside its own effect.
+    useWatch({
+        value: { entities, zoom, tileSize, radiusPx },
+        immediate: true,
+        isEqual: sameInputs,
+        onChange: latest => {
+            inputsRef.current = latest;
+            recompute();
+        },
+    });
+    // Track the cursor and recompute on each throttled move.
+    useEffect(() => api.on("pointermove", event => {
+        cursorRef.current = event.position;
+        recompute();
+    }), [api, recompute]);
+    return nearby;
+};
+
 const DEFAULT_DEBOUNCE_MS = 150;
 /**
  * Fires `onShouldPreload` for the currently hovered entity after a debounce
@@ -7460,14 +7576,17 @@ const degreesPerPixel = (zoom, tileSize) => 360 / (tileSize * Math.pow(2, zoom))
 const shapesUnderCursor = (position, features, options) => {
     const { zoom, tileSize, strokeWidthFor, visibleFillFor, layerGeodesic, featureStyles } = options;
     // Densify before boundary-distance and point-in-polygon math so stroke/fill
-    // hit-tests follow great-circle arcs on large polygons.
+    // hit-tests follow great-circle arcs on large polygons. Always defer to
+    // densifyGeodesicFeatures' per-feature resolution (geodesic override > layer
+    // default) rather than short-circuiting on layerGeodesic === false — that
+    // matches the Mapbox render path, so the hit-test geometry never diverges
+    // from the painted edge when a feature opts into geodesic under a non-geodesic
+    // layer. The util returns the original collection when nothing is densified.
     const featureCollection = {
         type: "FeatureCollection",
         features: Array.from(features),
     };
-    const densifiedFeatures = layerGeodesic !== false
-        ? densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
-        : features;
+    const densifiedFeatures = densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features;
     const degPerPx = degreesPerPixel(zoom, tileSize);
     const hits = [];
     for (const feature of densifiedFeatures) {
@@ -7579,14 +7698,16 @@ const promoteToFront = (order, id) => order.includes(id) ? [id, ...order.filter(
  * preserved and translucent fills do not compound under the winner.
  */
 const computePromotionGroupFills = (members, winnerId, restingPeerFills = new Map(), layerGeodesic = undefined, featureStyles = undefined) => {
-    // Densify before peer-vs-winner clip so promotion clips follow great-circle arcs.
+    // Densify before peer-vs-winner clip so promotion clips follow great-circle
+    // arcs. Always defer to densifyGeodesicFeatures' per-feature resolution
+    // (geodesic override > layer default) rather than short-circuiting on
+    // layerGeodesic === false — keeps the clip geometry in step with the render
+    // path. The util returns the original collection when nothing is densified.
     const featureCollection = {
         type: "FeatureCollection",
         features: Array.from(members),
     };
-    const densifiedMembers = layerGeodesic !== false
-        ? densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
-        : members;
+    const densifiedMembers = densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features;
     const geometries = new Map();
     for (const feature of densifiedMembers) {
         if (feature.id === undefined)
@@ -7626,14 +7747,16 @@ const computePromotionGroupFills = (members, winnerId, restingPeerFills = new Ma
 const computeFillTiling = (input) => {
     const { features, viewportBounds, resolveStackOrder, selectedFeatureId, suppressedFeatureIds, layerGeodesic, featureStyles, } = input;
     // Densify before any polygon/boundary math so clip geometry follows great-circle
-    // arcs on large polygons (mirrors the ADR-0024 precedent for edge labels).
+    // arcs on large polygons (mirrors the ADR-0024 precedent for edge labels). Always
+    // defer to densifyGeodesicFeatures' per-feature resolution (geodesic override >
+    // layer default) rather than short-circuiting on layerGeodesic === false — keeps
+    // the clip geometry in step with the Mapbox render path. The util returns the
+    // original collection when nothing is densified.
     const featureCollection = {
         type: "FeatureCollection",
         features: Array.from(features),
     };
-    const densifiedFeatures = layerGeodesic !== false
-        ? densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
-        : features;
+    const densifiedFeatures = densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features;
     const records = [];
     for (const feature of densifiedFeatures) {
         if (feature.id === undefined)
@@ -8110,7 +8233,6 @@ const DEG_TO_RAD = Math.PI / 180;
 const RAD_TO_DEG$1 = 180 / Math.PI;
 const DEFAULT_EDGE_LABEL_INSET_PX = 6;
 const LABEL_HEIGHT_PX = 20;
-const MAX_WEB_MERCATOR_LAT = 85.05112878;
 const EARTH_RADIUS_KM = 6371;
 const GEODESIC_PLACEMENT_MAX_SEGMENT_RAD = GEODESIC_MAX_SEGMENT_KM / EARTH_RADIUS_KM;
 /**
@@ -8170,24 +8292,6 @@ const clipSegmentToRect = (x0, y0, x1, y1, xMin, yMin, xMax, yMax) => {
     }
     return [x0 + tMin * dx, y0 + tMin * dy, x0 + tMax * dx, y0 + tMax * dy];
 };
-/**
- * Inner implementations that accept a pre-computed worldSize.
- * Used by findBestEdgePosition to avoid recomputing Math.pow(2, zoom) on
- * every vertex when projecting dozens of geodesic sub-segments per frame.
- */
-const lngLatToMercatorPxWS = (lng, lat, worldSize) => {
-    const clampedLat = Math.max(-MAX_WEB_MERCATOR_LAT, Math.min(MAX_WEB_MERCATOR_LAT, lat));
-    const x = ((lng + 180) / 360) * worldSize;
-    const latRad = clampedLat * DEG_TO_RAD;
-    const y = (0.5 - Math.log(Math.tan(Math.PI / 4 + latRad / 2)) / (2 * Math.PI)) * worldSize;
-    return [x, y];
-};
-const mercatorPxToLngLatWS = (px, py, worldSize) => {
-    const lng = (px / worldSize) * 360 - 180;
-    const lat = Math.atan(Math.sinh(Math.PI * (1 - (2 * py) / worldSize))) * RAD_TO_DEG$1;
-    return [lng, lat];
-};
-const lngLatToWebMercatorPx = (lng, lat, zoom, tileSize = 256) => lngLatToMercatorPxWS(lng, lat, tileSize * Math.pow(2, zoom));
 /**
  * Determine which side of an edge the geometry interior lies on, in screen space.
  * Returns "above" if the label should extend above the edge (interior is below),
@@ -10030,6 +10134,8 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
     }, [suppressedFillIdsByHandle]);
     const debounceTimerRef = useRef(null);
     const idleRecomputeTimerRef = useRef(null);
+    /** Pending deferred selection re-tile (double-rAF handle); see selection effect. */
+    const selectionRecomputeRafRef = useRef(null);
     // Currently emitted overrides — used for hit-testing visible fills in handleSettle.
     const prevFillOverridesRef = useRef(EMPTY_OVERRIDES);
     const prevZIndexOverridesRef = useRef(EMPTY_ZINDEX_OVERRIDES);
@@ -10284,8 +10390,30 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
             return;
         recompute();
     }, [recompute, tilingContentKey]);
+    // Selection forces the selected feature to the front of its overlap group,
+    // which requires a resting re-tile (computeFillTiling depends on
+    // selectedFeatureId via resolveStackOrder). For large layers that re-tile is
+    // expensive (~600ms for 200 polygons over global bounds) and must NOT block
+    // the interaction's first paint — e.g. a panel opening on the clicked feature.
+    // Defer it past the next paint with a double rAF so the click commits and
+    // paints immediately, then the selected polygon restacks one frame later.
+    // Rapid selections coalesce: each schedule cancels the previous pending one.
     useEffect(() => {
-        recompute();
+        if (selectionRecomputeRafRef.current !== null) {
+            cancelAnimationFrame(selectionRecomputeRafRef.current);
+        }
+        selectionRecomputeRafRef.current = requestAnimationFrame(() => {
+            selectionRecomputeRafRef.current = requestAnimationFrame(() => {
+                selectionRecomputeRafRef.current = null;
+                recompute();
+            });
+        });
+        return () => {
+            if (selectionRecomputeRafRef.current !== null) {
+                cancelAnimationFrame(selectionRecomputeRafRef.current);
+                selectionRecomputeRafRef.current = null;
+            }
+        };
     }, [recompute, selectedFeatureId]);
     // Suppression changes must trigger a recompute so EMPTY_FILL entries are
     // added / removed even when the map is idle (covers the decorations-vs-tiling
@@ -10537,7 +10665,24 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
     const [viewportStyleOverrides, setViewportStyleOverrides] = useState(new Map());
     const [fillGeometryOverrides, setFillGeometryOverrides] = useState(new Map());
     const [zIndexOverrides, setZIndexOverrides] = useState(new Map());
+    // Mirror the authoritative hovered entity into a ref. The settle channel fires
+    // on a ~120ms debounce (outside React's render cycle) and needs to read the
+    // current hover synchronously.
+    const hoveredEntityRef = useRef(layers.interaction.hoveredEntity);
+    useEffect(() => {
+        hoveredEntityRef.current = layers.interaction.hoveredEntity;
+    }, [layers.interaction.hoveredEntity]);
     const onSettledHover = useCallback((handleId, featureId) => {
+        // Z-order truth: markers and clusters render above shapes (DOM/symbol portals
+        // over the polygon canvas). When a point entity is the current hovered entity
+        // it is the authoritative top hit under the cursor, so the shape settle — which
+        // is not itself position-gated against the marker layer — must not overwrite it.
+        // Without this guard, moving onto an asset pill that overlaps a site would leave
+        // the covered site as `hoveredEntity` (a stale cross-channel hover write). We read
+        // the single source of truth (`hoveredEntity`) rather than a parallel guard flag.
+        const hovered = hoveredEntityRef.current;
+        if (hovered !== null && (hovered.type === "marker" || hovered.type === "cluster"))
+            return;
         // Fill tiling only fires on polygonal features — shapeType is always "polygon".
         layers.hover({ type: "shape", id: featureId, handleId, shapeType: "polygon" });
     }, [layers]);
@@ -10599,17 +10744,27 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
         });
     }, [layers.handles, adaptiveByLayer, viewportStyleOverrides, fillGeometryOverrides, zIndexOverrides, queryAt]);
     const { renderedSourceIds, hasSourceReadiness, readyRevision } = useLayerHandleSync(layerPort, enrichedHandles, layers.interaction, decorationLayers);
-    const hoveredEntityRef = useRef(layers.interaction.hoveredEntity);
-    useEffect(() => {
-        hoveredEntityRef.current = layers.interaction.hoveredEntity;
-    }, [layers.interaction.hoveredEntity]);
     const coordinatedSelect = useCallback((entity) => {
-        if (entity !== null && hoveredEntityRef.current !== null) {
-            layers.select(hoveredEntityRef.current);
-        }
-        else {
+        const hovered = hoveredEntityRef.current;
+        if (entity === null || hovered === null) {
             layers.select(entity);
+            return;
+        }
+        // Default to the entity the click actually carried — it is the freshest,
+        // most direct signal of what the user hit, and it hit-tests per element
+        // for markers/clusters/routes. The single exception is a shape-on-shape
+        // conflict: the adapter resolves polygon clicks with its own z-order and
+        // full (unclipped) hit areas, so it cannot honor the fill-tiling ownership
+        // model that decides which overlapping site is visually on top (ADR-0021).
+        // There the settle-resolved hovered shape is the precise winner, so we
+        // trust it instead. This is also why an asset pill overlapping a site
+        // selects the asset: a marker click is never a shape, so it bypasses the
+        // exception even when a stale site shape is still the hovered entity.
+        if (entity.type === "shape" && hovered.type === "shape") {
+            layers.select(hovered);
+            return;
         }
+        layers.select(entity);
     }, [layers]);
     const fitOnDblClick = useDblClickFit(api, layers.handles);
     const handleDblClick = useCallback((entity) => {
@@ -11589,4 +11744,4 @@ const mockMapApi = (overrides) => {
  */
 setupLibraryTranslations();
 
-export { ClusterMarker, ClusterStick, Controls, DEFAULT_MARKER_SIZE_BREAKPOINTS, DefaultControls, Layers, MARKER_DARK_PILL, MARKER_DISC_BORDER_WIDTH_PX, MARKER_LIGHT_PILL, MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, MARKER_TUNING, MapLoadingState, MapMarker, MapMarkerIcon, ShapeAnnotationLabel, buildExpandedIds, cvaMapMarker, cvaMarkerIndicator, mockMapApi, useAdaptiveMarkerHelpers, useAutoPanResolver, useCameraIdle, useCameraState, useClusterCountFormat, useControlStack, useControls, useDefaultControls, useDirectionIndicator, useExpandedIds, useFitFeatureBounds, useFitToContent, useImageOverlay, useLayers, useMap, useMapAnnotation, useMapAnnotations, useMapAppearanceControls, useMapKeyboardNavigation, useMarkerColors, useMarkerStateResolvers, useMarkers, usePanel, usePanelPreload, usePreviewMap, useRoute, useShapeLabelHelpers, useShapes, useViewportContext };
+export { ClusterMarker, ClusterStick, Controls, DEFAULT_MARKER_SIZE_BREAKPOINTS, DefaultControls, Layers, MARKER_DARK_PILL, MARKER_DISC_BORDER_WIDTH_PX, MARKER_LIGHT_PILL, MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, MARKER_TUNING, MapLoadingState, MapMarker, MapMarkerIcon, ShapeAnnotationLabel, buildExpandedIds, cvaMapMarker, cvaMarkerIndicator, mockMapApi, useAdaptiveMarkerHelpers, useAutoPanResolver, useCameraIdle, useCameraState, useClusterCountFormat, useControlStack, useControls, useDefaultControls, useDirectionIndicator, useEntitiesNearCursor, useExpandedIds, useFitFeatureBounds, useFitToContent, useImageOverlay, useLayers, useMap, useMapAnnotation, useMapAnnotations, useMapAppearanceControls, useMapKeyboardNavigation, useMarkerColors, useMarkerStateResolvers, useMarkers, usePanel, usePanelPreload, usePreviewMap, useRoute, useShapeLabelHelpers, useShapes, useViewportContext };

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.1.24",
+  "version": "0.1.27",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "2.1.35",
-    "@trackunit/css-class-variance-utilities": "1.13.39",
-    "@trackunit/react-form-components": "2.1.37",
-    "@trackunit/react-core-hooks": "1.17.48",
-    "@trackunit/geo-json-utils": "1.14.42",
-    "@trackunit/i18n-library-translation": "2.0.36",
-    "@trackunit/react-modal": "2.1.38",
+    "@trackunit/react-components": "2.1.38",
+    "@trackunit/css-class-variance-utilities": "1.13.42",
+    "@trackunit/react-form-components": "2.1.40",
+    "@trackunit/react-core-hooks": "1.17.51",
+    "@trackunit/geo-json-utils": "1.14.45",
+    "@trackunit/i18n-library-translation": "2.0.39",
+    "@trackunit/react-modal": "2.1.41",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.23",
-    "@trackunit/react-map-color-utils": "0.0.8",
-    "@trackunit/ui-design-tokens": "1.13.39",
+    "@trackunit/react-map-adapter-shared": "0.0.26",
+    "@trackunit/react-map-color-utils": "0.0.11",
+    "@trackunit/ui-design-tokens": "1.13.42",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.39.10",
     "tailwind-merge": "^2.0.0",

package/src/cursor/useEntitiesNearCursor.d.ts

@@ -0,0 +1,36 @@
+import type { GeoJsonPosition, MapApi } from "../core/types";
+/**
+ * A point entity that can be tested against the cursor. `position` is the
+ * geographic anchor as `[lng, lat]`.
+ */
+export type EntityNearCursor = Readonly<{
+    id: string;
+    position: GeoJsonPosition;
+}>;
+export type UseEntitiesNearCursorOptions = Readonly<{
+    /** The point entities to hit-test against the cursor on every move. */
+    entities: ReadonlyArray<EntityNearCursor>;
+    /** Hit radius around the cursor, in CSS pixels. */
+    radiusPx: number;
+}>;
+/**
+ * The **Entities Near Cursor** primitive: returns a referentially-stable
+ * `ReadonlySet<string>` of entity ids whose projected position is within
+ * `radiusPx` CSS pixels of the projected cursor, nearest-first.
+ *
+ * It is the point-marker counterpart to **Shapes Under Cursor** and runs on the
+ * same pure Web Mercator substrate (`@trackunit/geo-json-utils`) fed by
+ * `useCameraState` + the RAF-throttled `pointermove` event — adapter-agnostic by
+ * construction (see ADR-0025). The hook owns radius geometry only; consumers
+ * decide why the ids are wanted (preload, highlight, …) and may cap the set to
+ * the nearest N via iteration order.
+ *
+ * The returned Set keeps a stable identity until either its membership or its
+ * nearest-first ordering changes, so wiring it straight into a memo or query
+ * does not churn while the cursor drifts within the same cluster of dots at the
+ * same relative distances. The host only re-renders when membership or ordering
+ * actually changes: the cursor lives in a ref and recomputes commit through an
+ * order-sensitive functional update that bails out (returns the previous Set)
+ * when nothing changed.
+ */
+export declare const useEntitiesNearCursor: (api: MapApi, options: UseEntitiesNearCursorOptions) => ReadonlySet<string>;

package/src/index.d.ts

@@ -38,6 +38,7 @@ export { MARKER_TUNING } from "./markers/model/markerTuningParams";
 export { cvaMapMarker, cvaMarkerIndicator } from "./markers/shared/mapMarkerVariants";
 export { MARKER_DARK_PILL, MARKER_LIGHT_PILL } from "./markers/shared/markerColors";
 export type { MarkerColorConfig, MarkerColorCssVars, ResolvedMarkerColors } from "./markers/shared/markerColors";
+export { useEntitiesNearCursor, type EntityNearCursor, type UseEntitiesNearCursorOptions, } from "./cursor/useEntitiesNearCursor";
 export { type HoverPanelPreloadInitiator, type PanelPreloadInitiator, type PanelPreloadInitiatorType, type ProximityPanelPreloadInitiator, } from "./panel/preload/preloadInitiators";
 export { usePanelPreload, type UsePanelPreloadOptions } from "./panel/preload/usePanelPreload";
 export { type PanelStore } from "./panel/store/panels";

package/src/layers/useShapes/edge/findBestEdgePosition.d.ts

@@ -39,8 +39,6 @@ export type EdgeInsets = Readonly<{
 export declare const clipSegmentToRect: (x0: number, y0: number, x1: number, y1: number, xMin: number, yMin: number, xMax: number, yMax: number) => ClippedSegment | null;
 export { extractEdges } from "@trackunit/geo-json-utils";
 export { computeGeometryCentroid } from "@trackunit/geo-json-utils";
-export declare const lngLatToWebMercatorPx: (lng: number, lat: number, zoom: number, tileSize?: number) => readonly [number, number];
-export declare const webMercatorPxToLngLat: (px: number, py: number, zoom: number, tileSize?: number) => readonly [number, number];
 /**
  * Compute the screen-space angle (in degrees) of a line segment, accounting for
  * Web Mercator distortion. Normalized to [-90, 90] so text reads left-to-right.
@@ -60,11 +58,6 @@ export declare const edgeScreenAngleDeg: (x0: number, y0: number, x1: number, y1
  * Latitude pixels scale by sec(lat).
  */
 export declare const edgePixelLength: (x0: number, y0: number, x1: number, y1: number, zoom: number, midLatDeg: number, tileSize?: number) => number;
-/**
- * Convert a pixel distance to latitude degrees at a given zoom level,
- * accounting for Web Mercator latitude distortion.
- */
-export declare const pixelsToLatDegrees: (pixels: number, zoom: number, latDeg: number, tileSize?: number) => number;
 /**
  * Determine which side of an edge the geometry interior lies on, in screen space.
  * Returns "above" if the label should extend above the edge (interior is below),