Documentation accuracy: installation, migration differences and performance claims

[jkasprzyk17]

Problem

The docs don't match the code in these places:

• Migration guide. It says props "keep working", but these differences are undocumented:

  • the onRegionChangeComplete signature (Document that onRegionChangeComplete follows react-native-map-clustering 4.x, not 3.x (and warn in dev) #29)
  • marker keys (Marker keys are replaced by index keys (marker-${index}) #28)
  • style is applied to a wrapper <View style={[{flex: 1}, style]}> (MapView.tsx:681,700-706). Verify on device before deciding whether to forward it (that would be breaking).
  • the default cluster colour is #0F52FF, but the README says "green"
  • layoutAnimationConf
  • RenderClusterProps has no clusterFontFamily
  • the superClusterRef lifecycle: it's replaced by an unbuilt instance on every rebuild and is null when clustering is disabled

• spiralEnabled is documented as "on cluster press" / "at max zoom", but it's automatic and currently unreachable (Spiderfy never triggers for co-located markers #22).

• animationEnabled is documented as "iOS only", but it also gates the Android fade.

• Marker detection rules aren't documented: only direct children with a top-level coordinate prop are clustered. Fragments and wrapper components silently render unclustered.

• Performance claims. These are unbacked or inaccurate:

  • "faster"
  • "instead of JavaScript on the RN bridge"
  • "off the JS thread": only the build is; queries are synchronous JSI
  • "zero-copy": the buffer is copied into C++
  • the FPS tables

  Sources: README.md:5,35,45,211-229, the homepage features, packPoints.ts:32.

• API reference gaps:

  • The Supercluster class methods aren't documented at all.
  • The /clusterer snippet uses the private featureKey.
  • The defaults differ from react-native-clusterer (minZoom 1 / maxZoom 20 vs 0 / 16).
  • map/reduce is advertised but unsupported (only sum/min/max).

• Missing topics:

  • a Jest guide (Ship a Jest mock so apps can test screens that render MapView #30)
  • the threading contract for /engine (buildAsync is not thread-safe and captures a raw this #23)
  • antimeridian notes (Markers across the antimeridian (±180°) disappear #18)

• Stale: a CONTRIBUTING checklist that mentions a tab and 30k markers.

Suggested fix

• Add a "Differences from react-native-map-clustering" page with a table.
• Add a performance model page: "async build, synchronous query; rendering is the ceiling".
• Add a marker rules section and a testing guide.
• Fix each inaccurate line.
• Tie performance numbers only to the benchmark output (Add a reproducible benchmark suite with a CI regression gate #20).

Acceptance criteria

• Every item above is fixed or explicitly deferred.
• bun run docs:build passes.
• No performance claim appears without a linked benchmark.

---

Priority: P2 · Breaking change: No · Depends on: land the related code fixes first where behaviour changes (#12, #29, #22, #31)

_{From the engineering audit of main@7c7d659 (2026-09-29) · audit ref I-23. Line numbers refer to that commit.}