@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/terrain/tiling.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Subdivision step per terrain tile (the index)
+ *
+ * MapLibre's terrain is "a polyline surface stretched over a fixed grid per tile". The grid
+ * spacing is the tile's Mercator width / terrain.meshSize, and in a pitched view coarser-zoom
+ * tiles are used the farther away the view is, so it varies from place to place.
+ *
+ * Unless our own subdivision matches that grid exactly, the fill drops out whichever way it
+ * deviates.
+ *
+ * - When our step is finer than the tile's actual mesh, in concave terrain (valley floors)
+ *   MapLibre's coarse chord crosses above the true terrain while our own nodes drop all the
+ *   way to the DEM value, so the polygon sinks below the chord and is carved away by depth
+ *   (dendritic dropouts)
+ * - When it is coarser, in convex terrain (ridges) our own chord dives below the ridge and is
+ *   carved away
+ *
+ * It is not "finer is safer" but "only an exact match is safe".
+ *
+ * The index is held in cells whose side length is that of the finest tile. A coarse tile spans
+ * several cells, but the finest tile's side length is an integer multiple of a coarse tile's
+ * mesh spacing, so a cell boundary always lies on one of that tile's mesh lines. In other
+ * words, cutting at cell boundaries only adds nodes; it never creates a seam (a T-junction).
+ */
+import type { RenderableTerrainTile } from './detect.js';
+import type { MercatorRect, TessellationTiling } from './tessellation.js';
+/**
+ * Builds the index of subdivision steps from the terrain tiles being drawn
+ *
+ * @param tiles The terrain tiles MapLibre is drawing
+ * @param meshSize The number of subdivisions of one tile (terrain.meshSize; 128 by default)
+ * @param region The range that may be subdivided (the index covers all of it)
+ */
+export declare function buildTessellationTiling(tiles: readonly RenderableTerrainTile[], meshSize: number, region: MercatorRect | null): TessellationTiling | null;
+/**
+ * Fingerprint of the tile configuration covering a given rectangle
+ *
+ * This is the key for deciding "whether the subdivision of that range is still correct". With
+ * the same fingerprint there is no need to subdivide again; with a different one there is. It
+ * includes the following three things.
+ *
+ * - The base step (which changes when the zoom changes) and the step of each index cell that
+ *   overlaps the rectangle (the tile zoom configuration itself). Both are written as absolute
+ *   values
+ * - The coarsening factor (the power of 2 applied to the step)
+ * - Whether the rectangle sticks out of the range that may be subdivided (the part that sticks
+ *   out is not subdivided, so once the range moves and "ground that has not been subdivided
+ *   yet" comes in, it has to be subdivided again)
+ *
+ * Moving the camera changes the zoom of the tiles used for the distance. Even when the
+ * geometry is correct, a polygon left "subdivided with the step of the old configuration"
+ * makes the old chord disagree with the new mesh, producing spotty breakthroughs and seams on
+ * ridges and in valleys. This is what is behind the observation that it looks clean right
+ * after a reload but falls apart once you pan or zoom to the spot.
+ */
+export declare function tilingSignature(tiling: TessellationTiling | null, region: MercatorRect | null, coarsen: number, baseGrid: number, x0: number, y0: number, x1: number, y1: number): string;

