Refactor EntityGridView for better performance & memory usage (#269)

Refactors EntityGridView (used for Artists and Albums grid) to have better
performance around scrolling and memory usage while also sharing artwork
caching logic between the tracks list and entity grid views.

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
     }
 }