@trackunit/react-map 0.0.4-alpha-9d327375fc1.0

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

@@ -0,0 +1,27 @@
+import type { GeoJsonFeature } from "@trackunit/geo-json-utils";
+import type { ShapeLayerHandle } from "../../types";
+import { type ResolvedDecoration } from "../shapeDecorations";
+import { type EdgeInsets } from "./findBestEdgePosition";
+/**
+ * Compute per-edge insets from pre-resolved decorations.
+ *
+ * For each edge, the start inset is the maximum `radiusPx` of any
+ * decoration anchored at the start vertex, and the end inset is the
+ * maximum `radiusPx` at the end vertex. This tells the label system
+ * how much to inset from each corner to avoid overlapping decorations.
+ *
+ * Accepts already-resolved decorations so the caller (the unified hook)
+ * can resolve once and reuse the results for both rendering and insets.
+ *
+ * @param resolved - Decorations whose anchors have already been resolved to positions.
+ * @param edgeCount - Number of edges in the feature's geometry (as returned by `extractEdges`).
+ */
+export declare const computeEdgeInsetsFromResolved: (resolved: ReadonlyArray<ResolvedDecoration>, edgeCount: number) => ReadonlyArray<EdgeInsets> | undefined;
+/**
+ * Compute per-edge insets for a single feature based on its decorations.
+ *
+ * Convenience wrapper that resolves decoration anchors internally.
+ * Prefer `computeEdgeInsetsFromResolved` when decorations have already
+ * been resolved (e.g. in the unified hook) to avoid redundant resolution.
+ */
+export declare const computeEdgeInsetsForFeature: (feature: GeoJsonFeature, handle: ShapeLayerHandle) => ReadonlyArray<EdgeInsets> | undefined;

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

@@ -0,0 +1,36 @@
+import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { ResolvedDecoration } from "../shapeDecorations";
+/**
+ * Reserved pixel space at each end of an edge, computed from decorations
+ * that sit on the edge's start or end vertex.
+ */
+export type EdgeReservation = Readonly<{
+    /** Total pixel length of the edge. */
+    totalPx: number;
+    /** Available length after subtracting vertex decoration reservations from both ends. */
+    safePx: number;
+    /** Pixel inset from the start vertex (left end when the edge reads left-to-right). */
+    startInsetPx: number;
+    /** Pixel inset from the end vertex (right end when the edge reads left-to-right). */
+    endInsetPx: number;
+}>;
+/**
+ * Compute edge reservations for a list of edges given the resolved
+ * decorations for the same feature.
+ *
+ * For each edge `[startVertex, endVertex]`, the start inset is the maximum
+ * `radiusPx` of any decoration at the start vertex, and the end inset is the
+ * maximum `radiusPx` of any decoration at the end vertex. The safe length
+ * is `totalPx - startInset - endInset`, clamped to zero.
+ *
+ * @param edges - Consecutive vertex pairs forming edges (as returned by `extractEdges`).
+ * @param decorations - Resolved decorations for the same feature.
+ * @param zoom - Current map zoom level.
+ * @param tileSize - Tile size (256 for Google, 512 for Mapbox).
+ */
+export declare const computeEdgeReservations: (edges: ReadonlyArray<readonly [GeoJsonPosition, GeoJsonPosition]>, decorations: ReadonlyArray<ResolvedDecoration>, zoom: number, tileSize: number) => ReadonlyArray<EdgeReservation>;
+/**
+ * Look up the reservation for a specific edge. Returns a default reservation
+ * with zero insets if the edge index is out of range.
+ */
+export declare const getEdgeReservation: (reservations: ReadonlyArray<EdgeReservation>, edgeIndex: number) => EdgeReservation;

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

