@sakuzu/maplibre-gl-draw 1.0.0

package/dist/dispatcher/hit-test/box-strategy.d.ts

@@ -0,0 +1,59 @@
+/**
+ * BoxSelectionStrategy
+ *
+ * Intersection test strategy interface for box selection.
+ * Like HitTestStrategy, it defines the test logic per Feature type.
+ * Tests for custom types can be added through CustomFeatureHandler.
+ */
+import type { BoundingBox, Feature, FeatureType } from '../../store/types.js';
+/**
+ * The test of one feature type against the rectangle of a box selection in select mode, as
+ * registered through the `boxSelection` of a `CustomFeatureHandler`. A box that crosses the
+ * ±180 degree meridian is tested as two rectangles.
+ *
+ * @example
+ * ```ts
+ * import type { BoxSelectionStrategy } from '@sakuzu/maplibre-gl-draw';
+ *
+ * const markerBoxSelection: BoxSelectionStrategy = {
+ *   featureType: 'Marker',
+ *   intersects(feature, rect) {
+ *     const [lng, lat] = feature.coordinates as [number, number];
+ *     return lng >= rect.minX && lng <= rect.maxX && lat >= rect.minY && lat <= rect.maxY;
+ *   },
+ * };
+ * ```
+ */
+export interface BoxSelectionStrategy {
+    /** The target feature type */
+    readonly featureType: FeatureType;
+    /**
+     * Tests whether the Feature intersects the selection box
+     *
+     * @param feature The feature to test
+     * @param rect The selection box in degrees
+     * @returns `true` if it intersects (the feature is then selected)
+     */
+    intersects(feature: Feature, rect: BoundingBox): boolean;
+}
+/**
+ * The registry of {@link BoxSelectionStrategy} by feature type; one strategy per type.
+ */
+export declare class BoxSelectionStrategyRegistry {
+    private strategies;
+    /**
+     * Registers a strategy
+     *
+     * @returns a function that cancels the registration and puts back the strategy it replaced
+     *   (it does nothing once another strategy has been registered for the type)
+     */
+    register(strategy: BoxSelectionStrategy): () => void;
+    /**
+     * Returns the strategy of a type, or `undefined` when none is registered
+     */
+    get(featureType: FeatureType): BoxSelectionStrategy | undefined;
+    /**
+     * Returns every registered strategy, in registration order
+     */
+    getAll(): BoxSelectionStrategy[];
+}

