@trackunit/react-map 0.1.3 → 0.1.4

package/index.cjs.js

@@ -6411,7 +6411,7 @@ const extractPositions = (features) => {
  * ```
  */
 const useShapes = (options) => {
-    const { id, name, features: rawFeatures, resolveStyle, interactive = "stroke", controls, getDecorations, skipAutoDecorations = false, loading, fitParticipation = "all", } = options;
+    const { id, name, features: rawFeatures, resolveStyle, interactive = "stroke", overlap, controls, getDecorations, skipAutoDecorations = false, loading, fitParticipation = "all", onShapesUnderCursor, } = options;
     // ---- Data readiness tracking ----
     const layerReady = useLayerReady(loading);
     // ---- Validate and stabilize features ----
@@ -6475,6 +6475,14 @@ const useShapes = (options) => {
         const auto = buildMultiPartDecorations(feature, strokeColor, pointRadius, strokeWidth);
         return auto.length > 0 ? [...custom, ...auto] : custom;
     }, [skipAutoDecorations, featureStyles]);
+    // Stabilize onShapesUnderCursor so an inline lambda does not recreate the handle.
+    const onShapesUnderCursorRef = react.useRef(onShapesUnderCursor);
+    react.useEffect(() => {
+        onShapesUnderCursorRef.current = onShapesUnderCursor;
+    }, [onShapesUnderCursor]);
+    const stableOnShapesUnderCursor = react.useCallback((hits, ctx) => {
+        onShapesUnderCursorRef.current?.(hits, ctx);
+    }, []);
     // ---- Build the layer handle ----
     return react.useMemo(() => ({
         id,
@@ -6492,7 +6500,9 @@ const useShapes = (options) => {
         resolveStyle: stableResolveStyle,
         featureStyles,
         interactive,
+        overlap,
         getDecorations: stableGetDecorations,
+        onShapesUnderCursor: stableOnShapesUnderCursor,
     }), [
         id,
         name,
@@ -6505,7 +6515,9 @@ const useShapes = (options) => {
         stableResolveStyle,
         featureStyles,
         interactive,
+        overlap,
         stableGetDecorations,
+        stableOnShapesUnderCursor,
     ]);
 };
 
@@ -6961,6 +6973,8 @@ function toMapLayer(handle) {
                 features: handle.features,
                 style: handle.style,
                 featureStyles: handle.featureStyles,
+                featureFillGeometries: handle.featureFillGeometries,
+                featureZIndexOverrides: handle.featureZIndexOverrides,
                 interactive: handle.interactive,
             };
         case "route":
@@ -7165,6 +7179,42 @@ const useMarkerMountBridge = (features, currentMediums) => {
     return react.useMemo(() => ({ mountingIds }), [mountingIds]);
 };
 
+// Matches the browser's default double-click timing window. Pixel-proximity is
+// intentionally NOT checked — geo-anchored decorations can shift on screen
+// between the two clicks (e.g. when the first click opens a panel that
+// triggers a map auto-pan), so the browser's native dblclick event and the
+// e.detail === 2 shorthand both fail here. Time-only detection is the correct
+// solution.
+const DOUBLE_CLICK_THRESHOLD_MS = 500;
+/**
+ * Time-based double-click detection for interactive DOM overlays.
+ *
+ * Call the returned `dispatch` on every `click` event. When two calls arrive
+ * within `DOUBLE_CLICK_THRESHOLD_MS`, the second call is treated as a
+ * double-click and `onDblClick` is invoked; otherwise `onClick` is invoked.
+ *
+ * A third rapid click resets the window (triple-click is not treated as a
+ * second double-click).
+ *
+ * @internal
+ */
+const useManualDblClick = (onClick, onDblClick) => {
+    const lastClickTimeRef = react.useRef(0);
+    return react.useCallback((arg) => {
+        const now = Date.now();
+        const timeSinceLast = now - lastClickTimeRef.current;
+        const isManualDblClick = timeSinceLast <= DOUBLE_CLICK_THRESHOLD_MS && onDblClick !== undefined;
+        // Reset so a third rapid click doesn't re-fire the double-click action.
+        lastClickTimeRef.current = isManualDblClick ? 0 : now;
+        if (isManualDblClick) {
+            onDblClick(arg);
+        }
+        else {
+            onClick?.(arg);
+        }
+    }, [onClick, onDblClick]);
+};
+
 /**
  * Uniform interactive wrapper for shape decorations.
  *
@@ -7173,19 +7223,24 @@ const useMarkerMountBridge = (features, currentMediums) => {
  * selection, mouseenter/mouseleave dispatches entity hover — both followed
  * by optional supplementary callbacks.
  *
+ * Double-click is detected via time-based logic (`useManualDblClick`) rather
+ * than the native `dblclick` event. See that hook for the rationale.
+ *
  * @internal
  */
 const InteractiveDecoration = ({ entity, select, hover, onClick, onDblClick, onHover, children, }) => {
+    const dispatchClick = useManualDblClick(onClick, onDblClick);
     const handleClick = react.useCallback((e) => {
         e.stopPropagation();
         select(entity);
-        onClick?.(entity);
-    }, [entity, select, onClick]);
+        dispatchClick(entity);
+    }, [entity, select, dispatchClick]);
+    // Native dblclick is suppressed — the action is already handled by the
+    // time-based detection in handleClick above (second click fires before dblclick).
+    // We still stopPropagation so the event doesn't reach the map canvas.
     const handleDblClick = react.useCallback((e) => {
         e.stopPropagation();
-        select(entity);
-        onDblClick?.(entity);
-    }, [entity, select, onDblClick]);
+    }, []);
     const handleMouseEnter = react.useCallback(() => {
         hover(entity);
         onHover?.(entity);
@@ -7197,6 +7252,401 @@ const InteractiveDecoration = ({ entity, select, hover, onClick, onDblClick, onH
     return (jsxRuntime.jsx("button", { className: "m-0 cursor-pointer appearance-none border-0 bg-transparent p-0 focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-1", onClick: handleClick, onDoubleClick: handleDblClick, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, type: "button", children: children }));
 };
 
+/**
+ * Pure fill-tiling core for ADR-0021. Given a set of features, the current
+ * viewport, a stack-order resolver, and an optional cursor, it computes the
+ * clipped fill geometry for every feature whose fill overlaps a neighbour.
+ *
+ * Non-overlapping features and the top-ranked feature of each overlap group
+ * keep their full geometry (no entry returned → adapter falls back to full).
+ * Fully covered features map to an empty MultiPolygon (no fill painted).
+ *
+ * Kept free of React/rAF so it is unit-testable; the surrounding hook owns the
+ * pointermove throttling and emits the result through the adapter.
+ */
+/** Empty fill = painted by nobody (fully covered loser or suppressed feature). */
+const EMPTY_FILL = { type: "MultiPolygon", coordinates: [] };
+/**
+ * A feature's fill is suppressed when `fillOpacity` is exactly `0` on the
+ * resolved style. Suppressed features are excluded from tiling stack
+ * computation (no overlap ownership, no clip neighbour) and from fill
+ * hit-testing (stroke remains interactive).
+ */
+const isFillSuppressed = (style) => style?.fillOpacity === 0;
+const polygonalFromGeometry = (geometry) => {
+    if (geometry.type === "Polygon")
+        return geometry;
+    if (geometry.type === "MultiPolygon") {
+        if (geometry.coordinates.length === 0)
+            return null;
+        return geometry;
+    }
+    return null;
+};
+/** Resolve the geometry used for fill hit-tests; stroke always uses the full shape. */
+const fillGeometryForHitTest = (featureId, fullGeometry, visibleFillFor) => {
+    if (visibleFillFor === undefined)
+        return fullGeometry;
+    const override = visibleFillFor(featureId);
+    if (override === undefined)
+        return fullGeometry;
+    if (override === null)
+        return null;
+    return polygonalFromGeometry(override);
+};
+const polygonalGeometry = (feature) => {
+    const geom = feature.geometry;
+    if (geom === null)
+        return null;
+    if (geom.type === "Polygon" || geom.type === "MultiPolygon")
+        return geom;
+    return null;
+};
+const computeBbox = (geometry) => {
+    let minLng = Infinity;
+    let minLat = Infinity;
+    let maxLng = -Infinity;
+    let maxLat = -Infinity;
+    const rings = geometry.type === "Polygon" ? geometry.coordinates : geometry.coordinates.flatMap(part => part);
+    for (const ring of rings) {
+        for (const [lng, lat] of ring) {
+            if (lng < minLng)
+                minLng = lng;
+            if (lng > maxLng)
+                maxLng = lng;
+            if (lat < minLat)
+                minLat = lat;
+            if (lat > maxLat)
+                maxLat = lat;
+        }
+    }
+    return [minLng, minLat, maxLng, maxLat];
+};
+/**
+ * Longitude-interval intersection that honours RFC 7946 §5.2 antimeridian-crossing
+ * bboxes (west > east). Latitude stays a standard closed-interval test.
+ *
+ * Note: `computeBbox` produces a conservative [-180..180] box for MultiPolygon
+ * sites that span the antimeridian after RFC 7946 coordinate-splitting; this
+ * over-includes (never drops) those shapes, which is intentional.
+ *
+ * `useShapeDecorations.tsx` has its own copy of bboxesIntersect — left separate
+ * (it is not exported and that file is out of scope for this fix).
+ */
+const lngIntervalsIntersect = (aW, aE, bW, bE) => {
+    const aWraps = aW > aE;
+    const bWraps = bW > bE;
+    if (aWraps && bWraps)
+        return true;
+    if (aWraps)
+        return bE >= aW || bW <= aE;
+    if (bWraps)
+        return aE >= bW || aW <= bE;
+    return aW <= bE && bW <= aE;
+};
+const bboxesIntersect$1 = (a, b) => lngIntervalsIntersect(a[0], a[2], b[0], b[2]) && a[3] >= b[1] && a[1] <= b[3];
+const ringArea = (ring) => {
+    let sum = 0;
+    for (let i = 0; i < ring.length - 1; i++) {
+        const current = ring[i];
+        const next = ring[i + 1];
+        if (current === undefined || next === undefined)
+            continue;
+        sum += current[0] * next[1] - next[0] * current[1];
+    }
+    return Math.abs(sum) / 2;
+};
+/**
+ * Planar area of any GeoJSON geometry (outer rings minus holes). Returns 0 for
+ * non-polygonal types (Point, LineString, …). Relative magnitude only — not
+ * geodesically accurate, but consistent enough for stack-order and tiebreak use.
+ */
+const geometryArea = (geometry) => {
+    if (geometry.type !== "Polygon" && geometry.type !== "MultiPolygon")
+        return 0;
+    const polygons = geometry.type === "Polygon" ? [geometry.coordinates] : geometry.coordinates;
+    let total = 0;
+    for (const rings of polygons) {
+        rings.forEach((ring, index) => {
+            const area = ringArea(ring);
+            total += index === 0 ? area : -area;
+        });
+    }
+    return Math.abs(total);
+};
+/** Inside any polygon part (holes respected). */
+const pointInGeometry = (position, geometry) => {
+    const point = { type: "Point", coordinates: position };
+    const polygons = geometry.type === "Polygon"
+        ? [geometry]
+        : geometry.coordinates.map(coordinates => ({ type: "Polygon", coordinates }));
+    for (const polygon of polygons) {
+        if (geoJsonUtils.isGeoJsonPointInPolygon({ point, polygon }) === true)
+            return true;
+    }
+    return false;
+};
+// ============================================================================
+// Shapes-under-cursor query (ADR-0021 §shapesUnderCursor)
+// ============================================================================
+/** Geographic degrees spanned by one screen pixel at a given zoom and tile size. */
+const degreesPerPixel = (zoom, tileSize) => 360 / (tileSize * Math.pow(2, zoom));
+/**
+ * Adapter-agnostic hit test: given a cursor `position` and a list of GeoJSON
+ * features, returns all features whose fill or stroke region contains the
+ * position, along with raw distance-to-boundary for caller tiebreaks.
+ *
+ * - **fill**: point-in-polygon on the feature's **visible** fill geometry when
+ *   `visibleFillFor` is supplied (clipped tiling output); otherwise the full
+ *   feature geometry. Stroke distance always uses the full outline.
+ * - **stroke**: `distanceToBoundary < max(strokeWidth, 3) / 2` pixels, converted
+ *   to geographic degrees via `degreesPerPixel(zoom, tileSize)`.
+ * - Bbox-prefiltered for performance; results are in deterministic (feature-id) order.
+ */
+const shapesUnderCursor = (position, features, options) => {
+    const { zoom, tileSize, strokeWidthFor, visibleFillFor } = options;
+    const degPerPx = degreesPerPixel(zoom, tileSize);
+    const hits = [];
+    for (const feature of features) {
+        if (feature.id === undefined)
+            continue;
+        const geometry = polygonalGeometry(feature);
+        if (geometry === null)
+            continue;
+        const featureId = String(feature.id);
+        const bbox = computeBbox(geometry);
+        // Loose bbox pre-filter: expand by a small margin for stroke proximity.
+        const strokeWidth = strokeWidthFor(featureId);
+        const strokeHalfDeg = (degPerPx * Math.max(strokeWidth, 3)) / 2;
+        const expandedBbox = [
+            bbox[0] - strokeHalfDeg,
+            bbox[1] - strokeHalfDeg,
+            bbox[2] + strokeHalfDeg,
+            bbox[3] + strokeHalfDeg,
+        ];
+        const pointBbox = [position[0], position[1], position[0], position[1]];
+        if (!bboxesIntersect$1(expandedBbox, pointBbox))
+            continue;
+        const fillGeom = fillGeometryForHitTest(featureId, geometry, visibleFillFor);
+        const fill = fillGeom !== null && pointInGeometry(position, fillGeom);
+        const distanceToBoundary = geoJsonUtils.distanceToGeoJsonPolygonBoundary(position, geometry);
+        const stroke = distanceToBoundary !== null && distanceToBoundary < strokeHalfDeg;
+        if (fill || stroke) {
+            hits.push({ featureId, fill, stroke, distanceToBoundary });
+        }
+    }
+    // Deterministic order: sort by featureId string so callers get stable results.
+    hits.sort((a, b) => (a.featureId < b.featureId ? -1 : a.featureId > b.featureId ? 1 : 0));
+    return hits;
+};
+/**
+ * Connected components of features that share fill area. Bbox prefilter then
+ * exact polygon intersection, mirroring `countOverlappingShapes`.
+ */
+const buildOverlapGroups = (records) => {
+    const parent = records.map((_, index) => index);
+    const find = (index) => {
+        let root = index;
+        while (parent[root] !== root)
+            root = parent[root] ?? root;
+        let node = index;
+        while (parent[node] !== root) {
+            const nextNode = parent[node] ?? root;
+            parent[node] = root;
+            node = nextNode;
+        }
+        return root;
+    };
+    const union = (a, b) => {
+        parent[find(a)] = find(b);
+    };
+    for (let i = 0; i < records.length; i++) {
+        for (let j = i + 1; j < records.length; j++) {
+            const a = records[i];
+            const b = records[j];
+            if (a === undefined || b === undefined)
+                continue;
+            if (!bboxesIntersect$1(a.bbox, b.bbox))
+                continue;
+            if (geoJsonUtils.getGeoJsonPolygonIntersection(a.geometry, b.geometry) !== null) {
+                union(i, j);
+            }
+        }
+    }
+    const groups = new Map();
+    records.forEach((record, index) => {
+        const root = find(index);
+        const group = groups.get(root);
+        if (group === undefined) {
+            groups.set(root, [record]);
+        }
+        else {
+            group.push(record);
+        }
+    });
+    return [...groups.values()].filter(group => group.length >= 2);
+};
+const buildContendedShapes = (group) => group.map(record => {
+    const containedIn = [];
+    for (const other of group) {
+        if (other.id === record.id)
+            continue;
+        if (geoJsonUtils.isFullyContainedInGeoJsonGeometry(record.geometry, other.geometry) === true) {
+            containedIn.push(other.id);
+        }
+    }
+    return {
+        feature: record.feature,
+        area: geometryArea(record.geometry),
+        containedIn,
+    };
+});
+/** Stable key for a group: sorted member ids. */
+const groupKeyOf = (group) => group
+    .map(record => record.id)
+    .sort()
+    .join("|");
+/** Promote `id` to the front of `order` (no-op if not present). */
+const promoteToFront = (order, id) => order.includes(id) ? [id, ...order.filter(item => item !== id)] : order;
+/**
+ * Hover-promotion overlay for one overlap group: the winner renders at full
+ * geometry (caller removes its fill override). Each peer is clipped against the
+ * winner's full outline starting from its **resting** fill (when present), not
+ * 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 geometries = new Map();
+    for (const feature of members) {
+        if (feature.id === undefined)
+            continue;
+        const geometry = polygonalGeometry(feature);
+        if (geometry !== null)
+            geometries.set(String(feature.id), geometry);
+    }
+    const winnerGeometry = geometries.get(winnerId);
+    if (winnerGeometry === undefined)
+        return new Map();
+    const result = new Map();
+    const winnerMercator = geoJsonUtils.projectPolygonalToWebMercator(winnerGeometry);
+    for (const [memberId, fullGeometry] of geometries) {
+        if (memberId === winnerId)
+            continue;
+        const restingClip = restingPeerFills.get(memberId);
+        let subject;
+        if (restingClip === undefined) {
+            subject = fullGeometry;
+        }
+        else {
+            const restingPolygonal = polygonalFromGeometry(restingClip);
+            if (restingPolygonal === null) {
+                result.set(memberId, EMPTY_FILL);
+                continue;
+            }
+            subject = restingPolygonal;
+        }
+        const subjectMercator = geoJsonUtils.projectPolygonalToWebMercator(subject);
+        const clippedMercator = geoJsonUtils.geoJsonPolygonDifference(subjectMercator, [winnerMercator]);
+        const clipped = clippedMercator === null ? null : geoJsonUtils.unprojectPolygonalFromWebMercator(clippedMercator);
+        result.set(memberId, clipped === null ? EMPTY_FILL : clipped);
+    }
+    return result;
+};
+const computeFillTiling = (input) => {
+    const { features, viewportBounds, resolveStackOrder, zoom, selectedFeatureId, suppressedFeatureIds } = input;
+    const records = [];
+    for (const feature of features) {
+        if (feature.id === undefined)
+            continue;
+        const id = String(feature.id);
+        const geometry = polygonalGeometry(feature);
+        if (geometry === null)
+            continue;
+        const bbox = computeBbox(geometry);
+        if (!bboxesIntersect$1(bbox, viewportBounds))
+            continue;
+        // Suppressed features are excluded from the overlap stack so they neither
+        // claim fill ownership nor clip their neighbours.
+        if (suppressedFeatureIds?.has(id) === true)
+            continue;
+        records.push({ feature, id, geometry, bbox });
+    }
+    const fillGeometries = new Map();
+    const featureToGroupKey = new Map();
+    const featureZIndex = new Map();
+    const overlapGroups = buildOverlapGroups(records);
+    for (const group of overlapGroups) {
+        const contended = buildContendedShapes(group);
+        const recordById = new Map(group.map(record => [record.id, record]));
+        const key = groupKeyOf(group);
+        for (const record of group) {
+            featureToGroupKey.set(record.id, key);
+        }
+        // 1. Resting order: containment then smaller-area.
+        let order = resolveStackOrder(contended, { zoom });
+        // 2. Selection override: selected feature always takes front (highest priority).
+        if (selectedFeatureId !== null && selectedFeatureId !== undefined) {
+            order = promoteToFront(order, selectedFeatureId);
+        }
+        // Assign resting z-indices: rank 0 (front) → highest value, rank N-1 → 1.
+        // These are stable across hover events; the hook applies a lightweight
+        // promotion overlay on top without re-running computeFillTiling (ADR-0021 Path B).
+        for (let rank = 0; rank < order.length; rank++) {
+            const id = order[rank];
+            if (id !== undefined) {
+                featureZIndex.set(id, order.length - rank);
+            }
+        }
+        // Top feature (index 0) keeps its full fill. Each lower-ranked feature is
+        // clipped against the union of all features ranked above it.
+        for (let rank = 1; rank < order.length; rank++) {
+            const id = order[rank];
+            if (id === undefined)
+                continue;
+            const record = recordById.get(id);
+            if (record === undefined)
+                continue;
+            const higherRanked = [];
+            for (let above = 0; above < rank; above++) {
+                const aboveId = order[above];
+                const aboveRecord = aboveId !== undefined ? recordById.get(aboveId) : undefined;
+                if (aboveRecord !== undefined)
+                    higherRanked.push(aboveRecord.geometry);
+            }
+            // Clip in Web Mercator, not planar lng/lat. Google Maps and Mapbox both render
+            // polygon edges as straight lines in Web Mercator, so a clip computed in lng/lat
+            // produces boundary vertices that drift off the rendered edge of the covering
+            // shape — visibly so on long, diagonal, high-latitude-span edges. Projecting
+            // before the difference lands every cut exactly on the rendered edge (ADR-0021).
+            const subjectMercator = geoJsonUtils.projectPolygonalToWebMercator(record.geometry);
+            const clipsMercator = higherRanked.map(geoJsonUtils.projectPolygonalToWebMercator);
+            const clippedMercator = geoJsonUtils.geoJsonPolygonDifference(subjectMercator, clipsMercator);
+            const clipped = clippedMercator === null ? null : geoJsonUtils.unprojectPolygonalFromWebMercator(clippedMercator);
+            fillGeometries.set(id, clipped === null ? EMPTY_FILL : clipped);
+        }
+    }
+    // Suppressed features emit EMPTY_FILL when in the viewport so the adapter
+    // paints nothing for their fill layer. They get no featureToGroupKey entry
+    // so promoteFeature is a natural no-op for them.
+    if (suppressedFeatureIds !== undefined && suppressedFeatureIds.size > 0) {
+        for (const feature of features) {
+            if (feature.id === undefined)
+                continue;
+            const id = String(feature.id);
+            if (!suppressedFeatureIds.has(id))
+                continue;
+            const geometry = polygonalGeometry(feature);
+            if (geometry === null)
+                continue;
+            const bbox = computeBbox(geometry);
+            if (!bboxesIntersect$1(bbox, viewportBounds))
+                continue;
+            fillGeometries.set(id, EMPTY_FILL);
+        }
+    }
+    return { fillGeometries, featureToGroupKey, featureZIndex };
+};
+
 const DEFAULT_ZOOM = 0;
 const DEFAULT_TILE_SIZE = 256;
 /**
@@ -8512,11 +8962,31 @@ 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)
             continue;
-        if (bboxesIntersect(otherBbox, viewportBounds) && bboxesIntersect(bbox, otherBbox)) {
+        if (!bboxesIntersect(otherBbox, viewportBounds))
+            continue;
+        if (!bboxesIntersect(bbox, otherBbox))
+            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 (geoJsonUtils.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 (geoJsonUtils.isFullyContainedInGeoJsonGeometry(geom, otherGeom) === true) {
+                    continue;
+                }
+                count++;
+            }
+        }
+        else {
+            // Points and lines keep bbox-only overlap (geometries have no fill area)
             count++;
         }
     }
@@ -8605,6 +9075,7 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
     const previousAnchorGeos = react.useRef(new Map());
     const previousLayoutSides = react.useRef(new Map());
     const prevStyleOverridesRef = react.useRef(new Map());
+    const prevDecorationLayersRef = react.useRef([]);
     /**
      * Labels that just transitioned from absent (hidden) to placed. While in
      * this set, edge identity is NOT stored — the algorithm gets one extra
@@ -8627,6 +9098,8 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
     const viewport = useViewportContext(hasShapeHandles ? api : undefined);
     const isReady = api?.state.isReady ?? false;
     const theme = api?.state.appearance.theme ?? "light";
+    const isMapMovingRef = react.useRef(false);
+    const pendingDecorationUpdateRef = react.useRef(false);
     const updateDecorations = react.useCallback(() => {
         const bounds = viewport.bounds;
         if (bounds === null || !isReady) {
@@ -8885,7 +9358,14 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
             });
             styleOverrides.set(handle.id, handleStyleOverrides);
         }
-        onDecorationsChange(newLayers);
+        // Only push decoration layer changes when the output actually differs.
+        // During pan, updateDecorations is called on every camera frame; skipping
+        // unchanged outputs avoids triggering unnecessary React re-renders while
+        // the camera is moving but no edge label has changed position.
+        if (!esToolkit.isEqual(prevDecorationLayersRef.current, newLayers)) {
+            prevDecorationLayersRef.current = newLayers;
+            onDecorationsChange(newLayers);
+        }
         if (!styleOverridesEqual(prevStyleOverridesRef.current, styleOverrides)) {
             prevStyleOverridesRef.current = styleOverrides;
             onStyleOverridesChange(styleOverrides);
@@ -8904,11 +9384,53 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
         renderedSourceIds,
         isReady,
     ]);
+    const updateDecorationsRef = react.useRef(updateDecorations);
     react.useEffect(() => {
-        updateDecorations();
-    }, [updateDecorations, readyRevision]);
+        updateDecorationsRef.current = updateDecorations;
+    }, [updateDecorations]);
+    react.useEffect(() => {
+        if (api === undefined || !hasShapeHandles)
+            return;
+        const unsubscribeMoveStart = api.on("movestart", () => {
+            isMapMovingRef.current = true;
+        });
+        // Update decorations immediately on idle — no extra debounce. The 300 ms
+        // debounce used by fill tiling is not needed here because:
+        //  1. updateDecorations is cheap (pure JS placement math, no polygon clipping).
+        //  2. pendingDecorationUpdateRef prevents redundant calls: only the first idle
+        //     after a pan triggers a real recompute; subsequent tile-load idles are
+        //     no-ops because the flag was already cleared.
+        const unsubscribeIdle = api.on("idle", () => {
+            isMapMovingRef.current = false;
+            if (pendingDecorationUpdateRef.current) {
+                pendingDecorationUpdateRef.current = false;
+                updateDecorationsRef.current();
+            }
+        });
+        return () => {
+            unsubscribeMoveStart();
+            unsubscribeIdle();
+        };
+    }, [api, hasShapeHandles]);
+    react.useEffect(() => {
+        pendingDecorationUpdateRef.current = true;
+    }, [viewport]);
+    react.useEffect(() => {
+        pendingDecorationUpdateRef.current = true;
+        if (isMapMovingRef.current)
+            return;
+        updateDecorationsRef.current();
+        pendingDecorationUpdateRef.current = false;
+    }, [readyRevision]);
     react.useEffect(() => {
         interactionRef.current = interaction;
+        // Always update decorations when the viewport changes (updateDecorations ref
+        // is recreated on every camera frame because viewport is in its useCallback
+        // deps). This makes edge labels track the viewport boundary in real-time
+        // during pan instead of only snapping on idle.
+        // The prevDecorationLayersRef equality guard inside updateDecorations
+        // prevents onDecorationsChange from firing when the positions haven't
+        // actually changed, keeping React re-renders cheap.
         updateDecorations();
     }, [interaction, updateDecorations]);
     react.useEffect(() => {
@@ -8927,6 +9449,674 @@ const useShapeDecorations = ({ onDecorationsChange, onStyleOverridesChange, api,
     return react.useMemo(() => ({ subscribe, getSnapshot }), [subscribe, getSnapshot]);
 };
 
+// ============================================================================
+// Default resolver
+// ============================================================================
+const featureId = (shape) => String(shape.feature.id);
+/**
+ * Default stack-order policy (ADR-0021 "golden path"). In priority order:
+ *
+ * 1. **Containment** — a shape contained within another ranks above its
+ *    container, so the specific inner site beats the broad outer one.
+ * 2. **Smaller area on top** — stable tiebreak; inner shapes are typically
+ *    smaller, so this reinforces containment and keeps nested sites visible.
+ */
+const defaultShapeStackOrder = (contended, _ctx) => {
+    const idOf = new Map();
+    for (const shape of contended) {
+        idOf.set(shape, featureId(shape));
+    }
+    const compare = (a, b) => {
+        const aId = idOf.get(a) ?? featureId(a);
+        const bId = idOf.get(b) ?? featureId(b);
+        // 1. Containment — a contained inside b ranks above (on top of) b.
+        const aInsideB = a.containedIn.includes(bId);
+        const bInsideA = b.containedIn.includes(aId);
+        if (aInsideB && !bInsideA)
+            return -1;
+        if (bInsideA && !aInsideB)
+            return 1;
+        // 2. Smaller area on top.
+        if (a.area !== b.area)
+            return a.area - b.area;
+        // Final stable tiebreak by id so ordering is deterministic.
+        return aId < bId ? -1 : aId > bId ? 1 : 0;
+    };
+    return [...contended].sort(compare).map(shape => idOf.get(shape) ?? featureId(shape));
+};
+
+const EMPTY_OVERRIDES = new Map();
+const EMPTY_ZINDEX_OVERRIDES = new Map();
+/** How long to wait after the last pointermove before running the stroke hit-test (ms). */
+const SETTLE_DEBOUNCE_MS = 120;
+/**
+ * Coalesce rapid `idle` events (wheel-zoom steps, tile-load idles during pan)
+ * into one resting recompute. 300 ms is wide enough to absorb the tile-load
+ * idle bursts that Google Maps fires every 100–300 ms during and just after
+ * panning, so only the final true-idle triggers `computeFillTiling`.
+ */
+const IDLE_RECOMPUTE_DEBOUNCE_MS = 300;
+/** Default stroke width when featureStyles does not specify one. */
+const DEFAULT_STROKE_WIDTH = 2;
+/**
+ * Z-index override applied to a hover-promoted feature so it renders above all
+ * resting-order peers in its group. Must exceed the maximum possible resting z-index
+ * (which equals groupSize, bounded by the number of features in a viewport).
+ */
+const HOVER_PROMOTION_Z_INDEX = 10000;
+/**
+ * FNV-1a 32-bit hash over an array of coordinate numbers. Cheap and
+ * change-detecting: any moved vertex changes the output; identical polls keep
+ * it stable so the tiling useMemo does not recompute unnecessarily.
+ */
+const fnv1a32Coords = (coords) => {
+    let h = 0x811c9dc5;
+    for (const n of coords) {
+        // Pack each float as two 16-bit halves to avoid float-to-int truncation loss.
+        const bits = Math.round(n * 1e7);
+        h ^= (bits >>> 16) & 0xffff;
+        h = (Math.imul(h, 0x01000193) | 0) >>> 0;
+        h ^= bits & 0xffff;
+        h = (Math.imul(h, 0x01000193) | 0) >>> 0;
+    }
+    return h;
+};
+const geometryCoordFingerprint = (feature) => {
+    const geom = feature.geometry;
+    if (geom === null)
+        return "null";
+    if (geom.type === "Polygon") {
+        const coords = geom.coordinates.flat(2);
+        return `${coords.length}:${fnv1a32Coords(coords)}`;
+    }
+    if (geom.type === "MultiPolygon") {
+        const coords = geom.coordinates.flat(3);
+        return `${coords.length}:${fnv1a32Coords(coords)}`;
+    }
+    return geom.type;
+};
+/** Content key for tiling handles — stable across new `handles` array refs with the same data.
+ * Includes a geometry fingerprint per feature so polygon edits (same id, new vertices) trigger
+ * a recompute rather than serving a stale clip. */
+const buildTilingContentKey = (handles) => {
+    const segments = [];
+    for (const handle of handles) {
+        if (handle.layerType !== "shapes" || handle.overlap?.mode !== "tile")
+            continue;
+        const featureSegments = handle.features.features.map(feature => `${String(feature.id ?? "")}:${geometryCoordFingerprint(feature)}`);
+        segments.push(`${handle.id}:${featureSegments.join(",")}`);
+    }
+    return segments.join("||");
+};
+const overridesEqual = (a, b) => {
+    if (a === b)
+        return true;
+    if (a.size !== b.size)
+        return false;
+    for (const [handleId, aHandle] of a) {
+        const bHandle = b.get(handleId);
+        if (bHandle === undefined || aHandle.size !== bHandle.size)
+            return false;
+        for (const [featureId, aGeom] of aHandle) {
+            if (!esToolkit.isEqual(aGeom, bHandle.get(featureId)))
+                return false;
+        }
+    }
+    return true;
+};
+const zIndexOverridesEqual = (a, b) => {
+    if (a === b)
+        return true;
+    if (a.size !== b.size)
+        return false;
+    for (const [handleId, aHandle] of a) {
+        const bHandle = b.get(handleId);
+        if (bHandle === undefined || aHandle.size !== bHandle.size)
+            return false;
+        for (const [featureId, aZ] of aHandle) {
+            if (aZ !== bHandle.get(featureId))
+                return false;
+        }
+    }
+    return true;
+};
+/**
+ * Pre-build a `featureId → area` lookup and return a comparator that sorts
+ * hits smallest-area-first with featureId as a stable tiebreak. Costs O(n)
+ * upfront instead of O(n) per comparison in the sort.
+ */
+const buildHitAreaComparator = (features) => {
+    const areaById = new Map();
+    for (const feature of features) {
+        if (feature.id !== undefined) {
+            areaById.set(String(feature.id), feature.geometry !== null ? geometryArea(feature.geometry) : 0);
+        }
+    }
+    return (a, b) => {
+        const aArea = areaById.get(a.featureId) ?? 0;
+        const bArea = areaById.get(b.featureId) ?? 0;
+        if (aArea !== bArea)
+            return aArea - bArea;
+        return a.featureId < b.featureId ? -1 : 1;
+    };
+};
+/**
+ * Pick one fill hit for promotion; smallest area wins when multiple remain.
+ * Accepts a pre-built comparator so the area lookup map is shared with the
+ * caller's per-group sort.
+ */
+const pickFillPromotionCandidates = (fillHits, compareByArea) => {
+    if (fillHits.length === 0)
+        return [];
+    if (fillHits.length === 1)
+        return fillHits;
+    const sorted = [...fillHits].sort(compareByArea);
+    const top = sorted[0];
+    return top === undefined ? [] : [top];
+};
+/**
+ * `useShapeFillTiling` — clips overlapping polygon fills for shape handles that
+ * opted in via `overlap: { mode: "tile" }`, and promotes shapes on stroke-hover
+ * settle (sticky, ~120ms debounce), decoration hover (edge labels, etc.), or when
+ * a shape is selected (selection always forces front). Emits the result through
+ * `onFillGeometriesChange` and `onZIndexOverridesChange`; `<Layers>` merges them
+ * into each shape handle's `featureFillGeometries` and `featureZIndexOverrides`.
+ *
+ * **Path B (ADR-0021):** `computeFillTiling` is promotion-unaware — it only runs on
+ * viewport / feature-set / selection changes and produces stable resting fills and
+ * resting z-indices. Hover promotion removes the resting clip for each group's
+ * current sticky winner (so covered area can paint on top) and raises its z-index.
+ * Non-winners in an active group are re-clipped against the winner's full outline
+ * only (exclusive rings stay painted). Promotion clears when the pointer leaves
+ * all sites on the handle.
+ *
+ * Resting tiling (viewport + feature set) is deferred while the map is moving
+ * and coalesced on `idle` so pan/zoom does not run `computeFillTiling` every frame.
+ *
+ * @internal
+ */
+const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOverridesChange, onSettledHover, selectedFeatureId, suppressedFillIdsByHandle, }) => {
+    const tilingContentKey = react.useMemo(() => buildTilingContentKey(handles), [handles]);
+    const tilingHandles = react.useMemo(() => handles.filter((handle) => handle.layerType === "shapes" && handle.overlap?.mode === "tile"), [handles]);
+    const hasTilingHandles = tilingHandles.length > 0;
+    const viewport = useViewportContext(hasTilingHandles ? api : undefined);
+    const onFillChangeRef = react.useRef(onFillGeometriesChange);
+    react.useEffect(() => {
+        onFillChangeRef.current = onFillGeometriesChange;
+    }, [onFillGeometriesChange]);
+    const onZIndexChangeRef = react.useRef(onZIndexOverridesChange);
+    react.useEffect(() => {
+        onZIndexChangeRef.current = onZIndexOverridesChange;
+    }, [onZIndexOverridesChange]);
+    const onSettledHoverRef = react.useRef(onSettledHover);
+    react.useEffect(() => {
+        onSettledHoverRef.current = onSettledHover;
+    }, [onSettledHover]);
+    const selectedFeatureIdRef = react.useRef(selectedFeatureId);
+    react.useEffect(() => {
+        selectedFeatureIdRef.current = selectedFeatureId;
+    }, [selectedFeatureId]);
+    const suppressedFillIdsByHandleRef = react.useRef(suppressedFillIdsByHandle);
+    react.useEffect(() => {
+        suppressedFillIdsByHandleRef.current = suppressedFillIdsByHandle;
+    }, [suppressedFillIdsByHandle]);
+    const debounceTimerRef = react.useRef(null);
+    const idleRecomputeTimerRef = react.useRef(null);
+    // Currently emitted overrides — used for hit-testing visible fills in handleSettle.
+    const prevFillOverridesRef = react.useRef(EMPTY_OVERRIDES);
+    const prevZIndexOverridesRef = react.useRef(EMPTY_ZINDEX_OVERRIDES);
+    // Resting state from the last computeFillTiling run (stable across hover events).
+    const restingFillByHandleRef = react.useRef(new Map());
+    const restingZIndexByHandleRef = react.useRef(new Map());
+    // Per-handle: groupKey → promoted feature id (sticky hover winner).
+    const promotedByHandleRef = react.useRef(new Map());
+    // Per-handle: featureId → groupKey (populated from last computeFillTiling result).
+    const featureToGroupKeyByHandleRef = react.useRef(new Map());
+    /** True while an interactive shape decoration (edge label, badge, …) is hovered. */
+    const decorationHoverActiveRef = react.useRef(false);
+    // Stable ref to current tiling handles for the debounce callback.
+    const tilingHandlesRef = react.useRef(tilingHandles);
+    react.useEffect(() => {
+        tilingHandlesRef.current = tilingHandles;
+    });
+    // Stable ref to current viewport for the debounce callback.
+    const viewportRef = react.useRef(viewport);
+    react.useEffect(() => {
+        viewportRef.current = viewport;
+    });
+    /** True between map `movestart` and debounced `idle` flush. */
+    const isMapMovingRef = react.useRef(false);
+    /** Viewport or tiling data changed while moving or before idle flush. */
+    const pendingRestingRecomputeRef = react.useRef(false);
+    const lastComputeInputKeyRef = react.useRef(null);
+    const tilingContentKeyRef = react.useRef(tilingContentKey);
+    react.useEffect(() => {
+        tilingContentKeyRef.current = tilingContentKey;
+    }, [tilingContentKey]);
+    /**
+     * Apply the current promotion state on top of resting fills and z-indices and emit
+     * the result. Called both at the end of `recompute` and directly on hover-settle
+     * without re-running `computeFillTiling` (Path B: promotion is a cheap overlay).
+     *
+     * Active promotion: winner unclipped; peers in the same group are clipped against
+     * the winner's full geometry so exclusive rings stay painted without compounding.
+     */
+    const emitWithPromotion = react.useCallback(() => {
+        const nextFills = new Map();
+        const nextZIndices = new Map();
+        const handleById = new Map(tilingHandlesRef.current.map(handle => [handle.id, handle]));
+        for (const [handleId, restingFills] of restingFillByHandleRef.current) {
+            const promoted = promotedByHandleRef.current.get(handleId);
+            const featureToGroupKey = featureToGroupKeyByHandleRef.current.get(handleId);
+            if (promoted === undefined || promoted.size === 0) {
+                if (restingFills.size > 0)
+                    nextFills.set(handleId, restingFills);
+            }
+            else if (featureToGroupKey === undefined) {
+                const modifiedFills = new Map(restingFills);
+                for (const promotedId of promoted.values()) {
+                    modifiedFills.delete(promotedId);
+                }
+                if (modifiedFills.size > 0)
+                    nextFills.set(handleId, modifiedFills);
+            }
+            else {
+                const handle = handleById.get(handleId);
+                const featuresById = new Map();
+                if (handle !== undefined) {
+                    for (const feature of handle.features.features) {
+                        if (feature.id !== undefined)
+                            featuresById.set(String(feature.id), feature);
+                    }
+                }
+                const modifiedFills = new Map(restingFills);
+                for (const [groupKey, winnerId] of promoted) {
+                    const groupMembers = [];
+                    for (const [featureId, memberGroupKey] of featureToGroupKey) {
+                        if (memberGroupKey !== groupKey)
+                            continue;
+                        const feature = featuresById.get(featureId);
+                        if (feature !== undefined)
+                            groupMembers.push(feature);
+                    }
+                    const restingPeerFills = new Map();
+                    for (const [featureId, memberGroupKey] of featureToGroupKey) {
+                        if (memberGroupKey !== groupKey)
+                            continue;
+                        const restingClip = restingFills.get(featureId);
+                        if (restingClip !== undefined)
+                            restingPeerFills.set(featureId, restingClip);
+                    }
+                    const peerFills = computePromotionGroupFills(groupMembers, winnerId, restingPeerFills);
+                    modifiedFills.delete(winnerId);
+                    for (const [featureId, clip] of peerFills) {
+                        modifiedFills.set(featureId, clip);
+                    }
+                }
+                if (modifiedFills.size > 0)
+                    nextFills.set(handleId, modifiedFills);
+            }
+        }
+        for (const [handleId, restingZIndices] of restingZIndexByHandleRef.current) {
+            const promoted = promotedByHandleRef.current.get(handleId);
+            if (promoted === undefined || promoted.size === 0) {
+                if (restingZIndices.size > 0)
+                    nextZIndices.set(handleId, restingZIndices);
+            }
+            else {
+                const featureToGroupKey = featureToGroupKeyByHandleRef.current.get(handleId);
+                const modifiedZIndices = new Map(restingZIndices);
+                for (const [groupKey, winnerId] of promoted) {
+                    modifiedZIndices.set(winnerId, HOVER_PROMOTION_Z_INDEX);
+                    if (featureToGroupKey !== undefined) {
+                        for (const [featureId, memberGroupKey] of featureToGroupKey) {
+                            if (memberGroupKey === groupKey && featureId !== winnerId) {
+                                modifiedZIndices.set(featureId, 0);
+                            }
+                        }
+                    }
+                }
+                nextZIndices.set(handleId, modifiedZIndices);
+            }
+        }
+        if (!overridesEqual(prevFillOverridesRef.current, nextFills)) {
+            prevFillOverridesRef.current = nextFills;
+            onFillChangeRef.current(nextFills);
+        }
+        if (!zIndexOverridesEqual(prevZIndexOverridesRef.current, nextZIndices)) {
+            prevZIndexOverridesRef.current = nextZIndices;
+            onZIndexChangeRef.current(nextZIndices);
+        }
+    }, []);
+    const recompute = react.useCallback(() => {
+        const currentViewport = viewportRef.current;
+        const currentHandles = tilingHandlesRef.current;
+        // Stable suppressed-key: per-handle sorted ids so suppression changes are
+        // not deduped away by the inputKey guard.
+        const currentSuppressed = suppressedFillIdsByHandleRef.current;
+        const suppressedKey = currentSuppressed === undefined || currentSuppressed.size === 0
+            ? ""
+            : [...currentSuppressed.entries()]
+                .sort(([a], [b]) => (a < b ? -1 : 1))
+                .map(([handleId, ids]) => `${handleId}:${[...ids].sort().join(",")}`)
+                .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}`;
+        if (inputKey === lastComputeInputKeyRef.current) {
+            return;
+        }
+        lastComputeInputKeyRef.current = inputKey;
+        if (currentHandles.length === 0) {
+            if (prevFillOverridesRef.current !== EMPTY_OVERRIDES && prevFillOverridesRef.current.size > 0) {
+                restingFillByHandleRef.current = new Map();
+                restingZIndexByHandleRef.current = new Map();
+                prevFillOverridesRef.current = EMPTY_OVERRIDES;
+                prevZIndexOverridesRef.current = EMPTY_ZINDEX_OVERRIDES;
+                promotedByHandleRef.current = new Map();
+                featureToGroupKeyByHandleRef.current = new Map();
+                onFillChangeRef.current(EMPTY_OVERRIDES);
+                onZIndexChangeRef.current(EMPTY_ZINDEX_OVERRIDES);
+            }
+            return;
+        }
+        // Use global bounds so all overlapping features always have pre-computed clips,
+        // regardless of which part of the world is currently in view.
+        const GLOBAL_BOUNDS = [-180, -90, 180, 90];
+        const nextRestingFills = new Map();
+        const nextRestingZIndices = new Map();
+        for (const handle of currentHandles) {
+            const { fillGeometries, featureToGroupKey, featureZIndex } = computeFillTiling({
+                features: handle.features.features,
+                viewportBounds: GLOBAL_BOUNDS,
+                resolveStackOrder: handle.overlap?.resolveStackOrder ?? defaultShapeStackOrder,
+                zoom: currentViewport.zoom,
+                selectedFeatureId: selectedFeatureIdRef.current,
+                suppressedFeatureIds: suppressedFillIdsByHandleRef.current?.get(handle.id),
+            });
+            featureToGroupKeyByHandleRef.current.set(handle.id, new Map(featureToGroupKey));
+            if (fillGeometries.size > 0) {
+                nextRestingFills.set(handle.id, fillGeometries);
+            }
+            if (featureZIndex.size > 0) {
+                nextRestingZIndices.set(handle.id, featureZIndex);
+            }
+        }
+        restingFillByHandleRef.current = nextRestingFills;
+        restingZIndexByHandleRef.current = nextRestingZIndices;
+        emitWithPromotion();
+    }, [emitWithPromotion]);
+    const flushPendingRestingRecompute = react.useCallback(() => {
+        if (!pendingRestingRecomputeRef.current)
+            return;
+        pendingRestingRecomputeRef.current = false;
+        // Sticky promotions survive pan/zoom — resting clips are always pre-computed
+        // globally (global-bounds fix) so the promoted feature is never "full-fill".
+        recompute();
+    }, [recompute]);
+    const scheduleIdleRestingRecompute = react.useCallback(() => {
+        if (idleRecomputeTimerRef.current !== null) {
+            clearTimeout(idleRecomputeTimerRef.current);
+        }
+        idleRecomputeTimerRef.current = setTimeout(() => {
+            idleRecomputeTimerRef.current = null;
+            isMapMovingRef.current = false;
+            flushPendingRestingRecompute();
+        }, IDLE_RECOMPUTE_DEBOUNCE_MS);
+    }, [flushPendingRestingRecompute]);
+    const promoteFeature = react.useCallback((handleId, featureId) => {
+        const groupKey = featureToGroupKeyByHandleRef.current.get(handleId)?.get(featureId);
+        if (groupKey === undefined)
+            return;
+        let handleMap = promotedByHandleRef.current.get(handleId);
+        if (handleMap === undefined) {
+            handleMap = new Map();
+            promotedByHandleRef.current.set(handleId, handleMap);
+        }
+        if (handleMap.get(groupKey) === featureId)
+            return;
+        handleMap.set(groupKey, featureId);
+        // Path B: emit lightweight promotion overlay — no recompute.
+        emitWithPromotion();
+    }, [emitWithPromotion]);
+    const clearPromotion = react.useCallback((handleId, featureId) => {
+        const groupKey = featureToGroupKeyByHandleRef.current.get(handleId)?.get(featureId);
+        if (groupKey === undefined)
+            return;
+        const handleMap = promotedByHandleRef.current.get(handleId);
+        if (handleMap === undefined || handleMap.get(groupKey) !== featureId)
+            return;
+        handleMap.delete(groupKey);
+        emitWithPromotion();
+    }, [emitWithPromotion]);
+    // Tiling feature set changed (stable key — not the `tilingHandles` array ref).
+    react.useEffect(() => {
+        pendingRestingRecomputeRef.current = true;
+        if (isMapMovingRef.current)
+            return;
+        recompute();
+    }, [recompute, tilingContentKey]);
+    react.useEffect(() => {
+        recompute();
+    }, [recompute, selectedFeatureId]);
+    // Suppression changes must trigger a recompute so EMPTY_FILL entries are
+    // added / removed even when the map is idle (covers the decorations-vs-tiling
+    // idle race where viewport-style overrides arrive after the last idle event).
+    react.useEffect(() => {
+        pendingRestingRecomputeRef.current = true;
+        if (!isMapMovingRef.current)
+            recompute();
+    }, [recompute, suppressedFillIdsByHandle]);
+    // Viewport changes only mark pending; resting recompute runs on debounced map idle.
+    react.useEffect(() => {
+        pendingRestingRecomputeRef.current = true;
+    }, [viewport]);
+    // Pointer channel: settle-debounce → stroke hit-test → promote sticky winner.
+    react.useEffect(() => {
+        if (api === undefined || !hasTilingHandles)
+            return;
+        const unsubscribeMoveStart = api.on("movestart", () => {
+            isMapMovingRef.current = true;
+            if (idleRecomputeTimerRef.current !== null) {
+                clearTimeout(idleRecomputeTimerRef.current);
+                idleRecomputeTimerRef.current = null;
+            }
+            // Promotions intentionally NOT cleared here: resting clips are always
+            // pre-computed globally so a promoted feature stays correctly clipped
+            // throughout pan/zoom. Promotion only resets when the cursor settles on
+            // a different group (handleSettle / clearPromotion path).
+        });
+        const unsubscribeIdle = api.on("idle", () => {
+            scheduleIdleRestingRecompute();
+        });
+        const handleSettle = (position) => {
+            const currentViewport = viewportRef.current;
+            const currentHandles = tilingHandlesRef.current;
+            const settleHitsByHandle = new Map();
+            for (const handle of currentHandles) {
+                const strokeWidthFor = (featureId) => handle.featureStyles?.get(featureId)?.strokeWidth ?? DEFAULT_STROKE_WIDTH;
+                const handleFillOverrides = prevFillOverridesRef.current.get(handle.id);
+                const suppressedIds = suppressedFillIdsByHandleRef.current?.get(handle.id);
+                const visibleFillFor = handleFillOverrides === undefined && suppressedIds === undefined
+                    ? undefined
+                    : (featureId) => {
+                        if (suppressedIds?.has(featureId) === true)
+                            return null;
+                        return handleFillOverrides?.get(featureId);
+                    };
+                const hits = shapesUnderCursor(position, handle.features.features, {
+                    zoom: currentViewport.zoom,
+                    tileSize: currentViewport.tileSize,
+                    strokeWidthFor,
+                    visibleFillFor,
+                });
+                handle.onShapesUnderCursor?.(hits, { position });
+                settleHitsByHandle.set(handle.id, hits);
+            }
+            // Count hits that could trigger promotion: stroke hits plus unambiguous
+            // single-fill hits (poked-out area). Used to guard the recompute-on-move.
+            const totalCandidateHits = [...settleHitsByHandle.values()].reduce((count, hits) => {
+                const strokeCount = hits.filter(h => h.stroke === true).length;
+                if (strokeCount > 0)
+                    return count + strokeCount;
+                const fillHits = hits.filter(h => h.fill === true);
+                return count + (fillHits.length >= 1 ? 1 : 0);
+            }, 0);
+            // While panning, group keys are not updated every frame — refresh once per
+            // settle when any candidate hit exists so promotion targets the right group.
+            if (isMapMovingRef.current && totalCandidateHits > 0) {
+                recompute();
+            }
+            // Sticky promotion: hovering nothing keeps all promotions — the cursor
+            // drifted off, the last winner stays in front. Hovering something updates
+            // groups under the cursor and clears groups no longer under the cursor
+            // (user's attention has moved on from those groups).
+            if (decorationHoverActiveRef.current) {
+                return;
+            }
+            // Skip promotion updates while the map is moving. The map fires
+            // pointermove during wheel zoom (world coords shift even with a stationary
+            // cursor), causing settle to run mid-zoom. Promotions should not change
+            // during movement — the sticky winner stays in front through pan/zoom.
+            if (isMapMovingRef.current) {
+                return;
+            }
+            let overallTop;
+            for (const handle of currentHandles) {
+                const hits = settleHitsByHandle.get(handle.id);
+                if (hits === undefined)
+                    continue;
+                const strokeHits = hits.filter(h => h.stroke === true);
+                // Build the area lookup once per handle; shared by the fill-pick and
+                // the per-group sort below so we never call features.find() inside a comparator.
+                const compareByArea = buildHitAreaComparator(handle.features.features);
+                // Fill promotion uses visible (clipped) fill geometry from the last
+                // tiling pass. Stroke hits take priority; otherwise the visible fill
+                // owner wins (smallest-area tiebreak if multiple remain).
+                const allFillHits = hits.filter(h => h.fill === true);
+                const candidateHits = strokeHits.length > 0 ? strokeHits : pickFillPromotionCandidates(allFillHits, compareByArea);
+                const groupKeyMap = featureToGroupKeyByHandleRef.current.get(handle.id) ?? new Map();
+                const hitsByGroup = new Map();
+                for (const hit of candidateHits) {
+                    const groupKey = groupKeyMap.get(hit.featureId);
+                    if (groupKey === undefined)
+                        continue;
+                    const existing = hitsByGroup.get(groupKey);
+                    if (existing === undefined) {
+                        hitsByGroup.set(groupKey, [hit]);
+                    }
+                    else {
+                        existing.push(hit);
+                    }
+                }
+                // When the cursor is over something, clear promotions for groups that
+                // have no hit in this settle — this resets groups the cursor has left.
+                // When the cursor is over nothing (totalCandidateHits === 0) we skip
+                // this so the last winner stays in front (sticky promotion).
+                if (totalCandidateHits > 0) {
+                    const handlePromotion = promotedByHandleRef.current.get(handle.id);
+                    if (handlePromotion !== undefined) {
+                        for (const [groupKey, promotedFeatureId] of [...handlePromotion.entries()]) {
+                            if (!hitsByGroup.has(groupKey))
+                                clearPromotion(handle.id, promotedFeatureId);
+                        }
+                    }
+                }
+                const featuresById = new Map();
+                for (const feature of handle.features.features) {
+                    if (feature.id !== undefined)
+                        featuresById.set(String(feature.id), feature);
+                }
+                for (const [, groupHits] of hitsByGroup) {
+                    const top = [...groupHits].sort(compareByArea)[0];
+                    if (top === undefined)
+                        continue;
+                    promoteFeature(handle.id, top.featureId);
+                    const topFeature = featuresById.get(top.featureId);
+                    const topArea = topFeature?.geometry !== null && topFeature?.geometry !== undefined ? geometryArea(topFeature.geometry) : 0;
+                    if (overallTop === undefined || topArea < overallTop.area) {
+                        overallTop = { handleId: handle.id, featureId: top.featureId, area: topArea };
+                    }
+                }
+            }
+            if (overallTop !== undefined) {
+                onSettledHoverRef.current?.(overallTop.handleId, overallTop.featureId);
+            }
+        };
+        const unsubscribe = api.on("pointermove", event => {
+            if (debounceTimerRef.current !== null) {
+                clearTimeout(debounceTimerRef.current);
+            }
+            const pos = event.position;
+            debounceTimerRef.current = setTimeout(() => {
+                debounceTimerRef.current = null;
+                handleSettle(pos);
+            }, SETTLE_DEBOUNCE_MS);
+        });
+        return () => {
+            unsubscribeMoveStart();
+            unsubscribeIdle();
+            unsubscribe();
+            if (debounceTimerRef.current !== null) {
+                clearTimeout(debounceTimerRef.current);
+                debounceTimerRef.current = null;
+            }
+            if (idleRecomputeTimerRef.current !== null) {
+                clearTimeout(idleRecomputeTimerRef.current);
+                idleRecomputeTimerRef.current = null;
+            }
+        };
+    }, [
+        api,
+        clearPromotion,
+        emitWithPromotion,
+        hasTilingHandles,
+        promoteFeature,
+        recompute,
+        scheduleIdleRestingRecompute,
+    ]);
+    // Clear on unmount.
+    react.useEffect(() => {
+        return () => {
+            onFillChangeRef.current(EMPTY_OVERRIDES);
+            onZIndexChangeRef.current(EMPTY_ZINDEX_OVERRIDES);
+        };
+    }, []);
+    const allShapeHandlesRef = react.useRef([]);
+    react.useEffect(() => {
+        allShapeHandlesRef.current = handles.filter((h) => h.layerType === "shapes");
+    });
+    const queryAt = react.useCallback((handleId, position) => {
+        const handle = allShapeHandlesRef.current.find(h => h.id === handleId);
+        if (handle === undefined)
+            return [];
+        const { zoom, tileSize } = viewportRef.current;
+        const strokeWidthFor = (featureId) => handle.featureStyles?.get(featureId)?.strokeWidth ?? DEFAULT_STROKE_WIDTH;
+        const handleFillOverrides = prevFillOverridesRef.current.get(handleId);
+        const suppressedIds = suppressedFillIdsByHandleRef.current?.get(handleId);
+        const visibleFillFor = handleFillOverrides === undefined && suppressedIds === undefined
+            ? undefined
+            : (featureId) => {
+                if (suppressedIds?.has(featureId) === true)
+                    return null;
+                return handleFillOverrides?.get(featureId);
+            };
+        return shapesUnderCursor(position, handle.features.features, {
+            zoom,
+            tileSize,
+            strokeWidthFor,
+            visibleFillFor,
+        });
+    }, []);
+    const setDecorationHoverActive = react.useCallback((active) => {
+        decorationHoverActiveRef.current = active;
+    }, []);
+    return react.useMemo(() => ({ queryAt, promoteFeature, clearPromotion, setDecorationHoverActive }), [queryAt, promoteFeature, clearPromotion, setDecorationHoverActive]);
+};
+
 const applyPortalZIndex = (container, zIndex) => {
     container.style.zIndex = String(zIndex);
 };
