feat: support custom provider

[ZTongci]

This PR adds support for custom tile providers and fixes critical async loading issues with imagery layers.

🎯 Key Changes

1. Custom Provider System 🆕

• Added CustomProviderConfig type for vendor-agnostic tile provider configuration
• Flows through: Visualizer → Map → Cesium Engine → Feature Context → Components
• Supports custom imagery providers and 3D tileset providers
• Configured via EXAMPLE_CUSTOM_PROVIDER env var in examples

New Types:

  type CustomProviderConfig = {
    imagery?: { providers?: ImageryProviderEntry[] };
    layers?: { providers?: LayerProviderEntry[] };
  }

Files added:

• src/Map/types/customProvider.ts
• src/engines/Cesium/core/customProviderResolver.ts

2. Fixed Imagery Layer Async Loading Bug 🐛

• Problem: When providers loaded asynchronously, they could resolve out of order, causing "index out of bounds" errors
• Solution: Implemented layer tracking and dynamic reordering
  • Layers always append (safe)
  • Automatic reordering after each load to maintain correct stacking order
  • Handles tile reordering without crashes

Files changed: src/engines/Cesium/core/Imagery.tsx

3. Enhanced Tile Presets ✨

• Added explicit Cesium Ion tile types:
  • cesium_ion - Dynamic asset loading via ionAssetId field
  • cesium_ion_default, cesium_ion_labelled, cesium_ion_road, cesium_ion_earth_at_night
• Maintained backward compatibility with legacy aliases (default, default_road, etc.)

Files changed: src/engines/Cesium/core/presets.ts

4. Google Photorealistic 3D Tiles Support 🌍

• Added support for multiple providers: reearth, cesium-ion, Google API
• Custom provider URLs can override default behavior via customProvider.layers.providers
• Flexible configuration via layer data or customProvider

Files changed: src/engines/Cesium/Feature/Tileset/hooks.ts

5. Example Project Enhancements 🧹

• Added EXAMPLE_CUSTOM_PROVIDER environment variable for custom tile configuration
• Added Re:Earth Buildings test layer
• Set dev server port to 3000
• Simplified configuration loading (inlined JSON parsing)

Files changed:

• .env.example
• example/hooks.ts
• example/testLayers/reearth_buildings.ts (new)
• vite.config.example.ts

6. Terrain Configuration 🏔️

• Set Re:Earth terrain as default
• Refactored terrain provider resolution
• Removed unsupported terrain types

Files changed: src/engines/Cesium/core/Globe/useTerrainProviderPromise.ts

📊 Statistics

• 27 files changed
• 1,109 additions, 596 deletions
• Net: +513 lines

🔍 Testing

• ✅ Build passes successfully
• ✅ Example app runs on port 3000
• ✅ Custom tile providers load correctly
• ✅ Async imagery layers maintain correct order
• ✅ Backward compatibility with legacy tile type names

🔗 Related Issues

Fixes imagery layer ordering crashes when using async tile providers.

[Copilot]

Pull request overview

Adds a configurable “custom provider” mechanism for imagery + tilesets across the Visualizer → Map → Cesium engine pipeline, refactors Cesium imagery/terrain handling, and updates the example app to exercise the new configuration.

Changes:

• Introduces CustomProviderConfig (imagery + layer provider entries) and threads it through core props/context.
• Reworks Cesium imagery layer creation to avoid Resium StrictMode async cleanup issues and to maintain ordering with async provider resolution.
• Expands tileset/terrain/tile preset support (Re:Earth terrain/buildings, Google Photorealistic provider selection, Cesium Ion preset types + per-tile asset IDs) and updates the example app/env accordingly.

Reviewed changes

Copilot reviewed 26 out of 27 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
vite.config.example.ts	Sets example dev server port and adds terrain proxy for local CORS avoidance.
src/Visualizer/index.tsx	Adds customProvider prop and passes it into the Map.
src/Map/types/viewerProperty.ts	Updates terrain type union and adds cesiumIonAssetId to tile properties.
src/Map/types/index.ts	Exports CustomProviderConfig and adds it to EngineProps.
src/Map/types/customProvider.ts	Adds new provider config types for imagery/layers.
src/Map/Sketch/sketchMachine.ts	Formatting-only refactor of sketch state machine definition.
src/mantle/types/index.ts	Adds provider field to layer data and new reearth-buildings data type.
src/engines/Cesium/index.tsx	Threads customProvider into Cesium context and expands delegated data types.
src/engines/Cesium/hooks/useOverrideGlobeShader/useOverrideGlobeShader.ts	Comment formatting adjustment.
src/engines/Cesium/hooks.ts	Stops defaulting to Ion.defaultAccessToken and passes customProvider through context.
src/engines/Cesium/Feature/Tileset/hooks.ts	Adds provider selection and new tileset URL resolution logic (Re:Earth/Google/Ion/buildings).
src/engines/Cesium/Feature/index.tsx	Enables rendering for reearth-buildings.
src/engines/Cesium/Feature/context.ts	Adds customProvider into Cesium feature context.
src/engines/Cesium/core/presets.ts	Adds Cesium Ion presets and per-tile Ion asset support; keeps legacy aliases.
src/engines/Cesium/core/Imagery.tsx	Replaces Resium <ImageryLayer /> usage with manual collection management + async reorder; adds custom provider imagery resolution.
src/engines/Cesium/core/Imagery.test.ts	Updates tests for new provider shape and custom provider behavior.
src/engines/Cesium/core/Globe/useTerrainProviderPromise.ts	Refactors terrain provider selection and defaults (Re:Earth terrain); improves cache keying.
src/engines/Cesium/core/Globe/index.tsx	Minor cleanup of terrain load error handling.
src/engines/Cesium/core/customProviderResolver.ts	Adds resolver helpers for provider config (currently unused).
example/testLayers/reearth_buildings.ts	Adds a Re:Earth buildings demo layer.
example/testLayers/index.ts	Registers the new Re:Earth buildings test layer.
example/scene.ts	Sets Re:Earth terrain as the default in the example scene.
example/hooks.ts	Adds EXAMPLE_CUSTOM_PROVIDER parsing + UI state for Ion asset ID selection.
example/constants.ts	Updates tile preset list and comments for new imagery options.
example/components/OptionsPanel/index.tsx	Adds UI for selecting custom tiles and entering Ion asset IDs.
example/App.tsx	Passes customProvider and related UI props through to the Visualizer.
.env.example	Documents new env vars and how to configure custom providers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bnimit]

LGTM