Guide privacy-preserving PhotosUI media selection and PhotoKit authorization, limited-library access, assets, collections, fetches, change observation, image/video requests, caching, iCloud delivery, asset resources, creation transactions, albums, content editing, adjustment data, nondestructive edits, cancellation, and diagnostics. Use when selecting user media or reading, saving, observing, organizing, exporting, or editing the Apple Photos library.
Guide privacy-preserving PhotosUI media selection and PhotoKit authorization, limited-library access, assets, collections, fetches, change observation, image/video requests, caching, iCloud delivery, asset resources, creation transactions, albums, content editing, adjustment data, nondestructive edits, cancellation, and diagnostics. Use when selecting user media or reading, saving, observing, organizing, exporting, or editing the Apple Photos library.
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
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
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
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
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
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
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.
Inputs
request: Photos selection, library, resource, save, or edit task.
photos_goal: pick, add, browse, fetch, observe, request, resource, create, album, edit, or repair.
platform_context: Apple platform, deployment target, UI framework, and Photos availability.
privacy_context: required access level, user explanation, metadata policy, network/iCloud policy, retention, and export behavior.
Outputs
status: success, handoff, or blocked.
path_type: primary for PhotosUI/PhotoKit, fallback for image decode/process, video, UI architecture, or execution.
Do not request PhotoKit read/write authorization when a system picker or add-only access fulfills the feature.
Do not treat .limited as fully authorized or as denial; operate on the visible library and provide the documented management path when appropriate.
Do not promise album browsing or organization under .limited; require full .authorized read/write access before fetching, creating, renaming, deleting, or changing user albums.
Do not mirror the entire library into app-owned state or introduce a Photos repository when PHFetchResult, local identifiers, change details, and picker bindings express the requirement.
Do not assume a picker item, asset, or resource is local; model iCloud/network delivery, progress, cancellation, and failure explicitly.
Do not treat degraded or opportunistic image callbacks as final, and do not let stale request callbacks overwrite a newer selection.
Do not silently substitute adjusted content for original resources, flatten Live Photos, discard RAW/paired resources, or copy metadata without an explicit policy.
Do not claim a library change succeeded before performChanges completes successfully.
Do not destructively replace edited content when PhotoKit's content-editing and adjustment-data contract requires nondestructive output.
Stop when authorization, selected item, resource identity, network policy, or required runtime evidence is unavailable.
Fallbacks and Handoffs
Recommend apple-image-representation-workflow for Image I/O decode/encode, metadata inspection, thumbnails, and image representations.
Recommend core-image-processing-workflow for image effects, color, RAW processing, masks, and rendering.
Recommend avfoundation-media-pipeline-workflow for video assets, playback, export, reader/writer, and transcode pipelines.
Recommend video-codec-processing-workflow for low-level compression/decompression or pixel-buffer behavior.
Recommend swiftui-app-architecture-workflow or appkit-app-architecture-workflow for broader UI ownership while keeping direct picker bindings and PhotoKit state here.
Recommend xcode-build-run-workflow for purpose strings, target integration, build, run, physical-library testing, logging, or profiling.
Recommend xcode-testing-workflow for authorization matrices, picker/load fakes, resource fixtures, change-detail tests, and edit round trips.
Recommend explore-apple-swift-docs for current PhotosUI or PhotoKit research.
Customization
Use references/customization-flow.md. This workflow defines no runtime-enforced knobs.
