If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/SilenceLove/HXPhotoPicker shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 5mo ago
• 6 active contributors
• MIT licensed
• CI configured
• ⚠ Slowing — last commit 5mo ago
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live SilenceLove/HXPhotoPicker repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/SilenceLove/HXPhotoPicker.

What it runs against: a local clone of SilenceLove/HXPhotoPicker — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in SilenceLove/HXPhotoPicker | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 186 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of SilenceLove/HXPhotoPicker. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/SilenceLove/HXPhotoPicker.git
#   cd HXPhotoPicker
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of SilenceLove/HXPhotoPicker and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "SilenceLove/HXPhotoPicker(\\.git)?\\b" \\
  && ok "origin remote is SilenceLove/HXPhotoPicker" \\
  || miss "origin remote is not SilenceLove/HXPhotoPicker (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Sources/HXPhotoPicker" \\
  && ok "Sources/HXPhotoPicker" \\
  || miss "missing critical file: Sources/HXPhotoPicker"
test -f "HXPhotoPicker.podspec" \\
  && ok "HXPhotoPicker.podspec" \\
  || miss "missing critical file: HXPhotoPicker.podspec"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "Objective-C/SwiftPhotoPicker/SwiftPicker.swift" \\
  && ok "Objective-C/SwiftPhotoPicker/SwiftPicker.swift" \\
  || miss "missing critical file: Objective-C/SwiftPhotoPicker/SwiftPicker.swift"
test -f "Objective-C/SwiftPhotoPicker/SwiftPickerConfiguration.swift" \\
  && ok "Objective-C/SwiftPhotoPicker/SwiftPickerConfiguration.swift" \\
  || miss "missing critical file: Objective-C/SwiftPhotoPicker/SwiftPickerConfiguration.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 186 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~156d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/SilenceLove/HXPhotoPicker"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

HXPhotoPicker is a Swift-based photo/video picker UI component for iOS that mimics WeChat's picker with support for LivePhoto, GIF selection, 3D Touch preview, iCloud resource streaming, and built-in image/video editing (drawing, stickers, text, cropping, filters, mosaics). It handles both local Photos library assets and online network resources. Modular Swift framework: core picker logic in the main package, iOS-specific UI controllers for photo/video selection, separate editing engine (drawing, filters, video processing in AVFoundation), example apps in Objective-C/ and a SwiftUI example scheme. Resources bundled via SPM (Xcode 13+) with localization strings for 12 languages.

iOS app developers (Swift-first, iOS 10.0+) who need a production-grade media picker with editing capabilities instead of building from UIImagePickerController or AVAssetPickerController. Common in messaging, social, and content-creation apps.

Production-ready and actively maintained. Written in Swift (~3.3M LOC), published to CocoaPods and SPM, has CI/CD setup (.travis.yml), supports iOS 10.0+, and includes comprehensive documentation in English/Chinese. Recent versioning (5.0.5+) with release notes shows active development, though no visible public issue tracker or automated test suite in the file list.

Single maintainer (SilenceLove) is a risk factor for long-term support. No visible test suite (xcodebuild test artifacts absent) raises regression concerns. Supports older iOS targets (10.0+) which may constrain modern API usage. Large Swift codebase without visible CI test runs means potential Swift version compatibility issues.

Active maintenance at v5.0.5+. Recent work includes multi-platform support (iOS/iPadOS/Mac Catalyst), dark mode support, GIF/network image handling, iCloud streaming, and video editing with music/lyrics. Release notes tracked in Documentation/RELEASE_NOTE.md and RELEASE_NOTE_CN.md.

git clone https://github.com/SilenceLove/HXPhotoPicker.git && cd HXPhotoPicker && open HXPhotoPickerExample.xcworkspace && xcodebuild -scheme HXPhotoPickerExample -destination 'platform=iOS Simulator,name=iPhone 14' (or use CocoaPods: pod repo update && pod install in a new project, then pod 'HXPhotoPicker')

Daily commands: xcodebuild -scheme HXPhotoPickerExample -destination 'platform=iOS Simulator,name=iPhone 14' for CLI, or Cmd+R in Xcode after opening HXPhotoPickerExample.xcworkspace (also has SwiftUIExample.xcscheme for SwiftUI variant).