@@ -0,0 +1,247 @@
+import { type GeoJsonBbox, type GeoJsonFeatureCollection, type GeoJsonPosition } from "@trackunit/geo-json-utils";
+type ClippedSegment = readonly [number, number, number, number];
+/**
+ * - `"fits"` — label fits on the chosen edge.
+ * - `"clipped"` — placed for layout but hidden (edge too narrow for auto placement).
+ * - `"overflow"` — label is shown even when it extends past the edge (force placement).
+ */
+export type EdgeFitMode = "fits" | "clipped" | "overflow";
+export type EdgeIdentity = readonly [GeoJsonPosition, GeoJsonPosition];
+export type EdgeLabelAnchor = "left" | "center" | "right";
+export type EdgeLabelLayout = Readonly<{
+    type: "edge";
+    directionPx: readonly [number, number];
+    anchor: EdgeLabelAnchor;
+    outwardSide: "above" | "below";
+}> | Readonly<{
+    type: "point";
+}>;
+export type EdgePlacement = Readonly<{
+    position: GeoJsonPosition;
+    layout: EdgeLabelLayout;
+    fitMode: EdgeFitMode;
+    edgeIdentity: EdgeIdentity | null;
+    /** Pixel width available for the label between both-side insets. */
+    availableWidthPx: number;
+}>;
+/**
+ * Per-edge insets from decorations sitting on the edge's start/end vertices.
+ * Provided by the edge reservation system to avoid labels overlapping decorations.
+ */
+export type EdgeInsets = Readonly<{
+    startPx: number;
+    endPx: number;
+}>;
+/**
+ * Liang-Barsky line-segment clipping against an axis-aligned rectangle.
+ * Returns clipped endpoints [x0, y0, x1, y1] or null if the segment is entirely outside.
+ */
+export declare const clipSegmentToRect: (x0: number, y0: number, x1: number, y1: number, xMin: number, yMin: number, xMax: number, yMax: number) => ClippedSegment | null;
+export { extractEdges } from "@trackunit/geo-json-utils";
+export { computeGeometryCentroid } from "@trackunit/geo-json-utils";
+export declare const lngLatToWebMercatorPx: (lng: number, lat: number, zoom: number, tileSize?: number) => readonly [number, number];
+export declare const webMercatorPxToLngLat: (px: number, py: number, zoom: number, tileSize?: number) => readonly [number, number];
+/**
+ * Compute the screen-space angle (in degrees) of a line segment, accounting for
+ * Web Mercator distortion. Normalized to [-90, 90] so text reads left-to-right.
+ *
+ * In Web Mercator, 1 degree of latitude spans more pixels than 1 degree of longitude
+ * at latitudes away from the equator (by a factor of sec(lat)). The screen-space
+ * deltas are therefore:
+ *   dx_screen ∝ dlng
+ *   dy_screen ∝ dlat * sec(midLat)
+ */
+export declare const edgeScreenAngleDeg: (x0: number, y0: number, x1: number, y1: number, midLatDeg: number) => number;
+/**
+ * Compute the pixel length of a line segment at a given zoom level,
+ * accounting for Web Mercator latitude distortion.
+ *
+ * Web Mercator tile math: worldSize = 256 * 2^zoom pixels for 360 degrees of longitude.
+ * Latitude pixels scale by sec(lat).
+ */
+export declare const edgePixelLength: (x0: number, y0: number, x1: number, y1: number, zoom: number, midLatDeg: number, tileSize?: number) => number;
+/**
+ * Convert a pixel distance to latitude degrees at a given zoom level,
+ * accounting for Web Mercator latitude distortion.
+ */
+export declare const pixelsToLatDegrees: (pixels: number, zoom: number, latDeg: number, tileSize?: number) => number;
+/**
+ * Determine which side of an edge the geometry interior lies on, in screen space.
+ * Returns "above" if the label should extend above the edge (interior is below),
+ * or "below" if the label should extend below (interior is above).
+ *
+ * Uses the cross product to find which side the centroid is on, then computes
+ * the outward normal's y-component to determine the screen direction.
+ * In y-down screen coords: right normal of (dx, dy) = (-dy, dx).
+ */
+export declare const computeOutwardSide: (cx0: number, cy0: number, cx1: number, cy1: number, centroid: GeoJsonPosition, midLatDeg: number) => "above" | "below";
+export { extractFirstPointCoordinate } from "@trackunit/geo-json-utils";
+export { isPositionInsideRing as isPointInsideRing } from "@trackunit/geo-json-utils";
+/**
+ * Per-candidate information passed to a label placement resolver.
+ *
+ * All pixel coordinates are viewport-relative (origin = top-left of viewport).
+ * `outwardBbox` and `inwardBbox` are also viewport-relative bounding boxes for
+ * the rotated label rectangle when placed on the outward and inward side respectively.
+ */
+export type EdgeCandidateInfo = Readonly<{
+    edgeIdx: number;
+    edge: EdgeIdentity;
+    pxLen: number;
+    angleDeg: number;
+    availableWidthPx: number;
+    labelFits: boolean;
+    outwardSide: "above" | "below";
+    startInsetPx: number;
+    endInsetPx: number;
+    directionPx: readonly [number, number];
+    /** Viewport-relative pixel coordinate of the reading-direction start. */
+    readingStartPx: readonly [number, number];
+    /** Viewport-relative pixel coordinate of the reading-direction end. */
+    readingEndPx: readonly [number, number];
+    /** Viewport-relative bounding box when label is placed on the outward side. */
+    outwardBbox: Readonly<{
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    }>;
+    /** Viewport-relative bounding box when label is placed on the inward side. */
+    inwardBbox: Readonly<{
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    }>;
+}>;
+/**
+ * All information the resolver needs to choose a placement.
+ *
+ * `isForced` is true when this is the second-pass retry with `minPixelWidth: 0`
+ * — meaning no edge was wide enough for the label in the normal pass.
+ * The default resolver uses this to center the label (`anchorT: 0.5`) on forced
+ * placements. Custom resolvers can use it to adapt their strategy accordingly.
+ */
+export type EdgePlacementContext = Readonly<{
+    candidates: ReadonlyArray<EdgeCandidateInfo>;
+    viewportWidth: number;
+    viewportHeight: number;
+    labelPixelWidth: number;
+    labelAnchor: EdgeLabelAnchor;
+    previousEdgeIdentity?: EdgeIdentity;
+    isForced: boolean;
+    /**
+     * t ∈ [0, 1] along the reading direction of the candidate matching
+     * `previousEdgeIdentity`, corresponding to the geographic position of the
+     * last known anchor. Only set when `previousAnchorGeo` was provided to
+     * `findBestEdgePosition` and the previous edge is still in the candidate pool.
+     *
+     * The default resolver uses this to pin a left-anchored label no further
+     * left than it was on the previous frame ("don't slide back" behaviour).
+     */
+    previousAnchorClippedT?: number;
+    /**
+     * The `outwardSide` ("above" | "below") of the label on the previous frame.
+     * The default resolver uses this to avoid flipping the label to the other
+     * side of the line unless the current side no longer fits in the viewport.
+     */
+    previousLayoutSide?: "above" | "below";
+}>;
+/**
+ * The resolver's answer: which candidate to use and on which side.
+ *
+ * - `anchorT` (0–1 along the reading direction) sets the geographic position
+ *   on the edge where the label is pinned. Defaults to the position derived
+ *   from `labelAnchor` when omitted.
+ * - `anchor` overrides which part of the label element is pinned to that geo
+ *   position (left edge / center / right edge of the pill). Defaults to the
+ *   config `labelAnchor` when omitted. Pair with `anchorT` for visual centering
+ *   — e.g. `anchorT: 0.5, anchor: "center"` places the center of the pill at
+ *   the midpoint of the edge.
+ */
+export type EdgePlacementDecision = Readonly<{
+    edgeIdx: number;
+    side: "outward" | "inward";
+    anchorT?: number;
+    anchor?: EdgeLabelAnchor;
+}>;
+/**
+ * Callback signature for custom edge-label placement strategies.
+ * Return `null` to suppress the label entirely.
+ */
+export type EdgeLabelPlacementResolver = (context: EdgePlacementContext) => EdgePlacementDecision | null;
+/**
+ * Find the best position to place an edge label for shape features.
+ *
+ * Clips all edges against the viewport, optionally filters by screen angle
+ * (when `maxReadableAngleDeg` is provided) and pixel length (must be at least
+ * `minPixelWidth` at the current zoom), and returns the anchor position + angle of
+ * the best qualifying edge.
+ *
+ * Selection tiers (applied in order after viewport-inside preference):
+ *   0. Hysteresis — if `previousEdgeIdentity` is set and a candidate from that
+ *      edge still fits the label, stick with it to avoid visual jumps during panning.
+ *   1. Panning — when hysteresis fails (previous edge left viewport), score
+ *      candidates by blending normalized angle (|angle|/90) with normalized
+ *      proximity to the previous midpoint (dist/maxDist), weighted equally
+ *      (α = 0.5). Nearby candidates win unless much steeper.
+ *   2. Initial — when no previous edge exists, pick the least-steep
+ *      fitting edge (pure min |angleDeg|).
+ *   3. Longest fallback — if no edge fits the label, pick the longest.
+ *
+ * Both ends of the edge are inset so the label doesn't start or end right at
+ * a corner (minimum 6px each, or the edge's decoration reservation if larger).
+ * Both endpoint reservations (`startPx`/`endPx` from `edgeInsets`) are
+ * subtracted from the usable length: the anchor-side inset reserves space at
+ * the text origin, and the far-end inset reserves space at the opposite vertex.
+ *
+ * `fitMode` is determined by comparing usable length against `labelPixelWidth`:
+ * - `"fits"` — label fits within the edge minus both endpoint reservations
+ * - `"clipped"` — label doesn't fit on this edge
+ *
+ * When `labelPlacementResolver` is provided it receives the full
+ * `EdgePlacementContext` (all candidates with both-side bboxes in viewport-relative
+ * coordinates) and returns an `EdgePlacementDecision` (or `null` to suppress).
+ * When omitted, `defaultEdgeLabelPlacementResolver` is used.
+ *
+ * The `outwardSide` indicates which side of the edge is away from the shape
+ * interior, computed via centroid cross product.
+ */
+export type FindBestEdgePositionConfig = Readonly<{
+    features: GeoJsonFeatureCollection;
+    viewportBounds: Readonly<GeoJsonBbox>;
+    zoom: number;
+    minPixelWidth: number;
+    labelPixelWidth: number;
+    tileSize?: number;
+    maxReadableAngleDeg?: number;
+    previousEdgeIdentity?: EdgeIdentity;
+    /** Geographic position of the previous anchor — used to implement "don't slide back left" hysteresis. */
+    previousAnchorGeo?: GeoJsonPosition;
+    /**
+     * The layout side ("above" | "below") of the label on the previous frame.
+     * Used to prevent the label from flipping sides unless the current side
+     * no longer fits within the viewport.
+     */
+    previousLayoutSide?: "above" | "below";
+    edgeInsets?: ReadonlyArray<EdgeInsets>;
+    labelAnchor?: EdgeLabelAnchor;
+    labelPlacementResolver?: EdgeLabelPlacementResolver;
+    /** True when this is the forced retry pass (minPixelWidth was relaxed to 0). Passed to EdgePlacementContext. */
+    isForced?: boolean;
+}>;
+/**
+ * Default edge-label placement strategy.
+ *
+ * Builds a valid pool from candidates where at least one side (outward or
+ * inward) fits within the viewport. Applies the standard selection tiers
+ * (hysteresis → proximity blend → least-steep → longest fallback) to pick
+ * the best candidate, then chooses the outward side when it fits — falling
+ * back to the inward side otherwise.
+ *
+ * This replaces the previous anchor-nudging approach: instead of pushing the
+ * anchor along the edge to avoid horizontal overflow, it simply flips the label
+ * to the inward side of the edge, which naturally avoids the overflow.
+ */
+export declare const defaultEdgeLabelPlacementResolver: (context: EdgePlacementContext) => EdgePlacementDecision | null;
+export declare const findBestEdgePosition: ({ features, viewportBounds, zoom, minPixelWidth, labelPixelWidth, tileSize, maxReadableAngleDeg, previousEdgeIdentity, previousAnchorGeo, previousLayoutSide, edgeInsets, labelAnchor, labelPlacementResolver, isForced, }: FindBestEdgePositionConfig) => EdgePlacement | null;

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