package/dist/view/terrain/tiling.js

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/** Upper bound on the number of cells in the index (no index is built for a wider view) */
+const MAX_TILING_CELLS = 4096;
+/**
+ * Builds the index of subdivision steps from the terrain tiles being drawn
+ *
+ * @param tiles The terrain tiles MapLibre is drawing
+ * @param meshSize The number of subdivisions of one tile (terrain.meshSize; 128 by default)
+ * @param region The range that may be subdivided (the index covers all of it)
+ */
+export function buildTessellationTiling(tiles, meshSize, region) {
+    if (tiles.length === 0 || !(meshSize > 0))
+        return null;
+    let maxZoom = 0;
+    for (const tile of tiles) {
+        if (tile.z > maxZoom)
+            maxZoom = tile.z;
+    }
+    const cell = 1 / 2 ** maxZoom;
+    if (!(cell > 0))
+        return null;
+    // The index covers all of "the range that may be subdivided". A cell with no tile gets a
+    // step of 0, and that area is emitted as is without being subdivided (outside the range the
+    // elevation is clamped to the edge value, so there is no point in subdividing).
+    //
+    // The index must not be trimmed to the bounding box of the tiles. Doing so drops the part of
+    // the range that falls outside the index, and the fill of that ground disappears entirely
+    // (hit while implementing this).
+    let minX;
+    let minY;
+    let maxX;
+    let maxY;
+    if (region) {
+        minX = region.x0;
+        minY = region.y0;
+        maxX = region.x1;
+        maxY = region.y1;
+    }
+    else {
+        minX = Number.POSITIVE_INFINITY;
+        minY = Number.POSITIVE_INFINITY;
+        maxX = Number.NEGATIVE_INFINITY;
+        maxY = Number.NEGATIVE_INFINITY;
+        for (const tile of tiles) {
+            const size = 1 / 2 ** tile.z;
+            const x0 = tile.x * size;
+            const y0 = tile.y * size;
+            if (x0 < minX)
+                minX = x0;
+            if (y0 < minY)
+                minY = y0;
+            if (x0 + size > maxX)
+                maxX = x0 + size;
+            if (y0 + size > maxY)
+                maxY = y0 + size;
+        }
+    }
+    if (!(maxX > minX) || !(maxY > minY))
+        return null;
+    const x0 = Math.floor(minX / cell) * cell;
+    const y0 = Math.floor(minY / cell) * cell;
+    const cols = Math.ceil((maxX - x0) / cell);
+    const rows = Math.ceil((maxY - y0) / cell);
+    if (cols <= 0 || rows <= 0)
+        return null;
+    // When there are too many cells (an unexpectedly wide spread) no index is built. Without an
+    // index the subdivision falls back to a single step as before (a picture is still produced)
+    if (cols * rows > MAX_TILING_CELLS)
+        return null;
+    const grids = new Float64Array(cols * rows);
+    // Coarse tiles are placed first and finer tiles overwrite them (same as how the atlas is
+    // baked)
+    const ordered = [...tiles].sort((a, b) => a.z - b.z);
+    for (const tile of ordered) {
+        const size = 1 / 2 ** tile.z;
+        const grid = size / meshSize;
+        const tx0 = tile.x * size;
+        const ty0 = tile.y * size;
+        const ix0 = Math.max(0, Math.floor((tx0 - x0) / cell));
+        const iy0 = Math.max(0, Math.floor((ty0 - y0) / cell));
+        const ix1 = Math.min(cols - 1, Math.ceil((tx0 + size - x0) / cell) - 1);
+        const iy1 = Math.min(rows - 1, Math.ceil((ty0 + size - y0) / cell) - 1);
+        for (let iy = iy0; iy <= iy1; iy++) {
+            for (let ix = ix0; ix <= ix1; ix++) {
+                grids[iy * cols + ix] = grid;
+            }
+        }
+    }
+    return {
+        rect: { x0, y0, x1: x0 + cols * cell, y1: y0 + rows * cell },
+        cell,
+        cols,
+        rows,
+        grids,
+    };
+}
+/**
+ * Fingerprint of the tile configuration covering a given rectangle
+ *
+ * This is the key for deciding "whether the subdivision of that range is still correct". With
+ * the same fingerprint there is no need to subdivide again; with a different one there is. It
+ * includes the following three things.
+ *
+ * - The base step (which changes when the zoom changes) and the step of each index cell that
+ *   overlaps the rectangle (the tile zoom configuration itself). Both are written as absolute
+ *   values
+ * - The coarsening factor (the power of 2 applied to the step)
+ * - Whether the rectangle sticks out of the range that may be subdivided (the part that sticks
+ *   out is not subdivided, so once the range moves and "ground that has not been subdivided
+ *   yet" comes in, it has to be subdivided again)
+ *
+ * Moving the camera changes the zoom of the tiles used for the distance. Even when the
+ * geometry is correct, a polygon left "subdivided with the step of the old configuration"
+ * makes the old chord disagree with the new mesh, producing spotty breakthroughs and seams on
+ * ridges and in valleys. This is what is behind the observation that it looks clean right
+ * after a reload but falls apart once you pan or zoom to the spot.
+ */
+export function tilingSignature(tiling, region, coarsen, baseGrid, x0, y0, x1, y1) {
+    // The step is 1/(2^z * meshSize), so its log2 is always an integer. It is written as an
+    // absolute value.
+    //
+    // This must not be written as "the difference from the finest tile in the view". Moving the
+    // zoom by one level moves both the tile's z and the finest z together, so the difference
+    // stays the same and it is judged "unchanged" even though the step actually changed by a
+    // factor of 2. A chunk left with the old step is never subdivided again, and streaky
+    // breakthroughs remain on ridges and in valleys.
+    const exponent = (grid) => (grid > 0 ? String(Math.round(Math.log2(grid))) : '-');
+    // The step itself is part of the key too (so that a zoom change is caught even on the path
+    // without an index)
+    const parts = [`${exponent(baseGrid)}:${coarsen}`];
+    if (!tiling)
+        return parts.join('|');
+    const inside = !region || (x0 >= region.x0 && x1 <= region.x1 && y0 >= region.y0 && y1 <= region.y1);
+    parts.push(inside ? 'i' : 'o');
+    if (!inside && region) {
+        // Something straddling the range also depends on the range itself (the cut changes)
+        parts.push(`${region.x0},${region.y0},${region.x1},${region.y1}`);
+    }
+    const ix0 = Math.max(0, Math.floor((x0 - tiling.rect.x0) / tiling.cell));
+    const ix1 = Math.min(tiling.cols - 1, Math.floor((x1 - tiling.rect.x0) / tiling.cell));
+    const iy0 = Math.max(0, Math.floor((y0 - tiling.rect.y0) / tiling.cell));
+    const iy1 = Math.min(tiling.rows - 1, Math.floor((y1 - tiling.rect.y0) / tiling.cell));
+    if (ix1 < ix0 || iy1 < iy0)
+        return parts.join('|');
+    // The step of each cell. The origin of the index is rounded to the finest tile's boundary,
+    // so the same ground always falls into the same cell (the indices do not shift when the
+    // range moves)
+    for (let iy = iy0; iy <= iy1; iy++) {
+        for (let ix = ix0; ix <= ix1; ix++) {
+            parts.push(exponent(tiling.grids[iy * tiling.cols + ix]));
+        }
+    }
+    return parts.join('|');
+}