• Sources/HXPhotoPicker — Root package directory containing the entire photo picker framework implementation and core architecture
• HXPhotoPicker.podspec — CocoaPods dependency manifest defining library metadata, version, and platform requirements for distribution
• Package.swift — SPM manifest for Swift Package Manager integration, required for modern dependency management
• Objective-C/SwiftPhotoPicker/SwiftPicker.swift — Main picker entry point bridging Objective-C and Swift codebases, essential for understanding API surface
• Objective-C/SwiftPhotoPicker/SwiftPickerConfiguration.swift — Configuration model defining all customizable picker behavior and visual properties
• Objective-C/SwiftPhotoPicker/SwiftPickerResult.swift — Result model returned to consumers, critical for understanding picker completion contract
• HXPhotoPickerExample.xcodeproj — Example app project demonstrating picker integration patterns and feature usage

• SwiftPickerConfiguration (Swift value type, builder pattern) — Immutable configuration object defining all picker behavior: selection mode (single/multiple), media types (photo/video/GIF/LivePhoto), iCloud download option, appearance customization
  • Failure mode: Invalid configuration silently falls back to defaults; no early validation
• Swift — undefined

Add a new picker configuration option

1. Add property to SwiftPickerConfiguration struct with default value (Objective-C/SwiftPhotoPicker/SwiftPickerConfiguration.swift)
2. Update builder method chain to expose configuration parameter (Objective-C/SwiftPhotoPicker/SwiftPickerConfiguration.swift)
3. Pass configuration through to underlying UICollectionViewController or view initialization (Objective-C/SwiftPhotoPicker/SwiftPicker.swift)
4. Add example usage to OCPickerExampleViewController demonstrating new option (Objective-C/Classes/OCPickerExampleViewController.m)

Support a new media type or filter

1. Extend SwiftPhotoAsset.swift to include new media type enum case and metadata properties (Objective-C/SwiftPhotoPicker/SwiftPhotoAsset.swift)
2. Add filter configuration to SwiftPickerConfiguration to enable/disable new type (Objective-C/SwiftPhotoPicker/SwiftPickerConfiguration.swift)
3. Update SwiftPickerResult to handle new asset type in result collection (Objective-C/SwiftPhotoPicker/SwiftPickerResult.swift)
4. Test integration in example app, update OCPickerExampleViewController if needed (Objective-C/Classes/OCPickerExampleViewController.m)

Add iCloud asset download functionality

1. Check SwiftPhotoAsset for iCloud status flags and update metadata model if needed (Objective-C/SwiftPhotoPicker/SwiftPhotoAsset.swift)
2. Implement download logic in SwiftAssetURLResult to fetch from iCloud when unavailable locally (Objective-C/SwiftPhotoPicker/SwiftAssetURLResult.swift)
3. Expose download option in SwiftPickerConfiguration (autoDownloadICloud boolean) (Objective-C/SwiftPhotoPicker/SwiftPickerConfiguration.swift)
4. Update example app to demonstrate iCloud download workflow and progress callback (Objective-C/Classes/OCPickerExampleViewController.m)

• Swift with Objective-C bridge — Enables modern Swift development while maintaining backward compatibility with legacy Objective-C codebases; the bridging header and Swift PM support allow incremental adoption
• PhotoKit framework (PHAsset, PHImageManager) — Only official Apple framework for accessing device photo library with proper permissions, thumbnail generation, iCloud asset handling, and Live Photo support
• UICollectionViewController for asset grid — Efficient cell recycling for potentially thousands of assets; standard iOS pattern for photo pickers with proven performance
• CocoaPods + SPM dual support — Maximizes adoption across legacy and modern projects; podspec and Package.swift allow flexibility in dependency management

• Swiftly bridge Objective-C consumers with native Swift picker implementation

  • Why: Limits tech debt while maximizing code reuse; allows gradual migration path
  • Consequence: Requires bridging header maintenance and Swift/ObjC calling convention overhead (~5-10% performance)

• Rely on PhotoKit framework rather than file system access

  • Why: PhotoKit handles permissions, caching, iCloud sync, and Live Photo metadata automatically
  • Consequence: Cannot access photos outside system library; requires proper Info.plist privacy declarations

