Fix laggy globe dragging with atmospheric effects (#1653)

* perf: reduce redundant map rendering work

* fix: preserve overlays and enforce effect frame pacing

* fix: keep comet timing independent of refresh rate

Author: santiago-ramos-02

packages/map/src/MapCanvas.tsx

@@ -1114,7 +1114,6 @@ export const MapCanvas = memo(function MapCanvas({
     map.on("projectiontransition", updateProjection);
     map.on("load", () => {
       const state = useAppStore.getState();
-      mc.waitAndSyncLayers(applyGroupEffects(state.layers, state.layerGroups));
       mc.setBasemapVisible(state.basemapVisible);
       mc.setBasemapOpacity(state.basemapOpacity);
       mc.highlightFeature(
@@ -1186,7 +1185,6 @@ export const MapCanvas = memo(function MapCanvas({
     prevBasemap.current = basemapStyleUrl;
     map.once("style.load", () => {
       const state = useAppStore.getState();
-      controller.current?.waitAndSyncLayers(applyGroupEffects(state.layers, state.layerGroups));
       controller.current?.setBasemapVisible(state.basemapVisible);
       controller.current?.setBasemapOpacity(state.basemapOpacity);
       controller.current?.highlightFeature(

packages/map/src/layer-sync.ts

@@ -14,6 +14,7 @@ import {
   validateMapExpression,
 } from "@geolibre/core";
 import { addProtocol, config } from "maplibre-gl";
+import type { GeoJSON } from "geojson";
 import type maplibregl from "maplibre-gl";
 import type { PropertyValueSpecification } from "maplibre-gl";
 import { FileSource, PMTiles, Protocol } from "pmtiles";
@@ -328,6 +329,18 @@ function applyExternalNativeFeatureFilters(
 // range we keep applying the style range on every sync, including a later reset
 // back to the full [0, 24] window.
 const managedZoomRangeLayerIds = new Set<string>();
+const geoJsonSourceData = new WeakMap<maplibregl.GeoJSONSource, GeoJSON>();
+
+function rememberGeoJsonData(map: maplibregl.Map, sourceId: string, data: GeoJSON): void {
+  const source = map.getSource(sourceId);
+  if (source?.type === "geojson") geoJsonSourceData.set(source as maplibregl.GeoJSONSource, data);
+}
+
+function setGeoJsonData(source: maplibregl.GeoJSONSource, data: GeoJSON): void {
+  if (geoJsonSourceData.get(source) === data) return;
+  source.setData(data);
+  geoJsonSourceData.set(source, data);
+}
 
 function clampLayerZoom(value: number, fallback: number): number {
   if (!Number.isFinite(value)) return fallback;
@@ -598,8 +611,9 @@ function ensureExternalGeoJsonNativeLayer(
       type: "geojson",
       data: layer.geojson,
     });
+    rememberGeoJsonData(map, nativeSourceId, layer.geojson);
   } else {
-    (map.getSource(nativeSourceId) as maplibregl.GeoJSONSource).setData(layer.geojson);
+    setGeoJsonData(map.getSource(nativeSourceId) as maplibregl.GeoJSONSource, layer.geojson);
   }
 
   if (nativeLayerIds.every((id) => map.getLayer(id))) return;
@@ -1438,6 +1452,10 @@ function setNativeLayerVisibility(
   visibility: "visible" | "none",
 ): void {
   try {
+    const canRead = typeof map.getLayoutProperty === "function";
+    const current = canRead ? map.getLayoutProperty(nativeLayerId, "visibility") : undefined;
+    if (current === visibility || (canRead && current === undefined && visibility === "visible"))
+      return;
     map.setLayoutProperty(nativeLayerId, "visibility", visibility);
   } catch {
     // Custom layers from external controls may not accept layout updates.
@@ -1666,7 +1684,9 @@ function syncVectorControlPointSymbology(
   // of the other rule-based paint overrides apply to control-owned layers.
   const radius = proportionalRadiusExpression(layer.style);
   if (radius) {
-    map.setPaintProperty(circleNativeId, "circle-radius", radius);
+    if (!styleValuesEqual(map.getPaintProperty?.(circleNativeId, "circle-radius"), radius)) {
+      map.setPaintProperty(circleNativeId, "circle-radius", radius);
+    }
     overriddenRadiusIdsFor(map).add(circleNativeId);
   } else {
     restoreOverriddenCircleRadius(map, circleNativeId, layer);
@@ -1721,7 +1741,9 @@ function setExternalNativeLayerPaint(
 
   for (const [property, value] of Object.entries(paint)) {
     try {
-      map.setPaintProperty(nativeLayerId, property, value);
+      if (!styleValuesEqual(map.getPaintProperty?.(nativeLayerId, property), value)) {
+        map.setPaintProperty(nativeLayerId, property, value);
+      }
     } catch {
       // External controls can create heterogeneous style layers. Ignore paint
       // properties that do not apply to a specific native layer type.
@@ -1807,8 +1829,9 @@ function syncGeoJsonLayer(map: maplibregl.Map, layer: GeoLibreLayer, beforeId?:
             ...(attribution ? { attribution } : {}),
           },
     );
+    rememberGeoJsonData(map, src, layer.geojson!);
   } else {
-    (map.getSource(src) as maplibregl.GeoJSONSource).setData(layer.geojson!);
+    setGeoJsonData(map.getSource(src) as maplibregl.GeoJSONSource, layer.geojson!);
   }
 
   applyVectorDataRenderLayers(map, layer, src, profile, renderer, beforeId);
@@ -3403,12 +3426,16 @@ function ensureLayer(
   if (map.getLayer(id)) {
     if (spec.paint) {
       for (const [key, value] of Object.entries(spec.paint)) {
-        map.setPaintProperty(id, key, value);
+        if (!styleValuesEqual(map.getPaintProperty?.(id, key), value)) {
+          map.setPaintProperty(id, key, value);
+        }
       }
     }
     if (spec.layout) {
       for (const [key, value] of Object.entries(spec.layout)) {
-        map.setLayoutProperty(id, key, value);
+        if (!styleValuesEqual(map.getLayoutProperty?.(id, key), value)) {
+          map.setLayoutProperty(id, key, value);
+        }
       }
     }
     if ("filter" in spec) {
@@ -3462,6 +3489,10 @@ function ensureLayer(
   map.addLayer(addSpec, validBeforeId);
 }
 
+export function styleValuesEqual(current: unknown, next: unknown): boolean {
+  return Object.is(current, next) || JSON.stringify(current) === JSON.stringify(next);
+}
+
 function setLayerZoomRange(
   map: maplibregl.Map,
   id: string,

packages/map/src/map-controller.ts

@@ -37,6 +37,7 @@ import {
 import {
   mbtilesStyleLayerIds,
   removeLayerFromMap,
+  styleValuesEqual,
   syncLayer,
   vectorTileStyleLayerIds,
 } from "./layer-sync";
@@ -1075,13 +1076,11 @@ export class MapController {
     const map = this.map;
 
     const nextIds = layers.map((l) => l.id);
+    const nextIdSet = new Set(nextIds);
+    const previousLayers = new Map(this.syncedLayers.map((layer) => [layer.id, layer]));
     for (const id of this.layerIds) {
-      if (!nextIds.includes(id)) {
-        removeLayerFromMap(
-          map,
-          id,
-          this.syncedLayers.find((layer) => layer.id === id),
-        );
+      if (!nextIdSet.has(id)) {
+        removeLayerFromMap(map, id, previousLayers.get(id));
       }
     }
 
@@ -1109,17 +1108,28 @@ export class MapController {
   }
 
   private styleLoadHandler: (() => void) | null = null;
+  private styleReloadHandler: (() => void) | null = null;
 
   waitAndSyncLayers(layers: GeoLibreLayer[]): void {
     if (!this.map) return;
 
+    if (!this.styleReloadHandler) {
+      this.styleReloadHandler = () => {
+        if (!this.styleLoadHandler) this.syncLayers(this.syncedLayers);
+      };
+      this.map.on("style.load", this.styleReloadHandler);
+    }
+
     if (this.styleLoadHandler) {
       this.map.off("style.load", this.styleLoadHandler);
       this.map.off("load", this.styleLoadHandler);
     }
 
     const run = () => {
       if (this.styleLoadHandler !== run) return;
+      this.map?.off("load", run);
+      this.map?.off("style.load", run);
+      this.styleLoadHandler = null;
       this.syncLayers(layers);
     };
     this.styleLoadHandler = run;
@@ -1128,17 +1138,21 @@ export class MapController {
       run();
     } else {
       this.map.once("load", run);
+      this.map.once("style.load", run);
     }
-    this.map.on("style.load", run);
   }
 
   private applyBasemapVisibility(): void {
     if (!this.isStyleReady() || !this.map) return;
     const map = this.map;
+    const visibility = this.basemapVisible ? "visible" : "none";
 
     for (const layer of this.getBasemapStyleLayers()) {
       try {
-        map.setLayoutProperty(layer.id, "visibility", this.basemapVisible ? "visible" : "none");
+        const current = map.getLayoutProperty(layer.id, "visibility");
+        if (current !== visibility && !(current === undefined && visibility === "visible")) {
+          map.setLayoutProperty(layer.id, "visibility", visibility);
+        }
       } catch {
         // Some third-party custom style layers may not expose layout properties.
       }
@@ -1194,6 +1208,8 @@ export class MapController {
           ? original * this.basemapOpacity
           : this.basemapOpacity;
     try {
+      const current = this.map.getPaintProperty(layerId, property);
+      if (styleValuesEqual(current, opacity)) return;
       this.map.setPaintProperty(layerId, property, opacity);
     } catch {
       // Some third-party custom style layers may not expose paint properties.

packages/plugins/src/plugins/maplibre-effects.ts

@@ -88,6 +88,12 @@ const STARFIELD_LNG_PERIOD_DEGREES = 360;
 const STARFIELD_LAT_PERIOD_DEGREES = 180;
 
 const HALO_SAMPLE_COUNT = 16;
+// Keep decorative canvas work from competing with MapLibre on high-refresh displays.
+const EFFECTS_FRAME_MS = 1000 / 60;
+
+export function nextEffectsFrameTime(timestamp: number, lastFrameTime: number): number | null {
+  return timestamp - lastFrameTime + 0.1 < EFFECTS_FRAME_MS ? null : timestamp;
+}
 
 // Halo radial gradient as a *shape* independent of the chosen color: each stop
 // is [offset, alpha, shade] where offset is the fraction of the gradient span
@@ -458,6 +464,7 @@ class EffectsEngine {
   private settings: EffectsSettings;
 
   private rafId: number | null = null;
+  private lastFrameTime = -Infinity;
   private destroyed = false;
 
   constructor(map: MapLibreMap, settings: EffectsSettings) {
@@ -700,18 +707,19 @@ class EffectsEngine {
     ctx.drawImage(field, wrappedX - this.width, wrappedY - this.height, this.width, this.height);
   }
 
-  private updateAndDrawComets(): void {
-    // One comet at a time, spawned with ~0.5% probability per frame.
-    if (this.comets.length === 0 && Math.random() < 0.005) {
+  private updateAndDrawComets(frameScale: number): void {
+    // Preserve the original ~0.5% chance per 60 Hz frame when frames are skipped.
+    const spawnChance = 1 - Math.pow(1 - 0.005, frameScale);
+    if (this.comets.length === 0 && Math.random() < spawnChance) {
       this.comets.push(this.spawnComet());
     }
 
     const ctx = this.cometCtx;
     const survivors: Comet[] = [];
     for (const comet of this.comets) {
-      comet.life += 1;
-      comet.x += Math.cos(comet.angle) * comet.speed;
-      comet.y += Math.sin(comet.angle) * comet.speed;
+      comet.life += frameScale;
+      comet.x += Math.cos(comet.angle) * comet.speed * frameScale;
+      comet.y += Math.sin(comet.angle) * comet.speed * frameScale;
       comet.alpha = 1 - comet.life / comet.maxLife;
 
       const offscreen =
@@ -803,10 +811,20 @@ class EffectsEngine {
     ctx.restore();
   }
 
-  private tick(): void {
+  private tick(timestamp: number): void {
     this.rafId = null;
     if (this.destroyed) return;
 
+    const nextFrameTime = nextEffectsFrameTime(timestamp, this.lastFrameTime);
+    if (nextFrameTime === null) {
+      this.start();
+      return;
+    }
+    const elapsed = Number.isFinite(this.lastFrameTime)
+      ? Math.min(nextFrameTime - this.lastFrameTime, EFFECTS_FRAME_MS * 2)
+      : EFFECTS_FRAME_MS;
+    this.lastFrameTime = nextFrameTime;
+
     this.clear();
 
     if (!isGlobeProjection(this.map)) {
@@ -821,7 +839,7 @@ class EffectsEngine {
       this.drawStarfield();
       this.starsDirty = false;
     }
-    this.updateAndDrawComets();
+    this.updateAndDrawComets(elapsed / EFFECTS_FRAME_MS);
     // The atmospheric halo is Earth-only — other celestial bodies (Moon, Mars,
     // Pluto, …) are airless or don't share Earth's blue glow, so we keep the
     // space backdrop, starfield, and comets but skip the halo for them.

tests/effects-settings.test.ts

@@ -6,6 +6,7 @@ import {
   HALO_EXTENT_MIN,
   HALO_OPACITY_MAX,
   HALO_OPACITY_MIN,
+  nextEffectsFrameTime,
   normalizeEffectsSettings,
 } from "../packages/plugins/src/plugins/maplibre-effects";
 
@@ -64,3 +65,23 @@ describe("normalizeEffectsSettings", () => {
     assert.equal(result.haloOpacity, 0.5);
   });
 });
+
+describe("nextEffectsFrameTime", () => {
+  it("keeps decorative frames one 60 FPS interval apart on high-refresh displays", () => {
+    let lastFrameTime = -Infinity;
+    const renderedAt: number[] = [];
+
+    for (let index = 0; index < 180; index += 1) {
+      const timestamp = index * (1000 / 90);
+      const nextFrameTime = nextEffectsFrameTime(timestamp, lastFrameTime);
+      if (nextFrameTime === null) continue;
+      renderedAt.push(nextFrameTime);
+      lastFrameTime = nextFrameTime;
+    }
+
+    assert.equal(renderedAt.length, 90);
+    for (let index = 1; index < renderedAt.length; index += 1) {
+      assert.ok(renderedAt[index] - renderedAt[index - 1] + 0.1 >= 1000 / 60);
+    }
+  });
+});