@trackunit/react-map 0.2.180-alpha-7fd06f36b49.0 → 0.2.183

package/index.cjs.js

@@ -13,6 +13,7 @@ var esToolkit = require('es-toolkit');
 var reactCoreHooks = require('@trackunit/react-core-hooks');
 var reactFormComponents = require('@trackunit/react-form-components');
 var zod = require('zod');
+var sharedUtils = require('@trackunit/shared-utils');
 var reactMinimalPieChart = require('react-minimal-pie-chart');
 var uiDesignTokens = require('@trackunit/ui-design-tokens');
 var geoJsonUtils = require('@trackunit/geo-json-utils');
@@ -2792,22 +2793,20 @@ const AppearancePreview = ({ adapterConfig, mapType, label, selected, onSelect,
  * @internal
  */
 const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme, currentMapType, onChange, }) => {
-    const derivedConfigs = react.useMemo(() => {
-        const configs = new Map();
-        for (const option of options) {
-            if (!configs.has(option.theme)) {
-                configs.set(option.theme, adapterConfig.derive({ theme: option.theme }));
-            }
-        }
-        return configs;
-    }, [adapterConfig, options]);
-    return (jsxRuntime.jsx("div", { "aria-label": ariaLabel, className: "flex flex-wrap items-start gap-2 px-3 py-2", role: "radiogroup", children: options.map(option => {
-            const derivedConfig = derivedConfigs.get(option.theme);
-            if (derivedConfig === undefined) {
-                return null;
-            }
-            return (jsxRuntime.jsx(AppearancePreview, { adapterConfig: derivedConfig, "data-testid": `map-style-preview-${option.key}`, label: option.label, mapType: option.mapType, onSelect: () => onChange(option.theme, option.mapType), selected: option.theme === currentTheme && option.mapType === currentMapType }, option.key));
-        }) }));
+    const derivedOptions = react.useMemo(() => options.map(option => ({
+        option,
+        // Pin the full appearance per option: the main map's config may carry a
+        // persisted seed (theme, mapType, roads, traffic — see
+        // usePersistedAppearanceSeed), and a preview depicts exactly one
+        // theme/mapType combination with no overlays.
+        config: adapterConfig.derive({
+            theme: option.theme,
+            mapType: option.mapType,
+            showRoads: false,
+            showTraffic: false,
+        }),
+    })), [adapterConfig, options]);
+    return (jsxRuntime.jsx("div", { "aria-label": ariaLabel, className: "flex flex-wrap items-start gap-2 px-3 py-2", role: "radiogroup", children: derivedOptions.map(({ option, config }) => (jsxRuntime.jsx(AppearancePreview, { adapterConfig: config, "data-testid": `map-style-preview-${option.key}`, label: option.label, mapType: option.mapType, onSelect: () => onChange(option.theme, option.mapType), selected: option.theme === currentTheme && option.mapType === currentMapType }, option.key))) }));
 };
 
 // ============================================================================
@@ -2815,10 +2814,16 @@ const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme
 // ============================================================================
 /**
  * Increment this number when the persisted appearance shape changes, and add a
- * matching migration step in useMapAppearanceControls so stored settings are
+ * matching migration step in appearanceMigrations.ts so stored settings are
  * upgraded instead of reset. (v2: added showTraffic.)
  */
 const APPEARANCE_SETTINGS_VERSION = 2;
+/**
+ * Default localStorage key for the persisted map appearance settings.
+ * Shared by `useMapAppearanceControls` (owner) and `usePersistedAppearanceSeed`
+ * (read-only) so both resolve the same stored preference by default.
+ */
+const DEFAULT_APPEARANCE_PERSISTENCE_KEY = "map-appearance-settings";
 // ============================================================================
 // Persisted Appearance Schema (extends core mapAppearanceSchema with version)
 // ============================================================================
@@ -2853,8 +2858,6 @@ const appearanceReducer = (state, action) => {
     }
 };
 
