feat(file-provider): add save state & screenshot enumeration

Adds Save States and Screenshots as browsable top-level categories in
the ROM File Provider extension.  Each game with saves or screenshots
gets a named sub-folder; files can be copied out or deleted from
Files.app via the file provider.

Changes:
- RomFileProviderRootCategory: add .saveStates and .screenshots cases
- RomFileProviderVirtualPath: add save-state / screenshot identifier
  helpers (ss-game:, ss:, sc-game:, sc:) with encode/parse round-trip
- FileProviderItem: new Kind cases + inits for saveStateGameFolder,
  saveStateFile, screenshotGameFolder, screenshotFile
- RomFileProviderCPDI: SaveStateEntry / ScreenshotEntry structs and
  loaders (loadAllSaveStateEntries, loadAllScreenshotEntries,
  saveStateGameFolders, screenshotGameFolders)
- FileProviderEnumerator: route ss-game: and sc-game: prefixes;
  enumerate save state / screenshot items with paging
- FileProviderExtension: fetchContents, deleteItem, and resolveItem
  support for save state and screenshot items; modifyItem guard
- Tests: round-trip tests for new identifier helpers

Part of #3595
Closes #3617

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: github-actions[bot]

.changelog/3617.md

@@ -0,0 +1,2 @@
+### Added
+- **File Provider Save States & Screenshots** — Provenance now exposes Save States and Screenshots as browsable top-level folders in Files.app; each game with saves/screenshots gets a named sub-folder, and files can be copied out or deleted from Files.app.

Extensions/ROM File Provider/FileProviderEnumerator.swift

