@trackunit/react-map 0.1.24 → 0.1.25

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
@@ -8111,7 +8227,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 +8286,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 +8636,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 +8655,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 +8672,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 +8810,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 +8880,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 +8894,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 +8917,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 +9111,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);
@@ -11671,6 +11768,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
@@ -8110,7 +8226,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 +8285,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),
@@ -11589,4 +11686,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.25",
   "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.36",
+    "@trackunit/css-class-variance-utilities": "1.13.40",
+    "@trackunit/react-form-components": "2.1.38",
+    "@trackunit/react-core-hooks": "1.17.49",
+    "@trackunit/geo-json-utils": "1.14.43",
+    "@trackunit/i18n-library-translation": "2.0.37",
+    "@trackunit/react-modal": "2.1.39",
     "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.24",
+    "@trackunit/react-map-color-utils": "0.0.9",
+    "@trackunit/ui-design-tokens": "1.13.40",
     "@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),