@@ -0,0 +1,25 @@
+import type { GeoJsonGeometry, GeoJsonPosition } from "@trackunit/geo-json-utils";
+/**
+ * Describes a single part of a multi-geometry: its representative position
+ * (polygon corner / line joint / multipoint coordinate) and bounds.
+ */
+export type PartInfo = Readonly<{
+    position: GeoJsonPosition;
+    minLng: number;
+    maxLng: number;
+    minLat: number;
+    maxLat: number;
+}>;
+/**
+ * Decompose a multi-geometry into per-part info (position + bounds).
+ *
+ * Returns `null` for single geometries (Polygon, LineString, Point) or
+ * multi-geometries that contain only one part. Only returns a non-null
+ * array when the geometry genuinely has multiple parts.
+ *
+ * - MultiPolygon -> southwesternmost outer-ring vertex and bounds of each polygon
+ * - MultiLineString -> a joint vertex on each line (`floor(n/2)`; two-point lines: first endpoint)
+ * - MultiPoint -> the point itself with degenerate bounds
+ * - GeometryCollection -> flattens recursively
+ */
+export declare const extractMultiParts: (geometry: GeoJsonGeometry) => ReadonlyArray<PartInfo> | null;

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

@@ -0,0 +1,18 @@
+import type { GeoJsonBbox, GeoJsonGeometry, GeoJsonPosition } from "@trackunit/geo-json-utils";
+/**
+ * Find the best visible vertex for the `vertex-auto` anchor.
+ *
+ * Searches ALL parts of multi-geometry, filters to vertices inside the
+ * viewport, and returns the one closest to the viewport center.
+ * Returns null if no vertices are visible.
+ *
+ * For Point geometry, returns the single coordinate (regardless of viewport).
+ *
+ * When `previousPosition` is provided (hysteresis mode):
+ * - If the previous position is still inside the viewport, it is returned
+ *   unchanged — the label stays put during panning.
+ * - If the previous position left the viewport, the nearest visible vertex
+ *   to that position is chosen (not nearest to viewport center) so the
+ *   label migrates to the closest alternative.
+ */
+export declare const findBestVisibleVertex: (geometry: GeoJsonGeometry, viewportBounds: Readonly<GeoJsonBbox>, previousPosition?: GeoJsonPosition) => GeoJsonPosition | null;

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

