@devo-bmad-custom/agent-orchestration 1.0.2 → 1.0.4

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/photos-camera-media/references/image-loading-caching.md

@@ -1,869 +1,869 @@
-# Image Loading and Caching Patterns
-
-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.2, backward-compatible to iOS 16 unless noted.
-
-## 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 (iOS 15+) provides built-in async image loading from a URL. Suitable for simple cases but has significant limitations for production use.
-
-### Basic Usage
-
-```swift
-AsyncImage(url: URL(string: "https://example.com/photo.jpg"))
-```
-
-### Phase Handling
-
-```swift
-AsyncImage(url: imageURL) { 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 .failure:
-        Image(systemName: "photo")
-            .font(.largeTitle)
-            .foregroundStyle(.secondary)
-            .frame(width: 200, height: 200)
-    @unknown default:
-        EmptyView()
-    }
-}
-```
-
-### Custom Transition
-
-```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)
-    }
-}
-.frame(width: 200, height: 200)
-.clipShape(RoundedRectangle(cornerRadius: 12))
-```
-
-### Limitations
-
-AsyncImage has several shortcomings for production apps:
-
-- **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.
-
-For anything beyond simple, low-volume image display, use a custom loading pipeline.
-
----
-
-## NSCache-Based In-Memory Cache
-
-An actor-isolated in-memory image cache backed by NSCache. Thread-safe and automatically evicts entries under memory pressure.
-
-```swift
-import UIKit
-
-actor ImageCache {
-    static let shared = ImageCache()
-
-    private let cache = NSCache<NSString, UIImage>()
-    private var inFlightTasks: [URL: Task<UIImage?, Never>] = [:]
-
-    init(countLimit: Int = 100, totalCostLimit: Int = 50 * 1024 * 1024) {
-        cache.countLimit = countLimit
-        cache.totalCostLimit = totalCostLimit  // 50 MB default
-    }
-
-    func image(for url: URL) -> UIImage? {
-        cache.object(forKey: url.absoluteString as NSString)
-    }
-
-    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 removeImage(for url: URL) {
-        cache.removeObject(forKey: url.absoluteString as NSString)
-    }
-
-    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
-        }
-
-        inFlightTasks[url] = task
-        return await task.value
-    }
-}
-```
-
-### Usage in SwiftUI
-
-```swift
-struct CachedImageView: View {
-    let url: URL
-    @State private var image: 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)
-        }
-    }
-}
-```
-
----
-
-## URLCache-Based Disk Caching
-
-Configure URLCache for persistent image caching that survives app restarts. URLCache handles HTTP cache headers automatically.
-
-### Configuring a Dedicated URLSession
-
-```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)
-    }
-}
-```
-
-### Cache-Aware Request
-
-```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
-}
-```
-
-### 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
-}
-```
-
-### 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
-
-```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
-    }
-
-    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
-    }
-
-    return UIImage(cgImage: cgImage)
-}
-```
-
-### When to Downsample
-
-- 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.
-
-### Memory Savings
-
-| Source Size | Display Size | Without Downsampling | With Downsampling |
-|---|---|---|---|
-| 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 |
-
----
-
-## Image Prefetching for Lists and Grids
-
-Prefetch images before they scroll into view. Works with both UICollectionView data source prefetching and SwiftUI List.
-
-### Prefetch Coordinator
-
-```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
-    }
-
-    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
-            }
-        }
-    }
-
-    func cancelPrefetch(urls: [URL]) {
-        for url in urls {
-            prefetchTasks[url]?.cancel()
-            prefetchTasks[url] = nil
-        }
-    }
-
-    func cancelAll() {
-        prefetchTasks.values.forEach { $0.cancel() }
-        prefetchTasks.removeAll()
-    }
-}
-```
-
-### SwiftUI Integration with ScrollView and LazyVGrid
-
-```swift
-struct PhotoGrid: View {
-    let photos: [Photo]
-    @State private var prefetcher = ImagePrefetcher()
-
-    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()
-                        .onAppear {
-                            prefetchNearby(photo)
-                        }
-                }
-            }
-        }
-        .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)
-    }
-}
-```
-
-### UICollectionView Prefetching (UIKit Interop)
-
-```swift
-final class PhotoCollectionPrefetcher: NSObject, UICollectionViewDataSourcePrefetching {
-    private let prefetcher = ImagePrefetcher()
-    private let photos: [Photo]
-
-    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
-
-```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
-    }
-
-    let mutableData = NSMutableData()
-    guard let destination = CGImageDestinationCreateWithData(
-        mutableData, UTType.jpeg.identifier as CFString, 1, nil
-    ) else {
-        return nil
-    }
-
-    var options: [CFString: Any] = [
-        kCGImageDestinationLossyCompressionQuality: 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)
-    }
-
-    guard CGImageDestinationFinalize(destination) else { return nil }
-    return mutableData as Data
-}
-```
-
----
-
-## Compression Before Upload
-
-Reduce file size before uploading to a server. Balance quality and size based on the use case.
-
-### JPEG Compression with Target Size
-
-```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
-        }
-        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
-    }
-
-    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))
-    }
-
-    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
-    }
-
-    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
-
-Monitor and respond to memory pressure to keep your image pipeline stable.
-
-### Memory Warning Observer
-
-```swift
-@Observable
-@MainActor
-final class MemoryMonitor {
-    var isUnderPressure = false
-
-    init() {
-        NotificationCenter.default.addObserver(
-            forName: UIApplication.didReceiveMemoryWarningNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
-            self?.handleMemoryWarning()
-        }
-    }
-
-    private func handleMemoryWarning() {
-        isUnderPressure = true
-
-        Task {
-            await ImageCache.shared.removeAll()
-        }
-
-        // Reset after a delay
-        Task {
-            try? await Task.sleep(for: .seconds(10))
-            isUnderPressure = 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)
-        }
-    }
-    guard result == KERN_SUCCESS else { return 0 }
-    return Double(info.resident_size) / (1024 * 1024)
-}
-```
-
-### Adaptive Cache Sizing
-
-```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()
-    }
-}
-```
-
----
-
-## Complete Image Loading Pipeline
-
-A production-ready pipeline that combines in-memory caching, disk caching via URLCache, downsampling, and request coalescing.
-
-### ImageLoader Actor
-
-```swift
-import UIKit
-import ImageIO
-
-actor ImageLoader {
-    static let shared = ImageLoader()
-
-    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?
-            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 image
-        }
-
-        inFlightTasks[url] = task
-        return await task.value
-    }
-
-    /// 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)
-    }
-
-    /// 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
-    }
-}
-```
-
-### SwiftUI View Using the Pipeline
-
-```swift
-struct PipelineImageView: View {
-    let url: URL
-    var displaySize: CGSize = CGSize(width: 300, height: 300)
-
-    @State private var image: UIImage?
-    @State private var isLoading = true
-
-    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())
-            } else {
-                Color.secondary.opacity(0.15)
-                    .overlay {
-                        Image(systemName: "photo")
-                            .font(.title2)
-                            .foregroundStyle(.secondary)
-                    }
-            }
-        }
-        .frame(width: displaySize.width, height: displaySize.height)
-        .clipped()
-        .task(id: url) {
-            isLoading = true
-            image = await ImageLoader.shared.load(from: url, displaySize: displaySize)
-            isLoading = false
-        }
-    }
-}
-```
-
-### Memory Warning Integration
-
-```swift
-struct PhotoGridView: View {
-    let photos: [Photo]
-
-    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)
-                    )
-                }
-            }
-        }
-        .onReceive(NotificationCenter.default.publisher(
-            for: UIApplication.didReceiveMemoryWarningNotification
-        )) { _ in
-            Task {
-                await ImageLoader.shared.purgeMemoryCache()
-            }
-        }
-    }
-}
-```
-
-### When to Use Each Layer
-
-| Scenario | Recommended Approach |
-|---|---|
-| 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 |
+# Image Loading and Caching Patterns
+
+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.2, backward-compatible to iOS 16 unless noted.
+
+## 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 (iOS 15+) provides built-in async image loading from a URL. Suitable for simple cases but has significant limitations for production use.
+
+### Basic Usage
+
+```swift
+AsyncImage(url: URL(string: "https://example.com/photo.jpg"))
+```
+
+### Phase Handling
+
+```swift
+AsyncImage(url: imageURL) { 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 .failure:
+        Image(systemName: "photo")
+            .font(.largeTitle)
+            .foregroundStyle(.secondary)
+            .frame(width: 200, height: 200)
+    @unknown default:
+        EmptyView()
+    }
+}
+```
+
+### Custom Transition
+
+```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)
+    }
+}
+.frame(width: 200, height: 200)
+.clipShape(RoundedRectangle(cornerRadius: 12))
+```
+
+### Limitations
+
+AsyncImage has several shortcomings for production apps:
+
+- **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.
+
+For anything beyond simple, low-volume image display, use a custom loading pipeline.
+
+---
+
+## NSCache-Based In-Memory Cache
+
+An actor-isolated in-memory image cache backed by NSCache. Thread-safe and automatically evicts entries under memory pressure.
+
+```swift
+import UIKit
+
+actor ImageCache {
+    static let shared = ImageCache()
+
+    private let cache = NSCache<NSString, UIImage>()
+    private var inFlightTasks: [URL: Task<UIImage?, Never>] = [:]
+
+    init(countLimit: Int = 100, totalCostLimit: Int = 50 * 1024 * 1024) {
+        cache.countLimit = countLimit
+        cache.totalCostLimit = totalCostLimit  // 50 MB default
+    }
+
+    func image(for url: URL) -> UIImage? {
+        cache.object(forKey: url.absoluteString as NSString)
+    }
+
+    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 removeImage(for url: URL) {
+        cache.removeObject(forKey: url.absoluteString as NSString)
+    }
+
+    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
+        }
+
+        inFlightTasks[url] = task
+        return await task.value
+    }
+}
+```
+
+### Usage in SwiftUI
+
+```swift
+struct CachedImageView: View {
+    let url: URL
+    @State private var image: 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)
+        }
+    }
+}
+```
+
+---
+
+## URLCache-Based Disk Caching
+
+Configure URLCache for persistent image caching that survives app restarts. URLCache handles HTTP cache headers automatically.
+
+### Configuring a Dedicated URLSession
+
+```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)
+    }
+}
+```
+
+### Cache-Aware Request
+
+```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
+}
+```
+
+### 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
+}
+```
+
+### 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
+
+```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
+    }
+
+    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
+    }
+
+    return UIImage(cgImage: cgImage)
+}
+```
+
+### When to Downsample
+
+- 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.
+
+### Memory Savings
+
+| Source Size | Display Size | Without Downsampling | With Downsampling |
+|---|---|---|---|
+| 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 |
+
+---
+
+## Image Prefetching for Lists and Grids
+
+Prefetch images before they scroll into view. Works with both UICollectionView data source prefetching and SwiftUI List.
+
+### Prefetch Coordinator
+
+```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
+    }
+
+    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
+            }
+        }
+    }
+
+    func cancelPrefetch(urls: [URL]) {
+        for url in urls {
+            prefetchTasks[url]?.cancel()
+            prefetchTasks[url] = nil
+        }
+    }
+
+    func cancelAll() {
+        prefetchTasks.values.forEach { $0.cancel() }
+        prefetchTasks.removeAll()
+    }
+}
+```
+
+### SwiftUI Integration with ScrollView and LazyVGrid
+
+```swift
+struct PhotoGrid: View {
+    let photos: [Photo]
+    @State private var prefetcher = ImagePrefetcher()
+
+    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()
+                        .onAppear {
+                            prefetchNearby(photo)
+                        }
+                }
+            }
+        }
+        .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)
+    }
+}
+```
+
+### UICollectionView Prefetching (UIKit Interop)
+
+```swift
+final class PhotoCollectionPrefetcher: NSObject, UICollectionViewDataSourcePrefetching {
+    private let prefetcher = ImagePrefetcher()
+    private let photos: [Photo]
+
+    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
+
+```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
+    }
+
+    let mutableData = NSMutableData()
+    guard let destination = CGImageDestinationCreateWithData(
+        mutableData, UTType.jpeg.identifier as CFString, 1, nil
+    ) else {
+        return nil
+    }
+
+    var options: [CFString: Any] = [
+        kCGImageDestinationLossyCompressionQuality: 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)
+    }
+
+    guard CGImageDestinationFinalize(destination) else { return nil }
+    return mutableData as Data
+}
+```
+
+---
+
+## Compression Before Upload
+
+Reduce file size before uploading to a server. Balance quality and size based on the use case.
+
+### JPEG Compression with Target Size
+
+```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
+        }
+        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
+    }
+
+    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))
+    }
+
+    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
+    }
+
+    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
+
+Monitor and respond to memory pressure to keep your image pipeline stable.
+
+### Memory Warning Observer
+
+```swift
+@Observable
+@MainActor
+final class MemoryMonitor {
+    var isUnderPressure = false
+
+    init() {
+        NotificationCenter.default.addObserver(
+            forName: UIApplication.didReceiveMemoryWarningNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.handleMemoryWarning()
+        }
+    }
+
+    private func handleMemoryWarning() {
+        isUnderPressure = true
+
+        Task {
+            await ImageCache.shared.removeAll()
+        }
+
+        // Reset after a delay
+        Task {
+            try? await Task.sleep(for: .seconds(10))
+            isUnderPressure = 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)
+        }
+    }
+    guard result == KERN_SUCCESS else { return 0 }
+    return Double(info.resident_size) / (1024 * 1024)
+}
+```
+
+### Adaptive Cache Sizing
+
+```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()
+    }
+}
+```
+
+---
+
+## Complete Image Loading Pipeline
+
+A production-ready pipeline that combines in-memory caching, disk caching via URLCache, downsampling, and request coalescing.
+
+### ImageLoader Actor
+
+```swift
+import UIKit
+import ImageIO
+
+actor ImageLoader {
+    static let shared = ImageLoader()
+
+    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?
+            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 image
+        }
+
+        inFlightTasks[url] = task
+        return await task.value
+    }
+
+    /// 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)
+    }
+
+    /// 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
+    }
+}
+```
+
+### SwiftUI View Using the Pipeline
+
+```swift
+struct PipelineImageView: View {
+    let url: URL
+    var displaySize: CGSize = CGSize(width: 300, height: 300)
+
+    @State private var image: UIImage?
+    @State private var isLoading = true
+
+    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())
+            } else {
+                Color.secondary.opacity(0.15)
+                    .overlay {
+                        Image(systemName: "photo")
+                            .font(.title2)
+                            .foregroundStyle(.secondary)
+                    }
+            }
+        }
+        .frame(width: displaySize.width, height: displaySize.height)
+        .clipped()
+        .task(id: url) {
+            isLoading = true
+            image = await ImageLoader.shared.load(from: url, displaySize: displaySize)
+            isLoading = false
+        }
+    }
+}
+```
+
+### Memory Warning Integration
+
+```swift
+struct PhotoGridView: View {
+    let photos: [Photo]
+
+    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)
+                    )
+                }
+            }
+        }
+        .onReceive(NotificationCenter.default.publisher(
+            for: UIApplication.didReceiveMemoryWarningNotification
+        )) { _ in
+            Task {
+                await ImageLoader.shared.purgeMemoryCache()
+            }
+        }
+    }
+}
+```
+
+### When to Use Each Layer
+
+| Scenario | Recommended Approach |
+|---|---|
+| 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 |