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

package/index.esm.js

@@ -0,0 +1,2397 @@
+import { validatePosition, validateBbox, geoJsonBboxSchema } from '@trackunit/geo-json-utils';
+import { color } from '@trackunit/ui-design-tokens';
+import { isEqual } from 'es-toolkit';
+import { z } from 'zod';
+
+/**
+ * Helper to define an adapter factory with proper type inference.
+ *
+ * Automatically injects the `derive` method on every `AdapterConfig` it produces.
+ * Adapter implementations don't need to handle `derive` -- it's added transparently
+ * by closing over the original factory function.
+ *
+ * @example
+ * ```typescript
+ * export const googleMapsAdapter = defineAdapter((config: GoogleMapsConfig) => ({
+ *   name: "google",
+ *   config,
+ *   createInstance: () => createGoogleMapsInstance(config),
+ *   Renderer: GoogleMapsRenderer,
+ * }));
+ *
+ * // derive is available automatically:
+ * const darkAdapter = googleMapsAdapter({ apiKey, theme: "light" }).derive({ theme: "dark" });
+ * ```
+ */
+const defineAdapter = (factory) => {
+    const wrappedFactory = (config) => {
+        const base = factory(config);
+        return {
+            ...base,
+            derive: (overrides) => wrappedFactory({ ...config, ...overrides }),
+        };
+    };
+    return wrappedFactory;
+};
+
+// ============================================================================
+// Constants
+// ============================================================================
+const ANTIMERIDIAN = 180;
+/**
+ * Degrees tolerance for treating a longitude as lying on the antimeridian (±180°).
+ * Used when classifying vertices as on the eastern (+180°) or western (−180°) seam.
+ * Double-precision GeoJSON from RFC split tooling is expected near-exactly on ±180;
+ * widen only with a failing test from real data. Pairing seam latitudes uses {@link SEAM_LATITUDE_TOLERANCE}.
+ */
+const ANTIMERIDIAN_LONGITUDE_TOLERANCE = 1e-9;
+/** Tolerance for matching seam latitudes between east (+180°) and west (-180°) runs (clip output floats).
+ *
+ * SEAM_LATITUDE_TOLERANCE = 1e-5 means 0.00001° of latitude difference is treated as “the same” seam point.
+ * See https://docs.mapbox.com/help/dive-deeper/geojson-coordinate-precision/ for more details.
+ *
+ */
+const SEAM_LATITUDE_TOLERANCE = 1e-5;
+// ============================================================================
+// Coordinate helpers
+// ============================================================================
+const isAtEasternAntimeridian = (lng) => Math.abs(lng - ANTIMERIDIAN) < ANTIMERIDIAN_LONGITUDE_TOLERANCE;
+const isAtWesternAntimeridian = (lng) => Math.abs(lng + ANTIMERIDIAN) < ANTIMERIDIAN_LONGITUDE_TOLERANCE;
+/**
+ * Shift a position's longitude by a given offset, preserving 2D/3D format.
+ */
+const shiftPosition = (pos, offset) => {
+    if (pos.length === 3) {
+        return [pos[0] + offset, pos[1], pos[2]];
+    }
+    return [pos[0] + offset, pos[1]];
+};
+/**
+ * Shift all positions in a ring by a longitude offset.
+ */
+const shiftRing = (ring, offset) => ring.map(pos => shiftPosition(pos, offset));
+/**
+ * Find a maximal run of consecutive vertices at a given longitude (±180) in a ring.
+ * The ring's closing vertex (which duplicates the first) is excluded from indexing.
+ * Returns null if fewer than 2 vertices lie at the target longitude.
+ */
+const findAntimeridianRun = (ring, isAtTarget) => {
+    const len = ring.length - 1;
+    if (len < 3)
+        return null;
+    let seedIdx = -1;
+    for (let i = 0; i < len; i++) {
+        const vertex = ring[i];
+        if (vertex !== undefined && isAtTarget(vertex[0])) {
+            seedIdx = i;
+            break;
+        }
+    }
+    if (seedIdx === -1)
+        return null;
+    // Walk backwards from seed to find the true start of the run (handles wrap-around)
+    let startIdx = seedIdx;
+    for (;;) {
+        const prev = (startIdx - 1 + len) % len;
+        if (prev === seedIdx)
+            break;
+        const prevVertex = ring[prev];
+        if (prevVertex === undefined || !isAtTarget(prevVertex[0]))
+            break;
+        startIdx = prev;
+    }
+    // Walk forward from start to collect the full run
+    const latitudes = [];
+    let current = startIdx;
+    for (let count = 0; count < len; count++) {
+        const vertex = ring[current];
+        if (vertex === undefined || !isAtTarget(vertex[0]))
+            break;
+        latitudes.push(vertex[1]);
+        current = (current + 1) % len;
+    }
+    if (latitudes.length < 2)
+        return null;
+    const endIdx = (startIdx + latitudes.length - 1) % len;
+    return { startIdx, endIdx, latitudes };
+};
+/**
+ * Maximal run of consecutive vertices on ±180° in an open polyline (no closing duplicate).
+ *
+ * Unlike {@link findAntimeridianRun} on closed rings, a **single** seam vertex is valid: RFC 7946
+ * splits at the crossing often yield one point at +180° on the east segment and one at −180° on
+ * the west segment (no edge *along* the meridian).
+ */
+const findAntimeridianRunOnPolyline = (polyline, isAtTarget) => {
+    const len = polyline.length;
+    if (len < 2)
+        return null;
+    let seedIdx = -1;
+    for (let i = 0; i < len; i++) {
+        const vertex = polyline[i];
+        if (vertex !== undefined && isAtTarget(vertex[0])) {
+            seedIdx = i;
+            break;
+        }
+    }
+    if (seedIdx === -1)
+        return null;
+    let startIdx = seedIdx;
+    for (let i = seedIdx - 1; i >= 0; i--) {
+        const vertex = polyline[i];
+        if (vertex === undefined || !isAtTarget(vertex[0]))
+            break;
+        startIdx = i;
+    }
+    const latitudes = [];
+    let current = startIdx;
+    for (; current < len; current++) {
+        const vertex = polyline[current];
+        if (vertex === undefined || !isAtTarget(vertex[0]))
+            break;
+        latitudes.push(vertex[1]);
+    }
+    const endIdx = startIdx + latitudes.length - 1;
+    return { startIdx, endIdx, latitudes };
+};
+// ============================================================================
+// Matching & stitching
+// ============================================================================
+/**
+ * Check whether two antimeridian runs have matching latitude values (reversed order,
+ * as expected for two adjacent CCW rings sharing an edge in opposite directions).
+ */
+const runsMatch = (eastRun, westRun) => {
+    if (eastRun.latitudes.length !== westRun.latitudes.length)
+        return false;
+    const reversedWest = westRun.latitudes.toReversed();
+    return eastRun.latitudes.every((lat, i) => {
+        const westLat = reversedWest[i];
+        return westLat !== undefined && Math.abs(lat - westLat) < SEAM_LATITUDE_TOLERANCE;
+    });
+};
+/**
+ * Stitch an eastern ring (vertices at lng=+180) and a western ring (vertices at lng=-180)
+ * into a single ring with unwrapped coordinates. The western ring's longitudes are shifted
+ * by +360 so the merged ring has continuous coordinates across the antimeridian.
+ *
+ * The shared antimeridian edge is eliminated — the merged ring goes smoothly from the
+ * eastern side (lng near 180) through to the western side (lng near 190+).
+ */
+const stitchRings = (eastRing, eastRun, westRing, westRun) => {
+    const eastLen = eastRing.length - 1;
+    const westLen = westRing.length - 1;
+    const result = [];
+    // Walk eastern ring from after the AM run end, through the non-AM portion,
+    // up to the AM run start (inclusive). This collects the entire eastern
+    // perimeter plus the connection vertex at lng=180.
+    const eastWalkStart = (eastRun.endIdx + 1) % eastLen;
+    let idx = eastWalkStart;
+    for (let count = 0; count < eastLen; count++) {
+        const vertex = eastRing[idx];
+        if (vertex === undefined)
+            break;
+        result.push(vertex);
+        if (idx === eastRun.startIdx)
+            break;
+        idx = (idx + 1) % eastLen;
+    }
+    // Walk western ring from after the AM run end, through the non-AM portion,
+    // shifted by +360. Skip the AM endpoints to avoid duplicating vertices that
+    // coincide with the eastern connection points.
+    const westWalkStart = (westRun.endIdx + 1) % westLen;
+    const westWalkEnd = (westRun.startIdx - 1 + westLen) % westLen;
+    idx = westWalkStart;
+    for (let count = 0; count < westLen; count++) {
+        const vertex = westRing[idx];
+        if (vertex === undefined)
+            break;
+        result.push(shiftPosition(vertex, 360));
+        if (idx === westWalkEnd)
+            break;
+        idx = (idx + 1) % westLen;
+    }
+    // Close the ring
+    const first = result[0];
+    if (first !== undefined) {
+        result.push(first);
+    }
+    return result;
+};
+/**
+ * Stitch east and west polylines that share a seam at ±180° into one path with unwrapped longitudes.
+ */
+const stitchPolylines = (eastLine, eastRun, westLine, westRun) => {
+    const eastPrefix = eastLine.slice(0, eastRun.endIdx + 1);
+    const westTail = westLine.slice(westRun.endIdx + 1).map(pos => shiftPosition(pos, 360));
+    return [...eastPrefix, ...westTail];
+};
+/**
+ * Classify a sub-polygon as eastern (has AM run at +180) or western (at -180).
+ * Returns null if the exterior ring has no antimeridian run.
+ */
+const classifySubPolygon = (rings) => {
+    const exterior = rings[0];
+    if (exterior === undefined)
+        return null;
+    const eastRun = findAntimeridianRun(exterior, isAtEasternAntimeridian);
+    if (eastRun !== null) {
+        return { rings, run: eastRun, side: "east" };
+    }
+    const westRun = findAntimeridianRun(exterior, isAtWesternAntimeridian);
+    if (westRun !== null) {
+        return { rings, run: westRun, side: "west" };
+    }
+    return null;
+};
+// ============================================================================
+// MultiPolygon merging
+// ============================================================================
+/**
+ * When both halves of a hole sit on ±180° with matching seam latitudes, stitch them into one ring
+ * (same as the exterior). Otherwise return null so callers keep the legacy behaviour: east ring plus
+ * west ring shifted by +360° (holes that lie entirely on one side of the seam).
+ */
+const tryMergeHolePair = (eastHole, westHoleOriginal) => {
+    const eastRun = findAntimeridianRun(eastHole, isAtEasternAntimeridian);
+    const westRun = findAntimeridianRun(westHoleOriginal, isAtWesternAntimeridian);
+    if (eastRun === null || westRun === null) {
+        return null;
+    }
+    if (!runsMatch(eastRun, westRun)) {
+        return null;
+    }
+    return stitchRings(eastHole, eastRun, westHoleOriginal, westRun);
+};
+/**
+ * Pair east/west interior rings: seam-split holes match by antimeridian run geometry;
+ * remaining rings pair in stable index order (legacy split tooling order).
+ */
+const buildMergedInteriorRings = (eastHoles, westHolesOriginal) => {
+    const eastCount = eastHoles.length;
+    const westCount = westHolesOriginal.length;
+    const usedEast = new Set();
+    const usedWest = new Set();
+    const eastToWest = new Map();
+    for (let e = 0; e < eastCount; e++) {
+        const eastHole = eastHoles[e];
+        if (eastHole === undefined || usedEast.has(e))
+            continue;
+        for (let w = 0; w < westCount; w++) {
+            if (usedWest.has(w))
+                continue;
+            const westHole = westHolesOriginal[w];
+            if (westHole === undefined)
+                continue;
+            if (tryMergeHolePair(eastHole, westHole) !== null) {
+                eastToWest.set(e, w);
+                usedEast.add(e);
+                usedWest.add(w);
+                break;
+            }
+        }
+    }
+    const eastRemaining = [];
+    for (let e = 0; e < eastCount; e++) {
+        if (!usedEast.has(e)) {
+            eastRemaining.push(e);
+        }
+    }
+    const westRemaining = [];
+    for (let w = 0; w < westCount; w++) {
+        if (!usedWest.has(w)) {
+            westRemaining.push(w);
+        }
+    }
+    const remainderPairCount = Math.min(eastRemaining.length, westRemaining.length);
+    for (let k = 0; k < remainderPairCount; k++) {
+        const e = eastRemaining[k];
+        const w = westRemaining[k];
+        if (e === undefined || w === undefined)
+            continue;
+        eastToWest.set(e, w);
+        usedEast.add(e);
+        usedWest.add(w);
+    }
+    const mergedHoles = [];
+    for (let e = 0; e < eastCount; e++) {
+        const eastHole = eastHoles[e];
+        if (eastHole === undefined)
+            continue;
+        const w = eastToWest.get(e);
+        if (w !== undefined) {
+            const westHoleOriginal = westHolesOriginal[w];
+            if (westHoleOriginal !== undefined) {
+                const stitchedHole = tryMergeHolePair(eastHole, westHoleOriginal);
+                if (stitchedHole !== null) {
+                    mergedHoles.push(stitchedHole);
+                }
+                else {
+                    mergedHoles.push(eastHole, shiftRing(westHoleOriginal, 360));
+                }
+            }
+        }
+        else {
+            mergedHoles.push(eastHole);
+        }
+    }
+    for (let w = 0; w < westCount; w++) {
+        if (usedWest.has(w))
+            continue;
+        const westHoleOriginal = westHolesOriginal[w];
+        if (westHoleOriginal !== undefined) {
+            mergedHoles.push(shiftRing(westHoleOriginal, 360));
+        }
+    }
+    return mergedHoles;
+};
+/**
+ * Attempt to merge antimeridian-split sub-polygons within a MultiPolygon.
+ * Returns the merged coordinate arrays. Matching east/west pairs are stitched
+ * into single polygons; non-matching sub-polygons pass through unchanged.
+ */
+const mergeMultiPolygonGeometry = (geometry) => {
+    const classified = geometry.coordinates.map(classifySubPolygon);
+    const used = new Set();
+    const mergedPolygons = [];
+    for (let i = 0; i < classified.length; i++) {
+        if (used.has(i))
+            continue;
+        const ci = classified[i] ?? null;
+        if (ci === null || ci.side !== "east") {
+            continue;
+        }
+        let matched = false;
+        for (let j = 0; j < classified.length; j++) {
+            if (i === j || used.has(j))
+                continue;
+            const cj = classified[j] ?? null;
+            if (cj === null || cj.side !== "west")
+                continue;
+            if (runsMatch(ci.run, cj.run)) {
+                used.add(i);
+                used.add(j);
+                const eastExterior = ci.rings[0];
+                const westExterior = cj.rings[0];
+                if (eastExterior === undefined || westExterior === undefined)
+                    continue;
+                const mergedExterior = stitchRings(eastExterior, ci.run, westExterior, cj.run);
+                const eastHoles = ci.rings.slice(1);
+                const westHolesOriginal = cj.rings.slice(1);
+                const mergedHoles = buildMergedInteriorRings(eastHoles, westHolesOriginal);
+                mergedPolygons.push([mergedExterior, ...mergedHoles]);
+                matched = true;
+                break;
+            }
+        }
+        if (!matched) {
+            used.add(i);
+            mergedPolygons.push(ci.rings);
+        }
+    }
+    for (let i = 0; i < geometry.coordinates.length; i++) {
+        if (!used.has(i)) {
+            const coords = geometry.coordinates[i];
+            if (coords !== undefined) {
+                mergedPolygons.push(coords);
+            }
+        }
+    }
+    return mergedPolygons;
+};
+const classifySubLine = (line) => {
+    const eastRun = findAntimeridianRunOnPolyline(line, isAtEasternAntimeridian);
+    if (eastRun !== null) {
+        return { line, run: eastRun, side: "east" };
+    }
+    const westRun = findAntimeridianRunOnPolyline(line, isAtWesternAntimeridian);
+    if (westRun !== null) {
+        return { line, run: westRun, side: "west" };
+    }
+    return null;
+};
+/**
+ * Merge antimeridian-split sub-lines within a MultiLineString into one LineString when possible.
+ * Returns the input reference when no east/west pair qualifies.
+ */
+const mergeMultiLineStringGeometry = (geometry) => {
+    const lines = geometry.coordinates.map(line => line.map((pos) => [...pos]));
+    let anyMerged = false;
+    for (;;) {
+        const length = lines.length;
+        const classified = lines.map(classifySubLine);
+        let pair = null;
+        outer: for (let i = 0; i < length; i++) {
+            const ci = classified[i] ?? null;
+            if (ci === null || ci.side !== "east")
+                continue;
+            for (let j = 0; j < length; j++) {
+                if (i === j)
+                    continue;
+                const cj = classified[j] ?? null;
+                if (cj === null || cj.side !== "west")
+                    continue;
+                if (runsMatch(ci.run, cj.run)) {
+                    pair = { eastIndex: i, westIndex: j };
+                    break outer;
+                }
+            }
+        }
+        if (pair === null) {
+            break;
+        }
+        const eastC = classified[pair.eastIndex];
+        const westC = classified[pair.westIndex];
+        if (eastC === undefined || westC === undefined || eastC === null || westC === null) {
+            break;
+        }
+        const stitched = stitchPolylines(eastC.line, eastC.run, westC.line, westC.run);
+        const i0 = Math.min(pair.eastIndex, pair.westIndex);
+        const j0 = Math.max(pair.eastIndex, pair.westIndex);
+        lines.splice(j0, 1);
+        lines.splice(i0, 1);
+        lines.splice(i0, 0, stitched);
+        anyMerged = true;
+    }
+    if (!anyMerged) {
+        return geometry;
+    }
+    if (lines.length === 1 && lines[0] !== undefined) {
+        return {
+            type: "LineString",
+            coordinates: lines[0],
+        };
+    }
+    return {
+        type: "MultiLineString",
+        coordinates: lines,
+    };
+};
+// ============================================================================
+// Feature-level transformation
+// ============================================================================
+const mergeFeature = (feature) => {
+    if (feature.geometry === null) {
+        return feature;
+    }
+    switch (feature.geometry.type) {
+        case "MultiPolygon": {
+            const mergedCoordinates = mergeMultiPolygonGeometry(feature.geometry);
+            const firstMerged = mergedCoordinates[0];
+            if (mergedCoordinates.length === 1 && firstMerged !== undefined) {
+                return {
+                    ...feature,
+                    geometry: {
+                        type: "Polygon",
+                        coordinates: firstMerged,
+                    },
+                };
+            }
+            if (mergedCoordinates.length === feature.geometry.coordinates.length) {
+                let changed = false;
+                for (let i = 0; i < mergedCoordinates.length; i++) {
+                    if (mergedCoordinates[i] !== feature.geometry.coordinates[i]) {
+                        changed = true;
+                        break;
+                    }
+                }
+                if (!changed)
+                    return feature;
+            }
+            return {
+                ...feature,
+                geometry: {
+                    type: "MultiPolygon",
+                    coordinates: mergedCoordinates,
+                },
+            };
+        }
+        case "MultiLineString": {
+            const mergedGeometry = mergeMultiLineStringGeometry(feature.geometry);
+            if (mergedGeometry === feature.geometry) {
+                return feature;
+            }
+            return {
+                ...feature,
+                geometry: mergedGeometry,
+            };
+        }
+        default:
+            return feature;
+    }
+};
+// ============================================================================
+// Exported entry point
+// ============================================================================
+/**
+ * Pre-process a GeoJSON FeatureCollection for antimeridian-aware rendering.
+ *
+ * - MultiPolygon features that represent a single polygon split at the antimeridian
+ * (per RFC 7946 Section 3.1.9) are merged back into single Polygons with
+ * unwrapped coordinates (lng values may exceed 180). Interior rings that are also
+ * split at ±180° with matching seam latitudes are stitched the same way as exteriors.
+ *
+ * - MultiLineString features that represent one route split at ±180° are merged
+ * into a single LineString with the same unwrapping. This eliminates visible strokes
+ * at the antimeridian and ensures hover/selection treats each shape as one entity.
+ *
+ * The input collection is never mutated. Features that don't need merging
+ * are returned by reference.
+ *
+ * **Important:** The output contains coordinates outside [-180, 180] and is
+ * intended only for rendering via Google Maps or Mapbox, which handle
+ * world-wrapped coordinates natively. Do not pass the output to GeoJSON
+ * validators or store it.
+ */
+const mergeAntimeridianFeatures = (features) => {
+    const mergedFeatures = features.features.map(mergeFeature);
+    const anyChanged = mergedFeatures.some((merged, i) => merged !== features.features[i]);
+    if (!anyChanged)
+        return features;
+    return {
+        ...features,
+        features: mergedFeatures,
+    };
+};
+
+// TODO (next PR): colorUtils is a generic CSS utility with no adapter-specific knowledge.
+// Extract to a standalone utility package so it isn't coupled to the adapter layer.
+/**
+ * Browser-backed color mixing via CSS `color-mix()`.
+ *
+ * Uses a hidden DOM element + `getComputedStyle` to resolve expressions,
+ * cached so each unique expression is computed at most once.
+ */
+const colorCache = new Map();
+/**
+ * Modern browsers return CSS Color Level 4 `color(srgb r g b)` from
+ * `getComputedStyle`, but Mapbox GL JS only accepts classic formats
+ * (hex, rgb, rgba, hsl, hsla). Convert to `rgb()`/`rgba()`.
+ */
+const normalizeComputedColor = (color) => {
+    const m = color.match(/^color\(srgb\s+([\d.e+-]+)\s+([\d.e+-]+)\s+([\d.e+-]+)(?:\s*\/\s*([\d.e+-]+))?\)$/);
+    if (!m)
+        return color;
+    const r = Math.round(parseFloat(m[1] ?? "0") * 255);
+    const g = Math.round(parseFloat(m[2] ?? "0") * 255);
+    const b = Math.round(parseFloat(m[3] ?? "0") * 255);
+    if (m[4] !== undefined) {
+        return `rgba(${r}, ${g}, ${b}, ${parseFloat(m[4])})`;
+    }
+    return `rgb(${r}, ${g}, ${b})`;
+};
+let probeElement = null;
+const getProbeElement = () => {
+    if (probeElement) {
+        return probeElement;
+    }
+    if (typeof document === "undefined") {
+        return null;
+    }
+    const el = document.createElement("span");
+    el.style.display = "none";
+    document.body.appendChild(el);
+    probeElement = el;
+    return el;
+};
+const resolveColorMix = (expression, fallback) => {
+    const cached = colorCache.get(expression);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const el = getProbeElement();
+    if (!el) {
+        return fallback;
+    }
+    el.style.color = "";
+    el.style.color = expression;
+    if (!el.style.color) {
+        return fallback;
+    }
+    const computed = getComputedStyle(el).color;
+    if (!computed) {
+        return fallback;
+    }
+    const normalized = normalizeComputedColor(computed);
+    colorCache.set(expression, normalized);
+    return normalized;
+};
+/**
+ * Mix two CSS colors using the browser's `color-mix(in srgb)` function.
+ *
+ * @param color1 - First color (any valid CSS color string)
+ * @param color2 - Second color (any valid CSS color string)
+ * @param percentage - Percentage of `color1` in the mix (0–100)
+ * @returns Resolved color as an `rgb()` string, or `color1` if resolution fails
+ */
+const mixColor = (color1, color2, percentage) => {
+    const expression = `color-mix(in srgb, ${color1} ${percentage}%, ${color2})`;
+    return resolveColorMix(expression, color1);
+};
+/**
+ * Darken a CSS color by mixing it with black.
+ *
+ * @param color - Any valid CSS color string
+ * @param amount - Darkening intensity from 0 (no change) to 100 (pure black)
+ */
+const darkenColor = (color, amount) => mixColor(color, "black", 100 - amount);
+/**
+ * Lighten a CSS color by mixing it with white.
+ *
+ * @param color - Any valid CSS color string
+ * @param amount - Lightening intensity from 0 (no change) to 100 (pure white)
+ */
+const lightenColor = (color, amount) => mixColor(color, "white", 100 - amount);
+/**
+ * Resolve a CSS color and apply an opacity multiplier to its alpha channel.
+ *
+ * Unlike setting `element.style.opacity`, this only affects the individual
+ * color value — useful when fill and stroke need independent opacity.
+ *
+ * @param color - Any valid CSS color string
+ * @param opacity - Opacity multiplier from 0 to 1 (multiplied with existing alpha)
+ * @returns `rgba()` string with the combined alpha, or the original color if resolution fails
+ */
+const colorWithOpacity = (color, opacity) => {
+    if (opacity >= 1)
+        return color;
+    const cacheKey = `${color}@${opacity}`;
+    const cached = colorCache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const el = getProbeElement();
+    if (!el)
+        return color;
+    el.style.color = "";
+    el.style.color = color;
+    const computed = getComputedStyle(el).color;
+    if (!computed)
+        return color;
+    const normalized = normalizeComputedColor(computed);
+    const rgbaMatch = normalized.match(/^rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)$/);
+    if (!rgbaMatch)
+        return color;
+    const existingAlpha = rgbaMatch[4] !== undefined ? parseFloat(rgbaMatch[4]) : 1;
+    const result = `rgba(${rgbaMatch[1]}, ${rgbaMatch[2]}, ${rgbaMatch[3]}, ${existingAlpha * opacity})`;
+    colorCache.set(cacheKey, result);
+    return result;
+};
+/**
+ * Clear the resolved-color cache and detach the probe element.
+ * Exposed for test teardown only — not part of the public API.
+ */
+const resetColorUtilsForTesting = () => {
+    colorCache.clear();
+    if (probeElement) {
+        probeElement.remove();
+        probeElement = null;
+    }
+};
+
+/**
+ * Web Mercator max latitude in degrees: atan(sinh(π)).
+ * This is where Mercator tiles are cut off to form a square map (EPSG:3857).
+ */
+const WEB_MERCATOR_MAX_LAT_DEG = (Math.atan(Math.sinh(Math.PI)) * 180) / Math.PI;
+/**
+ * World bounds for Web Mercator projection.
+ * GeoJSON format: [minLng, minLat, maxLng, maxLat]
+ */
+const WORLD_BBOX = [-180, -WEB_MERCATOR_MAX_LAT_DEG, 180, WEB_MERCATOR_MAX_LAT_DEG];
+/**
+ * Default zoom level when not specified
+ */
+const DEFAULT_ZOOM = 2;
+/**
+ * Default center when not specified (Atlantic Ocean)
+ * Position format: { lat: number, lng: number }
+ */
+const DEFAULT_CENTER = { lat: 0, lng: 0 };
+/**
+ * Minimum zoom level supported across providers
+ * Both Mapbox and Google Maps support zoom level 0
+ */
+const MIN_ZOOM = 0;
+/**
+ * Maximum zoom level supported across providers
+ * Both Mapbox and Google Maps support zoom level 22
+ */
+const MAX_ZOOM = 22;
+/**
+ * Amount to pan the map when using arrow keys (in pixels)
+ */
+const KEYBOARD_PAN_AMOUNT = 100;
+/**
+ * Amount to zoom when using +/- keys
+ */
+const KEYBOARD_ZOOM_AMOUNT = 1;
+/**
+ * CSS cursor values used across map adapters.
+ * Centralised so both Mapbox and Google stay in sync.
+ */
+const MAP_CURSORS = {
+    default: "default",
+    interactive: "pointer",
+};
+/**
+ * Estimate zoom level from a bounding box using Web Mercator projection.
+ * Both Google Maps and Mapbox use the same 256px tile / 2^zoom formula,
+ * so a simple `log2(360 / lonSpan)` gives a close approximation without
+ * needing the container size. Used by adapter constructors to provide
+ * a reasonable initial zoom before the native map instance is created.
+ */
+const estimateZoomFromBounds = (bounds) => {
+    const lonSpan = bounds[2] - bounds[0];
+    if (lonSpan <= 0)
+        return DEFAULT_ZOOM;
+    return Math.log2(360 / lonSpan);
+};
+const mercatorY = (lat) => Math.log(Math.tan(Math.PI / 4 + (lat * Math.PI) / 360));
+/**
+ * Compute the visual center of a bounding box in Web Mercator projection.
+ * The arithmetic mean of lat/lng gives a wrong center because Mercator
+ * stretches latitudes non-linearly. This converts to Mercator Y, averages
+ * there, and converts back — matching what Google Maps and Mapbox render.
+ */
+const mercatorCenterFromBounds = (bounds) => {
+    const [minLon, minLat, maxLon, maxLat] = bounds;
+    const centerLon = (minLon + maxLon) / 2;
+    const centerLat = ((Math.atan(Math.exp((mercatorY(minLat) + mercatorY(maxLat)) / 2)) - Math.PI / 4) * 360) / Math.PI;
+    return [centerLon, centerLat];
+};
+
+const isViewportLike = (value) => {
+    return typeof value === "object" && value !== null && "type" in value;
+};
+/**
+ * Validates InitialViewport and returns undefined for invalid values.
+ */
+const validateInitialViewport = (value) => {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    if (!isViewportLike(value)) {
+        // eslint-disable-next-line no-console -- Intentional: warn developers when initialViewport shape is invalid; fallback to undefined
+        console.warn("[initialViewport] Invalid: expected object with type 'center' or 'bounds'");
+        return undefined;
+    }
+    if (value.type === "center") {
+        const center = validatePosition(value.center, "[initialViewport]");
+        if (center === null) {
+            return undefined;
+        }
+        return {
+            type: "center",
+            center,
+            zoom: typeof value.zoom === "number" ? value.zoom : undefined,
+        };
+    }
+    if (value.type === "bounds") {
+        const bounds = validateBbox(value.bounds, "[initialViewport]");
+        if (bounds === null) {
+            return undefined;
+        }
+        return {
+            type: "bounds",
+            bounds,
+            padding: typeof value.padding === "number" ? value.padding : undefined,
+            maxZoom: typeof value.maxZoom === "number" ? value.maxZoom : undefined,
+        };
+    }
+    // eslint-disable-next-line no-console -- Intentional: warn developers when initialViewport type is unknown; fallback to undefined
+    console.warn("[initialViewport] Invalid: expected type 'center' or 'bounds'");
+    return undefined;
+};
+
+/**
+ * Maps a primitive GeoJSON geometry type to the ShapeType discriminant.
+ */
+const geometryTypeToShapeType = (geometryType) => {
+    switch (geometryType) {
+        case "Polygon":
+        case "MultiPolygon":
+            return "polygon";
+        case "Point":
+        case "MultiPoint":
+            return "point";
+        case "LineString":
+        case "MultiLineString":
+            return "line";
+        default:
+            throw new Error(`${geometryType} is not a known primitive geometry type`);
+    }
+};
+/**
+ * Initial interaction state -- nothing selected or hovered.
+ */
+const INITIAL_INTERACTION_STATE = {
+    selectedEntity: null,
+    hoveredEntity: null,
+};
+
+const GEOMETRY_WEIGHT = {
+    cluster: 0,
+    circle: 1,
+    pill: 2,
+    stick: 3,
+};
+const PHASE_WEIGHT = {
+    expanded: 0,
+    idle: 1,
+    hovered: 2,
+    selected: 3,
+};
+/** Room for new phases without overlapping the next geometry band. */
+const GEOMETRY_STRIDE = 10;
+/**
+ * Single source of truth for DOM marker portal `z-index` values.
+ *
+ * Higher geometry tiers always sort above lower tiers regardless of phase
+ * (e.g. any `pill` stacks above any `circle`). Within a tier, phase orders
+ * expanded → idle → hovered → selected.
+ */
+const computeMarkerDomPortalZIndex = (geometry, phase) => {
+    return GEOMETRY_WEIGHT[geometry] * GEOMETRY_STRIDE + PHASE_WEIGHT[phase];
+};
+
+// ============================================================================
+// GeoJSON extraction helpers
+// ============================================================================
+/**
+ * Extract {lng, lat} coordinates from a GeoJSON Point feature's geometry.
+ * Returns null if the geometry is null (unlocated feature) or not a Point.
+ */
+const extractPointCoordinates = (feature) => {
+    if (feature.geometry === null || feature.geometry.type !== "Point")
+        return null;
+    const [lng, lat] = feature.geometry.coordinates;
+    return { lng, lat };
+};
+/**
+ * Extract coordinates array from a GeoJSON LineString feature.
+ * Returns an array of {lat, lng} objects, or null if empty.
+ * Returns null if the geometry is null (unlocated feature) or not a LineString.
+ */
+const extractLineCoordinates = (feature) => {
+    if (feature.geometry === null || feature.geometry.type !== "LineString")
+        return null;
+    const path = feature.geometry.coordinates.map(([lng, lat]) => ({ lng, lat }));
+    return path.length > 0 ? path : null;
+};
+/**
+ * Extract coordinates from GeoJSON Polygon coordinates.
+ * Returns an array of rings (outer ring + holes), each an array of {lat, lng}.
+ */
+const extractPolygonPaths = (coordinates) => {
+    if (!Array.isArray(coordinates))
+        return null;
+    const paths = [];
+    for (const ring of coordinates) {
+        if (!Array.isArray(ring))
+            continue;
+        const path = [];
+        for (const coord of ring) {
+            if (!Array.isArray(coord) || coord.length < 2)
+                continue;
+            const lng = coord[0];
+            const lat = coord[1];
+            if (typeof lng !== "number" || typeof lat !== "number")
+                continue;
+            path.push({ lat, lng });
+        }
+        if (path.length > 0) {
+            paths.push(path);
+        }
+    }
+    return paths.length > 0 ? paths : null;
+};
+// ============================================================================
+// Feature comparison helpers
+// ============================================================================
+/**
+ * Check whether two GeoJSON feature collections contain the same features
+ * by comparing the count and individual feature IDs. Returns true if both
+ * are null, or if they have the same number of features with matching IDs
+ * in the same order.
+ *
+ * Used by adapters to skip unnecessary full marker rebuilds when a new config
+ * object is created but the underlying data hasn't changed (e.g. only callback
+ * references differ due to a React re-render).
+ */
+const hasSameFeatureIds = (a, b) => {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    const af = a.features, bf = b.features;
+    if (af.length !== bf.length)
+        return false;
+    for (let i = 0; i < af.length; i++) {
+        const featureA = af[i];
+        const featureB = bf[i];
+        if (featureA === undefined || featureB === undefined)
+            return false;
+        if (featureA.id !== featureB.id)
+            return false;
+    }
+    return true;
+};
+/**
+ * True when paired features (same length / ids per {@link hasSameFeatureIds}) share identical
+ * Point coordinates. Non-Point or missing geometries must match structurally (both null/absent).
+ */
+const markerPointPositionsMatch = (existing, incoming) => {
+    const { features: af } = existing;
+    const { features: bf } = incoming;
+    if (af.length !== bf.length)
+        return false;
+    for (let i = 0; i < af.length; i++) {
+        const featureA = af[i];
+        const featureB = bf[i];
+        if (featureA === undefined || featureB === undefined)
+            return false;
+        const posA = extractPointCoordinates(featureA);
+        const posB = extractPointCoordinates(featureB);
+        if (posA === null && posB === null)
+            continue;
+        if (posA === null || posB === null)
+            return false;
+        if (posA.lng !== posB.lng || posA.lat !== posB.lat)
+            return false;
+    }
+    return true;
+};
+const markerRenderAnchor = (render) => render.mode === "dom" ? render.anchor : undefined;
+const markerRenderPixelOffset = (render) => render.mode === "dom" ? render.pixelOffset : undefined;
+const pixelOffsetEqual = (a, b) => a === b || (a !== undefined && b !== undefined && a.x === b.x && a.y === b.y);
+/**
+ * Determines whether an existing marker source can be patched in place
+ * (position + portal update) instead of requiring a full teardown/rebuild.
+ *
+ * A full rebuild is required when the Mapbox/Google marker `anchor` or
+ * `pixelOffset` changes, because both are immutable after marker construction.
+ * Without this check the DOM marker keeps a stale anchor/offset while React
+ * renders with the new values.
+ */
+const canPatchMarkerInPlace = (existing, incoming) => {
+    if (existing.markerRender.mode === "adaptive" || incoming.markerRender.mode === "adaptive") {
+        // Adaptive mode re-evaluates medium selection and can swap symbol/DOM backends;
+        // reuse the dedicated adaptive patch path instead of the static DOM/symbol patcher.
+        return false;
+    }
+    if (existing.kind !== incoming.kind)
+        return false;
+    const baseMatch = existing.markerRender.mode === incoming.markerRender.mode &&
+        markerRenderAnchor(existing.markerRender) === markerRenderAnchor(incoming.markerRender) &&
+        pixelOffsetEqual(markerRenderPixelOffset(existing.markerRender), markerRenderPixelOffset(incoming.markerRender)) &&
+        hasSameFeatureIds(existing.features, incoming.features);
+    if (!baseMatch)
+        return false;
+    // Canvas symbol overlays snapshot marker positions when built; the DOM patch path
+    // updates coordinates in place. If only Point coords move, force a rebuild so symbols redraw.
+    const renderMode = incoming.markerRender.mode;
+    if (renderMode === "symbol") {
+        if (!markerPointPositionsMatch(existing.features, incoming.features)) {
+            return false;
+        }
+    }
+    if (existing.kind === "marker" && incoming.kind === "marker") {
+        return (existing.clusterConfig?.mode === incoming.clusterConfig?.mode &&
+            hasSameFeatureIds(existing.clusterFeatures, incoming.clusterFeatures));
+    }
+    return true;
+};
+// ============================================================================
+// Data extraction and style resolution
+// ============================================================================
+/**
+ * Extract the original source data from GeoJSON feature properties.
+ * useMarkers stores the original TItem / TCluster in properties.__data
+ * so that style functions receive the full typed object, not raw GeoJSON properties.
+ */
+const extractSourceData = (properties) => {
+    if (properties !== null && "__data" in properties) {
+        return properties.__data;
+    }
+    return properties;
+};
+const isPortalSourceComparableObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const normalizePortalSourceComparable = (value) => {
+    if (value === null) {
+        return null;
+    }
+    if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+        return value;
+    }
+    if (typeof value !== "object") {
+        // Catches symbol, bigint, function, and undefined
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map(normalizePortalSourceComparable);
+    }
+    const keys = Object.keys(value).toSorted();
+    const out = {};
+    for (const k of keys) {
+        out[k] = normalizePortalSourceComparable(Reflect.get(value, k));
+    }
+    return out;
+};
+/**
+ * Stable JSON-like serialization (order-independent object keys) for comparing
+ * {@link PortalSourceComparable} values.
+ */
+const stableSerializePortalComparable = (value) => {
+    if (value === null) {
+        return "null";
+    }
+    if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(stableSerializePortalComparable).join(",")}]`;
+    }
+    if (!isPortalSourceComparableObject(value)) {
+        throw new Error("[layerPortHelpers] stableSerializePortalComparable: unreachable branch");
+    }
+    const keys = Object.keys(value).toSorted();
+    return `{${keys
+        .map(k => {
+        const child = value[k];
+        if (child === undefined) {
+            throw new Error(`[layerPortHelpers] stableSerializePortalComparable: missing key ${k}`);
+        }
+        return `${JSON.stringify(k)}:${stableSerializePortalComparable(child)}`;
+    })
+        .join(",")}}`;
+};
+const portalSourceDataEqual = (a, b) => stableSerializePortalComparable(normalizePortalSourceComparable(a)) ===
+    stableSerializePortalComparable(normalizePortalSourceComparable(b));
+/**
+ * Patch portal descriptors for features whose data or render function changed,
+ * preserving the existing container and key so React can update in-place
+ * without a remove-then-add cycle (which causes visible flickering).
+ *
+ * Pure function: returns a new descriptors array and a `changed` flag.
+ * Both adapters delegate to this from their `patchDomMarkers` method.
+ */
+const patchPortalDescriptors = (descriptors, sourceId, features, render) => {
+    const result = Array.from(descriptors);
+    let changed = false;
+    for (const feature of features) {
+        const featureId = feature.id !== undefined ? String(feature.id) : "";
+        const key = `${sourceId}:${featureId}`;
+        const idx = result.findIndex(d => d.key === key);
+        const existing = idx !== -1 ? result[idx] : undefined;
+        if (existing !== undefined) {
+            const nextSourceData = extractSourceData(feature.properties);
+            const renderSame = existing.renderFn === render;
+            const dataSame = portalSourceDataEqual(existing.sourceData, nextSourceData);
+            if (renderSame && dataSame) {
+                continue;
+            }
+            result[idx] = {
+                ...existing,
+                renderFn: render,
+                sourceData: nextSourceData,
+            };
+            changed = true;
+        }
+    }
+    return { descriptors: result, changed };
+};
+/**
+ * Defaults for a {@link CircleSymbolDescriptor} (per ADR-0011).
+ * - `diameterPx`: 16
+ * - `opacity`: 1
+ * - `borderColor`: null (no border)
+ * - `borderWidthPx`: 0 (no border)
+ */
+const CIRCLE_SYMBOL_DEFAULT_DIAMETER_PX = 16;
+const CIRCLE_SYMBOL_DEFAULT_OPACITY = 1;
+/**
+ * Fill {@link CircleSymbolDescriptor} defaults and compute `radiusPx`
+ * (`= diameterPx / 2`) and `hasBorder` (`= borderColor !== null && borderWidthPx > 0`).
+ *
+ * Pure function — adapters use this once per feature to derive the values they
+ * pass to their style format (Mapbox paint expression or canvas `ctx.arc`).
+ */
+const resolveCircleSymbolDefaults = (descriptor) => {
+    const diameterPx = descriptor.diameterPx ?? CIRCLE_SYMBOL_DEFAULT_DIAMETER_PX;
+    const opacity = descriptor.opacity ?? CIRCLE_SYMBOL_DEFAULT_OPACITY;
+    const borderColor = descriptor.borderColor ?? null;
+    const borderWidthPx = descriptor.borderWidthPx ?? 0;
+    return {
+        color: descriptor.color,
+        diameterPx,
+        radiusPx: diameterPx / 2,
+        opacity,
+        borderColor,
+        borderWidthPx,
+        hasBorder: borderColor !== null && borderWidthPx > 0,
+    };
+};
+/**
+ * Resolve a {@link SymbolDescriptor} by calling the style function with the
+ * source data extracted from `properties.__data`.
+ */
+const resolveSymbolDescriptor = (style, properties) => {
+    return style(extractSourceData(properties));
+};
+/**
+ * Structural runtime check for a {@link SymbolDescriptor}: a non-null,
+ * non-array object with a `color: string` field.
+ */
+const isSymbolDescriptor = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    if (!("color" in value)) {
+        return false;
+    }
+    return typeof value.color === "string";
+};
+/**
+ * Discriminate the result of a unified `render(item, state)` callback into a
+ * symbol descriptor or a DOM node (ADR-0009).
+ *
+ * Rules:
+ * - Plain object with `color: string` → `{ kind: "symbol", symbol }`.
+ * - Anything else (strings, numbers, `null`, fragments, iterables) → treated
+ *   as a DOM node so consumers can return primitives like text directly.
+ *
+ * When the optional `expectedMedium` argument is set (adaptive routing), a dev-only
+ * `console.warn` runs if the discriminated `kind` disagrees with it — e.g.
+ * the consumer returned a `ReactNode` while `state.medium` was `"symbol"`.
+ * Omitted in production builds (`NODE_ENV === "production"`).
+ */
+const discriminateRenderResult = (result, expectedMedium) => {
+    let discriminated;
+    if (isSymbolDescriptor(result)) {
+        discriminated = { kind: "symbol", symbol: result };
+    }
+    else {
+        discriminated = { kind: "dom", node: result };
+    }
+    if (expectedMedium !== undefined && discriminated.kind !== expectedMedium && process.env.NODE_ENV !== "production") {
+        // eslint-disable-next-line no-console -- dev-only adaptive render contract check (ADR-0009)
+        console.warn(`[react-map-adapter-shared] Adaptive render return type does not match state.medium: ` +
+            `expected "${expectedMedium}" but the return value was discriminated as "${discriminated.kind}". ` +
+            `Branch on state.medium and return a SymbolDescriptor when medium is "symbol", or a ReactNode when medium is "dom".`);
+    }
+    return discriminated;
+};
+/**
+ * Fallback {@link SymbolDescriptor} used when an adaptive `render` returns a
+ * DOM node while the symbol medium was requested. This is a programmer error
+ * (the adaptive contract requires a `SymbolDescriptor` when `state.medium`
+ * is `"symbol"`); a dev-only mismatch warning is emitted when
+ * {@link discriminateRenderResult} is called with `expectedMedium: "symbol"`.
+ */
+const adaptiveSymbolFallback = () => ({ color: color("NEUTRAL", 400, "HEX") });
+/**
+ * Build a `(item) → SymbolDescriptor` closure from an adaptive
+ * {@link AdaptiveRenderConfig.render} callback (ADR-0009).
+ *
+ * Adapters that render a feature in symbol medium under `mode: "adaptive"`
+ * call render with the supplied `SymbolRenderState`, then route the result
+ * via {@link discriminateRenderResult}. When the discriminated kind is
+ * `"symbol"`, the descriptor is returned; when it disagrees with the
+ * requested medium (the consumer accidentally returned a `ReactNode`), a
+ * neutral fallback descriptor is returned so rendering can proceed (with a
+ * dev-only `console.warn` via {@link discriminateRenderResult}).
+ */
+const buildAdaptiveSymbolStyleFn = (render, state) => {
+    return (item) => {
+        const result = render(item, state);
+        const discriminated = discriminateRenderResult(result, "symbol");
+        return discriminated.kind === "symbol" ? discriminated.symbol : adaptiveSymbolFallback();
+    };
+};
+/**
+ * Build a `DomPortalDescriptor["renderFn"]` from an adaptive
+ * {@link AdaptiveRenderConfig.render} callback (ADR-0009).
+ *
+ * Adapters wrap the consumer's unified render with this when registering a
+ * DOM portal for an adaptive feature: the closure forwards the
+ * `DomRenderState` (a member of `AdaptiveRenderState`) into render, then
+ * routes the result via {@link discriminateRenderResult}, returning the
+ * `ReactNode` for `kind === "dom"` and `null` for the mismatch case where
+ * the consumer accidentally returned a `SymbolDescriptor` (with a dev-only
+ * `console.warn` via {@link discriminateRenderResult}).
+ */
+const buildAdaptiveDomRenderFn = (render) => {
+    return (item, state) => {
+        // DomPortalDescriptor's renderFn accepts both marker (DomRenderState) and
+        // cluster (ClusterRenderState) state shapes. Adapters never wire adaptive
+        // markers' render into a cluster portal, so reaching this with a non-DOM
+        // state is a programmer error — return null defensively rather than feed
+        // an invalid state into the adaptive render.
+        if (!("medium" in state))
+            return null;
+        const result = render(item, state);
+        const discriminated = discriminateRenderResult(result, "dom");
+        return discriminated.kind === "dom" ? discriminated.node : null;
+    };
+};
+// ============================================================================
+// DOM element creation (provider-agnostic)
+// ============================================================================
+/**
+ * Create a styled cluster pin DOM element.
+ * Used by both Google Maps and Mapbox adapters for symbol-mode cluster rendering.
+ *
+ * Cluster pins keep their always-on white border (visual distinction from
+ * individual markers); only `color` is read from the descriptor.
+ */
+const createClusterPinElement = (descriptor, count) => {
+    const size = Math.max(36, Math.min(56, 36 + (typeof count === "number" ? count : 0) * 2));
+    const el = document.createElement("div");
+    el.style.width = `${size}px`;
+    el.style.height = `${size}px`;
+    el.style.borderRadius = "50%";
+    el.style.backgroundColor = descriptor.color;
+    el.style.color = "white";
+    el.style.display = "flex";
+    el.style.alignItems = "center";
+    el.style.justifyContent = "center";
+    el.style.fontWeight = "bold";
+    el.style.fontSize = "14px";
+    el.style.boxShadow = "0 2px 6px rgba(0,0,0,0.3)";
+    el.style.border = "2px solid white";
+    el.style.cursor = "pointer";
+    if (typeof count === "number") {
+        el.textContent = String(count);
+    }
+    return el;
+};
+/**
+ * Create a default cluster element with the default blue color.
+ */
+const createDefaultClusterElement = (count) => {
+    return createClusterPinElement({ color: "#4285F4" }, count);
+};
+/**
+ * Create a styled dot element for symbol-mode markers (e.g. client-clustering
+ * paths that emit per-marker DOM elements). Uses the resolved descriptor's
+ * `diameterPx` for sizing and applies the border only when `hasBorder` is true.
+ */
+const createSymbolDotElement = (resolved) => {
+    const el = document.createElement("div");
+    el.style.width = `${resolved.diameterPx}px`;
+    el.style.height = `${resolved.diameterPx}px`;
+    el.style.borderRadius = "50%";
+    el.style.backgroundColor = resolved.color;
+    el.style.border = resolved.hasBorder ? `${resolved.borderWidthPx}px solid ${resolved.borderColor}` : "none";
+    el.style.boxShadow = "0 1px 4px rgba(0,0,0,0.3)";
+    el.style.cursor = "pointer";
+    el.style.opacity = String(resolved.opacity);
+    return el;
+};
+// ============================================================================
+// Adaptive DOM helpers
+// ============================================================================
+/**
+ * Feature IDs that render as DOM markers in adaptive mode (i.e. resolved
+ * medium is `"dom"`).
+ */
+const getAdaptiveDomFeatureIds = (config) => {
+    const ids = new Set();
+    const { markerRender } = config;
+    if (markerRender.mode !== "adaptive")
+        return ids;
+    if (config.kind !== "marker")
+        return ids;
+    const adaptiveResolution = config.adaptiveResolution;
+    if (adaptiveResolution === undefined)
+        return ids;
+    for (const feature of config.features.features) {
+        if (feature.id === undefined)
+            continue;
+        const id = String(feature.id);
+        const mode = adaptiveResolution.modesByFeatureId.get(id);
+        if (mode === "dom") {
+            ids.add(id);
+        }
+    }
+    return ids;
+};
+// ============================================================================
+// Adaptive DOM overlay helpers
+// ============================================================================
+/**
+ * Returns true when a render mode requires the WebGL/canvas circle layer
+ * (symbol or adaptive). Use to branch between the canvas path and
+ * the individual DOM-marker-per-feature path.
+ */
+const isCanvasMarkerMode = (mode) => mode === "symbol" || mode === "adaptive";
+/**
+ * Shared loop body for adaptive DOM overlay creation. Handles guards, feature
+ * iteration, and renderFn construction, then delegates marker creation to the
+ * adapter via `createMarker`.
+ *
+ * Returns one entry per DOM-rendered feature so each adapter can apply its own
+ * post-creation work (zIndex, interaction listeners, tracked-marker bookkeeping).
+ */
+const buildAdaptiveDomEntries = (config, createMarker) => {
+    const { markerRender } = config;
+    if (markerRender.mode !== "adaptive")
+        return [];
+    if (config.kind !== "marker")
+        return [];
+    const resolution = config.adaptiveResolution;
+    if (resolution === undefined)
+        return [];
+    const entries = [];
+    /** Non-empty feature ids already given a DOM marker — avoids duplicate portal keys when the collection repeats the same `id`. */
+    const domPortalCreatedForId = new Set();
+    for (const feature of config.features.features) {
+        const coords = extractPointCoordinates(feature);
+        if (coords === null)
+            continue;
+        const featureId = feature.id !== undefined ? String(feature.id) : "";
+        const mode = resolution.modesByFeatureId.get(featureId) ?? "symbol";
+        if (mode !== "dom")
+            continue;
+        if (featureId !== "" && domPortalCreatedForId.has(featureId))
+            continue;
+        const data = extractSourceData(feature.properties);
+        const renderFn = buildAdaptiveDomRenderFn(markerRender.render);
+        const domMarker = createMarker(featureId, coords, config.id, data, renderFn);
+        entries.push({ featureId, coords, domMarker });
+        if (featureId !== "")
+            domPortalCreatedForId.add(featureId);
+    }
+    return entries;
+};
+// ============================================================================
+// Viewport-patch helpers (shared across adapters)
+// ============================================================================
+/**
+ * Collect the set of non-empty feature IDs from a GeoJSON feature collection.
+ * Returns an empty set when `collection` is null.
+ *
+ * Used by adapters to diff feature ID sets between config updates so they can
+ * remove gone markers and add new ones without a full teardown/rebuild.
+ */
+const collectFeatureIdSet = (collection) => {
+    const ids = new Set();
+    if (collection === null)
+        return ids;
+    for (const feature of collection.features) {
+        if (feature.id !== undefined) {
+            ids.add(String(feature.id));
+        }
+    }
+    return ids;
+};
+/**
+ * Returns true when an adaptive marker source can be patched incrementally
+ * after a viewport refetch — i.e. structural config (render mode, anchor,
+ * clustering mode, cluster render mode) matches between existing and incoming,
+ * but marker/cluster feature IDs may differ.
+ *
+ * When this returns true, adapters should diff by feature ID (add new,
+ * remove gone) instead of doing a full teardown/rebuild. This prevents
+ * existing DOM markers from flickering when only the set of visible IDs changes.
+ *
+ * Callback references (render functions) are intentionally not compared:
+ * they change on every React render and are always captured fresh during the patch.
+ */
+const canPatchAdaptiveViewport = (existing, incoming) => {
+    if (existing.kind !== "marker" || incoming.kind !== "marker")
+        return false;
+    if (existing.markerRender.mode !== "adaptive" || incoming.markerRender.mode !== "adaptive")
+        return false;
+    if (existing.markerRender.anchor !== incoming.markerRender.anchor)
+        return false;
+    if (!pixelOffsetEqual(existing.markerRender.pixelOffset, incoming.markerRender.pixelOffset))
+        return false;
+    if (existing.clusterConfig?.mode !== incoming.clusterConfig?.mode)
+        return false;
+    if (existing.clusterRender === null && incoming.clusterRender !== null)
+        return false;
+    if (existing.clusterRender !== null && incoming.clusterRender === null)
+        return false;
+    if (existing.clusterRender !== null && incoming.clusterRender !== null) {
+        if (existing.clusterRender.mode !== incoming.clusterRender.mode)
+            return false;
+        if (existing.clusterRender.mode === "dom" && incoming.clusterRender.mode === "dom") {
+            if (existing.clusterRender.anchor !== incoming.clusterRender.anchor)
+                return false;
+            if (!pixelOffsetEqual(existing.clusterRender.pixelOffset, incoming.clusterRender.pixelOffset))
+                return false;
+        }
+    }
+    return true;
+};
+/**
+ * Returns true when an adaptive marker source can be patched incrementally for
+ * mode transitions / portal updates where feature IDs and cluster data are stable.
+ */
+const canPatchAdaptiveMarker = (existing, incoming) => {
+    if (existing.markerRender.mode !== "adaptive" || incoming.markerRender.mode !== "adaptive")
+        return false;
+    if (existing.kind !== "marker" || incoming.kind !== "marker")
+        return false;
+    return (hasSameFeatureIds(existing.features, incoming.features) &&
+        existing.markerRender.anchor === incoming.markerRender.anchor &&
+        pixelOffsetEqual(existing.markerRender.pixelOffset, incoming.markerRender.pixelOffset) &&
+        existing.clusterConfig?.mode === incoming.clusterConfig?.mode &&
+        hasSameFeatureIds(existing.clusterFeatures, incoming.clusterFeatures) &&
+        isEqual(existing.clusterFeatures, incoming.clusterFeatures));
+};
+/**
+ * Removes indexed native markers whose feature IDs are no longer present and
+ * removes the matching DOM portal descriptors. The marker index is mutated in
+ * place because adapters keep it as their long-lived native marker registry.
+ */
+const removeGoneIndexedMarkers = ({ incomingFeatureIds, markerIndex, markers, portalDescriptors, sourceId, detachMarker, }) => {
+    const removedMarkers = new Set();
+    const removedPortalKeys = new Set();
+    for (const [featureId, marker] of markerIndex) {
+        if (incomingFeatureIds.has(featureId))
+            continue;
+        detachMarker(marker);
+        markerIndex.delete(featureId);
+        removedMarkers.add(marker);
+        removedPortalKeys.add(`${sourceId}:${featureId}`);
+    }
+    const nextMarkers = removedMarkers.size === 0 ? markers : markers.filter(marker => !removedMarkers.has(marker));
+    const nextPortalDescriptors = removedPortalKeys.size === 0
+        ? portalDescriptors
+        : portalDescriptors.filter(descriptor => !removedPortalKeys.has(descriptor.key));
+    return {
+        markerIndex,
+        markers: nextMarkers,
+        portalDescriptors: nextPortalDescriptors,
+        markersChanged: removedMarkers.size > 0,
+        portalDescriptorsChanged: nextPortalDescriptors.length !== portalDescriptors.length,
+    };
+};
+// ============================================================================
+// Anchor helpers
+// ============================================================================
+/**
+ * Convert a MarkerAnchor value to a CSS transform string.
+ * Assumes the element's **bottom-center** is at the coordinate by default.
+ * Google Maps AdvancedMarkerElement positions custom DOM content at
+ * bottom-center, so all Google DOM elements (symbol dots, shape point dots,
+ * and DOM markers) need this to correct anchoring.
+ */
+const anchorFromBottomCenter = (anchor) => {
+    switch (anchor) {
+        case "center":
+            return "translate(0, 50%)";
+        case "top":
+            return "translate(0, 100%)";
+        case "bottom":
+            return "translate(0, 0)";
+        case "left":
+            return "translate(50%, 50%)";
+        case "right":
+            return "translate(-50%, 50%)";
+        case "top-left":
+            return "translate(50%, 100%)";
+        case "top-right":
+            return "translate(-50%, 100%)";
+        case "bottom-left":
+            return "translate(50%, 0)";
+        case "bottom-right":
+            return "translate(-50%, 0)";
+        default: {
+            throw new Error(`${anchor} is not known`);
+        }
+    }
+};
+const LAYER_FADE_DURATION_MS = 200;
+/**
+ * Start an element at opacity 0 and animate it in via CSS transition.
+ * Used for DOM-based markers in both Mapbox and Google adapters.
+ */
+const fadeInElement = (el) => {
+    el.style.opacity = "0";
+    el.style.transition = `opacity ${LAYER_FADE_DURATION_MS}ms ease-out`;
+    requestAnimationFrame(() => {
+        el.style.opacity = "1";
+    });
+};
+
+/** Type predicate to narrow a MapEvent to a specific event type */
+const isEventOfType = (mapEvent, type) => mapEvent.type === type;
+
+// ============================================================================
+// Appearance Schemas & Types (single source of truth)
+// ============================================================================
+const mapThemeSchema = z.enum(["light", "dark"]);
+const mapTypeSchema = z.enum(["roadmap", "satellite", "hybrid"]);
+const mapAppearanceSchema = z.object({
+    theme: mapThemeSchema,
+    mapType: mapTypeSchema,
+    showRoads: z.boolean(),
+});
+/** Default appearance before any user preference is applied */
+const DEFAULT_MAP_APPEARANCE = {
+    theme: "light",
+    mapType: "roadmap",
+    showRoads: false,
+};
+const INITIAL_CAMERA_STATE = {
+    center: [0, 0],
+    zoom: DEFAULT_ZOOM,
+    bounds: null,
+    isIdle: true,
+};
+const INITIAL_MAP_STATUS = {
+    isReady: false,
+    initializationFailed: false,
+    appearance: DEFAULT_MAP_APPEARANCE,
+    tileSize: 256,
+};
+/**
+ * Initial map state - default values before map loads
+ */
+const INITIAL_MAP_STATE = {
+    ...INITIAL_CAMERA_STATE,
+    ...INITIAL_MAP_STATUS,
+};
+
+/**
+ * Compute the initial MapState from a config's appearance and optional viewport.
+ * Shared by both Google Maps and Mapbox adapters.
+ */
+const computeInitialState = (appearance, initialViewport) => {
+    const vp = validateInitialViewport(initialViewport);
+    if (vp === undefined) {
+        return { ...INITIAL_MAP_STATE, appearance };
+    }
+    if (vp.type === "center") {
+        return {
+            ...INITIAL_MAP_STATE,
+            appearance,
+            center: vp.center,
+            zoom: vp.zoom ?? INITIAL_MAP_STATE.zoom,
+        };
+    }
+    return {
+        ...INITIAL_MAP_STATE,
+        appearance,
+        center: mercatorCenterFromBounds(vp.bounds),
+        zoom: estimateZoomFromBounds(vp.bounds),
+        bounds: vp.bounds,
+    };
+};
+const bboxEquals = (a, b) => {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    return a[0] === b[0] && a[1] === b[1] && a[2] === b[2] && a[3] === b[3];
+};
+/** Field-wise equality for camera state (center, zoom, bounds, isIdle). */
+const cameraStateEquals = (a, b) => a.center[0] === b.center[0] &&
+    a.center[1] === b.center[1] &&
+    a.zoom === b.zoom &&
+    a.isIdle === b.isIdle &&
+    bboxEquals(a.bounds, b.bounds);
+/** Field-wise equality for map status (isReady, initializationFailed, appearance, tileSize). */
+const statusEquals = (a, b) => a.isReady === b.isReady &&
+    a.initializationFailed === b.initializationFailed &&
+    a.appearance === b.appearance &&
+    a.tileSize === b.tileSize;
+/** Field-wise equality for the full combined MapState. */
+const mapStateEquals = (a, b) => cameraStateEquals(a, b) && statusEquals(a, b);
+
+/**
+ * Resolve effective restrict bounds from config.
+ * Returns null if no restriction; GeoJsonBbox otherwise.
+ * Validates custom bbox with geoJsonBboxSchema; on failure, console.warn and fallback to null.
+ *
+ * @note - Why fallback to null and not WORLD_BBOX?
+ * Different map providers handle full world bounds differently.
+ * Eg. -/+180 degrees longitude is disregarded by Google Maps allowing for infinite horizontal scroll.
+ * while Mapbox respects the full world bounds, leading to inconsistent behavior between adapters.
+ */
+function getEffectiveRestrictBounds(configValue) {
+    if (configValue === null || configValue === undefined)
+        return null;
+    const result = geoJsonBboxSchema.safeParse(configValue);
+    if (!result.success) {
+        // eslint-disable-next-line no-console -- Intentional: warn devs when invalid restrictBounds bbox is passed; fallback to null
+        console.warn("[restrictBounds]", result.error.message);
+        return null;
+    }
+    return result.data;
+}
+
+/**
+ * The DOM-attribute contract that the safe-area hover system relies on. Any
+ * marker (built-in or third-party) opts into the spurious-mouseleave-safe
+ * hover by tagging two elements inside its DOM tree:
+ *
+ *   - {@link HIT_SURFACE_SELECTOR} on the visible interactive surface (e.g.
+ *     the pill at the tip of a stick marker).
+ *   - {@link ANCHOR_SELECTOR} on the geographic-anchor element. Prefer the
+ *     visible anchor footprint when one exists (e.g. a stick marker's anchor
+ *     dot); a 0×0 coordinate node also works when no visible anchor exists.
+ *     The anchor is only required when the visible surface is *spatially
+ *     separated* from the anchor (the classic stick-marker case); plain
+ *     non-stick markers can omit it without consequence.
+ */
+/** Stable attribute on the visible interactive surface element. */
+const HIT_SURFACE_SELECTOR = "[data-map-marker-hit-surface]";
+/** Stable attribute on the geographic-anchor element. */
+const ANCHOR_SELECTOR = "[data-map-marker-anchor]";
+/**
+ * Outward buffer applied to each rect's corners when building the safe-area
+ * polygon. Guards against OS pointer-jitter at the polygon boundary without
+ * masking intentional outward movement.
+ */
+const SAFE_AREA_DEFAULT_BUFFER_PX = 1;
+/**
+ * Resolve the rect to use for hit-testing a DOM marker. Prefers the inner
+ * hit-surface element (when present and non-empty); falls back to the host's
+ * own rect; returns null when both are empty.
+ */
+const getHitSurfaceRect = (host) => {
+    const inner = host.querySelector(HIT_SURFACE_SELECTOR);
+    if (inner !== null) {
+        const innerRect = inner.getBoundingClientRect();
+        if (innerRect.width > 0 && innerRect.height > 0)
+            return innerRect;
+    }
+    const hostRect = host.getBoundingClientRect();
+    return hostRect.width > 0 && hostRect.height > 0 ? hostRect : null;
+};
+/**
+ * Return the page-space rect of the geographic anchor element, or null when
+ * the host does not contain one (no `data-map-marker-anchor`). A visible
+ * anchor dot gives the safe area its real footprint; a 0×0 coordinate node is
+ * still valid when no visible anchor exists.
+ */
+const getAnchorRect = (host) => {
+    const el = host.querySelector(ANCHOR_SELECTOR);
+    if (el === null)
+        return null;
+    return el.getBoundingClientRect();
+};
+
+/**
+ * Pure 2D polygon primitives used by the safe-area system. No DOM dependency,
+ * no React dependency — just geometry.
+ */
+/**
+ * Return the four corners of `rect`, outward-buffered by `px` on every axis.
+ * A 0×0 rect with a positive buffer still contributes a 4-point square (used
+ * to give the geographic anchor a non-zero footprint in the safe area).
+ */
+const bufferRectCorners = (rect, px) => {
+    const left = rect.left - px;
+    const right = rect.right + px;
+    const top = rect.top - px;
+    const bottom = rect.bottom + px;
+    return [
+        { x: left, y: top },
+        { x: right, y: top },
+        { x: right, y: bottom },
+        { x: left, y: bottom },
+    ];
+};
+/**
+ * Andrew's monotone-chain convex hull. Returns hull points in counter-clockwise
+ * order (in screen coordinates where y grows downward, this is visually
+ * clockwise, but the orientation does not affect the even-odd point-in-polygon
+ * test). The first point is **not** repeated at the end.
+ *
+ * Inputs are typically ≤ 12 (3 rects × 4 corners) so the O(n log n) sort is
+ * negligible. Empty input returns an empty hull.
+ */
+const convexHull = (points) => {
+    if (points.length <= 1)
+        return points.slice();
+    const sorted = points.slice().sort((a, b) => (a.x === b.x ? a.y - b.y : a.x - b.x));
+    const cross = (o, a, b) => (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
+    const lower = [];
+    for (const p of sorted) {
+        while (lower.length >= 2) {
+            const a = lower[lower.length - 2];
+            const b = lower[lower.length - 1];
+            if (a === undefined || b === undefined)
+                break;
+            if (cross(a, b, p) <= 0) {
+                lower.pop();
+            }
+            else {
+                break;
+            }
+        }
+        lower.push(p);
+    }
+    const upper = [];
+    for (let i = sorted.length - 1; i >= 0; i--) {
+        const p = sorted[i];
+        if (p === undefined)
+            continue;
+        while (upper.length >= 2) {
+            const a = upper[upper.length - 2];
+            const b = upper[upper.length - 1];
+            if (a === undefined || b === undefined)
+                break;
+            if (cross(a, b, p) <= 0) {
+                upper.pop();
+            }
+            else {
+                break;
+            }
+        }
+        upper.push(p);
+    }
+    lower.pop();
+    upper.pop();
+    return lower.concat(upper);
+};
+/**
+ * Even-odd ray-cast point-in-polygon test. The standard formulation: edges are
+ * classified consistently (one side "inside", the other "outside") so a point
+ * that lies exactly on a polygon boundary may go either way depending on which
+ * edge was tested first — relying on edge classification is fragile. Callers
+ * should use the outward buffer in {@link ./safePolygon#safePolygon} as the
+ * tolerance margin and treat strictly-inside checks as the contract.
+ */
+const pointInPolygon = (x, y, polygon) => {
+    if (polygon.length < 3)
+        return false;
+    let inside = false;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        const pi = polygon[i];
+        const pj = polygon[j];
+        if (pi === undefined || pj === undefined)
+            continue;
+        const intersects = pi.y > y !== pj.y > y && x < ((pj.x - pi.x) * (y - pi.y)) / (pj.y - pi.y) + pi.x;
+        if (intersects)
+            inside = !inside;
+    }
+    return inside;
+};
+
+/**
+ * Dev-only visual overlay for the safe-area polygon computed by
+ * {@link ./safePolygon#safePolygon}. Lets you see the polygon the
+ * leave-detection logic is actually testing against, so shape regressions
+ * (e.g. "this doesn't look like a funnel at all") are debuggable from the
+ * browser instead of via unit tests alone.
+ *
+ * Design:
+ * - Off by default. Zero work when disabled.
+ * - One singleton `<svg>` overlay attached to `document.body` on first enable.
+ * - Per-area polygons keyed by string id; replace-or-clear by id.
+ * - Toggle from any code path:
+ *     enableSafeAreaDebug();   // turn on
+ *     disableSafeAreaDebug();  // turn off
+ */
+const COLORS = ["#ff3b30", "#34c759", "#5ac8fa", "#ff9500", "#af52de", "#ff2d55"];
+let enabled = false;
+let overlay = null;
+const entries = new Map();
+let nextColorIndex = 0;
+const ensureOverlay = () => {
+    if (typeof document === "undefined")
+        return null;
+    if (overlay !== null && overlay.isConnected)
+        return overlay;
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("data-safe-area-debug", "");
+    svg.style.position = "fixed";
+    svg.style.inset = "0";
+    svg.style.width = "100vw";
+    svg.style.height = "100vh";
+    svg.style.pointerEvents = "none";
+    svg.style.zIndex = "2147483600";
+    document.body.appendChild(svg);
+    overlay = svg;
+    return svg;
+};
+const removeOverlay = () => {
+    if (overlay !== null && overlay.isConnected) {
+        overlay.remove();
+    }
+    overlay = null;
+};
+const polygonPath = (polygon) => {
+    if (polygon.length === 0)
+        return "";
+    const head = polygon[0];
+    if (head === undefined)
+        return "";
+    const segments = [`M ${head.x} ${head.y}`];
+    for (let i = 1; i < polygon.length; i++) {
+        const p = polygon[i];
+        if (p === undefined)
+            continue;
+        segments.push(`L ${p.x} ${p.y}`);
+    }
+    segments.push("Z");
+    return segments.join(" ");
+};
+const render = () => {
+    const svg = ensureOverlay();
+    if (svg === null)
+        return;
+    while (svg.firstChild !== null)
+        svg.removeChild(svg.firstChild);
+    for (const entry of entries.values()) {
+        // Safe-area polygon: filled translucent + dashed stroke so the shape is
+        // immediately visible against the underlying content.
+        if (entry.polygon.length >= 3) {
+            const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+            path.setAttribute("d", polygonPath(entry.polygon));
+            path.setAttribute("fill", entry.color);
+            path.setAttribute("fill-opacity", "0.15");
+            path.setAttribute("stroke", entry.color);
+            path.setAttribute("stroke-width", "1.5");
+            path.setAttribute("stroke-dasharray", "4 3");
+            svg.appendChild(path);
+        }
+        // Input rects: dotted outlines so you can see what we're hulling.
+        for (const rect of entry.rects) {
+            if (rect === null)
+                continue;
+            const r = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+            r.setAttribute("x", String(rect.left));
+            r.setAttribute("y", String(rect.top));
+            r.setAttribute("width", String(Math.max(rect.width, 1)));
+            r.setAttribute("height", String(Math.max(rect.height, 1)));
+            r.setAttribute("fill", "none");
+            r.setAttribute("stroke", entry.color);
+            r.setAttribute("stroke-width", "1");
+            r.setAttribute("stroke-dasharray", "2 2");
+            r.setAttribute("opacity", "0.9");
+            svg.appendChild(r);
+        }
+    }
+};
+/**
+ * Enable the debug overlay. Idempotent. Persists until {@link disableSafeAreaDebug}
+ * is called or the page reloads.
+ */
+const enableSafeAreaDebug = () => {
+    if (enabled)
+        return;
+    enabled = true;
+    ensureOverlay();
+    render();
+};
+/**
+ * Disable the overlay, remove the SVG element, and forget all registered
+ * safe areas. Call when you're done debugging.
+ */
+const disableSafeAreaDebug = () => {
+    enabled = false;
+    entries.clear();
+    removeOverlay();
+};
+/** Read-only check used by the wiring hooks to skip work when off. */
+const isSafeAreaDebugEnabled = () => enabled;
+/**
+ * Register or update a safe-area polygon. Use a stable id per active hover so
+ * repeated calls during pointermove/animation update the same shape in place.
+ */
+const renderSafeArea = (id, polygon, rects) => {
+    if (!enabled)
+        return;
+    let entry = entries.get(id);
+    if (entry === undefined) {
+        const color = COLORS[nextColorIndex % COLORS.length] ?? "#ff3b30";
+        nextColorIndex++;
+        entry = { polygon, rects, color };
+    }
+    else {
+        entry = { ...entry, polygon, rects };
+    }
+    entries.set(id, entry);
+    render();
+};
+/** Remove a registered safe area by id. No-op if id is unknown. */
+const clearSafeArea = (id) => {
+    if (!enabled)
+        return;
+    if (entries.delete(id))
+        render();
+};
+
+/**
+ * Filter `rects` to those on the "cursor side" of an opposing rect, preventing
+ * the safe-area polygon from extending into a corridor the cursor has clearly
+ * turned away from.
+ *
+ * For every pair of rects (R, S) in the input where the cursor is NOT inside R:
+ * if the cursor is on the opposite side of S from R (along the S→R axis,
+ * tested via the sign of `dot(cursor − centerS, centerR − centerS)`), R is
+ * dropped. Concretely: when cursor is at the entry-rect side of the marker and
+ * moving away from the floating live-rect (e.g. stick-marker pill), the live
+ * rect is dropped so the polygon does not include it. Rects the cursor is
+ * inside are always kept.
+ *
+ * Pure function. Returns the filtered list in the original order.
+ */
+const filterRectsByCursorDirection = (rects, cursorX, cursorY) => {
+    const present = [];
+    for (let i = 0; i < rects.length; i++) {
+        const r = rects[i];
+        if (r === undefined || r === null)
+            continue;
+        const cx = (r.left + r.right) / 2;
+        const cy = (r.top + r.bottom) / 2;
+        const insideCursor = cursorX >= r.left && cursorX <= r.right && cursorY >= r.top && cursorY <= r.bottom;
+        present.push({ rect: r, index: i, cx, cy, insideCursor });
+    }
+    const dropped = new Set();
+    for (const r of present) {
+        if (r.insideCursor)
+            continue;
+        for (const s of present) {
+            if (s.index === r.index)
+                continue;
+            if (s.insideCursor) {
+                // Cursor is inside S: anything S→R-pointing past S still belongs to
+                // the corridor; do not drop based on this S.
+                continue;
+            }
+            const sToRx = r.cx - s.cx;
+            const sToRy = r.cy - s.cy;
+            const sToCursorX = cursorX - s.cx;
+            const sToCursorY = cursorY - s.cy;
+            const dot = sToRx * sToCursorX + sToRy * sToCursorY;
+            if (dot < 0) {
+                dropped.add(r.index);
+                break;
+            }
+        }
+    }
+    return rects.map((r, i) => (dropped.has(i) ? null : r));
+};
+/**
+ * Build a hover-safe convex-hull polygon spanning every input rect. Each
+ * non-null rect contributes its four corners (outward-buffered by `bufferPx`)
+ * and the result is the convex hull of all collected corners.
+ *
+ * Inspired by Floating UI's `safePolygon` middleware (used by `useHover` to
+ * keep menus open while the cursor travels toward them). The difference: that
+ * implementation builds a pointer-to-single-rect triangle for the standard
+ * trigger ↔ floating-element relationship; this one accepts an arbitrary list
+ * of rects so a single safe area can span N visible targets — e.g. a stick
+ * marker's pill at the tip, an entry-time snapshot of the same pill (used as
+ * an animation grace area), and the geographic anchor at the stick's base.
+ *
+ * The hull is angle-agnostic: it hugs the visible elements at any layout and
+ * naturally excludes the dead corners that an axis-aligned bounding box would
+ * include. Returns an empty polygon when no rects were provided; callers
+ * should treat that as "no safe area" (any cursor position is outside).
+ */
+const safePolygon = (rects, bufferPx) => {
+    const points = [];
+    for (const rect of rects) {
+        if (rect === null)
+            continue;
+        points.push(...bufferRectCorners(rect, bufferPx));
+    }
+    return convexHull(points);
+};
+
+let nextDebugId = 0;
+/**
+ * Generate a unique id for one active hover instance. Exposed so callers that
+ * orchestrate multiple watchers (e.g. {@link ./attachSafeAreaHoverListeners})
+ * can pre-allocate one id and pass it in, so the debug overlay shows a single
+ * polygon entry across the listener's lifecycle.
+ */
+const allocSafeAreaDebugId = (label) => `${label}-${++nextDebugId}`;
+/**
+ * Listen for genuine pointer departure from a DOM marker's safe area. The
+ * watcher consults `getHitSurfaceRect` on every pointermove; when the inner
+ * query returns nothing transiently (mid-mount, mid-collapse), it falls back
+ * to the most recent non-empty rect seen.
+ *
+ * `entryRect` is the hit-surface rect captured at `mouseenter` time. It acts
+ * as a second stable reference so that when the element animates away from a
+ * stationary cursor (e.g. stick marker expanding from anchor to tip), the
+ * watcher does not fire `onLeave` while the cursor is still inside the
+ * original entry area.
+ *
+ * Returns a cancel function. Caller is responsible for invoking it on
+ * hover-end and on cleanup.
+ */
+const watchSafeAreaLeave = (host, onLeave, entryRect, debugId) => {
+    let rememberedRect = getHitSurfaceRect(host);
+    const fixedEntryRect = entryRect ?? null;
+    const id = debugId ?? allocSafeAreaDebugId("watcher");
+    const handler = (pe) => {
+        const liveRect = getHitSurfaceRect(host);
+        if (liveRect !== null) {
+            rememberedRect = liveRect;
+        }
+        else if (!host.isConnected) {
+            // Element removed from DOM — self-cancel without firing onLeave.
+            document.removeEventListener("pointermove", handler);
+            clearSafeArea(id);
+            return;
+        }
+        const rect = liveRect ?? rememberedRect;
+        if (rect === null)
+            return;
+        const anchorRect = getAnchorRect(host);
+        const filtered = filterRectsByCursorDirection([rect, fixedEntryRect, anchorRect], pe.clientX, pe.clientY);
+        const polygon = safePolygon(filtered, SAFE_AREA_DEFAULT_BUFFER_PX);
+        if (isSafeAreaDebugEnabled()) {
+            renderSafeArea(id, polygon, filtered);
+        }
+        const inside = pointInPolygon(pe.clientX, pe.clientY, polygon);
+        if (!inside)
+            onLeave();
+    };
+    const cancel = () => {
+        document.removeEventListener("pointermove", handler);
+        clearSafeArea(id);
+    };
+    document.addEventListener("pointermove", handler, { passive: true });
+    return cancel;
+};
+
+/**
+ * Attach `mouseenter` and `mouseleave` listeners to a DOM marker element with
+ * the full spurious-mouseleave-safe hover contract:
+ *
+ * - Records the hit-surface rect at entry time (`hoverEntryRect`).
+ * - On `mouseleave`, computes the safe area: convex hull of the live hit
+ *   surface, the entry rect, and the anchor rect. If the pointer is still
+ *   inside, installs a {@link watchSafeAreaLeave} instead of firing onLeave
+ *   immediately.
+ * - Cancels any watcher from a previous marker (via the shared `state` box)
+ *   when a new `mouseenter` arrives.
+ *
+ * Both `MapboxLayerPort` and `GoogleMapsLayerPort` share this implementation
+ * so the safe-area logic has one source of truth.
+ */
+const attachSafeAreaHoverListeners = (el, onEnter, onLeave, state) => {
+    let cancelWatcher = null;
+    let hoverEntryRect = null;
+    // Timestamp of the most recent honoured `mouseenter`. When `mouseleave`
+    // fires within the marker's morph window of this, the polygon at that
+    // instant may not yet include the materialising pill rect (e.g. cursor
+    // crossed the round-indicator boundary while the pill is still scaling up
+    // from the anchor); fall back to installing the watcher so its polling
+    // catches the pill once it renders, instead of firing onLeave on an
+    // incomplete polygon.
+    let lastEnterTime = 0;
+    const MORPH_GRACE_MS = 250;
+    // Set to true once the cursor has been observed inside the current live hit
+    // surface during this hover session. While still false, `hoverEntryRect`
+    // contributes to the safe-area polygon (grace area for marker morphs that
+    // shrink under the cursor). Once true, the cursor has demonstrably acquired
+    // the new (smaller) hit surface — the entry rect grace is dropped so leaving
+    // the live surface closes the marker on the next move.
+    let cursorAcquiredLiveSurface = false;
+    // Re-entry guard: set to `true` when the close path fires `onLeave`. While
+    // it's `true`, fresh `mouseenter` events on `el` are swallowed (the consumer
+    // never sees a hover-start). The guard clears when a `pointermove` observes
+    // the cursor outside the accumulated footprint envelope — i.e. the cursor
+    // has visibly left the marker's footprint, so any future mouseenter is a
+    // deliberate re-hover. Without this guard the stick → round
+    // morph-back grows the hit surface around a near-stationary cursor and
+    // fires a phantom mouseenter that re-arms the cycle.
+    let pendingReentryGuard = false;
+    let suppressedSinceEnter = false;
+    // Footprint to test the cursor against while the guard is active. Built as
+    // the union of every hit-surface rect ever observed for this `el` — the
+    // morph-back round indicator falls inside this max-rect by definition, so
+    // the guard correctly stays armed while the cursor is over any pixel the
+    // marker has ever occupied. Cleared (and the union restarted) when the
+    // guard clears, so the next hover session builds its own envelope.
+    let guardFootprintRect = null;
+    const expandFootprint = (rect) => {
+        if (rect === null || rect.width === 0 || rect.height === 0)
+            return;
+        if (guardFootprintRect === null) {
+            guardFootprintRect = rect;
+            return;
+        }
+        const left = Math.min(guardFootprintRect.left, rect.left);
+        const top = Math.min(guardFootprintRect.top, rect.top);
+        const right = Math.max(guardFootprintRect.right, rect.right);
+        const bottom = Math.max(guardFootprintRect.bottom, rect.bottom);
+        guardFootprintRect = new DOMRect(left, top, right - left, bottom - top);
+    };
+    const debugId = allocSafeAreaDebugId("hover");
+    // rAF loop that re-renders the debug overlay each frame while the marker is
+    // hovered — the pill animates outward from the anchor, so a static snapshot
+    // would not match the visible state. Stops on hover-end.
+    let debugRafHandle = 0;
+    const stopDebugLoop = () => {
+        if (debugRafHandle !== 0) {
+            cancelAnimationFrame(debugRafHandle);
+            debugRafHandle = 0;
+        }
+        clearSafeArea(debugId);
+    };
+    const startDebugLoop = () => {
+        if (!isSafeAreaDebugEnabled())
+            return;
+        const tick = () => {
+            if (!isSafeAreaDebugEnabled()) {
+                debugRafHandle = 0;
+                return;
+            }
+            const liveRect = getHitSurfaceRect(el);
+            const anchorRect = getAnchorRect(el);
+            if (liveRect !== null) {
+                // While `mouseenter` is active the cursor is over the marker; show the
+                // unfiltered convex hull (the funnel-grace area) rather than running
+                // the directional filter against a stale pointer.
+                const polygon = safePolygon([liveRect, hoverEntryRect, anchorRect], SAFE_AREA_DEFAULT_BUFFER_PX);
+                renderSafeArea(debugId, polygon, [liveRect, hoverEntryRect, anchorRect]);
+            }
+            debugRafHandle = requestAnimationFrame(tick);
+        };
+        debugRafHandle = requestAnimationFrame(tick);
+    };
+    // pointermove sampled while the cursor is over `el`. Two jobs: (1) detect
+    // when the cursor enters a *shrunk* live hit surface so the entry-rect
+    // grace can be dropped (see `cursorAcquiredLiveSurface`); (2) keep the
+    // footprint envelope up to date so the re-entry guard has an accurate
+    // bound when armed.
+    const pointerMoveDuringHover = (pe) => {
+        const live = getHitSurfaceRect(el);
+        if (live === null && !el.isConnected) {
+            // Element removed from DOM — remove the document listener.
+            document.removeEventListener("pointermove", pointerMoveDuringHover);
+            return;
+        }
+        expandFootprint(live);
+        if (cursorAcquiredLiveSurface)
+            return;
+        if (live === null || hoverEntryRect === null)
+            return;
+        const liveArea = live.width * live.height;
+        const entryArea = hoverEntryRect.width * hoverEntryRect.height;
+        if (liveArea >= entryArea)
+            return;
+        if (pe.clientX < live.left || pe.clientX > live.right)
+            return;
+        if (pe.clientY < live.top || pe.clientY > live.bottom)
+            return;
+        cursorAcquiredLiveSurface = true;
+    };
+    const pointInRect = (x, y, r) => r !== null && x >= r.left && x <= r.right && y >= r.top && y <= r.bottom;
+    const removeGuardListener = () => {
+        document.removeEventListener("pointermove", pointerMoveDuringGuard);
+        if (state.activeGuardCancel === cancelReentryGuard) {
+            state.activeGuardCancel = null;
+        }
+    };
+    const cancelReentryGuard = () => {
+        removeGuardListener();
+        pendingReentryGuard = false;
+        guardFootprintRect = null;
+        hoverEntryRect = null;
+        cursorAcquiredLiveSurface = false;
+    };
+    // pointermove sampled while the re-entry guard is active. Continues to
+    // expand the footprint envelope so a still-growing morph-back stays
+    // covered; clears the guard the moment the cursor is outside the
+    // accumulated envelope.
+    const pointerMoveDuringGuard = (pe) => {
+        const live = getHitSurfaceRect(el);
+        if (live === null && !el.isConnected) {
+            cancelReentryGuard();
+            return;
+        }
+        expandFootprint(live);
+        if (!pointInRect(pe.clientX, pe.clientY, guardFootprintRect)) {
+            cancelReentryGuard();
+        }
+    };
+    const armReentryGuard = () => {
+        removeGuardListener();
+        pendingReentryGuard = true;
+        // Seed the envelope with everything we know about the marker's geometry
+        // — the current live rect, the hover entry rect (largest non-stick state
+        // for this session), and the anchor point. The pointermove handler will
+        // continue expanding the envelope as the morph-back materialises.
+        expandFootprint(getHitSurfaceRect(el));
+        expandFootprint(hoverEntryRect);
+        expandFootprint(getAnchorRect(el));
+        document.addEventListener("pointermove", pointerMoveDuringGuard, { passive: true });
+        state.activeGuardCancel = cancelReentryGuard;
+    };
+    el.addEventListener("mouseenter", (e) => {
+        // Suppress re-mouseenter if the re-entry guard is still armed — the
+        // cursor has not yet visibly left the marker's footprint since the last
+        // close, so this enter is the morph-back artefact, not an intentional
+        // re-hover.
+        if (pendingReentryGuard) {
+            suppressedSinceEnter = true;
+            return;
+        }
+        suppressedSinceEnter = false;
+        lastEnterTime = Date.now();
+        state.activeWatcherCancel?.();
+        state.activeWatcherCancel = null;
+        state.activeGuardCancel?.();
+        state.activeGuardCancel = null;
+        cancelWatcher = null;
+        const previousEntryRect = hoverEntryRect;
+        hoverEntryRect = getHitSurfaceRect(el);
+        expandFootprint(hoverEntryRect);
+        // Acquisition test: if the new entry rect is meaningfully smaller than the
+        // previous one AND the cursor is inside it, the user has visibly acquired
+        // the smaller hit surface — drop the entry-rect grace from now on.
+        cursorAcquiredLiveSurface =
+            hoverEntryRect !== null &&
+                e.clientX >= hoverEntryRect.left &&
+                e.clientX <= hoverEntryRect.right &&
+                e.clientY >= hoverEntryRect.top &&
+                e.clientY <= hoverEntryRect.bottom &&
+                previousEntryRect !== null &&
+                hoverEntryRect.width * hoverEntryRect.height < previousEntryRect.width * previousEntryRect.height;
+        document.addEventListener("pointermove", pointerMoveDuringHover, { passive: true });
+        onEnter();
+        startDebugLoop();
+    });
+    el.addEventListener("mouseleave", (e) => {
+        document.removeEventListener("pointermove", pointerMoveDuringHover);
+        // If the matching `mouseenter` was suppressed, the consumer never observed
+        // hover-start; skip onLeave too. The guard is already armed and tracking
+        // the cursor — leave it in place so it covers consecutive morph cycles.
+        if (suppressedSinceEnter) {
+            return;
+        }
+        const rect = getHitSurfaceRect(el);
+        const anchorRect = getAnchorRect(el);
+        expandFootprint(rect);
+        expandFootprint(anchorRect);
+        // Once the cursor has acquired the (smaller) live hit surface, the entry
+        // rect grace zone is stale — exclude it so leaving the live surface
+        // closes the marker promptly.
+        const entryRectForPolygon = cursorAcquiredLiveSurface ? null : hoverEntryRect;
+        const pointerInsideSafeArea = (() => {
+            if (rect === null)
+                return false;
+            const filtered = filterRectsByCursorDirection([rect, entryRectForPolygon, anchorRect], e.clientX, e.clientY);
+            const polygon = safePolygon(filtered, SAFE_AREA_DEFAULT_BUFFER_PX);
+            return pointInPolygon(e.clientX, e.clientY, polygon);
+        })();
+        // Morph grace: if mouseleave fires within the marker's morph-in window of
+        // mouseenter, the polygon may not yet include the materialising stick pill
+        // (cursor crossed the round-indicator boundary while the pill is still
+        // scaling up from the anchor). Defer the close decision to the watcher
+        // whose polling will catch the pill once it renders.
+        const insideMorphWindow = lastEnterTime !== 0 && Date.now() - lastEnterTime < MORPH_GRACE_MS;
+        // Spurious if: no usable rect, pointer is still within the safe-area
+        // polygon (convex hull of live hit surface ∪ entry rect ∪ anchor), or
+        // we're still within the morph-in window where the pill is materialising.
+        if (rect === null || pointerInsideSafeArea || insideMorphWindow) {
+            cancelWatcher?.();
+            cancelWatcher = watchSafeAreaLeave(el, () => {
+                onLeave();
+                armReentryGuard();
+                cancelWatcher?.();
+                cancelWatcher = null;
+                state.activeWatcherCancel = null;
+                stopDebugLoop();
+            }, entryRectForPolygon, debugId);
+            state.activeWatcherCancel = cancelWatcher;
+        }
+        else {
+            onLeave();
+            armReentryGuard();
+            cancelWatcher?.();
+            cancelWatcher = null;
+            state.activeWatcherCancel = null;
+            stopDebugLoop();
+        }
+    });
+};
+
+// TODO (next PR): shapeStyleDefaults computes visual defaults for shapes — a map consumer
+// concern, not an adapter concern. Make these injectable from react-map's createMapComponent
+// so adapters don't need to know about default visual styles.
+const SHAPE_STYLE_DEFAULTS = {
+    polygon: {
+        fillOpacity: 0.05,
+        strokeWidth: 1,
+        strokeOpacity: 1,
+    },
+    line: {
+        strokeWidth: 1,
+        strokeOpacity: 1,
+    },
+    point: {
+        fillOpacity: 0.2,
+        strokeWidth: 1,
+        strokeOpacity: 1,
+        pointRadius: 5,
+    },
+};
+// ============================================================================
+// Interaction style constants
+// ============================================================================
+const HOVER_COLOR_SHIFT = 15;
+const SELECTED_COLOR_SHIFT = 25;
+// ============================================================================
+// Interaction style resolution
+// ============================================================================
+/**
+ * Resolve the visual style for a hovered shape.
+ *
+ * User-provided `base.hovered` overrides take priority; missing properties
+ * fall back to auto-computed defaults (darkened/lightened stroke based on theme).
+ */
+const resolveHoveredStyle = (base, _shapeType, theme) => {
+    const userOverrides = base.hovered;
+    const baseStroke = base.stroke ?? "#000000";
+    const autoStroke = theme === "dark" ? lightenColor(baseStroke, HOVER_COLOR_SHIFT) : darkenColor(baseStroke, HOVER_COLOR_SHIFT);
+    return {
+        fill: userOverrides?.fill ?? base.fill,
+        fillOpacity: userOverrides?.fillOpacity ?? base.fillOpacity,
+        stroke: userOverrides?.stroke ?? autoStroke,
+        strokeOpacity: userOverrides?.strokeOpacity ?? base.strokeOpacity,
+        strokeWidth: userOverrides?.strokeWidth ?? base.strokeWidth,
+    };
+};
+/**
+ * Resolve the visual style for a selected shape.
+ *
+ * User-provided `base.selected` overrides take priority; missing properties
+ * fall back to auto-computed defaults (darkened/lightened stroke based on theme,
+ * stronger shift than hover).
+ */
+const resolveSelectedStyle = (base, _shapeType, theme) => {
+    const userOverrides = base.selected;
+    const baseStroke = base.stroke ?? "#000000";
+    const autoStroke = theme === "dark" ? lightenColor(baseStroke, SELECTED_COLOR_SHIFT) : darkenColor(baseStroke, SELECTED_COLOR_SHIFT);
+    return {
+        fill: userOverrides?.fill ?? base.fill,
+        fillOpacity: userOverrides?.fillOpacity ?? base.fillOpacity,
+        stroke: userOverrides?.stroke ?? autoStroke,
+        strokeOpacity: userOverrides?.strokeOpacity ?? base.strokeOpacity,
+        strokeWidth: userOverrides?.strokeWidth ?? base.strokeWidth,
+    };
+};
+// ============================================================================
+// Stroke color variants
+// ============================================================================
+/**
+ * Returns the base, hovered, and selected stroke colors for a shape in one call.
+ * Backed by the module-level color cache in colorUtils, so repeated calls with
+ * the same inputs are cheap Map lookups.
+ */
+const resolveStrokeColors = (style, shapeType, theme) => {
+    const base = style.stroke ?? "#000";
+    return {
+        base,
+        hovered: resolveHoveredStyle(style, shapeType, theme).stroke ?? base,
+        selected: resolveSelectedStyle(style, shapeType, theme).stroke ?? base,
+    };
+};
+
+export { ANCHOR_SELECTOR, CIRCLE_SYMBOL_DEFAULT_DIAMETER_PX, CIRCLE_SYMBOL_DEFAULT_OPACITY, DEFAULT_CENTER, DEFAULT_MAP_APPEARANCE, DEFAULT_ZOOM, HIT_SURFACE_SELECTOR, INITIAL_CAMERA_STATE, INITIAL_INTERACTION_STATE, INITIAL_MAP_STATE, INITIAL_MAP_STATUS, KEYBOARD_PAN_AMOUNT, KEYBOARD_ZOOM_AMOUNT, LAYER_FADE_DURATION_MS, MAP_CURSORS, MAX_ZOOM, MIN_ZOOM, SAFE_AREA_DEFAULT_BUFFER_PX, SHAPE_STYLE_DEFAULTS, WORLD_BBOX, allocSafeAreaDebugId, anchorFromBottomCenter, attachSafeAreaHoverListeners, bboxEquals, bufferRectCorners, buildAdaptiveDomEntries, buildAdaptiveDomRenderFn, buildAdaptiveSymbolStyleFn, cameraStateEquals, canPatchAdaptiveMarker, canPatchAdaptiveViewport, canPatchMarkerInPlace, clearSafeArea, collectFeatureIdSet, colorWithOpacity, computeInitialState, computeMarkerDomPortalZIndex, convexHull, createClusterPinElement, createDefaultClusterElement, createSymbolDotElement, darkenColor, defineAdapter, disableSafeAreaDebug, discriminateRenderResult, enableSafeAreaDebug, estimateZoomFromBounds, extractLineCoordinates, extractPointCoordinates, extractPolygonPaths, extractSourceData, fadeInElement, filterRectsByCursorDirection, geometryTypeToShapeType, getAdaptiveDomFeatureIds, getAnchorRect, getEffectiveRestrictBounds, getHitSurfaceRect, hasSameFeatureIds, isCanvasMarkerMode, isEventOfType, isSafeAreaDebugEnabled, lightenColor, mapAppearanceSchema, mapStateEquals, mapThemeSchema, mapTypeSchema, mercatorCenterFromBounds, mergeAntimeridianFeatures, mixColor, patchPortalDescriptors, pointInPolygon, removeGoneIndexedMarkers, renderSafeArea, resetColorUtilsForTesting, resolveCircleSymbolDefaults, resolveHoveredStyle, resolveSelectedStyle, resolveStrokeColors, resolveSymbolDescriptor, safePolygon, validateInitialViewport, watchSafeAreaLeave };