@trackunit/react-map 0.1.3 → 0.1.5

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "2.1.22",
-    "@trackunit/css-class-variance-utilities": "1.13.29",
-    "@trackunit/react-form-components": "2.1.23",
-    "@trackunit/react-core-hooks": "1.17.36",
-    "@trackunit/geo-json-utils": "1.14.30",
-    "@trackunit/i18n-library-translation": "2.0.24",
-    "@trackunit/react-modal": "2.1.24",
+    "@trackunit/react-components": "2.1.24",
+    "@trackunit/css-class-variance-utilities": "1.13.30",
+    "@trackunit/react-form-components": "2.1.25",
+    "@trackunit/react-core-hooks": "1.17.38",
+    "@trackunit/geo-json-utils": "1.14.32",
+    "@trackunit/i18n-library-translation": "2.0.26",
+    "@trackunit/react-modal": "2.1.26",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.9",
-    "@trackunit/ui-design-tokens": "1.13.29",
+    "@trackunit/react-map-adapter-shared": "0.0.11",
+    "@trackunit/ui-design-tokens": "1.13.30",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.39.10",
     "tailwind-merge": "^2.0.0",

package/src/index.d.ts

@@ -22,7 +22,7 @@ export type { ControlMiddleware, MiddlewareContext } from "./controls/renderingR
 export type { CategoryMetadata } from "./controls/collapseControls";
 export type { ClusterEntity, Entity, MapInteractionState, MarkerEntity, RouteEntity, ShapeEntity, ShapeType, } from "@trackunit/react-map-adapter-shared";
 export { geometryTypeToShapeType, INITIAL_INTERACTION_STATE } from "@trackunit/react-map-adapter-shared";
-export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterInfo, ClusterRenderState, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, FitParticipation, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./layers/types";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterInfo, ClusterRenderState, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, FitParticipation, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeOverlapConfig, ShapeStyle, ShapeStyleOverrides, ShapesUnderCursorHit, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./layers/types";
 export { computeMarkerDomPortalZIndex } from "./layers/types";
 export { ANCHOR_SELECTOR, HIT_SURFACE_SELECTOR } from "@trackunit/react-map-adapter-shared";
 export { ClusterMarker, type ClusterMarkerProps, type ClusterMarkerStickInput, type ClusterSegment, } from "./clusters/ClusterMarker";
@@ -46,6 +46,7 @@ export { type AutoPanContext, type AutoPanResult } from "./panel/utils/autoPan";
 export type { DecorationAnchor, EdgeSide, ShapeDecoration } from "./layers/useShapes/shapeDecorations";
 export { type AnnotationContext, type ShapeLabelPolicy } from "./layers/useShapes/shapeLabelPolicy";
 export type { ResolveShapeLabel, ShapeLabelResolution, ShapeLabelResolutionContext, } from "./layers/useShapes/shapeLabelResolution";
+export { type ContendedShape, type ResolveShapeStackOrder, type ShapeStackContext, } from "./layers/useShapes/shapeStackOrder";
 export { useImageOverlay, type UseImageOverlayOptions, type UseImageOverlayReturn, } from "./layers/image-overlay/useImageOverlay";
 export { buildExpandedIds, useExpandedIds, type MapFocus, type MapFocusTier, type MapFocusTierDisplay, } from "./layers/mapFocus";
 export { useRoute, type UseRouteOptions, type UseRouteReturn } from "./layers/routes/useRoute";

package/src/layers/types.d.ts