package/dist/dispatcher/hit-test/box-strategy.js

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { registerRestoring } from './strategies/base.js';
+/**
+ * The registry of {@link BoxSelectionStrategy} by feature type; one strategy per type.
+ */
+export class BoxSelectionStrategyRegistry {
+    constructor() {
+        Object.defineProperty(this, "strategies", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * Registers a strategy
+     *
+     * @returns a function that cancels the registration and puts back the strategy it replaced
+     *   (it does nothing once another strategy has been registered for the type)
+     */
+    register(strategy) {
+        return registerRestoring(this.strategies, strategy.featureType, strategy);
+    }
+    /**
+     * Returns the strategy of a type, or `undefined` when none is registered
+     */
+    get(featureType) {
+        return this.strategies.get(featureType);
+    }
+    /**
+     * Returns every registered strategy, in registration order
+     */
+    getAll() {
+        return Array.from(this.strategies.values());
+    }
+}

package/dist/dispatcher/hit-test/globe-shape.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The shape hit testing tests on the globe
+ *
+ * The strategies test in longitude and latitude and take an edge as the straight line between
+ * its vertices in degrees. On the globe an edge is drawn along the straight line of the
+ * Mercator plane carried onto the sphere (`view/globe-subdivision.ts`), which leaves the
+ * straight line in degrees on a long edge that is not a parallel or a meridian. So on the globe
+ * the lines and the rings are cut along the Mercator plane before they are tested, with the
+ * line cell of the rendering: between two close points the two straight lines agree, and what
+ * can be clicked is what is drawn.
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { Feature } from '../../store/types.js';
+/**
+ * Reshapes a feature into the shape it is drawn with, for the precise test (the feature itself
+ * when the shape is the same)
+ */
+export type DrawnShapeResolver = (feature: Feature) => Feature;
+/**
+ * The line cell of the globe for hit testing, in Mercator world units (0 on a flat map)
+ *
+ * The rendering cuts while maplibre draws the globe. A map set to the globe projection is cut
+ * here at every zoom: past its switch to Mercator the cut only adds points on the straight
+ * lines already drawn.
+ */
+export declare function globeHitTestGrid(map: MapLibreMap): number;
+/**
+ * The feature with its lines and rings cut along the Mercator plane into pieces of at most
+ * `grid` (the feature itself when nothing is cut)
+ *
+ * LineString, Freehand, Polygon, MultiLineString and MultiPolygon are cut. The other types
+ * keep their shape: a point has no edge, and a circle and an image are tested by their own
+ * geometry.
+ *
+ * @param feature The feature to test
+ * @param grid The longest piece, in Mercator world units (0 cuts nothing)
+ */
+export declare function shapeOnGlobe(feature: Feature, grid: number): Feature;
+/**
+ * A resolver that cuts on the globe of `map`, keeping the last cut of each feature
+ *
+ * Hover tests the same features on every move of the pointer, so a feature object that was
+ * already cut with the same cell is not cut again. Features are replaced, not changed in
+ * place, when their coordinates change, so the object is the key.
+ */
+export declare function createGlobeShapeResolver(map: MapLibreMap): DrawnShapeResolver;

package/dist/dispatcher/hit-test/globe-shape.js

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { densifyOnMercatorPlane, globeSubdivisionGrid, } from '../../shared/math/globe-subdivision.js';
+import { isGlobeProjection } from '../../shared/utils/map.js';
+/** The most points the cut adds to one path (a guard against a runaway) */
+const MAX_POINTS = 65536;
+/**
+ * The line cell of the globe for hit testing, in Mercator world units (0 on a flat map)
+ *
+ * The rendering cuts while maplibre draws the globe. A map set to the globe projection is cut
+ * here at every zoom: past its switch to Mercator the cut only adds points on the straight
+ * lines already drawn.
+ */
+export function globeHitTestGrid(map) {
+    return isGlobeProjection(map) ? globeSubdivisionGrid(map.getZoom(), 'line') : 0;
+}
+/**
+ * The feature with its lines and rings cut along the Mercator plane into pieces of at most
+ * `grid` (the feature itself when nothing is cut)
+ *
+ * LineString, Freehand, Polygon, MultiLineString and MultiPolygon are cut. The other types
+ * keep their shape: a point has no edge, and a circle and an image are tested by their own
+ * geometry.
+ *
+ * @param feature The feature to test
+ * @param grid The longest piece, in Mercator world units (0 cuts nothing)
+ */
+export function shapeOnGlobe(feature, grid) {
+    if (!(grid > 0))
+        return feature;
+    const cut = (path) => densifyOnMercatorPlane(path, grid, MAX_POINTS);
+    let coordinates;
+    switch (feature.type) {
+        case 'LineString':
+        case 'Freehand':
+            coordinates = cut(feature.coordinates);
+            break;
+        case 'Polygon':
+        case 'MultiLineString':
+            coordinates = feature.coordinates.map(cut);
+            break;
+        case 'MultiPolygon':
+            coordinates = feature.coordinates.map((rings) => rings.map(cut));
+            break;
+        default:
+            return feature;
+    }
+    return { ...feature, coordinates };
+}
+/**
+ * A resolver that cuts on the globe of `map`, keeping the last cut of each feature
+ *
+ * Hover tests the same features on every move of the pointer, so a feature object that was
+ * already cut with the same cell is not cut again. Features are replaced, not changed in
+ * place, when their coordinates change, so the object is the key.
+ */
+export function createGlobeShapeResolver(map) {
+    const cache = new WeakMap();
+    return (feature) => {
+        const grid = globeHitTestGrid(map);
+        if (!(grid > 0))
+            return feature;
+        const hit = cache.get(feature);
+        if (hit && hit.grid === grid)
+            return hit.shape;
+        const shape = shapeOnGlobe(feature, grid);
+        cache.set(feature, { grid, shape });
+        return shape;
+    };
+}

package/dist/dispatcher/hit-test/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Hit Test module
+ */
+export type { OBB, ScreenPoint } from '../../shared/math/index.js';
+export { createOBB, distanceToOBB, getOBBAABB, getOBBCorners, pointInOBB, } from '../../shared/math/index.js';
+export { createCoreBoxSelectionStrategies, ImageBoxSelectionStrategy, LineStringBoxSelectionStrategy, MultiLineStringBoxSelectionStrategy, MultiPointBoxSelectionStrategy, MultiPolygonBoxSelectionStrategy, PointBoxSelectionStrategy, PolygonBoxSelectionStrategy, } from './box-strategies.js';
+export type { BoxSelectionStrategy } from './box-strategy.js';
+export { BoxSelectionStrategyRegistry } from './box-strategy.js';
+export type { HitTestService, UnprojectFunction } from './service.js';
+export { HitTestServiceImpl } from './service.js';
+export type { HitTestOptions, HitTestResult, HitTestStrategy, VertexHit, } from './strategies/index.js';
+export { CircleHitTestStrategy, DEFAULT_HIT_TEST_OPTIONS, HitTestStrategyRegistry, ImageHitTestStrategy, LineHitTestStrategy, MultiLineStringHitTestStrategy, MultiPointHitTestStrategy, MultiPolygonHitTestStrategy, PointHitTestStrategy, PolygonHitTestStrategy, } from './strategies/index.js';
+export type { HitTestTopmost, TopHit, TopmostHitTestDeps, TopmostHitTestOptions, } from './topmost.js';
+export { createTopmostHitTester } from './topmost.js';

package/dist/dispatcher/hit-test/index.js

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export { createOBB, distanceToOBB, getOBBAABB, getOBBCorners, pointInOBB, } from '../../shared/math/index.js';
+// Box selection strategies
+export { createCoreBoxSelectionStrategies, ImageBoxSelectionStrategy, LineStringBoxSelectionStrategy, MultiLineStringBoxSelectionStrategy, MultiPointBoxSelectionStrategy, MultiPolygonBoxSelectionStrategy, PointBoxSelectionStrategy, PolygonBoxSelectionStrategy, } from './box-strategies.js';
+export { BoxSelectionStrategyRegistry } from './box-strategy.js';
+export { HitTestServiceImpl } from './service.js';
+export { CircleHitTestStrategy, DEFAULT_HIT_TEST_OPTIONS, HitTestStrategyRegistry, ImageHitTestStrategy, LineHitTestStrategy, MultiLineStringHitTestStrategy, MultiPointHitTestStrategy, MultiPolygonHitTestStrategy, PointHitTestStrategy, PolygonHitTestStrategy, } from './strategies/index.js';
+export { createTopmostHitTester } from './topmost.js';

package/dist/dispatcher/hit-test/local-frame.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The local frame of hit testing
+ *
+ * Hit testing decides "within clickTolerance screen pixels of the click". Coordinates are
+ * longitude / latitude, so that decision is made in a frame where one unit is the same
+ * screen length in every direction: the Web Mercator plane around the click. Near a
+ * latitude φ a latitude difference is 1 / cos φ times longer on screen than the same
+ * longitude difference, so latitude differences are divided by cos φ and every distance
+ * comes out in degrees of longitude at the click latitude.
+ *
+ * The tolerance is expressed in the same unit. It is the ground length of clickTolerance
+ * pixels along the screen x axis, measured with unproject, so it does not depend on the
+ * bearing (the length of a displacement does not change when the map is turned) and follows
+ * the local scale under pitch (the screen x axis is never foreshortened).
+ *
+ * This is the contract every HitTestStrategy receives as `toleranceLngLat`: degrees of
+ * longitude at the click latitude. A latitude tolerance is `toleranceLngLat * cos φ`.
+ */
+import type { ScreenPoint } from '../../shared/math/index.js';
+import type { Coordinate } from '../../store/types.js';
+/** Converts a screen point into longitude / latitude */
+type Unproject = (point: ScreenPoint) => {
+    lng: number;
+    lat: number;
+};
+/**
+ * cos φ of a latitude: how much shorter a latitude difference is than on screen, relative
+ * to the same longitude difference
+ */
+export declare function latitudeScale(latitude: number): number;
+/**
+ * The click on the copies of the world whose stored features it can reach
+ *
+ * The features are stored with longitudes in [-180, 180], while the click unprojects to the
+ * unwrapped longitude of the view (above 180 on the copy east of the antimeridian, which the
+ * rendering draws as a second copy of the stored features). The click is therefore brought
+ * into [-180, 180], where it meets the stored coordinates of the copy drawn under it. When its
+ * reach runs past ±180, the click is also given on the neighbouring copy, so a feature just
+ * across the line is found too. Away from the antimeridian this is the click alone, unchanged.
+ *
+ * The first step is the rule InputRouter applies to every event before a mode sees it
+ * (`toStoredCopy`), so a click routed through it arrives here already in [-180, 180]; the
+ * wrapping stays for the callers that hit test a raw pointer position.
+ *
+ * @param coordinate The click (unwrapped longitude)
+ * @param reach How far the test reaches from the click (degrees of longitude)
+ * @returns The click on each copy to test, the stored copy first
+ */
+export declare function clickCopies(coordinate: Coordinate, reach: number): Coordinate[];
+/**
+ * The click tolerance in degrees of longitude at the click latitude
+ *
+ * It measures the ground length of `tolerancePx` pixels along the screen x axis, so turning
+ * the map does not change it.
+ */
+export declare function toleranceDegrees(unproject: Unproject, point: ScreenPoint, tolerancePx: number): number;
+/**
+ * The distance between two points in the local frame (degrees of longitude)
+ *
+ * @param latScale latitudeScale of the click latitude
+ */
+export declare function localDistance(a: Coordinate, b: Coordinate, latScale: number): number;
+/**
+ * The distance from a point to a segment in the local frame (degrees of longitude)
+ *
+ * @param latScale latitudeScale of the click latitude
+ */
+export declare function localPointToSegmentDistance(point: Coordinate, start: Coordinate, end: Coordinate, latScale: number): number;
+/**
+ * The shortest distance from a point to a polyline in the local frame (degrees of longitude)
+ *
+ * An array with fewer than two vertices has no segment and is infinitely far.
+ *
+ * @param latScale latitudeScale of the click latitude
+ */
+export declare function localPointToPolylineDistance(point: Coordinate, coords: Coordinate[], latScale: number): number;
+export {};

package/dist/dispatcher/hit-test/local-frame.js

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { wrapLongitude } from '../../shared/math/longitude.js';
+/** Lower bound of cos φ (guards against the poles, where Web Mercator diverges) */
+const MIN_LATITUDE_SCALE = 1e-6;
+/**
+ * cos φ of a latitude: how much shorter a latitude difference is than on screen, relative
+ * to the same longitude difference
+ */
+export function latitudeScale(latitude) {
+    return Math.max(Math.cos((latitude * Math.PI) / 180), MIN_LATITUDE_SCALE);
+}
+/**
+ * Wraps a longitude difference into [-180, 180)
+ */
+function wrapLngDelta(delta) {
+    return ((((delta + 180) % 360) + 360) % 360) - 180;
+}
+/**
+ * The click on the copies of the world whose stored features it can reach
+ *
+ * The features are stored with longitudes in [-180, 180], while the click unprojects to the
+ * unwrapped longitude of the view (above 180 on the copy east of the antimeridian, which the
+ * rendering draws as a second copy of the stored features). The click is therefore brought
+ * into [-180, 180], where it meets the stored coordinates of the copy drawn under it. When its
+ * reach runs past ±180, the click is also given on the neighbouring copy, so a feature just
+ * across the line is found too. Away from the antimeridian this is the click alone, unchanged.
+ *
+ * The first step is the rule InputRouter applies to every event before a mode sees it
+ * (`toStoredCopy`), so a click routed through it arrives here already in [-180, 180]; the
+ * wrapping stays for the callers that hit test a raw pointer position.
+ *
+ * @param coordinate The click (unwrapped longitude)
+ * @param reach How far the test reaches from the click (degrees of longitude)
+ * @returns The click on each copy to test, the stored copy first
+ */
+export function clickCopies(coordinate, reach) {
+    const lng = wrapLongitude(coordinate[0]);
+    const lat = coordinate[1];
+    const copies = [lng === coordinate[0] ? coordinate : [lng, lat]];
+    if (lng + reach > 180)
+        copies.push([lng - 360, lat]);
+    if (lng - reach < -180)
+        copies.push([lng + 360, lat]);
+    return copies;
+}
+/**
+ * The click tolerance in degrees of longitude at the click latitude
+ *
+ * It measures the ground length of `tolerancePx` pixels along the screen x axis, so turning
+ * the map does not change it.
+ */
+export function toleranceDegrees(unproject, point, tolerancePx) {
+    if (!(tolerancePx > 0))
+        return 0;
+    const origin = unproject(point);
+    const offset = unproject({ x: point.x + tolerancePx, y: point.y });
+    const dLng = wrapLngDelta(offset.lng - origin.lng);
+    const dLat = (offset.lat - origin.lat) / latitudeScale(origin.lat);
+    return Math.hypot(dLng, dLat);
+}
+/**
+ * The distance between two points in the local frame (degrees of longitude)
+ *
+ * @param latScale latitudeScale of the click latitude
+ */
+export function localDistance(a, b, latScale) {
+    const dx = b[0] - a[0];
+    const dy = (b[1] - a[1]) / latScale;
+    return Math.sqrt(dx * dx + dy * dy);
+}
+/**
+ * The distance from a point to a segment in the local frame (degrees of longitude)
+ *
+ * @param latScale latitudeScale of the click latitude
+ */
+export function localPointToSegmentDistance(point, start, end, latScale) {
+    const px = point[0];
+    const py = point[1] / latScale;
+    const ax = start[0];
+    const ay = start[1] / latScale;
+    const dx = end[0] - ax;
+    const dy = end[1] / latScale - ay;
+    const lengthSquared = dx * dx + dy * dy;
+    // The same arithmetic as shared/math pointToSegmentDistance, so that a latScale of 1
+    // gives bit-identical results
+    if (lengthSquared === 0)
+        return planarDistance(px, py, ax, ay);
+    const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / lengthSquared));
+    return planarDistance(px, py, ax + t * dx, ay + t * dy);
+}
+function planarDistance(x1, y1, x2, y2) {
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    return Math.sqrt(dx * dx + dy * dy);
+}
+/**
+ * The shortest distance from a point to a polyline in the local frame (degrees of longitude)
+ *
+ * An array with fewer than two vertices has no segment and is infinitely far.
+ *
+ * @param latScale latitudeScale of the click latitude
+ */
+export function localPointToPolylineDistance(point, coords, latScale) {
+    let min = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < coords.length - 1; i++) {
+        const distance = localPointToSegmentDistance(point, coords[i], coords[i + 1], latScale);
+        if (distance < min)
+            min = distance;
+    }
+    return min;
+}

