Implement storage architecture from ai_blueprint.md

Primary sync: replace PersistenceActor JSON file with SwiftData + CloudKit
- Add SavedCardModel (@Model class) and PersistenceController (ModelContainer
  with .automatic CloudKit, fallback to local). BackgroundPersistenceActor
  (@ModelActor) handles all DB I/O off the main thread.
- One-time migration imports user_collection.json into SwiftData and renames
  the original file to prevent re-import.
- Inject modelContainer into SwiftUI environment in IYmtgApp.

Image storage: Documents/UserContent/ subfolder (blueprint requirement)
- ImageManager.dir now targets iCloud Documents/UserContent/ (or local equiv).
- migrateImagesToUserContent() moves existing JPGs to the new subfolder on
  first launch; called during the SwiftData migration.

Firebase: demoted to optional manual backup (metadata only, no images)
- Remove all automatic CloudEngine.save/delete/batchUpdatePrices calls from
  CollectionViewModel mutations.
- Add backupAllToFirebase() for user-triggered metadata sync.
- Add isFirebaseBackupEnabled to AppConfig (default false).
- Add Cloud Backup section in Library settings with iCloud vs Firebase
  explanation and "Backup Metadata to Firebase Now" button.

Also: full modular refactor (Data/, Features/, Services/ directories) and
README updated with CloudKit setup steps and revised release checklist.

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

IYmtg_App_iOS/Features/Collection/CollectionViewModel.swift

@@ -0,0 +1,383 @@
+import SwiftUI
+import Combine
+
+enum SortOption: String, CaseIterable {
+    case dateAdded = "Date Added"
+    case valueHighLow = "Value (High-Low)"
+    case nameAZ = "Name (A-Z)"
+}
+
+// MARK: - COLLECTION VIEW MODEL
+// Owns all collection state: list management, filtering, sorting, pricing, persistence.
+// Primary sync: SwiftData + CloudKit (via PersistenceController).
+// Secondary backup: Firebase — user-triggered, metadata only, no images.
+@MainActor
+class CollectionViewModel: ObservableObject {
+    @Published var scannedList: [SavedCard] = [] {
+        didSet { recalcStats() }
+    }
+    @Published var collections: [String] = [AppConfig.Defaults.masterCollectionName]
+    @Published var boxes: [String] = [AppConfig.Defaults.unsortedBoxName]
+
+    @Published var currentCollection: String = AppConfig.Defaults.masterCollectionName {
+        didSet { librarySearchText = ""; recalcStats() }
+    }
+    @Published var currentBox: String = AppConfig.Defaults.unsortedBoxName
+    @Published var sortOption: SortOption = .dateAdded
+    @Published var librarySearchText = "" {
+        didSet { recalcStats() }
+    }
+    @Published var isConnected = true
+    @Published var selectedCurrency: CurrencyCode = AppConfig.defaultCurrency
+
+    @Published var filteredList: [SavedCard] = []
+    @Published var totalValue: Double = 0.0
+
+    // Dashboard Stats
+    @Published var portfolioValue: Double = 0.0
+    @Published var portfolioDailyChange: Double = 0.0
+    @Published var topMovers: [SavedCard] = []
+
+    @Published var isCollectionLoading = true
+    @Published var isRefreshingPrices = false
+    @Published var isBackingUpToFirebase = false
+
+    private var cancellables = Set<AnyCancellable>()
+    private var recalcTask: Task<Void, Never>?
+    private var refreshTask: Task<Void, Never>?
+    private var saveTask: Task<Void, Never>?
+
+    init() {
+        NetworkMonitor.shared.$isConnected
+            .receive(on: RunLoop.main)
+            .sink { [weak self] status in self?.isConnected = status }
+            .store(in: &cancellables)
+
+        Task { [weak self] in
+            // One-time JSON → SwiftData migration, then load
+            await PersistenceController.shared.backgroundActor.migrateFromJSONIfNeeded()
+            let loaded = await PersistenceController.shared.backgroundActor.load()
+            guard let self = self else { return }
+            self.scannedList = loaded
+            self.isCollectionLoading = false
+
+            let loadedCollections = Set(loaded.map { $0.collectionName })
+            let loadedBoxes = Set(loaded.map { $0.storageLocation })
+            self.collections = Array(loadedCollections.union([AppConfig.Defaults.masterCollectionName])).sorted()
+            self.boxes = Array(loadedBoxes.union([AppConfig.Defaults.unsortedBoxName])).sorted()
+
+            Task.detached {
+                let activeImages = Set(loaded.map { $0.imageFileName })
+                ImageManager.cleanupOrphans(activeImages: activeImages)
+            }
+            self.refreshPrices(force: false)
+        }
+    }
+
+    // MARK: - Stats & Filtering
+
+    func recalcStats() {
+        let currentColl = self.currentCollection
+        let searchText = self.librarySearchText.lowercased()
+        let sort = self.sortOption
+        let sourceList = self.scannedList
+
+        recalcTask?.cancel()
+        recalcTask = Task.detached { [weak self] in
+            let filtered = sourceList.filter { card in
+                (searchText.isEmpty ||
+                 card.name.localizedCaseInsensitiveContains(searchText) ||
+                 card.setCode.localizedCaseInsensitiveContains(searchText) ||
+                 card.collectorNumber.localizedCaseInsensitiveContains(searchText)) &&
+                (currentColl == AppConfig.Defaults.masterCollectionName || card.collectionName == currentColl)
+            }
+
+            let sorted: [SavedCard]
+            switch sort {
+            case .dateAdded: sorted = filtered.sorted { $0.dateAdded > $1.dateAdded }
+            case .valueHighLow: sorted = filtered.sorted { ($0.currentValuation ?? 0) > ($1.currentValuation ?? 0) }
+            case .nameAZ: sorted = filtered.sorted { $0.name < $1.name }
+            }
+
+            let total = filtered.reduce(0) { $0 + ($1.currentValuation ?? 0) }
+
+            let globalTotal = sourceList.reduce(0) { $0 + ($1.currentValuation ?? 0) }
+            let globalPrev = sourceList.reduce(0) { $0 + ($1.previousValuation ?? $1.currentValuation ?? 0) }
+            let dailyChange = globalTotal - globalPrev
+
+            let movers = sourceList.filter { ($0.currentValuation ?? 0) != ($0.previousValuation ?? 0) }
+                .sorted { abs(($0.currentValuation ?? 0) - ($0.previousValuation ?? 0)) > abs(($1.currentValuation ?? 0) - ($1.previousValuation ?? 0)) }
+                .prefix(5)
+
+            if Task.isCancelled { return }
+            await MainActor.run { [weak self] in
+                guard let self = self else { return }
+                self.filteredList = sorted
+                self.totalValue = total
+                self.portfolioValue = globalTotal
+                self.portfolioDailyChange = dailyChange
+                self.topMovers = Array(movers)
+            }
+        }
+    }
+
+    // MARK: - Pricing
+
+    func refreshPrices(force: Bool = false) {
+        refreshTask?.cancel()
+        self.isRefreshingPrices = true
+        let cardsSnapshot = self.scannedList
+        let currencySnapshot = self.selectedCurrency
+
+        refreshTask = Task.detached { [weak self] in
+            let (priceUpdates, metadataUpdates) = await ScryfallAPI.updateTrends(cards: cardsSnapshot, currency: currencySnapshot, force: force)
+            await MainActor.run { [weak self] in
+                guard let self = self else { return }
+                self.isRefreshingPrices = false
+                if priceUpdates.isEmpty && metadataUpdates.isEmpty { return }
+
+                var listCopy = self.scannedList
+                var changedIndices = Set<Int>()
+                var hasChanges = false
+
+                var indexMap = [UUID: Int]()
+                for (index, card) in listCopy.enumerated() { indexMap[card.id] = index }
+
+                for (id, newPrice) in priceUpdates {
+                    if let index = indexMap[id] {
+                        let oldCurrency = listCopy[index].currencyCode
+                        let oldPrice = listCopy[index].currentValuation
+
+                        if oldCurrency != currencySnapshot.rawValue {
+                            listCopy[index].previousValuation = newPrice
+                            listCopy[index].currentValuation = newPrice
+                            listCopy[index].currencyCode = currencySnapshot.rawValue
+                            changedIndices.insert(index)
+                            hasChanges = true
+                        } else if oldPrice != newPrice {
+                            listCopy[index].previousValuation = oldPrice
+                            listCopy[index].currentValuation = newPrice
+                            changedIndices.insert(index)
+                            hasChanges = true
+                        }
+                    }
+                }
+
+                for (id, meta) in metadataUpdates {
+                    if let index = indexMap[id] {
+                        if listCopy[index].rarity != meta.0 || listCopy[index].colorIdentity != meta.1 || (meta.2 && listCopy[index].isSerialized != true) {
+                            listCopy[index].rarity = meta.0
+                            listCopy[index].colorIdentity = meta.1
+                            if meta.2 { listCopy[index].isSerialized = true }
+                            changedIndices.insert(index)
+                            hasChanges = true
+                        }
+                    }
+                }
+
+                if hasChanges {
+                    self.scannedList = listCopy
+                    self.saveCollectionAsync()
+                }
+            }
+        }
+    }
+
+    // MARK: - Collection Mutations
+
+    func addCard(_ entry: SavedCard, cgImage: CGImage, uiImage: UIImage, autoScan: Bool) {
+        self.scannedList.insert(entry, at: 0)
+        self.saveCollectionAsync()
+        ReviewEngine.logScan()
+
+        var taskID = UIBackgroundTaskIdentifier.invalid
+        taskID = UIApplication.shared.beginBackgroundTask(withName: "SaveCard") {
+            UIApplication.shared.endBackgroundTask(taskID)
+            taskID = .invalid
+        }
+
+        Task.detached(priority: .userInitiated) { [weak self, taskID] in
+            defer { UIApplication.shared.endBackgroundTask(taskID) }
+            do {
+                try ImageManager.save(uiImage, name: entry.imageFileName)
+            } catch {
+                print("Warning: Image Save Failed")
+            }
+
+            guard let self = self else { return }
+
+            if entry.currentValuation == nil {
+                let currency = await MainActor.run { self.selectedCurrency }
+                let (prices, metadata) = await ScryfallAPI.updateTrends(cards: [entry], currency: currency, force: true, updateTimestamp: false)
+                if let newPrice = prices[entry.id] {
+                    await MainActor.run {
+                        guard let self = self else { return }
+                        if let idx = self.scannedList.firstIndex(where: { $0.id == entry.id }) {
+                            self.scannedList[idx].currentValuation = newPrice
+                            if let meta = metadata[entry.id] {
+                                self.scannedList[idx].rarity = meta.0
+                                self.scannedList[idx].colorIdentity = meta.1
+                                if meta.2 { self.scannedList[idx].isSerialized = true }
+                            }
+                            self.saveCollectionAsync()
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    func updateCardDetails(_ card: SavedCard) {
+        if let idx = scannedList.firstIndex(where: { $0.id == card.id }) {
+            scannedList[idx] = card
+
+            if !collections.contains(card.collectionName) { collections.append(card.collectionName); collections.sort() }
+            if !boxes.contains(card.storageLocation) { boxes.append(card.storageLocation); boxes.sort() }
+
+            self.saveCollectionAsync()
+
+            var taskID = UIBackgroundTaskIdentifier.invalid
+            taskID = UIApplication.shared.beginBackgroundTask(withName: "UpdateCard") {
+                UIApplication.shared.endBackgroundTask(taskID)
+                taskID = .invalid
+            }
+
+            Task.detached(priority: .userInitiated) { [weak self, taskID] in
+                defer { UIApplication.shared.endBackgroundTask(taskID) }
+                guard let self = self else { return }
+                let currency = await MainActor.run { self.selectedCurrency }
+                let (prices, _) = await ScryfallAPI.updateTrends(cards: [card], currency: currency, force: true, updateTimestamp: false)
+                if let newPrice = prices[card.id] {
+                    await MainActor.run {
+                        guard let self = self else { return }
+                        if let i = self.scannedList.firstIndex(where: { $0.id == card.id }) {
+                            self.scannedList[i].currentValuation = newPrice
+                            self.saveCollectionAsync()
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    func moveCard(_ card: SavedCard, toCollection: String, toBox: String) {
+        if let idx = scannedList.firstIndex(of: card) {
+            scannedList[idx].collectionName = toCollection
+            scannedList[idx].storageLocation = toBox
+            self.saveCollectionAsync()
+        }
+    }
+
+    func deleteCard(_ card: SavedCard) {
+        if let idx = scannedList.firstIndex(where: { $0.id == card.id }) {
+            let fileName = scannedList[idx].imageFileName
+            Task { await ImageManager.delete(name: fileName) }
+            scannedList.remove(at: idx)
+            self.saveCollectionAsync()
+        }
+    }
+
+    func saveManualCard(_ card: SavedCard) {
+        self.scannedList.insert(card, at: 0)
+        self.saveCollectionAsync()
+        ReviewEngine.logScan()
+
+        var taskID = UIBackgroundTaskIdentifier.invalid
+        taskID = UIApplication.shared.beginBackgroundTask(withName: "SaveManual") {
+            UIApplication.shared.endBackgroundTask(taskID)
+            taskID = .invalid
+        }
+
+        Task.detached(priority: .userInitiated) { [weak self, taskID] in
+            defer { UIApplication.shared.endBackgroundTask(taskID) }
+            guard let self = self else { return }
+            let currency = await MainActor.run { self.selectedCurrency }
+            let (prices, metadata) = await ScryfallAPI.updateTrends(cards: [card], currency: currency, force: true, updateTimestamp: false)
+
+            if let newPrice = prices[card.id] {
+                await MainActor.run { [weak self] in
+                    guard let self = self else { return }
+                    if let idx = self.scannedList.firstIndex(where: { $0.id == card.id }) {
+                        self.scannedList[idx].currentValuation = newPrice
+                        if let meta = metadata[card.id] {
+                            self.scannedList[idx].rarity = meta.0
+                            self.scannedList[idx].colorIdentity = meta.1
+                            if meta.2 { self.scannedList[idx].isSerialized = true }
+                        }
+                        self.saveCollectionAsync()
+                    }
+                }
+            }
+        }
+    }
+
+    // MARK: - Export
+
+    func exportCollection(format: ExportFormat) async -> URL? {
+        let list = self.scannedList
+        return await Task.detached { ExportEngine.generate(cards: list, format: format) }.value
+    }
+
+    func copyToClipboard(format: ExportFormat) {
+        let text = ExportEngine.generateString(cards: self.scannedList, format: format)
+        UIPasteboard.general.string = text
+    }
+
+    func generateShareImage(for card: SavedCard) async -> UIImage? {
+        let currencySymbol = self.selectedCurrency.symbol
+        return await Task.detached {
+            let renderer = UIGraphicsImageRenderer(size: CGSize(width: 1080, height: 1080))
+            return renderer.image { ctx in
+                UIColor.black.setFill()
+                ctx.fill(CGRect(x: 0, y: 0, width: 1080, height: 1080))
+                if let img = ImageManager.load(name: card.imageFileName) { img.draw(in: CGRect(x: 140, y: 180, width: 800, height: 800)) }
+                if let watermark = UIImage(named: "share_watermark") { watermark.draw(in: CGRect(x: 340, y: 990, width: 400, height: 80)) }
+                else { "Verified by IYmtg".draw(at: CGPoint(x: 100, y: 1000), withAttributes: [.font: UIFont.systemFont(ofSize: 40), .foregroundColor: UIColor.gray]) }
+                let price = "\(currencySymbol)\(card.currentValuation ?? 0.0)" as NSString
+                price.draw(at: CGPoint(x: 100, y: 40), withAttributes: [.font: UIFont.systemFont(ofSize: 120, weight: .bold), .foregroundColor: UIColor.green])
+            }
+        }.value
+    }
+
+    // MARK: - Firebase Backup (manual, metadata only)
+
+    /// Pushes all card metadata to Firebase Firestore as a secondary disaster-recovery backup.
+    /// Does NOT include card images (those remain in iCloud Drive).
+    /// Primary sync is handled automatically by SwiftData + CloudKit.
+    func backupAllToFirebase() {
+        guard !isBackingUpToFirebase else { return }
+        isBackingUpToFirebase = true
+        let snapshot = self.scannedList
+
+        Task { [weak self] in
+            CloudEngine.signInSilently()
+            for card in snapshot {
+                await CloudEngine.save(card: card)
+            }
+            await MainActor.run { [weak self] in
+                self?.isBackingUpToFirebase = false
+            }
+        }
+    }
+
+    // MARK: - Persistence
+
+    func forceSave() {
+        saveTask?.cancel()
+        let listSnapshot = self.scannedList
+        Task { await PersistenceController.shared.backgroundActor.save(listSnapshot) }
+    }
+
+    func saveCollectionAsync() {
+        saveTask?.cancel()
+        let listSnapshot = self.scannedList
+        saveTask = Task {
+            do {
+                try await Task.sleep(nanoseconds: 500_000_000)
+                if !Task.isCancelled {
+                    await PersistenceController.shared.backgroundActor.save(listSnapshot)
+                }
+            } catch {}
+        }
+    }
+}

IYmtg_App_iOS/Features/Scanner/ScannerViewModel.swift

@@ -0,0 +1,449 @@
+import SwiftUI
+import UIKit
+import Vision
+import AVFoundation
+import AudioToolbox
+import Combine
+import os
+import ImageIO
+import CoreMedia
+import CoreImage
+
+// MARK: - SCANNER VIEW MODEL
+// Focused exclusively on camera management, frame processing, and the scanning pipeline.
+// Collection state and persistence are delegated to CollectionViewModel.
+@MainActor
+class ScannerViewModel: NSObject, ObservableObject, AVCaptureVideoDataOutputSampleBufferDelegate {
+
+    // MARK: Scanner State
+    @Published var statusText = "Initializing Database..."
+    @Published var isDatabaseLoading = true
+    @Published var detectedCard: CardMetadata?
+    @Published var detectedDamages: [DamageObservation] = []
+    @Published var isProcessing = false
+    @Published var isFound = false
+    @Published var isPermissionDenied = false
+    @Published var showDatabaseAlert = false
+    @Published var databaseAlertTitle = ""
+    @Published var databaseAlertMessage = ""
+    @Published var isSaving = false
+    @Published var isTorchOn = false
+    @Published var isAutoScanEnabled: Bool = UserDefaults.standard.bool(forKey: "isAutoScanEnabled") {
+        didSet { UserDefaults.standard.set(isAutoScanEnabled, forKey: "isAutoScanEnabled") }
+    }
+    @Published var currentFoilType: String = AppConfig.Defaults.defaultFoil
+
+    // MARK: Collection Forwarding (read-only convenience for ScannerView & CardDetailView)
+    // Changes to collectionVM's @Published properties propagate via objectWillChange forwarding.
+    var isCollectionLoading: Bool { collectionVM.isCollectionLoading }
+    var isConnected: Bool { collectionVM.isConnected }
+    var collections: [String] { collectionVM.collections }
+    var boxes: [String] { collectionVM.boxes }
+    var selectedCurrency: CurrencyCode { collectionVM.selectedCurrency }
+    var currentCollection: String {
+        get { collectionVM.currentCollection }
+        set { collectionVM.currentCollection = newValue }
+    }
+    var currentBox: String {
+        get { collectionVM.currentBox }
+        set { collectionVM.currentBox = newValue }
+    }
+
+    // MARK: Collection Method Forwarding (for CardDetailView backward compatibility)
+    func saveManualCard(_ card: SavedCard) { collectionVM.saveManualCard(card) }
+    func updateCardDetails(_ card: SavedCard) { collectionVM.updateCardDetails(card) }
+
+    // MARK: Dependencies
+    let collectionVM: CollectionViewModel
+    var currentFrameImage: CGImage?
+
+    private var collectionVMObservation: AnyCancellable?
+    private var cancellables = Set<AnyCancellable>()
+    private var processingTask: Task<Void, Never>?
+    private let analyzer = AnalysisActor()
+    public let session = AVCaptureSession()
+    private let sessionQueue = DispatchQueue(label: "com.iymtg.sessionQueue")
+    private let foilEngine = FoilEngine()
+    private var lastFrameTime = Date.distantPast
+    private var lastSaveTime = Date.distantPast
+
+    private let successHaptics = UINotificationFeedbackGenerator()
+    private let detectHaptics = UIImpactFeedbackGenerator(style: .light)
+    private var saveTask: Task<Void, Never>?
+    private let processingLock = OSAllocatedUnfairLock(initialState: false)
+    private var isScanningActive = false
+    private var isSessionConfigured = false
+    private var focusResetTask: Task<Void, Never>?
+
+    // MARK: Init
+
+    init(collectionVM: CollectionViewModel) {
+        self.collectionVM = collectionVM
+        super.init()
+
+        // Forward collectionVM changes so ScannerView re-renders on collection state updates
+        collectionVMObservation = collectionVM.objectWillChange
+            .sink { [weak self] _ in self?.objectWillChange.send() }
+
+        UIDevice.current.beginGeneratingDeviceOrientationNotifications()
+
+        // Pre-warm ML models in background
+        Task(priority: .background) { let _ = ConditionEngine.model; let _ = FoilEngine.model }
+
+        // Load card fingerprint database
+        Task.detached(priority: .userInitiated) { [weak self] in
+            guard let self = self else { return }
+            if let url = Bundle.main.url(forResource: "cards", withExtension: "json") {
+                do {
+                    try await self.analyzer.loadDatabase(from: url)
+                    await MainActor.run { [weak self] in
+                        guard let self = self else { return }
+                        self.isDatabaseLoading = false
+                        self.statusText = "Ready to Scan"
+                        self.checkCameraPermissions()
+                    }
+                } catch {
+                    await MainActor.run { [weak self] in
+                        guard let self = self else { return }
+                        self.isDatabaseLoading = false
+                        self.databaseAlertTitle = "Database Error"
+                        self.databaseAlertMessage = "Failed to load card database. Please try restarting the app."
+                        self.showDatabaseAlert = true
+                    }
+                }
+            } else {
+                await MainActor.run { [weak self] in
+                    guard let self = self else { return }
+                    self.isDatabaseLoading = false
+                    self.databaseAlertTitle = "Database Missing"
+                    self.databaseAlertMessage = "The card database could not be found. Please reinstall the app."
+                    self.showDatabaseAlert = true
+                }
+            }
+        }
+
+        DevEngine.activateIfCompiled()
+        ModelManager.shared.checkForUpdates()
+    }
+
+    deinit {
+        UIDevice.current.endGeneratingDeviceOrientationNotifications()
+        processingTask?.cancel()
+        saveTask?.cancel()
+        focusResetTask?.cancel()
+    }
+
+    // MARK: - Camera Permissions & Setup
+
+    func checkCameraPermissions() {
+        switch AVCaptureDevice.authorizationStatus(for: .video) {
+        case .authorized:
+            self.isPermissionDenied = false
+            if !isSessionConfigured { self.setupCamera() } else { self.startSession() }
+        case .notDetermined:
+            Task { [weak self] in
+                if await AVCaptureDevice.requestAccess(for: .video) {
+                    self?.isPermissionDenied = false; self?.setupCamera()
+                } else {
+                    self?.isPermissionDenied = true; self?.statusText = "Camera Access Denied"
+                }
+            }
+        case .denied, .restricted:
+            self.isPermissionDenied = true; self.statusText = "Camera Access Denied"
+        @unknown default: break
+        }
+    }
+
+    func setupCamera() {
+        if self.isPermissionDenied { return }
+
+        DispatchQueue.global(qos: .background).async {
+            try? AVAudioSession.sharedInstance().setCategory(.ambient, mode: .default, options: .mixWithOthers)
+            try? AVAudioSession.sharedInstance().setActive(true)
+        }
+
+        sessionQueue.async { [weak self] in
+            guard let self = self else { return }
+            guard let dev = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back),
+                  let input = try? AVCaptureDeviceInput(device: dev) else { return }
+
+            self.session.beginConfiguration()
+            for i in self.session.inputs { self.session.removeInput(i) }
+            for o in self.session.outputs { self.session.removeOutput(o) }
+
+            if self.session.canSetSessionPreset(.hd1920x1080) { self.session.sessionPreset = .hd1920x1080 }
+            if self.session.canAddInput(input) { self.session.addInput(input) }
+
+            let out = AVCaptureVideoDataOutput()
+            out.setSampleBufferDelegate(self, queue: DispatchQueue(label: "video"))
+            if self.session.canAddOutput(out) { self.session.addOutput(out) }
+
+            do {
+                try dev.lockForConfiguration()
+                if dev.isFocusModeSupported(.continuousAutoFocus) { dev.focusMode = .continuousAutoFocus }
+                if dev.isSmoothAutoFocusSupported { dev.isSmoothAutoFocusEnabled = true }
+                // OPTIMIZATION: Cap at 30 FPS to reduce thermal load and battery usage
+                dev.activeVideoMinFrameDuration = CMTime(value: 1, timescale: 30)
+                let zoomFactor = min(dev.maxAvailableVideoZoomFactor, max(1.5, dev.minAvailableVideoZoomFactor))
+                dev.videoZoomFactor = zoomFactor
+                dev.unlockForConfiguration()
+            } catch {}
+
+            self.session.commitConfiguration()
+            Task { @MainActor [weak self] in self?.isSessionConfigured = true }
+            self.session.startRunning()
+
+            if dev.hasTorch {
+                let actualState = dev.torchMode == .on
+                Task { @MainActor [weak self] in self?.isTorchOn = actualState }
+            }
+        }
+    }
+
+    func toggleTorch() {
+        guard let dev = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back), dev.hasTorch else { return }
+        sessionQueue.async { [weak self] in
+            try? dev.lockForConfiguration()
+            dev.torchMode = dev.torchMode == .on ? .off : .on
+            dev.unlockForConfiguration()
+            let actualState = dev.torchMode == .on
+            Task { @MainActor [weak self] in self?.isTorchOn = actualState }
+        }
+    }
+
+    func focusCamera(at point: CGPoint) {
+        focusResetTask?.cancel()
+
+        sessionQueue.async {
+            guard let dev = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back) else { return }
+            do {
+                try dev.lockForConfiguration()
+                if dev.isFocusPointOfInterestSupported { dev.focusPointOfInterest = point; dev.focusMode = .autoFocus }
+                if dev.isExposurePointOfInterestSupported { dev.exposurePointOfInterest = point; dev.exposureMode = .autoExpose }
+                dev.unlockForConfiguration()
+            } catch {}
+        }
+
+        focusResetTask = Task { [weak self] in
+            do {
+                try await Task.sleep(nanoseconds: 4_000_000_000)
+                self?.sessionQueue.async {
+                    guard let dev = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back) else { return }
+                    do {
+                        try dev.lockForConfiguration()
+                        if dev.isFocusModeSupported(.continuousAutoFocus) { dev.focusMode = .continuousAutoFocus }
+                        dev.unlockForConfiguration()
+                    } catch {}
+                }
+            } catch {
+                // Task cancelled, do not reset focus
+            }
+        }
+    }
+
+    func startSession() {
+        self.isScanningActive = true
+        sessionQueue.async { [weak self] in
+            guard let self = self else { return }
+            if !self.session.isRunning { self.session.startRunning() }
+        }
+    }
+
+    func stopSession() {
+        self.isScanningActive = false
+        focusResetTask?.cancel()
+        processingTask?.cancel()
+        collectionVM.forceSave()
+
+        sessionQueue.async { [weak self] in
+            if let dev = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back), dev.hasTorch {
+                try? dev.lockForConfiguration(); dev.torchMode = .off; dev.unlockForConfiguration()
+            }
+            guard let self = self else { return }
+            if self.session.isRunning { self.session.stopRunning() }
+        }
+        Task { @MainActor [weak self] in
+            guard let self = self else { return }
+            if !self.isFound { self.cancelScan() }
+            self.isProcessing = false; self.isTorchOn = false
+        }
+    }
+
+    // MARK: - Frame Processing
+
+    nonisolated func captureOutput(_ output: AVCaptureOutput, didOutput sampleBuffer: CMSampleBuffer, from connection: AVCaptureConnection) {
+        guard let cvBuffer = CMSampleBufferGetImageBuffer(sampleBuffer) else { return }
+        guard processingLock.withLock({ if $0 { return false } else { $0 = true; return true } }) else { return }
+
+        let ciImage = CIImage(cvPixelBuffer: cvBuffer)
+
+        Task.detached(priority: .userInitiated) { [weak self] in
+            guard let self = self else { return }
+            defer { self.processingLock.withLock { $0 = false } }
+
+            let (shouldProcess, orientation, isBusy) = await MainActor.run {
+                let now = Date()
+                // OPTIMIZATION: Throttle analysis pipeline to ~15 FPS
+                if now.timeIntervalSince(self.lastFrameTime) < 0.06 { return (false, CGImagePropertyOrientation.up, false) }
+                self.lastFrameTime = now
+                return (self.isScanningActive && !self.isFound && !self.isSaving && !self.isDatabaseLoading && !self.isCollectionLoading && now.timeIntervalSince(self.lastSaveTime) > 2.0, self.getCurrentOrientations().1, self.isProcessing)
+            }
+
+            guard shouldProcess else { return }
+            guard let cg = SharedEngineResources.context.createCGImage(ciImage, from: ciImage.extent) else { return }
+
+            let foilType = await self.foilEngine.addFrame(cg, orientation: orientation)
+            await MainActor.run { if let foilType { self.currentFoilType = foilType } }
+
+            guard !isBusy else { return }
+
+            let handler = VNImageRequestHandler(cgImage: cg, orientation: .up)
+            let req = VNDetectRectanglesRequest()
+            try? handler.perform([req])
+            if let obs = req.results?.first as? VNRectangleObservation {
+                Task { @MainActor [weak self] in
+                    guard let self = self, self.isScanningActive else { return }
+                    self.processingTask = Task { [weak self] in await self?.processCrop(obs, from: cg, orientation: orientation) }
+                }
+            }
+        }
+    }
+
+    func processCrop(_ obs: VNRectangleObservation, from fullImage: CGImage, orientation: CGImagePropertyOrientation) async {
+        if Task.isCancelled { return }
+
+        let shouldProceed = await MainActor.run {
+            if self.isFound || self.isProcessing { return false }
+            self.isProcessing = true
+            self.detectHaptics.prepare()
+            return true
+        }
+        guard shouldProceed else { return }
+
+        let croppedImage: CGImage? = await Task.detached {
+            let width = CGFloat(fullImage.width)
+            let height = CGFloat(fullImage.height)
+            let bbox = obs.boundingBox
+            let rect = CGRect(x: bbox.origin.x * width,
+                              y: (1 - bbox.origin.y - bbox.height) * height,
+                              width: bbox.width * width,
+                              height: bbox.height * height)
+            return fullImage.cropping(to: rect)
+        }.value
+
+        guard let cropped = croppedImage else {
+            await MainActor.run { self.isProcessing = false }
+            return
+        }
+
+        if DevEngine.isDevMode { DevEngine.saveRaw(image: UIImage(cgImage: cropped), label: "AutoCrop") }
+        if Task.isCancelled { await MainActor.run { self.isProcessing = false }; return }
+
+        // OPTIMIZATION: Run identification and damage grading in parallel
+        async let analysis = self.analyzer.analyze(croppedImage: cropped, orientation: orientation)
+        async let damageCheck = Task.detached(priority: .userInitiated) { ConditionEngine.detectDamage(image: cropped, orientation: orientation) }.value
+
+        let ((finalCard, detectedSerialized), damages) = await (analysis, damageCheck)
+
+        if Task.isCancelled { await MainActor.run { self.isProcessing = false }; return }
+
+        await MainActor.run {
+            guard !self.isFound && self.isScanningActive else { self.isProcessing = false; return }
+
+            if var card = finalCard {
+                self.isFound = true
+                self.successHaptics.notificationOccurred(.success)
+                AudioServicesPlaySystemSound(1108)
+
+                card.isSerialized = detectedSerialized
+                self.detectedDamages = damages
+                self.detectedCard = card
+                self.currentFrameImage = cropped
+
+                if self.isAutoScanEnabled {
+                    self.saveCurrentCard()
+                } else {
+                    self.isProcessing = false
+                }
+            } else {
+                self.isProcessing = false
+            }
+        }
+    }
+
+    // MARK: - Scan Actions
+
+    func cancelScan() {
+        self.isFound = false
+        self.detectedCard = nil
+        self.currentFrameImage = nil
+        self.isProcessing = false
+        self.currentFoilType = AppConfig.Defaults.defaultFoil
+        self.statusText = "Ready to Scan"
+        self.processingTask?.cancel()
+    }
+
+    func saveCurrentCard() {
+        guard let card = detectedCard, let cgImage = currentFrameImage else { return }
+        self.isSaving = true
+        self.lastSaveTime = Date()
+
+        let imageName = "\(UUID().uuidString).jpg"
+        let uiImage = UIImage(cgImage: cgImage, scale: 1.0, orientation: getCurrentOrientations().0)
+
+        var entry = SavedCard(from: card, imageName: imageName, collection: collectionVM.currentCollection, location: collectionVM.currentBox)
+        entry.foilType = self.currentFoilType
+        entry.condition = ConditionEngine.overallGrade(damages: self.detectedDamages)
+
+        let autoScan = self.isAutoScanEnabled
+
+        // Delegate persistence and cloud sync to CollectionViewModel
+        collectionVM.addCard(entry, cgImage: cgImage, uiImage: uiImage, autoScan: autoScan)
+
+        if autoScan {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
+                self?.cancelScan()
+                self?.isSaving = false
+            }
+        } else {
+            self.cancelScan()
+            self.isSaving = false
+        }
+    }
+
+    // MARK: - Training Uploads
+
+    func uploadTrainingImage(label: String) {
+        guard let cg = currentFrameImage else { return }
+        let orientation = getCurrentOrientations().0
+        let img = UIImage(cgImage: cg, scale: 1.0, orientation: orientation)
+        Task.detached { TrainingUploader.upload(image: img, label: label, force: true) }
+    }
+
+    func uploadCorrection(image: UIImage?, card: SavedCard, original: SavedCard?) {
+        guard let img = image ?? ImageManager.load(name: card.imageFileName) else { return }
+
+        var labels: [String] = []
+        if card.name != original?.name || card.setCode != original?.setCode { labels.append("Identity_\(card.setCode)_\(card.collectorNumber)") }
+        if card.condition != original?.condition { labels.append("Condition_\(card.condition)") }
+        if card.foilType != original?.foilType { labels.append("Foil_\(card.foilType)") }
+
+        if labels.isEmpty { return }
+
+        Task.detached {
+            for label in labels { TrainingUploader.upload(image: img, label: label, force: true) }
+        }
+    }
+
+    // MARK: - Helpers
+
+    private func getCurrentOrientations() -> (UIImage.Orientation, CGImagePropertyOrientation) {
+        switch UIDevice.current.orientation {
+        case .portrait: return (.right, .right)
+        case .portraitUpsideDown: return (.left, .left)
+        case .landscapeLeft: return (.up, .up)
+        case .landscapeRight: return (.down, .down)
+        default: return (.right, .right)
+        }
+    }
+}