@@ -8956,14 +10146,60 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
     const layerPort = useLayerPort();
     const [decorationLayers, setDecorationLayers] = react.useState([]);
     const [viewportStyleOverrides, setViewportStyleOverrides] = react.useState(new Map());
+    const [fillGeometryOverrides, setFillGeometryOverrides] = react.useState(new Map());
+    const [zIndexOverrides, setZIndexOverrides] = react.useState(new Map());
+    const onSettledHover = react.useCallback((handleId, featureId) => {
+        // Fill tiling only fires on polygonal features — shapeType is always "polygon".
+        layers.hover({ type: "shape", id: featureId, handleId, shapeType: "polygon" });
+    }, [layers]);
+    const suppressedFillIdsByHandle = react.useMemo(() => {
+        const result = new Map();
+        for (const [handleId, featureStyles] of viewportStyleOverrides) {
+            const suppressed = new Set();
+            for (const [featureId, style] of featureStyles) {
+                if (isFillSuppressed(style))
+                    suppressed.add(featureId);
+            }
+            if (suppressed.size > 0)
+                result.set(handleId, suppressed);
+        }
+        return result;
+    }, [viewportStyleOverrides]);
+    const { queryAt, promoteFeature, setDecorationHoverActive } = useShapeFillTiling({
+        api,
+        handles: layers.handles,
+        onFillGeometriesChange: setFillGeometryOverrides,
+        onZIndexOverridesChange: setZIndexOverrides,
+        onSettledHover,
+        selectedFeatureId: layers.interaction.selectedEntity?.type === "shape" ? String(layers.interaction.selectedEntity.id) : null,
+        suppressedFillIdsByHandle,
+    });
+    const promoteFeatureRef = react.useRef(promoteFeature);
+    react.useEffect(() => {
+        promoteFeatureRef.current = promoteFeature;
+    }, [promoteFeature]);
+    const setDecorationHoverActiveRef = react.useRef(setDecorationHoverActive);
+    react.useEffect(() => {
+        setDecorationHoverActiveRef.current = setDecorationHoverActive;
+    }, [setDecorationHoverActive]);
     const adaptiveByLayer = useAdaptiveMarkerResolution(layers.handles, layers.interaction, api);
     const enrichedHandles = react.useMemo(() => {
         return layers.handles.map(handle => {
             if (handle.layerType === "shapes") {
-                const overrides = viewportStyleOverrides.get(handle.id);
-                if (overrides === undefined)
-                    return handle;
-                return { ...handle, featureStyles: overrides };
+                const styleOverrides = viewportStyleOverrides.get(handle.id);
+                const fillOverrides = fillGeometryOverrides.get(handle.id);
+                const zIndexOverridesForHandle = zIndexOverrides.get(handle.id);
+                const queryShapesAt = (position) => queryAt(handle.id, position);
+                if (styleOverrides === undefined && fillOverrides === undefined && zIndexOverridesForHandle === undefined) {
+                    return { ...handle, queryShapesAt };
+                }
+                return {
+                    ...handle,
+                    queryShapesAt,
+                    ...(styleOverrides !== undefined ? { featureStyles: styleOverrides } : {}),
+                    ...(fillOverrides !== undefined ? { featureFillGeometries: fillOverrides } : {}),
+                    ...(zIndexOverridesForHandle !== undefined ? { featureZIndexOverrides: zIndexOverridesForHandle } : {}),
+                };
             }
             if (handle.layerType !== "markers" || handle.markerRender.mode !== "adaptive")
                 return handle;
@@ -8972,7 +10208,7 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
                 return handle;
             return { ...handle, adaptiveResolution };
         });
-    }, [layers.handles, adaptiveByLayer, viewportStyleOverrides]);
+    }, [layers.handles, adaptiveByLayer, viewportStyleOverrides, fillGeometryOverrides, zIndexOverrides, queryAt]);
     const { renderedSourceIds, hasSourceReadiness, readyRevision } = useLayerHandleSync(layerPort, enrichedHandles, layers.interaction, decorationLayers);
     const hoveredEntityRef = react.useRef(layers.interaction.hoveredEntity);
     react.useEffect(() => {
@@ -9000,6 +10236,10 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
     });
     const coordinatedHover = react.useCallback((entity) => {
         setDomHoverActive(entity !== null);
+        setDecorationHoverActiveRef.current(entity !== null);
+        if (entity !== null && entity.type === "shape" && entity.handleId !== undefined) {
+            promoteFeatureRef.current(entity.handleId, entity.id);
+        }
         layers.hover(entity);
     }, [layers, setDomHoverActive]);
     const interactionMapStore = useShapeDecorations({