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

package/src/markerTypes.d.ts

@@ -0,0 +1,352 @@
+import type { GeoJsonBbox, GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { DomPortalStackingInput, DomPortalStackingResult } from "./markerDomPortalStacking";
+import type { MapTheme } from "./primitiveMapTypes";
+type ReactNode = import("react").ReactNode;
+export type { DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, } from "./markerDomPortalStacking";
+export { computeMarkerDomPortalZIndex } from "./markerDomPortalStacking";
+/**
+ * The medium an adaptive marker is rendered through: a map-native symbol
+ * (WebGL/canvas circle) or a DOM portal. The indicator-vs-stick distinction
+ * is a component-level concern (signaled by `MapMarker`'s `stickPositioning`
+ * presence), not part of the adaptive vocabulary (ADR-0009 / ADR-0010).
+ */
+export type RenderMedium = "symbol" | "dom";
+/**
+ * Fields common to every render-state shape (ADR-0009).
+ *
+ * Threaded through `<Layers>`; passed to `render` callbacks regardless of
+ * mode or medium so consumers can branch on selection / hover / theme without
+ * looking these up themselves.
+ */
+export type CommonRenderState = Readonly<{
+    selected: boolean;
+    hovered: boolean;
+    /** Basemap theme from `Map` appearance (threaded through `<Layers>`). */
+    theme: MapTheme;
+}>;
+/**
+ * Render-state for `mode: "symbol"` and the symbol arm of `mode: "adaptive"`
+ * (ADR-0009).
+ *
+ * Symbol render returns a {@link CircleSymbolDescriptor}; no DOM-only fields
+ * (`labelVisible`, `isMounting`) are surfaced here — they have no meaning for
+ * a WebGL/canvas circle.
+ */
+export type SymbolRenderState = CommonRenderState & Readonly<{
+    medium: "symbol";
+}>;
+/**
+ * Render-state for `mode: "dom"` and the DOM arm of `mode: "adaptive"`
+ * (ADR-0009).
+ *
+ * - `labelVisible`: `false` when collision avoidance forces the marker to
+ *   stay in circle form (plan §4 / §8). DOM-only.
+ * - `isMounting`: `true` for the very first frame after a symbol→DOM
+ *   transition so consumers can suppress the "first-paint" entry animation
+ *   on adaptive markers. Always `false` until slice 6 (SAGA-424) introduces
+ *   `useMarkerMountBridge`.
+ */
+export type DomRenderState = CommonRenderState & Readonly<{
+    medium: "dom";
+    labelVisible: boolean;
+    isMounting: boolean;
+}>;
+/**
+ * Render-state for `mode: "adaptive"` (ADR-0009).
+ *
+ * Discriminated on `medium`. Adaptive `render` is invoked with whichever
+ * shape matches the medium chosen by `resolveMode` for the current frame.
+ */
+export type AdaptiveRenderState = SymbolRenderState | DomRenderState;
+/**
+ * Inputs to `resolveMode` for adaptive rendering.
+ */
+export type AdaptiveResolutionContext = Readonly<{
+    zoom: number;
+    markersInViewport: number;
+    isHovered: boolean;
+    isSelected: boolean;
+}>;
+/**
+ * Inputs to `resolveGroups` for cluster entity-shape decisions (ADR-0016).
+ *
+ * Mirrors {@link AdaptiveResolutionContext} but adds `viewportBounds` so the
+ * consumer can branch on geographic extent in addition to zoom and density.
+ */
+export type ResolutionContext = Readonly<{
+    zoom: number;
+    markersInViewport: number;
+    isHovered: boolean;
+    isSelected: boolean;
+    viewportBounds: GeoJsonBbox | null;
+}>;
+/**
+ * Render-state passed as the second argument to `clusterRender`'s render
+ * callback (ADR-0016).
+ *
+ * Extends {@link CommonRenderState} with `memberItems` — the cluster's
+ * members cross-referenced from the hook's `data` array via `getMarkerIds`.
+ * Null when any member ID is missing from the index (the consumer cannot
+ * resolve the full member set in this frame).
+ *
+ * Cluster renders never receive the marker-only fields `medium`,
+ * `labelVisible`, or `isMounting` — clusters have no adaptive symbol↔DOM
+ * transition (ADR-0016: `MapCluster` is DOM-only; symbol cluster mode still
+ * returns a static {@link SymbolDescriptor}) and no per-item collision label.
+ */
+export type ClusterRenderState<TItem> = CommonRenderState & Readonly<{
+    memberItems: ReadonlyArray<TItem> | null;
+}>;
+/**
+ * Symbol cluster render: cluster bubble drawn as a map-native circle
+ * (WebGL/canvas) sized to the cluster count.
+ *
+ * Receives {@link ClusterRenderState} — `memberItems` is always `null` here
+ * because the symbol pipeline doesn't materialize the member set; consumers
+ * that need `memberItems` should use {@link ClusterDomRenderConfig}.
+ */
+export type ClusterSymbolRenderConfig<TCluster, TItem> = Readonly<{
+    mode: "symbol";
+    render(cluster: TCluster, state: ClusterRenderState<TItem>): SymbolDescriptor;
+}>;
+/**
+ * DOM cluster render: cluster bubble rendered as a React subtree inside a
+ * portal positioned by the adapter.
+ *
+ * Receives {@link ClusterRenderState} with `memberItems` cross-referenced
+ * from the hook's `data` array via `getMarkerIds`. Consumers can use it to
+ * build the `sticks` array for `MapCluster` directly, without maintaining
+ * a separate lookup table.
+ */
+export type ClusterDomRenderConfig<TCluster, TItem> = Readonly<{
+    mode: "dom";
+    /** Anchor position relative to the cluster coordinate. */
+    anchor: MarkerAnchor;
+    /** Additional pixel displacement applied after anchor alignment. */
+    pixelOffset?: PixelOffset;
+    /** Optional portal stacking resolver, mirrors {@link DomRenderConfig.resolveDomPortalStacking}. */
+    resolveDomPortalStacking?(cluster: TCluster, input: DomPortalStackingInput): DomPortalStackingResult;
+    render(cluster: TCluster, state: ClusterRenderState<TItem>): ReactNode;
+}>;
+/**
+ * Cluster render configuration (ADR-0016).
+ *
+ * Unlike marker `RenderConfig`, clusters have no `adaptive` mode — the
+ * cluster entity-shape decision is owned by the `resolveGroups` callback,
+ * and `MapCluster` is DOM-only. If a future cluster type needs symbol↔DOM
+ * adaptive rendering, it can be added without breaking changes by extending
+ * this union.
+ */
+export type ClusterRenderConfig<TCluster, TItem> = Readonly<ClusterSymbolRenderConfig<TCluster, TItem> | ClusterDomRenderConfig<TCluster, TItem>>;
+/**
+ * Anchor position for a marker relative to its coordinate.
+ * WebGL circle layers (Mapbox) are always center-anchored; this field
+ * is consumed by DOM-based markers (Google Maps, promoted overlays).
+ */
+export type MarkerAnchor = "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/**
+ * Additional pixel displacement applied after anchor alignment.
+ * Positive x moves right, positive y moves down (screen coordinates).
+ */
+export type PixelOffset = Readonly<{
+    x: number;
+    y: number;
+}>;
+/**
+ * Provider-agnostic descriptor for a circular symbol marker (WebGL/canvas).
+ * Per ADR-0011: the only symbol kind today is a circle; explicit pixel sizing
+ * (no unitless `scale`) and opt-in border (no implicit white stroke).
+ */
+export type CircleSymbolDescriptor = Readonly<{
+    /** Fill color as a CSS color string. */
+    color: string;
+    /** Diameter in pixels. Default: 16. */
+    diameterPx?: number;
+    /** Opacity from 0 to 1. Default: 1. */
+    opacity?: number;
+    /** Border (stroke) color, or `null` for no border. Default: null. */
+    borderColor?: string | null;
+    /** Border (stroke) width in pixels. Default: 0. */
+    borderWidthPx?: number;
+}>;
+/**
+ * Symbol descriptor returned by symbol/adaptive render callbacks.
+ *
+ * Today this is exactly a {@link CircleSymbolDescriptor}. Kept as a type alias
+ * so a future symbol kind can extend it without breaking changes (the alias
+ * becomes a discriminated union with a `kind` discriminator defaulting to
+ * `"circle"`).
+ */
+export type SymbolDescriptor = CircleSymbolDescriptor;
+/**
+ * Provider-agnostic style for cluster symbols (separate from individual marker
+ * symbols since clusters carry a count label and dynamic sizing).
+ */
+export type ClusterSymbolStyle = Readonly<{
+    /** Background color of the cluster indicator */
+    color?: string;
+    /** Text color for the count label */
+    textColor?: string;
+    /** Size multiplier (1 = default) */
+    scale?: number;
+    /** Opacity from 0 to 1 */
+    opacity?: number;
+}>;
+/**
+ * Symbol mode: map-native rendering (WebGL/canvas), high performance.
+ *
+ * Note: `render` uses method syntax (bivariant) to allow type erasure at the
+ * layer handle boundary (`RenderConfig<TItem>` → `RenderConfig<unknown>`).
+ * For static styles, use `render: () => mySymbol`.
+ *
+ * Per ADR-0009, symbol mode receives a {@link SymbolRenderState}; per-item
+ * `selected` / `hovered` variations are not surfaced through this callback —
+ * they are handled by the adapter's paint expression / canvas redraw.
+ * `selected` and `hovered` are always `false` here.
+ */
+export type SymbolRenderConfig<TData> = Readonly<{
+    mode: "symbol";
+    /** Render per item. For static symbols use `() => mySymbol`. */
+    render(item: TData, state: SymbolRenderState): SymbolDescriptor;
+}>;
+/**
+ * DOM mode: React components, maximum flexibility.
+ *
+ * Per ADR-0009, DOM mode receives a {@link DomRenderState} with `medium: "dom"`
+ * plus the DOM-only fields `labelVisible` and `isMounting` (`isMounting` is
+ * always `false` until slice 6 / SAGA-424 wires `useMarkerMountBridge`).
+ */
+export type DomRenderConfig<TData> = Readonly<{
+    mode: "dom";
+    /**
+     * Anchor position relative to the coordinate. Anchor is geometric input
+     * (where the DOM box meets the geo coordinate), not a styling preference.
+     * Mirrors {@link AdaptiveRenderConfig.anchor}.
+     *
+     * Use `"center"` for plain indicator/stick markers rendered with `<MapMarker>`.
+     */
+    anchor: MarkerAnchor;
+    /** Additional pixel displacement applied after anchor alignment. */
+    pixelOffset?: PixelOffset;
+    /**
+     * Optional: map geometry + interaction phase → portal `z-index` via {@link computeMarkerDomPortalZIndex}.
+     * Omit to keep legacy interaction-only stacking (equivalent to `circle` + selected/hover/idle).
+     */
+    resolveDomPortalStacking?(item: TData, input: DomPortalStackingInput): DomPortalStackingResult;
+    /**
+     * Render function. Receives the original data item and interaction state.
+     *
+     * Custom DOM markers can opt into the same hover-safe-area behavior as
+     * `<MapMarker>` by adding `data-map-marker-hit-surface` to the visible
+     * interactive element and, when the visible surface is spatially separated
+     * from the geographic anchor, `data-map-marker-anchor` to the anchor element.
+     * See `HIT_SURFACE_SELECTOR` and `ANCHOR_SELECTOR`.
+     */
+    render(item: TData, state: DomRenderState): ReactNode;
+}>;
+/**
+ * Adaptive mode: each item is either a WebGL/canvas symbol or a DOM marker,
+ * chosen per frame by `resolveMode` (plan §8).
+ *
+ * Per ADR-0009, a single `render(item, state)` callback covers both media.
+ * `state.medium` discriminates: when it is `"symbol"` the callback must
+ * return a {@link SymbolDescriptor}; when it is `"dom"` it must return a
+ * `ReactNode`. Adapters route the result via
+ * `discriminateRenderResult`.
+ *
+ * `anchor` and `pixelOffset` apply to the DOM-medium branch (mirrors
+ * {@link DomRenderConfig}); the symbol branch is map-native and ignores them.
+ *
+ * Note: `render` uses method syntax (bivariant) to allow type erasure at
+ * the layer-handle boundary (`RenderConfig<TItem>` → `RenderConfig<unknown>`).
+ */
+export type AdaptiveRenderConfig<TData> = Readonly<{
+    mode: "adaptive";
+    /**
+     * Anchor for DOM-medium renders. Symbol circles are always center-anchored,
+     * so DOM indicators should use `"center"` unless you have a deliberate reason
+     * to deviate.
+     *
+     * Use `"center"` for plain indicator/stick markers rendered with `<MapMarker>`.
+     */
+    anchor: MarkerAnchor;
+    /** Pixel offset for DOM-medium renders. */
+    pixelOffset?: PixelOffset;
+    /**
+     * Optional: DOM portal stacking; see {@link DomRenderConfig.resolveDomPortalStacking}.
+     * Invoked only when the resolved medium is `dom`.
+     */
+    resolveDomPortalStacking?(item: TData, input: DomPortalStackingInput): DomPortalStackingResult;
+    resolveMode(item: TData, ctx: AdaptiveResolutionContext): RenderMedium;
+    /**
+     * Called per item, per frame, with whichever render-state matches the
+     * medium chosen by {@link resolveMode}. Return a {@link SymbolDescriptor}
+     * for `state.medium === "symbol"` and a `ReactNode` for
+     * `state.medium === "dom"`.
+     *
+     * DOM-medium custom markers can opt into hover-safe-area detection with
+     * `data-map-marker-hit-surface` and `data-map-marker-anchor`; see
+     * {@link DomRenderConfig.render}.
+     */
+    render(item: TData, state: AdaptiveRenderState): SymbolDescriptor | ReactNode;
+}>;
+/**
+ * Per-feature modes computed in `<Layers>` for adaptive marker sources.
+ */
+export type AdaptiveMarkerResolution = Readonly<{
+    modesByFeatureId: ReadonlyMap<string, RenderMedium>;
+    previousModesByFeatureId: ReadonlyMap<string, RenderMedium>;
+}>;
+/**
+ * Discriminated union of all render configurations.
+ * Used for both marker rendering and cluster rendering.
+ */
+export type RenderConfig<TData> = Readonly<SymbolRenderConfig<TData> | DomRenderConfig<TData> | AdaptiveRenderConfig<TData>>;
+/**
+ * Information about a cluster produced by client-side clustering.
+ * This is what the adapter provides when it handles clustering internally.
+ */
+export type ClusterInfo = Readonly<{
+    id: string;
+    position: GeoJsonPosition;
+    markerIds: ReadonlyArray<string>;
+    count: number;
+    /** Extent of clustered members when known; null if not provided */
+    bbox: GeoJsonBbox | null;
+}>;
+/**
+ * Client-side clustering: the adapter handles clustering
+ * (Mapbox native, Google Supercluster, etc.)
+ */
+export type ClientClusterConfig = Readonly<{
+    mode: "client";
+    /** Cluster radius in pixels */
+    radius?: number;
+    /** Max zoom at which clusters are created */
+    maxZoom?: number;
+}>;
+/**
+ * Server-side clustering: clusters are pre-computed and provided as data.
+ * Generic over TCluster so the render function gets full access to the
+ * original server cluster object (e.g., breakdown counts, chart data).
+ */
+export type ServerClusterConfig<TCluster> = Readonly<{
+    mode: "server";
+    /** Pre-computed cluster data from the server */
+    data: ReadonlyArray<TCluster>;
+    /** Extract cluster center position */
+    getPosition(cluster: TCluster): GeoJsonPosition;
+    /** Extract cluster unique ID */
+    getId(cluster: TCluster): string;
+    /** Extract IDs of markers contained in this cluster */
+    getMarkerIds(cluster: TCluster): ReadonlyArray<string>;
+    /** Extract total count of items in this cluster */
+    getCount(cluster: TCluster): number;
+    /** Geographic extent as GeoJSON bbox `[minLon, minLat, maxLon, maxLat]`, or null when not provided */
+    getBbox(cluster: TCluster): GeoJsonBbox | null;
+}>;
+/**
+ * Discriminated union for clustering strategy.
+ * `mode` makes the clustering strategy explicit at the type level.
+ */
+export type ClusterConfig<TCluster> = Readonly<ClientClusterConfig | ServerClusterConfig<TCluster>>;

package/src/primitiveMapTypes.d.ts

@@ -0,0 +1,152 @@
+import type { GeoJsonBbox, GeoJsonPosition } from "@trackunit/geo-json-utils";
+import { z } from "zod";
+type CSSProperties = import("react").CSSProperties;
+type ReactNode = import("react").ReactNode;
+export type { GeoJsonBbox, GeoJsonPosition } from "@trackunit/geo-json-utils";
+/**
+ * Mutable holder for the container element.
+ * Behaves like a React ref but is a plain object so that passing it
+ * into `useMemo`/`createMapComponent` doesn't trigger the react-hooks/refs lint.
+ */
+export type ContainerRefHolder = {
+    current: HTMLDivElement | null;
+};
+export declare const mapThemeSchema: z.ZodEnum<["light", "dark"]>;
+export type MapTheme = z.infer<typeof mapThemeSchema>;
+export declare const mapTypeSchema: z.ZodEnum<["roadmap", "satellite", "hybrid"]>;
+export type MapType = z.infer<typeof mapTypeSchema>;
+export declare const mapAppearanceSchema: z.ZodObject<{
+    theme: z.ZodEnum<["light", "dark"]>;
+    mapType: z.ZodEnum<["roadmap", "satellite", "hybrid"]>;
+    showRoads: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    theme: "light" | "dark";
+    mapType: "roadmap" | "satellite" | "hybrid";
+    showRoads: boolean;
+}, {
+    theme: "light" | "dark";
+    mapType: "roadmap" | "satellite" | "hybrid";
+    showRoads: boolean;
+}>;
+/**
+ * Map appearance - grouped visual properties (theme, base layer, road overlay).
+ * Nested inside MapState as `state.appearance` so it can be watched and
+ * passed around as a single stable reference.
+ */
+export type MapAppearance = Readonly<z.infer<typeof mapAppearanceSchema>>;
+/** Default appearance before any user preference is applied */
+export declare const DEFAULT_MAP_APPEARANCE: MapAppearance;
+/**
+ * Camera state — viewport properties that change at up to 60fps during panning/zooming.
+ * React consumers subscribe to this channel with `useCameraState(api)`.
+ * Components that only need lifecycle or appearance data should read MapStatus
+ * from `api.state` instead.
+ */
+export type CameraState = Readonly<{
+    /** Current center position as [longitude, latitude] */
+    center: Readonly<GeoJsonPosition>;
+    /** Current zoom level (0-22) */
+    zoom: number;
+    /** Current visible bounds as [minLon, minLat, maxLon, maxLat], null if not available */
+    bounds: Readonly<GeoJsonBbox> | null;
+    /** True when the map is idle (not animating/panning) */
+    isIdle: boolean;
+}>;
+/**
+ * Map status — slow-changing properties (initialization lifecycle and visual appearance).
+ * This is the shape exposed as `api.state` by `useMap`.
+ */
+export type MapStatus = Readonly<{
+    /** Whether the map is ready for interactions */
+    isReady: boolean;
+    /** True when map initialization failed permanently (e.g. API script error). Implies `isReady` is false. */
+    initializationFailed: boolean;
+    /** Current visual appearance (theme, map type, road overlay) */
+    appearance: MapAppearance;
+    /** Base tile size in pixels used by the map provider (256 for Google Maps, 512 for Mapbox GL) */
+    tileSize: number;
+}>;
+/**
+ * Full map state — union of CameraState and MapStatus.
+ * Used internally by adapters and for event payloads (e.g. moveend).
+ * External consumers should prefer `api.state` for MapStatus and
+ * `useCameraState(api)` for CameraState.
+ */
+export type MapState = CameraState & MapStatus;
+export declare const INITIAL_CAMERA_STATE: CameraState;
+export declare const INITIAL_MAP_STATUS: MapStatus;
+/**
+ * Initial map state - default values before map loads
+ */
+export declare const INITIAL_MAP_STATE: MapState;
+/**
+ * Map events - discriminated union for type-safe event handling
+ */
+export type MapEvent = {
+    readonly type: "idle";
+} | {
+    readonly type: "movestart";
+} | {
+    readonly type: "moveend";
+    readonly state: MapState;
+} | {
+    readonly type: "click";
+    readonly position: GeoJsonPosition;
+    readonly originalEvent: MouseEvent;
+};
+/**
+ * Extract a specific event type from MapEvent union
+ */
+export type MapEventOfType<TEventType extends MapEvent["type"]> = Extract<MapEvent, {
+    type: TEventType;
+}>;
+/**
+ * Event handler type for a specific event
+ */
+export type MapEventHandler<TEventType extends MapEvent["type"]> = (event: MapEventOfType<TEventType>) => void;
+/**
+ * Internal handler type for storing event listeners (receives full MapEvent union).
+ * Used by adapters when dispatching to typed handlers.
+ */
+export type StoredEventHandler = (event: MapEvent) => void;
+/**
+ * Options for fitBounds action
+ */
+export type FitBoundsOptions = Readonly<{
+    /** Padding in pixels around the bounds. Defaults to 0 if omitted. */
+    padding?: number;
+    /** Maximum zoom level to use */
+    maxZoom?: number;
+    /** Whether to animate the transition */
+    animate?: boolean;
+}>;
+/**
+ * Initial viewport: either center+zoom or bounds. Mutually exclusive.
+ */
+export type InitialViewport = {
+    readonly type: "center";
+    readonly center: Readonly<GeoJsonPosition>;
+    readonly zoom?: number;
+} | {
+    readonly type: "bounds";
+    readonly bounds: Readonly<GeoJsonBbox>;
+    readonly padding?: number;
+    readonly maxZoom?: number;
+};
+/**
+ * Props for the Map component returned by useMap
+ */
+export type MapComponentProps = Readonly<{
+    /** Children rendered inside the map */
+    children?: ReactNode;
+    /** CSS class name for the map container */
+    className?: string;
+    /** Inline styles for the map container */
+    style?: CSSProperties;
+    /** Test ID for testing */
+    "data-testid"?: string;
+    /** Accessible label for the map */
+    "aria-label"?: string;
+    /** ID of element describing the map */
+    "aria-describedby"?: string;
+}>;

package/src/restrictBounds.d.ts

@@ -0,0 +1,12 @@
+import { type GeoJsonBbox } from "@trackunit/geo-json-utils";
+/**
+ * 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.
+ */
+export declare function getEffectiveRestrictBounds(configValue: GeoJsonBbox | null | undefined): GeoJsonBbox | null;

package/src/safeArea/_testUtils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared test helpers for safe-area unit tests. Co-located with the source
+ * (under `safeArea/`) so per-module specs can find them locally.
+ */
+export declare const makeRect: (w: number, h: number, x?: number, y?: number) => DOMRect;
+export declare const firePointermove: (x: number, y: number) => void;
+export declare const fireMouseenter: (el: HTMLElement) => void;
+export declare const fireMouseleave: (el: HTMLElement, x: number, y: number) => void;

package/src/safeArea/attachSafeAreaHoverListeners.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared mutable state box for cross-marker hover watcher coordination. One
+ * instance should be held per adapter instance and passed to every
+ * {@link attachSafeAreaHoverListeners} call. When `mouseenter` fires on any
+ * marker, the previous marker's document-level hover/guard listeners are
+ * cancelled via this reference.
+ */
+export type SafeAreaHoverState = {
+    activeWatcherCancel: (() => void) | null;
+    activeGuardCancel: (() => void) | null;
+};
+/**
+ * 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.
+ */
+export declare const attachSafeAreaHoverListeners: (el: HTMLElement, onEnter: () => void, onLeave: () => void, state: SafeAreaHoverState) => void;

package/src/safeArea/markerContract.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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. */
+export declare const HIT_SURFACE_SELECTOR = "[data-map-marker-hit-surface]";
+/** Stable attribute on the geographic-anchor element. */
+export declare 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.
+ */
+export declare 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.
+ */
+export declare const getHitSurfaceRect: (host: HTMLElement) => DOMRect | 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.
+ */
+export declare const getAnchorRect: (host: HTMLElement) => DOMRect | null;

package/src/safeArea/polygon.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure 2D polygon primitives used by the safe-area system. No DOM dependency,
+ * no React dependency — just geometry.
+ */
+/** A 2D point in page-space coordinates (matches `clientX`/`clientY`). */
+export type Point2D = Readonly<{
+    x: number;
+    y: number;
+}>;
+/**
+ * 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).
+ */
+export declare const bufferRectCorners: (rect: DOMRect, px: number) => ReadonlyArray<Point2D>;
+/**
+ * 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.
+ */
+export declare const convexHull: (points: ReadonlyArray<Point2D>) => ReadonlyArray<Point2D>;
+/**
+ * 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.
+ */
+export declare const pointInPolygon: (x: number, y: number, polygon: ReadonlyArray<Point2D>) => boolean;

package/src/safeArea/safeAreaDebug.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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
+ */
+import type { Point2D } from "./polygon";
+/**
+ * Enable the debug overlay. Idempotent. Persists until {@link disableSafeAreaDebug}
+ * is called or the page reloads.
+ */
+export declare const enableSafeAreaDebug: () => void;
+/**
+ * Disable the overlay, remove the SVG element, and forget all registered
+ * safe areas. Call when you're done debugging.
+ */
+export declare const disableSafeAreaDebug: () => void;
+/** Read-only check used by the wiring hooks to skip work when off. */
+export declare const isSafeAreaDebugEnabled: () => boolean;
+/**
+ * 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.
+ */
+export declare const renderSafeArea: (id: string, polygon: ReadonlyArray<Point2D>, rects: ReadonlyArray<DOMRect | null>) => void;
+/** Remove a registered safe area by id. No-op if id is unknown. */
+export declare const clearSafeArea: (id: string) => void;