@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/photos-camera-media/SKILL.md

@@ -1,95 +1,84 @@
 ---
 name: photos-camera-media
-description: "Implement, review, or improve photo picking, camera capture, and media handling in iOS apps using PhotoKit and AVFoundation. Use when working with PhotosPicker, PHPickerViewController, camera capture sessions (AVCaptureSession), photo library access, image loading and display, video recording, or media permissions. Also use when selecting photos from the library, taking pictures, recording video, processing images, or handling photo/camera privacy permissions in Swift apps."
+description: "PhotoKit and AVFoundation media on iOS: PhotosPicker and PHPickerViewController, Transferable loading of images, movies and Live Photos, photo library and camera permissions, saving to the library, AVCaptureSession photo capture and video recording, image loading, downsampling, caching and display, AVPlayer playback. Use when implementing, reviewing or improving photo picking, camera capture, video recording, image processing or media permissions in Swift."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# PhotoKit
-
-Modern patterns for photo picking, camera capture, image loading, and media permissions targeting iOS 26+ with Swift 6.3. Patterns are backward-compatible to iOS 16 unless noted. See [references/photokit-patterns.md](references/photokit-patterns.md) for complete picker recipes and [references/camera-capture.md](references/camera-capture.md) for AVCaptureSession patterns.
 
-## Contents
+# PhotoKit
 