@@ -0,0 +1,19 @@
+import type { GeoJsonFeature } from "@trackunit/geo-json-utils";
+import type { ShapeDecoration } from "./shapeDecorations";
+/**
+ * Generate multi-geometry "+" badge decorations for a feature.
+ *
+ * Returns one decoration per part of a multi-geometry (MultiPolygon,
+ * MultiLineString, MultiPoint). Each badge is placed at the part's
+ * representative position (from `extractMultiParts`) using a `"position"`
+ * anchor with the pre-resolved coordinate.
+ *
+ * For MultiPoint features a `pixelOffset` displaces the badge to the
+ * top-right edge of the point circle so it does not obscure the fill area.
+ *
+ * Returns an empty array for single-geometry features or multi-geometries
+ * with only one part.
+ *
+ * @internal
+ */
+export declare const buildMultiPartDecorations: (feature: GeoJsonFeature, strokeColor: string, pointRadius?: number, strokeWidth?: number) => ReadonlyArray<ShapeDecoration>;

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

@@ -0,0 +1,154 @@
+import type { Placement } from "@floating-ui/react";
+import type { GeoJsonGeometry, GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { DomPortalDescriptor, PixelOffset, ShapeEntity } from "@trackunit/react-map-adapter-shared";
+import type { RefCallback } from "react";
+import type { EdgeLabelAnchor, EdgeLabelPlacementResolver } from "./edge/findBestEdgePosition";
+import type { ResolveShapeLabel } from "./shapeLabelResolution";
+/**
+ * Which side of an edge a decoration extends toward.
+ *
+ * - `"outward"` / `"inward"` — resolved from polygon winding order. For LineStrings, falls back to `"above"`.
+ * - `"above"` / `"below"` — explicit screen-space direction.
+ *
+ * Default is `"outward"`.
+ */
+export type EdgeSide = "outward" | "inward" | "above" | "below";
+/**
+ * Where a decoration attaches to a shape's geometry. All variants use category
+ * prefixes (`vertex-*` / `edge-*`) except `position` which is universal.
+ */
+export type DecorationAnchor = 
+/** Explicit geographic coordinate. Works with any geometry type. */
+Readonly<{
+    type: "position";
+    position: GeoJsonPosition;
+}>
+/** Specific vertex by index in the outer coordinate ring.
+ * Returns null for empty geometries or out-of-bounds indices. */
+ | Readonly<{
+    type: "vertex-index";
+    vertexIndex: number;
+}>
+/** Extremal vertex in a cardinal direction (geographic bounding corner).
+ * Returns null for Point geometry. */
+ | Readonly<{
+    type: "vertex-corner";
+    corner: "sw" | "nw" | "ne" | "se";
+}>
+/** Viewport-aware automatic vertex selection. Picks the visible vertex
+ * closest to the viewport center across ALL parts of multi-geometry.
+ * Returns null if no vertices are visible. For Point: the coordinate.
+ * Resolved by the unified hook, not by `resolveDecorationPosition`. */
+ | Readonly<{
+    type: "vertex-auto";
+}>
+/** Midpoint of a specific edge. Optional `side` controls placement relative
+ * to the edge direction. Returns null for Point geometry or out-of-bounds edge. */
+ | Readonly<{
+    type: "edge-midpoint";
+    edgeIndex: number;
+    side?: EdgeSide;
+}>
+/** Parametric position (`t` in 0..1) along a specific edge. Optional `side`
+ * controls placement. Returns null for Point geometry or out-of-bounds edge. */
+ | Readonly<{
+    type: "edge-parametric";
+    edgeIndex: number;
+    t: number;
+    side?: EdgeSide;
+}>
+/** Viewport-aware automatic edge selection for label placement.
+ * Best visible edge for Polygon/LineString; above the coordinate for Point.
+ * Optional `resolveLabel` callback decides per-frame whether to render
+ * normally (`"auto"`), overflow a too-narrow edge (`"force"`), or suppress
+ * (`"hide"`) — see {@link ResolveShapeLabel}. When omitted, behaves as `"auto"`.
+ * `labelPlacementResolver` receives `context.isForced = true` on the retry
+ * pass so it can adapt anchor or side selection without a separate option.
+ * Resolved by the unified hook, not by `resolveDecorationPosition`. */
+ | Readonly<{
+    type: "edge-auto";
+    label: string;
+    resolveLabel?: ResolveShapeLabel;
+    labelAnchor?: EdgeLabelAnchor;
+    labelPlacementResolver?: EdgeLabelPlacementResolver;
+}>;
+/**
+ * Declarative descriptor for a visual adornment attached to a shape feature.
+ *
+ * The decoration system resolves the anchor to a geographic position, manages
+ * viewport gating and marker source lifecycle, and tracks the pixel space
+ * each decoration reserves (so edge labels can compute safe insets).
+ */
+export type ShapeDecoration = Readonly<{
+    /** Stable identifier (unique within the feature's decoration list). */
+    id: string;
+    /** Where this decoration attaches to the geometry. */
+    anchor: DecorationAnchor;
+    /** Pixel radius this decoration occupies — used for edge-reservation calculations. */
+    radiusPx: number;
+    /** Additional pixel displacement from the resolved anchor position (screen coordinates). */
+    pixelOffset?: PixelOffset;
+    /** DOM render function passed to the synthetic marker source. */
+    render: DomPortalDescriptor["renderFn"];
+    /**
+     * Properties passed through as GeoJSON feature properties to the render function.
+     * The render function receives these as the `item` argument via portal descriptors.
+     */
+    sourceProperties?: Readonly<Record<string, unknown>>;
+    /** Whether to hide the decoration when its position falls outside the viewport. Default: true. */
+    viewportClip?: boolean;
+    /**
+     * Enable entity hover/select interaction. When true, the system wraps the
+     * rendered output with an interactive button providing cursor, keyboard a11y,
+     * and focus ring. Default: false.
+     */
+    interactive?: boolean;
+    /**
+     * Supplementary click handler called after entity selection.
+     * Only invoked when `interactive` is true (or when the unified hook
+     * determines that interaction is enabled for this decoration).
+     */
+    onClick?: (entity: ShapeEntity) => void;
+    /**
+     * Supplementary hover handler called after entity hover state changes.
+     * Receives the entity on hover-enter, null on hover-leave.
+     */
+    onHover?: (entity: ShapeEntity | null) => void;
+    /**
+     * When present, the edge-label portal container element is forwarded to
+     * this ref callback so a panel (e.g. `usePanel`) can anchor to it.
+     * Only active for `edge-auto` decorations.
+     */
+    panelAnchorRef?: RefCallback<HTMLElement>;
+    /**
+     * Called with the outward Floating UI `Placement` when an `edge-auto`
+     * decoration is placed. Lets the panel's `usePanel` start from the correct
+     * side so Floating UI's flip middleware only changes sides when necessary.
+     *
+     * Mapping: `outwardSide "above"` → `"top"`, `"below"` → `"bottom"`.
+     * Point-geometry labels emit no call (no shape-edge direction to infer).
+     */
+    onEdgePlacement?: (placement: Placement) => void;
+}>;
+/**
+ * A decoration whose anchor has been resolved to a concrete geographic position.
+ */
+export type ResolvedDecoration = Readonly<{
+    decoration: ShapeDecoration;
+    position: GeoJsonPosition;
+    /** Index of the vertex the decoration sits on (if vertex/corner anchor), or null for edge anchors. */
+    vertexIndex: number | null;
+    /** Index of the edge the decoration sits on (if edge anchor), or null for vertex anchors. */
+    edgeIndex: number | null;
+    /** Start and end coordinates of the resolved edge (edge-* anchors only). Null for vertex/position anchors. */
+    edgeEndpoints: Readonly<{
+        start: GeoJsonPosition;
+        end: GeoJsonPosition;
+    }> | null;
+}>;
+/**
+ * Resolve a `DecorationAnchor` to a geographic position given the geometry's
+ * coordinate ring. Returns null if the anchor references an out-of-bounds
+ * index or the geometry has no coordinates.
+ */
+export declare const resolveDecorationPosition: (anchor: DecorationAnchor, geometry: GeoJsonGeometry) => Omit<ResolvedDecoration, "decoration"> | null;

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

@@ -0,0 +1,25 @@
+import type { GeoJsonFeatureCollection, GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { MapTheme } from "../../core/types";
+import type { EdgeFitMode, EdgeLabelLayout } from "./edge/findBestEdgePosition";
+export declare const EDGE_LABEL_SUFFIX = "__edge-label";
+export declare const MULTI_BADGE_SUFFIX = "__multi-badge";
+/** Serializable props for DOM-rendered shape edge labels (mirrors `ShapeEdgeLabel`). */
+export type ShapeEdgeLabelFeaturePayload = Readonly<{
+    text: string;
+    color: string;
+    hoveredColor?: string;
+    selectedColor?: string;
+    theme: MapTheme;
+    layout: EdgeLabelLayout;
+    fitMode: EdgeFitMode;
+    availableWidthPx: number;
+    hidden?: boolean;
+    handleId: string;
+    shapeType: string;
+    featureId: string;
+}>;
+export declare const buildEdgeLabelFeatureCollection: (stableId: string, position: GeoJsonPosition, payload: ShapeEdgeLabelFeaturePayload) => GeoJsonFeatureCollection;
+export type MultiBadgeFeaturePayload = Readonly<{
+    strokeColor: string;
+}>;
+export declare const buildMultiBadgeFeatureCollection: (stableId: string, position: GeoJsonPosition, payload: MultiBadgeFeaturePayload) => GeoJsonFeatureCollection;

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

@@ -0,0 +1,42 @@
+import type { GeoJsonFeature } from "@trackunit/geo-json-utils";
+import type { ResolveShapeLabel, ShapeLabelResolution, ShapeLabelResolutionContext } from "./shapeLabelResolution";
+/**
+ * The subset of `ShapeLabelResolutionContext` that governs the
+ * annotation/edge-label decision. Kept minimal so the policy doesn't
+ * depend on viewport-density or geometry fields it doesn't use.
+ */
+export type AnnotationContext = Readonly<{
+    /** True when the viewport is fully contained inside the shape (no edges visible). */
+    isViewportInsideShape: boolean;
+    /** True when the feature is the currently selected entity. */
+    isSelected: boolean;
+    /** True when the feature is the currently hovered entity. */
+    isHovered: boolean;
+}>;
+/**
+ * Couples the edge-label resolution function with the annotation opt-in
+ * predicate so the two cannot drift apart.
+ *
+ * `resolveLabel` must return `"hide"` whenever `shouldAnnotate` returns
+ * `true` for the same feature — enforced structurally by `createShapeLabelPolicy`.
+ *
+ * See ADR-0017 for rationale.
+ */
+export type ShapeLabelPolicy = Readonly<{
+    resolveLabel: ResolveShapeLabel;
+    shouldAnnotate: (feature: GeoJsonFeature, ctx: AnnotationContext) => boolean;
+}>;
+/**
+ * Factory that creates a `ShapeLabelPolicy` where `resolveLabel` and
+ * `shouldAnnotate` are structurally coupled: when `annotateWhen` returns
+ * `true` for a feature, `resolveLabel` automatically returns `"hide"` so
+ * the edge label is suppressed and the annotation takes over.
+ *
+ * @param opts.annotateWhen - Predicate; returns true when the annotation
+ *   fallback should render instead of the edge label.
+ * @param opts.resolve - Edge-label resolution used when `annotateWhen` is false.
+ */
+export declare const createShapeLabelPolicy: (opts: {
+    readonly annotateWhen: (feature: GeoJsonFeature, ctx: AnnotationContext) => boolean;
+    readonly resolve: (feature: GeoJsonFeature, ctx: ShapeLabelResolutionContext) => ShapeLabelResolution;
+}) => ShapeLabelPolicy;

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

@@ -0,0 +1,45 @@
+import type { GeoJsonFeature, GeoJsonGeometry } from "@trackunit/geo-json-utils";
+/**
+ * Intent returned by a `resolveLabel` callback on an `edge-auto` anchor.
+ *
+ * - `"auto"` — run placement normally; hide if no qualifying edge is found.
+ * - `"force"` — place on the best available edge even if the label overflows
+ *   its measured width. Still hides if the feature is entirely off-screen.
+ * - `"hide"` — suppress unconditionally.
+ */
+export type ShapeLabelResolution = "auto" | "force" | "hide";
+/**
+ * Per-feature, per-frame context passed to `resolveLabel`. Lets the consumer
+ * decide whether a shape's edge label should render, taking into account
+ * zoom, viewport density, geometry, and interaction state.
+ *
+ * Deliberate parallel to the `resolveMode(item, ctx)` callback used by the
+ * adaptive marker render mode (see ADR-0008 / ADR-0016).
+ */
+export type ShapeLabelResolutionContext = Readonly<{
+    /** Current map zoom level. */
+    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. */
+    overlappingShapesCount: number;
+    /** GeoJSON geometry type of the feature. */
+    geometryType: GeoJsonGeometry["type"];
+    /** Width of the feature's bounding box in screen pixels at the current zoom. */
+    bboxPixelWidth: number;
+    /** Height of the feature's bounding box in screen pixels at the current zoom. */
+    bboxPixelHeight: number;
+    /** True when the viewport is fully contained inside the feature (no edges visible). */
+    isViewportInsideShape: boolean;
+    /** Number of parts in multi-geometries (1 for single geometries). */
+    partCount: number;
+    /** True when the feature is the currently selected entity. */
+    isSelected: boolean;
+    /** True when the feature is the currently hovered entity. */
+    isHovered: boolean;
+}>;
+/**
+ * Callback signature for `edge-auto` `resolveLabel`. Receives the feature and
+ * a snapshot of the resolution context; returns the desired render intent.
+ */
+export type ResolveShapeLabel = (feature: GeoJsonFeature, ctx: ShapeLabelResolutionContext) => ShapeLabelResolution;

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

@@ -0,0 +1,16 @@
+import type { DomPortalDescriptor } from "@trackunit/react-map-adapter-shared";
+/**
+ * Stable DOM `renderFn` for synthetic edge-label markers — pure rendering only.
+ * Reads visual props from GeoJSON `properties`. Interaction (select/hover) is
+ * handled externally by the `InteractiveDecoration` wrapper in Layers.
+ *
+ * The effective background color follows `selected > hovered > base` priority,
+ * matching the adapter paint expression order for stroke colors.
+ */
+export declare const shapeEdgeLabelPortalRender: DomPortalDescriptor["renderFn"];
+/**
+ * Stable DOM `renderFn` for multi-geometry "+" badges on the map.
+ *
+ * Follows the same `selected > hovered > base` color priority as edge labels.
+ */
+export declare const multiBadgePortalRender: DomPortalDescriptor["renderFn"];