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.

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.
• output: documented behavior, access decision, identity/lifecycle, request/change/edit plan, diagnostics, validation, and handoffs.

Guards and Stop Conditions

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

References

• references/photosui-selection-and-authorization.md
• references/assets-fetches-requests-resources-and-changes.md
• references/creation-collections-and-nondestructive-editing.md
• references/customization-flow.md
• Recommend references/snippets/apple-xcode-project-core.md for reusable Xcode-project policy.

Script Inventory

• scripts/customization_config.py