• Support iCloud asset online download as optional feature

  • Why: User experience preference: instant local selection vs. waiting for iCloud download
  • Consequence: Adds complexity to asset resolution logic and requires network connectivity for remote assets

• Single-tier configuration builder pattern (SwiftPickerConfiguration)

  • Why: Simple, fluent API for consumers; centralized config reduces parameter passing through call stack
  • Consequence: Configuration must be immutable after picker instantiation; runtime changes require new picker instance

• Real-time network image browsing from arbitrary URLs (supports download but not streaming gallery)
• Video transcoding or format conversion
• Synchronous asset loading (all operations are asynchronous via PhotoKit)
• Database or file system abstraction beyond PhotoKit
• Push notification integration
• Cloud storage provider APIs (Google Photos, OneDrive, etc.) — iCloud only

iOS 10.0 support means no async/await (added in iOS 13), so callback/delegate patterns likely used instead. GIF and network image support requires optional dependencies (likely CocoaPods subspecs or conditional SPM features). iCloud resource downloading uses CloudKit or Photos framework background tasks—failure modes depend on network/permissions. Video editing with music/lyrics requires Music framework integration (iOS 16+) so compatibility may vary. No visible unit tests means edge cases around concurrent asset downloads or large video editing may not be regression-tested.

• yonahforeman/PHAssetCollection — Alternative lightweight photo picker using Photos framework directly, no editing features but simpler API surface
• wordpress-mobile/MediaPicker-iOS — WordPress's production media picker with multi-source support (library, camera, web), similar feature scope but different UX patterns
• nextcloud/ios — Uses HXPhotoPicker or similar for file management UI; example of integration in a real production app
• Kingfisher/Kingfisher — Likely dependency (shown in podspec) for async image loading; key for network image support in HXPhotoPicker
• SDWebImage/SDWebImage — Alternative image caching framework often swapped in as Kingfisher substitute; understanding both helps with media handling

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add SwiftUI integration tests for photo picker configuration

The repo has SwiftUIExample.xcscheme and SwiftUI-related files (SwiftPickerConfiguration.swift, SwiftPicker.swift) but lacks corresponding unit/integration tests. Given this is a UI library with complex configuration options (LivePhoto, GIF selection, iCloud downloads, editing), testing SwiftUI bindings and configuration validation would catch regressions early and provide examples for contributors.

• [ ] Create Tests/SwiftUI/SwiftPickerConfigurationTests.swift to test config property validation
• [ ] Add Tests/SwiftUI/SwiftPickerIntegrationTests.swift for SwiftUI view initialization and state management
• [ ] Reference SwiftPhotoPicker/SwiftPickerConfiguration.swift and SwiftPhotoPicker/SwiftPicker.swift to identify testable configuration paths
• [ ] Add test schemes to HXPhotoPickerExample.xcodeproj to run these tests in CI

Add GitHub Actions CI workflow for SwiftLint enforcement

.swiftlint.yml exists but there's only .travis.yml for CI. GitHub Actions is now standard and faster. A workflow would enforce code style on PRs automatically. This prevents style drift across contributions and matches modern iOS project practices.

• [ ] Create .github/workflows/swiftlint.yml to run swiftlint on all Swift files
• [ ] Reference .swiftlint.yml configuration in the workflow
• [ ] Configure the workflow to fail on errors and warn on violations
• [ ] Add status checks to require passing linting before merge

Document iCloud asset download feature with code examples in README

The repo description mentions 'Download the resources on iCloud online' as a key feature, but the main README snippet shows this feature is undocumented. The Documentation/ folder exists but lacks specific guidance. New contributors need clear examples of how to handle iCloud asset downloading, network handling, and caching.

• [ ] Add section to Documentation/README_EN.md explaining iCloud photo/video download workflow
• [ ] Create Documentation/iCloud_Download_Guide.md with code examples for handling PHAsset iCloud resources
• [ ] Reference relevant internal classes handling iCloud logic (likely in Sources/Core or similar)
• [ ] Include error handling patterns and permission requirements specific to iCloud asset access