@@ -1,8 +1,11 @@
-import type { GeoJsonBbox, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { GeoJsonBbox, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, GeoJsonPosition } from "@trackunit/geo-json-utils";
 import type { AdaptiveMarkerResolution, ClusterConfig, ClusterRenderConfig, RenderConfig, RouteStyle, ShapeInteractiveMode, ShapeStyle } from "@trackunit/react-map-adapter-shared";
 import type { CategoryKey, ControlConfig } from "../controls/types";
 import type { ShapeDecoration } from "./useShapes/shapeDecorations";
+import type { ShapesUnderCursorHit } from "./useShapes/shapeFillTiling";
 import type { ShapeLabelResolutionContext } from "./useShapes/shapeLabelResolution";
+import type { ResolveShapeStackOrder } from "./useShapes/shapeStackOrder";
+export type { ShapesUnderCursorHit };
 export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
 export { computeMarkerDomPortalZIndex } from "@trackunit/react-map-adapter-shared";
 /**
@@ -13,6 +16,22 @@ export { computeMarkerDomPortalZIndex } from "@trackunit/react-map-adapter-share
  * - `"none"` — never participates in any fit operation.
  */
 export type FitParticipation = "all" | "initial" | "none";
+/**
+ * Opt-in fill-tiling configuration for a shape layer (ADR-0021).
+ *
+ * When set, overlapping polygon fills are clipped so every pixel is painted by
+ * exactly one feature (no compounded translucency). Strokes always stay full.
+ * Ownership of shared regions is decided by `resolveStackOrder`, biased toward
+ * the feature the cursor is most inside.
+ *
+ * Orthogonal to `interactive`: this controls the *visual* tiling only and never
+ * implies hit-testing behaviour.
+ */
+export type ShapeOverlapConfig = Readonly<{
+    mode: "tile";
+    /** Swappable ranking policy. Defaults to `defaultShapeStackOrder`. */
+    resolveStackOrder?: ResolveShapeStackOrder;
+}>;
 /**
  * Metadata common to all layer types.
  * Every layer hook returns an object extending this shape.
@@ -93,12 +112,52 @@ export interface ShapeLayerHandle extends LayerMeta {
     readonly featureStyles?: ReadonlyMap<string, ShapeStyle>;
     /** Which parts of the shape respond to interaction */
     readonly interactive: ShapeInteractiveMode;
+    /**
+     * Fill-tiling configuration. When present (`mode: "tile"`), overlapping fills
+     * are clipped and ranked. Absent = legacy compounding fills. Orthogonal to
+     * `interactive`.
+     */
+    readonly overlap?: ShapeOverlapConfig;
+    /**
+     * Per-feature clipped fill geometry keyed by `String(feature.id)`, filled by
+     * `<Layers>` for layers with `overlap.mode === "tile"`. Strokes keep the full
+     * geometry; only the fill consumes this clipped geometry.
+     */
+    readonly featureFillGeometries?: ReadonlyMap<string, GeoJsonGeometry>;
+    /**
+     * Per-feature z-index override for fill rendering, filled by `<Layers>` for
+     * layers with `overlap.mode === "tile"` (ADR-0021 Path B). Higher value = visually
+     * on top. Only features in an overlap group receive an entry; the adapter uses
+     * the feature's default z-index for absent entries. The hook keeps resting values
+     * stable across hovers; only the promoted feature's value is boosted on hover.
+     */
+    readonly featureZIndexOverrides?: ReadonlyMap<string, number>;
     /**
      * Returns all decorations for a feature, including auto-generated ones
      * (e.g. multi-geometry "+" badges). Merging of custom and auto decorations
      * is handled by `useShapes` at construction time.
      */
     readonly getDecorations: (feature: GeoJsonFeature) => ReadonlyArray<ShapeDecoration>;
+    /**
+     * Geometric hit-test at the given map position. Returns all features whose
+     * fill or stroke region contains `position`, with fill/stroke flags and
+     * distance-to-boundary for tiebreaks.
+     *
+     * Injected by `<Layers>` with live viewport context (zoom + tile-size).
+     * `undefined` when the handle is used outside `<Layers>` (e.g. in unit tests).
+     */
+    readonly queryShapesAt?: (position: GeoJsonPosition) => ReadonlyArray<ShapesUnderCursorHit>;
+    /**
+     * Called by `<Layers>` after the pointer settle debounce fires and the
+     * stroke hit-test completes for this layer. Receives all fill + stroke hits
+     * (sorted by feature id). Wired from `UseShapesOptions.onShapesUnderCursor`;
+     * always present but is a no-op when that option is not provided.
+     *
+     * Only fires for layers with `overlap: { mode: "tile" }`.
+     */
+    readonly onShapesUnderCursor?: (hits: ReadonlyArray<ShapesUnderCursorHit>, ctx: Readonly<{
+        position: GeoJsonPosition;
+    }>) => void;
 }
 /**
  * Route layer handle -- returned by `useRoute`.

package/src/layers/useShapes/InteractiveDecoration.d.ts

@@ -17,6 +17,9 @@ type InteractiveDecorationProps = Readonly<{
  * 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
  */
 export declare const InteractiveDecoration: ({ entity, select, hover, onClick, onDblClick, onHover, children, }: InteractiveDecorationProps) => import("react/jsx-runtime").JSX.Element;

package/src/layers/useShapes/shapeFillTiling.d.ts

