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

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@trackunit/react-map-adapter-shared",
+  "version": "0.0.4-alpha-9d327375fc1.0",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "dependencies": {
+    "@trackunit/geo-json-utils": "1.14.25-alpha-9d327375fc1.0",
+    "@trackunit/ui-design-tokens": "1.13.24-alpha-9d327375fc1.0",
+    "es-toolkit": "^1.39.10",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/LayerPort.d.ts

@@ -0,0 +1,234 @@
+import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
+import type { Entity } from "./interactionTypes";
+import type { AdaptiveMarkerResolution, ClusterConfig, ClusterRenderConfig, ClusterRenderState, DomRenderState, GeoJsonFeatureCollection, RenderConfig, RouteStyle, ShapeInteractiveMode, ShapeStyle } from "./layerApiTypes";
+type ReactNode = import("react").ReactNode;
+/**
+ * Full interactive marker with clustering and adapter-managed entity events.
+ */
+export type InteractiveMarkerConfig = Readonly<{
+    kind: "marker";
+    id: string;
+    features: GeoJsonFeatureCollection;
+    markerRender: RenderConfig<unknown>;
+    clusterConfig: ClusterConfig<unknown> | null;
+    clusterRender: ClusterRenderConfig<unknown, unknown> | null;
+    clusterFeatures: GeoJsonFeatureCollection | null;
+    /**
+     * Populated by `<Layers>` when `markerRender.mode === "adaptive"` so adapters
+     * can split symbol vs DOM per feature (plan §8).
+     */
+    adaptiveResolution?: AdaptiveMarkerResolution;
+}>;
+/**
+ * Positioned DOM content anchor — adapter only handles positioning,
+ * content manages its own interaction.
+ */
+export type AnchoredContentConfig = Readonly<{
+    kind: "anchor";
+    id: string;
+    features: GeoJsonFeatureCollection;
+    markerRender: RenderConfig<unknown>;
+}>;
+/**
+ * Configuration for a marker source.
+ * The adapter uses this to render markers and clusters on the map.
+ *
+ * - `"marker"` — interactive marker with clustering and entity events
+ * - `"anchor"` — positioned DOM content; content handles its own interaction
+ */
+export type MarkerSourceConfig = InteractiveMarkerConfig | AnchoredContentConfig;
+/**
+ * Configuration for a shape source.
+ * The adapter uses this to render polygons, multipolygons, and lines.
+ */
+export type ShapeSourceConfig = Readonly<{
+    id: string;
+    features: GeoJsonFeatureCollection;
+    style: ShapeStyle;
+    /** Per-feature resolved styles, keyed by `String(feature.id)`. */
+    featureStyles?: ReadonlyMap<string, ShapeStyle>;
+    interactive: ShapeInteractiveMode;
+}>;
+/**
+ * Configuration for a route source.
+ */
+export type RouteSourceConfig = Readonly<{
+    id: string;
+    features: GeoJsonFeatureCollection;
+    style: RouteStyle;
+    interactive: boolean;
+}>;
+/**
+ * Configuration for an image overlay.
+ */
+export type ImageOverlayConfig = Readonly<{
+    id: string;
+    url: string;
+    imageBounds: GeoJsonBbox;
+    opacity: number;
+}>;
+/**
+ * A typed layer description — the declarative unit passed to `setSnapshot`.
+ *
+ * Discriminated on `layerType`, matching `LayerHandle.layerType`.
+ * Adding a new layer type is additive: extend this union, add a case in each
+ * adapter's layer-type handling (for example, its internal snapshot-application
+ * switch), and TypeScript's exhaustive check catches any adapter that missed
+ * the new type.
+ */
+export type MapLayer = ({
+    readonly layerType: "markers";
+} & MarkerSourceConfig) | ({
+    readonly layerType: "shapes";
+} & ShapeSourceConfig) | ({
+    readonly layerType: "route";
+} & RouteSourceConfig) | ({
+    readonly layerType: "image-overlay";
+} & ImageOverlayConfig);
+/**
+ * Shape interaction state — which shape feature is currently selected/hovered.
+ * Both fields are null when nothing is selected/hovered.
+ */
+export type ShapeInteractionState = Readonly<{
+    handleId: string | null;
+    featureId: string | null;
+}>;
+/**
+ * Full desired rendering state passed to `LayerPort.setSnapshot`.
+ *
+ * The adapter owns the diff between the previous snapshot and this one,
+ * applying only the minimal changes needed to bring the map up to date.
+ */
+export type LayerSnapshot = Readonly<{
+    /** All active layers in desired render order. */
+    layers: ReadonlyArray<MapLayer>;
+    /** Currently selected shape feature. Both fields null when nothing selected. */
+    shapeSelection: ShapeInteractionState;
+    /** Currently hovered shape feature. Both fields null when nothing hovered. */
+    shapeHover: ShapeInteractionState;
+}>;
+/**
+ * Entity interaction event types emitted by the map adapter.
+ */
+export type EntityInteractionEvent = Readonly<{
+    type: "click";
+    entity: Entity;
+}> | Readonly<{
+    type: "dblclick";
+    entity: Entity;
+}> | Readonly<{
+    type: "hover-start";
+    entity: Entity;
+}> | Readonly<{
+    type: "hover-end";
+    entity: Entity;
+}>;
+/**
+ * Handler for entity interaction events.
+ */
+export type EntityInteractionHandler = (event: EntityInteractionEvent) => void;
+/**
+ * Describes a React portal target for DOM-rendered markers/clusters.
+ *
+ * The adapter creates an `AdvancedMarkerElement` (or equivalent) with an
+ * empty container div as its content. `<Layers>` subscribes to these
+ * descriptors and renders user-provided React content into each container
+ * via `createPortal()`. Routing to `markerRender` vs `clusterRender` is
+ * derived structurally from which {@link DomPortalStore} the descriptor
+ * came from (`markerPortals` vs `clusterPortals` on {@link LayerPort}).
+ */
+export type DomPortalDescriptor = Readonly<{
+    /** Unique React key for list rendering. Format: `${sourceId}:${featureId}`. */
+    key: string;
+    /** Owning marker layer id. Avoids parsing composite React keys. */
+    sourceId: string;
+    /** The marker's content element (portal target) */
+    container: HTMLElement;
+    /**
+     * Optional adapter hook for map-native marker stacking.
+     *
+     * Some adapters wrap `container` in their own marker object whose z-index
+     * controls sibling ordering, so the computed portal z-index must be applied
+     * outside the React portal target as well.
+     */
+    setZIndex?: (zIndex: number) => void;
+    /** Feature ID for computing `DomRenderState` (selected/hovered) */
+    featureId: string;
+    /** Original data item (TItem or TCluster extracted from properties.__data) */
+    sourceData: unknown;
+    /**
+     * User-provided render function. For marker portals this is a
+     * `DomRenderConfig`/`AdaptiveRenderConfig.render` (state =
+     * {@link DomRenderState}); for cluster portals it is a
+     * {@link ClusterRenderConfig} `render` (state =
+     * {@link ClusterRenderState}). `<Layers>` constructs the matching state
+     * shape based on which store the descriptor came from (`markerPortals`
+     * vs `clusterPortals`) before invoking this function.
+     *
+     * Method syntax: parameter variance is bivariant so the narrower
+     * marker-only and cluster-only render signatures both assign into this
+     * field without re-wrapping.
+     */
+    renderFn(item: unknown, state: DomRenderState | ClusterRenderState<unknown>): ReactNode;
+}>;
+/**
+ * Optional subscription interface for DOM portal rendering.
+ * Compatible with `useSyncExternalStore(subscribe, getSnapshot)`.
+ */
+export type DomPortalStore = Readonly<{
+    subscribe: (callback: () => void) => () => void;
+    getSnapshot: () => ReadonlyArray<DomPortalDescriptor>;
+}>;
+/**
+ * The adapter extension point for layer rendering.
+ *
+ * Each adapter provides a `LayerPort` that the `<Layers>` component uses
+ * to communicate the full desired map state. The adapter receives a
+ * `LayerSnapshot` describing all active layers and interaction state, and
+ * is responsible for diffing against its previous state to apply minimal
+ * changes to the underlying map engine.
+ */
+export type LayerPort = Readonly<{
+    /**
+     * Push the full desired rendering state to the adapter.
+     *
+     * Called whenever layers or interaction state changes. The adapter diffs
+     * the new snapshot against its previous state and applies only the
+     * necessary changes to the map engine. Passing an empty `layers` array
+     * removes all active sources.
+     */
+    setSnapshot: (snapshot: LayerSnapshot) => void;
+    /** Subscribe to entity interaction events from the map (click, hover) */
+    onEntityInteraction: (handler: EntityInteractionHandler) => () => void;
+    /** Subscribe to clicks on the map background (no entity hit). */
+    onBackgroundClick: (handler: () => void) => () => void;
+    /**
+     * Subscribe to know when a specific source has been loaded and is ready
+     * for rendering. Used by `<Layers>` to defer showing edge labels until
+     * the parent shape source has finished drawing.
+     *
+     * Mapbox: fires after `sourcedata` with `isSourceLoaded` for the source.
+     * Google Maps: fires immediately (shapes are added synchronously).
+     *
+     * @param configId - The same `id` that was passed in a shape layer's config.
+     *   The adapter maps this to its internal source identifier.
+     * @param callback - Called once when the source data is loaded and ready.
+     * @returns Unsubscribe function.
+     */
+    onSourceReady: (configId: string, callback: () => void) => () => void;
+    /**
+     * Subscription for DOM-rendered individual markers (including adaptive DOM
+     * features). `<Layers>` routes these descriptors to `markerRender`.
+     *
+     * Null or undefined if the adapter doesn't support DOM rendering.
+     */
+    markerPortals?: DomPortalStore | null;
+    /**
+     * Subscription for DOM-rendered clusters (server clusters and client-side
+     * clusters alike). `<Layers>` routes these descriptors to `clusterRender`.
+     *
+     * Null or undefined if the adapter doesn't support DOM rendering.
+     */
+    clusterPortals?: DomPortalStore | null;
+}>;
+export {};

package/src/adapterContract.d.ts

@@ -0,0 +1,189 @@
+import type { LayerPort } from "./LayerPort";
+import type { CameraState, FitBoundsOptions, GeoJsonBbox, GeoJsonPosition, InitialViewport, MapComponentProps, MapEvent, MapEventHandler, MapStatus, MapTheme, MapType } from "./primitiveMapTypes";
+type ComponentType<TProps> = import("react").ComponentType<TProps>;
+/** Viewport overrides for adapter switching - both adapters support these */
+type ViewportOverrides = Readonly<{
+    initialViewport: InitialViewport;
+}>;
+/**
+ * Props passed to adapter renderer components
+ */
+export type AdapterRendererProps = MapComponentProps & {
+    /** Adapter instance to connect to */
+    readonly adapterInstance: AdapterInstance;
+};
+/**
+ * Adapter instance - the runtime interface for controlling the map
+ * Created by adapter factory, used internally by useMap
+ * Generic over the config type for type-safe config access
+ */
+export type AdapterInstance<TConfig extends Record<string, unknown> = Record<string, unknown>> = Readonly<{
+    /**
+     * Get the adapter configuration
+     */
+    getConfig: () => TConfig;
+    /**
+     * Get current camera state (center, zoom, bounds, isIdle).
+     * This snapshot belongs to the high-frequency camera channel and can change
+     * continuously during panning/zooming.
+     */
+    getCameraState: () => CameraState;
+    /**
+     * Get current map status (isReady, initializationFailed, appearance, tileSize).
+     * This snapshot belongs to the low-frequency status channel used by `api.state`.
+     */
+    getStatus: () => MapStatus;
+    /**
+     * Subscribe to camera state changes only.
+     * Adapters should notify this channel only after replacing the cached
+     * CameraState snapshot with a field-wise different value.
+     */
+    subscribeCamera: (listener: () => void) => () => void;
+    /**
+     * Subscribe to status changes only.
+     * Adapters should notify this channel only after replacing the cached MapStatus
+     * snapshot with a field-wise different value.
+     */
+    subscribeStatus: (listener: () => void) => () => void;
+    /**
+     * Set the map center
+     */
+    setCenter: (center: GeoJsonPosition) => Promise<void>;
+    /**
+     * Set the zoom level (absolute)
+     */
+    setZoom: (zoom: number) => Promise<void>;
+    /**
+     * Adjust zoom by delta (relative)
+     */
+    zoomBy: (delta: number) => Promise<void>;
+    /**
+     * Fit the map to bounds
+     */
+    fitBounds: (bounds: GeoJsonBbox, options?: FitBoundsOptions) => Promise<void>;
+    /**
+     * Pan to a position with animation
+     */
+    panTo: (center: GeoJsonPosition) => Promise<void>;
+    /**
+     * Pan the map by pixel offsets (for keyboard navigation)
+     * Uses screen coordinate convention where origin (0,0) is top-left:
+     *
+     * @param deltaX - Horizontal pan amount in pixels (positive = right, negative = left)
+     * @param deltaY - Vertical pan amount in pixels (positive = down, negative = up)
+     */
+    panBy: (deltaX: number, deltaY: number) => Promise<void>;
+    /**
+     * Set the map type (base layer)
+     */
+    setMapType: (type: MapType) => Promise<void>;
+    /**
+     * Set the map theme (visual appearance)
+     */
+    setTheme: (theme: MapTheme) => Promise<void>;
+    /**
+     * Set whether road labels are shown over satellite/hybrid imagery
+     */
+    setShowRoads: (showRoads: boolean) => Promise<void>;
+    /**
+     * Subscribe to map events
+     */
+    on: <TEventType extends MapEvent["type"]>(event: TEventType, handler: MapEventHandler<TEventType>) => () => void;
+    /**
+     * Mark map initialization as permanently failed (e.g. provider API could not load).
+     * Sets `initializationFailed` on state and `isReady` false, then notifies subscribers.
+     */
+    notifyInitializationFailed: () => void;
+    /**
+     * Cleanup resources
+     */
+    destroy: () => void;
+    /**
+     * Layer rendering capabilities.
+     * Null if this adapter does not yet support layer rendering.
+     * Adapters can implement this incrementally.
+     */
+    layers: LayerPort | null;
+}>;
+/**
+ * Pixel insets representing areas reserved by the map provider's own UI
+ * (logo, attribution links, etc.). Controls use these to avoid overlapping
+ * provider chrome.
+ */
+export type SafeAreaInsets = Readonly<{
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}>;
+/**
+ * Base adapter configuration fields returned by adapter factory functions.
+ * This is the shape that adapter factories produce before `defineAdapter`
+ * injects the `derive` method.
+ */
+export type AdapterConfigBase<TConfig extends Record<string, unknown> = Record<string, unknown>> = Readonly<{
+    /** Unique name for this adapter */
+    name: string;
+    /** Adapter-specific configuration */
+    config: TConfig;
+    /**
+     * Safe area insets declared by the map provider.
+     * Provide pixel values for sides where the provider renders its own UI,
+     * or `null` to indicate no safe area concerns.
+     */
+    safeAreaInsets: SafeAreaInsets | null;
+    /** Factory function to create the adapter instance */
+    createInstance: () => AdapterInstance;
+    /** React component that renders the map */
+    Renderer: ComponentType<AdapterRendererProps>;
+}>;
+/**
+ * Full adapter configuration with the `derive` method for creating variants.
+ * Generic over the config type for type-safe adapter-specific options.
+ *
+ * Use `derive(overrides)` to create a new adapter config with merged settings,
+ * e.g. for spawning preview map instances with a different theme or map type.
+ */
+export type AdapterConfig<TConfig extends Record<string, unknown> = Record<string, unknown>> = AdapterConfigBase<TConfig> & {
+    /**
+     * Create a variant of this adapter config with merged overrides.
+     * Returns a new `AdapterConfig` that uses the same adapter factory
+     * but with the overridden config values merged in.
+     *
+     * Uses method syntax intentionally — bivariant method parameters
+     * let `AdapterConfig<TConfig>` remain assignable to `AdapterConfig`
+     * (default `Record<string, unknown>`) so we can store it on `MapApi`
+     * without requiring a generic on `MapApi` itself.
+     *
+     * @param overrides - Partial config to merge into the existing config
+     * @returns A new AdapterConfig with the merged configuration
+     * @example
+     * ```typescript
+     * // Create a dark-themed variant for a preview map
+     * const darkPreview = api.adapterConfig.derive({ theme: "dark" });
+     * ```
+     */
+    derive(overrides: Partial<TConfig> | ViewportOverrides): AdapterConfig<TConfig>;
+};
+/**
+ * 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" });
+ * ```
+ */
+export declare const defineAdapter: <TConfig extends Record<string, unknown>>(factory: (config: TConfig) => AdapterConfigBase<TConfig>) => ((config: TConfig) => AdapterConfig<TConfig>);
+export {};

package/src/antimeridianMerge.d.ts

@@ -0,0 +1,22 @@
+import type { GeoJsonFeatureCollection } from "@trackunit/geo-json-utils";
+/**
+ * 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.
+ */
+export declare const mergeAntimeridianFeatures: (features: GeoJsonFeatureCollection) => GeoJsonFeatureCollection;

package/src/colorUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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
+ */
+export declare const mixColor: (color1: string, color2: string, percentage: number) => string;
+/**
+ * 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)
+ */
+export declare const darkenColor: (color: string, amount: number) => string;
+/**
+ * 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)
+ */
+export declare const lightenColor: (color: string, amount: number) => string;
+/**
+ * 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
+ */
+export declare const colorWithOpacity: (color: string, opacity: number) => string;
+/**
+ * Clear the resolved-color cache and detach the probe element.
+ * Exposed for test teardown only — not part of the public API.
+ */
+export declare const resetColorUtilsForTesting: () => void;

package/src/constants.d.ts

@@ -0,0 +1,58 @@
+/**
+ * World bounds for Web Mercator projection.
+ * GeoJSON format: [minLng, minLat, maxLng, maxLat]
+ */
+export declare const WORLD_BBOX: readonly [-180, number, 180, number];
+/**
+ * Default zoom level when not specified
+ */
+export declare const DEFAULT_ZOOM = 2;
+/**
+ * Default center when not specified (Atlantic Ocean)
+ * Position format: { lat: number, lng: number }
+ */
+export declare const DEFAULT_CENTER: {
+    readonly lat: 0;
+    readonly lng: 0;
+};
+/**
+ * Minimum zoom level supported across providers
+ * Both Mapbox and Google Maps support zoom level 0
+ */
+export declare const MIN_ZOOM = 0;
+/**
+ * Maximum zoom level supported across providers
+ * Both Mapbox and Google Maps support zoom level 22
+ */
+export declare const MAX_ZOOM = 22;
+/**
+ * Amount to pan the map when using arrow keys (in pixels)
+ */
+export declare const KEYBOARD_PAN_AMOUNT = 100;
+/**
+ * Amount to zoom when using +/- keys
+ */
+export declare const KEYBOARD_ZOOM_AMOUNT = 1;
+/**
+ * CSS cursor values used across map adapters.
+ * Centralised so both Mapbox and Google stay in sync.
+ */
+export declare const MAP_CURSORS: {
+    readonly default: "default";
+    readonly 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.
+ */
+export declare const estimateZoomFromBounds: (bounds: readonly [number, number, number, number]) => number;
+/**
+ * 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.
+ */
+export declare const mercatorCenterFromBounds: (bounds: readonly [number, number, number, number]) => readonly [number, number];

package/src/index.d.ts

@@ -0,0 +1,21 @@
+export * from "./adapterContract";
+export * from "./antimeridianMerge";
+export * from "./colorUtils";
+export * from "./constants";
+export * from "./initialViewportValidation";
+export * from "./interactionTypes";
+export * from "./layerApiTypes";
+export * from "./LayerPort";
+export * from "./layerPortHelpers";
+export * from "./mapEventUtils";
+export * from "./mapStateUtils";
+export * from "./primitiveMapTypes";
+export * from "./restrictBounds";
+export * from "./safeArea/attachSafeAreaHoverListeners";
+export * from "./safeArea/markerContract";
+export * from "./safeArea/polygon";
+export * from "./safeArea/safeAreaDebug";
+export * from "./safeArea/safePolygon";
+export * from "./safeArea/watchSafeAreaLeave";
+export * from "./shapeStyleDefaults";
+export * from "./types";

package/src/initialViewportValidation.d.ts

@@ -0,0 +1,5 @@
+import type { InitialViewport } from "./primitiveMapTypes";
+/**
+ * Validates InitialViewport and returns undefined for invalid values.
+ */
+export declare const validateInitialViewport: (value: unknown) => InitialViewport | undefined;

package/src/interactionTypes.d.ts

@@ -0,0 +1,79 @@
+import type { GeoJsonBbox, GeoJsonGeometry, GeoJsonPosition } from "@trackunit/geo-json-utils";
+/**
+ * A marker entity -- a single point of interest on the map.
+ * May be contained within a cluster when clustering is active.
+ */
+export type MarkerEntity = Readonly<{
+    type: "marker";
+    id: string;
+    position: GeoJsonPosition | null;
+    /** If this marker is inside a cluster, the cluster's ID. Null when unclustered. */
+    clusterId: string | null;
+}>;
+/**
+ * A cluster entity -- a group of markers aggregated into a single point.
+ * Produced by either client-side or server-side clustering.
+ */
+export type ClusterEntity = Readonly<{
+    type: "cluster";
+    id: string;
+    position: GeoJsonPosition;
+    /** IDs of markers contained in this cluster */
+    markerIds: ReadonlyArray<string>;
+    /**
+     * Geographic extent as GeoJSON bbox when known (eg. server clusters from backend)
+     */
+    bbox: GeoJsonBbox | null;
+}>;
+/**
+ * The kind of geometry a shape entity represents.
+ * Derived from GeoJSON geometry types when constructing entities in adapters.
+ */
+export type ShapeType = "polygon" | "line" | "point";
+/**
+ * A shape entity -- a polygon, line, or point on the map.
+ * When the interaction originates from an anchor (e.g. edge label),
+ * `handleId` carries the layer handle the feature belongs to.
+ */
+export type ShapeEntity = Readonly<{
+    type: "shape";
+    id: string;
+    shapeType: ShapeType;
+    handleId?: string;
+}>;
+/**
+ * A route entity -- a polyline with waypoints.
+ */
+export type RouteEntity = Readonly<{
+    type: "route";
+    id: string;
+    /** The waypoints that define this route */
+    waypoints: ReadonlyArray<GeoJsonPosition>;
+}>;
+/**
+ * Discriminated union of all interactive map entities.
+ * Used for hover/select interaction across all layer types.
+ */
+export type Entity = Readonly<MarkerEntity | ClusterEntity | ShapeEntity | RouteEntity>;
+/**
+ * Shared interaction state for all layers.
+ * At most one entity can be selected and one hovered at any time.
+ * Selecting a marker clears any previously selected polygon, and vice versa.
+ */
+export type MapInteractionState = Readonly<{
+    selectedEntity: Entity | null;
+    hoveredEntity: Entity | null;
+}>;
+/**
+ * GeoJSON geometry types excluding GeometryCollection, which is a
+ * container of mixed primitives rather than a renderable shape itself.
+ */
+export type GeoJsonPrimitiveGeometryType = Exclude<GeoJsonGeometry["type"], "GeometryCollection">;
+/**
+ * Maps a primitive GeoJSON geometry type to the ShapeType discriminant.
+ */
+export declare const geometryTypeToShapeType: (geometryType: GeoJsonPrimitiveGeometryType) => ShapeType;
+/**
+ * Initial interaction state -- nothing selected or hovered.
+ */
+export declare const INITIAL_INTERACTION_STATE: MapInteractionState;