  In this paper we study Cuntz--Pimsner algebras associated to
$\mathrm{C}^*$-correspondences over commutative $\mathrm{C}^*$-algebras from
the point of view of the $\mathrm{C}^*$-algebra classification programme. We
show that when the correspondence comes from an aperiodic homeomorphism of a
finite-dimensional infinite compact metric space $X$ twisted by a vector
bundle, the resulting Cuntz--Pimsner algebras have finite nuclear dimension.
When the homeomorphism is minimal, this entails classification of these
$\mathrm{C}^*$-algebras by the Elliott invariant. This establishes a dichotomy:
when the vector bundle has rank one, the Cuntz--Pimsner algebra has stable rank
one. Otherwise, it is purely infinite.
  For a Cuntz--Pimsner algebra of a minimal homeomorphism of an infinite
compact metric space $X$ twisted by a line bundle over $X$, we introduce
orbit-breaking subalgebras. With no assumptions on the dimension of $X$, we
show that they are centrally large subalgebras and hence simple and stably
finite. When the dimension of $X$ is finite, they are furthermore
$\mathcal{Z}$-stable and hence classified by the Elliott invariant.