-const DEFAULT_THEMES = ["light", "dark"];
-const DEFAULT_MAP_TYPES = ["roadmap", "satellite"];
 /**
  * The v1 persisted shape, frozen as a literal. Deliberately NOT derived from
  * the live mapAppearanceSchema: deriving would make every future appearance
@@ -2890,6 +2893,20 @@ const appearanceMigrationV2 = {
             : DEFAULT_PERSISTED_APPEARANCE;
     },
 };
+/**
+ * Migration pipeline for the persisted map appearance settings.
+ *
+ * Shared by `useMapAppearanceControls` (the owning reader/writer) and
+ * `usePersistedAppearanceSeed` (a read-only consumer), so both interpret
+ * stored data — including pre-envelope and v1 shapes — identically.
+ */
+const APPEARANCE_MIGRATION = {
+    version: APPEARANCE_SETTINGS_VERSION,
+    steps: [appearanceMigrationV1, appearanceMigrationV2],
+};
+
+const DEFAULT_THEMES = ["light", "dark"];
+const DEFAULT_MAP_TYPES = ["roadmap", "satellite"];
 const themeToTranslationKey = (theme) => {
     switch (theme) {
         case "light":
@@ -2978,7 +2995,7 @@ const buildAppearanceOptions = (themes, mapTypes, t) => {
  * <Controls api={api} controls={controlsConfig} />
  * ```
  */
-const useMapAppearanceControls = ({ api, options: appearanceOptions, persistenceKey = "map-appearance-settings", }) => {
+const useMapAppearanceControls = ({ api, options: appearanceOptions, persistenceKey = DEFAULT_APPEARANCE_PERSISTENCE_KEY, }) => {
     const [t] = useTranslation();
     const themes = appearanceOptions?.themes ?? DEFAULT_THEMES;
     const mapTypes = appearanceOptions?.mapTypes ?? DEFAULT_MAP_TYPES;
@@ -2993,7 +3010,7 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
     const [localState, dispatch] = reactComponents.useLocalStorageReducer({
         key: persistenceKey,
         defaultState: DEFAULT_PERSISTED_APPEARANCE,
-        migration: { version: APPEARANCE_SETTINGS_VERSION, steps: [appearanceMigrationV1, appearanceMigrationV2] },
+        migration: APPEARANCE_MIGRATION,
         reducer: appearanceReducer,
         schema: persistedAppearanceSchema,
     });
@@ -3241,7 +3258,11 @@ const useDefaultControls = (api, options) => {
             "data-testid": "map-my-location-button",
         }, [api.actions, getPosition, options?.navigation?.myLocation?.enabled, t]);
     const navigationControls = react.useMemo(() => defineControlStack([myLocationControl, zoomControl, fullscreenControl]), [fullscreenControl, myLocationControl, zoomControl]);
-    const mapAppearanceControls = useMapAppearanceControls({ api });
+    const mapAppearanceControls = useMapAppearanceControls({
+        api,
+        options: options?.settings?.mapStyle?.options,
+        persistenceKey: options?.settings?.mapStyle?.persistenceKey,
+    });
     const mapStyleControl = react.useMemo(() => options?.settings?.mapStyle?.enabled === false ? undefined : mapAppearanceControls[0], [mapAppearanceControls, options?.settings?.mapStyle?.enabled]);
     const settingsControls = react.useMemo(() => defineControlStack([mapStyleControl]), [mapStyleControl]);
     return react.useMemo(() => ({
@@ -3362,6 +3383,57 @@ const useControls = (base, areas) => {
     }, [base, areas]);
 };
 
+/**
+ * Reads the persisted map appearance once (on mount) so it can seed the adapter
+ * factory, letting the FIRST map be constructed with the user's stored theme,
+ * map type, and traffic preference instead of being corrected after mount.
+ *
+ * Without the seed, a stored dark theme or traffic-on preference only reaches
+ * the adapter once the map is ready, forcing an immediate map recreation on
+ * every page load: a visible blink, a wasted provider map construction (each
+ * one is a billed Dynamic Maps load on Google), and overlays built on a
+ * throwaway instance (ADR 0029).
+ *
+ * Read-only: `useMapAppearanceControls` keeps owning the persistence and pushes
+ * all later changes through the adapter's appearance actions. The seed is
+ * deliberately not reactive — it only matters at construction time.
+ *
+ * Storage being unavailable or corrupt is never an error: the seed then falls
+ * back to the defaults, which is exactly the pre-seeding behavior.
+ *
+ * @example
+ * ```tsx
+ * const appearanceSeed = usePersistedAppearanceSeed();
+ * const [Map, api] = useMap(googleMapsAdapter({ apiKey, ...appearanceSeed }));
+ * ```
+ */
+const usePersistedAppearanceSeed = (params) => {
+    const [seed] = react.useState(() => {
+        let persisted = DEFAULT_PERSISTED_APPEARANCE;
+        try {
+            persisted = sharedUtils.readLocalStorageValue({
+                key: params?.persistenceKey ?? DEFAULT_APPEARANCE_PERSISTENCE_KEY,
+                defaultState: DEFAULT_PERSISTED_APPEARANCE,
+                schema: persistedAppearanceSchema,
+                migration: APPEARANCE_MIGRATION,
+            });
+        }
+        catch {
+            // Accessing localStorage can throw (privacy mode, blocked site data,
+            // non-browser rendering) — fall through to the defaults.
+        }
+        return {
+            theme: persisted.theme,
+            mapType: persisted.mapType,
+            showRoads: persisted.showRoads,
+            // `traffic: false` opts the whole surface out of traffic (see
+            // useMapAppearanceControls), so it must override a stored preference here too
+            showTraffic: params?.options?.traffic === false ? false : persisted.showTraffic,
+        };
+    });
+    return seed;
+};
+
 const MARKER_SPRING_CONFIG = {
     stiffness: 380,
     damping: 30,
@@ -5173,7 +5245,7 @@ const useLayerReady = (loading) => {
 // ============================================================================
 // Constants
 // ============================================================================
-const EMPTY_CONTROLS$3 = {};
+const EMPTY_CONTROLS$4 = {};
 // ============================================================================
 // Hook
 // ============================================================================
@@ -5213,7 +5285,7 @@ const useImageOverlay = (options) => {
         ready: layerReady.ready,
         getBounds,
         counts,
-        controls: controls ?? EMPTY_CONTROLS$3,
+        controls: controls ?? EMPTY_CONTROLS$4,
         fitParticipation,
         layerType: "image-overlay",
         url,
@@ -5494,7 +5566,7 @@ const createLazyGetter = (compute) => {
 // ============================================================================
 // Constants
 // ============================================================================
-const EMPTY_CONTROLS$2 = {};
+const EMPTY_CONTROLS$3 = {};
 const EMPTY_FEATURES$1 = { type: "FeatureCollection", features: [] };
 // ============================================================================
 // Internal helpers
@@ -5582,7 +5654,7 @@ const useRoute = (options) => {
         ready: layerReady.ready,
         getBounds,
         counts,
-        controls: controls ?? EMPTY_CONTROLS$2,
+        controls: controls ?? EMPTY_CONTROLS$3,
         fitParticipation,
         layerType: "route",
         features,
@@ -5708,6 +5780,78 @@ const useFitToContent = (api, handles, options) => {
     return react.useMemo(() => ({ hasFitted, isWaiting, fitNow }), [hasFitted, isWaiting, fitNow]);
 };
 
+const EMPTY_CONTROLS$2 = {};
+/**
+ * Weighted point heatmap layer handle (provider-agnostic).
+ *
+ * - Normalizes `data` → GeoJSON `Point` features + `properties.weight`.
+ * - Synced as `HeatmapSourceConfig` in {@link LayerSnapshot}.
+ * - Renderers: ADR-0029 (`libs/react/map/docs/adr/0029-heatmap-provider-specific-renderers.md`).
+ */
+const useHeatmap = (options) => {
+    const { id, name, data, getPosition, getWeight, style, controls, loading, fitParticipation = "all" } = options;
+    const layerReady = useLayerReady(loading);
+    const normalized = react.useMemo(() => {
+        const features = [];
+        const positions = [];
+        for (const item of data) {
+            const position = getPosition(item);
+            if (position === null)
+                continue;
+            const parsedPosition = geoJsonUtils.geoJsonPositionSchema.safeParse(position);
+            if (!parsedPosition.success)
+                continue;
+            const weight = getWeight?.(item) ?? 1;
+            if (!Number.isFinite(weight) || weight <= 0)
+                continue;
+            positions.push(parsedPosition.data);
+            features.push({
+                type: "Feature",
+                geometry: { type: "Point", coordinates: parsedPosition.data },
+                properties: { weight },
+            });
+        }
+        return {
+            features: { type: "FeatureCollection", features },
+            positions,
+        };
+    }, [data, getPosition, getWeight]);
+    const resolvedStyle = react.useMemo(() => ({
+        radiusPixels: style?.radiusPixels ?? 30,
+        intensity: style?.intensity ?? 1,
+        opacity: style?.opacity ?? 1,
+    }), [style?.radiusPixels, style?.intensity, style?.opacity]);
+    const getBounds = react.useMemo(() => createLazyGetter(() => computeBoundsFromPositions(normalized.positions)), [normalized.positions]);
+    const counts = react.useMemo(() => ({ total: data.length, points: normalized.features.features.length }), [data.length, normalized.features.features.length]);
+    return react.useMemo(() => ({
+        id,
+        name,
+        loadsData: layerReady.loadsData,
+        loading: layerReady.isLoading,
+        ready: layerReady.ready,
+        getBounds,
+        counts,
+        controls: controls ?? EMPTY_CONTROLS$2,
+        fitParticipation,
+        layerType: "heatmap",
+        features: normalized.features,
+        style: resolvedStyle,
+        pointCount: normalized.features.features.length,
+        totalCount: data.length,
+    }), [
+        id,
+        name,
+        layerReady,
+        getBounds,
+        counts,
+        controls,
+        fitParticipation,
+        normalized.features,
+        resolvedStyle,
+        data.length,
+    ]);
+};
+
 /**
  * Do two label footprints overlap? Each is a box of its own size centred on its point, so the boxes
  * overlap when the centres are closer than the sum of their half-extents in each axis. Shared by the
@@ -8002,6 +8146,13 @@ function toMapLayer(handle) {
                 imageBounds: handle.imageBounds,
                 opacity: handle.opacity,
             };
+        case "heatmap":
+            return {
+                layerType: "heatmap",
+                id: handle.id,
+                features: handle.features,
+                style: handle.style,
+            };
         default: {
             const exhaustiveCheck = handle;
             throw new Error(`${String(exhaustiveCheck)} is not known`);
@@ -12884,6 +13035,7 @@ Object.defineProperty(exports, "mapTypeSchema", {
 exports.ClusterMarker = ClusterMarker;
 exports.ClusterStick = ClusterStick;
 exports.Controls = Controls;
+exports.DEFAULT_APPEARANCE_PERSISTENCE_KEY = DEFAULT_APPEARANCE_PERSISTENCE_KEY;
 exports.DEFAULT_MARKER_SIZE_BREAKPOINTS = DEFAULT_MARKER_SIZE_BREAKPOINTS;
 exports.DefaultControls = DefaultControls;
 exports.Layers = Layers;
@@ -12915,6 +13067,7 @@ exports.useEntitiesNearCursor = useEntitiesNearCursor;
 exports.useExpandedIds = useExpandedIds;
 exports.useFitFeatureBounds = useFitFeatureBounds;
 exports.useFitToContent = useFitToContent;
+exports.useHeatmap = useHeatmap;
 exports.useImageOverlay = useImageOverlay;
 exports.useLabelPlacement = useLabelPlacement;
 exports.useLayers = useLayers;
@@ -12928,6 +13081,7 @@ exports.useMarkerStateResolvers = useMarkerStateResolvers;
 exports.useMarkers = useMarkers;
 exports.usePanel = usePanel;
 exports.usePanelPreload = usePanelPreload;
+exports.usePersistedAppearanceSeed = usePersistedAppearanceSeed;
 exports.usePreviewMap = usePreviewMap;
 exports.useRoute = useRoute;
 exports.useShapeLabelHelpers = useShapeLabelHelpers;

package/index.esm.js

@@ -12,6 +12,7 @@ import { isEqual } from 'es-toolkit';
 import { useGeolocation, useErrorHandlerOrNull } from '@trackunit/react-core-hooks';
 import { Checkbox, ToggleSwitch, RadioGroup as RadioGroup$1, RadioItem, FormGroup, Search as Search$1, SelectField, BaseSelect } from '@trackunit/react-form-components';
 import { z } from 'zod';
+import { readLocalStorageValue } from '@trackunit/shared-utils';
 import { PieChart } from 'react-minimal-pie-chart';
 import { tailwindPalette } from '@trackunit/ui-design-tokens';
 import { lngLatToMercatorPxWS, validateBboxWithFallback, extractPositionsFromGeometry, geoJsonPositionSchema, validateFeatureCollection, EMPTY_FEATURE_COLLECTION, splitAntimeridianCrossingFeatures, validateBbox, projectPolygonalToWebMercator, geoJsonPolygonDifference, unprojectPolygonalFromWebMercator, geoJsonPolygonSchema, geoJsonMultiPolygonSchema, distanceToGeoJsonPolygonBoundary, getGeoJsonPolygonIntersection, isFullyContainedInGeometry, isGeoJsonPointInPolygon, isBboxInsideFeatureCollection, extractEdges, computeGeometryCentroid, mercatorPxToLngLatWS, isPositionInsideRing, lngLatToWebMercatorPx, edgePixelLength, isFullyContainedInGeoJsonGeometry } from '@trackunit/geo-json-utils';
@@ -2791,22 +2792,20 @@ const AppearancePreview = ({ adapterConfig, mapType, label, selected, onSelect,
  * @internal
  */
 const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme, currentMapType, onChange, }) => {
-    const derivedConfigs = useMemo(() => {
-        const configs = new Map();
-        for (const option of options) {
-            if (!configs.has(option.theme)) {
-                configs.set(option.theme, adapterConfig.derive({ theme: option.theme }));
-            }
-        }
-        return configs;
-    }, [adapterConfig, options]);
-    return (jsx("div", { "aria-label": ariaLabel, className: "flex flex-wrap items-start gap-2 px-3 py-2", role: "radiogroup", children: options.map(option => {
-            const derivedConfig = derivedConfigs.get(option.theme);
-            if (derivedConfig === undefined) {
-                return null;
-            }
-            return (jsx(AppearancePreview, { adapterConfig: derivedConfig, "data-testid": `map-style-preview-${option.key}`, label: option.label, mapType: option.mapType, onSelect: () => onChange(option.theme, option.mapType), selected: option.theme === currentTheme && option.mapType === currentMapType }, option.key));
-        }) }));
+    const derivedOptions = useMemo(() => options.map(option => ({
+        option,
+        // Pin the full appearance per option: the main map's config may carry a
+        // persisted seed (theme, mapType, roads, traffic — see
+        // usePersistedAppearanceSeed), and a preview depicts exactly one
+        // theme/mapType combination with no overlays.
+        config: adapterConfig.derive({
+            theme: option.theme,
+            mapType: option.mapType,
+            showRoads: false,
+            showTraffic: false,
+        }),
+    })), [adapterConfig, options]);
+    return (jsx("div", { "aria-label": ariaLabel, className: "flex flex-wrap items-start gap-2 px-3 py-2", role: "radiogroup", children: derivedOptions.map(({ option, config }) => (jsx(AppearancePreview, { adapterConfig: config, "data-testid": `map-style-preview-${option.key}`, label: option.label, mapType: option.mapType, onSelect: () => onChange(option.theme, option.mapType), selected: option.theme === currentTheme && option.mapType === currentMapType }, option.key))) }));
 };
 
 // ============================================================================
@@ -2814,10 +2813,16 @@ const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme
 // ============================================================================
 /**
  * Increment this number when the persisted appearance shape changes, and add a
- * matching migration step in useMapAppearanceControls so stored settings are
+ * matching migration step in appearanceMigrations.ts so stored settings are
  * upgraded instead of reset. (v2: added showTraffic.)
  */
 const APPEARANCE_SETTINGS_VERSION = 2;
+/**
+ * Default localStorage key for the persisted map appearance settings.
+ * Shared by `useMapAppearanceControls` (owner) and `usePersistedAppearanceSeed`
+ * (read-only) so both resolve the same stored preference by default.
+ */
+const DEFAULT_APPEARANCE_PERSISTENCE_KEY = "map-appearance-settings";
 // ============================================================================
 // Persisted Appearance Schema (extends core mapAppearanceSchema with version)
 // ============================================================================
@@ -2852,8 +2857,6 @@ const appearanceReducer = (state, action) => {
     }
 };
 
-const DEFAULT_THEMES = ["light", "dark"];
-const DEFAULT_MAP_TYPES = ["roadmap", "satellite"];
 /**
  * The v1 persisted shape, frozen as a literal. Deliberately NOT derived from
  * the live mapAppearanceSchema: deriving would make every future appearance
@@ -2889,6 +2892,20 @@ const appearanceMigrationV2 = {
             : DEFAULT_PERSISTED_APPEARANCE;
     },
 };
+/**
+ * Migration pipeline for the persisted map appearance settings.
+ *
+ * Shared by `useMapAppearanceControls` (the owning reader/writer) and
+ * `usePersistedAppearanceSeed` (a read-only consumer), so both interpret
+ * stored data — including pre-envelope and v1 shapes — identically.
+ */
+const APPEARANCE_MIGRATION = {
+    version: APPEARANCE_SETTINGS_VERSION,
+    steps: [appearanceMigrationV1, appearanceMigrationV2],
+};
+
+const DEFAULT_THEMES = ["light", "dark"];
+const DEFAULT_MAP_TYPES = ["roadmap", "satellite"];
 const themeToTranslationKey = (theme) => {
     switch (theme) {
         case "light":
@@ -2977,7 +2994,7 @@ const buildAppearanceOptions = (themes, mapTypes, t) => {
  * <Controls api={api} controls={controlsConfig} />
  * ```
  */
-const useMapAppearanceControls = ({ api, options: appearanceOptions, persistenceKey = "map-appearance-settings", }) => {
+const useMapAppearanceControls = ({ api, options: appearanceOptions, persistenceKey = DEFAULT_APPEARANCE_PERSISTENCE_KEY, }) => {
     const [t] = useTranslation();
     const themes = appearanceOptions?.themes ?? DEFAULT_THEMES;
     const mapTypes = appearanceOptions?.mapTypes ?? DEFAULT_MAP_TYPES;
@@ -2992,7 +3009,7 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
     const [localState, dispatch] = useLocalStorageReducer({
         key: persistenceKey,
         defaultState: DEFAULT_PERSISTED_APPEARANCE,
-        migration: { version: APPEARANCE_SETTINGS_VERSION, steps: [appearanceMigrationV1, appearanceMigrationV2] },
+        migration: APPEARANCE_MIGRATION,
         reducer: appearanceReducer,
         schema: persistedAppearanceSchema,
     });
@@ -3240,7 +3257,11 @@ const useDefaultControls = (api, options) => {
             "data-testid": "map-my-location-button",
         }, [api.actions, getPosition, options?.navigation?.myLocation?.enabled, t]);
     const navigationControls = useMemo(() => defineControlStack([myLocationControl, zoomControl, fullscreenControl]), [fullscreenControl, myLocationControl, zoomControl]);
-    const mapAppearanceControls = useMapAppearanceControls({ api });
+    const mapAppearanceControls = useMapAppearanceControls({
+        api,
+        options: options?.settings?.mapStyle?.options,
+        persistenceKey: options?.settings?.mapStyle?.persistenceKey,
+    });
     const mapStyleControl = useMemo(() => options?.settings?.mapStyle?.enabled === false ? undefined : mapAppearanceControls[0], [mapAppearanceControls, options?.settings?.mapStyle?.enabled]);
     const settingsControls = useMemo(() => defineControlStack([mapStyleControl]), [mapStyleControl]);
     return useMemo(() => ({
@@ -3361,6 +3382,57 @@ const useControls = (base, areas) => {
     }, [base, areas]);
 };
 
+/**
+ * Reads the persisted map appearance once (on mount) so it can seed the adapter
+ * factory, letting the FIRST map be constructed with the user's stored theme,
+ * map type, and traffic preference instead of being corrected after mount.
+ *
+ * Without the seed, a stored dark theme or traffic-on preference only reaches
+ * the adapter once the map is ready, forcing an immediate map recreation on
+ * every page load: a visible blink, a wasted provider map construction (each
+ * one is a billed Dynamic Maps load on Google), and overlays built on a
+ * throwaway instance (ADR 0029).
+ *
+ * Read-only: `useMapAppearanceControls` keeps owning the persistence and pushes
+ * all later changes through the adapter's appearance actions. The seed is
+ * deliberately not reactive — it only matters at construction time.
+ *
+ * Storage being unavailable or corrupt is never an error: the seed then falls
+ * back to the defaults, which is exactly the pre-seeding behavior.
+ *
+ * @example
+ * ```tsx
+ * const appearanceSeed = usePersistedAppearanceSeed();
+ * const [Map, api] = useMap(googleMapsAdapter({ apiKey, ...appearanceSeed }));
+ * ```
+ */
+const usePersistedAppearanceSeed = (params) => {
+    const [seed] = useState(() => {
+        let persisted = DEFAULT_PERSISTED_APPEARANCE;
+        try {
+            persisted = readLocalStorageValue({
+                key: params?.persistenceKey ?? DEFAULT_APPEARANCE_PERSISTENCE_KEY,
+                defaultState: DEFAULT_PERSISTED_APPEARANCE,
+                schema: persistedAppearanceSchema,
+                migration: APPEARANCE_MIGRATION,
+            });
+        }
+        catch {
+            // Accessing localStorage can throw (privacy mode, blocked site data,
+            // non-browser rendering) — fall through to the defaults.
+        }
+        return {
+            theme: persisted.theme,
+            mapType: persisted.mapType,
+            showRoads: persisted.showRoads,
+            // `traffic: false` opts the whole surface out of traffic (see
+            // useMapAppearanceControls), so it must override a stored preference here too
+            showTraffic: params?.options?.traffic === false ? false : persisted.showTraffic,
+        };
+    });
+    return seed;
+};
+
 const MARKER_SPRING_CONFIG = {
     stiffness: 380,
     damping: 30,
@@ -5172,7 +5244,7 @@ const useLayerReady = (loading) => {
 // ============================================================================
 // Constants
 // ============================================================================
-const EMPTY_CONTROLS$3 = {};
+const EMPTY_CONTROLS$4 = {};
 // ============================================================================
 // Hook
 // ============================================================================
@@ -5212,7 +5284,7 @@ const useImageOverlay = (options) => {
         ready: layerReady.ready,
         getBounds,
         counts,
-        controls: controls ?? EMPTY_CONTROLS$3,
+        controls: controls ?? EMPTY_CONTROLS$4,
         fitParticipation,
         layerType: "image-overlay",
         url,
@@ -5493,7 +5565,7 @@ const createLazyGetter = (compute) => {
 // ============================================================================
 // Constants
 // ============================================================================
-const EMPTY_CONTROLS$2 = {};
+const EMPTY_CONTROLS$3 = {};
 const EMPTY_FEATURES$1 = { type: "FeatureCollection", features: [] };
 // ============================================================================
 // Internal helpers
@@ -5581,7 +5653,7 @@ const useRoute = (options) => {
         ready: layerReady.ready,
         getBounds,
         counts,
-        controls: controls ?? EMPTY_CONTROLS$2,
+        controls: controls ?? EMPTY_CONTROLS$3,
         fitParticipation,
         layerType: "route",
         features,
@@ -5707,6 +5779,78 @@ const useFitToContent = (api, handles, options) => {
     return useMemo(() => ({ hasFitted, isWaiting, fitNow }), [hasFitted, isWaiting, fitNow]);
 };
 
+const EMPTY_CONTROLS$2 = {};
+/**
+ * Weighted point heatmap layer handle (provider-agnostic).
+ *
+ * - Normalizes `data` → GeoJSON `Point` features + `properties.weight`.
+ * - Synced as `HeatmapSourceConfig` in {@link LayerSnapshot}.
+ * - Renderers: ADR-0029 (`libs/react/map/docs/adr/0029-heatmap-provider-specific-renderers.md`).
+ */
+const useHeatmap = (options) => {
+    const { id, name, data, getPosition, getWeight, style, controls, loading, fitParticipation = "all" } = options;
+    const layerReady = useLayerReady(loading);
+    const normalized = useMemo(() => {
+        const features = [];
+        const positions = [];
+        for (const item of data) {
+            const position = getPosition(item);
+            if (position === null)
+                continue;
+            const parsedPosition = geoJsonPositionSchema.safeParse(position);
+            if (!parsedPosition.success)
+                continue;
+            const weight = getWeight?.(item) ?? 1;
+            if (!Number.isFinite(weight) || weight <= 0)
+                continue;
+            positions.push(parsedPosition.data);
+            features.push({
+                type: "Feature",
+                geometry: { type: "Point", coordinates: parsedPosition.data },
+                properties: { weight },
+            });
+        }
+        return {
+            features: { type: "FeatureCollection", features },
+            positions,
+        };
+    }, [data, getPosition, getWeight]);
+    const resolvedStyle = useMemo(() => ({
+        radiusPixels: style?.radiusPixels ?? 30,
+        intensity: style?.intensity ?? 1,
+        opacity: style?.opacity ?? 1,
+    }), [style?.radiusPixels, style?.intensity, style?.opacity]);
+    const getBounds = useMemo(() => createLazyGetter(() => computeBoundsFromPositions(normalized.positions)), [normalized.positions]);
+    const counts = useMemo(() => ({ total: data.length, points: normalized.features.features.length }), [data.length, normalized.features.features.length]);
+    return useMemo(() => ({
+        id,
+        name,
+        loadsData: layerReady.loadsData,
+        loading: layerReady.isLoading,
+        ready: layerReady.ready,
+        getBounds,
+        counts,
+        controls: controls ?? EMPTY_CONTROLS$2,
+        fitParticipation,
+        layerType: "heatmap",
+        features: normalized.features,
+        style: resolvedStyle,
+        pointCount: normalized.features.features.length,
+        totalCount: data.length,
+    }), [
+        id,
+        name,
+        layerReady,
+        getBounds,
+        counts,
+        controls,
+        fitParticipation,
+        normalized.features,
+        resolvedStyle,
+        data.length,
+    ]);
+};
+
 /**
  * Do two label footprints overlap? Each is a box of its own size centred on its point, so the boxes
  * overlap when the centres are closer than the sum of their half-extents in each axis. Shared by the
@@ -8001,6 +8145,13 @@ function toMapLayer(handle) {
                 imageBounds: handle.imageBounds,
                 opacity: handle.opacity,
             };
+        case "heatmap":
+            return {
+                layerType: "heatmap",
+                id: handle.id,
+                features: handle.features,
+                style: handle.style,
+            };
         default: {
             const exhaustiveCheck = handle;
             throw new Error(`${String(exhaustiveCheck)} is not known`);
@@ -12828,4 +12979,4 @@ const mockMapApi = (overrides) => {
  */
 setupLibraryTranslations();
 
-export { ClusterMarker, ClusterStick, Controls, DEFAULT_MARKER_SIZE_BREAKPOINTS, DefaultControls, Layers, MARKER_DARK_PILL, MARKER_DISC_BORDER_WIDTH_PX, MARKER_LIGHT_PILL, MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, MARKER_TUNING, MapLoadingState, MapMarker, MapMarkerIcon, PanelIconButton, ShapeAnnotationLabel, buildExpandedIds, cvaMapMarker, cvaMarkerIndicator, mockMapApi, useAdaptiveMarkerHelpers, useAutoPanResolver, useCameraIdle, useCameraState, useClusterCountFormat, useControlStack, useControls, useDefaultControls, useDirectionIndicator, useEntitiesNearCursor, useExpandedIds, useFitFeatureBounds, useFitToContent, useImageOverlay, useLabelPlacement, useLayers, useMap, useMapAnnotation, useMapAnnotations, useMapAppearanceControls, useMapKeyboardNavigation, useMarkerColors, useMarkerStateResolvers, useMarkers, usePanel, usePanelPreload, usePreviewMap, useRoute, useShapeLabelHelpers, useShapes, useViewportContext };
+export { ClusterMarker, ClusterStick, Controls, DEFAULT_APPEARANCE_PERSISTENCE_KEY, DEFAULT_MARKER_SIZE_BREAKPOINTS, DefaultControls, Layers, MARKER_DARK_PILL, MARKER_DISC_BORDER_WIDTH_PX, MARKER_LIGHT_PILL, MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, MARKER_TUNING, MapLoadingState, MapMarker, MapMarkerIcon, PanelIconButton, ShapeAnnotationLabel, buildExpandedIds, cvaMapMarker, cvaMarkerIndicator, mockMapApi, useAdaptiveMarkerHelpers, useAutoPanResolver, useCameraIdle, useCameraState, useClusterCountFormat, useControlStack, useControls, useDefaultControls, useDirectionIndicator, useEntitiesNearCursor, useExpandedIds, useFitFeatureBounds, useFitToContent, useHeatmap, useImageOverlay, useLabelPlacement, useLayers, useMap, useMapAnnotation, useMapAnnotations, useMapAppearanceControls, useMapKeyboardNavigation, useMarkerColors, useMarkerStateResolvers, useMarkers, usePanel, usePanelPreload, usePersistedAppearanceSeed, usePreviewMap, useRoute, useShapeLabelHelpers, useShapes, useViewportContext };

package/package.json

@@ -1,22 +1,23 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.180-alpha-7fd06f36b49.0",
+  "version": "0.2.183",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "3.4.1-alpha-7fd06f36b49.0",
-    "@trackunit/css-class-variance-utilities": "2.1.1-alpha-7fd06f36b49.0",
-    "@trackunit/react-form-components": "2.8.1-alpha-7fd06f36b49.0",
-    "@trackunit/react-core-hooks": "1.23.1-alpha-7fd06f36b49.0",
-    "@trackunit/geo-json-utils": "1.16.1-alpha-7fd06f36b49.0",
-    "@trackunit/i18n-library-translation": "2.6.1-alpha-7fd06f36b49.0",
+    "@trackunit/react-components": "3.4.4",
+    "@trackunit/css-class-variance-utilities": "2.1.3",
+    "@trackunit/react-form-components": "2.8.4",
+    "@trackunit/react-core-hooks": "1.23.3",
+    "@trackunit/geo-json-utils": "1.16.3",
+    "@trackunit/i18n-library-translation": "2.6.3",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.142-alpha-7fd06f36b49.0",
-    "@trackunit/react-map-color-utils": "0.0.117-alpha-7fd06f36b49.0",
-    "@trackunit/ui-design-tokens": "1.16.1-alpha-7fd06f36b49.0",
+    "@trackunit/react-map-adapter-shared": "0.0.144",
+    "@trackunit/react-map-color-utils": "0.0.119",
+    "@trackunit/shared-utils": "1.17.3",
+    "@trackunit/ui-design-tokens": "1.16.3",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.39.10",
     "tailwind-merge": "^2.0.0",

package/src/appearance/appearanceMigrations.d.ts

@@ -0,0 +1,9 @@
+import type { MigrationConfig } from "@trackunit/react-components";
+/**
+ * Migration pipeline for the persisted map appearance settings.
+ *
+ * Shared by `useMapAppearanceControls` (the owning reader/writer) and
+ * `usePersistedAppearanceSeed` (a read-only consumer), so both interpret
+ * stored data — including pre-envelope and v1 shapes — identically.
+ */
+export declare const APPEARANCE_MIGRATION: MigrationConfig;

package/src/appearance/appearanceTypes.d.ts

@@ -3,10 +3,16 @@ import { z } from "zod";
 import { type MapActions, type MapStatus, type MapTheme, type MapType } from "../core/types";
 /**
  * Increment this number when the persisted appearance shape changes, and add a
- * matching migration step in useMapAppearanceControls so stored settings are
+ * matching migration step in appearanceMigrations.ts so stored settings are
  * upgraded instead of reset. (v2: added showTraffic.)
  */
 export declare const APPEARANCE_SETTINGS_VERSION = 2;
+/**
+ * Default localStorage key for the persisted map appearance settings.
+ * Shared by `useMapAppearanceControls` (owner) and `usePersistedAppearanceSeed`
+ * (read-only) so both resolve the same stored preference by default.
+ */
+export declare const DEFAULT_APPEARANCE_PERSISTENCE_KEY = "map-appearance-settings";
 export declare const persistedAppearanceSchema: z.ZodObject<{
     theme: z.ZodEnum<["light", "dark"]>;
     mapType: z.ZodEnum<["roadmap", "satellite", "hybrid"]>;

package/src/appearance/usePersistedAppearanceSeed.d.ts

@@ -0,0 +1,51 @@
+import type { MapAppearance } from "@trackunit/react-map-adapter-shared";
+import { type AppearanceOptions } from "./appearanceTypes";
+/**
+ * The persisted appearance as a seed for adapter construction: every field
+ * resolved (`showTraffic` is optional in the core `MapAppearance` for external
+ * compatibility, but a seed always knows its value). The shape spreads directly
+ * into an adapter factory's `BaseAdapterConfig` fields.
+ */
+export type MapAppearanceSeed = Readonly<Required<MapAppearance>>;
+/** Parameters for the usePersistedAppearanceSeed hook */
+export type UsePersistedAppearanceSeedParams = Readonly<{
+    /**
+     * localStorage persistence key. Must match the `persistenceKey` passed to
+     * `useMapAppearanceControls` on the same surface. Default: "map-appearance-settings"
+     */
+    persistenceKey?: string;
+    /**
+     * The surface's appearance options (the same object given to
+     * `useMapAppearanceControls` works). Only `traffic` affects the seed: a
+     * surface with `traffic: false` must not seed a traffic-on preference stored
+     * by another surface sharing the persistence key. `themes`/`mapTypes` never
+     * clamp the seed, matching the controls' push path, which does not clamp
+     * stored values either — hence the narrowed Pick.
+     */
+    options?: Pick<AppearanceOptions, "traffic">;
+}>;
+/**
+ * Reads the persisted map appearance once (on mount) so it can seed the adapter
+ * factory, letting the FIRST map be constructed with the user's stored theme,
+ * map type, and traffic preference instead of being corrected after mount.
+ *
+ * Without the seed, a stored dark theme or traffic-on preference only reaches
+ * the adapter once the map is ready, forcing an immediate map recreation on
+ * every page load: a visible blink, a wasted provider map construction (each
+ * one is a billed Dynamic Maps load on Google), and overlays built on a
+ * throwaway instance (ADR 0029).
+ *
+ * Read-only: `useMapAppearanceControls` keeps owning the persistence and pushes
+ * all later changes through the adapter's appearance actions. The seed is
+ * deliberately not reactive — it only matters at construction time.
+ *
+ * Storage being unavailable or corrupt is never an error: the seed then falls
+ * back to the defaults, which is exactly the pre-seeding behavior.
+ *
+ * @example
+ * ```tsx
+ * const appearanceSeed = usePersistedAppearanceSeed();
+ * const [Map, api] = useMap(googleMapsAdapter({ apiKey, ...appearanceSeed }));
+ * ```
+ */
+export declare const usePersistedAppearanceSeed: (params?: UsePersistedAppearanceSeedParams) => MapAppearanceSeed;

package/src/controls/useDefaultControls.d.ts

@@ -1,4 +1,5 @@
 import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import type { AppearanceOptions } from "../appearance/appearanceTypes";
 import type { ContainerRefHolder, MapActions, MapStatus } from "../core/types";
 import type { BuiltInControlsConfig } from "./types";
 /**
@@ -21,6 +22,18 @@ export type UseDefaultControlsOptions = Readonly<{
     settings?: Readonly<{
         mapStyle?: Readonly<{
             enabled?: boolean;
+            /**
+             * Appearance options forwarded to `useMapAppearanceControls`. A surface
+             * that also uses `usePersistedAppearanceSeed` must pass the same options
+             * to both, so opt-outs (e.g. `traffic: false`) apply to the seed too.
+             */
+            options?: AppearanceOptions;
+            /**
+             * localStorage key forwarded to `useMapAppearanceControls`. A surface
+             * that also uses `usePersistedAppearanceSeed` must pass the same key to
+             * both. Default: "map-appearance-settings"
+             */
+            persistenceKey?: string;
         }>;
     }>;
 }>;

package/src/core/__testHelpers.d.ts

@@ -1,7 +1,7 @@
-import type { AdapterConfig, AdapterInstance, AdapterRendererProps, CameraState, MapStatus, SafeAreaInsets } from "@trackunit/react-map-adapter-shared";
+import type { AdapterConfig, AdapterInstance, AdapterRendererProps, BaseAdapterConfig, CameraState, MapStatus, SafeAreaInsets } from "@trackunit/react-map-adapter-shared";
 import type { ReactElement } from "react";
 import type { MapApi, MapState } from "./types";
-export type MockConfig = {
+export type MockConfig = BaseAdapterConfig & {
     readonly apiKey: string;
 };
 export declare const INITIAL_MOCK_MAP_STATE: MapState;

package/src/index.d.ts

@@ -17,12 +17,14 @@ export type { UseControlsAreas } from "./controls/types";
 export { useControls } from "./controls/useControls";
 export { useDefaultControls, type UseDefaultControlsOptions } from "./controls/useDefaultControls";
 export type { AppearanceAction, AppearanceOption, AppearanceOptions, MapAppearanceApi, PersistedAppearance, UseMapAppearanceControlsParams, } from "./appearance/appearanceTypes";
+export { DEFAULT_APPEARANCE_PERSISTENCE_KEY } from "./appearance/appearanceTypes";
 export { useMapAppearanceControls } from "./appearance/useMapAppearanceControls";
+export { usePersistedAppearanceSeed, type MapAppearanceSeed, type UsePersistedAppearanceSeedParams, } from "./appearance/usePersistedAppearanceSeed";
 export type { ControlMiddleware, MiddlewareContext } from "./controls/renderingRules";
 export type { CategoryMetadata } from "./controls/collapseControls";
 export type { ClusterEntity, Entity, MapInteractionState, MarkerEntity, RouteEntity, ShapeEntity, ShapeType, } from "@trackunit/react-map-adapter-shared";
 export { geometryTypeToShapeType, INITIAL_INTERACTION_STATE } from "@trackunit/react-map-adapter-shared";
-export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterInfo, ClusterRenderState, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, FitParticipation, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeOverlapConfig, ShapeStyle, ShapeStyleOverrides, ShapesUnderCursorHit, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./layers/types";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterInfo, ClusterRenderState, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, FitParticipation, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapLayerHandle, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeOverlapConfig, ShapeStyle, ShapeStyleOverrides, ShapesUnderCursorHit, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./layers/types";
 export { computeMarkerDomPortalZIndex } from "./layers/types";
 export { ANCHOR_SELECTOR, HIT_SURFACE_SELECTOR } from "@trackunit/react-map-adapter-shared";
 export { ClusterMarker, type ClusterMarkerProps, type ClusterMarkerStickInput, type ClusterSegment, } from "./clusters/ClusterMarker";
@@ -53,6 +55,7 @@ export { useImageOverlay, type UseImageOverlayOptions, type UseImageOverlayRetur
 export { buildExpandedIds, useExpandedIds, type MapFocus, type MapFocusTier, type MapFocusTierDisplay, } from "./layers/mapFocus";
 export { useRoute, type UseRouteOptions, type UseRouteReturn } from "./layers/routes/useRoute";
 export { useFitToContent, type FitToContentOptions, type FitToContentResult } from "./layers/useFitToContent";
+export { useHeatmap, type HeatmapStyle, type UseHeatmapOptions, type UseHeatmapReturn, } from "./layers/useHeatmap/useHeatmap";
 export { useLabelPlacement, type UseLabelPlacementParams } from "./layers/useLabelPlacement";
 export { useLayers, type UseLayersReturn } from "./layers/useLayers";
 export { DEFAULT_MARKER_SIZE_BREAKPOINTS, MARKER_DISC_BORDER_WIDTH_PX, type MarkerSizeBreakpoint, type PickMarkerSizeOptions, type PickRenderMediumOptions, type PickSymbolDiameterOptions, } from "./layers/useMarkers/adaptiveHelpers";

package/src/layers/types.d.ts

@@ -1,12 +1,12 @@
 import type { GeoJsonBbox, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, GeoJsonPosition } from "@trackunit/geo-json-utils";
-import type { AdaptiveMarkerResolution, ClusterConfig, ClusterRenderConfig, RenderConfig, RouteStyle, ShapeInteractiveMode, ShapeStyle } from "@trackunit/react-map-adapter-shared";
+import type { AdaptiveMarkerResolution, ClusterConfig, ClusterRenderConfig, HeatmapRenderStyle, RenderConfig, RouteStyle, ShapeInteractiveMode, ShapeStyle } from "@trackunit/react-map-adapter-shared";
 import type { CategoryKey, ControlConfig } from "../controls/types";
 import type { ShapeDecoration } from "./useShapes/shapeDecorations";
 import type { ShapesUnderCursorHit } from "./useShapes/shapeFillTiling";
 import type { ShapeLabelResolutionContext } from "./useShapes/shapeLabelResolution";
 import type { ResolveShapeStackOrder } from "./useShapes/shapeStackOrder";
 export type { ShapesUnderCursorHit };
-export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapRenderStyle, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
 export { computeMarkerDomPortalZIndex } from "@trackunit/react-map-adapter-shared";
 /**
  * Controls whether a layer's bounds are included in fit-to-content operations.
@@ -187,8 +187,13 @@ export interface ImageOverlayHandle extends LayerMeta {
     /** Opacity from 0 to 1 */
     readonly opacity: number;
 }
+export interface HeatmapLayerHandle extends LayerMeta {
+    readonly layerType: "heatmap";
+    readonly features: GeoJsonFeatureCollection;
+    readonly style: HeatmapRenderStyle;
+}
 /**
  * Discriminated union of all layer handle types.
  * Discriminated on `layerType`.
  */
-export type LayerHandle = MarkerLayerHandle | ShapeLayerHandle | RouteLayerHandle | ImageOverlayHandle;
+export type LayerHandle = MarkerLayerHandle | ShapeLayerHandle | RouteLayerHandle | ImageOverlayHandle | HeatmapLayerHandle;

package/src/layers/useHeatmap/heatmapPocFixture.d.ts

@@ -0,0 +1,7 @@
+import type { GeoJsonBbox, GeoJsonPosition } from "@trackunit/geo-json-utils";
+export type HeatmapPocPoint = Readonly<{
+    position: GeoJsonPosition;
+    weight: number;
+}>;
+export declare const HEATMAP_POC_BOUNDS: GeoJsonBbox;
+export declare const HEATMAP_POC_POINTS: ReadonlyArray<HeatmapPocPoint>;

package/src/layers/useHeatmap/useHeatmap.d.ts

@@ -0,0 +1,31 @@
+import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { CategoryKey, ControlConfig } from "../../controls/types";
+import type { FitParticipation, HeatmapLayerHandle } from "../types";
+export type HeatmapStyle = Readonly<{
+    radiusPixels?: number;
+    intensity?: number;
+    opacity?: number;
+}>;
+export type UseHeatmapOptions<TItem> = Readonly<{
+    id: string;
+    name: string;
+    data: ReadonlyArray<TItem>;
+    getPosition: (item: TItem) => GeoJsonPosition | null;
+    getWeight?: (item: TItem) => number;
+    style?: HeatmapStyle;
+    controls?: Partial<Record<CategoryKey, ReadonlyArray<ControlConfig>>>;
+    loading?: boolean;
+    fitParticipation?: FitParticipation;
+}>;
+export interface UseHeatmapReturn extends HeatmapLayerHandle {
+    readonly pointCount: number;
+    readonly totalCount: number;
+}
+/**
+ * Weighted point heatmap layer handle (provider-agnostic).
+ *
+ * - Normalizes `data` → GeoJSON `Point` features + `properties.weight`.
+ * - Synced as `HeatmapSourceConfig` in {@link LayerSnapshot}.
+ * - Renderers: ADR-0029 (`libs/react/map/docs/adr/0029-heatmap-provider-specific-renderers.md`).
+ */
+export declare const useHeatmap: <TItem>(options: UseHeatmapOptions<TItem>) => UseHeatmapReturn;