@reearth/core 0.0.7-alpha.66 → 0.0.7-alpha.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reearth/core",
-  "version": "0.0.7-alpha.66",
+  "version": "0.0.7-alpha.68",
   "author": "Re:Earth contributors <community@reearth.io>",
   "license": "Apache-2.0",
   "description": "A library that abstracts a map engine as one common API.",

package/src/engines/Cesium/core/Imagery.test.ts

@@ -1,10 +1,44 @@
 import { renderHook } from "@testing-library/react";
 import { UrlTemplateImageryProvider } from "cesium";
-import { expect, test, vi } from "vitest";
+import { expect, test, vi, beforeEach } from "vitest";
 
 import type { CustomProviderConfig } from "../../../Map/types/customProvider";
 
-import { type Tile, useImageryProviders } from "./Imagery";
+import ImageryLayers, { type Tile, useImageryProviders } from "./Imagery";
+
+// Mock Cesium scene and imageryLayerCollection for ImageryLayers component tests
+const mockAdd = vi.fn();
+const mockRemove = vi.fn();
+const mockContains = vi.fn(() => true);
+const mockIndexOf = vi.fn(() => 0);
+const mockRequestRender = vi.fn();
+
+const mockImageryLayerCollection = {
+  add: mockAdd,
+  remove: mockRemove,
+  contains: mockContains,
+  indexOf: mockIndexOf,
+};
+
+const mockScene = {
+  requestRender: mockRequestRender,
+  isDestroyed: () => false,
+};
+
+vi.mock("resium", () => ({
+  useCesium: () => ({
+    imageryLayerCollection: mockImageryLayerCollection,
+    scene: mockScene,
+  }),
+}));
+
+beforeEach(() => {
+  mockAdd.mockClear();
+  mockRemove.mockClear();
+  mockContains.mockClear();
+  mockIndexOf.mockClear();
+  mockRequestRender.mockClear();
+});
 
 test("useImageryProviders", () => {
   const provider = vi.fn(({ url }: { url?: string } = {}): any => ({ hoge: url }));
@@ -153,3 +187,173 @@ test("useImageryProviders", () => {
   typedRerender({ tiles: [] });
   expect(result.current.providers).toEqual({});
 });
+
+test("ImageryLayers should not re-render when tiles array reference changes but content is the same", async () => {
+  const tiles: Tile[] = [{ id: "1", type: "open_street_map", opacity: 0.8 }];
+
+  const { rerender } = renderHook(
+    ({ tiles }: { tiles: Tile[] }) => {
+      return ImageryLayers({
+        tiles,
+        cesiumIonAccessToken: undefined,
+        customProvider: undefined,
+        onTilesChange: undefined,
+      });
+    },
+    {
+      initialProps: { tiles },
+    },
+  );
+
+  // Wait for initial render to complete
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  // Clear mock calls from initial render
+  mockAdd.mockClear();
+  mockRemove.mockClear();
+
+  // Re-render with a NEW tiles array reference but SAME content
+  const newTilesArraySameContent: Tile[] = [{ id: "1", type: "open_street_map", opacity: 0.8 }];
+
+  rerender({ tiles: newTilesArraySameContent });
+
+  // Wait for any effects to run
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  // Effect should NOT have run again - no layers should be removed or added
+  expect(mockRemove).not.toHaveBeenCalled();
+  expect(mockAdd).not.toHaveBeenCalled();
+
+  // Clear mocks
+  mockAdd.mockClear();
+  mockRemove.mockClear();
+
+  // Re-render with ONLY opacity changed
+  const opacityChangedTiles: Tile[] = [
+    { id: "1", type: "open_street_map", opacity: 0.5 }, // only opacity changed
+  ];
+
+  rerender({ tiles: opacityChangedTiles });
+
+  // Wait for effects to run
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  // With our optimization, when ONLY opacity changes, the layer is NOT recreated
+  // The layer.alpha property is updated directly without removing/adding the layer
+  expect(mockRemove).not.toHaveBeenCalled();
+  expect(mockAdd).not.toHaveBeenCalled();
+
+  // Clear mocks
+  mockAdd.mockClear();
+  mockRemove.mockClear();
+
+  // Re-render with DIFFERENT tile type (requires layer recreation)
+  const differentTypeTiles: Tile[] = [
+    { id: "1", type: "stamen_watercolor", opacity: 0.5 }, // type changed
+  ];
+
+  rerender({ tiles: differentTypeTiles });
+
+  // Wait for effects to run
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  // When provider changes (type, url, etc.), layer IS recreated
+  expect(mockRemove).toHaveBeenCalled();
+  expect(mockAdd).toHaveBeenCalled();
+});
+
+test("ImageryLayers should optimize opacity changes without recreating layers", async () => {
+  const tiles: Tile[] = [{ id: "1", type: "open_street_map", opacity: 1.0 }];
+
+  const { rerender } = renderHook(
+    ({ tiles }: { tiles: Tile[] }) => {
+      return ImageryLayers({
+        tiles,
+        cesiumIonAccessToken: undefined,
+        customProvider: undefined,
+        onTilesChange: undefined,
+      });
+    },
+    {
+      initialProps: { tiles },
+    },
+  );
+
+  // Wait for initial render
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  // Clear initial render calls
+  mockAdd.mockClear();
+  mockRemove.mockClear();
+
+  // Change opacity multiple times
+  for (const opacity of [0.8, 0.6, 0.4, 0.2]) {
+    rerender({ tiles: [{ id: "1", type: "open_street_map", opacity }] });
+    await new Promise(resolve => setTimeout(resolve, 0));
+  }
+
+  // After multiple opacity changes, layers should NEVER be removed/added
+  // The optimization updates layer.alpha directly
+  expect(mockRemove).not.toHaveBeenCalled();
+  expect(mockAdd).not.toHaveBeenCalled();
+});
+
+test("ImageryLayers should recreate layer when customProvider changes even if tile properties are same", async () => {
+  // Use a custom provider that we can change
+  const tiles: Tile[] = [{ id: "1", type: "my_custom", opacity: 0.8 }];
+
+  const customProvider1: CustomProviderConfig = {
+    imagery: {
+      providers: [
+        {
+          id: "my_custom",
+          url: "https://tiles1.example.com/{z}/{x}/{y}.png",
+          credit: "© Example 1",
+        },
+      ],
+    },
+  };
+
+  const customProvider2: CustomProviderConfig = {
+    imagery: {
+      providers: [
+        {
+          id: "my_custom",
+          url: "https://tiles2.example.com/{z}/{x}/{y}.png", // Different URL
+          credit: "© Example 2",
+        },
+      ],
+    },
+  };
+
+  const { rerender } = renderHook(
+    ({ tiles, customProvider }: { tiles: Tile[]; customProvider?: CustomProviderConfig }) => {
+      return ImageryLayers({
+        tiles,
+        cesiumIonAccessToken: undefined,
+        customProvider,
+        onTilesChange: undefined,
+      });
+    },
+    {
+      initialProps: { tiles, customProvider: customProvider1 },
+    },
+  );
+
+  // Wait for initial render
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  // Clear initial render calls
+  mockAdd.mockClear();
+  mockRemove.mockClear();
+
+  // Change the customProvider (this creates a new provider with different URL)
+  // Tile properties stay the same
+  rerender({ tiles, customProvider: customProvider2 });
+  await new Promise(resolve => setTimeout(resolve, 0));
+
+  // Layer SHOULD be recreated because the provider changed
+  // (even though tile properties didn't change)
+  expect(mockRemove).toHaveBeenCalled();
+  expect(mockAdd).toHaveBeenCalled();
+});

package/src/engines/Cesium/core/Imagery.tsx

@@ -53,20 +53,60 @@ export default function ImageryLayers({
 }: Props) {
   const { imageryLayerCollection, scene } = useCesium();
 
+  // Create a stable tiles reference that only changes when the content actually changes
+  // Normalize `undefined` to a stable empty array so `useImageryProviders` doesn't allocate a new default `[]` each render.
+  const emptyTiles = useMemo<Tile[]>(() => [], []);
+  const tilesValue = tiles ?? emptyTiles;
+
+  const prevTilesRef = useRef<Tile[]>(tilesValue);
+  const stableTiles = useMemo(() => {
+    if (!isEqual(prevTilesRef.current, tilesValue)) {
+      prevTilesRef.current = tilesValue;
+    }
+    return prevTilesRef.current;
+  }, [tilesValue]);
+
+  // Pass stableTiles to useImageryProviders to prevent providers from being recreated
+  // when tiles reference changes but content is the same
   const { providers } = useImageryProviders({
-    tiles,
+    tiles: stableTiles,
     cesiumIonAccessToken,
     customProvider,
     presets: tilePresets,
   });
 
+  // Store layers keyed by tile ID to allow incremental updates
+  const layersRef = useRef<
+    Map<
+      string,
+      {
+        layer: CesiumImageryLayer;
+        tile: Tile;
+        provider: Promise<ImageryProvider> | ImageryProvider;
+      }
+    >
+  >(new Map());
+
   useEffect(() => {
     if (!imageryLayerCollection || !scene) return;
 
     let cancelled = false;
-    const addedLayers: CesiumImageryLayer[] = [];
+    const currentTileIds = new Set(stableTiles?.map(t => t.id) || []);
+
+    // Remove layers for tiles that no longer exist
+    layersRef.current.forEach(({ layer }, id) => {
+      if (!currentTileIds.has(id)) {
+        if (imageryLayerCollection.contains(layer)) {
+          imageryLayerCollection.remove(layer);
+        }
+        layersRef.current.delete(id);
+      }
+    });
+
     // Track layers by their intended index to maintain order with async loading
-    const layersByIndex: (CesiumImageryLayer | null)[] = new Array(tiles?.length || 0).fill(null);
+    const layersByIndex: (CesiumImageryLayer | null)[] = new Array(stableTiles?.length || 0).fill(
+      null,
+    );
 
     const reorderLayers = () => {
       if (cancelled || scene.isDestroyed()) return;
@@ -91,10 +131,50 @@ export default function ImageryLayers({
       scene.requestRender();
     };
 
-    tiles?.forEach(({ id, zoomLevel, opacity, heatmap }, i) => {
+    stableTiles?.forEach((tile, i) => {
+      const { id, zoomLevel, opacity, heatmap } = tile;
+      const existing = layersRef.current.get(id);
       const providerOrPromise = providers[id]?.[3];
+
       if (!providerOrPromise) return;
 
+      // Check if we can reuse the existing layer with just an opacity update
+      if (existing) {
+        const prevTile = existing.tile;
+        const prevProvider = existing.provider;
+        // Must check provider reference - if provider changed (e.g. cesiumIonAccessToken updated),
+        // the layer needs to be recreated even if tile properties are the same
+        const canReuseLayer =
+          prevProvider === providerOrPromise &&
+          prevTile.type === tile.type &&
+          prevTile.url === tile.url &&
+          prevTile.cesiumIonAssetId === tile.cesiumIonAssetId &&
+          prevTile.zoomLevel?.[0] === zoomLevel?.[0] &&
+          prevTile.zoomLevel?.[1] === zoomLevel?.[1] &&
+          prevTile.heatmap === heatmap;
+
+        if (canReuseLayer) {
+          // Only opacity might have changed - update it directly if needed
+          const nextAlpha = opacity ?? 1;
+          if (existing.layer.alpha !== nextAlpha) {
+            existing.layer.alpha = nextAlpha;
+            scene.requestRender();
+          }
+          // Update stored tile and provider for next comparison
+          existing.tile = tile;
+          existing.provider = providerOrPromise;
+          layersByIndex[i] = existing.layer;
+          reorderLayers();
+          return;
+        }
+
+        // Need to recreate the layer - remove the old one
+        if (imageryLayerCollection.contains(existing.layer)) {
+          imageryLayerCollection.remove(existing.layer);
+        }
+        layersRef.current.delete(id);
+      }
+
       const doAdd = (provider: ImageryProvider) => {
         if (!provider || cancelled || scene.isDestroyed()) return;
         const layer = new CesiumImageryLayer(provider, {
@@ -110,14 +190,17 @@ export default function ImageryLayers({
         // Always append to avoid index out of bounds
         imageryLayerCollection.add(layer);
         layersByIndex[i] = layer;
-        addedLayers.push(layer);
+        // Store the provider reference to detect when provider changes (e.g. token update)
+        layersRef.current.set(id, { layer, tile, provider: providerOrPromise });
 
         // Reorder all layers after each addition
         reorderLayers();
       };
 
       if (providerOrPromise instanceof Promise) {
-        providerOrPromise.then(doAdd).catch(err => console.error("Failed to load imagery provider:", err));
+        providerOrPromise
+          .then(doAdd)
+          .catch(err => console.error("Failed to load imagery provider:", err));
       } else {
         doAdd(providerOrPromise);
       }
@@ -128,13 +211,24 @@ export default function ImageryLayers({
 
     return () => {
       cancelled = true;
-      for (const layer of addedLayers) {
-        if (!scene.isDestroyed() && imageryLayerCollection.contains(layer)) {
+      // Don't remove layers on cleanup - they'll be managed by the next render
+      // This prevents flickering when tiles change
+    };
+  }, [providers, stableTiles, imageryLayerCollection, scene, onTilesChange]);
+
+  // Cleanup all layers on unmount
+  useEffect(() => {
+    const layers = layersRef.current;
+    return () => {
+      if (!imageryLayerCollection || !scene || scene.isDestroyed()) return;
+      layers.forEach(({ layer }) => {
+        if (imageryLayerCollection.contains(layer)) {
           imageryLayerCollection.remove(layer);
         }
-      }
+      });
+      layers.clear();
     };
-  }, [providers, tiles, imageryLayerCollection, scene, onTilesChange]);
+  }, [imageryLayerCollection, scene]);
 
   return null;
 }