photos-library-editing-workflow

Photos Library and Editing Workflow

Purpose

Guide PhotosUI selection and PhotoKit library work while requesting the narrowest access, preserving typed asset/resource identity, and keeping image processing and video pipelines with their owning frameworks.

When To Use

• Use for PhotosPicker, PHPickerViewController, PHPhotoLibrary, assets, fetches, collections, image/resource requests, changes, creation, albums, or nondestructive editing.
• Prefer PhotosUI when the app only needs media the user explicitly selects.
• Use PhotoKit authorization only for concrete library read, add, observe, organize, or edit behavior.

Single-Path Workflow

1. Classify the request:
   • user-selected image/video through PhotosUI
   • add-only save
   • read/write or limited-library browse
   • asset/collection fetch and change observation
   • image, video, Live Photo, data, or resource request
   • iCloud-backed delivery, progress, cancellation, or caching
   • asset/album creation or transactional change
   • content-editing input/output and adjustment data
   • privacy, lifecycle, or correctness repair
2. Apply the Apple docs gate:
   • read current PhotosUI, PhotoKit, SwiftUI, and Core Transferable documentation for the platform
   • state the documented behavior relied on
   • check API/platform availability before making macOS, iOS, iPadOS, or visionOS claims
3. Choose the narrowest access:
   • use PhotosPicker or PHPickerViewController for explicit user selection when broad library access is unnecessary
   • use .addOnly when the app only saves into Photos
   • use .readWrite only for fetch, limited-library, organization, observation, or edit requirements
   • handle .notDetermined, .restricted, .denied, .authorized, and .limited distinctly
   • require .authorized, not merely .limited, before fetching, creating, or modifying user albums and provide a picker, selected-assets, or settings fallback when full-library organization is unavailable
4. Preserve typed identity and lifecycle:
   • keep PhotosPickerItem, PHPickerResult, PHAsset, PHAssetCollection, PHFetchResult, PHAssetResource, request IDs, placeholders, and adjustment data typed
   • attach asynchronous results to the current selection, asset local identifier, request ID, fetch result, or edit generation
   • cancel obsolete loads and ignore stale callbacks
5. Perform changes transactionally:
   • create PHAssetCreationRequest, asset/collection change requests, and placeholders only inside PHPhotoLibrary.performChanges
   • surface transaction errors and fetch created objects after commit when needed
6. Return documented behavior, picker-versus-library decision, authorization/purpose-string policy, asset/resource identity, request/cancellation and iCloud policy, transactional/editing plan, diagnostics, validation, and handoffs.