@@ -0,0 +1,114 @@
+import { type GeoJsonBbox, type GeoJsonFeature, type GeoJsonGeometry, type GeoJsonMultiPolygon, type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { ShapeStyle } from "@trackunit/react-map-adapter-shared";
+import type { ResolveShapeStackOrder } from "./shapeStackOrder";
+/**
+ * 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). */
+export declare const EMPTY_FILL: GeoJsonMultiPolygon;
+/**
+ * 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).
+ */
+export declare const isFillSuppressed: (style: ShapeStyle | undefined) => boolean;
+/** Per-feature visible fill lookup for hit-testing (clipped geometry from tiling). */
+export type VisibleFillLookup = (featureId: string) => GeoJsonGeometry | null | undefined;
+export type FillTilingInput = Readonly<{
+    features: ReadonlyArray<GeoJsonFeature>;
+    /** Only features whose bbox intersects this are considered. */
+    viewportBounds: GeoJsonBbox;
+    resolveStackOrder: ResolveShapeStackOrder;
+    zoom: number;
+    /**
+     * Feature id that is currently selected. Selection forces the feature to the
+     * top of its overlap group, overriding resting order. Takes highest priority.
+     */
+    selectedFeatureId?: string | null;
+    /**
+     * Feature ids whose fill is suppressed (`fillOpacity === 0`). Suppressed
+     * features are excluded from the tiling stack (no overlap group, no clip
+     * of neighbours) and receive `EMPTY_FILL` when their bbox is in the
+     * viewport. They get no `featureToGroupKey` entry so promotion is a no-op.
+     */
+    suppressedFeatureIds?: ReadonlySet<string>;
+}>;
+export type FillTilingResult = Readonly<{
+    /** Feature id → clipped fill geometry. Only clipped/covered features appear. */
+    fillGeometries: ReadonlyMap<string, GeoJsonGeometry>;
+    /**
+     * Feature id → group key. Lets the hook look up which group a stroke-hover
+     * hit belongs to so it can set the promotion overlay on the next hover.
+     */
+    featureToGroupKey: ReadonlyMap<string, string>;
+    /**
+     * Resting z-index per feature in each overlap group (rank 0 = highest value =
+     * visually on top). Only features that belong to an overlap group are included.
+     * Used by Path B promotion: the hook keeps these stable across hover events and
+     * only overrides the promoted feature's value to raise it above its peers.
+     */
+    featureZIndex: ReadonlyMap<string, number>;
+}>;
+/**
+ * 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.
+ */
+export declare const geometryArea: (geometry: GeoJsonGeometry) => number;
+/** Geographic degrees spanned by one screen pixel at a given zoom and tile size. */
+export declare const degreesPerPixel: (zoom: number, tileSize: number) => number;
+/** A single hit-test result from `shapesUnderCursor`. */
+export type ShapesUnderCursorHit = Readonly<{
+    featureId: string;
+    /** True when the position is inside the polygon fill (holes respected). */
+    fill: boolean;
+    /** True when the position is within half the rendered stroke width of any boundary ring. */
+    stroke: boolean;
+    /**
+     * Minimum distance from `position` to the nearest boundary segment, in geographic
+     * degrees. `null` when the geometry could not be parsed. Used by callers for
+     * tiebreaks (e.g. "top stroke hit = smallest area").
+     */
+    distanceToBoundary: number | null;
+}>;
+/**
+ * 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.
+ */
+export declare const shapesUnderCursor: (position: GeoJsonPosition, features: ReadonlyArray<GeoJsonFeature>, options: Readonly<{
+    zoom: number;
+    tileSize: number;
+    strokeWidthFor: (featureId: string) => number;
+    /**
+     * Optional per-feature visible fill geometry (from fill tiling). Absent entry
+     * = full geometry; null / empty MultiPolygon = no visible fill.
+     */
+    visibleFillFor?: VisibleFillLookup;
+}>) => Array<ShapesUnderCursorHit>;
+/**
+ * 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.
+ */
+export declare const computePromotionGroupFills: (members: ReadonlyArray<GeoJsonFeature>, winnerId: string, restingPeerFills?: ReadonlyMap<string, GeoJsonGeometry>) => ReadonlyMap<string, GeoJsonGeometry>;
+export declare const computeFillTiling: (input: FillTilingInput) => FillTilingResult;

package/src/layers/useShapes/shapeLabelResolution.d.ts

@@ -21,7 +21,7 @@ export type ShapeLabelResolutionContext = Readonly<{
     zoom: number;
     /** Number of features from the same layer that intersect the viewport. */
     shapesInViewport: number;
-    /** Number of other in-viewport features whose bbox intersects this feature's bbox. */
+    /** Number of other in-viewport features whose **geometry shares area** with this feature's polygon (bbox prefilter, then polygon intersection for Polygon/MultiPolygon geometries; bbox-only for Point/Line types). Fully contained inner polygons are not counted — their fill does not obscure the map below. */
     overlappingShapesCount: number;
     /** GeoJSON geometry type of the feature. */
     geometryType: GeoJsonGeometry["type"];

package/src/layers/useShapes/shapeStackOrder.d.ts

@@ -0,0 +1,39 @@
+import type { GeoJsonFeature } from "@trackunit/geo-json-utils";
+/**
+ * Precomputed geometric facts about a single contended shape — a feature whose
+ * fill overlaps at least one other feature in the same layer. The library
+ * computes these facts; the resolver only orders them.
+ */
+export type ContendedShape = Readonly<{
+    /** The contended feature. Its `id` (stringified) is what the resolver returns. */
+    feature: GeoJsonFeature;
+    /** Planar area of the feature's fill, used as the stable tiebreak. */
+    area: number;
+    /** IDs of other contended shapes that fully contain this one. */
+    containedIn: ReadonlyArray<string>;
+}>;
+/**
+ * Context for a single resolve pass.
+ */
+export type ShapeStackContext = Readonly<{
+    /** Current map zoom level. */
+    zoom: number;
+}>;
+/**
+ * Decides fill ownership for a set of overlapping shapes. Returns the contended
+ * feature IDs ordered **top-first** — the first ID owns shared pixels, later
+ * IDs are clipped against the winners ahead of them.
+ *
+ * Pure: same inputs must yield the same ordering. Swappable per-layer via the
+ * `overlap.resolveStackOrder` option on `useShapes`.
+ */
+export type ResolveShapeStackOrder = (contended: ReadonlyArray<ContendedShape>, ctx: ShapeStackContext) => ReadonlyArray<string>;
+/**
+ * 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.
+ */
+export declare const defaultShapeStackOrder: ResolveShapeStackOrder;

package/src/layers/useShapes/useManualDblClick.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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
+ */
+export declare const useManualDblClick: <TArg>(onClick: ((arg: TArg) => void) | undefined, onDblClick: ((arg: TArg) => void) | undefined) => ((arg: TArg) => void);

package/src/layers/useShapes/useShapeFillTiling.d.ts

@@ -0,0 +1,89 @@
+import type { GeoJsonGeometry, GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { MapApi } from "../../core/types";
+import type { LayerHandle, ShapesUnderCursorHit } from "../types";
+/**
+ * Per-handle, per-feature clipped fill geometries (ADR-0021), keyed
+ * `handleId → (featureId → geometry)`. Mirrors the style-overrides channel in
+ * `useShapeDecorations`.
+ */
+export type FillGeometryOverrides = ReadonlyMap<string, ReadonlyMap<string, GeoJsonGeometry>>;
+/**
+ * Per-handle, per-feature z-index overrides for fill promotion (ADR-0021 Path B),
+ * keyed `handleId → (featureId → zIndex)`. Higher value = visually on top.
+ * Only features in an overlap group receive an entry.
+ */
+export type ZIndexOverrides = ReadonlyMap<string, ReadonlyMap<string, number>>;
+type UseShapeFillTilingConfig = Readonly<{
+    api: MapApi | undefined;
+    handles: ReadonlyArray<LayerHandle>;
+    onFillGeometriesChange: (overrides: FillGeometryOverrides) => void;
+    onZIndexOverridesChange: (overrides: ZIndexOverrides) => void;
+    /**
+     * Called once per pointer-settle with the overall top hit (smallest area
+     * across all handles/groups). Fires only when at least one candidate hit
+     * exists and decoration hover is not active.
+     */
+    onSettledHover?: (handleId: string, featureId: string) => void;
+    /**
+     * Currently selected feature id. The matching feature is forced to the front
+     * of its overlap group, overriding resting order.
+     */
+    selectedFeatureId?: string | null;
+    /**
+     * Per-handle set of feature ids whose fill is suppressed (`fillOpacity === 0`
+     * on the resolved context-aware style). Suppressed features are excluded from
+     * tiling stack computation and return no fill hit during settle / queryAt.
+     * Derived from `viewportStyleOverrides` in `<Layers>` via `isFillSuppressed`.
+     */
+    suppressedFillIdsByHandle?: ReadonlyMap<string, ReadonlySet<string>>;
+}>;
+/** Return type of `useShapeFillTiling`. */
+export type UseShapeFillTilingReturn = Readonly<{
+    /**
+     * Imperative hit-test for a given handle and position. Uses the current
+     * viewport snapshot captured by the last render. Returns an empty array
+     * when the handle id is unknown or has no polygonal features.
+     */
+    queryAt: (handleId: string, position: GeoJsonPosition) => ReadonlyArray<ShapesUnderCursorHit>;
+    /**
+     * Promote a feature to the front of its overlap group (sticky until the next
+     * hover or selection). Used when the pointer is over a shape decoration
+     * (e.g. edge label) that is not on the fill/stroke geometry — same
+     * promotion channel as stroke/fill settle promotion.
+     */
+    promoteFeature: (handleId: string, featureId: string) => void;
+    /**
+     * Symmetric counterpart to `promoteFeature`. Clears the promotion for
+     * `featureId` in its overlap group only when it is the current group winner;
+     * no-op otherwise.
+     */
+    clearPromotion: (handleId: string, featureId: string) => void;
+    /**
+     * Suppress pointer-settle fill promotion while a shape decoration (edge label,
+     * etc.) is hovered — the cursor may sit over another polygon's fill visually.
+     */
+    setDecorationHoverActive: (active: boolean) => void;
+}>;
+/**
+ * `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
+ */
+export declare const useShapeFillTiling: ({ api, handles, onFillGeometriesChange, onZIndexOverridesChange, onSettledHover, selectedFeatureId, suppressedFillIdsByHandle, }: UseShapeFillTilingConfig) => UseShapeFillTilingReturn;
+export {};

package/src/layers/useShapes/useShapes.d.ts

@@ -1,6 +1,6 @@
-import { type GeoJsonFeature, type GeoJsonFeatureCollection } from "@trackunit/geo-json-utils";
+import { type GeoJsonFeature, type GeoJsonFeatureCollection, type GeoJsonPosition } from "@trackunit/geo-json-utils";
 import type { CategoryKey, ControlConfig } from "../../controls/types";
-import type { FitParticipation, ShapeInteractiveMode, ShapeLayerHandle, ShapeStyle } from "../types";
+import type { FitParticipation, ShapeInteractiveMode, ShapeLayerHandle, ShapeOverlapConfig, ShapeStyle, ShapesUnderCursorHit } from "../types";
 import type { ShapeDecoration } from "./shapeDecorations";
 import type { ShapeLabelResolutionContext } from "./shapeLabelResolution";
 export type UseShapesOptions = Readonly<{
@@ -14,6 +14,13 @@ export type UseShapesOptions = Readonly<{
     resolveStyle: (feature: GeoJsonFeature, ctx?: ShapeLabelResolutionContext) => ShapeStyle;
     /** Which parts of the shape respond to interaction. Default: `"stroke"` */
     interactive?: ShapeInteractiveMode;
+    /**
+     * Opt-in fill tiling for overlapping polygons (ADR-0021). When set to
+     * `{ mode: "tile" }`, overlapping fills are clipped so every pixel is painted
+     * by exactly one feature and ownership follows the cursor. Strokes stay full.
+     * Orthogonal to `interactive` — neither implies the other.
+     */
+    overlap?: ShapeOverlapConfig;
     /**
      * Controls to contribute to the map UI, keyed by semantic area.
      * Omit entirely (or omit a key) to contribute nothing to that area.
@@ -31,6 +38,17 @@ export type UseShapesOptions = Readonly<{
     loading?: boolean;
     /** Controls whether this layer's bounds are included in fit-to-content operations. Default: `"all"` */
     fitParticipation?: FitParticipation;
+    /**
+     * Called by `<Layers>` after the pointer settle debounce fires and the
+     * stroke hit-test completes for this layer. Receives the full hit list
+     * (fill + stroke flags) sorted by feature id. Useful for custom
+     * hover-promotion, tooltips, or analytics.
+     *
+     * Only fires for layers with `overlap: { mode: "tile" }`.
+     */
+    onShapesUnderCursor?: (hits: ReadonlyArray<ShapesUnderCursorHit>, ctx: Readonly<{
+        position: GeoJsonPosition;
+    }>) => void;
 }>;
 export type UseShapesReturn = ShapeLayerHandle;
 /**