@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/photos-camera-media/references/image-loading-caching.md

@@ -1,869 +1,525 @@
-# Image Loading and Caching Patterns
+# Loading, caching and downsampling images
 
-Complete patterns for efficient image handling in iOS apps, from basic AsyncImage usage through production-ready caching and loading pipelines. All patterns use modern Swift async/await and target iOS 26 with Swift 6.3, backward-compatible to iOS 16 unless noted.
+Everything here uses async/await and targets iOS 26 and Swift 6.3.
+The samples need iOS 17 or later because the models use `@Observable`.
 
 ## Contents
-- AsyncImage Patterns
-- NSCache-Based In-Memory Cache
-- URLCache-Based Disk Caching
-- Image Downsampling with CGImageSource
-- Image Prefetching for Lists and Grids
-- HEIF/HEIC Handling
-- Compression Before Upload
-- Memory Budget Management
-- Complete Image Loading Pipeline
 
-## AsyncImage Patterns
+- [AsyncImage](#asyncimage)
+- [In-memory cache on NSCache](#in-memory-cache-on-nscache)
+- [Disk cache with URLCache](#disk-cache-with-urlcache)
+- [Downsampling at decode time](#downsampling-at-decode-time)
+- [Prefetching](#prefetching)
+- [HEIF and HEIC](#heif-and-heic)
+- [Shrinking before upload](#shrinking-before-upload)
+- [Staying inside a memory budget](#staying-inside-a-memory-budget)
+- [One loader for everything](#one-loader-for-everything)
+- [Which layer for which job](#which-layer-for-which-job)
 
-AsyncImage (iOS 15+) provides built-in async image loading from a URL. Suitable for simple cases but has significant limitations for production use.
+## AsyncImage
 
-### Basic Usage
+`AsyncImage` (iOS 15+) is fine for a handful of images and weak for anything
+heavier.
 
 ```swift
-AsyncImage(url: URL(string: "https://example.com/photo.jpg"))
-```
-
-### Phase Handling
+AsyncImage(url: logoURL)
 
-```swift
-AsyncImage(url: imageURL) { phase in
+AsyncImage(url: bannerURL) { phase in
     switch phase {
     case .empty:
         ProgressView()
-            .frame(width: 200, height: 200)
-    case .success(let image):
-        image
-            .resizable()
-            .aspectRatio(contentMode: .fill)
-            .frame(width: 200, height: 200)
-            .clipped()
+    case .success(let banner):
+        banner.resizable().aspectRatio(contentMode: .fill)
     case .failure:
-        Image(systemName: "photo")
-            .font(.largeTitle)
-            .foregroundStyle(.secondary)
-            .frame(width: 200, height: 200)
+        Image(systemName: "photo").foregroundStyle(.secondary)
     @unknown default:
         EmptyView()
     }
 }
-```
-
-### Custom Transition
+.frame(width: 200, height: 200)
+.clipped()
 
-```swift
-AsyncImage(url: imageURL, transaction: Transaction(animation: .easeIn(duration: 0.3))) { phase in
-    switch phase {
-    case .success(let image):
-        image
-            .resizable()
-            .aspectRatio(contentMode: .fill)
-            .transition(.opacity)
-    default:
-        Color.secondary.opacity(0.2)
+AsyncImage(url: coverURL, transaction: .init(animation: .easeIn(duration: 0.3))) { phase in
+    if let cover = phase.image {
+        cover.resizable().scaledToFit().transition(.opacity)
+    } else {
+        Color.gray.opacity(0.2)
     }
 }
-.frame(width: 200, height: 200)
-.clipShape(.rect(cornerRadius: 12))
 ```
 
-### Limitations
+What it cannot do:
 
-AsyncImage has several shortcomings for production apps:
+- Cache across redraws. When the view is rebuilt, the image downloads again.
+- Prefetch rows that are about to scroll into view.
+- Use your own `URLSession`. It rides the shared session with no say over cache
+  policy.
+- Expose the downloaded bytes, so no processing, downsampling or persistence.
+- Cancel on your terms. Its work lives and dies with the view.
 
-- **No caching across redraws**: images re-download when the view is recreated.
-- **No prefetching**: cannot load images ahead of scroll position.
-- **No custom URLSession**: uses the shared session with no cache policy control.
-- **No access to raw data**: cannot process, downsample, or persist the image data.
-- **No cancellation control**: tied entirely to the view lifecycle.
+Past simple, low-volume display, build a loading pipeline like the ones below.
 
-For anything beyond simple, low-volume image display, use a custom loading pipeline.
+## In-memory cache on NSCache
 
----
-
-## NSCache-Based In-Memory Cache
-
-An actor-isolated in-memory image cache backed by NSCache. Thread-safe and automatically evicts entries under memory pressure.
+An actor around `NSCache` is safe to call from anywhere, and `NSCache` drops
+entries on its own when memory gets tight. The actor also coalesces requests:
+two callers asking for the same URL share one download.
 
 ```swift
 import UIKit
 
-actor ImageCache {
-    static let shared = ImageCache()
+actor PosterCache {
+    static let shared = PosterCache()
 
-    private let cache = NSCache<NSString, UIImage>()
-    private var inFlightTasks: [URL: Task<UIImage?, Never>] = [:]
+    private let store: NSCache<NSString, UIImage> = {
+        let cache = NSCache<NSString, UIImage>()
+        cache.countLimit = 100
+        cache.totalCostLimit = 50 * 1024 * 1024
+        return cache
+    }()
+    private var inFlight: [URL: Task<UIImage?, Never>] = [:]
 
-    init(countLimit: Int = 100, totalCostLimit: Int = 50 * 1024 * 1024) {
-        cache.countLimit = countLimit
-        cache.totalCostLimit = totalCostLimit  // 50 MB default
-    }
+    private func key(_ address: URL) -> NSString { address.absoluteString as NSString }
 
-    func image(for url: URL) -> UIImage? {
-        cache.object(forKey: url.absoluteString as NSString)
+    func image(for address: URL) -> UIImage? {
+        store.object(forKey: key(address))
     }
 
-    func store(_ image: UIImage, for url: URL) {
-        let cost = image.jpegData(compressionQuality: 1.0)?.count ?? 0
-        cache.setObject(image, forKey: url.absoluteString as NSString, cost: cost)
+    func store(_ picture: UIImage, for address: URL) {
+        store.setObject(picture, forKey: key(address), cost: Self.bitmapBytes(picture))
     }
 
-    func removeImage(for url: URL) {
-        cache.removeObject(forKey: url.absoluteString as NSString)
+    func removeImage(for address: URL) {
+        store.removeObject(forKey: key(address))
     }
 
     func removeAll() {
-        cache.removeAllObjects()
-        inFlightTasks.removeAll()
-    }
-
-    /// Fetch an image with request coalescing. Multiple callers for the same URL
-    /// share a single network request.
-    func fetch(from url: URL, session: URLSession = .shared) async -> UIImage? {
-        // Return cached image immediately
-        if let cached = image(for: url) {
-            return cached
-        }
-
-        // Coalesce duplicate in-flight requests
-        if let existingTask = inFlightTasks[url] {
-            return await existingTask.value
-        }
-
-        let task = Task<UIImage?, Never> {
-            defer { inFlightTasks[url] = nil }
-
-            guard let (data, response) = try? await session.data(from: url),
-                  let httpResponse = response as? HTTPURLResponse,
-                  httpResponse.statusCode == 200,
-                  let image = UIImage(data: data) else {
-                return nil
-            }
-
-            store(image, for: url)
-            return image
+        store.removeAllObjects()
+        inFlight.values.forEach { $0.cancel() }
+        inFlight.removeAll()
+    }
+
+    func fetch(from address: URL, session: URLSession = .shared) async -> UIImage? {
+        if let hit = image(for: address) { return hit }
+        if let running = inFlight[address] { return await running.value }
+        let download = Task { () -> UIImage? in
+            guard let (body, reply) = try? await session.data(from: address),
+                  (reply as? HTTPURLResponse)?.statusCode == 200 else { return nil }
+            return UIImage(data: body)
         }
+        inFlight[address] = download
+        defer { inFlight[address] = nil }
+        let result = await download.value
+        if let result { store(result, for: address) }
+        return result
+    }
 
-        inFlightTasks[url] = task
-        return await task.value
+    static func bitmapBytes(_ image: UIImage) -> Int {
+        guard let bitmap = image.cgImage else { return 0 }
+        return bitmap.bytesPerRow * bitmap.height
     }
 }
 ```
 
-### Usage in SwiftUI
+Price each entry by its decoded bitmap size. Encoding a JPEG just to measure an
+entry is slow and reports compressed bytes, which is not what the cache holds
+in memory.
 
 ```swift
-struct CachedImageView: View {
+struct PosterView: View {
     let url: URL
-    @State private var image: UIImage?
+    @State private var poster: UIImage?
 
     var body: some View {
         Group {
-            if let image {
-                Image(uiImage: image)
-                    .resizable()
-                    .aspectRatio(contentMode: .fill)
-            } else {
-                Color.secondary.opacity(0.2)
-                    .overlay(ProgressView())
-            }
-        }
-        .task(id: url) {
-            image = await ImageCache.shared.fetch(from: url)
+            if let poster { Image(uiImage: poster).resizable().scaledToFill() } else { ProgressView() }
         }
+        .task(id: url) { poster = await PosterCache.shared.fetch(from: url) }
     }
 }
 ```
 
----
-
-## URLCache-Based Disk Caching
+## Disk cache with URLCache
 
-Configure URLCache for persistent image caching that survives app restarts. URLCache handles HTTP cache headers automatically.
-
-### Configuring a Dedicated URLSession
+`URLCache` survives relaunches and honours the server's HTTP cache headers with
+no extra code. Give images their own session and cache:
 
 ```swift
-enum ImageSessionConfiguration {
-    static func makeSession() -> URLSession {
-        let config = URLSessionConfiguration.default
-
-        // 50 MB memory / 200 MB disk
-        config.urlCache = URLCache(
-            memoryCapacity: 50 * 1024 * 1024,
-            diskCapacity: 200 * 1024 * 1024,
-            directory: cacheDirectory
-        )
-
-        config.requestCachePolicy = .returnCacheDataElseLoad
-        config.httpMaximumConnectionsPerHost = 6
-
-        return URLSession(configuration: config)
-    }
-
-    private static var cacheDirectory: URL {
-        FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
-            .appendingPathComponent("ImageCache", isDirectory: true)
-    }
+enum ImageNetwork {
+    static let session: URLSession = {
+        let folder = URL.cachesDirectory.appending(path: "ImageCache")
+        let megabyte = 1024 * 1024
+        let setup = URLSessionConfiguration.default
+        setup.urlCache = URLCache(memoryCapacity: 50 * megabyte,
+                                  diskCapacity: 200 * megabyte,
+                                  directory: folder)
+        setup.requestCachePolicy = .returnCacheDataElseLoad
+        setup.httpMaximumConnectionsPerHost = 6
+        return URLSession(configuration: setup)
+    }()
 }
-```
 
-### Cache-Aware Request
+let cached = URLRequest(url: artURL, cachePolicy: .returnCacheDataElseLoad)
+let fresh = URLRequest(url: artURL, cachePolicy: .reloadIgnoringLocalCacheData)
 
-```swift
-func cachedImageData(from url: URL, session: URLSession) async throws -> Data {
-    let request = URLRequest(url: url, cachePolicy: .returnCacheDataElseLoad)
-    let (data, _) = try await session.data(for: request)
-    return data
-}
+ImageNetwork.session.configuration.urlCache?.removeAllCachedResponses()
+ImageNetwork.session.configuration.urlCache?.removeCachedResponse(for: cached)
 ```
 
-### Force Refresh (Bypass Cache)
-
-```swift
-func refreshImageData(from url: URL, session: URLSession) async throws -> Data {
-    let request = URLRequest(url: url, cachePolicy: .reloadIgnoringLocalCacheData)
-    let (data, _) = try await session.data(for: request)
-    return data
-}
-```
+## Downsampling at decode time
 
-### Cache Cleanup
-
-```swift
-func cleanImageCache(session: URLSession) {
-    session.configuration.urlCache?.removeAllCachedResponses()
-}
-
-func removeCachedImage(for url: URL, session: URLSession) {
-    let request = URLRequest(url: url)
-    session.configuration.urlCache?.removeCachedResponse(for: request)
-}
-```
-
----
-
-## Image Downsampling with CGImageSource
-
-Loading a full-resolution image into memory then scaling it in the view wastes significant memory. Downsampling at decode time creates a smaller bitmap directly.
-
-### Downsample Function
+Decoding at full size and letting the view scale it down wastes memory.
+`CGImageSource` can decode straight into a small bitmap instead.
 
 ```swift
 import ImageIO
-import UIKit
 
-func downsample(data: Data, to pointSize: CGSize, scale: CGFloat = UITraitCollection.current.displayScale) -> UIImage? {
-    let maxDimensionInPixels = max(pointSize.width, pointSize.height) * scale
-
-    let options: [CFString: Any] = [
-        kCGImageSourceCreateThumbnailFromImageAlways: true,
-        kCGImageSourceShouldCacheImmediately: true,
-        kCGImageSourceCreateThumbnailWithTransform: true,
-        kCGImageSourceThumbnailMaxPixelSize: maxDimensionInPixels
-    ]
-
-    guard let source = CGImageSourceCreateWithData(data as CFData, nil),
-          let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
-        return nil
+enum Shrinker {
+    static func fromData(_ bytes: Data, maxPixels: CGFloat) -> UIImage? {
+        guard let reader = CGImageSourceCreateWithData(bytes as CFData, nil) else { return nil }
+        return render(reader, maxPixels: maxPixels)
     }
 
-    return UIImage(cgImage: cgImage)
-}
-```
-
-### Downsample from URL
-
-```swift
-func downsample(url: URL, to pointSize: CGSize, scale: CGFloat = UITraitCollection.current.displayScale) -> UIImage? {
-    let maxDimensionInPixels = max(pointSize.width, pointSize.height) * scale
-
-    let options: [CFString: Any] = [
-        kCGImageSourceCreateThumbnailFromImageAlways: true,
-        kCGImageSourceShouldCacheImmediately: true,
-        kCGImageSourceCreateThumbnailWithTransform: true,
-        kCGImageSourceThumbnailMaxPixelSize: maxDimensionInPixels
-    ]
-
-    guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
-          let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
-        return nil
+    static func fromFile(_ file: URL, maxPixels: CGFloat) -> UIImage? {
+        guard let reader = CGImageSourceCreateWithURL(file as CFURL, nil) else { return nil }
+        return render(reader, maxPixels: maxPixels)
     }
 
-    return UIImage(cgImage: cgImage)
+    private static func render(_ reader: CGImageSource, maxPixels: CGFloat) -> UIImage? {
+        let plan: [CFString: Any] = [
+            kCGImageSourceThumbnailMaxPixelSize: maxPixels,
+            kCGImageSourceShouldCacheImmediately: true,
+            kCGImageSourceCreateThumbnailFromImageAlways: true,
+            kCGImageSourceCreateThumbnailWithTransform: true,
+        ]
+        return CGImageSourceCreateThumbnailAtIndex(reader, 0, plan as CFDictionary).map(UIImage.init(cgImage:))
+    }
 }
 ```
 
-### When to Downsample
+Downsample when:
 
-- Displaying thumbnails in a list or grid (a 4032x3024 photo for a 100x100 cell wastes ~46 MB per image).
-- User-selected photos from the photo library.
-- Images fetched from a server that are larger than the display size.
-- Any time the source image dimensions exceed 2x the display point size.
+- showing thumbnails in lists or grids (a 4032 x 3024 photo in a 100 x 100 cell
+  wastes roughly 46 MB per cell otherwise);
+- showing photos the person picked from the library;
+- the server sends images larger than they will be drawn;
+- as a rule of thumb, the source is more than twice the display size in points.
 
-### Memory Savings
+Decoded memory at 3x scale, downsampled against a full decode:
 
-| Source Size | Display Size | Without Downsampling | With Downsampling |
+| Source | Drawn at | Downsampled | Full decode |
 |---|---|---|---|
-| 4032x3024 | 100x100 pt @3x | ~46 MB | ~0.35 MB |
-| 4032x3024 | 300x300 pt @3x | ~46 MB | ~3.1 MB |
-| 1920x1080 | 100x100 pt @3x | ~7.9 MB | ~0.35 MB |
-
----
+| 4032 x 3024 | 100 x 100 pt | ~0.35 MB | ~46 MB |
+| 4032 x 3024 | 300 x 300 pt | ~3.1 MB | ~46 MB |
+| 1920 x 1080 | 100 x 100 pt | ~0.35 MB | ~7.9 MB |
 
-## Image Prefetching for Lists and Grids
+## Prefetching
 
-Prefetch images before they scroll into view. Works with both UICollectionView data source prefetching and SwiftUI List.
-
-### Prefetch Coordinator
+Start downloads a little before cells appear. This pairs with
+`UICollectionView` prefetching and with SwiftUI grids alike.
 
 ```swift
-@Observable
-@MainActor
-final class ImagePrefetcher {
-    private let cache: ImageCache
-    private let session: URLSession
-    private var prefetchTasks: [URL: Task<Void, Never>] = [:]
-
-    init(cache: ImageCache = .shared,
-         session: URLSession = ImageSessionConfiguration.makeSession()) {
-        self.cache = cache
-        self.session = session
-    }
+@Observable @MainActor
+final class ArtPrefetcher {
+    private var jobs: [URL: Task<Void, Never>] = [:]
 
     func prefetch(urls: [URL]) {
-        for url in urls {
-            guard prefetchTasks[url] == nil else { continue }
-
-            prefetchTasks[url] = Task {
-                _ = await cache.fetch(from: url, session: session)
-                prefetchTasks[url] = nil
+        for url in urls where jobs[url] == nil {
+            jobs[url] = Task {
+                _ = await PosterCache.shared.fetch(from: url)
+                jobs[url] = nil
             }
         }
     }
 
     func cancelPrefetch(urls: [URL]) {
         for url in urls {
-            prefetchTasks[url]?.cancel()
-            prefetchTasks[url] = nil
+            jobs[url]?.cancel()
+            jobs[url] = nil
         }
     }
 
     func cancelAll() {
-        prefetchTasks.values.forEach { $0.cancel() }
-        prefetchTasks.removeAll()
+        jobs.values.forEach { $0.cancel() }
+        jobs.removeAll()
     }
 }
-```
-
-### SwiftUI Integration with ScrollView and LazyVGrid
-
-```swift
-struct PhotoGrid: View {
-    let photos: [Photo]
-    @State private var prefetcher = ImagePrefetcher()
 
+struct ArtGrid: View {
+    let urls: [URL]
+    @State private var prefetcher = ArtPrefetcher()
     private let columns = [GridItem(.adaptive(minimum: 100), spacing: 2)]
 
     var body: some View {
         ScrollView {
-            LazyVGrid(columns: columns, spacing: 2) {
-                ForEach(photos) { photo in
-                    CachedImageView(url: photo.thumbnailURL)
-                        .aspectRatio(1, contentMode: .fill)
-                        .clipped()
+            LazyVGrid(columns: columns) {
+                ForEach(Array(urls.enumerated()), id: \.offset) { index, url in
+                    PosterView(url: url)
+                        .frame(height: 100)
                         .onAppear {
-                            prefetchNearby(photo)
+                            let ahead = urls[(index + 1)..<min(index + 11, urls.count)]
+                            prefetcher.prefetch(urls: Array(ahead))
                         }
                 }
             }
         }
-        .onDisappear {
-            prefetcher.cancelAll()
-        }
-    }
-
-    private func prefetchNearby(_ photo: Photo) {
-        guard let index = photos.firstIndex(where: { $0.id == photo.id }) else { return }
-        let prefetchRange = (index + 1)..<min(index + 10, photos.count)
-        let urls = prefetchRange.map { photos[$0].thumbnailURL }
-        prefetcher.prefetch(urls: urls)
+        .onDisappear { prefetcher.cancelAll() }
     }
 }
 ```
 
-### UICollectionView Prefetching (UIKit Interop)
+In UIKit, a `UICollectionViewDataSourcePrefetching` object maps index paths to
+URLs in `collectionView(_:prefetchItemsAt:)` and calls `cancelPrefetch` from
+`collectionView(_:cancelPrefetchingForItemsAt:)`.
 
-```swift
-final class PhotoCollectionPrefetcher: NSObject, UICollectionViewDataSourcePrefetching {
-    private let prefetcher = ImagePrefetcher()
-    private let photos: [Photo]
+## HEIF and HEIC
 
-    init(photos: [Photo]) {
-        self.photos = photos
-    }
-
-    func collectionView(_ collectionView: UICollectionView,
-                        prefetchItemsAt indexPaths: [IndexPath]) {
-        let urls = indexPaths.map { photos[$0.item].thumbnailURL }
-        prefetcher.prefetch(urls: urls)
-    }
-
-    func collectionView(_ collectionView: UICollectionView,
-                        cancelPrefetchingForItemsAt indexPaths: [IndexPath]) {
-        let urls = indexPaths.map { photos[$0.item].thumbnailURL }
-        prefetcher.cancelPrefetch(urls: urls)
-    }
-}
-```
-
----
-
-## HEIF/HEIC Handling
-
-HEIF (High Efficiency Image Format) is the default camera format on modern iPhones. Handle detection, display, and conversion.
-
-### Detection
+HEIF is what current iPhones shoot by default.
 
 ```swift
 import UniformTypeIdentifiers
 
-func isHEIF(data: Data) -> Bool {
-    guard data.count >= 12 else { return false }
-    // Check for 'ftyp' box at byte 4
-    let ftypRange = data[4..<8]
-    return ftypRange.elementsEqual("ftyp".utf8)
-}
-
-func isHEIF(url: URL) -> Bool {
-    guard let type = UTType(filenameExtension: url.pathExtension) else { return false }
-    return type.conforms(to: .heif) || type.conforms(to: .heic)
-}
-```
-
-### Conversion to JPEG
-
-```swift
-func convertHEICToJPEG(data: Data, compressionQuality: CGFloat = 0.9) -> Data? {
-    guard let image = UIImage(data: data) else { return nil }
-    return image.jpegData(compressionQuality: compressionQuality)
-}
-```
-
-### Conversion to PNG
-
-```swift
-func convertHEICToPNG(data: Data) -> Data? {
-    guard let image = UIImage(data: data) else { return nil }
-    return image.pngData()
-}
-```
-
-### Conversion with CGImageDestination (More Control)
-
-```swift
-import ImageIO
-
-func convertHEICToJPEG(sourceData: Data,
-                        quality: CGFloat = 0.9,
-                        preserveMetadata: Bool = true) -> Data? {
-    guard let source = CGImageSourceCreateWithData(sourceData as CFData, nil),
-          let cgImage = CGImageSourceCreateImageAtIndex(source, 0, nil) else {
-        return nil
+enum HEIFTools {
+    static func looksLikeHEIF(_ bytes: Data) -> Bool {
+        guard bytes.count >= 12 else { return false }
+        return bytes[bytes.startIndex + 4 ..< bytes.startIndex + 8] == Data("ftyp".utf8)
     }
 
-    let mutableData = NSMutableData()
-    guard let destination = CGImageDestinationCreateWithData(
-        mutableData, UTType.jpeg.identifier as CFString, 1, nil
-    ) else {
-        return nil
+    static func isHEIF(fileExtension: String) -> Bool {
+        guard let kind = UTType(filenameExtension: fileExtension) else { return false }
+        return kind.conforms(to: .heif) || kind.conforms(to: .heic)
     }
 
-    var options: [CFString: Any] = [
-        kCGImageDestinationLossyCompressionQuality: quality
-    ]
+    static func jpeg(from photo: UIImage, quality: CGFloat = 0.9) -> Data? {
+        photo.jpegData(compressionQuality: quality)
+    }
 
-    // Preserve EXIF, GPS, and other metadata
-    if preserveMetadata,
-       let metadata = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) {
-        options[kCGImageDestinationMergeMetadata] = true
-        CGImageDestinationAddImage(destination, cgImage, metadata)
-    } else {
-        CGImageDestinationAddImage(destination, cgImage, options as CFDictionary)
+    static func png(from photo: UIImage) -> Data? {
+        photo.pngData()
     }
 
-    guard CGImageDestinationFinalize(destination) else { return nil }
-    return mutableData as Data
+    static func jpegKeepingMetadata(_ heif: Data, quality: CGFloat = 0.9) -> Data? {
+        guard let reader = CGImageSourceCreateWithData(heif as CFData, nil),
+              let frame = CGImageSourceCreateImageAtIndex(reader, 0, nil) else { return nil }
+        let sink = NSMutableData()
+        let jpegID = UTType.jpeg.identifier as CFString
+        guard let writer = CGImageDestinationCreateWithData(sink, jpegID, 1, nil)
+        else { return nil }
+        var properties = (CGImageSourceCopyPropertiesAtIndex(reader, 0, nil) as? [CFString: Any]) ?? [:]
+        properties[kCGImageDestinationLossyCompressionQuality] = quality
+        properties[kCGImageDestinationMergeMetadata] = true
+        CGImageDestinationAddImage(writer, frame, properties as CFDictionary)
+        return CGImageDestinationFinalize(writer) ? sink as Data : nil
+    }
 }
 ```
 
----
-
-## Compression Before Upload
+The `ftyp` check is a cheap first look at the container box; confirm with
+`CGImageSourceGetType` when it matters. The metadata-preserving path copies the
+source properties (EXIF, GPS) into the destination; the `UIImage` paths drop
+them.
 
-Reduce file size before uploading to a server. Balance quality and size based on the use case.
-
-### JPEG Compression with Target Size
+## Shrinking before upload
 
 ```swift
-func compressForUpload(image: UIImage,
-                       maxBytes: Int = 1_000_000,
-                       initialQuality: CGFloat = 0.9) -> Data? {
-    var quality = initialQuality
-
-    while quality > 0.1 {
-        guard let data = image.jpegData(compressionQuality: quality) else { return nil }
-        if data.count <= maxBytes {
-            return data
+enum UploadPrep {
+    static func jpeg(_ photo: UIImage, under maxBytes: Int = 1_000_000) -> Data? {
+        var quality: CGFloat = 0.9
+        while quality > 0.1 {
+            if let encoded = photo.jpegData(compressionQuality: quality), encoded.count <= maxBytes {
+                return encoded
+            }
+            quality -= 0.1
         }
-        quality -= 0.1
-    }
-
-    // Final attempt at minimum quality
-    return image.jpegData(compressionQuality: 0.1)
-}
-```
-
-### Resize and Compress
-
-```swift
-func resizeAndCompress(image: UIImage,
-                       maxDimension: CGFloat = 1920,
-                       compressionQuality: CGFloat = 0.8) -> Data? {
-    let size = image.size
-    let scale: CGFloat
-
-    if max(size.width, size.height) > maxDimension {
-        scale = maxDimension / max(size.width, size.height)
-    } else {
-        scale = 1.0
+        return photo.jpegData(compressionQuality: 0.1)
     }
 
-    let newSize = CGSize(width: size.width * scale, height: size.height * scale)
-
-    let renderer = UIGraphicsImageRenderer(size: newSize)
-    let resized = renderer.image { _ in
-        image.draw(in: CGRect(origin: .zero, size: newSize))
+    static func resized(_ photo: UIImage, longestSide: CGFloat = 1920) -> Data? {
+        let ratio = min(1, longestSide / max(photo.size.width, photo.size.height))
+        let target = CGSize(width: photo.size.width * ratio, height: photo.size.height * ratio)
+        let redrawn = UIGraphicsImageRenderer(size: target).image { _ in
+            photo.draw(in: CGRect(x: 0, y: 0, width: target.width, height: target.height))
+        }
+        return redrawn.jpegData(compressionQuality: 0.8)
     }
 
-    return resized.jpegData(compressionQuality: compressionQuality)
-}
-```
-
-### HEIF Compression (Smaller Files)
-
-```swift
-func compressAsHEIF(image: UIImage, quality: CGFloat = 0.8) -> Data? {
-    guard let cgImage = image.cgImage else { return nil }
-
-    let mutableData = NSMutableData()
-    guard let destination = CGImageDestinationCreateWithData(
-        mutableData, UTType.heic.identifier as CFString, 1, nil
-    ) else {
-        return nil
+    static func heic(_ photo: UIImage, level: CGFloat = 0.8) -> Data? {
+        guard let bitmap = photo.cgImage else { return nil }
+        let sink = NSMutableData()
+        let heicID = UTType.heic.identifier as CFString
+        guard let writer = CGImageDestinationCreateWithData(sink, heicID, 1, nil)
+        else { return nil }
+        CGImageDestinationAddImage(writer, bitmap, [kCGImageDestinationLossyCompressionQuality: level] as CFDictionary)
+        return CGImageDestinationFinalize(writer) ? sink as Data : nil
     }
-
-    let options: [CFString: Any] = [
-        kCGImageDestinationLossyCompressionQuality: quality
-    ]
-
-    CGImageDestinationAddImage(destination, cgImage, options as CFDictionary)
-    guard CGImageDestinationFinalize(destination) else { return nil }
-
-    return mutableData as Data
 }
 ```
 
----
-
-## Memory Budget Management
+Pick the trade-off per use: the quality ladder steps down from 0.9 in 0.1
+steps until the payload fits, with 0.1 as the floor; resizing caps the long
+edge first; HEIC gives smaller files at the same visual quality.
 
-Monitor and respond to memory pressure to keep your image pipeline stable.
-
-### Memory Warning Observer
+## Staying inside a memory budget
 
 ```swift
-@Observable
-@MainActor
-final class MemoryMonitor {
-    var isUnderPressure = false
+@Observable @MainActor
+final class PressureWatch {
+    private(set) var underPressure = false
+    @ObservationIgnored private var listener: Task<Void, Never>?
+    private let cooldown: Duration = .seconds(10)
 
     init() {
-        NotificationCenter.default.addObserver(
-            forName: UIApplication.didReceiveMemoryWarningNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
-            self?.handleMemoryWarning()
+        listener = Task { [weak self] in
+            let warnings = NotificationCenter.default.notifications(named: UIApplication.didReceiveMemoryWarningNotification)
+            for await _ in warnings { self?.react() }
         }
     }
 
-    private func handleMemoryWarning() {
-        isUnderPressure = true
-
-        Task {
-            await ImageCache.shared.removeAll()
-        }
-
-        // Reset after a delay
+    private func react() {
+        underPressure = true
         Task {
-            try? await Task.sleep(for: .seconds(10))
-            isUnderPressure = false
+            await PosterCache.shared.removeAll()
+            try? await Task.sleep(for: cooldown)
+            underPressure = false
         }
     }
 }
-```
 
-### Process Memory Usage
-
-```swift
-func currentMemoryUsageMB() -> Double {
-    var info = mach_task_basic_info()
-    var count = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size) / 4
-    let result = withUnsafeMutablePointer(to: &info) {
-        $0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
-            task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), $0, &count)
+func residentMemory() -> UInt64 {
+    var usage = mach_task_basic_info()
+    var words = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size / MemoryLayout<natural_t>.size)
+    let slotCount = Int(words)
+    let status = withUnsafeMutablePointer(to: &usage) { raw in
+        raw.withMemoryRebound(to: integer_t.self, capacity: slotCount) { slots in
+            task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), slots, &words)
         }
     }
-    guard result == KERN_SUCCESS else { return 0 }
-    return Double(info.resident_size) / (1024 * 1024)
+    return status == KERN_SUCCESS ? usage.resident_size : 0
 }
 ```
 
-### Adaptive Cache Sizing
+Size the cache from the device instead of a constant:
 
 ```swift
-actor AdaptiveImageCache {
-    private let cache = NSCache<NSString, UIImage>()
-
-    init() {
-        let totalMemory = ProcessInfo.processInfo.physicalMemory
-        // Use at most 10% of physical memory for image cache
-        let budgetBytes = Int(totalMemory / 10)
-        cache.totalCostLimit = budgetBytes
-        cache.countLimit = 200
-    }
-
-    func image(for url: URL) -> UIImage? {
-        cache.object(forKey: url.absoluteString as NSString)
-    }
-
-    func store(_ image: UIImage, for url: URL) {
-        let cost = cgImageMemorySize(image)
-        cache.setObject(image, forKey: url.absoluteString as NSString, cost: cost)
-    }
-
-    /// Estimate the decoded bitmap size in bytes.
-    private func cgImageMemorySize(_ image: UIImage) -> Int {
-        guard let cgImage = image.cgImage else { return 0 }
-        return cgImage.bytesPerRow * cgImage.height
-    }
-
-    func purge() {
-        cache.removeAllObjects()
-    }
-}
+let adaptive = NSCache<NSString, UIImage>()
+adaptive.totalCostLimit = Int(ProcessInfo.processInfo.physicalMemory / 10)
+adaptive.countLimit = 200
 ```
 
----
-
-## Complete Image Loading Pipeline
+Charge each entry `cgImage.bytesPerRow * cgImage.height`, its real decoded
+footprint.
 
-A production-ready pipeline that combines in-memory caching, disk caching via URLCache, downsampling, and request coalescing.
+## One loader for everything
 
-### ImageLoader Actor
+`GalleryLoader` stacks the layers: memory cache, `URLCache` on disk,
+downsampling and request coalescing.
 
 ```swift
-import UIKit
-import ImageIO
-
-actor ImageLoader {
-    static let shared = ImageLoader()
+actor GalleryLoader {
+    static let shared = GalleryLoader()
 
-    private let memoryCache = NSCache<NSString, UIImage>()
-    private let session: URLSession
-    private var inFlightTasks: [URL: Task<UIImage?, Never>] = [:]
-
-    init() {
-        let config = URLSessionConfiguration.default
-        config.urlCache = URLCache(
-            memoryCapacity: 50 * 1024 * 1024,
-            diskCapacity: 200 * 1024 * 1024
-        )
-        config.requestCachePolicy = .returnCacheDataElseLoad
-        config.httpMaximumConnectionsPerHost = 6
-        session = URLSession(configuration: config)
-
-        let totalMemory = ProcessInfo.processInfo.physicalMemory
-        memoryCache.totalCostLimit = Int(totalMemory / 10)
-        memoryCache.countLimit = 200
-    }
-
-    /// Load an image, optionally downsampling to the given display size.
-    func load(from url: URL, displaySize: CGSize? = nil) async -> UIImage? {
-        let cacheKey = cacheKey(url: url, size: displaySize)
-
-        // 1. Check memory cache
-        if let cached = memoryCache.object(forKey: cacheKey as NSString) {
-            return cached
-        }
-
-        // 2. Coalesce duplicate in-flight requests
-        if let existing = inFlightTasks[url] {
-            return await existing.value
-        }
-
-        let task = Task<UIImage?, Never> {
-            defer { inFlightTasks[url] = nil }
-
-            guard let (data, response) = try? await session.data(from: url),
-                  let httpResponse = response as? HTTPURLResponse,
-                  httpResponse.statusCode == 200 else {
-                return nil
-            }
-
-            // 3. Downsample if a display size is provided
-            let image: UIImage?
+    private let memory: NSCache<NSString, UIImage> = {
+        let cache = NSCache<NSString, UIImage>()
+        cache.totalCostLimit = Int(ProcessInfo.processInfo.physicalMemory / 10)
+        cache.countLimit = 200
+        return cache
+    }()
+    private let network = ImageNetwork.session
+    private var running: [String: Task<UIImage?, Never>] = [:]
+
+    private func key(_ url: URL, _ size: CGSize?) -> String {
+        guard let size else { return url.absoluteString }
+        let wide = Int(size.width), tall = Int(size.height)
+        return "\(url.absoluteString)_\(wide)x\(tall)"
+    }
+
+    func load(_ url: URL, displaySize: CGSize? = nil, scale: CGFloat = 3) async -> UIImage? {
+        let slot = key(url, displaySize)
+        if let hit = memory.object(forKey: slot as NSString) { return hit }
+        if let shared = running[slot] { return await shared.value }
+
+        let session = network
+        let source = url
+        let job = Task { () -> UIImage? in
+            guard let (body, _) = try? await session.data(from: source) else { return nil }
             if let displaySize {
-                image = Self.downsample(data: data, to: displaySize)
-            } else {
-                image = UIImage(data: data)
-            }
-
-            // 4. Store in memory cache
-            if let image {
-                let cost = Self.bitmapSize(of: image)
-                memoryCache.setObject(image, forKey: cacheKey as NSString, cost: cost)
+                return Shrinker.fromData(body, maxPixels: max(displaySize.width, displaySize.height) * scale)
             }
-
-            return image
+            return UIImage(data: body)
         }
+        running[slot] = job
+        defer { running[slot] = nil }
 
-        inFlightTasks[url] = task
-        return await task.value
+        guard let image = await job.value else { return nil }
+        let cost = image.cgImage.map { $0.bytesPerRow * $0.height } ?? 0
+        memory.setObject(image, forKey: slot as NSString, cost: cost)
+        return image
     }
 
-    /// Remove a specific URL from the memory cache.
-    func evict(url: URL, displaySize: CGSize? = nil) {
-        let key = cacheKey(url: url, size: displaySize)
-        memoryCache.removeObject(forKey: key as NSString)
+    func evict(url target: URL, displaySize box: CGSize? = nil) {
+        memory.removeObject(forKey: key(target, box) as NSString)
     }
 
-    /// Purge all in-memory cached images.
     func purgeMemoryCache() {
-        memoryCache.removeAllObjects()
-        inFlightTasks.values.forEach { $0.cancel() }
-        inFlightTasks.removeAll()
-    }
-
-    // MARK: - Private
-
-    private func cacheKey(url: URL, size: CGSize?) -> String {
-        if let size {
-            return "\(url.absoluteString)_\(Int(size.width))x\(Int(size.height))"
-        }
-        return url.absoluteString
-    }
-
-    private static func downsample(data: Data, to pointSize: CGSize) -> UIImage? {
-        let scale = UITraitCollection.current.displayScale
-        let maxDimension = max(pointSize.width, pointSize.height) * scale
-
-        let options: [CFString: Any] = [
-            kCGImageSourceCreateThumbnailFromImageAlways: true,
-            kCGImageSourceShouldCacheImmediately: true,
-            kCGImageSourceCreateThumbnailWithTransform: true,
-            kCGImageSourceThumbnailMaxPixelSize: maxDimension
-        ]
-
-        guard let source = CGImageSourceCreateWithData(data as CFData, nil),
-              let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
-            return nil
-        }
-
-        return UIImage(cgImage: cgImage)
-    }
-
-    private static func bitmapSize(of image: UIImage) -> Int {
-        guard let cgImage = image.cgImage else { return 0 }
-        return cgImage.bytesPerRow * cgImage.height
+        memory.removeAllObjects()
+        running.values.forEach { $0.cancel() }
+        running.removeAll()
     }
 }
 ```
 
-### SwiftUI View Using the Pipeline
+Order of lookup: memory, then an in-flight task for the same key, then a fetch
+(downsampled when a display size is given, plain decode otherwise), then store
+with the bitmap cost. The key carries the display size, so one URL can be
+cached at several sizes.
 
 ```swift
-struct PipelineImageView: View {
+struct GalleryTile: View {
     let url: URL
-    var displaySize: CGSize = CGSize(width: 300, height: 300)
-
     @State private var image: UIImage?
-    @State private var isLoading = true
+    @State private var failed = false
 
     var body: some View {
         ZStack {
             if let image {
-                Image(uiImage: image)
-                    .resizable()
-                    .aspectRatio(contentMode: .fill)
-            } else if isLoading {
-                Color.secondary.opacity(0.15)
-                    .overlay(ProgressView())
+                Image(uiImage: image).resizable().scaledToFill()
+            } else if failed {
+                Image(systemName: "photo").foregroundStyle(.secondary)
             } else {
-                Color.secondary.opacity(0.15)
-                    .overlay {
-                        Image(systemName: "photo")
-                            .font(.title2)
-                            .foregroundStyle(.secondary)
-                    }
+                ProgressView()
             }
         }
-        .frame(width: displaySize.width, height: displaySize.height)
-        .clipped()
         .task(id: url) {
-            isLoading = true
-            image = await ImageLoader.shared.load(from: url, displaySize: displaySize)
-            isLoading = false
+            image = await GalleryLoader.shared.load(url, displaySize: CGSize(width: 120, height: 120))
+            failed = image == nil
         }
     }
 }
-```
-
-### Memory Warning Integration
 
-```swift
-struct PhotoGridView: View {
-    let photos: [Photo]
+struct GalleryScreen: View {
+    let urls: [URL]
+    private let memoryWarning = NotificationCenter.default.publisher(for: UIApplication.didReceiveMemoryWarningNotification)
 
     var body: some View {
         ScrollView {
-            LazyVGrid(columns: [GridItem(.adaptive(minimum: 100), spacing: 2)], spacing: 2) {
-                ForEach(photos) { photo in
-                    PipelineImageView(
-                        url: photo.thumbnailURL,
-                        displaySize: CGSize(width: 100, height: 100)
-                    )
-                }
+            LazyVGrid(columns: [GridItem(.adaptive(minimum: 120))]) {
+                ForEach(urls, id: \.self) { GalleryTile(url: $0).frame(height: 120) }
             }
         }
-        .onReceive(NotificationCenter.default.publisher(
-            for: UIApplication.didReceiveMemoryWarningNotification
-        )) { _ in
-            Task {
-                await ImageLoader.shared.purgeMemoryCache()
-            }
+        .onReceive(memoryWarning) { _ in
+            Task { await GalleryLoader.shared.purgeMemoryCache() }
         }
     }
 }
 ```
 
-### When to Use Each Layer
+## Which layer for which job
 
-| Scenario | Recommended Approach |
+| Use | Layers |
 |---|---|
-| Simple profile avatar | AsyncImage |
-| Photo grid with scrolling | ImageLoader + downsampling + prefetch |
-| Offline-capable gallery | ImageLoader + URLCache disk caching |
-| Chat message images | ImageLoader + in-memory cache |
-| Full-resolution photo viewer | ImageLoader without downsampling |
-| Thumbnail in a widget | Downsample at fetch time, store in app group |
+| A single profile avatar | `AsyncImage` |
+| A scrolling photo grid | loader + downsampling + prefetching |
+| A gallery that works offline | loader + `URLCache` on disk |
+| Images inside chat messages | loader + memory cache |
+| A full-resolution photo viewer | loader, no downsampling |
+| A widget thumbnail | downsample when fetching, store in the app group |