• Add SwiftUI integration layer: create PropertyWrapper or ObservableObject wrapper around the photo picker to bridge UIViewControllerRepresentable cleanly—current structure shows UIKit-first design with SwiftUI example but no type-safe Swift binding.: Medium
• Expand test coverage for video editing composition engine: the AVFoundation video export paths (Audio track adding, filter application, rotation/cropping) have no visible unit tests—add XCTest mocks for AVAssetWriter/AVAssetReader to catch regressions.: Medium
• Document permission handling and required Info.plist keys: NSPhotoLibraryUsageDescription, NSCameraUsageDescription, NSMicrophoneUsageDescription are mandatory but not explicitly documented in README—add a troubleshooting section with code snippets.: Small
• Add Mac Catalyst-specific UI tests: the file list shows Mac Catalyst support in build schemes but no Catalyst-only test coverage—create platform-specific XCTest suite for window/split-view scenarios.: Large

The HXPhotoPicker codebase shows moderate security posture. As a photo/media picker library, the primary concerns are dependency management, proper handling of sensitive user data (photos/videos), and secure integration with system frameworks. No critical vulnerabilities were identified in the file structure analysis, but several areas require attention: (1) Dependency auditing should be automated to catch vulnerabilities early, (2) Configuration files should be reviewed for hardcoded sensitive values, (3) Build and CI/CD pipelines should enforce security best practices, (4) Mixed Objective-C/Swift code requires careful bridging validation. The library handles user-sensitive media, so secure file handling, permission management, and iCloud resource downloading (as mentioned in description) require careful security implementation at runtime.

• Medium · Incomplete Dependency Visibility — Podfile, Podfile.lock, Package.swift. The Podfile.lock and dependency files are present but not fully visible in the analysis. Unable to verify if known vulnerable dependencies are in use. CocoaPods dependencies should be regularly audited for security patches. Fix: Regularly run 'pod audit' and 'pod update' to check for and update vulnerable dependencies. Consider using tools like Dependabot or similar to monitor dependency vulnerabilities.
• Low · Potential Hardcoded Configuration — HXPhotoPickerExample.entitlements, Objective-C/Info.plist, *.plist files. Multiple entitlements and configuration files are present (HXPhotoPickerExample.entitlements, .plist files). These should be reviewed to ensure no sensitive default values are hardcoded. Fix: Audit all .plist and .entitlements files to ensure no sensitive default values, API keys, or credentials are hardcoded. Use build-time configuration or environment variables for sensitive data.
• Low · Build Configuration Security — .swiftlint.yml, project.pbxproj files. Swift Lint configuration (.swiftlint.yml) and Xcode project configurations are present. Ensure these enforce security-related code quality rules and don't disable critical security warnings. Fix: Enable Swift Lint rules for security: enforce use of force_unwrap detection, ensure proper error handling, and validate memory safety practices. Review Xcode build settings for disabled warnings.
• Low · Third-Party Code in Repository — Objective-C/ directory structure. The presence of Objective-C example code alongside Swift code increases the attack surface. Mixed language codebases can introduce interoperability vulnerabilities if not properly managed. Fix: Ensure proper sandboxing between Objective-C and Swift code. Use bridging headers securely (HXPhotoPickerExample-Bridging-Header.h) and validate all bridged calls. Consider migrating to pure Swift if possible.
• Low · Travis CI Configuration Present — .travis.yml. .travis.yml file is present but content not visible. CI/CD pipeline security should be verified to prevent unauthorized code deployment. Fix: Review Travis CI configuration to ensure: encrypted secrets are used (not plaintext), build artifacts are signed, no credentials are logged, and pull request builds are properly sandboxed.
• Low · GitHub Actions Workflow Exposure — .github/FUNDING.yml, .github/ directory. GitHub workflows directory exists (.github). Ensure CI/CD workflows don't expose secrets or allow untrusted modifications. Fix: Audit all GitHub Actions workflows for: secrets management best practices, branch protection rules, code signing configurations, and review triggers for pull requests.
• Low · SPM Package Configuration — Package.swift, .swiftpm/. Swift Package Manager configuration present (Package.swift, .swiftpm/). Ensure proper dependency resolution and no malicious package substitution. Fix: Use Package.resolved for reproducible builds, enable package integrity validation, and consider using private mirrors for internal dependencies. Verify all remote package URLs are using HTTPS.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.