/// TRACES: NFR-R7 | NFR-R8
/// Failures from the GPU layer.
///
/// `DeviceLost` is deliberately a distinct variant rather than folded into a
/// generic error: it is an expected event on Android (ARCH §6.10), not an
/// exceptional one, and callers recover from it by rebuilding the device and
/// re-driving from the edit graph.
#[derive(Debug, thiserror::Error)]
pub enum GpuError {
    #[error("no suitable GPU adapter found")]
    NoAdapter,

    #[error("failed to request device: {0}")]
    DeviceRequest(String),

    #[error("GPU device lost — recreate and re-render from the edit graph")]
    DeviceLost,

    #[error("shader compilation failed: {0}")]
    ShaderCompilation(String),

    #[error("readback failed: {0}")]
    Readback(String),
}