@trackunit/react-map 0.1.5 → 0.1.13

package/index.esm.js

@@ -1,6 +1,6 @@
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import { useNamespaceTranslation, registerTranslations } from '@trackunit/i18n-library-translation';
-import { INITIAL_CAMERA_STATE, INITIAL_MAP_STATUS, KEYBOARD_PAN_AMOUNT, KEYBOARD_ZOOM_AMOUNT, mapAppearanceSchema, DEFAULT_MAP_APPEARANCE, WORLD_BBOX, INITIAL_INTERACTION_STATE, darkenColor, lightenColor, mapThemeSchema, SHAPE_STYLE_DEFAULTS, extractSourceData, computeMarkerDomPortalZIndex, geometryTypeToShapeType, resolveStrokeColors } from '@trackunit/react-map-adapter-shared';
+import { INITIAL_CAMERA_STATE, INITIAL_MAP_STATUS, KEYBOARD_PAN_AMOUNT, KEYBOARD_ZOOM_AMOUNT, mapAppearanceSchema, DEFAULT_MAP_APPEARANCE, WORLD_BBOX, INITIAL_INTERACTION_STATE, darkenColor, lightenColor, mapThemeSchema, extractSourceData, computeMarkerDomPortalZIndex, densifyGeodesicFeatures, angularDistance, intermediatePoint, GEODESIC_MAX_SEGMENT_KM, geometryTypeToShapeType, resolveStrokeColors } from '@trackunit/react-map-adapter-shared';
 export { ANCHOR_SELECTOR, DEFAULT_MAP_APPEARANCE, HIT_SURFACE_SELECTOR, INITIAL_CAMERA_STATE, INITIAL_INTERACTION_STATE, INITIAL_MAP_STATE, INITIAL_MAP_STATUS, computeMarkerDomPortalZIndex, defineAdapter, geometryTypeToShapeType, mapAppearanceSchema, mapThemeSchema, mapTypeSchema } from '@trackunit/react-map-adapter-shared';
 import { useSyncExternalStore, useMemo, useState, useRef, useCallback, useLayoutEffect, useEffect, useReducer, createContext, useContext, memo, Suspense, useId, Fragment as Fragment$1, forwardRef } from 'react';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
@@ -671,6 +671,30 @@ const useLayerPort = () => {
     return useContext(MapLayerContext);
 };
 