@@ -27,6 +27,8 @@ final class FileProviderEnumerator: NSObject, NSFileProviderEnumerator {
     private var cachedLocalSystemIDs: Set<String>?
     private var cachedCanonicalGames: [(game: Game, url: URL)]?
     private var cachedLocalRows: [RomFileProviderLibrary.LocalEntry]?
+    private var cachedSaveStateEntries: [RomFileProviderLibrary.SaveStateEntry]?
+    private var cachedScreenshotEntries: [RomFileProviderLibrary.ScreenshotEntry]?
 
     init(enumeratedItemIdentifier: NSFileProviderItemIdentifier) {
         self.enumeratedItemIdentifier = enumeratedItemIdentifier
@@ -88,6 +90,20 @@ final class FileProviderEnumerator: NSObject, NSFileProviderEnumerator {
         return rows
     }
 
+    private func loadSaveStateEntriesIfNeeded() -> [RomFileProviderLibrary.SaveStateEntry] {
+        if let cached = cachedSaveStateEntries { return cached }
+        let entries = RomFileProviderLibrary.loadAllSaveStateEntries()
+        cachedSaveStateEntries = entries
+        return entries
+    }
+
+    private func loadScreenshotEntriesIfNeeded() -> [RomFileProviderLibrary.ScreenshotEntry] {
+        if let cached = cachedScreenshotEntries { return cached }
+        let entries = RomFileProviderLibrary.loadAllScreenshotEntries()
+        cachedScreenshotEntries = entries
+        return entries
+    }
+
     // MARK: - buildItems
 
     private func buildItems(offset: Int, limit: Int) throws -> ([FileProviderItem], Int) {
@@ -156,6 +172,17 @@ final class FileProviderEnumerator: NSObject, NSFileProviderEnumerator {
             return try buildSymlinkGameItems(rows: filtered, parentRaw: raw, parentIdentifier: enumeratedItemIdentifier, offset: offset, limit: limit)
         }
 
+        if let md5 = RomFileProviderVirtualPath.parseSaveStateGameMD5(from: raw) {
+            let entries = loadSaveStateEntriesIfNeeded().filter { $0.game.md5.uppercased() == md5 }
+                .sorted { $0.date > $1.date }
+            return buildSaveStateItems(entries: entries, parentIdentifier: enumeratedItemIdentifier, offset: offset, limit: limit)
+        }
+
+        if let md5 = RomFileProviderVirtualPath.parseScreenshotGameMD5(from: raw) {
+            let entries = loadScreenshotEntriesIfNeeded().filter { $0.gameMD5.uppercased() == md5 }
+            return buildScreenshotItems(entries: entries, parentIdentifier: enumeratedItemIdentifier, offset: offset, limit: limit)
+        }
+
         throw NSFileProviderError(.noSuchItem)
     }
 
@@ -166,7 +193,7 @@ final class FileProviderEnumerator: NSObject, NSFileProviderEnumerator {
         return (Array(items[offset..<end]), total)
     }
 
-    private func buildCategoryContents(cat: RomFileProviderRootCategory, offset: Int, limit: Int) throws -> ([FileProviderItem], Int) {
+    private func buildCategoryContents(cat: RomFileProviderRootCategory, offset: Int, limit: Int) throws -> ([FileProviderItem], Int) { // swiftlint:disable:this cyclomatic_complexity
         switch cat {
         case .systems:
             return buildSystemFolderItems(offset: offset, limit: limit)
@@ -227,6 +254,16 @@ final class FileProviderEnumerator: NSObject, NSFileProviderEnumerator {
                 )
             }
             return pageSlice(items: items, offset: offset, limit: limit)
+        case .saveStates:
+            let parent = NSFileProviderItemIdentifier(cat.rawIdentifier)
+            let games = RomFileProviderLibrary.saveStateGameFolders()
+            let folders = games.map { FileProviderItem(saveStateGameFolder: $0, parentItemIdentifier: parent) }
+            return pageSlice(items: folders, offset: offset, limit: limit)
+        case .screenshots:
+            let parent = NSFileProviderItemIdentifier(cat.rawIdentifier)
+            let games = RomFileProviderLibrary.screenshotGameFolders()
+            let folders = games.map { FileProviderItem(screenshotGameFolder: $0, parentItemIdentifier: parent) }
+            return pageSlice(items: folders, offset: offset, limit: limit)
         }
     }
 
@@ -296,6 +333,49 @@ final class FileProviderEnumerator: NSObject, NSFileProviderEnumerator {
         return pageSlice(items: children, offset: offset, limit: limit)
     }
 
+    private func buildSaveStateItems(
+        entries: [RomFileProviderLibrary.SaveStateEntry],
+        parentIdentifier: NSFileProviderItemIdentifier,
+        offset: Int,
+        limit: Int
+    ) -> ([FileProviderItem], Int) {
+        let total = entries.count
+        guard offset < total else { return ([], total) }
+        let slice = entries[offset..<min(offset + limit, total)]
+        let items = slice.map { entry -> FileProviderItem in
+            FileProviderItem(
+                saveStateID: entry.id,
+                game: entry.game,
+                date: entry.date,
+                isAutosave: entry.isAutosave,
+                userDescription: entry.userDescription,
+                fileURL: entry.fileURL,
+                parentItemIdentifier: parentIdentifier
+            )
+        }
+        return (Array(items), total)
+    }
+
+    private func buildScreenshotItems(
+        entries: [RomFileProviderLibrary.ScreenshotEntry],
+        parentIdentifier: NSFileProviderItemIdentifier,
+        offset: Int,
+        limit: Int
+    ) -> ([FileProviderItem], Int) {
+        let total = entries.count
+        guard offset < total else { return ([], total) }
+        let slice = entries[offset..<min(offset + limit, total)]
+        let items = slice.map { entry -> FileProviderItem in
+            FileProviderItem(
+                screenshotGameMD5: entry.gameMD5,
+                index: entry.index,
+                imageURL: entry.imageURL,
+                parentItemIdentifier: parentIdentifier
+            )
+        }
+        return (Array(items), total)
+    }
+
     private func buildSymlinkGameItems(
         rows: [RomFileProviderLibrary.LocalEntry],
         parentRaw: String,

Extensions/ROM File Provider/FileProviderExtension.swift

@@ -92,7 +92,69 @@ final class FileProviderExtension: NSObject, NSFileProviderReplicatedExtension {
         request: NSFileProviderRequest,
         completionHandler: @escaping (URL?, NSFileProviderItem?, Error?) -> Void
     ) -> Progress {
-        guard let md5 = canonicalGameMD5(from: itemIdentifier.rawValue) else {
+        let raw = itemIdentifier.rawValue
+
+        // Save state file
+        if let ssID = RomFileProviderVirtualPath.parseSaveStateID(from: raw) {
+            let realm = RomFileProviderLibrary.realm
+            guard let pvSS = realm.object(ofType: PVSaveState.self, forPrimaryKey: ssID),
+                  !pvSS.isInvalidated,
+                  let pvGame = pvSS.game, !pvGame.isInvalidated,
+                  let pvFile = pvSS.file, let fileURL = pvFile.url,
+                  FileManager.default.fileExists(atPath: fileURL.path) else {
+                completionHandler(nil, nil, NSFileProviderError(.noSuchItem))
+                return Progress()
+            }
+            let md5 = pvGame.md5Hash
+            let parent = NSFileProviderItemIdentifier(RomFileProviderVirtualPath.saveStateGameFolderIdentifier(gameMD5: md5))
+            let item = FileProviderItem(
+                saveStateID: ssID,
+                game: pvGame.asDomain(),
+                date: pvSS.date,
+                isAutosave: pvSS.isAutosave,
+                userDescription: pvSS.userDescription,
+                fileURL: fileURL,
+                parentItemIdentifier: parent
+            )
+            ILOG("FileProvider: serving save state \(fileURL.lastPathComponent) for \(pvGame.title)")
+            completionHandler(fileURL, item, nil)
+            return Progress()
+        }
+
+        // Screenshot file
+        if let parsed = RomFileProviderVirtualPath.parseScreenshotID(from: raw) {
+            let realm = RomFileProviderLibrary.realm
+            guard let pvGame = realm.object(ofType: PVGame.self, forPrimaryKey: parsed.gameMD5),
+                  !pvGame.isInvalidated else {
+                completionHandler(nil, nil, NSFileProviderError(.noSuchItem))
+                return Progress()
+            }
+            let shots = Array(pvGame.screenShots)
+            guard parsed.index < shots.count else {
+                completionHandler(nil, nil, NSFileProviderError(.noSuchItem))
+                return Progress()
+            }
+            let pvImageFile = shots[parsed.index]
+            guard !pvImageFile.isInvalidated,
+                  let imageURL = pvImageFile.url,
+                  FileManager.default.fileExists(atPath: imageURL.path) else {
+                completionHandler(nil, nil, NSFileProviderError(.noSuchItem))
+                return Progress()
+            }
+            let parent = NSFileProviderItemIdentifier(RomFileProviderVirtualPath.screenshotGameFolderIdentifier(gameMD5: parsed.gameMD5))
+            let item = FileProviderItem(
+                screenshotGameMD5: parsed.gameMD5,
+                index: parsed.index,
+                imageURL: imageURL,
+                parentItemIdentifier: parent
+            )
+            ILOG("FileProvider: serving screenshot \(imageURL.lastPathComponent) for \(pvGame.title)")
+            completionHandler(imageURL, item, nil)
+            return Progress()
+        }
+
+        // ROM file
+        guard let md5 = canonicalGameMD5(from: raw) else {
             completionHandler(nil, nil, NSFileProviderError(.noSuchItem))
             return Progress()
         }
@@ -173,7 +235,16 @@ final class FileProviderExtension: NSObject, NSFileProviderReplicatedExtension {
         request: NSFileProviderRequest,
         completionHandler: @escaping (NSFileProviderItem?, NSFileProviderItemFields, Bool, Error?) -> Void
     ) -> Progress {
-        guard let md5 = canonicalGameMD5(from: item.itemIdentifier.rawValue) else {
+        let raw = item.itemIdentifier.rawValue
+
+        // Save states and screenshots are read-only (no renames or content edits)
+        if RomFileProviderVirtualPath.parseSaveStateID(from: raw) != nil
+            || RomFileProviderVirtualPath.parseScreenshotID(from: raw) != nil {
+            completionHandler(nil, [], false, CocoaError(.featureUnsupported))
+            return Progress()
+        }
+
+        guard let md5 = canonicalGameMD5(from: raw) else {
             completionHandler(nil, [], false, CocoaError(.featureUnsupported))
             return Progress()
         }
@@ -245,7 +316,73 @@ final class FileProviderExtension: NSObject, NSFileProviderReplicatedExtension {
         request: NSFileProviderRequest,
         completionHandler: @escaping (Error?) -> Void
     ) -> Progress {
-        guard let md5 = canonicalGameMD5(from: identifier.rawValue) else {
+        let raw = identifier.rawValue
+
+        // Delete save state
+        if let ssID = RomFileProviderVirtualPath.parseSaveStateID(from: raw) {
+            do {
+                let realm = RomFileProviderLibrary.realm
+                guard let pvSS = realm.object(ofType: PVSaveState.self, forPrimaryKey: ssID),
+                      !pvSS.isInvalidated else {
+                    completionHandler(nil)
+                    return Progress()
+                }
+                if let pvFile = pvSS.file, let fileURL = pvFile.url,
+                   FileManager.default.fileExists(atPath: fileURL.path) {
+                    try FileManager.default.removeItem(at: fileURL)
+                    ILOG("FileProvider: deleted save state file \(fileURL.lastPathComponent)")
+                }
+                let imageToDelete = pvSS.image
+                try realm.write {
+                    if let img = imageToDelete { realm.delete(img) }
+                    if let f = pvSS.file { realm.delete(f) }
+                    realm.delete(pvSS)
+                }
+                completionHandler(nil)
+            } catch {
+                ELOG("FileProvider: deleteItem (save state) error — \(error)")
+                completionHandler(error)
+            }
+            return Progress()
+        }
+
+        // Delete screenshot
+        if let parsed = RomFileProviderVirtualPath.parseScreenshotID(from: raw) {
+            do {
+                let realm = RomFileProviderLibrary.realm
+                guard let pvGame = realm.object(ofType: PVGame.self, forPrimaryKey: parsed.gameMD5),
+                      !pvGame.isInvalidated else {
+                    completionHandler(nil)
+                    return Progress()
+                }
+                let shots = Array(pvGame.screenShots)
+                guard parsed.index < shots.count else {
+                    completionHandler(nil)
+                    return Progress()
+                }
+                let pvImageFile = shots[parsed.index]
+                guard !pvImageFile.isInvalidated else {
+                    completionHandler(nil)
+                    return Progress()
+                }
+                if let imageURL = pvImageFile.url,
+                   FileManager.default.fileExists(atPath: imageURL.path) {
+                    try FileManager.default.removeItem(at: imageURL)
+                    ILOG("FileProvider: deleted screenshot \(imageURL.lastPathComponent)")
+                }
+                try realm.write {
+                    realm.delete(pvImageFile)
+                }
+                completionHandler(nil)
+            } catch {
+                ELOG("FileProvider: deleteItem (screenshot) error — \(error)")
+                completionHandler(error)
+            }
+            return Progress()
+        }
+
+        // Delete ROM game
+        guard let md5 = canonicalGameMD5(from: raw) else {
             completionHandler(CocoaError(.featureUnsupported))
             return Progress()
         }
@@ -486,6 +623,22 @@ final class FileProviderExtension: NSObject, NSFileProviderReplicatedExtension {
             return FileProviderItem(ratingFolderKey: key, title: title, parentItemIdentifier: parent)
         }
 
+        if let md5 = RomFileProviderVirtualPath.parseSaveStateGameMD5(from: raw) {
+            return resolveSaveStateGameFolder(md5: md5)
+        }
+
+        if let ssID = RomFileProviderVirtualPath.parseSaveStateID(from: raw) {
+            return resolveSaveStateItem(id: ssID)
+        }
+
+        if let md5 = RomFileProviderVirtualPath.parseScreenshotGameMD5(from: raw) {
+            return resolveScreenshotGameFolder(md5: md5)
+        }
+
+        if let parsed = RomFileProviderVirtualPath.parseScreenshotID(from: raw) {
+            return resolveScreenshotItem(gameMD5: parsed.gameMD5, index: parsed.index)
+        }
+
         return nil
     }
 
@@ -531,6 +684,60 @@ final class FileProviderExtension: NSObject, NSFileProviderReplicatedExtension {
         return FileProviderItem(publisherFolderGroupingKey: groupingKey, title: title, parentItemIdentifier: parent)
     }
 
+    private func resolveSaveStateGameFolder(md5: String) -> FileProviderItem? {
+        let realm = RomFileProviderLibrary.realm
+        guard let pvGame = realm.object(ofType: PVGame.self, forPrimaryKey: md5),
+              !pvGame.isInvalidated else { return nil }
+        let parent = NSFileProviderItemIdentifier(RomFileProviderRootCategory.saveStates.rawIdentifier)
+        return FileProviderItem(saveStateGameFolder: pvGame.asDomain(), parentItemIdentifier: parent)
+    }
+
+    private func resolveSaveStateItem(id: String) -> FileProviderItem? {
+        let realm = RomFileProviderLibrary.realm
+        guard let pvSS = realm.object(ofType: PVSaveState.self, forPrimaryKey: id),
+              !pvSS.isInvalidated,
+              let pvGame = pvSS.game, !pvGame.isInvalidated else { return nil }
+        let fileURL: URL?
+        if let pvFile = pvSS.file, let url = pvFile.url,
+           FileManager.default.fileExists(atPath: url.path) {
+            fileURL = url
+        } else {
+            fileURL = nil
+        }
+        let md5 = pvGame.md5Hash
+        let parent = NSFileProviderItemIdentifier(RomFileProviderVirtualPath.saveStateGameFolderIdentifier(gameMD5: md5))
+        return FileProviderItem(
+            saveStateID: id,
+            game: pvGame.asDomain(),
+            date: pvSS.date,
+            isAutosave: pvSS.isAutosave,
+            userDescription: pvSS.userDescription,
+            fileURL: fileURL,
+            parentItemIdentifier: parent
+        )
+    }
+
+    private func resolveScreenshotGameFolder(md5: String) -> FileProviderItem? {
+        let realm = RomFileProviderLibrary.realm
+        guard let pvGame = realm.object(ofType: PVGame.self, forPrimaryKey: md5),
+              !pvGame.isInvalidated else { return nil }
+        let parent = NSFileProviderItemIdentifier(RomFileProviderRootCategory.screenshots.rawIdentifier)
+        return FileProviderItem(screenshotGameFolder: pvGame.asDomain(), parentItemIdentifier: parent)
+    }
+
+    private func resolveScreenshotItem(gameMD5: String, index: Int) -> FileProviderItem? {
+        let realm = RomFileProviderLibrary.realm
+        guard let pvGame = realm.object(ofType: PVGame.self, forPrimaryKey: gameMD5),
+              !pvGame.isInvalidated else { return nil }
+        let shots = Array(pvGame.screenShots)
+        guard index < shots.count else { return nil }
+        let pvImageFile = shots[index]
+        guard !pvImageFile.isInvalidated else { return nil }
+        let imageURL = pvImageFile.url.flatMap { FileManager.default.fileExists(atPath: $0.path) ? $0 : nil }
+        let parent = NSFileProviderItemIdentifier(RomFileProviderVirtualPath.screenshotGameFolderIdentifier(gameMD5: gameMD5))
+        return FileProviderItem(screenshotGameMD5: gameMD5, index: index, imageURL: imageURL, parentItemIdentifier: parent)
+    }
+
     private func resolvePublisherSystemFolder(raw: String) -> FileProviderItem? {
         let rest = String(raw.dropFirst(RomFileProviderVirtualPath.publisherSystemPrefix.count))
         guard let colon = rest.firstIndex(of: ":") else { return nil }