package/dist/view/terrain/upstream-terrain.d.ts

@@ -0,0 +1,82 @@
+/**
+ * How maplibre lays out a DEM tile, reads it on the GPU and measures elevations (the one copy
+ * the engine keeps)
+ *
+ * A custom layer does not receive the `TERRAIN3D` part of maplibre's vertex prelude
+ * (maplibre-coupling.md, item 2), so the engine reads maplibre's DEM textures with its own
+ * shaders: the drape (`drape/shared.ts`, `drape/edge-constrain.ts`) and the DEM atlas
+ * (`dem-atlas.ts`). Whatever those shaders must assume about the upstream layout is written
+ * here and nowhere else, so an upstream change is one edit.
+ *
+ * Copied from maplibre-gl-js 6.11.1:
+ *
+ * - `src/data/dem_data.ts`, `DEMData`: the texture of a DEM tile is `dim + 4` texels on a
+ *   side, the `dim` pixels of the tile behind a border of 2 texels on every side
+ *   (`dim = data.height - 4` at line 54, `_idx` at line 140). `backfillBorder` (line 157) fills
+ *   the border from the neighbouring tiles, and until a neighbour arrives it repeats the edge
+ *   pixels (line 83).
+ * - `src/shaders/glsl/_prelude.vertex.glsl`, `ele` and `get_elevation` (lines 137 to 169): a
+ *   tile position is mapped by `u_terrain_matrix` into the unit square of the DEM tile and the
+ *   texel coordinate is `uv * u_terrain_dim + 1.5` (DEM pixel i describes the cell centred at
+ *   `(i + 0.5) / dim` and sits at texel `i + 2`). The four texels around it are fetched with
+ *   `texelFetch`, clamped to the texture, decoded with `u_terrain_unpack` and interpolated
+ *   bilinearly by hand (an encoded DEM cannot be interpolated by the sampler), then multiplied
+ *   by `u_terrain_exaggeration`.
+ * - `src/geo/lng_lat.ts`, `earthRadius = 6371008.8` (line 8), and
+ *   `src/geo/mercator_coordinate.ts`, `circumferenceAtLatitude` (line 14): the sphere an
+ *   elevation in meters is turned into Mercator units on (`mercatorZfromAltitude`), which is
+ *   how maplibre scales its terrain mesh and `map.project`. It is not the WGS84 equator the
+ *   geometry of the engine measures distances on; the 0.1 % between them is a pixel at the
+ *   top of a high, exaggerated mountain.
+ * - `src/render/terrain.ts`, `getElevationSampler` (line 324, `DEM_CELL_CENTER_OFFSET = -0.5`
+ *   at line 60): the CPU sampler places the pixels the same way, and it is what
+ *   `map.queryTerrainElevation` returns where the terrain is drawn. The engine's CPU side reads
+ *   that function (`ground.ts`) and copies nothing of it.
+ *
+ * Up to maplibre 6.7 the border was one texel and the offset `+ 1.0` (the pixels sat on the
+ * cell corners); 6.8.0 and 6.9.1 changed both (the move to the cell centres is
+ * maplibre-gl-js#8420). The end-to-end test `src/e2e/terrain.e2e.test.ts` compares what
+ * these shaders read with `map.queryTerrainElevation`, and the projection of the anchors
+ * (which uses the sphere through `metrics.ts`) with `map.project`, on a known DEM, and fails
+ * when they part.
+ */
+/**
+ * The circumference of the sphere maplibre turns elevations into Mercator units on (meters),
+ * `2 * PI * earthRadius`
+ */
+export declare const UPSTREAM_EARTH_CIRCUMFERENCE_METERS: number;
+/** The border around the pixels of a DEM tile, in texels on each side */
+export declare const DEM_BORDER_TEXELS = 2;
+/**
+ * What is added to `uv * dim` to get the texel coordinate of a position (the border, less half
+ * a texel because pixels are centred on their cells)
+ */
+export declare const DEM_TEXEL_OFFSET: number;
+/**
+ * The texel coordinate of a position of the DEM tile (the same formula as `get_elevation`)
+ *
+ * @param uv The position in the unit square of the DEM tile
+ * @param dim The number of pixels of the DEM tile on a side (`u_terrain_dim`)
+ */
+export declare function demTexelCoord(uv: number, dim: number): number;
+/**
+ * The texel coordinate of the last texel of a DEM texture (the far end of the border)
+ *
+ * A bilinear sample needs the texel at `floor(coord) + 1`, so real data is read only for
+ * texel coordinates in `[0, demLastTexel(dim)]`; beyond it the clamp repeats the last texel.
+ *
+ * @param dim The number of pixels of the DEM tile on a side
+ */
+export declare function demLastTexel(dim: number): number;
+/**
+ * The GLSL of the upstream DEM layout, for both shader stages
+ *
+ * - `upstream_dem_coord(uv, dim)`: the texel coordinate of a position ({@link demTexelCoord})
+ * - `upstream_dem_last_texel(dim)`: {@link demLastTexel}
+ * - `upstream_dem_bilinear(dem, unpack, coord)`: the elevation at a texel coordinate, in
+ *   meters before the exaggeration (the body of `get_elevation`)
+ *
+ * The functions take the texture and its unpack vector as arguments, so the drape can also
+ * read the DEM of a neighbouring tile with them (`edge-constrain.ts`).
+ */
+export declare const UPSTREAM_DEM_GLSL: string;