package/dist/dispatcher/hit-test/segment-grid.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Distance queries of hit testing through the segment grid index
+ *
+ * The grid itself (shared/math/segment-grid.ts) is a plain index over a coordinate array.
+ * The distances here are measured in the local frame of hit testing (local-frame.ts).
+ */
+import { type SegmentGrid } from '../../shared/math/segment-grid.js';
+import type { Coordinate } from '../../store/types.js';
+export type { SegmentGrid } from '../../shared/math/segment-grid.js';
+export { buildSegmentGrid, getSegmentGrid, querySegmentIndicesInBBox, SEGMENT_INDEX_THRESHOLD, } from '../../shared/math/segment-grid.js';
+/**
+ * Finds the shortest distance within the tolerance through the index
+ *
+ * The distance is measured in the local frame of hit testing (local-frame.ts): degrees of
+ * longitude, with latitude differences divided by latScale. A latScale of 1 is plain degree
+ * space.
+ *
+ * @param latScale latitudeScale of the click latitude
+ * @returns The distance if within the tolerance, null if outside
+ */
+export declare function queryDistanceWithin(grid: SegmentGrid, coords: Coordinate[], point: Coordinate, tolerance: number, latScale?: number): number | null;
+/**
+ * The shortest distance to a polyline (or a ring) within the tolerance
+ *
+ * When the vertex count is below the threshold it scans everything, and at or above it
+ * uses the index. Both go through localPointToSegmentDistance, so the distance values match
+ * exactly.
+ *
+ * @param latScale latitudeScale of the click latitude (1 is plain degree space)
+ * @returns The distance if within the tolerance, null if outside
+ */
+export declare function polylineDistanceWithin(coords: Coordinate[], point: Coordinate, tolerance: number, latScale?: number): number | null;