-- [PhotosPicker (SwiftUI, iOS 16+)](#photospicker-swiftui-ios-16)
-- [Privacy and Permissions](#privacy-and-permissions)
-- [Camera Capture Basics](#camera-capture-basics)
-- [Image Loading and Display](#image-loading-and-display)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Written for iOS 26 and Swift 6.3. The samples need iOS 17 or later: they use
+the two-parameter `onChange(of:)`, `@Observable` and `ContentUnavailableView`.
+Where the framework API itself is older, the heading says so. Longer
+recipes live in two companion files: [picker recipes](references/photokit-patterns.md) and
+[capture session recipes](references/camera-capture.md).
 
-## PhotosPicker (SwiftUI, iOS 16+)
+## Picking with PhotosPicker (SwiftUI, iOS 16+)
 
-`PhotosPicker` is the native SwiftUI replacement for `UIImagePickerController`. It runs out-of-process, requires no photo library permission for browsing, and supports single or multi-selection with media type filtering.
+`PhotosPicker` replaces `UIImagePickerController` for choosing library items in
+SwiftUI. The picker UI runs in a separate process, so the app can browse
+without any photo library permission and only ever receives what the person
+selected. It handles one item or many and can filter by media type.
 
-### Single Selection
+### One item
 
 ```swift
 import SwiftUI
 import PhotosUI
 
-struct SinglePhotoPicker: View {
-    @State private var selectedItem: PhotosPickerItem?
-    @State private var selectedImage: Image?
+struct CoverPhotoField: View {
+    @State private var pick: PhotosPickerItem?
+    @State private var cover: Image?
 
     var body: some View {
         VStack {
-            if let selectedImage {
-                selectedImage
-                    .resizable()
-                    .scaledToFit()
-                    .frame(maxHeight: 300)
-            }
-
-            PhotosPicker("Select Photo", selection: $selectedItem, matching: .images)
+            cover?
+                .resizable()
+                .scaledToFit()
+                .frame(maxHeight: 300)
+            PhotosPicker("Choose Cover", selection: $pick, matching: .images)
         }
-        .onChange(of: selectedItem) { _, newItem in
+        .onChange(of: pick) { _, item in
             Task {
-                if let data = try? await newItem?.loadTransferable(type: Data.self),
-                   let uiImage = UIImage(data: data) {
-                    selectedImage = Image(uiImage: uiImage)
-                }
+                guard let chosen = item,
+                      let bytes = try? await chosen.loadTransferable(type: Data.self),
+                      let decoded = UIImage(data: bytes) else { return }
+                cover = Image(uiImage: decoded)
             }
         }
     }
 }
 ```
 
-### Multi-Selection
+### Several items
+
+Bind `selection` to an array and cap it with `maxSelectionCount`:
 
 ```swift
-struct MultiPhotoPicker: View {
-    @State private var selectedItems: [PhotosPickerItem] = []
-    @State private var selectedImages: [Image] = []
+struct MoodBoardPicker: View {
+    @State private var picks: [PhotosPickerItem] = []
+    @State private var tiles: [Image] = []
 
     var body: some View {
-        VStack {
-            ScrollView(.horizontal) {
-                HStack {
-                    ForEach(selectedImages.indices, id: \.self) { index in
-                        selectedImages[index]
-                            .resizable()
-                            .scaledToFill()
-                            .frame(width: 100, height: 100)
-                            .clipShape(.rect(cornerRadius: 8))
-                    }
+        PhotosPicker("Add Photos", selection: $picks, maxSelectionCount: 5, matching: .images)
+        ScrollView(.horizontal) {
+            HStack {
+                ForEach(tiles.indices, id: \.self) { index in
+                    tiles[index]
+                        .resizable()
+                        .scaledToFill()
+                        .frame(width: 100, height: 100)
+                        .clipShape(.rect(cornerRadius: 8))
                 }
             }
-
-            PhotosPicker(
-                "Select Photos",
-                selection: $selectedItems,
-                maxSelectionCount: 5,
-                matching: .images
-            )
         }
-        .onChange(of: selectedItems) { _, newItems in
+        .onChange(of: picks) { _, items in
             Task {
-                selectedImages = []
-                for item in newItems {
-                    if let data = try? await item.loadTransferable(type: Data.self),
-                       let uiImage = UIImage(data: data) {
-                        selectedImages.append(Image(uiImage: uiImage))
+                tiles.removeAll()
+                for entry in items {
+                    if let bytes = try? await entry.loadTransferable(type: Data.self),
+                       let decoded = UIImage(data: bytes) {
+                        tiles.append(Image(uiImage: decoded))
                     }
                 }
             }
@@ -98,136 +87,125 @@ struct MultiPhotoPicker: View {
 }
 ```
 
-### Media Type Filtering
+### Filtering by media type
 
-Filter with `PHPickerFilter` composites to restrict selectable media:
+`matching:` takes a `PHPickerFilter`:
 
-```swift
-// Images only
-PhotosPicker(selection: $items, matching: .images)
-
-// Videos only
-PhotosPicker(selection: $items, matching: .videos)
-
-// Live Photos only
-PhotosPicker(selection: $items, matching: .livePhotos)
-
-// Screenshots only
-PhotosPicker(selection: $items, matching: .screenshots)
-
-// Images and videos combined
-PhotosPicker(selection: $items, matching: .any(of: [.images, .videos]))
+| Filter | Shows |
+|---|---|
+| `.images` | still images only |
+| `.videos` | videos only |
+| `.livePhotos` | Live Photos only |
+| `.screenshots` | screenshots only |
+| `.any(of: [.images, .videos])` | either kind (logical OR) |
+| `.all(of: [.images, .not(.screenshots)])` | images that are not screenshots (AND plus negation) |
 
-// Images excluding screenshots
-PhotosPicker(selection: $items, matching: .all(of: [.images, .not(.screenshots)]))
-```
-
-### Loading Selected Items with Transferable
+### Decoding through Transferable
 
-`PhotosPickerItem` loads content asynchronously via `loadTransferable(type:)`. Define a `Transferable` type for automatic decoding:
+A `PhotosPickerItem` hands over its content asynchronously via
+`loadTransferable(type:)`. A custom `Transferable` type moves the decode step
+into the type itself:
 
 ```swift
-struct PickedImage: Transferable {
-    let data: Data
-    let image: Image
+import CoreTransferable
+import UniformTypeIdentifiers
+
+struct ScannedPage: Transferable {
+    enum DecodeFailure: Error { case notAnImage }
+    let bytes: Data
+    let preview: Image
 
     static var transferRepresentation: some TransferRepresentation {
-        DataRepresentation(importedContentType: .image) { data in
-            guard let uiImage = UIImage(data: data) else {
-                throw TransferError.importFailed
-            }
-            return PickedImage(data: data, image: Image(uiImage: uiImage))
+        DataRepresentation(importedContentType: .image) { bytes in
+            guard let decoded = UIImage(data: bytes) else { throw DecodeFailure.notAnImage }
+            return ScannedPage(bytes: bytes, preview: Image(uiImage: decoded))
         }
     }
 }
 
-enum TransferError: Error {
-    case importFailed
-}
-
-// Usage
-if let picked = try? await item.loadTransferable(type: PickedImage.self) {
-    selectedImage = picked.image
-}
+// let page = try? await item.loadTransferable(type: ScannedPage.self)
 ```
 
-Always load in a `Task` to avoid blocking the main thread. Handle `nil` returns and thrown errors -- the user may select a format that cannot be decoded.
-
-## Privacy and Permissions
+- Run the load inside a `Task`; never wait for it on the main thread.
+- Expect both a `nil` result and a thrown error. People can pick formats that
+  fail to decode.
 
-### Photo Library Access Levels
+## Privacy and permissions
 
-iOS provides two access levels for the photo library. The system automatically presents the limited-library picker when an app requests `.readWrite` access -- users choose which photos to share.
+### Library access levels
 
-| Access Level | Description | Info.plist Key |
-|-------------|-------------|----------------|
-| Add-only | Write photos to the library without reading | `NSPhotoLibraryAddUsageDescription` |
-| Read-write | Full or limited read access plus write | `NSPhotoLibraryUsageDescription` |
+| Level | What the app may do | Info.plist key |
+|---|---|---|
+| Add-only | write new items, never read | `NSPhotoLibraryAddUsageDescription` |
+| Read-write | read everything or a limited subset, and write | `NSPhotoLibraryUsageDescription` |
 
-`PhotosPicker` requires no permission to browse -- it runs out-of-process and only grants access to selected items. Request explicit permission only when you need to read the full library (e.g., a custom gallery) or save photos.
-
-### Checking and Requesting Photo Library Permission
+Asking for `.readWrite` lets the system offer its limited-library picker, where
+the person decides which photos the app sees. `PhotosPicker` needs no grant at
+all and exposes only the chosen items. Ask for library access only when the app
+reads the whole library (a custom gallery, for example) or saves into it.
 
 ```swift
 import Photos
 
-func requestPhotoLibraryAccess() async -> PHAuthorizationStatus {
-    let status = PHPhotoLibrary.authorizationStatus(for: .readWrite)
+func libraryAccess() async -> PHAuthorizationStatus {
+    let current = PHPhotoLibrary.authorizationStatus(for: .readWrite)
+    guard current == .notDetermined else { return current }
+    let answer = await PHPhotoLibrary.requestAuthorization(for: .readWrite)
+    return answer
+}
 
+func canBrowseGallery(_ status: PHAuthorizationStatus) -> Bool {
     switch status {
-    case .notDetermined:
-        return await PHPhotoLibrary.requestAuthorization(for: .readWrite)
-    case .authorized, .limited:
-        return status
-    case .denied, .restricted:
-        return status
-    @unknown default:
-        return status
+    case .authorized, .limited: true
+    case .denied, .restricted, .notDetermined: false
+    @unknown default: false
     }
 }
 ```
 
-### Camera Permission
+### Camera access
 
-Add `NSCameraUsageDescription` to Info.plist. Check and request access before configuring a capture session:
+The camera needs `NSCameraUsageDescription`. Check, and request if needed,
+before any capture session is configured:
 
 ```swift
 import AVFoundation
 
-func requestCameraAccess() async -> Bool {
-    let status = AVCaptureDevice.authorizationStatus(for: .video)
-
-    switch status {
-    case .notDetermined:
-        return await AVCaptureDevice.requestAccess(for: .video)
-    case .authorized:
-        return true
-    case .denied, .restricted:
-        return false
-    @unknown default:
-        return false
+enum CameraAccess {
+    static func isGranted() async -> Bool {
+        switch AVCaptureDevice.authorizationStatus(for: .video) {
+        case .authorized:
+            return true
+        case .notDetermined:
+            let allowed = await AVCaptureDevice.requestAccess(for: .video)
+            return allowed
+        case .denied, .restricted:
+            return false
+        @unknown default:
+            return false
+        }
     }
 }
 ```
 
-### Handling Denied Permissions
+### When the answer is no
 
-When the user denies access, guide them to Settings. Never repeatedly prompt or hide functionality silently.
+Send the person to Settings. Do not keep re-prompting and do not quietly drop
+the feature.
 
 ```swift
-struct PermissionDeniedView: View {
-    let message: String
+struct CameraBlockedView: View {
     @Environment(\.openURL) private var openURL
 
     var body: some View {
         ContentUnavailableView {
-            Label("Access Denied", systemImage: "lock.shield")
+            Label("Camera Is Off", systemImage: "lock.shield")
         } description: {
-            Text(message)
+            Text("Allow camera access in Settings to scan receipts.")
         } actions: {
             Button("Open Settings") {
-                if let url = URL(string: UIApplication.openSettingsURLString) {
-                    openURL(url)
+                if let target = URL(string: UIApplication.openSettingsURLString) {
+                    openURL(target)
                 }
             }
         }
@@ -235,266 +213,239 @@ struct PermissionDeniedView: View {
 }
 ```
 
-### Required Info.plist Keys
-
-| Key | When Required |
-|-----|--------------|
-| `NSPhotoLibraryUsageDescription` | Reading photos from the library |
-| `NSPhotoLibraryAddUsageDescription` | Saving photos/videos to the library |
-| `NSCameraUsageDescription` | Accessing the camera |
-| `NSMicrophoneUsageDescription` | Recording audio (video with sound) |
+### Usage strings
 
-Omitting a required key causes a runtime crash when the permission dialog would appear.
+| Key | Needed for |
+|---|---|
+| `NSPhotoLibraryUsageDescription` | reading existing library assets |
+| `NSPhotoLibraryAddUsageDescription` | saving photos or videos into the library |
+| `NSCameraUsageDescription` | any camera use |
+| `NSMicrophoneUsageDescription` | recording audio, including video with sound |
 
-## Camera Capture Basics
+A missing key is not a warning: the app crashes at the moment the system would
+have shown the prompt.
 
-Manage camera sessions in a dedicated `@Observable` model. The representable view only displays the preview. See [references/camera-capture.md](references/camera-capture.md) for complete patterns.
+## Camera capture basics
 
-### Minimal Camera Manager
+Put the `AVCaptureSession` in its own `@Observable` model. The representable
+view only draws the preview. The session itself is not `Sendable`, and
+`startRunning()` / `stopRunning()` are synchronous calls that block until the
+hardware settles, so all session work runs on one private serial queue that
+the model calls into.
 
 ```swift
 import AVFoundation
+import Observation
 
-@available(iOS 17.0, *)
-@Observable
-@MainActor
-final class CameraManager {
+final class CaptureEngine: @unchecked Sendable {
     let session = AVCaptureSession()
-    private let photoOutput = AVCapturePhotoOutput()
-    private var currentDevice: AVCaptureDevice?
-
-    var isRunning = false
-    var capturedImage: Data?
+    private let stills = AVCapturePhotoOutput()
+    private let queue = DispatchQueue(label: "capture.engine")
 
-    func configure() async {
-        guard await requestCameraAccess() else { return }
+    func run<T: Sendable>(_ work: @escaping @Sendable () -> T) async -> T {
+        await withCheckedContinuation { done in
+            queue.async { done.resume(returning: work()) }
+        }
+    }
 
+    func buildStillGraph() -> Bool {
         session.beginConfiguration()
+        defer { session.commitConfiguration() }
         session.sessionPreset = .photo
-
-        // Add camera input
-        guard let device = AVCaptureDevice.default(.builtInWideAngleCamera,
-                                                    for: .video,
-                                                    position: .back) else { return }
-        currentDevice = device
-
-        guard let input = try? AVCaptureDeviceInput(device: device),
-              session.canAddInput(input) else { return }
+        let wide = AVCaptureDevice.DeviceType.builtInWideAngleCamera
+        guard let rear = AVCaptureDevice.default(wide, for: .video, position: .back),
+              let input = try? AVCaptureDeviceInput(device: rear),
+              session.canAddInput(input) else { return false }
         session.addInput(input)
+        guard session.canAddOutput(stills) else { return false }
+        session.addOutput(stills)
+        return true
+    }
+}
 
-        // Add photo output
-        guard session.canAddOutput(photoOutput) else { return }
-        session.addOutput(photoOutput)
+@available(iOS 17.0, *)
+@Observable @MainActor
+final class ReceiptCamera {
+    private(set) var isRunning = false
+    @ObservationIgnored private let engine = CaptureEngine()
+    var session: AVCaptureSession { engine.session }
 
-        session.commitConfiguration()
+    func configure() async {
+        guard await CameraAccess.isGranted() else { return }
+        _ = await engine.run { [engine] in engine.buildStillGraph() }
     }
 
-    func start() {
-        guard !session.isRunning else { return }
-        Task.detached { [session] in
-            session.startRunning()
-        }
+    func start() async {
+        guard !isRunning else { return }
+        await engine.run { [engine] in engine.session.startRunning() }
         isRunning = true
     }
 
-    func stop() {
-        guard session.isRunning else { return }
-        Task.detached { [session] in
-            session.stopRunning()
-        }
+    func stop() async {
+        guard isRunning else { return }
+        await engine.run { [engine] in engine.session.stopRunning() }
         isRunning = false
     }
-
-    private func requestCameraAccess() async -> Bool {
-        let status = AVCaptureDevice.authorizationStatus(for: .video)
-        if status == .notDetermined {
-            return await AVCaptureDevice.requestAccess(for: .video)
-        }
-        return status == .authorized
-    }
 }
 ```
 
-Start and stop `AVCaptureSession` on a background queue. The `startRunning()` and `stopRunning()` methods are synchronous and block the calling thread.
-
-### Camera Preview in SwiftUI
+Keep every configuration change between `beginConfiguration()` and
+`commitConfiguration()`, and guard each `addInput` / `addOutput` with the
+matching `canAdd` check.
 
-Wrap `AVCaptureVideoPreviewLayer` in a `UIViewRepresentable`. Override `layerClass` for automatic resizing:
+### Preview layer in SwiftUI
 
 ```swift
-import SwiftUI
-import AVFoundation
-
-struct CameraPreview: UIViewRepresentable {
+struct ViewfinderView: UIViewRepresentable {
     let session: AVCaptureSession
 
-    func makeUIView(context: Context) -> PreviewView {
-        let view = PreviewView()
-        view.previewLayer.session = session
-        view.previewLayer.videoGravity = .resizeAspectFill
-        return view
+    final class LayerHost: UIView {
+        override static var layerClass: AnyClass { AVCaptureVideoPreviewLayer.self }
+        var preview: AVCaptureVideoPreviewLayer { unsafeDowncast(layer, to: AVCaptureVideoPreviewLayer.self) }
     }
 
-    func updateUIView(_ uiView: PreviewView, context: Context) {
-        if uiView.previewLayer.session !== session {
-            uiView.previewLayer.session = session
-        }
+    func makeUIView(context: Context) -> LayerHost {
+        let host = LayerHost()
+        host.preview.session = session
+        host.preview.videoGravity = .resizeAspectFill
+        return host
     }
-}
 
-final class PreviewView: UIView {
-    override class var layerClass: AnyClass { AVCaptureVideoPreviewLayer.self }
-    var previewLayer: AVCaptureVideoPreviewLayer { layer as! AVCaptureVideoPreviewLayer }
+    func updateUIView(_ host: LayerHost, context: Context) {
+        if host.preview.session !== session { host.preview.session = session }
+    }
 }
 ```
 
-### Using the Camera in a View
+Overriding `layerClass` makes the preview layer the view's backing layer, so
+it follows the view's size with no manual frame code.
+
+### A capture screen
 
 ```swift
-struct CameraScreen: View {
-    @State private var cameraManager = CameraManager()
+@available(iOS 17.0, *)
+struct ReceiptCaptureScreen: View {
+    @State private var camera = ReceiptCamera()
 
     var body: some View {
         ZStack(alignment: .bottom) {
-            CameraPreview(session: cameraManager.session)
-                .ignoresSafeArea()
-
+            ViewfinderView(session: camera.session).ignoresSafeArea()
             Button {
-                // Capture photo -- see references/camera-capture.md
+                // capture, see references/camera-capture.md
             } label: {
                 Circle()
                     .fill(.white)
                     .frame(width: 72, height: 72)
-                    .overlay(Circle().stroke(.gray, lineWidth: 3))
+                    .overlay { Circle().strokeBorder(.gray, lineWidth: 3) }
             }
-            .padding(.bottom)
+            .padding(.bottom, 32)
         }
         .task {
-            await cameraManager.configure()
-            cameraManager.start()
-        }
-        .onDisappear {
-            cameraManager.stop()
+            await camera.configure()
+            await camera.start()
         }
+        .onDisappear { Task { await camera.stop() } }
     }
 }
 ```
 
-Always call `stop()` in `onDisappear`. A running capture session holds the camera exclusively and drains battery.
+Always stop the session when the screen goes away. A running session keeps the
+camera to itself and burns battery.
 
-## Image Loading and Display
+## Loading and showing images
 
-### AsyncImage for Remote Images
+### Remote images with AsyncImage
 
 ```swift
-AsyncImage(url: imageURL) { phase in
+AsyncImage(url: posterURL) { phase in
     switch phase {
-    case .empty:
-        ProgressView()
-    case .success(let image):
-        image
-            .resizable()
-            .scaledToFill()
-    case .failure:
-        Image(systemName: "photo")
-            .foregroundStyle(.secondary)
-    @unknown default:
-        EmptyView()
+    case .empty: ProgressView()
+    case .success(let poster): poster.resizable().scaledToFit()
+    case .failure: Image(systemName: "photo")
+    @unknown default: EmptyView()
     }
 }
-.frame(width: 200, height: 200)
-.clipShape(.rect(cornerRadius: 12))
 ```
 
-`AsyncImage` does not cache images across view redraws. For production apps with many images, use a dedicated image loading library or `URLCache`-based caching.
+`AsyncImage` keeps no cache between redraws. An app that shows many remote
+images needs a real loader or `URLCache`-backed caching; the
+[loading and caching guide](references/image-loading-caching.md) builds one.
 
-### Downsampling Large Images
+### Downsample before display
 
-Load full-resolution photos from the library into a display-sized `CGImage` to avoid memory spikes. A 48MP photo can consume over 200 MB uncompressed.
+Decode library photos straight to the size they will be drawn at. A 48 MP
+photo takes more than 200 MB once decoded.
 
 ```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] = [
+func thumbnail(from bytes: Data, fitting points: CGSize, scale: CGFloat) -> UIImage? {
+    let longestEdge = max(points.width, points.height) * scale
+    guard let reader = CGImageSourceCreateWithData(bytes as CFData, nil) else { return nil }
+    let opts: [CFString: Any] = [
+        kCGImageSourceThumbnailMaxPixelSize: longestEdge,
+        kCGImageSourceCreateThumbnailWithTransform: true,
         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)
+    let scaled = CGImageSourceCreateThumbnailAtIndex(reader, 0, opts as CFDictionary)
+    return scaled.map { UIImage(cgImage: $0) }
 }
 ```
 
-Use this whenever displaying user-selected photos in lists, grids, or thumbnails. Pass the raw `Data` from `PhotosPickerItem` directly to the downsampler before creating a `UIImage`.
-
-### Image Rendering Modes
-
-```swift
-// Original: display the image as-is with its original colors
-Image("photo")
-    .renderingMode(.original)
-
-// Template: treat the image as a mask, colored by foregroundStyle
-Image(systemName: "heart.fill")
-    .renderingMode(.template)
-    .foregroundStyle(.red)
-```
-
-Use `.original` for photos and artwork. Use `.template` for icons that should adopt the current tint color.
-
-## Common Mistakes
-
-**DON'T:** Use `UIImagePickerController` for photo picking.
-**DO:** Use `PhotosPicker` (SwiftUI) or `PHPickerViewController` (UIKit).
-*Why:* `UIImagePickerController` is legacy API with limited functionality. `PhotosPicker` runs out-of-process, supports multi-selection, and requires no library permission for browsing.
-
-**DON'T:** Request full photo library access when you only need the user to pick photos.
-**DO:** Use `PhotosPicker` which requires no permission, or request `.readWrite` and let the system handle limited access.
-*Why:* Full access is unnecessary for most pick-and-use workflows. The system's limited-library picker respects user privacy and still grants access to selected items.
-
-**DON'T:** Load full-resolution images into memory for thumbnails.
-**DO:** Use `CGImageSource` with `kCGImageSourceThumbnailMaxPixelSize` to downsample. A 48MP image is over 200 MB uncompressed.
-
-**DON'T:** Block the main thread loading `PhotosPickerItem` data.
-**DO:** Use `async loadTransferable(type:)` in a `Task`.
-
-**DON'T:** Forget to stop `AVCaptureSession` when the view disappears.
-**DO:** Call `session.stopRunning()` in `onDisappear` or `dismantleUIView`.
-
-**DON'T:** Assume camera access is granted without checking.
-**DO:** Check `AVCaptureDevice.authorizationStatus(for: .video)` and handle `.denied`/`.restricted`.
-
-**DON'T:** Call `session.startRunning()` on the main thread.
-**DO:** Dispatch to a background thread with `Task.detached` or a dedicated serial queue.
-*Why:* `startRunning()` is a synchronous blocking call that can take hundreds of milliseconds while the hardware initializes.
-
-**DON'T:** Create `AVCaptureSession` inside a `UIViewRepresentable`.
-**DO:** Own the session in a separate `@Observable` model.
-
-## Review Checklist
-
-- [ ] `PhotosPicker` used instead of deprecated `UIImagePickerController`
-- [ ] Privacy descriptions in Info.plist for camera/photo library
-- [ ] Loading states handled for async image/video loading
-- [ ] Large images downsampled with `CGImageSource` before display
-- [ ] Camera session started on background thread; stopped in `onDisappear`
-- [ ] Permission denial handled with Settings deep link
-- [ ] `AVCaptureSession` owned by model, not created inside `UIViewRepresentable`
-- [ ] Media asset types and picker results are `Sendable` across concurrency boundaries
+Pass the screen scale in (`UITraitCollection.current.displayScale` or the
+SwiftUI `displayScale` environment value). Use this for every list, grid or
+thumbnail of picked photos, and feed the raw `Data` from `PhotosPickerItem`
+directly into it before any `UIImage` exists.
+
+### Rendering modes
+
+- `.renderingMode(.original)` keeps the image's own colors. Use it for photos
+  and artwork.
+- `.renderingMode(.template)` turns the image into a mask filled with the
+  current `foregroundStyle`. Use it for icons that should follow the tint.
+
+## Common mistakes
+
+1. Picking through `UIImagePickerController`. Its library source is legacy and
+   limited; `PhotosPicker` (SwiftUI) or `PHPickerViewController` (UIKit) runs
+   out of process, supports multi-select and needs no permission to browse.
+2. Asking for full library access just so someone can pick a photo. Use
+   `PhotosPicker`, or ask for `.readWrite` so the system can offer limited access.
+   Pick-and-use never needs the whole library.
+3. Decoding full-size images for thumbnails. Downsample with `CGImageSource`
+   and `kCGImageSourceThumbnailMaxPixelSize`.
+4. Loading `PhotosPickerItem` data on the main thread. Call the async
+   `loadTransferable(type:)` inside a `Task`.
+5. Leaving the `AVCaptureSession` running after the view leaves. Stop it in
+   `onDisappear` or `dismantleUIView`.
+6. Assuming the camera is authorized. Read the current video authorization
+   status first; `.denied` and `.restricted` both need a path.
+7. Calling `startRunning()` on the main thread. It blocks for hundreds of
+   milliseconds while the hardware starts; run it on a dedicated serial queue.
+8. Creating the session inside a `UIViewRepresentable`. Own it in an
+   `@Observable` model.
+
+## Review checklist
+
+- [ ] `PhotosPicker` or `PHPickerViewController` is used, not the legacy
+      `UIImagePickerController` library picker
+- [ ] Camera and photo library usage strings are in Info.plist
+- [ ] Async image and video loads show a loading state
+- [ ] Large images go through `CGImageSource` downsampling before display
+- [ ] The capture session starts off the main thread and stops in `onDisappear`
+- [ ] Denied permission leads to a Settings link
+- [ ] The capture session belongs to a model, not to a `UIViewRepresentable`
+- [ ] Media values and picker results that cross concurrency boundaries are
+      `Sendable`
 
 ## References
 
-- [references/photokit-patterns.md](references/photokit-patterns.md)  -  Picker patterns, media loading, HEIC handling
-- [references/camera-capture.md](references/camera-capture.md)  -  AVCaptureSession, photo/video capture, QR scanning
-- [references/image-loading-caching.md](references/image-loading-caching.md)  -  AsyncImage, caching, downsampling
-- [references/av-playback.md](references/av-playback.md)  -  AVPlayer, streaming, audio
+- [Picker recipes](references/photokit-patterns.md): loading states, video and
+  Live Photos, saving, HEIC
+- [Capture recipes](references/camera-capture.md): the full capture model,
+  stills and movies, barcode and QR scanning
+- [Loading and caching](references/image-loading-caching.md): the
+  AsyncImage limits, memory and disk caches, downsampling
+- [Playback](references/av-playback.md): the audio session, HLS streaming,
+  AVPlayer