refactor: optimize tile rendering: prevent unnecessary reloads and smooth opacity updates

[airslice]

Problem

While alpha branch already prevents unnecessary provider recreation with stableTiles, layers are still completely destroyed and recreated on every tile update—even when only opacity changes. This causes:

• Visual flickering during opacity animations
• Performance overhead from unnecessary layer recreation
• Potential stale providers when credentials change without tile property changes

Solutions

1. Layer Reuse with Opacity Optimization

• Store existing layers in a Map keyed by tile ID
• When tiles update, check if the layer can be reused
• If only opacity changed: update layer.alpha directly (no recreation)
• If provider/zoom/heatmap changed: recreate the layer

2. Provider Reference Comparison

• Store provider reference with each layer
• Compare prevProvider === currentProvider before reusing
• Ensures layers are recreated when provider changes (e.g., cesiumIonAccessToken or customProvider URL updates)
• Fixes bug where layers would silently use stale credentials

3. Smart Layer Lifecycle

• Layers persist across renders and are only recreated when necessary
• Separate cleanup effect ensures proper unmount cleanup
• Prevents flickering by not removing layers during normal updates

Implementation

Changes to src/engines/Cesium/core/Imagery.tsx:

• Added layersRef Map storing layers with tile and provider (lines 78-88)
• Remove layers only when tiles are deleted (lines 96-104)
• Check if layer can be reused before recreation (lines 141-168)
• Update layer.alpha directly for opacity-only changes (lines 158-161)
• Store provider reference with layer (line 193)
• Separate unmount cleanup effect (lines 219-230)

Tests added to src/engines/Cesium/core/Imagery.test.ts:

• Verifies opacity changes don't recreate layers
• Verifies layers recreated when provider changes
• Verifies multiple opacity updates remain smooth

Results

✅ Opacity changes: Instant property update, zero flicker
✅ Provider changes: Correctly detected and layers recreated
✅ Layer reuse: 0 recreations when only opacity changes, proper recreation when needed

[Copilot]

Pull request overview

Optimizes Cesium imagery tile rendering by avoiding unnecessary layer recreation. Layers are now kept in a Map keyed by tile id across renders; if only opacity changes, layer.alpha is mutated in place instead of removing/re-adding the layer. Layer removal on effect cleanup is deferred to the next render, with a dedicated unmount cleanup effect to prevent leaks. Regression tests cover the reuse and recreation paths.

Changes:

• Persist CesiumImageryLayer instances in layersRef and reuse them when tile properties (other than opacity) are unchanged, updating alpha directly on opacity-only changes.
• Replace per-effect-cleanup layer removal with id-diffed removal at the start of the next run, plus a separate unmount-only cleanup effect.
• Extend Imagery.test.ts to assert no add/remove on opacity-only updates and that provider-type changes still trigger recreation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
src/engines/Cesium/core/Imagery.tsx	Introduces layer reuse map, opacity-only fast path, and split unmount cleanup effect.
src/engines/Cesium/core/Imagery.test.ts	Updates and adds regression tests for opacity reuse and type-change recreation.

---

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

[bnimit]

LGTM!