@devo-bmad-custom/agent-orchestration 1.0.0

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

@@ -0,0 +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 |