fix(cesium): suppress Ion logo when no Ion assets are actively rendering (#155)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: ZTongci

src/Map/cesiumIonDetection.test.ts

@@ -20,28 +20,29 @@ describe("computeHasCesiumIonAsset", () => {
       expect(computeHasCesiumIonAsset({ tiles: [] })).toBe(false);
     });
 
-    test("returns true for cesium_ion tile type", () => {
+    test("returns true for cesium_ion tile type with valid assetId", () => {
       expect(
-        computeHasCesiumIonAsset({ tiles: [{ id: "", type: "cesium_ion" }] }),
+        computeHasCesiumIonAsset(
+          { tiles: [{ id: "", type: "cesium_ion", cesiumIonAssetId: 12345 }] },
+          undefined,
+          "my-token",
+        ),
       ).toBe(true);
     });
 
-    test("returns true for cesium_ion_default tile type", () => {
+    test("returns true for cesium_ion_default tile type when token present", () => {
       expect(
-        computeHasCesiumIonAsset({
-          tiles: [{ id: "", type: "cesium_ion_default" }],
-        }),
+        computeHasCesiumIonAsset(
+          { tiles: [{ id: "", type: "cesium_ion_default" }] },
+          undefined,
+          "my-token",
+        ),
       ).toBe(true);
     });
 
-    test("returns true for legacy tile types", () => {
-      for (const type of [
-        "default",
-        "default_road",
-        "default_label",
-        "black_marble",
-      ]) {
-        expect(computeHasCesiumIonAsset({ tiles: [{ id: "", type }] })).toBe(
+    test("returns true for legacy tile types when token present", () => {
+      for (const type of ["default", "default_road", "default_label", "black_marble"]) {
+        expect(computeHasCesiumIonAsset({ tiles: [{ id: "", type }] }, undefined, "my-token")).toBe(
           true,
         );
       }
@@ -65,14 +66,23 @@ describe("computeHasCesiumIonAsset", () => {
       ).toBe(true);
     });
 
-    test("returns true for cesiumion terrain type when enabled", () => {
+    test("returns true for cesiumion terrain type with ionAsset", () => {
       expect(
         computeHasCesiumIonAsset({
           terrain: { enabled: true, type: "cesiumion" },
-        }),
+          assets: { cesium: { terrain: { ionAsset: "1" } } },
+        } as any),
       ).toBe(true);
     });
 
+    test("returns false for cesiumion terrain type without ionAsset or ionUrl", () => {
+      expect(
+        computeHasCesiumIonAsset({
+          terrain: { enabled: true, type: "cesiumion" },
+        }),
+      ).toBe(false);
+    });
+
     test("returns false for cesium terrain when disabled", () => {
       expect(
         computeHasCesiumIonAsset({
@@ -111,9 +121,7 @@ describe("computeHasCesiumIonAsset", () => {
   describe("layers", () => {
     test("returns true for osm-buildings layer", () => {
       expect(
-        computeHasCesiumIonAsset(undefined, [
-          makeSimple({ type: "osm-buildings" }),
-        ] as any),
+        computeHasCesiumIonAsset(undefined, [makeSimple({ type: "osm-buildings" })] as any),
       ).toBe(true);
     });
 
@@ -135,9 +143,7 @@ describe("computeHasCesiumIonAsset", () => {
 
     test("returns false for google-photorealistic with no provider (google API path)", () => {
       expect(
-        computeHasCesiumIonAsset(undefined, [
-          makeSimple({ type: "google-photorealistic" }),
-        ] as any),
+        computeHasCesiumIonAsset(undefined, [makeSimple({ type: "google-photorealistic" })] as any),
       ).toBe(false);
     });
 
@@ -175,9 +181,7 @@ describe("computeHasCesiumIonAsset", () => {
     });
 
     test("returns false for layer with no data", () => {
-      expect(computeHasCesiumIonAsset(undefined, [makeSimple()] as any)).toBe(
-        false,
-      );
+      expect(computeHasCesiumIonAsset(undefined, [makeSimple()] as any)).toBe(false);
     });
   });
 
@@ -221,18 +225,19 @@ describe("computeHasCesiumIonAsset", () => {
 
     test("returns true when only tile uses ion", () => {
       expect(
-        computeHasCesiumIonAsset({ tiles: [{ id: "", type: "default" }] }, [
-          makeSimple({ type: "geojson" }),
-        ] as any),
+        computeHasCesiumIonAsset(
+          { tiles: [{ id: "", type: "default" }] },
+          [makeSimple({ type: "geojson" })] as any,
+          "my-token",
+        ),
       ).toBe(true);
     });
 
     test("returns true when only terrain uses ion", () => {
       expect(
-        computeHasCesiumIonAsset(
-          { terrain: { enabled: true, type: "cesium" } },
-          [makeSimple({ type: "geojson" })] as any,
-        ),
+        computeHasCesiumIonAsset({ terrain: { enabled: true, type: "cesium" } }, [
+          makeSimple({ type: "geojson" }),
+        ] as any),
       ).toBe(true);
     });
 
@@ -242,4 +247,48 @@ describe("computeHasCesiumIonAsset", () => {
       expect(computeHasCesiumIonAsset(undefined, [])).toBe(false);
     });
   });
+
+  describe("token and assetId gating", () => {
+    test("returns false for cesium_ion tile with no cesiumIonAssetId", () => {
+      expect(
+        computeHasCesiumIonAsset(
+          { tiles: [{ id: "", type: "cesium_ion" }] },
+          undefined,
+          "my-token",
+        ),
+      ).toBe(false);
+    });
+
+    test("returns false for cesium_ion tile with assetId of 0", () => {
+      expect(
+        computeHasCesiumIonAsset(
+          { tiles: [{ id: "", type: "cesium_ion", cesiumIonAssetId: 0 }] },
+          undefined,
+          "my-token",
+        ),
+      ).toBe(false);
+    });
+
+    test("returns false for cesium_ion_default when no token", () => {
+      expect(
+        computeHasCesiumIonAsset({
+          tiles: [{ id: "", type: "cesium_ion_default" }],
+        }),
+      ).toBe(false);
+    });
+
+    test("returns false for legacy tile types when no token", () => {
+      for (const type of ["default", "default_road", "default_label", "black_marble"]) {
+        expect(computeHasCesiumIonAsset({ tiles: [{ id: "", type }] })).toBe(false);
+      }
+    });
+
+    test("returns true for cesium_ion with valid assetId (token gate is at engine level)", () => {
+      expect(
+        computeHasCesiumIonAsset({
+          tiles: [{ id: "", type: "cesium_ion", cesiumIonAssetId: 2275207 }],
+        }),
+      ).toBe(true);
+    });
+  });
 });

src/Map/cesiumIonDetection.ts

@@ -14,17 +14,28 @@ function isIonUrl(url?: string | null): boolean {
   return !!url && url.includes(CESIUM_ION_URL_PATTERN);
 }
 
-function tileUsesIon(tile: TileProperty): boolean {
+function tileUsesIon(tile: TileProperty, accessToken?: string): boolean {
   if (!tile.type) return false;
-  if (tile.type.startsWith("cesium_ion")) return true;
-  if (CESIUM_ION_LEGACY_TILE_TYPES.has(tile.type)) return true;
+  if (tile.type === "cesium_ion") {
+    const id = tile.cesiumIonAssetId;
+    return !!id && !isNaN(parseInt(String(id), 10));
+  }
+  if (tile.type.startsWith("cesium_ion")) return !!accessToken;
+  if (CESIUM_ION_LEGACY_TILE_TYPES.has(tile.type)) return !!accessToken;
   return false;
 }
 
 function terrainUsesIon(property?: ViewerProperty): boolean {
   const terrain = property?.terrain;
   if (!terrain?.enabled) return false;
-  if (terrain.type === "cesium" || terrain.type === "cesiumion") return true;
+  if (terrain.type === "cesium") return true;
+  if (terrain.type === "cesiumion") {
+    // Mirrors useTerrainProviderPromise: returns EllipsoidTerrainProvider when neither is set.
+    return !!(
+      property?.assets?.cesium?.terrain?.ionAsset ||
+      isIonUrl(property?.assets?.cesium?.terrain?.ionUrl)
+    );
+  }
   if (isIonUrl(property?.assets?.cesium?.terrain?.ionUrl)) return true;
   return false;
 }
@@ -47,8 +58,12 @@ function anyLayerUsesIon(layer: Layer): boolean {
   return layerUsesIon(layer);
 }
 
-export function computeHasCesiumIonAsset(property?: ViewerProperty, layers?: Layer[]): boolean {
-  if (property?.tiles?.some(tileUsesIon)) return true;
+export function computeHasCesiumIonAsset(
+  property?: ViewerProperty,
+  layers?: Layer[],
+  accessToken?: string,
+): boolean {
+  if (property?.tiles?.some(tile => tileUsesIon(tile, accessToken))) return true;
   if (terrainUsesIon(property)) return true;
   if (layers?.some(anyLayerUsesIon)) return true;
   return false;

src/Map/index.tsx

@@ -106,10 +106,13 @@ function MapFn(
     onAPIReady,
   });
 
-  const hasCesiumIonAsset = useMemo(
-    () => computeHasCesiumIonAsset(props.property, layers),
-    [props.property, layers],
-  );
+  const hasCesiumIonAsset = useMemo(() => {
+    const token =
+      typeof props.meta?.cesiumIonAccessToken === "string" && props.meta.cesiumIonAccessToken
+        ? (props.meta.cesiumIonAccessToken as string)
+        : undefined;
+    return computeHasCesiumIonAsset(props.property, layers, token);
+  }, [props.property, layers, props.meta]);
 
   const selectedLayerIds = useMemo(
     () => ({

src/engines/Cesium/common.ts

@@ -914,24 +914,33 @@ export function getCredits(viewer: Viewer, hasCesiumIonAsset?: boolean) {
           screenCredits: { _array: { credit?: CesiumCredit }[] };
         };
         _currentCesiumCredit: CesiumCredit;
+        // _cesiumCredit is the per-instance clone that beginFrame() resets _currentCesiumCredit to
+        // each frame. addCreditToNextFrame(ionCredit) sets _currentCesiumCredit to _defaultCredit
+        // (a different object) when Ion tiles are actually rendering — see GlobeSurfaceTileProvider
+        // updateCredits(). If they are equal, no Ion tile rendered in the most-recent frame.
+        _cesiumCredit: CesiumCredit;
       })
     | undefined;
 
   if (!creditDisplay) return emptyCredites;
 
   const { lightboxCredits, screenCredits } = creditDisplay?._currentFrameCredits || {};
-  const cesiumCredits = creditDisplay._currentCesiumCredit;
+  const currentCesiumCredit = creditDisplay._currentCesiumCredit;
+  const staticCesiumCredit = creditDisplay._cesiumCredit;
+
+  // Ion tiles are truly rendering when _currentCesiumCredit !== _cesiumCredit.
+  // beginFrame() resets _currentCesiumCredit = _cesiumCredit each frame; only
+  // addCreditToNextFrame() (called for every ready+visible Ion layer) overrides it.
+  // hasCesiumIonAsset === false is a fast-path: skip the check when Ion is definitely absent.
+  const ionIsRendering =
+    hasCesiumIonAsset !== false &&
+    currentCesiumCredit !== undefined &&
+    staticCesiumCredit !== undefined &&
+    currentCesiumCredit !== staticCesiumCredit;
 
   const credits: Credits = {
     engine: {
-      // Only include Cesium-ion credit when Ion assets are actually in use.
-      // hasCesiumIonAsset === false means explicitly no Ion assets; undefined preserves existing behavior.
-      cesium:
-        hasCesiumIonAsset === false
-          ? undefined
-          : cesiumCredits?.html
-            ? { html: cesiumCredits.html }
-            : undefined,
+      cesium: ionIsRendering ? { html: currentCesiumCredit.html } : undefined,
     },
     lightbox: Array.from(lightboxCredits?._array ?? []).map(c => ({
       html: c?.credit?.html,

src/engines/Cesium/core/Globe/index.tsx

@@ -1,4 +1,4 @@
-import { type Globe as CesiumGlobeType } from "cesium";
+import { EllipsoidTerrainProvider, type Globe as CesiumGlobeType } from "cesium";
 import { useEffect, useMemo, useRef, type JSX } from "react";
 import { Globe as CesiumGlobe, type CesiumComponentRef } from "resium";
 
@@ -48,7 +48,13 @@ export default function Globe({
         }
       })
       .catch(() => {
-        // provider errors are handled by the existing useEffect below
+        // Fall back to flat terrain so stale Ion terrain doesn't persist and mislead
+        // the runtime Ion-credit check.
+        if (cancelled) return;
+        const cesiumGlobe = cesiumGlobeRef.current?.cesiumElement;
+        if (cesiumGlobe) {
+          cesiumGlobe.terrainProvider = new EllipsoidTerrainProvider();
+        }
       });
     return () => {
       cancelled = true;
@@ -68,7 +74,10 @@ export default function Globe({
         }
       })
       .catch(error => {
-        if (!isCancelled) console.warn("Terrain provider failed to load:", error);
+        if (isCancelled) return;
+        console.warn("Terrain provider failed to load:", error);
+        // Notify so the engine re-evaluates credits even when terrain fails.
+        onTerrainProviderChange?.();
       });
 
     return () => {

src/engines/Cesium/hooks.ts

@@ -143,8 +143,9 @@ export default ({
       ? meta.cesiumIonAccessToken
       : undefined;
 
-  const hasCesiumIonAssetRef = useRef(hasCesiumIonAsset);
-  hasCesiumIonAssetRef.current = hasCesiumIonAsset;
+  const effectiveHasCesiumIonAsset = hasCesiumIonAsset && !!cesiumIonAccessToken;
+  const hasCesiumIonAssetRef = useRef(effectiveHasCesiumIonAsset);
+  hasCesiumIonAssetRef.current = effectiveHasCesiumIonAsset;
 
   // expose ref
   const engineAPI = useEngineRef(ref, cesium, hasCesiumIonAssetRef);
@@ -665,9 +666,10 @@ export default ({
   onCreditsUpdateRef.current = onCreditsUpdate;
   const updateCredits = useCallback(() => {
     if (!onCreditsUpdateRef.current) return;
-    // currently we don't have a proper way to get the credits update event
-    // wait for 3 seconds to get latest credits
-    // some internal property is been used here.
+    // Wait for tiles to load/render before checking credits. Cesium's GlobeSurfaceTileProvider
+    // calls addCreditToNextFrame() each frame for ready+visible Ion layers, which sets
+    // _currentCesiumCredit !== _cesiumCredit — that comparison is the actual Ion-rendering check
+    // inside getCredits(). 3 s gives tiles enough time to reach that state.
     setTimeout(() => {
       if (!onCreditsUpdateRef.current) return;
       const viewer = cesium.current?.cesiumElement;