photokit

What this skill does

# 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

- [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)

## 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.

### Single Selection

```swift
import SwiftUI
import PhotosUI

struct SinglePhotoPicker: View {
    @State private var selectedItem: PhotosPickerItem?
    @State private var selectedImage: Image?

    var body: some View {
        VStack {
            if let selectedImage {
                selectedImage
                    .resizable()
                    .scaledToFit()
                    .frame(maxHeight: 300)
            }

            PhotosPicker("Select Photo", selection: $selectedItem, matching: .images)
        }
        .onChange(of: selectedItem) { _, newItem in
            Task {
                if let data = try? await newItem?.loadTransferable(type: Data.self),
                   let uiImage = UIImage(data: data) {
                    selectedImage = Image(uiImage: uiImage)
                }
            }
        }
    }
}
```

### Multi-Selection

```swift
struct MultiPhotoPicker: View {
    @State private var selectedItems: [PhotosPickerItem] = []
    @State private var selectedImages: [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(
                "Select Photos",
                selection: $selectedItems,
                maxSelectionCount: 5,
                matching: .images
            )
        }
        .onChange(of: selectedItems) { _, newItems 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))
                    }
                }
            }
        }
    }
}
```

### Media Type Filtering

Filter with `PHPickerFilter` composites to restrict selectable media:

```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]))

// Images excluding screenshots
PhotosPicker(selection: $items, matching: .all(of: [.images, .not(.screenshots)]))
```

### Loading Selected Items with Transferable

`PhotosPickerItem` loads content asynchronously via `loadTransferable(type:)`. Define a `Transferable` type for automatic decoding:

```swift
struct PickedImage: Transferable {
    let data: Data
    let image: 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))
        }
    }
}

enum TransferError: Error {
    case importFailed
}

// Usage
if let picked = try? await item.loadTransferable(type: PickedImage.self) {
    selectedImage = picked.image
}
```

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

### Photo Library Access Levels

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.

| 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` |

`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

```swift
import Photos

func requestPhotoLibraryAccess() async -> PHAuthorizationStatus {
    let status = PHPhotoLibrary.authorizationStatus(for: .readWrite)

    switch status {
    case .notDetermined:
        return await PHPhotoLibrary.requestAuthorization(for: .readWrite)
    case .authorized, .limited:
        return status
    case .denied, .restricted:
        return status
    @unknown default:
        return status
    }
}
```

### Camera Permission

Add `NSCameraUsageDescription` to Info.plist. Check and request access before configuring a capture session:

```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
    }
}
```

### Handling Denied Permissions

When the user denies access, guide them to Settings. Never repeatedly prompt or hide functionality silently.

```swift
struct PermissionDeniedView: View {
    let message: String
    @Environment(\.openURL) private var openURL

    var body: some View {
        ContentUnavailableView {
            Label("Access Denied", systemImage: "lock.shield")
        } description: {
            Text(message)
        } actions: {
            Button("Open Settings") {
                if let url = URL(string: UIApplication.openSettingsURLString) {
                    openURL(url)
                }
            }
        }
    }
}
```

### 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) |

Omitting a required key causes a runtime crash when the permission dialog would appear.

## Camera Capture Basics

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.

### Minimal Camera Manager

```swift
import AVFoundation

@available(iOS 17.0, *)
@Observable
@MainActor
final class CameraManager {
    let session = AVCaptu