+/**
+ * Default visual styles for each shape type.
+ *
+ * These are a map consumer concern — injected into the adapter via
+ * `createMapComponent` so adapters remain style-agnostic.
+ */
+const SHAPE_STYLE_DEFAULTS = {
+    polygon: {
+        fillOpacity: 0.05,
+        strokeWidth: 1,
+        strokeOpacity: 1,
+    },
+    line: {
+        strokeWidth: 1,
+        strokeOpacity: 1,
+    },
+    point: {
+        fillOpacity: 0.2,
+        strokeWidth: 1,
+        strokeOpacity: 1,
+        pointRadius: 5,
+    },
+};
+
 /**
  * CSS `max-height` of the Panel shell — `min(320px, 40vh)`.
  *
@@ -963,8 +987,6 @@ const MapLoadingState = ({ isLoading, error = false, className, style }) => {
         }, children: [isLoading ? jsx(Spinner, { "aria-label": t("map.loading"), centering: "centered", size: "large" }) : null, error ? (jsx("span", { role: "alert", children: jsx(Text, { italicize: true, subtle: true, weight: "thick", children: t("map.loadingErrorMessage") }) })) : null] }));
 };
 
-const SafeAreaLayoutContext = createContext(null);
-
 /** Build padding style that combines spacing with safe area insets. */
 const padWithInsets = (availableSpace, insets) => {
     const base = availableSpace === "constrained" ? "var(--spacing-2)" : "var(--spacing-4)";
@@ -974,6 +996,8 @@ const padWithInsets = (availableSpace, insets) => {
         : { padding: base };
 };
 
+const SafeAreaLayoutContext = createContext(null);
+
 /**
  * Renders the AnnotationStack when no external renderer (Controls) has
  * claimed annotation rendering. Subscribes to the store's renderer-claim
@@ -1080,7 +1104,10 @@ const SafeAreaOverlay = ({ safeAreaInsets, safeAreaContentRef, children }) => {
  *
  * @internal
  */
-const createMapComponent = ({ adapter, Renderer, adapterName, containerRefHolder, containerId, annotationStore, loadingIndicatorStore, panelStore, safeAreaInsets, }) => {
+const createMapComponent = ({ adapter, Renderer, adapterName, containerRefHolder, containerId, annotationStore, loadingIndicatorStore, panelStore, safeAreaInsets, shapeStyleDefaults = SHAPE_STYLE_DEFAULTS, }) => {
+    // Inject consumer-owned shape style defaults into the adapter's layer port so
+    // adapters don't need to hard-code visual defaults themselves.
+    adapter.layers?.setShapeStyleDefaults(shapeStyleDefaults);
     // Preview maps (no containerRefHolder) — Renderer fills a relative wrapper; readiness overlay lives here (SAGA-374).
     // No `min-h-[200px]` on this shell: thumbnails (e.g. AppearancePreview 72×96) must respect consumer `style` /
     // `className`. The full-map branch keeps the floor on the inner map cell / Mapbox container.
@@ -7403,10 +7430,19 @@ const degreesPerPixel = (zoom, tileSize) => 360 / (tileSize * Math.pow(2, zoom))
  * - Bbox-prefiltered for performance; results are in deterministic (feature-id) order.
  */
 const shapesUnderCursor = (position, features, options) => {
-    const { zoom, tileSize, strokeWidthFor, visibleFillFor } = options;
+    const { zoom, tileSize, strokeWidthFor, visibleFillFor, layerGeodesic, featureStyles } = options;
+    // Densify before boundary-distance and point-in-polygon math so stroke/fill
+    // hit-tests follow great-circle arcs on large polygons.
+    const featureCollection = {
+        type: "FeatureCollection",
+        features: Array.from(features),
+    };
+    const densifiedFeatures = layerGeodesic !== false
+        ? densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
+        : features;
     const degPerPx = degreesPerPixel(zoom, tileSize);
     const hits = [];
-    for (const feature of features) {
+    for (const feature of densifiedFeatures) {
         if (feature.id === undefined)
             continue;
         const geometry = polygonalGeometry(feature);
@@ -7514,9 +7550,17 @@ const promoteToFront = (order, id) => order.includes(id) ? [id, ...order.filter(
  * its full geometry — so peer-to-peer overlap ownership from resting tiling is
  * preserved and translucent fills do not compound under the winner.
  */
-const computePromotionGroupFills = (members, winnerId, restingPeerFills = new Map()) => {
+const computePromotionGroupFills = (members, winnerId, restingPeerFills = new Map(), layerGeodesic = undefined, featureStyles = undefined) => {
+    // Densify before peer-vs-winner clip so promotion clips follow great-circle arcs.
+    const featureCollection = {
+        type: "FeatureCollection",
+        features: Array.from(members),
+    };
+    const densifiedMembers = layerGeodesic !== false
+        ? densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
+        : members;
     const geometries = new Map();
-    for (const feature of members) {
+    for (const feature of densifiedMembers) {
         if (feature.id === undefined)
             continue;
         const geometry = polygonalGeometry(feature);
@@ -7552,9 +7596,18 @@ const computePromotionGroupFills = (members, winnerId, restingPeerFills = new Ma
     return result;
 };
 const computeFillTiling = (input) => {
-    const { features, viewportBounds, resolveStackOrder, zoom, selectedFeatureId, suppressedFeatureIds } = input;
+    const { features, viewportBounds, resolveStackOrder, zoom, selectedFeatureId, suppressedFeatureIds, layerGeodesic, featureStyles, } = input;
+    // Densify before any polygon/boundary math so clip geometry follows great-circle
+    // arcs on large polygons (mirrors the ADR-0024 precedent for edge labels).
+    const featureCollection = {
+        type: "FeatureCollection",
+        features: Array.from(features),
+    };
+    const densifiedFeatures = layerGeodesic !== false
+        ? densifyGeodesicFeatures(featureCollection, layerGeodesic ?? true, featureStyles).features
+        : features;
     const records = [];
-    for (const feature of features) {
+    for (const feature of densifiedFeatures) {
         if (feature.id === undefined)
             continue;
         const id = String(feature.id);
@@ -7989,6 +8042,8 @@ 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;
 /**
  * Hysteresis override thresholds.
  *
@@ -8249,6 +8304,29 @@ const computeLabelBoundingBox = (anchorX, anchorY, cosT, sinT, labelAnchor, labe
     }
     return { minX, maxX, minY, maxY };
 };
+const getPlacementSegments = (start, end, geodesic) => {
+    if (!geodesic) {
+        return [{ start, end, isOriginalStart: true, isOriginalEnd: true }];
+    }
+    const delta = angularDistance(start[0], start[1], end[0], end[1]);
+    if (delta === 0) {
+        return [{ start, end, isOriginalStart: true, isOriginalEnd: true }];
+    }
+    const segmentCount = Math.max(1, Math.ceil(delta / GEODESIC_PLACEMENT_MAX_SEGMENT_RAD));
+    const segments = [];
+    let segmentStart = start;
+    for (let segmentIndex = 1; segmentIndex <= segmentCount; segmentIndex++) {
+        const segmentEnd = segmentIndex === segmentCount ? end : intermediatePoint(start, end, segmentIndex / segmentCount, delta);
+        segments.push({
+            start: segmentStart,
+            end: segmentEnd,
+            isOriginalStart: segmentIndex === 1,
+            isOriginalEnd: segmentIndex === segmentCount,
+        });
+        segmentStart = segmentEnd;
+    }
+    return segments;
+};
 // ============================================================================
 // Default resolver
 // ============================================================================
@@ -8279,7 +8357,15 @@ const defaultEdgeLabelPlacementResolver = (context) => {
         : undefined;
     let best;
     if (previousEdgeIdentity !== undefined) {
-        const hysteresisCandidate = pool.find(c => c.labelFits && isSameEdge(previousEdgeIdentity, c.edge));
+        // When a held anchor was projected onto a specific segment-candidate, lock onto
+        // that same segment so the "don't slide back" hold fraction (measured in that
+        // segment's reading frame) is applied to the matching candidate. Falling back to
+        // the first fitting segment of the edge would apply the fraction in the wrong
+        // reading frame, making the label jump back toward the edge start when panning.
+        const heldCandidate = context.previousAnchorClippedCandidateId !== undefined
+            ? pool.find(c => c.candidateId === context.previousAnchorClippedCandidateId && c.labelFits)
+            : undefined;
+        const hysteresisCandidate = heldCandidate ?? pool.find(c => c.labelFits && isSameEdge(previousEdgeIdentity, c.edge));
         if (hysteresisCandidate !== undefined) {
             const isHysteresisCandidateSteep = Math.abs(hysteresisCandidate.angleDeg) > STEEP_EDGE_THRESHOLD_DEG;
             if (isHysteresisCandidateSteep) {
@@ -8338,7 +8424,7 @@ const defaultEdgeLabelPlacementResolver = (context) => {
     // the center of the pill element to that geo position. Together they visually
     // center the label on the edge rather than pinning the left edge at the midpoint.
     if (isForced && !best.labelFits) {
-        return { edgeIdx: best.edgeIdx, side, anchorT: 0.5, anchor: "center" };
+        return { edgeIdx: best.edgeIdx, candidateId: best.candidateId, side, anchorT: 0.5, anchor: "center" };
     }
     // "Don't slide back" — for left-anchored labels on the same edge as before,
     // once the viewport has pushed the anchor rightward (to stay in view), keep it
@@ -8356,20 +8442,21 @@ const defaultEdgeLabelPlacementResolver = (context) => {
             const maxSafeT = best.pxLen > 0 ? (best.pxLen - best.endInsetPx - context.labelPixelWidth) / best.pxLen : 0;
             const clampedT = Math.max(defaultLeftT, Math.min(maxSafeT, context.previousAnchorClippedT));
             if (clampedT > defaultLeftT) {
-                return { edgeIdx: best.edgeIdx, side, anchorT: clampedT };
+                return { edgeIdx: best.edgeIdx, candidateId: best.candidateId, side, anchorT: clampedT };
             }
         }
     }
-    return { edgeIdx: best.edgeIdx, side };
+    return { edgeIdx: best.edgeIdx, candidateId: best.candidateId, side };
 };
 // ============================================================================
 // Main function
 // ============================================================================
-const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, labelPixelWidth, tileSize = 256, maxReadableAngleDeg, previousEdgeIdentity, previousAnchorGeo, previousLayoutSide, edgeInsets, labelAnchor = "left", labelPlacementResolver, isForced = false, }) => {
+const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, labelPixelWidth, tileSize = 256, maxReadableAngleDeg, previousEdgeIdentity, previousAnchorGeo, previousLayoutSide, edgeInsets, labelAnchor = "left", labelPlacementResolver, isForced = false, geodesic = false, }) => {
     const [minLon, minLat, maxLon, maxLat] = viewportBounds;
     const edges = extractEdges(features);
     const centroid = computeGeometryCentroid(features);
     const candidates = [];
+    let nextCandidateId = 0;
     // Pre-compute pixel viewport bounds so we can clip in pixel space.
     // Mercator y is non-linear in latitude, so clipping in geo space then
     // projecting gives clip points that are NOT on the rendered (pixel-space)
@@ -8384,75 +8471,159 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
         const edge = edges[edgeIdx];
         if (edge === undefined)
             continue;
-        const [start, end] = edge;
-        // Project both endpoints to pixel space, then clip there.
-        const [startPxX, startPxY] = lngLatToWebMercatorPx(start[0], start[1], zoom, tileSize);
-        const [endPxX, endPxY] = lngLatToWebMercatorPx(end[0], end[1], zoom, tileSize);
-        const clippedPx = clipSegmentToRect(startPxX, startPxY, endPxX, endPxY, pxViewMin, pyViewMin, pxViewMax, pyViewMax);
-        if (!clippedPx)
+        const sourceEdge = edge;
+        // Collect every clipped segment for this edge.  For geodesic edges there
+        // will be multiple short arc segments; for Mercator there is always one.
+        // After collection we derive a single "chord" candidate that spans from the
+        // reading-start of the first visible segment to the reading-end of the last
+        // visible segment.  Using the chord (straight-line) length — not the summed
+        // arc length — ensures fit/visibility checks match what the label actually
+        // occupies in screen space.
+        const segmentClips = [];
+        for (const segment of getPlacementSegments(edge[0], edge[1], geodesic)) {
+            const { start, end } = segment;
+            const [startPxX, startPxY] = lngLatToWebMercatorPx(start[0], start[1], zoom, tileSize);
+            const [endPxX, endPxY] = lngLatToWebMercatorPx(end[0], end[1], zoom, tileSize);
+            const clippedPx = clipSegmentToRect(startPxX, startPxY, endPxX, endPxY, pxViewMin, pyViewMin, pxViewMax, pyViewMax);
+            if (!clippedPx)
+                continue;
+            const [px0, py0, px1, py1] = clippedPx;
+            const rawDx = px1 - px0;
+            const rawDy = py1 - py0;
+            const segPxLen = Math.sqrt(rawDx * rawDx + rawDy * rawDy);
+            if (segPxLen === 0)
+                continue;
+            const readsFromClippedStart = rawDx >= 0;
+            const directionPx = readsFromClippedStart
+                ? [rawDx / segPxLen, rawDy / segPxLen]
+                : [-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] = webMercatorPxToLngLat(px0, py0, zoom, tileSize);
+            const [ex1, ey1] = webMercatorPxToLngLat(px1, py1, zoom, tileSize);
+            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))
+                continue;
+            const inset = edgeInsets?.[edgeIdx];
+            const readingStartInset = readsFromClippedStart && segment.isOriginalStart
+                ? inset?.startPx
+                : !readsFromClippedStart && segment.isOriginalEnd
+                    ? inset?.endPx
+                    : 0;
+            const readingEndInset = readsFromClippedStart && segment.isOriginalEnd
+                ? inset?.endPx
+                : !readsFromClippedStart && segment.isOriginalStart
+                    ? inset?.startPx
+                    : 0;
+            const startInsetPx = Math.max(DEFAULT_EDGE_LABEL_INSET_PX, readingStartInset ?? 0);
+            const endInsetPx = Math.max(DEFAULT_EDGE_LABEL_INSET_PX, readingEndInset ?? 0);
+            const readingStartPx = readsFromClippedStart
+                ? [px0 - pxViewMin, py0 - pyViewMin]
+                : [px1 - pxViewMin, py1 - pyViewMin];
+            const readingEndPx = readsFromClippedStart
+                ? [px1 - pxViewMin, py1 - pyViewMin]
+                : [px0 - pxViewMin, py0 - pyViewMin];
+            segmentClips.push({
+                segment,
+                segmentPxLen: segPxLen,
+                readsFromClippedStart,
+                directionPx,
+                readingStartPx,
+                readingEndPx,
+                outwardSide: edgeOutwardSide,
+                startInsetPx,
+                endInsetPx,
+            });
+        }
+        if (segmentClips.length === 0)
             continue;
-        const [px0, py0, px1, py1] = clippedPx;
-        // Inverse-project pixel clip endpoints to geo for outward-side and
-        // polygon-interior checks (qualitative, so approximately correct geo is fine).
-        const [ex0, ey0] = webMercatorPxToLngLat(px0, py0, zoom, tileSize);
-        const [ex1, ey1] = webMercatorPxToLngLat(px1, py1, zoom, tileSize);
-        const midLat = (ey0 + ey1) / 2;
-        const rawDx = px1 - px0;
-        const rawDy = py1 - py0;
-        const pxLen = Math.sqrt(rawDx * rawDx + rawDy * rawDy);
-        if (pxLen === 0)
+        // ── Build the chord spanning the full clipped arc ─────────────────────────
+        //
+        // For geodesic edges the label must fit in screen-space. The chord (straight
+        // line from the first visible segment's reading start to the last visible
+        // segment's reading end) is the actual screen-space extent of the arc.
+        // Using chord length instead of the summed arc length prevents the label
+        // from extending past a polygon corner even when the arc is longer than
+        // the chord.
+        //
+        // For a right-to-left edge (readsFromClippedStart = false),
+        // getPlacementSegments returns segments in geographic A→B order but the
+        // reading direction is B→A, so the chord start is the LAST segment's
+        // readingStartPx and the chord end is the FIRST segment's readingEndPx.
+        // segmentClips is non-empty (checked above); TypeScript doesn't narrow that
+        // from .length > 0, so we do a non-null assertion via the bang-free fallback.
+        const firstClip = segmentClips[0];
+        const lastClip = segmentClips[segmentClips.length - 1];
+        if (firstClip === undefined || lastClip === undefined)
             continue;
-        const readsFromClippedStart = rawDx >= 0;
-        const directionPx = readsFromClippedStart
-            ? [rawDx / pxLen, rawDy / pxLen]
-            : [-rawDx / pxLen, -rawDy / pxLen];
-        const angleDeg = Math.atan2(directionPx[1], directionPx[0]) * RAD_TO_DEG$1;
-        if (pxLen < minPixelWidth)
+        const readsFromStart = firstClip.readsFromClippedStart;
+        const chordReadingStartPx = readsFromStart ? firstClip.readingStartPx : lastClip.readingStartPx;
+        const chordReadingEndPx = readsFromStart ? lastClip.readingEndPx : firstClip.readingEndPx;
+        const chordDx = chordReadingEndPx[0] - chordReadingStartPx[0];
+        const chordDy = chordReadingEndPx[1] - chordReadingStartPx[1];
+        const chordPxLen = Math.sqrt(chordDx * chordDx + chordDy * chordDy);
+        if (chordPxLen === 0)
             continue;
-        const edgeOutwardSide = centroid !== null ? computeOutwardSide(ex0, ey0, ex1, ey1, centroid, midLat) : "above";
-        if (isLabelInsidePolygon(ex0, ey0, ex1, ey1, features, centroid))
+        if (chordPxLen < minPixelWidth)
             continue;
-        const inset = edgeInsets?.[edgeIdx];
-        const startInsetPx = Math.max(DEFAULT_EDGE_LABEL_INSET_PX, (readsFromClippedStart ? inset?.startPx : inset?.endPx) ?? 0);
-        const endInsetPx = Math.max(DEFAULT_EDGE_LABEL_INSET_PX, (readsFromClippedStart ? inset?.endPx : inset?.startPx) ?? 0);
-        const availableWidthPx = Math.max(0, pxLen - startInsetPx - endInsetPx);
-        const labelFits = availableWidthPx >= labelPixelWidth;
-        // Viewport-relative reading start/end (subtract viewport origin so bbox
-        // checks can be done against [0, viewportWidth] × [0, viewportHeight]).
-        const readingStartPx = readsFromClippedStart
-            ? [px0 - pxViewMin, py0 - pyViewMin]
-            : [px1 - pxViewMin, py1 - pyViewMin];
-        const readingEndPx = readsFromClippedStart
-            ? [px1 - pxViewMin, py1 - pyViewMin]
-            : [px0 - pxViewMin, py0 - pyViewMin];
-        // Compute bbox anchor in viewport-relative coords.
-        const anchorOffsetForBbox = labelAnchor === "left"
-            ? startInsetPx
-            : labelAnchor === "center"
-                ? startInsetPx + availableWidthPx / 2
-                : pxLen - endInsetPx;
-        const anchorTForBbox = pxLen > 0 ? Math.max(0, Math.min(pxLen, anchorOffsetForBbox)) / pxLen : 0;
-        const bboxAnchorX = readingStartPx[0] + anchorTForBbox * (readingEndPx[0] - readingStartPx[0]);
-        const bboxAnchorY = readingStartPx[1] + anchorTForBbox * (readingEndPx[1] - readingStartPx[1]);
-        const outwardBbox = computeLabelBoundingBox(bboxAnchorX, bboxAnchorY, directionPx[0], directionPx[1], labelAnchor, labelPixelWidth, edgeOutwardSide);
-        const flippedSide = edgeOutwardSide === "above" ? "below" : "above";
-        const inwardBbox = computeLabelBoundingBox(bboxAnchorX, bboxAnchorY, directionPx[0], directionPx[1], labelAnchor, labelPixelWidth, flippedSide);
-        candidates.push({
-            edgeIdx,
-            edge: [start, end],
-            pxLen,
-            angleDeg,
-            availableWidthPx,
-            labelFits,
-            outwardSide: edgeOutwardSide,
-            startInsetPx,
-            endInsetPx,
-            directionPx,
-            readingStartPx,
-            readingEndPx,
-            outwardBbox,
-            inwardBbox,
-        });
+        const chordDirectionPx = [chordDx / chordPxLen, chordDy / chordPxLen];
+        const chordAngleDeg = Math.atan2(chordDy, chordDx) * RAD_TO_DEG$1;
+        // Edge insets come from the chord-start and chord-end segment.
+        const chordStartClip = readsFromStart ? firstClip : lastClip;
+        const chordEndClip = readsFromStart ? lastClip : firstClip;
+        const chordStartInsetPx = chordStartClip.startInsetPx;
+        const chordEndInsetPx = chordEndClip.endInsetPx;
+        const chordAvailableWidthPx = Math.max(0, chordPxLen - chordStartInsetPx - chordEndInsetPx);
+        const chordLabelFits = chordAvailableWidthPx >= labelPixelWidth;
+        // ── One candidate per visible segment, but with chord-level properties ──
+        //
+        // The chord properties (pxLen, available width, fit, reading direction,
+        // readingStartPx/EndPx) govern the final anchor position and angle — using
+        // the chord prevents protrusion past polygon corners caused by arc > chord.
+        //
+        // The bbox for each candidate is computed at that segment's own label anchor
+        // position (using the segment's own available width), oriented along the
+        // segment's own direction. This gives per-segment viewport-fit diversity so
+        // narrow viewports where only part of the arc is horizontal enough still
+        // produce at least one pool candidate.
+        for (const clip of segmentClips) {
+            // Per-segment bbox anchor at the segment's own label center / left / right.
+            const segAvailableWidthPx = Math.max(0, clip.segmentPxLen - clip.startInsetPx - clip.endInsetPx);
+            const segAnchorOffsetForBbox = labelAnchor === "left"
+                ? clip.startInsetPx
+                : labelAnchor === "center"
+                    ? clip.startInsetPx + segAvailableWidthPx / 2
+                    : clip.segmentPxLen - clip.endInsetPx;
+            const segAnchorTForBbox = clip.segmentPxLen > 0
+                ? Math.max(0, Math.min(clip.segmentPxLen, segAnchorOffsetForBbox)) / clip.segmentPxLen
+                : 0;
+            const bboxAnchorX = clip.readingStartPx[0] + segAnchorTForBbox * (clip.readingEndPx[0] - clip.readingStartPx[0]);
+            const bboxAnchorY = clip.readingStartPx[1] + segAnchorTForBbox * (clip.readingEndPx[1] - clip.readingStartPx[1]);
+            const outwardBbox = computeLabelBoundingBox(bboxAnchorX, bboxAnchorY, clip.directionPx[0], clip.directionPx[1], labelAnchor, labelPixelWidth, clip.outwardSide);
+            const flippedSide = clip.outwardSide === "above" ? "below" : "above";
+            const inwardBbox = computeLabelBoundingBox(bboxAnchorX, bboxAnchorY, clip.directionPx[0], clip.directionPx[1], labelAnchor, labelPixelWidth, flippedSide);
+            candidates.push({
+                candidateId: nextCandidateId,
+                edgeIdx,
+                edge: sourceEdge,
+                // Chord-level: anchor, fit, resolver selection criteria
+                pxLen: chordPxLen,
+                angleDeg: chordAngleDeg,
+                availableWidthPx: chordAvailableWidthPx,
+                labelFits: chordLabelFits,
+                startInsetPx: chordStartInsetPx,
+                endInsetPx: chordEndInsetPx,
+                directionPx: chordDirectionPx,
+                readingStartPx: chordReadingStartPx,
+                readingEndPx: chordReadingEndPx,
+                // Per-segment: bbox viewport filtering
+                outwardBbox,
+                inwardBbox,
+                outwardSide: clip.outwardSide,
+            });
+            nextCandidateId++;
+        }
     }
     if (candidates.length === 0) {
         return null;
@@ -8461,9 +8632,11 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
     // the reading direction of the matching previous-edge candidate so the resolver
     // can enforce "don't slide back left" without needing raw Mercator math.
     let previousAnchorClippedT;
+    let previousAnchorClippedCandidateId;
     if (previousAnchorGeo !== undefined && previousEdgeIdentity !== undefined) {
-        const matchingCandidate = candidates.find(c => isSameEdge(previousEdgeIdentity, c.edge));
-        if (matchingCandidate !== undefined && matchingCandidate.pxLen > 0) {
+        for (const matchingCandidate of candidates.filter(c => isSameEdge(previousEdgeIdentity, c.edge))) {
+            if (matchingCandidate.pxLen <= 0)
+                continue;
             const [prevAnchorAbsPx, prevAnchorAbsPy] = lngLatToWebMercatorPx(previousAnchorGeo[0], previousAnchorGeo[1], zoom, tileSize);
             const prevAnchorRelX = prevAnchorAbsPx - pxViewMin;
             const prevAnchorRelY = prevAnchorAbsPy - pyViewMin;
@@ -8476,8 +8649,10 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
             // right of the current clip start (t >= 0). A negative t means the viewport has
             // scrolled so far right that the anchor is now behind the left clip boundary —
             // in that case the default left position is already as far right as we can go.
-            if (t >= 0) {
-                previousAnchorClippedT = Math.min(1, t);
+            if (t >= 0 && t <= 1) {
+                previousAnchorClippedT = t;
+                previousAnchorClippedCandidateId = matchingCandidate.candidateId;
+                break;
             }
         }
     }
@@ -8490,13 +8665,16 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
         previousEdgeIdentity,
         isForced,
         previousAnchorClippedT,
+        previousAnchorClippedCandidateId,
         previousLayoutSide,
     };
     const resolver = labelPlacementResolver ?? defaultEdgeLabelPlacementResolver;
     const decision = resolver(context);
     if (decision === null)
         return null;
-    const best = candidates.find(c => c.edgeIdx === decision.edgeIdx);
+    const best = decision.candidateId !== undefined
+        ? candidates.find(c => c.candidateId === decision.candidateId)
+        : candidates.find(c => c.edgeIdx === decision.edgeIdx);
     if (best === undefined)
         return null;
     const fitMode = best.labelFits ? "fits" : "clipped";
@@ -8519,12 +8697,68 @@ const findBestEdgePosition = ({ features, viewportBounds, zoom, minPixelWidth, l
     // readingStartPx/readingEndPx are viewport-relative; add back viewport origin for absolute px.
     const anchorRelX = best.readingStartPx[0] + anchorT * (best.readingEndPx[0] - best.readingStartPx[0]);
     const anchorRelY = best.readingStartPx[1] + anchorT * (best.readingEndPx[1] - best.readingStartPx[1]);
-    const [anchorLng, anchorLat] = webMercatorPxToLngLat(anchorRelX + pxViewMin, anchorRelY + pyViewMin, zoom, tileSize);
+    let position;
+    let resolvedDirectionPx;
+    if (geodesic) {
+        const [A, B] = best.edge;
+        const delta = angularDistance(A[0], A[1], B[0], B[1]);
+        if (delta > 0) {
+            // Project the Mercator anchor pixel back to geo, then map it onto the
+            // 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] = webMercatorPxToLngLat(anchorRelX + pxViewMin, anchorRelY + pyViewMin, zoom, tileSize);
+            const tArc = Math.max(0, Math.min(1, angularDistance(A[0], A[1], approxLng, approxLat) / delta));
+            const geoAnchor = intermediatePoint(A, B, tArc, delta);
+            position = [geoAnchor[0], geoAnchor[1]];
+            // Tangent: finite-difference at the visual center of the label (not the
+            // anchor point). For a "left"-anchored label the anchor sits at the left
+            // edge of the pill; evaluating the tangent there means the label hugs the
+            // arc on the left but drifts on the right on curved edges. Computing the
+            // tangent at the label's midpoint (anchor ± halfWidth along the reading
+            // direction) keeps both sides equally aligned to the curve.
+            const halfLabelPx = labelPixelWidth / 2;
+            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] = webMercatorPxToLngLat(centerRelX + pxViewMin, centerRelY + pyViewMin, zoom, tileSize);
+            const tArcCenter = Math.max(0, Math.min(1, angularDistance(A[0], A[1], approxCenterLng, approxCenterLat) / delta));
+            const TANGENT_EPS = 0.001;
+            const p0 = intermediatePoint(A, B, Math.max(0, tArcCenter - TANGENT_EPS), delta);
+            const p1 = intermediatePoint(A, B, Math.min(1, tArcCenter + TANGENT_EPS), delta);
+            const [bx, by] = lngLatToWebMercatorPx(p0[0], p0[1], zoom, tileSize);
+            const [ax, ay] = lngLatToWebMercatorPx(p1[0], p1[1], zoom, tileSize);
+            const ddx = ax - bx;
+            const ddy = ay - by;
+            const tangentLen = Math.sqrt(ddx * ddx + ddy * ddy);
+            if (tangentLen > 0) {
+                const rawDir = [ddx / tangentLen, ddy / tangentLen];
+                // Orient tangent to match the reading direction stored in best.directionPx.
+                const dot = best.directionPx[0] * rawDir[0] + best.directionPx[1] * rawDir[1];
+                const negDir = [-rawDir[0], -rawDir[1]];
+                resolvedDirectionPx = dot >= 0 ? rawDir : negDir;
+            }
+            else {
+                resolvedDirectionPx = best.directionPx;
+            }
+        }
+        else {
+            // Co-located vertices — fall back to Mercator straight-line.
+            const [anchorLng, anchorLat] = webMercatorPxToLngLat(anchorRelX + pxViewMin, anchorRelY + pyViewMin, zoom, tileSize);
+            position = [anchorLng, anchorLat];
+            resolvedDirectionPx = best.directionPx;
+        }
+    }
+    else {
+        const [anchorLng, anchorLat] = webMercatorPxToLngLat(anchorRelX + pxViewMin, anchorRelY + pyViewMin, zoom, tileSize);
+        position = [anchorLng, anchorLat];
+        resolvedDirectionPx = best.directionPx;
+    }
     return {
-        position: [anchorLng, anchorLat],
+        position,
         layout: {
             type: "edge",
-            directionPx: best.directionPx,
+            directionPx: resolvedDirectionPx,
             anchor: resolvedAnchor,
             outwardSide: layoutOutwardSide,
         },
@@ -8580,7 +8814,7 @@ const placementToAnchor = (placement) => {
  * caller-managed annotation).
  */
 const computeEdgeAutoPlacement = (feature, label, viewportBounds, zoom, tileSize, options) => {
-    const { labelPixelWidth, mode = "auto", previousAnchorGeo, previousLayoutSide } = options;
+    const { labelPixelWidth, mode = "auto", previousAnchorGeo, previousLayoutSide, geodesic = false } = options;
     const geomType = feature.geometry?.type;
     const isPointGeometry = geomType === "Point" || geomType === "MultiPoint";
     if (isPointGeometry) {
@@ -8622,6 +8856,7 @@ const computeEdgeAutoPlacement = (feature, label, viewportBounds, zoom, tileSize
         edgeInsets: options.edgeInsets,
         labelAnchor: options.labelAnchor,
         labelPlacementResolver: options.labelPlacementResolver,
+        geodesic,
     });
     if (edgePlacement !== null) {
         return {
@@ -8649,6 +8884,7 @@ const computeEdgeAutoPlacement = (feature, label, viewportBounds, zoom, tileSize
             labelAnchor: options.labelAnchor,
             labelPlacementResolver: options.labelPlacementResolver,
             isForced: true,
+            geodesic,
         });
         if (forcedPlacement !== null) {
             const fitMode = forcedPlacement.fitMode === "clipped" ? "overflow" : forcedPlacement.fitMode;
@@ -8687,12 +8923,36 @@ const isLineGeometry = (geometry) => {
  * For Polygons, `outwardSide` uses the cross product with the geometry centroid
  * to determine which side faces away from the interior. For LineStrings (no
  * interior), `outwardSide` defaults to `"above"`.
+ *
+ * When `geodesic` is `true`, `angleDeg` is derived from the arc tangent at
+ * the edge midpoint (t = 0.5) via finite difference, so decorations are
+ * rotated correctly relative to the visible curved edge.
  */
-const computeEdgeProperties = (start, end, geometry, zoom, tileSize) => {
+const computeEdgeProperties = (start, end, geometry, zoom, tileSize, geodesic = false) => {
     const midLat = (start[1] + end[1]) / 2;
-    const [startPx, startPy] = lngLatToWebMercatorPx(start[0], start[1], zoom, tileSize);
-    const [endPx, endPy] = lngLatToWebMercatorPx(end[0], end[1], zoom, tileSize);
-    const angleDeg = normalizeReadableAngle(Math.atan2(endPy - startPy, endPx - startPx) * RAD_TO_DEG);
+    let angleDeg;
+    if (geodesic) {
+        const delta = angularDistance(start[0], start[1], end[0], end[1]);
+        if (delta > 0) {
+            // Finite-difference tangent at the arc midpoint (t = 0.5).
+            const TANGENT_EPS = 0.001;
+            const p0 = intermediatePoint(start, end, 0.5 - TANGENT_EPS, delta);
+            const p1 = 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);
+            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);
+            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);
+        angleDeg = normalizeReadableAngle(Math.atan2(endPy - startPy, endPx - startPx) * RAD_TO_DEG);
+    }
     const pixelLength = edgePixelLength(start[0], start[1], end[0], end[1], zoom, midLat, tileSize);
     let outwardSide = "above";
     if (!isLineGeometry(geometry)) {
@@ -8957,39 +9217,60 @@ const featureBbox = (feature) => {
     return [minLng, minLat, maxLng, maxLat];
 };
 const bboxesIntersect = (a, b) => a[2] >= b[0] && a[0] <= b[2] && a[3] >= b[1] && a[1] <= b[3];
-const countOverlappingShapes = (feature, featureBboxes, viewportBounds) => {
-    const bbox = featureBboxes.get(feature);
-    if (bbox === undefined || bbox === null)
-        return 0;
-    const geom = feature.geometry;
-    const isPolygonal = geom !== null && (geom.type === "Polygon" || geom.type === "MultiPolygon");
-    let count = 0;
-    for (const [otherFeature, otherBbox] of featureBboxes) {
-        if (otherFeature === feature || otherBbox === null)
+/**
+ * Compute per-feature overlap counts for all features in one O(n²) pass.
+ *
+ * Previously `countOverlappingShapes` was called once per feature, re-scanning
+ * every other feature and re-running polygon intersection for the same pairs —
+ * O(n³) intersection work per handle per pan frame. Each unordered pair is
+ * evaluated at most once here.
+ */
+const buildOverlappingShapesCountMap = (features, featureBboxes, viewportBounds) => {
+    const counts = new Map();
+    for (const feature of features) {
+        counts.set(feature, 0);
+    }
+    for (let i = 0; i < features.length; i++) {
+        const featureA = features[i];
+        if (featureA === undefined)
             continue;
-        if (!bboxesIntersect(otherBbox, viewportBounds))
+        const bboxA = featureBboxes.get(featureA);
+        if (bboxA === undefined || bboxA === null)
             continue;
-        if (!bboxesIntersect(bbox, otherBbox))
+        if (!bboxesIntersect(bboxA, viewportBounds))
             continue;
-        const otherGeom = otherFeature.geometry;
-        const otherIsPolygonal = otherGeom !== null && (otherGeom.type === "Polygon" || otherGeom.type === "MultiPolygon");
-        if (isPolygonal && otherIsPolygonal) {
-            // Precise polygon intersection — bbox was a prefilter only
-            if (getGeoJsonPolygonIntersection(geom, otherGeom) !== null) {
-                // If this feature is fully contained inside the other, its fill does not
-                // obscure the base map layer below — only the outer's count increments.
-                if (isFullyContainedInGeoJsonGeometry(geom, otherGeom) === true) {
-                    continue;
+        const geomA = featureA.geometry;
+        const isPolygonalA = geomA !== null && (geomA.type === "Polygon" || geomA.type === "MultiPolygon");
+        for (let j = i + 1; j < features.length; j++) {
+            const featureB = features[j];
+            if (featureB === undefined)
+                continue;
+            const bboxB = featureBboxes.get(featureB);
+            if (bboxB === undefined || bboxB === null)
+                continue;
+            if (!bboxesIntersect(bboxB, viewportBounds))
+                continue;
+            if (!bboxesIntersect(bboxA, bboxB))
+                continue;
+            const geomB = featureB.geometry;
+            const isPolygonalB = geomB !== null && (geomB.type === "Polygon" || geomB.type === "MultiPolygon");
+            if (isPolygonalA && isPolygonalB) {
+                if (getGeoJsonPolygonIntersection(geomA, geomB) !== null) {
+                    if (isFullyContainedInGeoJsonGeometry(geomA, geomB) !== true) {
+                        counts.set(featureA, (counts.get(featureA) ?? 0) + 1);
+                    }
+                    if (isFullyContainedInGeoJsonGeometry(geomB, geomA) !== true) {
+                        counts.set(featureB, (counts.get(featureB) ?? 0) + 1);
+                    }
                 }
-                count++;
             }
-        }
-        else {
-            // Points and lines keep bbox-only overlap (geometries have no fill area)
-            count++;
+            else {
+                counts.set(featureA, (counts.get(featureA) ?? 0) + 1);
+                counts.set(featureB, (counts.get(featureB) ?? 0) + 1);
+            }
         }
     }
-    return count;
+    return counts;
 };
 /**
  * Value-based equality for the nested style overrides maps. Used to skip
@@ -9128,6 +9409,7 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
                 }
                 return shapesInViewportCache;
             };
+            const overlappingCounts = buildOverlappingShapesCountMap(handle.features.features, featureBboxes, bounds);
             handle.features.features.forEach((feature, index) => {
                 const geometry = feature.geometry;
                 if (geometry === null || geometry.type === "GeometryCollection")
@@ -9140,7 +9422,7 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
                     zoom,
                     tileSize,
                     shapesInViewport: shapesInViewport(),
-                    overlappingShapesCount: countOverlappingShapes(feature, featureBboxes, bounds),
+                    overlappingShapesCount: overlappingCounts.get(feature) ?? 0,
                     interaction: currentInteraction,
                 });
                 const featureStyle = resolutionContext === null ? handle.resolveStyle(feature) : handle.resolveStyle(feature, resolutionContext);
@@ -9190,7 +9472,7 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
                         ...(decoration.sourceProperties ?? {}),
                     };
                     if (resolved.edgeEndpoints !== null) {
-                        const edgeProps = computeEdgeProperties(resolved.edgeEndpoints.start, resolved.edgeEndpoints.end, geometry, zoom, tileSize);
+                        const edgeProps = computeEdgeProperties(resolved.edgeEndpoints.start, resolved.edgeEndpoints.end, geometry, zoom, tileSize, featureStyle.geodesic ?? true);
                         properties = { ...properties, ...edgeProps };
                     }
                     newLayers.push({
@@ -9283,6 +9565,7 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
                             labelAnchor: anchor.labelAnchor,
                             labelPlacementResolver: anchor.labelPlacementResolver,
                             mode,
+                            geodesic: featureStyle.geodesic ?? true,
                         });
                         switch (outcome.type) {
                             case "placed": {
@@ -9746,7 +10029,7 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
                         if (restingClip !== undefined)
                             restingPeerFills.set(featureId, restingClip);
                     }
-                    const peerFills = computePromotionGroupFills(groupMembers, winnerId, restingPeerFills);
+                    const peerFills = computePromotionGroupFills(groupMembers, winnerId, restingPeerFills, handle?.style.geodesic, handle?.featureStyles);
                     modifiedFills.delete(winnerId);
                     for (const [featureId, clip] of peerFills) {
                         modifiedFills.set(featureId, clip);
@@ -9799,12 +10082,28 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
                 .sort(([a], [b]) => (a < b ? -1 : 1))
                 .map(([handleId, ids]) => `${handleId}:${[...ids].sort().join(",")}`)
                 .join(";");
+        // Geodesic key: per-handle layer flag + sorted per-feature geodesic overrides.
+        // Toggling geodesic (layer or per-feature) must recompute instead of serving
+        // a stale clip (mirrors suppressedKey shape).
+        const geodesicKey = currentHandles
+            .map(handle => {
+            const layerFlag = handle.style.geodesic;
+            const featureFlags = handle.featureStyles
+                ? [...handle.featureStyles.entries()]
+                    .filter(([, style]) => style.geodesic !== undefined)
+                    .sort(([a], [b]) => (a < b ? -1 : 1))
+                    .map(([id, style]) => `${id}:${String(style.geodesic)}`)
+                    .join(",")
+                : "";
+            return `${handle.id}:${String(layerFlag)}:${featureFlags}`;
+        })
+            .join(";");
         // Bounds are intentionally excluded from the inputKey. Clip geometry depends on
         // zoom (which affects stack order via resolveStackOrder) and feature geometry —
         // not on the visible viewport region. Using global bounds means all overlapping
         // features always have pre-computed clips, so polygons entering the viewport
         // during zoom-out never flash their unclipped fill.
-        const inputKey = `${tilingContentKeyRef.current}|${currentViewport.zoom}|${selectedFeatureIdRef.current ?? ""}|${suppressedKey}`;
+        const inputKey = `${tilingContentKeyRef.current}|${currentViewport.zoom}|${selectedFeatureIdRef.current ?? ""}|${suppressedKey}|${geodesicKey}`;
         if (inputKey === lastComputeInputKeyRef.current) {
             return;
         }
@@ -9835,6 +10134,8 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
                 zoom: currentViewport.zoom,
                 selectedFeatureId: selectedFeatureIdRef.current,
                 suppressedFeatureIds: suppressedFillIdsByHandleRef.current?.get(handle.id),
+                layerGeodesic: handle.style.geodesic,
+                featureStyles: handle.featureStyles,
             });
             featureToGroupKeyByHandleRef.current.set(handle.id, new Map(featureToGroupKey));
             if (fillGeometries.size > 0) {
@@ -9951,6 +10252,8 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
                     tileSize: currentViewport.tileSize,
                     strokeWidthFor,
                     visibleFillFor,
+                    layerGeodesic: handle.style.geodesic,
+                    featureStyles: handle.featureStyles,
                 });
                 handle.onShapesUnderCursor?.(hits, { position });
                 settleHitsByHandle.set(handle.id, hits);
@@ -10108,6 +10411,8 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
             tileSize,
             strokeWidthFor,
             visibleFillFor,
+            layerGeodesic: handle.style.geodesic,
+            featureStyles: handle.featureStyles,
         });
     }, []);
     const setDecorationHoverActive = useCallback((active) => {