Prevent brief blank map when switching clusters/pins by deferring marker refresh

[badjoke-lab]

Motivation

• Prevent a visible flicker to an empty map that happens when the map view changes and the old marker layer is removed before a new fetch/build completes.
• Document findings from an investigation into the blank interval during cluster↔pin switching.

Description

• Introduce isFetchScheduledRef to track when a fetch is scheduled and use it together with isFetchingMarkersRef to avoid replacing a non-empty marker layer with an empty one prematurely in renderClusters.
• Set and clear isFetchScheduledRef in scheduleFetchForBounds and clearFetchTimeout, and clear pendingFetchRef when the delayed fetch actually runs.
• Stop calling updateVisibleMarkers() immediately from handleMapViewChange to avoid using a stale/empty cluster result before the scheduled fetch starts.
• Add investigation notes as docs/map-cluster-pin-blank-investigation.md summarizing root cause analysis and suggested remediation options.

Testing

• Ran TypeScript type check via yarn build and the build succeeded.
• Ran the repository test suite via yarn test and all tests passed.
• Ran linter via yarn lint with no new violations reported.

---

Codex Task

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cryptopaymap-v2	Ready	Preview, Comment	Mar 23, 2026 1:23pm