package/dist/dispatcher/hit-test/segment-grid.js

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Distance queries of hit testing through the segment grid index
+ *
+ * The grid itself (shared/math/segment-grid.ts) is a plain index over a coordinate array.
+ * The distances here are measured in the local frame of hit testing (local-frame.ts).
+ */
+import { cellIndex, getSegmentGrid, nextGeneration, SEGMENT_INDEX_THRESHOLD, } from '../../shared/math/segment-grid.js';
+import { localPointToPolylineDistance, localPointToSegmentDistance } from './local-frame.js';
+export { buildSegmentGrid, getSegmentGrid, querySegmentIndicesInBBox, SEGMENT_INDEX_THRESHOLD, } from '../../shared/math/segment-grid.js';
+/**
+ * Finds the shortest distance within the tolerance through the index
+ *
+ * The distance is measured in the local frame of hit testing (local-frame.ts): degrees of
+ * longitude, with latitude differences divided by latScale. A latScale of 1 is plain degree
+ * space.
+ *
+ * @param latScale latitudeScale of the click latitude
+ * @returns The distance if within the tolerance, null if outside
+ */
+export function queryDistanceWithin(grid, coords, point, tolerance, latScale = 1) {
+    if (grid.segmentCount === 0)
+        return null;
+    const [px, py] = point;
+    // A latitude difference within the tolerance is at most tolerance * latScale
+    const queryMinX = px - tolerance;
+    const queryMinY = py - tolerance * latScale;
+    const queryMaxX = px + tolerance;
+    const queryMaxY = py + tolerance * latScale;
+    // If the tolerance box does not intersect the bbox, there is no candidate
+    if (queryMaxX < grid.minX ||
+        queryMinX > grid.maxX ||
+        queryMaxY < grid.minY ||
+        queryMinY > grid.maxY) {
+        return null;
+    }
+    const col0 = cellIndex(queryMinX - grid.minX, grid.cellW, grid.cols);
+    const col1 = cellIndex(queryMaxX - grid.minX, grid.cellW, grid.cols);
+    const row0 = cellIndex(queryMinY - grid.minY, grid.cellH, grid.rows);
+    const row1 = cellIndex(queryMaxY - grid.minY, grid.cellH, grid.rows);
+    const stamp = nextGeneration(grid);
+    let minDistance = Number.POSITIVE_INFINITY;
+    for (let row = row0; row <= row1; row++) {
+        const rowOffset = row * grid.cols;
+        for (let col = col0; col <= col1; col++) {
+            const cell = grid.cells[rowOffset + col];
+            if (!cell)
+                continue;
+            for (const i of cell) {
+                // A segment is registered in several cells, so compute it only once per query
+                if (grid.visited[i] === stamp)
+                    continue;
+                grid.visited[i] = stamp;
+                const distance = localPointToSegmentDistance(point, coords[i], coords[i + 1], latScale);
+                if (distance < minDistance)
+                    minDistance = distance;
+            }
+        }
+    }
+    return minDistance <= tolerance ? minDistance : null;
+}
+/**
+ * The shortest distance to a polyline (or a ring) within the tolerance
+ *
+ * When the vertex count is below the threshold it scans everything, and at or above it
+ * uses the index. Both go through localPointToSegmentDistance, so the distance values match
+ * exactly.
+ *
+ * @param latScale latitudeScale of the click latitude (1 is plain degree space)
+ * @returns The distance if within the tolerance, null if outside
+ */
+export function polylineDistanceWithin(coords, point, tolerance, latScale = 1) {
+    if (coords.length < SEGMENT_INDEX_THRESHOLD) {
+        const distance = localPointToPolylineDistance(point, coords, latScale);
+        return distance <= tolerance ? distance : null;
+    }
+    return queryDistanceWithin(getSegmentGrid(coords), coords, point, tolerance, latScale);
+}