package/dist/view/terrain/upstream-terrain.js

@@ -0,0 +1,116 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * How maplibre lays out a DEM tile, reads it on the GPU and measures elevations (the one copy
+ * the engine keeps)
+ *
+ * A custom layer does not receive the `TERRAIN3D` part of maplibre's vertex prelude
+ * (maplibre-coupling.md, item 2), so the engine reads maplibre's DEM textures with its own
+ * shaders: the drape (`drape/shared.ts`, `drape/edge-constrain.ts`) and the DEM atlas
+ * (`dem-atlas.ts`). Whatever those shaders must assume about the upstream layout is written
+ * here and nowhere else, so an upstream change is one edit.
+ *
+ * Copied from maplibre-gl-js 6.11.1:
+ *
+ * - `src/data/dem_data.ts`, `DEMData`: the texture of a DEM tile is `dim + 4` texels on a
+ *   side, the `dim` pixels of the tile behind a border of 2 texels on every side
+ *   (`dim = data.height - 4` at line 54, `_idx` at line 140). `backfillBorder` (line 157) fills
+ *   the border from the neighbouring tiles, and until a neighbour arrives it repeats the edge
+ *   pixels (line 83).
+ * - `src/shaders/glsl/_prelude.vertex.glsl`, `ele` and `get_elevation` (lines 137 to 169): a
+ *   tile position is mapped by `u_terrain_matrix` into the unit square of the DEM tile and the
+ *   texel coordinate is `uv * u_terrain_dim + 1.5` (DEM pixel i describes the cell centred at
+ *   `(i + 0.5) / dim` and sits at texel `i + 2`). The four texels around it are fetched with
+ *   `texelFetch`, clamped to the texture, decoded with `u_terrain_unpack` and interpolated
+ *   bilinearly by hand (an encoded DEM cannot be interpolated by the sampler), then multiplied
+ *   by `u_terrain_exaggeration`.
+ * - `src/geo/lng_lat.ts`, `earthRadius = 6371008.8` (line 8), and
+ *   `src/geo/mercator_coordinate.ts`, `circumferenceAtLatitude` (line 14): the sphere an
+ *   elevation in meters is turned into Mercator units on (`mercatorZfromAltitude`), which is
+ *   how maplibre scales its terrain mesh and `map.project`. It is not the WGS84 equator the
+ *   geometry of the engine measures distances on; the 0.1 % between them is a pixel at the
+ *   top of a high, exaggerated mountain.
+ * - `src/render/terrain.ts`, `getElevationSampler` (line 324, `DEM_CELL_CENTER_OFFSET = -0.5`
+ *   at line 60): the CPU sampler places the pixels the same way, and it is what
+ *   `map.queryTerrainElevation` returns where the terrain is drawn. The engine's CPU side reads
+ *   that function (`ground.ts`) and copies nothing of it.
+ *
+ * Up to maplibre 6.7 the border was one texel and the offset `+ 1.0` (the pixels sat on the
+ * cell corners); 6.8.0 and 6.9.1 changed both (the move to the cell centres is
+ * maplibre-gl-js#8420). The end-to-end test `src/e2e/terrain.e2e.test.ts` compares what
+ * these shaders read with `map.queryTerrainElevation`, and the projection of the anchors
+ * (which uses the sphere through `metrics.ts`) with `map.project`, on a known DEM, and fails
+ * when they part.
+ */
+/**
+ * The circumference of the sphere maplibre turns elevations into Mercator units on (meters),
+ * `2 * PI * earthRadius`
+ */
+export const UPSTREAM_EARTH_CIRCUMFERENCE_METERS = 2 * Math.PI * 6371008.8;
+/** The border around the pixels of a DEM tile, in texels on each side */
+export const DEM_BORDER_TEXELS = 2;
+/**
+ * What is added to `uv * dim` to get the texel coordinate of a position (the border, less half
+ * a texel because pixels are centred on their cells)
+ */
+export const DEM_TEXEL_OFFSET = DEM_BORDER_TEXELS - 0.5;
+/**
+ * The texel coordinate of a position of the DEM tile (the same formula as `get_elevation`)
+ *
+ * @param uv The position in the unit square of the DEM tile
+ * @param dim The number of pixels of the DEM tile on a side (`u_terrain_dim`)
+ */
+export function demTexelCoord(uv, dim) {
+    return uv * dim + DEM_TEXEL_OFFSET;
+}
+/**
+ * The texel coordinate of the last texel of a DEM texture (the far end of the border)
+ *
+ * A bilinear sample needs the texel at `floor(coord) + 1`, so real data is read only for
+ * texel coordinates in `[0, demLastTexel(dim)]`; beyond it the clamp repeats the last texel.
+ *
+ * @param dim The number of pixels of the DEM tile on a side
+ */
+export function demLastTexel(dim) {
+    return dim + 2 * DEM_BORDER_TEXELS - 1;
+}
+/** A number as a GLSL float literal */
+function glslFloat(value) {
+    return Number.isInteger(value) ? `${value}.0` : `${value}`;
+}
+/**
+ * The GLSL of the upstream DEM layout, for both shader stages
+ *
+ * - `upstream_dem_coord(uv, dim)`: the texel coordinate of a position ({@link demTexelCoord})
+ * - `upstream_dem_last_texel(dim)`: {@link demLastTexel}
+ * - `upstream_dem_bilinear(dem, unpack, coord)`: the elevation at a texel coordinate, in
+ *   meters before the exaggeration (the body of `get_elevation`)
+ *
+ * The functions take the texture and its unpack vector as arguments, so the drape can also
+ * read the DEM of a neighbouring tile with them (`edge-constrain.ts`).
+ */
+export const UPSTREAM_DEM_GLSL = `
+vec2 upstream_dem_coord(vec2 uv, float dim) {
+    return uv * dim + ${glslFloat(DEM_TEXEL_OFFSET)};
+}
+
+float upstream_dem_last_texel(float dim) {
+    return dim + ${glslFloat(2 * DEM_BORDER_TEXELS - 1)};
+}
+
+float upstream_dem_ele(sampler2D dem, vec4 unpack, ivec2 pos) {
+    vec4 rgb = (texelFetch(dem, pos, 0) * 255.0) * unpack;
+    return rgb.r + rgb.g + rgb.b - unpack.a;
+}
+
+float upstream_dem_bilinear(sampler2D dem, vec4 unpack, vec2 coord) {
+    vec2 f = fract(coord);
+    ivec2 c = ivec2(floor(coord));
+    ivec2 hi = textureSize(dem, 0) - 1;
+    float tl = upstream_dem_ele(dem, unpack, clamp(c, ivec2(0), hi));
+    float tr = upstream_dem_ele(dem, unpack, clamp(c + ivec2(1, 0), ivec2(0), hi));
+    float bl = upstream_dem_ele(dem, unpack, clamp(c + ivec2(0, 1), ivec2(0), hi));
+    float br = upstream_dem_ele(dem, unpack, clamp(c + ivec2(1, 1), ivec2(0), hi));
+    return mix(mix(tl, tr, f.x), mix(bl, br, f.x), f.y);
+}
+`;

package/dist/view/ui/auxiliary-handles.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Extension point for the auxiliary handles
+ *
+ * A general-purpose hook for showing and grabbing handles on the selected feature that are
+ * "neither a vertex nor a resize handle". All core holds is the hit testing and the drag
+ * delegation; drawing the handles is the responsibility of the registering side (the plugin
+ * of an extension implementation). core knows nothing at all about the meaning of a handle
+ * (it only carries the position and the identifier).
+ *
+ * There are two ways to emit handles: those bound to the selected feature (getHandles) and
+ * those that can always be emitted regardless of the selection (getGlobalHandles). The
+ * latter is an entry point provided for "interaction state that does not fit the concept of
+ * a selection" (such as a focus held by an extension implementation), and hit testing, drag
+ * delegation and the cursor all go through exactly the same machinery as the former.
+ *
+ * One registry belongs to one draw instance (it is part of the SelectionScope), so the handles
+ * of a second draw instance on the same page never appear in, or take the drags of, the first.
+ */
+import type { DragNormalizedEvent } from '../../dispatcher/types.js';
+import type { LngLat, ScreenPoint } from '../../shared/math/index.js';
+import type { Coordinate, Feature } from '../../store/types.js';
+/**
+ * One auxiliary handle returned by an {@link AuxiliaryHandleProvider}.
+ */
+export interface AuxiliaryHandle {
+    /** Identifier unique within the provider */
+    id: string;
+    /** Position of the handle, `[lng, lat]` in degrees */
+    position: Coordinate;
+    /** Cursor on hover (when omitted, 'pointer') */
+    cursor?: string;
+}
+/**
+ * The context passed to {@link AuxiliaryHandleProvider.getHandles}: the tested point, the
+ * coordinate transforms and the zoom.
+ *
+ * A minimal structure holding only the point being hit tested (screen px), the coordinate
+ * transform and the zoom. The point is passed as is so that dynamic handles which appear
+ * only near the cursor (edge affordances and the like) can be expressed. The coordinate
+ * transform follows the same convention as the CoordinateTransform used by the existing
+ * handle hit testing (geographic coordinates [lng, lat] <-> screen px).
+ */
+export interface AuxiliaryHandleContext {
+    /** The point being hit tested (screen px) */
+    point: ScreenPoint;
+    /** Geographic coordinates -> screen px */
+    project(lngLat: Coordinate): ScreenPoint;
+    /** Screen px -> geographic coordinates */
+    unproject(point: ScreenPoint): LngLat;
+    /** Current zoom level */
+    zoom: number;
+}
+/**
+ * Which auxiliary handle of which provider was grabbed, and on which feature.
+ */
+export interface AuxiliaryHandleHit {
+    /** The id of the provider that returned the handle */
+    providerId: string;
+    /** The id of the handle within the provider */
+    handleId: string;
+    /**
+     * ID of the feature the handle sat on.
+     *
+     * A selection-independent handle (getGlobalHandles) has no feature, so it becomes an
+     * empty string (when `global` is true).
+     */
+    featureId: string;
+    /** Whether it came from a selection-independent handle (getGlobalHandles) */
+    global?: boolean;
+}
+/**
+ * A source of handles on the selected feature that are neither vertices nor resize handles,
+ * and the receiver of their drags.
+ *
+ * Register one with `draw.registerAuxiliaryHandleProvider(provider)`. The library hit tests
+ * the handles and delegates their drags; drawing them is the provider's job (with an overlay
+ * renderer, for example).
+ *
+ * @example
+ * ```ts
+ * import type { AuxiliaryHandleProvider } from '@sakuzu/maplibre-gl-draw';
+ *
+ * // A handle 20 px above the first vertex of the selected line, which logs its drag
+ * const labelHandle: AuxiliaryHandleProvider = {
+ *   id: 'label-handle',
+ *   getHandles(feature, ctx) {
+ *     if (feature.type !== 'LineString') return [];
+ *     const first = (feature.coordinates as [number, number][])[0];
+ *     const p = ctx.project(first);
+ *     const { lng, lat } = ctx.unproject({ x: p.x, y: p.y - 20 });
+ *     return [{ id: 'label', position: [lng, lat], cursor: 'move' }];
+ *   },
+ *   onHandleDragStart: () => true,
+ *   onHandleDragMove: (event) => console.log(event.lngLat),
+ *   onHandleDragEnd: () => {},
+ * };
+ *
+ * const unregister = draw.registerAuxiliaryHandleProvider(labelHandle);
+ * ```
+ */
+export interface AuxiliaryHandleProvider {
+    /** Identifier unique within the registry (re-registering with the same id overwrites) */
+    id: string;
+    /**
+     * Returns the list of auxiliary handles for the feature in a single selection.
+     * It is called on every hit test, so heavy computation must be avoided.
+     */
+    getHandles(feature: Feature, context: AuxiliaryHandleContext): AuxiliaryHandle[];
+    /**
+     * Returns the list of selection-independent handles (optional).
+     *
+     * They can always be emitted, whether the selection is empty or something else is
+     * selected. When core has finished testing against the selected feature (getHandles) and
+     * nothing was hit, it goes on to ask this one. Hit testing, drag delegation and the
+     * handling of the cursor all go through exactly the same machinery as the handles of
+     * getHandles.
+     *
+     * When one is grabbed, the AuxiliaryHandleHit has an empty featureId and global set to
+     * true (because there is no feature it sits on).
+     *
+     * It is called on every hit test, so heavy computation must be avoided.
+     */
+    getGlobalHandles?(context: AuxiliaryHandleContext): AuxiliaryHandle[];
+    /**
+     * Drag delegation. When it returns true, core stops dragPan and routes the subsequent
+     * move / end to the same provider. When false, core does not start a drag.
+     */
+    onHandleDragStart(hit: AuxiliaryHandleHit, event: DragNormalizedEvent): boolean;
+    /** Called for each move of a drag this provider accepted */
+    onHandleDragMove(event: DragNormalizedEvent): void;
+    /** Called at the end of a drag this provider accepted */
+    onHandleDragEnd(event: DragNormalizedEvent): void;
+}
+/**
+ * The registered providers of auxiliary handles of one draw instance
+ */
+export interface AuxiliaryHandleRegistry {
+    /**
+     * Registers a provider (re-registering with the same id overwrites)
+     *
+     * @returns A function that cancels the registration (calling it after a re-registration
+     *   with the same id does not remove the provider that came in later)
+     */
+    register(provider: AuxiliaryHandleProvider): () => void;
+    /** Gets a registered provider by id */
+    get(id: string): AuxiliaryHandleProvider | undefined;
+    /** Enumerates the registered providers (in registration order) */
+    list(): AuxiliaryHandleProvider[];
+    /** Cancels every registration (called when the draw instance is destroyed) */
+    clear(): void;
+}

package/dist/view/ui/auxiliary-handles.js

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Creates the registry of auxiliary handle providers of one draw instance
+ *
+ * @internal
+ */
+export function createAuxiliaryHandleRegistry() {
+    const providers = new Map();
+    return {
+        register(provider) {
+            providers.set(provider.id, provider);
+            return () => {
+                if (providers.get(provider.id) === provider)
+                    providers.delete(provider.id);
+            };
+        },
+        get: (id) => providers.get(id),
+        list: () => [...providers.values()],
+        clear: () => providers.clear(),
+    };
+}

package/dist/view/ui/bounds.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Computing the selection bounding box
+ *
+ * Computes the bounding box in geographic coordinates uniformly for every feature type.
+ * Used by hit testing.
+ *
+ * The basic policy (see docs/internals/architecture.md):
+ * - Data and computation are in geographic coordinates
+ * - Hit testing unprojects the click position and decides in geographic coordinates
+ * - Only rendering converts into screen coordinates
+ */
+import type { SelectionUIConfig } from '../../shared/config/selection.js';
+import type { CoordinateTransform } from '../../shared/math/index.js';
+import type { Coordinate, Feature } from '../../store/types.js';
+import { type BoundingBoxCoords, type SelectionExtensionRegistry } from './selection-ui/index.js';
+/**
+ * Compute the bounding box with a margin of a feature in geographic coordinates
+ *
+ * Supports every feature type:
+ * - Point: the icon size + the margin are computed in screen coordinates and converted
+ *   into geographic coordinates
+ * - LineString/Polygon: the margin is applied by applyMarginToBoundingBox
+ *
+ * @param feature The target feature
+ * @param transform The coordinate transform
+ * @param config The selection UI configuration
+ * @returns The bounding box with a margin in geographic coordinates, or null when it
+ * cannot be computed
+ */
+export declare function computeFeatureGeoBoundingBox(feature: Feature, transform: CoordinateTransform, config: SelectionUIConfig, extensions?: SelectionExtensionRegistry): BoundingBoxCoords | null;
+/**
+ * Compute the combined geographic bounding box of several features (with a margin)
+ *
+ * @param features The array of target features
+ * @param transform The coordinate transform
+ * @param config The selection UI configuration
+ * @param extensions The draw instance's extension points (custom bounding boxes and point
+ *   frame extents)
+ * @returns The bounding box with a margin in geographic coordinates, or null when it
+ * cannot be computed
+ */
+export declare function computeCombinedGeoBoundingBox(features: Feature[], transform: CoordinateTransform, config: SelectionUIConfig, extensions?: SelectionExtensionRegistry): BoundingBoxCoords | null;
+/**
+ * Decide whether a point in geographic coordinates is inside a convex quadrilateral
+ *
+ * Uses the cross product method. It decides whether the point is inside the convex
+ * quadrilateral enclosed by the 4 corners.
+ *
+ * @param lngLat The geographic coordinate to test [lng, lat]
+ * @param bbox The bounding box in geographic coordinates
+ * @returns true when the point is inside the bbox
+ */
+export declare function isPointInGeoBoundingBox(lngLat: Coordinate, bbox: BoundingBoxCoords): boolean;