@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/photos-camera-media/references/photokit-patterns.md

@@ -1,78 +1,72 @@
-# PhotosPicker Patterns
+# Picker and PhotoKit recipes
 
-Complete recipes for photo and video selection, loading, saving, and processing. All patterns target iOS 16+ with SwiftUI and async/await.
-
----
+Each recipe uses SwiftUI with async/await and needs iOS 17 or later (the views
+use the two-parameter `onChange(of:)`). `PhotosPicker` itself is iOS 16.
 
 ## Contents
 
-- [1. Single Photo Selection with Loading State](#1-single-photo-selection-with-loading-state)
-- [2. Multi-Selection with Progress Tracking](#2-multi-selection-with-progress-tracking)
-- [3. Loading Videos from PhotosPicker](#3-loading-videos-from-photospicker)
-- [4. Loading Live Photos](#4-loading-live-photos)
-- [5. PHPickerViewController Wrapping (UIKit Interop)](#5-phpickerviewcontroller-wrapping-uikit-interop)
-- [6. Saving Images to Photo Library](#6-saving-images-to-photo-library)
-- [7. Thumbnail Generation with ImageIO Downsampling](#7-thumbnail-generation-with-imageio-downsampling)
-- [8. HEIC/HEIF Handling](#8-heicheif-handling)
-- [9. Custom PhotosPicker Appearance](#9-custom-photospicker-appearance)
-- [10. Image Cropping Pattern](#10-image-cropping-pattern)
+- [1. One photo with an explicit loading state](#1-one-photo-with-an-explicit-loading-state)
+- [2. Many photos with progress](#2-many-photos-with-progress)
+- [3. Video from the picker](#3-video-from-the-picker)
+- [4. Live Photos](#4-live-photos)
+- [5. PHPickerViewController inside SwiftUI](#5-phpickerviewcontroller-inside-swiftui)
+- [6. Saving into the library](#6-saving-into-the-library)
+- [7. Thumbnails with ImageIO](#7-thumbnails-with-imageio)
+- [8. HEIC and HEIF](#8-heic-and-heif)
+- [9. Picker appearance](#9-picker-appearance)
+- [10. Cropping](#10-cropping)
 
-## 1. Single Photo Selection with Loading State
+## 1. One photo with an explicit loading state
 
-Handle the full lifecycle: idle, loading, loaded, and error.
+Model what the screen shows as a small enum instead of a pile of optionals.
 
 ```swift
 import SwiftUI
 import PhotosUI
 
-struct ProfilePhotoPicker: View {
-    @State private var selectedItem: PhotosPickerItem?
-    @State private var loadState: LoadState = .idle
-
-    enum LoadState {
-        case idle, loading, loaded(Image), error(String)
+struct AvatarEditor: View {
+    enum Stage {
+        case empty
+        case working
+        case ready(Image)
+        case failed(String)
     }
 
+    @State private var pick: PhotosPickerItem?
+    @State private var stage: Stage = .empty
+
     var body: some View {
-        VStack {
-            switch loadState {
-            case .idle:
-                Image(systemName: "person.crop.circle.fill")
-                    .resizable()
-                    .frame(width: 120, height: 120)
-                    .foregroundStyle(.secondary)
-            case .loading:
+        VStack(spacing: 16) {
+            switch stage {
+            case .empty:
+                Label("No avatar", systemImage: "person.crop.circle.fill")
+                    .labelStyle(.iconOnly)
+                    .font(.system(size: 96))
+            case .working:
                 ProgressView()
-                    .frame(width: 120, height: 120)
-            case .loaded(let image):
-                image
-                    .resizable()
-                    .scaledToFill()
-                    .frame(width: 120, height: 120)
-                    .clipShape(Circle())
-            case .error(let message):
-                ContentUnavailableView(message, systemImage: "exclamationmark.triangle")
+            case .ready(let face):
+                face.resizable().aspectRatio(contentMode: .fill)
+                    .frame(width: 120, height: 120).clipShape(.circle)
+            case .failed(let reason):
+                ContentUnavailableView("Could Not Load", systemImage: "exclamationmark.triangle",
+                                       description: Text(reason))
             }
-
-            PhotosPicker("Choose Photo", selection: $selectedItem, matching: .images)
+            PhotosPicker("Change Avatar", selection: $pick, matching: .images)
                 .buttonStyle(.borderedProminent)
         }
-        .onChange(of: selectedItem) { _, newItem in
-            guard let newItem else {
-                loadState = .idle
-                return
-            }
-            loadState = .loading
+        .onChange(of: pick) { _, chosen in
+            guard let chosen else { stage = .empty; return }
+            stage = .working
             Task {
                 do {
-                    if let data = try await newItem.loadTransferable(type: Data.self),
-                       let uiImage = UIImage(data: data) {
-                        loadState = .loaded(Image(uiImage: uiImage))
-                    } else {
-                        loadState = .error("Unable to load image")
+                    guard let raw = try await chosen.loadTransferable(type: Data.self),
+                          let decoded = UIImage(data: raw) else {
+                        stage = .failed("That file is not an image this app can read.")
+                        return
                     }
+                    stage = .ready(Image(uiImage: decoded))
                 } catch {
-                    loadState = .error(error.localizedDescription)
+                    stage = .failed(error.localizedDescription)
                 }
             }
         }
@@ -80,518 +74,378 @@ struct ProfilePhotoPicker: View {
 }
 ```
 
----
-
-## 2. Multi-Selection with Progress Tracking
+A cleared selection goes back to `.empty`. A `nil` payload or an undecodable
+one becomes a readable failure; a thrown error shows its
+`localizedDescription`.
 
-Load multiple images sequentially and report progress back to the UI.
+## 2. Many photos with progress
 
 ```swift
-import SwiftUI
-import PhotosUI
-
-struct MultiPhotoLoader: View {
-    @State private var selectedItems: [PhotosPickerItem] = []
-    @State private var loadedImages: [UIImage] = []
-    @State private var loadProgress: Double = 0
-    @State private var isLoading = false
+struct AlbumImporter: View {
+    @State private var picks: [PhotosPickerItem] = []
+    @State private var imported: [Image] = []
+    @State private var fraction = 0.0
+    @State private var busy = false
 
     var body: some View {
         VStack {
-            if isLoading {
-                ProgressView(value: loadProgress)
-                    .padding()
-            }
-
+            PhotosPicker("Import", selection: $picks, maxSelectionCount: 10, matching: .images)
+            if busy { ProgressView(value: fraction) }
             ScrollView(.horizontal) {
                 LazyHStack {
-                    ForEach(loadedImages.indices, id: \.self) { index in
-                        Image(uiImage: loadedImages[index])
-                            .resizable()
-                            .scaledToFill()
-                            .frame(width: 100, height: 100)
-                            .clipShape(.rect(cornerRadius: 8))
+                    ForEach(imported.indices, id: \.self) { i in
+                        imported[i].resizable().scaledToFill().frame(width: 108, height: 108).clipped()
                     }
                 }
-                .padding(.horizontal)
             }
-            .frame(height: loadedImages.isEmpty ? 0 : 116)
-
-            PhotosPicker(
-                "Select Photos",
-                selection: $selectedItems,
-                maxSelectionCount: 10,
-                matching: .images
-            )
+            .frame(height: imported.isEmpty ? 0 : 116)
         }
-        .onChange(of: selectedItems) { _, newItems in
-            Task { await loadImages(from: newItems) }
+        .onChange(of: picks) { _, batch in
+            Task { await importSequentially(batch) }
         }
     }
 
-    private func loadImages(from items: [PhotosPickerItem]) async {
-        isLoading = true
-        loadProgress = 0
-        var images: [UIImage] = []
-
-        for (index, item) in items.enumerated() {
-            if let data = try? await item.loadTransferable(type: Data.self),
-               let uiImage = UIImage(data: data) {
-                images.append(uiImage)
+    private func importSequentially(_ batch: [PhotosPickerItem]) async {
+        busy = true
+        var collected: [Image] = []
+        for (position, entry) in batch.enumerated() {
+            if let raw = try? await entry.loadTransferable(type: Data.self),
+               let decoded = UIImage(data: raw) {
+                collected.append(Image(uiImage: decoded))
             }
-            loadProgress = Double(index + 1) / Double(items.count)
+            fraction = Double(position + 1) / Double(batch.count)
         }
-
-        loadedImages = images
-        isLoading = false
+        imported = collected
+        busy = false
     }
 }
 ```
 
-Load sequentially rather than concurrently to control memory usage. Each full-resolution image can be large; loading ten simultaneously risks memory termination.
+Load one item after another. Ten full-resolution decodes running at the same
+time can push the app past its memory limit and get it terminated.
 
----
+## 3. Video from the picker
 
-## 3. Loading Videos from PhotosPicker
-
-Use a `Transferable` wrapper that writes video data to a temporary file, since videos are too large to hold in memory as `Data`.
+Movies are too large to hold as `Data`. Import them as a file and copy that
+file somewhere the app owns.
 
 ```swift
-import SwiftUI
-import PhotosUI
 import AVKit
+import CoreTransferable
 
-struct PickedMovie: Transferable {
-    let url: URL
+struct PickedClip: Transferable {
+    let location: URL
 
     static var transferRepresentation: some TransferRepresentation {
-        FileRepresentation(contentType: .movie) { movie in
-            SentTransferredFile(movie.url)
-        } importing: { received in
-            // Copy to a temporary location the app controls
-            let tempURL = FileManager.default.temporaryDirectory
+        FileRepresentation(contentType: .movie) { clip in
+            SentTransferredFile(clip.location)
+        } importing: { incoming in
+            let copy = URL.temporaryDirectory
                 .appendingPathComponent(UUID().uuidString)
                 .appendingPathExtension("mov")
-            try FileManager.default.copyItem(at: received.file, to: tempURL)
-            return PickedMovie(url: tempURL)
+            try FileManager.default.copyItem(at: incoming.file, to: copy)
+            return PickedClip(location: copy)
         }
     }
 }
 
-struct VideoPickerView: View {
-    @State private var selectedItem: PhotosPickerItem?
-    @State private var player: AVPlayer?
+struct ClipPreview: View {
+    @State private var pick: PhotosPickerItem?
+    @State private var clipPlayer: AVPlayer?
 
     var body: some View {
         VStack {
-            if let player {
-                VideoPlayer(player: player)
-                    .frame(height: 300)
+            if let clipPlayer {
+                VideoPlayer(player: clipPlayer).frame(height: 280)
             }
-
-            PhotosPicker("Select Video", selection: $selectedItem, matching: .videos)
+            PhotosPicker("Pick Clip", selection: $pick, matching: .videos)
         }
-        .onChange(of: selectedItem) { _, newItem in
+        .onChange(of: pick) { _, chosen in
             Task {
-                if let movie = try? await newItem?.loadTransferable(type: PickedMovie.self) {
-                    player = AVPlayer(url: movie.url)
-                }
+                guard let clip = try? await chosen?.loadTransferable(type: PickedClip.self) else { return }
+                clipPlayer = AVPlayer(url: clip.location)
             }
         }
     }
 }
 ```
 
-Always copy the received file to a temporary directory you control. The system may delete the original transfer file at any time.
+The file handed to `importing:` is temporary and the system may remove it at
+any time, so copy it before returning.
 
----
+## 4. Live Photos
 
-## 4. Loading Live Photos
+`PHLivePhoto` conforms to `Transferable` through PhotosUI starting with iOS 16,
+so a Live Photo loads like any other type. Display it with `PHLivePhotoView`
+wrapped for SwiftUI.
 
 ```swift
-import SwiftUI
-import PhotosUI
+struct LiveMoment: UIViewRepresentable {
+    let moment: PHLivePhoto
 
-@available(iOS 17.0, *)
-struct LivePhotoPickerView: View {
-    @State private var selectedItem: PhotosPickerItem?
-    @State private var livePhoto: PHLivePhoto?
+    func makeUIView(context: Context) -> PHLivePhotoView {
+        let view = PHLivePhotoView()
+        view.contentMode = .scaleAspectFit
+        return view
+    }
+
+    func updateUIView(_ view: PHLivePhotoView, context: Context) {
+        view.livePhoto = moment
+    }
+}
+
+struct LiveMomentPicker: View {
+    @State private var pick: PhotosPickerItem?
+    @State private var moment: PHLivePhoto?
 
     var body: some View {
         VStack {
-            if let livePhoto {
-                LivePhotoView(livePhoto: livePhoto)
-                    .frame(height: 300)
-            }
-
-            PhotosPicker(
-                "Select Live Photo",
-                selection: $selectedItem,
-                matching: .livePhotos
-            )
+            if let moment { LiveMoment(moment: moment).frame(height: 320) }
+            PhotosPicker("Pick Live Photo", selection: $pick, matching: .livePhotos)
         }
-        .onChange(of: selectedItem) { _, newItem in
-            Task {
-                livePhoto = try? await newItem?.loadTransferable(type: PHLivePhoto.self)
-            }
+        .onChange(of: pick) { _, chosen in
+            Task { moment = try? await chosen?.loadTransferable(type: PHLivePhoto.self) }
         }
     }
 }
 ```
 
-`PHLivePhoto` conforms to `Transferable` on iOS 17+. On iOS 16, load the Live Photo components manually using `PHAsset`.
-
----
-
-## 5. PHPickerViewController Wrapping (UIKit Interop)
+## 5. PHPickerViewController inside SwiftUI
 
-Use `PHPickerViewController` when you need UIKit-level control or are integrating into an existing UIKit codebase. Prefer `PhotosPicker` for pure SwiftUI apps.
+Reach for `PHPickerViewController` when the surrounding code is UIKit or needs
+UIKit-level control. In pure SwiftUI, `PhotosPicker` is simpler.
 
 ```swift
-import SwiftUI
-import PhotosUI
-
-struct PHPickerWrapper: UIViewControllerRepresentable {
-    @Binding var selectedImages: [UIImage]
-    var selectionLimit: Int = 0
-    @Environment(\.dismiss) private var dismiss
-
-    func makeCoordinator() -> Coordinator { Coordinator(self) }
+struct LegacyGalleryPicker: UIViewControllerRepresentable {
+    @Binding var chosen: [UIImage]
+    var limit = 0
 
     func makeUIViewController(context: Context) -> PHPickerViewController {
-        var config = PHPickerConfiguration(photoLibrary: .shared())
-        config.filter = .images
-        config.selectionLimit = selectionLimit
-        config.preferredAssetRepresentationMode = .current
-
-        let picker = PHPickerViewController(configuration: config)
+        var setup = PHPickerConfiguration(photoLibrary: .shared())
+        setup.filter = .images
+        setup.selectionLimit = limit
+        setup.preferredAssetRepresentationMode = .current
+        let picker = PHPickerViewController(configuration: setup)
         picker.delegate = context.coordinator
         return picker
     }
 
-    func updateUIViewController(_ uiViewController: PHPickerViewController, context: Context) {
-        // Configuration is immutable after creation
-    }
+    func updateUIViewController(_ controller: PHPickerViewController, context: Context) {}
 
-    final class Coordinator: NSObject, PHPickerViewControllerDelegate {
-        let parent: PHPickerWrapper
+    func makeCoordinator() -> Coordinator { Coordinator(owner: self) }
 
-        init(_ parent: PHPickerWrapper) { self.parent = parent }
-
-        func picker(
-            _ picker: PHPickerViewController,
-            didFinishPicking results: [PHPickerResult]
-        ) {
-            parent.dismiss()
-            guard !results.isEmpty else { return }
+    final class Coordinator: NSObject, PHPickerViewControllerDelegate {
+        let owner: LegacyGalleryPicker
+        init(owner: LegacyGalleryPicker) { self.owner = owner }
 
+        func picker(_ sheet: PHPickerViewController, didFinishPicking picks: [PHPickerResult]) {
+            sheet.dismiss(animated: true)
+            let providers = picks.map(\.itemProvider)
             Task { @MainActor in
                 var images: [UIImage] = []
-                for result in results {
-                    if let image = await loadImage(from: result.itemProvider) {
-                        images.append(image)
+                for provider in providers where provider.canLoadObject(ofClass: UIImage.self) {
+                    let image: UIImage? = await withCheckedContinuation { done in
+                        provider.loadObject(ofClass: UIImage.self) { object, _ in
+                            done.resume(returning: object as? UIImage)
+                        }
                     }
+                    if let image { images.append(image) }
                 }
-                parent.selectedImages = images
-            }
-        }
-
-        private func loadImage(from provider: NSItemProvider) async -> UIImage? {
-            await withCheckedContinuation { continuation in
-                if provider.canLoadObject(ofClass: UIImage.self) {
-                    provider.loadObject(ofClass: UIImage.self) { image, _ in
-                        continuation.resume(returning: image as? UIImage)
-                    }
-                } else {
-                    continuation.resume(returning: nil)
-                }
+                owner.chosen = images
             }
         }
     }
 }
 ```
 
-Always call `parent.dismiss()` in `picker(_:didFinishPicking:)` -- this delegate method fires for both selection and cancellation (with empty results).
+- A `selectionLimit` of 0 means the system maximum.
+- The configuration is fixed once the controller exists, which is why
+  `updateUIViewController` does nothing.
+- `picker(_:didFinishPicking:)` fires for Cancel too, with an empty array.
+  Dismiss the picker there in every case.
 
----
+## 6. Saving into the library
 
-## 6. Saving Images to Photo Library
-
-Saving requires `NSPhotoLibraryAddUsageDescription` in Info.plist. Use `PHPhotoLibrary` for saving with metadata, or `UIImageWriteToSavedPhotosAlbum` for simple saves.
-
-### Using PHPhotoLibrary (Preferred)
+Saving needs `NSPhotoLibraryAddUsageDescription`. Use `PHPhotoLibrary` when you
+want control over the stored data and metadata;
+`UIImageWriteToSavedPhotosAlbum` is enough for a quick one-off save.
 
 ```swift
 import Photos
 
-func saveImageToLibrary(_ image: UIImage) async throws {
-    try await PHPhotoLibrary.shared().performChanges {
-        let request = PHAssetCreationRequest.forAsset()
-        request.addResource(with: .photo, data: image.jpegData(compressionQuality: 0.9)!, options: nil)
+enum LibraryWriter {
+    static func store(_ image: UIImage) async throws {
+        guard let encoded = image.jpegData(compressionQuality: 0.9) else { return }
+        try await store(encoded)
     }
-}
 
-func saveImageDataToLibrary(_ data: Data) async throws {
-    try await PHPhotoLibrary.shared().performChanges {
-        let request = PHAssetCreationRequest.forAsset()
-        let options = PHAssetResourceCreationOptions()
-        request.addResource(with: .photo, data: data, options: options)
+    static func store(_ encoded: Data) async throws {
+        try await PHPhotoLibrary.shared().performChanges {
+            let request = PHAssetCreationRequest.forAsset()
+            request.addResource(with: .photo, data: encoded, options: PHAssetResourceCreationOptions())
+        }
     }
 }
 ```
 
-### Saving to a Specific Album
-
-```swift
-import Photos
-
-func saveToAlbum(image: UIImage, albumName: String) async throws {
-    let album = try await findOrCreateAlbum(named: albumName)
+### Into a named album
 
-    try await PHPhotoLibrary.shared().performChanges {
-        let assetRequest = PHAssetCreationRequest.forAsset()
-        assetRequest.addResource(
-            with: .photo,
-            data: image.jpegData(compressionQuality: 0.9)!,
-            options: nil
-        )
+Look the album up by title; if it is missing, create it and capture its
+placeholder, then add the new asset in the same change block. The fallback is an
+`if`, not `??`: the right side of `??` is an autoclosure and cannot `await`.
 
-        guard let placeholder = assetRequest.placeholderForCreatedAsset,
-              let albumChangeRequest = PHAssetCollectionChangeRequest(for: album) else { return }
-        albumChangeRequest.addAssets([placeholder] as NSArray)
-    }
-}
-
-private func findOrCreateAlbum(named name: String) async throws -> PHAssetCollection {
-    let fetchOptions = PHFetchOptions()
-    fetchOptions.predicate = NSPredicate(format: "title = %@", name)
-    let result = PHAssetCollection.fetchAssetCollections(with: .album, subtype: .any, options: fetchOptions)
+```swift
+enum AlbumWriter {
+    enum Failure: Error { case albumMissing }
 
-    if let existing = result.firstObject {
-        return existing
+    static func album(titled title: String) -> PHAssetCollection? {
+        let query = PHFetchOptions()
+        query.predicate = NSPredicate(format: "title = %@", title)
+        return PHAssetCollection.fetchAssetCollections(with: PHAssetCollectionType.album, subtype: .any, options: query).firstObject
     }
 
-    // Create the album
-    var placeholder: PHObjectPlaceholder?
-    try await PHPhotoLibrary.shared().performChanges {
-        let request = PHAssetCollectionChangeRequest.creationRequestForAssetCollection(withTitle: name)
-        placeholder = request.placeholderForCreatedAssetCollection
+    static func makeAlbum(titled title: String) async throws -> PHAssetCollection {
+        var marker: PHObjectPlaceholder?
+        try await PHPhotoLibrary.shared().performChanges {
+            let create = PHAssetCollectionChangeRequest.creationRequestForAssetCollection(withTitle: title)
+            marker = create.placeholderForCreatedAssetCollection
+        }
+        guard let id = marker?.localIdentifier,
+              let made = PHAssetCollection.fetchAssetCollections(withLocalIdentifiers: [id], options: nil).firstObject
+        else { throw Failure.albumMissing }
+        return made
     }
 
-    guard let placeholder,
-          let collection = PHAssetCollection.fetchAssetCollections(
-              withLocalIdentifiers: [placeholder.localIdentifier],
-              options: nil
-          ).firstObject else {
-        throw PhotoLibraryError.albumCreationFailed
+    static func save(_ encoded: Data, into title: String) async throws {
+        let target: PHAssetCollection
+        if let existing = album(titled: title) {
+            target = existing
+        } else {
+            target = try await makeAlbum(titled: title)
+        }
+        try await PHPhotoLibrary.shared().performChanges {
+            let request = PHAssetCreationRequest.forAsset()
+            request.addResource(with: .photo, data: encoded, options: nil)
+            guard let newAsset = request.placeholderForCreatedAsset,
+                  let edit = PHAssetCollectionChangeRequest(for: target) else { return }
+            edit.addAssets([newAsset] as NSArray)
+        }
     }
-
-    return collection
-}
-
-enum PhotoLibraryError: Error {
-    case albumCreationFailed
 }
 ```
 
----
+## 7. Thumbnails with ImageIO
 
-## 7. Thumbnail Generation with ImageIO Downsampling
-
-Generate thumbnails efficiently without decoding the full image into memory. This is critical for grids and lists displaying many photos.
+Build thumbnails without decoding the whole image; with a grid of hundreds of
+photos this matters more than anything else. `UIImage(data:)` followed by a
+resize still decodes the full bitmap first, so prefer downsampling. When the
+image is on disk, open it by URL with caching switched off so the file is not
+read into memory up front:
 
 ```swift
 import ImageIO
-import UIKit
-
-/// Downsample image data to a target display size.
-/// Use this instead of UIImage(data:) followed by resizing, which decodes the full image.
-func downsample(
-    data: Data,
-    to pointSize: CGSize,
-    scale: CGFloat = UITraitCollection.current.displayScale
-) -> UIImage? {
-    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)
-}
-
-/// Downsample from a file URL (avoids loading full data into memory).
-func downsample(
-    url: URL,
-    to pointSize: CGSize,
-    scale: CGFloat = UITraitCollection.current.displayScale
-) -> UIImage? {
-    let maxDimension = max(pointSize.width, pointSize.height) * scale
-
-    let sourceOptions: [CFString: Any] = [kCGImageSourceShouldCache: false]
-    guard let source = CGImageSourceCreateWithURL(url as CFURL, sourceOptions as CFDictionary) else {
-        return nil
-    }
-
-    let downsampleOptions: [CFString: Any] = [
+func fileThumbnail(at file: URL, longestPixelEdge: CGFloat) -> UIImage? {
+    let openOptions = [kCGImageSourceShouldCache: false] as CFDictionary
+    guard let reader = CGImageSourceCreateWithURL(file as CFURL, openOptions) else { return nil }
+    let shrink: [CFString: Any] = [
         kCGImageSourceCreateThumbnailFromImageAlways: true,
-        kCGImageSourceShouldCacheImmediately: true,
         kCGImageSourceCreateThumbnailWithTransform: true,
-        kCGImageSourceThumbnailMaxPixelSize: maxDimension
+        kCGImageSourceShouldCacheImmediately: true,
+        kCGImageSourceThumbnailMaxPixelSize: longestPixelEdge,
     ]
-
-    guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, downsampleOptions as CFDictionary) else {
-        return nil
-    }
-
-    return UIImage(cgImage: cgImage)
+    return CGImageSourceCreateThumbnailAtIndex(reader, 0, shrink as CFDictionary).map(UIImage.init(cgImage:))
 }
-```
-
-### Usage in a Photo Grid
 
-```swift
-struct PhotoGridItem: View {
-    let imageData: Data
-    let thumbnailSize = CGSize(width: 100, height: 100)
-
-    @State private var thumbnail: UIImage?
+struct GridCell: View {
+    let file: URL
+    @Environment(\.displayScale) private var scale
+    @State private var small: UIImage?
 
     var body: some View {
-        Group {
-            if let thumbnail {
-                Image(uiImage: thumbnail)
-                    .resizable()
-                    .scaledToFill()
-            } else {
-                Rectangle()
-                    .fill(.quaternary)
-                    .overlay(ProgressView())
+        Rectangle()
+            .fill(.quaternary)
+            .overlay {
+                if let small { Image(uiImage: small).resizable().scaledToFill() } else { ProgressView() }
             }
-        }
-        .frame(width: 100, height: 100)
-        .clipShape(.rect(cornerRadius: 6))
-        .task {
-            thumbnail = downsample(data: imageData, to: thumbnailSize)
-        }
+            .frame(width: 100, height: 100)
+            .clipShape(.rect(cornerRadius: 6))
+            .task { small = fileThumbnail(at: file, longestPixelEdge: 100 * scale) }
     }
 }
 ```
 
----
+## 8. HEIC and HEIF
 
-## 8. HEIC/HEIF Handling
-
-Modern iPhones capture photos in HEIC format by default. Handle both HEIC and JPEG transparently.
-
-### Checking Image Format
+Recent iPhones capture HEIC unless the user changed the setting, so code must
+accept HEIC and JPEG alike.
 
 ```swift
 import UniformTypeIdentifiers
 
-func imageContentType(data: Data) -> UTType? {
-    guard let source = CGImageSourceCreateWithData(data as CFData, nil),
-          let uti = CGImageSourceGetType(source) as? String else {
-        return nil
-    }
-    return UTType(uti)
+func detectedType(of bytes: Data) -> UTType? {
+    guard let reader = CGImageSourceCreateWithData(bytes as CFData, nil),
+          let identifier = CGImageSourceGetType(reader) else { return nil }
+    return UTType(identifier as String)
 }
-```
-
-### Converting HEIC to JPEG
-
-```swift
-import UIKit
 
-func convertToJPEG(heicData: Data, compressionQuality: CGFloat = 0.9) -> Data? {
-    guard let image = UIImage(data: heicData) else { return nil }
-    return image.jpegData(compressionQuality: compressionQuality)
+func jpegCopy(of heic: Data, quality: CGFloat = 0.9) -> Data? {
+    UIImage(data: heic)?.jpegData(compressionQuality: quality)
 }
 ```
 
-### Preserving HEIC When Possible
+- Keep HEIC when saving or uploading: better quality per byte. Convert only
+  when the receiver demands JPEG, such as a server that rejects HEIC.
+- On `PHPickerConfiguration`, `preferredAssetRepresentationMode = .current`
+  avoids transcoding and hands over the HEIC as stored. `.compatible` asks for
+  the most compatible representation and transcodes when needed, which for
+  HEIC photos usually means JPEG.
 
-When saving or uploading, prefer keeping the original HEIC format to preserve quality and reduce file size. Convert to JPEG only when the destination requires it (e.g., a server that rejects HEIC).
+## 9. Picker appearance
 
-```swift
-import PhotosUI
-
-// Request the current representation to avoid transcoding
-var config = PHPickerConfiguration(photoLibrary: .shared())
-config.preferredAssetRepresentationMode = .current  // Keeps HEIC as-is
-// vs .compatible which transcodes to JPEG
-```
-
----
-
-## 9. Custom PhotosPicker Appearance
-
-Customize the picker trigger with any SwiftUI view using the label closure:
+Any SwiftUI view can be the picker's label:
 
 ```swift
-PhotosPicker(selection: $selectedItems, maxSelectionCount: 3, matching: .images) {
-    Label("Add Photos", systemImage: "photo.on.rectangle.angled")
-        .font(.headline)
+PhotosPicker(selection: $picks, maxSelectionCount: 4, matching: .images) {
+    Label("Attach", systemImage: "photo.on.rectangle.angled")
         .padding()
-        .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 12))
+        .background(.ultraThinMaterial, in: .rect(cornerRadius: 12))
 }
 ```
 
-### Inline PhotosPicker (iOS 17+)
-
-Display the picker inline rather than as a sheet:
+iOS 17 adds presentation control:
 
 ```swift
-@available(iOS 17.0, *)
-PhotosPicker(
-    selection: $selectedItems,
-    maxSelectionCount: 5,
-    matching: .images
-)
-.photosPickerStyle(.inline)
-.frame(height: 300)
+PhotosPicker("Pick", selection: $picks, selectionBehavior: .continuous, matching: .images)
+    .photosPickerStyle(.inline)
+    .photosPickerAccessoryVisibility(.hidden, edges: .bottom)
+    .photosPickerDisabledCapabilities([.search, .collectionNavigation])
+    .frame(height: 300)
 ```
 
-### Photos Picker Access Behavior (iOS 17+)
+- `.photosPickerStyle(.inline)` embeds the picker in the layout instead of a
+  sheet; `.compact` gives a single row. Give an inline picker a fixed height.
+- `.continuous` selection reports changes as the person taps, which suits an
+  embedded picker.
+- Limited library access is not a picker modifier. With `.limited` status, let
+  the person revise the selection through
+  `PHPhotoLibrary.shared().presentLimitedLibraryPicker(from:)`, and set
+  `PHPhotoLibraryPreventAutomaticLimitedAccessAlert` in Info.plist if the app
+  offers its own entry point for that.
 
-Control how the picker interacts with limited library access:
+## 10. Cropping
 
-```swift
-@available(iOS 17.0, *)
-PhotosPicker(selection: $selectedItems, matching: .images)
-    .photosPickerAccessBehavior(.limited)  // Only show user-approved photos
-    // .automatic (default) -- system decides
-    // .limited -- only previously approved photos
-```
-
----
-
-## 10. Image Cropping Pattern
-
-A basic square crop using Core Graphics after selecting a photo:
+A centered square crop needs only Core Graphics:
 
 ```swift
-import UIKit
-
-func cropToSquare(_ image: UIImage) -> UIImage? {
-    guard let cgImage = image.cgImage else { return nil }
-
-    let side = min(cgImage.width, cgImage.height)
-    let x = (cgImage.width - side) / 2
-    let y = (cgImage.height - side) / 2
-    let cropRect = CGRect(x: x, y: y, width: side, height: side)
-
-    guard let cropped = cgImage.cropping(to: cropRect) else { return nil }
-    return UIImage(cgImage: cropped, scale: image.scale, orientation: image.imageOrientation)
+func centerSquare(of photo: UIImage) -> UIImage? {
+    guard let bitmap = photo.cgImage else { return nil }
+    let side = min(bitmap.width, bitmap.height)
+    let frame = CGRect(x: (bitmap.width - side) / 2, y: (bitmap.height - side) / 2, width: side, height: side)
+    guard let square = bitmap.cropping(to: frame) else { return nil }
+    return UIImage(cgImage: square, scale: photo.scale, orientation: photo.imageOrientation)
 }
 ```
 
-For interactive cropping, consider wrapping a third-party crop view or building a gesture-based crop overlay in SwiftUI. The system does not provide a built-in crop controller.
+The system offers no crop controller. Interactive cropping means wrapping a
+third-party view or building a drag-and-pinch overlay in SwiftUI yourself.