[Bug] 3D map with terrain jitters when moving around

[leverglowh]

Describe the bug
After adding terrain to a maplibre map in 3d mode, the map camera elevation changes during movement, seemingly following terrain elevation.
This bug was observed and resolved over at react-map-gl at v8 (see visgl/react-map-gl#2211) while Kepler is currently using v7.
The weird thing is when I tested the bug with react-map-gl directly, I was only able to reproduce it with react-map-gl v7 + maplibre-gl-js v2.
Kepler is currently dependent on MaplibreGL 3.6.2, which according to my tests should only jitter on "moveend".
I'll summarize the versions and bug behavior:

react-map-gl	maplibre-gl-js	Bug behavior
8.1.1	2.4.0 / 3.6.2	no issue
7.1.6	3.6.2	jitter on moveend
7.1.6	2.4.0	jitter during move

To Reproduce
Move the map to somewhere with a lot of mountains then move around.

I've created a minimal repo to reproduce this issue with Kepler: https://github.com/leverglowh/keplergl-terrain-jitter
Steps are the usual: git clone, npm install, add .env file, npm run dev (starts at port 5668)
Only relevant code is in /src/App.tsx.

---

To test react-map-gl with maplibre-gl-js all I did was:

1. clone https://github.com/visgl/react-map-gl/tree/master/examples/get-started/maplibre
2. pin versions in package.json. Note: import path changes between v8 and v7, see import changes
3. update app.jsx to include terrain: update line 17 to be:

mapStyle = {{
  version: 8,
  sources: {
    osm: {
      type: "raster",
      tiles: ["https://a.tile.openstreetmap.org/{z}/{x}/{y}.png"],
      tileSize: 256,
      attribution: "© OpenStreetMap Contributors",
      maxzoom: 19,
    },
    terrain: {
      type: "raster-dem",
      url: "https://tiles.mapterhorn.com/tilejson.json",
    },
    hillshadeSource: {
      type: "raster-dem",
      url: "https://tiles.mapterhorn.com/tilejson.json",
    },
  },
  layers: [
    {
      id: "osm",
      type: "raster",
      source: "osm",
    },
    {
      id: "hillshade",
      type: "hillshade",
      source: "hillshadeSource",
      layout: { visibility: "visible" },
      paint: { "hillshade-shadow-color": "#473B24" },
    },
  ],
  terrain: {
    source: "terrain",
    exaggeration: 1.5,
  },
  sky: {},
}}

4. npm install
5. npm run start

Expected behavior
Given the current dependencies, I would expect Kepler's map to jitter on moveend, and not during move.
Would be nice if it didn't jitter at all.

Would also be nice if we could upgrade to react-map-gl v8, but that requires some work since export paths and types changed.

Screenshots

Screen.Recording.2026-04-29.at.19.24.58.mov

Desktop (please complete the following information):

• OS: both macOS and Windows
• Browser: chrome, safari, firefox
• Version: tested from 3.2.0 to latest 3.2.6, didn't try earlier versions

Additional context
I'll link some resources I bumped into while investigating this:

• Maplibre GL exposes a callback called transformCameraUpdate that could potentially let you override the elevation (I think, it didn't work for me) https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#transformcameraupdate
• Maplibre GL (only since v5) introduced a method setCenterClampedToGround https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/#setcenterclampedtoground
• Maplibre jitter on low map pitch (Terrain / camera jumps upon dragend / movend / mouseup when moving the view on globe at low pitch. maplibre/maplibre-gl-js#7025): not the case of this issue, but with the introduction of maxPitch option it could be

[igorDykhta]

On the latest master we upgraded to react-map-gl 8

[leverglowh]

I've updated leverglowh/keplergl-terrain-jitter with version 3.3.0-alpha.1 and am still encountering this issue.
react-map-gl has been updated to 8, I can see it in node_modules, but the error persists.

At this point I'm not sure what is causing it anymore, but it would explain why on Kepler the versions reproducing the error is not persistent with tests performed with plain react-map-gl and maplibre-gl-js.
Is there any calculation done on map pan that overrides the default?

[jo-chemla]

This screenshot looks a lot like an issue I had when trying to smoothly animate a camera along a path on terrain-viewer, with terrain enabled - from the top of my head, this is linked to terrain collision detection even when camera is far from terrain.

The fix was in my case to use jumpTo rather than easeTo — jumpTo is synchronous and bypasses the animation pipeline, so it correctly re-asserts pose. See the below feature request for disabling terrain collision detection.

maplibre/maplibre-gl-js#5004