package/dist/dispatcher/hit-test/service.d.ts

@@ -0,0 +1,120 @@
+/**
+ * HitTestService
+ *
+ * The service that integrates the two-stage hit testing.
+ * 1. Narrowing down the candidates with the SpatialIndex (rbush)
+ * 2. The precise test with a HitTestStrategy
+ */
+import type { ScreenPoint } from '../../shared/math/index.js';
+import type { Coordinate, Feature } from '../../store/types.js';
+import type { DrawnShapeResolver } from './globe-shape.js';
+import type { HitTestOptions, HitTestResult, HitTestStrategy } from './strategies/base.js';
+/**
+ * Converts a position in CSS px relative to the map container into degrees, as
+ * `map.unproject` does.
+ */
+export type UnprojectFunction = (point: ScreenPoint) => {
+    lng: number;
+    lat: number;
+};
+/**
+ * The injection point that maps the anchor of a symbol to screen coordinates (terrain
+ * aware)
+ *
+ * Points are drawn without a depth test, so they are visible even when they are behind the
+ * terrain. When one of those is clicked, the path "click -> terrain-aware unproject ->
+ * longitude/latitude -> spatial index" can never hit it in principle, because the line of
+ * sight lands on the terrain surface in front (even on a slope that is not occluded the
+ * landing point is displaced, which shrinks the effective radius).
+ *
+ * Therefore symbols alone take the path "project the anchor of each candidate to screen
+ * coordinates with the same projection as the rendering, and compare it directly with the
+ * screen coordinates of the click". The implementation is the anchor projection of the
+ * view layer (`view/terrain/anchor.ts`), which is identical to the one the rendering uses.
+ *
+ * While `project` returns null (the terrain is disabled, or no frame has been established
+ * yet) the conventional path is used as before. Hit testing without terrain does not
+ * change by a single byte.
+ */
+export interface AnchorScreenProjector {
+    project(coord: Coordinate): ScreenPoint | null;
+}
+/**
+ * The two-stage hit test of the features of the Store: candidates from the spatial index,
+ * then the precise test of each type's {@link HitTestStrategy}.
+ *
+ * Extensions receive it through their context. The tolerance is the click tolerance of the
+ * draw instance (6 px by default).
+ */
+export interface HitTestService {
+    /**
+     * Returns the frontmost feature that is hit, walking `orderedFeatures` from the end
+     *
+     * @param screenPoint The position in CSS px relative to the map container
+     * @param unproject Converts screen positions into degrees
+     * @param orderedFeatures The candidates in display order (the last is in front)
+     * @returns The hit, or `null` when nothing is hit
+     */
+    hitTest(screenPoint: ScreenPoint, unproject: UnprojectFunction, orderedFeatures: Feature[]): HitTestResult | null;
+    /**
+     * Returns every feature that is hit, sorted by distance (the closest first)
+     *
+     * @param screenPoint The position in CSS px relative to the map container
+     * @param unproject Converts screen positions into degrees
+     * @param orderedFeatures The candidates in display order
+     * @returns The hits. An empty array when nothing is hit
+     */
+    hitTestAll(screenPoint: ScreenPoint, unproject: UnprojectFunction, orderedFeatures: Feature[]): HitTestResult[];
+    /**
+     * Tests one feature with the strategy of its type
+     *
+     * @param feature The feature to test
+     * @param coordinate The position `[lng, lat]` in degrees
+     * @param toleranceLngLat The tolerance in degrees of longitude at that latitude
+     * @returns `true` when it is hit. `false` when no strategy is registered for its type
+     */
+    hitTestFeature(feature: Feature, coordinate: Coordinate, toleranceLngLat: number): boolean;
+    /**
+     * Updates the tile size in px of the map (the Image hit test converts pixel sizes with it)
+     */
+    setTileSize?(tileSize: number): void;
+    /**
+     * Registers a custom hit testing strategy (for dynamic registration)
+     *
+     * @returns a function that cancels the registration (see HitTestStrategyRegistry.register)
+     */
+    registerStrategy?(strategy: HitTestStrategy): () => void;
+    /**
+     * Registers, per feature type, the extra reach (in CSS pixels) for narrowing down the
+     * candidates
+     *
+     * The first stage narrows down the candidates with a radius equivalent to clickTolerance,
+     * so a type whose per-type strategy tests a wider area than that (icons and the like)
+     * would drop out of the candidates before it ever reaches the precise test. Widening the
+     * search radius by the registered distance lets such a type reach the second stage
+     * regardless of the state or the zoom.
+     *
+     * Only the candidate set widens; the semantics of a hit are decided by the strategy as
+     * before.
+     *
+     * @returns a function that cancels the registration (it does not remove a later
+     *   registration of the same type)
+     */
+    registerCandidateReach?(type: string, reachPx: number | (() => number)): () => void;
+}
+/**
+ * The options of HitTestServiceImpl
+ */
+export interface HitTestServiceImplOptions extends Partial<HitTestOptions> {
+    /** The tile size (taken from transform.tileSize of MapLibre) */
+    tileSize?: number;
+    /** The injection point that maps the anchor of a symbol to screen coordinates (terrain
+     * aware; when omitted only the conventional path is used) */
+    anchorScreen?: AnchorScreenProjector;
+    /**
+     * Reshapes a feature into the shape it is drawn with before the precise test (on the globe,
+     * its edges cut along the Mercator plane; `globe-shape.ts`). When omitted the stored shape
+     * is tested
+     */
+    drawnShape?: DrawnShapeResolver;
+}