They could have made the transition much more straightforward by just making the permissions system more granular (i.e. let the user pick a directory instead of simply asking storage access yes/no) and leaving the existing file APIs intact otherwise, just throw a permission error if you're accessing anything outside of the granted scope.

Instead they tried to force through a completely new API that isn't compatible with anything that came beforehand, isn't compatible with code that must have a classic file handle and cannot easily be changed (native libraries, parts of the Android API itself), introduces exciting new bugs and has worse performance.

Plus at the same time they seem hellbent on hiding the true, original location of files on the file system, so a) if an app needs to ensure continuing access to a file, it needs to copy it to its own storage (Yay, dozens of copies of the same file) b) this breaks any usages and file formats that don't consist of a single, atomic, fully standalone file (HTML files, playlists, subtitles, multi-part archives, ...).