Add Reanimated cluster fade with settle-gated cross-fade

README.md

@@ -55,18 +55,24 @@ That is it. Your `<Marker>` children, cluster props, and `react-native-maps` opt
 ### Bare React Native
 
 ```bash
-npm install @gmisoftware/react-native-better-clustering react-native-nitro-modules react-native-maps
+npm install @gmisoftware/react-native-better-clustering react-native-nitro-modules react-native-maps react-native-reanimated react-native-worklets
 cd ios && pod install && cd ..
 ```
 
-Rebuild the native app after installing.
+Rebuild the native app after installing. Add the Worklets Babel plugin (last in the list) to `babel.config.js`:
+
+```js
+plugins: ['react-native-worklets/plugin']
+```
 
 ### Expo
 
 ```bash
-npx expo install @gmisoftware/react-native-better-clustering react-native-nitro-modules react-native-maps
+npx expo install @gmisoftware/react-native-better-clustering react-native-nitro-modules react-native-maps react-native-reanimated react-native-worklets
 ```
 
+`babel-preset-expo` wires up the Worklets plugin automatically.
+
 Add the `react-native-maps` plugin to `app.json`:
 
 ```json

docs/docs/api/mapview.md

@@ -66,6 +66,7 @@ are supported, plus:
 | `clusterFontFamily` | — | Font family for cluster count label |
 | `animationEnabled` | `true` | Animate cluster changes (iOS only) |
 | `layoutAnimationConf` | 200ms easeInEaseOut create/delete + scale update | LayoutAnimation config when `animationEnabled` (tuned for cluster bubble transitions; pass a custom config to override) |
+| `clusterFadeInDuration` | `250` | Cross-fade duration (ms) for default cluster bubbles on zoom: new bubbles fade in while removed ones linger and fade out, eliminating the blink from native annotations being added/removed (iOS + Android). Driven by Reanimated on the UI thread. The fade-out cross-fade is applied to the settled cluster set only — during an active pinch/pan, removed bubbles are dropped immediately so a continuous zoom does not stack multiple bubble generations and overload the JS thread. Gated by `animationEnabled`; ignored with a custom `renderCluster`. Set to `0` to disable |
 | `tracksViewChanges` | `false` | Forwarded to default cluster markers |
 | `edgePadding` | 50px each side | Padding for `fitToCoordinates` on cluster press |
 | `preserveClusterPressBehavior` | `false` | Skip auto `fitToCoordinates` on cluster press |

docs/docs/setup/installation.md

@@ -19,6 +19,27 @@ npm install react-native-maps
 cd ios && pod install
 ```
 
+### Reanimated (required)
+
+Cluster bubbles fade in on zoom using [Reanimated](https://docs.swmansion.com/react-native-reanimated/),
+which runs the animation on the UI thread:
+
+```bash
+npm install react-native-reanimated react-native-worklets
+cd ios && pod install
+```
+
+In **bare React Native**, add the Worklets Babel plugin (must be last) to `babel.config.js`:
+
+```js
+module.exports = {
+  presets: ['module:@react-native/babel-preset'],
+  plugins: ['react-native-worklets/plugin'],
+}
+```
+
+With **Expo**, `babel-preset-expo` adds this plugin automatically — no Babel changes needed.
+
 ## New Architecture
 
 This library is a Nitro module and requires React Native's **New Architecture**.
@@ -29,7 +50,7 @@ Confirm it is enabled and rebuild the native app.
 Use a [development build](https://docs.expo.dev/develop/development-builds/introduction/) — not Expo Go.
 
 ```bash
-npx expo install @gmisoftware/react-native-better-clustering react-native-nitro-modules react-native-maps
+npx expo install @gmisoftware/react-native-better-clustering react-native-nitro-modules react-native-maps react-native-reanimated react-native-worklets
 ```
 
 Add the `react-native-maps` config plugin to `app.json`: