Refactor EntityGridView for better performance & memory usage

Author: kushalpandya

Models/Core/Entity.swift

@@ -1,6 +1,7 @@
 import Foundation
 import AppKit
 import SwiftUI
+import CryptoKit
 
 // MARK: - Artist Initials
 
@@ -168,17 +169,22 @@ struct CategoryEntity: Entity {
 // MARK: - UUID Extension
 
 extension UUID {
+    /// Deterministic name-based UUID
     init(name: String, namespace: UUID) {
-        let combined = "\(namespace.uuidString)-\(name)"
-        let hash = combined.hashValue
-        let uuidString = String(
-            format: "%08X-%04X-%04X-%04X-%012X",
-            UInt32(hash & 0xFFFFFFFF),
-            UInt16((hash >> 32) & 0xFFFF),
-            UInt16((hash >> 48) & 0x0FFF) | 0x5000,
-            UInt16((hash >> 60) & 0x3FFF) | 0x8000,
-            UInt64(abs(hash)) & 0xFFFFFFFFFFFF
+        var input = Data()
+        withUnsafeBytes(of: namespace.uuid) { input.append(contentsOf: $0) }
+        input.append(contentsOf: name.utf8)
+
+        var digest = Array(Insecure.SHA1.hash(data: input))
+        digest[6] = (digest[6] & 0x0F) | 0x50
+        digest[8] = (digest[8] & 0x3F) | 0x80
+
+        let bytes: uuid_t = (
+            digest[0], digest[1], digest[2], digest[3],
+            digest[4], digest[5], digest[6], digest[7],
+            digest[8], digest[9], digest[10], digest[11],
+            digest[12], digest[13], digest[14], digest[15]
         )
-        self = UUID(uuidString: uuidString)!
+        self.init(uuid: bytes)
     }
 }

Utilities/ArtworkCache.swift

@@ -0,0 +1,42 @@
+import AppKit
+import Foundation
+
+/// Operation subclass that guarantees its continuation is resumed
+/// even when cancelled, unlike `BlockOperation` whose execution blocks
+/// are skipped entirely for cancelled operations.
+final class ArtworkLoadOperation: Operation, @unchecked Sendable {
+    private let continuation: CheckedContinuation<NSImage?, Never>
+    private let work: () -> NSImage?
+
+    init(continuation: CheckedContinuation<NSImage?, Never>, work: @escaping () -> NSImage?) {
+        self.continuation = continuation
+        self.work = work
+        super.init()
+    }
+
+    override func main() {
+        continuation.resume(returning: isCancelled ? nil : work())
+    }
+}
+
+extension OperationQueue {
+    /// Enqueues a render and resumes its continuation when complete.
+    /// Cancelling the awaiting task cancels the queued operation; cancelled
+    /// operations resume with `nil` without rendering.
+    func renderArtwork(_ work: @escaping () -> NSImage?) async -> NSImage? {
+        final class Holder: @unchecked Sendable {
+            var operation: ArtworkLoadOperation?
+        }
+        let holder = Holder()
+
+        return await withTaskCancellationHandler {
+            await withCheckedContinuation { continuation in
+                let operation = ArtworkLoadOperation(continuation: continuation, work: work)
+                holder.operation = operation
+                self.addOperation(operation)
+            }
+        } onCancel: {
+            holder.operation?.cancel()
+        }
+    }
+}

Views/Components/EntityGridView.swift

@@ -6,8 +6,7 @@ struct EntityGridView<T: Entity>: View {
     let contextMenuItems: (T) -> [ContextMenuItem]
 
     @State private var hoveredEntityID: UUID?
-    @State private var isScrolling = false
-    
+
     private let columns = [
         GridItem(.adaptive(minimum: ViewDefaults.gridArtworkSize, maximum: ViewDefaults.gridArtworkSize + 40), spacing: 16)
     ]
@@ -18,30 +17,24 @@ struct EntityGridView<T: Entity>: View {
                 ForEach(entities) { entity in
                     EntityGridItem(
                         entity: entity,
-                        isHovered: isScrolling ? false : (hoveredEntityID == entity.id),
-                        isScrolling: isScrolling,
+                        isHovered: hoveredEntityID == entity.id,
                         onSelect: {
                             onSelectEntity(entity)
                         },
                         onHover: { isHovered in
-                            if !isScrolling {
-                                hoveredEntityID = isHovered ? entity.id : nil
-                            }
+                            hoveredEntityID = isHovered ? entity.id : nil
                         }
                     )
                     .contextMenu {
                         ForEach(contextMenuItems(entity), id: \.id) { item in
                             contextMenuItem(item)
                         }
                     }
-                    .id(entity.id)
                 }
             }
             .padding(.horizontal, 14)
             .padding(.vertical, 6)
         }
-        .coordinateSpace(name: "scroll")
-        .modifier(ScrollDetectionModifier(isScrolling: $isScrolling, hoveredEntityID: $hoveredEntityID))
     }
 
     @ViewBuilder
@@ -50,106 +43,58 @@ struct EntityGridView<T: Entity>: View {
     }
 }
 
-// MARK: - Cross-OS Scroll Detection
+// MARK: - Image Cache
 
-private struct ScrollDetectionModifier: ViewModifier {
-    @Binding var isScrolling: Bool
-    @Binding var hoveredEntityID: UUID?
-    
-    func body(content: Content) -> some View {
-        if #available(macOS 15.0, *) {
-            content
-                .onScrollPhaseChange { _, newPhase in
-                    withAnimation(.none) {
-                        let wasScrolling = isScrolling
-                        isScrolling = newPhase == .interacting || newPhase == .decelerating
-                        
-                        if isScrolling && !wasScrolling {
-                            hoveredEntityID = nil
-                        }
-                    }
-                }
-        } else {
-            content
-                .background(
-                    ScrollDetectionView { isDetectedScrolling in
-                        if isDetectedScrolling != isScrolling {
-                            withAnimation(.none) {
-                                isScrolling = isDetectedScrolling
-                                if isScrolling {
-                                    hoveredEntityID = nil
-                                }
-                            }
-                        }
-                    }
-                )
-        }
-    }
-}
+private final class EntityArtworkCache: @unchecked Sendable {
+    static let shared = EntityArtworkCache()
+    private let cache = NSCache<NSString, NSImage>()
+    private let loadQueue: OperationQueue = {
+        let queue = OperationQueue()
+        queue.maxConcurrentOperationCount = max(2, ProcessInfo.processInfo.activeProcessorCount / 2)
+        queue.qualityOfService = .utility
+        return queue
+    }()
 
-// MARK: - Scroll Detection for macOS 14
+    private static let pixelSize = Int(ViewDefaults.gridArtworkSize * 2)
+    private static let bytesPerImage = pixelSize * pixelSize * 4
 
-private struct ScrollDetectionView: View {
-    let onScrollingChanged: (Bool) -> Void
-    @State private var lastOffset: CGFloat = 0
-    @State private var scrollTimer: Timer?
-    
-    var body: some View {
-        GeometryReader { geometry in
-            Color.clear
-                .preference(
-                    key: ScrollOffsetKey.self,
-                    value: geometry.frame(in: .named("scroll")).origin.y
-                )
-        }
-        .onPreferenceChange(ScrollOffsetKey.self) { newOffset in
-            if abs(newOffset - lastOffset) > 1 {
-                onScrollingChanged(true)
-                lastOffset = newOffset
-                
-                scrollTimer?.invalidate()
-                scrollTimer = Timer.scheduledTimer(withTimeInterval: 0.15, repeats: false) { _ in
-                    onScrollingChanged(false)
-                }
-            }
-        }
+    init() {
+        cache.countLimit = 500
+        cache.totalCostLimit = 80 * 1024 * 1024
     }
-}
 
-private struct ScrollOffsetKey: PreferenceKey {
-    static var defaultValue: CGFloat = 0
-    static func reduce(value: inout CGFloat, nextValue: () -> CGFloat) {
-        value = nextValue()
+    private func cacheKey(for entity: any Entity) -> NSString {
+        let artworkSize = entity.artworkData?.count ?? 0
+        return "\(entity.id.uuidString)-\(artworkSize)-rendered" as NSString
     }
-}
-
-// MARK: - Image Cache
 
-private class RenderedImageCache {
-    static let shared = RenderedImageCache()
-    private let cache = NSCache<NSString, NSImage>()
-    
-    init() {
-        cache.countLimit = 1000
+    func getCachedImage(for entity: any Entity) -> NSImage? {
+        cache.object(forKey: cacheKey(for: entity))
     }
-    
-    func getImage(for entity: any Entity) -> NSImage? {
-        let artworkHash = entity.artworkData?.hashValue ?? 0
-        let key = "\(entity.id.uuidString)-\(artworkHash)-rendered" as NSString
+
+    func loadImage(for entity: any Entity) async -> NSImage? {
+        let key = cacheKey(for: entity)
 
         if let cached = cache.object(forKey: key) {
             return cached
         }
 
         guard let artworkData = entity.artworkData else { return nil }
 
-        let renderedImage = createRenderedImage(from: artworkData)
-        
-        if let image = renderedImage {
-            cache.setObject(image, forKey: key)
+        return await loadQueue.renderArtwork { [self] in
+            // Re-check cache, another operation may have loaded it while queued
+            if let cached = cache.object(forKey: key) {
+                return cached
+            }
+
+            let renderedImage = createRenderedImage(from: artworkData)
+
+            if let image = renderedImage {
+                cache.setObject(image, forKey: key, cost: Self.bytesPerImage)
+            }
+
+            return renderedImage
         }
-        
-        return renderedImage
     }
 
     private func createRenderedImage(from data: Data) -> NSImage? {
@@ -206,7 +151,6 @@ private class RenderedImageCache {
 private struct EntityGridItem<T: Entity>: View {
     let entity: T
     let isHovered: Bool
-    let isScrolling: Bool
     let onSelect: () -> Void
     let onHover: (Bool) -> Void
 
@@ -242,11 +186,8 @@ private struct EntityGridItem<T: Entity>: View {
                         .shadow(color: .black.opacity(0.2), radius: 10, x: 0, y: 5)
                 }
             }
-            .onAppear {
-                loadArtwork()
-            }
-            .onChange(of: entity.artworkData) {
-                loadArtwork()
+            .task(id: artworkTaskID) {
+                await loadArtwork()
             }
 
             VStack(alignment: .leading, spacing: 2) {
@@ -293,23 +234,27 @@ private struct EntityGridItem<T: Entity>: View {
         .background(
             RoundedRectangle(cornerRadius: 10)
                 .fill(isHovered ? Color(NSColor.selectedContentBackgroundColor).opacity(0.15) : Color.clear)
-                .animation(
-                    isScrolling ? .none : .easeInOut(duration: 0.08),
-                    value: isHovered
-                )
+                .animation(.easeInOut(duration: 0.08), value: isHovered)
         )
         .contentShape(Rectangle())
         .onTapGesture(perform: onSelect)
         .onHover(perform: onHover)
     }
 
-    private func loadArtwork() {
-        DispatchQueue.global(qos: .userInitiated).async {
-            let image = RenderedImageCache.shared.getImage(for: entity)
+    private var artworkTaskID: String {
+        "\(entity.id.uuidString)-\(entity.artworkData?.count ?? 0)"
+    }
 
-            DispatchQueue.main.async {
-                self.renderedImage = image
-            }
+    private func loadArtwork() async {
+        // Serve cache hits synchronously to avoid placeholder flicker on scroll recycle
+        if let cached = EntityArtworkCache.shared.getCachedImage(for: entity) {
+            renderedImage = cached
+            return
         }
+
+        let image = await EntityArtworkCache.shared.loadImage(for: entity)
+
+        guard !Task.isCancelled else { return }
+        renderedImage = image
     }
 }