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/BeauNouvelle/FaceAware 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.

WAIT — Stale — last commit 6y ago

• 9 active contributors
• MIT licensed
• ⚠ Stale — last commit 6y ago
• ⚠ Concentrated ownership — top contributor handles 54% of recent commits
• ⚠ No CI workflows detected
• ⚠ 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 BeauNouvelle/FaceAware repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/BeauNouvelle/FaceAware.

What it runs against: a local clone of BeauNouvelle/FaceAware — 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 BeauNouvelle/FaceAware | 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 ≤ 2138 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of BeauNouvelle/FaceAware. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/BeauNouvelle/FaceAware.git
#   cd FaceAware
#
# 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 BeauNouvelle/FaceAware and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "BeauNouvelle/FaceAware(\\.git)?\\b" \\
  && ok "origin remote is BeauNouvelle/FaceAware" \\
  || miss "origin remote is not BeauNouvelle/FaceAware (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 "FaceAware/UIImageView+FaceAware.swift" \\
  && ok "FaceAware/UIImageView+FaceAware.swift" \\
  || miss "missing critical file: FaceAware/UIImageView+FaceAware.swift"
test -f "FaceAware/Attachable.swift" \\
  && ok "FaceAware/Attachable.swift" \\
  || miss "missing critical file: FaceAware/Attachable.swift"
test -f "Example/Example/ViewController.swift" \\
  && ok "Example/Example/ViewController.swift" \\
  || miss "missing critical file: Example/Example/ViewController.swift"
test -f "FaceAware.podspec" \\
  && ok "FaceAware.podspec" \\
  || miss "missing critical file: FaceAware.podspec"
test -f "Example/Example/Assets.xcassets/sample.imageset/girl-1252995_1280.jpg" \\
  && ok "Example/Example/Assets.xcassets/sample.imageset/girl-1252995_1280.jpg" \\
  || miss "missing critical file: Example/Example/Assets.xcassets/sample.imageset/girl-1252995_1280.jpg"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 2138 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2108d)"
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/BeauNouvelle/FaceAware"
  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).

FaceAware is a Swift extension that adds intelligent face-detection-based image cropping to UIImageView. It uses Core Image's CIDetector to analyze images for human faces and automatically adjusts the content mode and layer bounds to keep detected faces centered and visible, solving the problem where AspectFill crop mode often removes faces from profile pictures and avatars. Simple file-based structure: core logic in FaceAware/UIImageView+FaceAware.swift (the main extension), with FaceAware/Attachable.swift as a supporting protocol. Example/Example/ contains a minimal demo app (ViewController.swift + storyboard) showing the feature in action. No src/ or packages/ subdirectories—entirely flat, appropriate for a single-purpose library.

iOS developers building apps with user avatars, profile pictures, or gallery features who want to avoid manual image cropping workflows. Specifically useful for teams building social apps, messaging platforms, or community features where user-submitted photos need smart framing.

Moderately mature but potentially stale. The codebase is small (~13KB Swift) and the README indicates it's a modernization of two unmaintained predecessors (BetterFace-Swift and FaceAwareFill). Swift 5.1+ requirement and iOS 8.0+ support suggest active maintenance, but the file list lacks visible tests, CI configuration (no .github/workflows/ or .travis.yml shown), and commit recency is unknown. Suitable for production use in straightforward scenarios but lacks test coverage visibility.

Low-to-medium risk for most use cases. The extension is tightly scoped (one main file UIImageView+FaceAware.swift) with minimal dependencies—only Core Image/Vision frameworks (native iOS). Main risks: single maintainer (BeauNouvelle), no visible test suite in file list, and face detection accuracy depends on image quality and lighting conditions. Breaking changes are unlikely given the stable API surface, but lack of test infrastructure means regressions could slip through.

No active commit history visible in the file list provided. The repo appears stable but not actively developed—it's a mature, self-contained library without pending features mentioned in the README or visible issue tracking.

Clone and open the example project:

git clone https://github.com/BeauNouvelle/FaceAware.git
cd FaceAware/Example
open Example.xcodeproj

Or integrate via CocoaPods: add pod 'FaceAware' to your Podfile and run pod install.

Daily commands: For the demo app:

open Example/Example.xcodeproj
# Select Example target, then Cmd+R to build and run in Simulator

No package manager setup required—purely Xcode project. To integrate into your own app, either drag UIImageView+FaceAware.swift into your project (manual) or use CocoaPods/Carthage.

• FaceAware/UIImageView+FaceAware.swift — Core extension that adds face-detection and content-mode-adjustment logic to UIImageView; all face-aware functionality flows through here.
• FaceAware/Attachable.swift — Protocol defining the interface for face-aware behavior; every component implementing face detection must conform to this contract.
• Example/Example/ViewController.swift — Primary usage example demonstrating how to integrate FaceAware into a real UIImageView; shows the expected API surface.
• FaceAware.podspec — Package manifest defining dependencies, module structure, and deployment targets; required for distribution and CocoaPods integration.
• Example/Example/Assets.xcassets/sample.imageset/girl-1252995_1280.jpg — Sample image asset used in example app to demonstrate face detection capabilities on real-world photography.

• UIImageView+FaceAware extension (Swift, UIKit, Core Image) — Orchestrates face detection, content-mode adjustment, and focus calculation; provides public API for image assignment
  • Failure mode: Falls back to standard contentMode if face detection fails or no faces found; returns default aspectFill behavior
• Attachable protocol (Swift Protocol) — Defines contract for face-aware behavior; enables type-safe, extensible design for future implementations
  • Failure mode: Not directly invoked at runtime in current codebase; serves as design anchor for future variants
• CIDetector (Core Image) (Core Image, C API) — Native iOS face detection engine; identifies face features and returns bounding rectangles
  • Failure mode: Returns empty array if no faces detected; detection accuracy varies with image quality and face angle
• Example app ViewController (UIKit, Swift) — Demonstrates FaceAware usage with sample image; provides reference integration pattern
  • Failure mode: Sample image missing or corrupted; gracefully degrades to default image display

• UIImageView.image property → CGImage extraction — User or code assigns UIImage to imageView; extension extracts underlying CGImage for analysis
• CGImage → CIDetector — Face detector analyzes pixel data to locate facial features
• CIDetector → Face bounds (CIFaceFeature) — Detector returns array of bounding rectangles for each detected face
• Face bounds → Focus calculation — Extension computes centroid and scales bounds relative to image and view dimensions
• Focus calculation → contentMode & contentOffset — Adjusted values are applied to UIImageView to center detected faces in visible bounds

Enable face-aware content mode on an existing UIImageView

1. Import the FaceAware module in your view controller (Example/Example/ViewController.swift)
2. Assign an image to your UIImageView and call the face-aware method (e.g., imageView.setImageAndFocus(imageName:) or similar) (FaceAware/UIImageView+FaceAware.swift)
3. The extension automatically detects faces and adjusts contentMode and contentOffset to keep faces centered (FaceAware/UIImageView+FaceAware.swift)

Create a new face-aware variant for a different image container

1. Define a new extension or class conforming to the Attachable protocol (FaceAware/Attachable.swift)
2. Implement the required methods using CIDetector to analyze images and calculate face bounds (FaceAware/UIImageView+FaceAware.swift)
3. Reuse the face detection logic from UIImageView+FaceAware as a reference implementation (FaceAware/UIImageView+FaceAware.swift)

Customize face detection parameters or add more detection types

1. Locate the CIDetector initialization and accuracy/type constants in the main extension (FaceAware/UIImageView+FaceAware.swift)
2. Modify detector options (e.g., accuracy level, tracking) or add additional feature types (e.g., eyes, rectangles) (FaceAware/UIImageView+FaceAware.swift)
3. Update the focus calculation logic if needed to account for new detection features (FaceAware/UIImageView+FaceAware.swift)

• Core Image (CIDetector) — Native iOS framework for efficient, GPU-accelerated face detection; no external ML dependencies required
• UIKit Extension (Swift) — Allows non-invasive enhancement of UIImageView without subclassing; leverages existing UIImageView APIs for contentMode and contentOffset
• CocoaPods — Standard package manager for iOS libraries; enables easy distribution and integration into existing projects

• Use CIDetector (Core Image) for face detection rather than Vision framework

  • Why: Broader iOS version support and simpler API for basic face detection; Core Image is available on older iOS versions
  • Consequence: Vision framework (iOS 11+) offers better accuracy and more feature types but would reduce compatibility

• Perform face detection synchronously in the main thread

  • Why: Simplifies API and ensures immediate visual feedback on image assignment
  • Consequence: May cause brief UI stalls on large images or images with many faces; background processing would improve responsiveness but complicate the API

• Use UIImageView extension rather than custom subclass

  • Why: Non-invasive; works with existing UIImageView instances without requiring class changes
  • Consequence: Prevents overriding contentMode after initialization; users must use provided setter methods

• Real-time video face tracking (designed for static images only)
• Multi-face ranking or prioritization (treats all detected faces equally)
• Batch image processing or bulk optimization
• Android or cross-platform support (iOS/Swift only)
• Custom ML model training or fine-tuning

• Synchronous main-thread face detection (Medium) — FaceAware/UIImageView+FaceAware.swift: Face detection (CIDetector analysis) runs synchronously on the main UI thread, potentially blocking UI for large images or images with multiple faces (50-200ms stalls possible)
• No caching of CIDetector instance (Low) — FaceAware/UIImageView+FaceAware.swift: If face detection is called multiple times, a new CIDetector may be created repeatedly, wasting resources; detector should be cached as a static or shared instance
• Hardcoded detector accuracy constants (Low) — FaceAware/UIImageView+FaceAware.swift: Face detector accuracy and type options are hardcoded; no configuration API for consumers to tune detection sensitivity or enable additional features (eye detection, etc.)

• CIDetector face analysis (Computational / Main thread) — Core Image face detection can take 50-200ms for complex images; no background processing or caching mitigates latency
• CGImage conversion (undefined) — Converting UIImage to CGImage and then to CIImage requires pixel data I/O; no early-exit for very small or

No hidden traps are directly obvious from the file list, but: (1) Face detection is CPU-intensive and runs on the main thread by default—large images may cause UI freezes; the code does not show async/background thread handling; (2) CIDetector accuracy degrades with faces at odd angles, low resolution, or poor lighting; tests using such images may fail silently; (3) @IBDesignable rendering in Interface Builder has a known lag—changes may not preview immediately; (4) Setting focusOnFaces before assigning an image will fail silently (no error, just no faces to detect); the README warns of this but code does not validate.

• CIDetector (Core Image Face Detection) — This is the underlying iOS API that FaceAware wraps; understanding how CIDetector.faceDetector works, its accuracy limits, and performance trade-offs is essential for debugging face detection failures or improving the implementation
• @IBDesignable and @IBInspectable — FaceAware uses these attributes to enable live preview and configuration in Interface Builder without code; knowing how they work and their rendering pipeline is crucial for understanding why the debug UI behaves differently in IB vs. runtime
• UIImageView content mode and layer bounds manipulation — The core technique: FaceAware adjusts contentMode and layer.bounds/layer.position to crop images dynamically; misunderstanding these properties will make modifications fail or produce incorrect framing
• Swift Extension (Category) pattern — The entire library is built as a UIImageView extension; grasping how Swift extensions work, their scope, and method resolution order is necessary to maintain or extend the codebase without introducing conflicts
• CGRect and CGPoint geometric calculations — Face detection returns CGRect bounds that must be scaled and centered; the code performs geometric math to map face coordinates to UIImageView bounds—bugs here cause faces to be cropped at wrong positions
• Main thread UI updates and async patterns — Face detection runs synchronously and may freeze the UI on large images; understanding why UI updates must occur on the main thread and how to dispatch background work is critical for performance improvements

• croath/UIImageView-BetterFace-Swift — Direct predecessor mentioned in README; the original face-aware cropping extension that FaceAware modernized and maintained
• Julioacarrettoni/UIImageView_FaceAwareFill — Second predecessor mentioned in README; alternative earlier approach to the same face-detection-based image fitting problem
• kingcos/UIImageView-Kingfisher — Complementary UIImageView extension library for image downloading and caching; commonly used alongside FaceAware in real apps for full image management
• apple/swift-coreimage-tools — Apple's official Core Image utilities; useful reference for advanced CIDetector patterns and optimization if you extend FaceAware's detection logic
• Firebase/firebase-ios-sdk — Firebase ML Kit provides alternative face detection via cloud APIs; a heavier but potentially more accurate option if FaceAware's on-device detection proves insufficient

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 unit tests for UIImageView+FaceAware.swift extension

The repo lacks any test files (.xctest bundles or test targets). The core functionality in UIImageView+FaceAware.swift that handles face detection and content mode adjustment needs test coverage to catch regressions. This is critical for a library that manipulates image rendering.

• [ ] Create FaceAwareTests target in Example/Example.xcodeproj
• [ ] Write tests for face detection logic in UIImageView+FaceAware.swift (e.g., test with sample.imageset/girl-1252995_1280.jpg)
• [ ] Test content mode switching and frame recalculation when faces are detected vs. not detected
• [ ] Test edge cases: nil images, images with no detectable faces, multiple faces in one image

Add GitHub Actions workflow for CI/CD on PR submissions

No .github/workflows directory exists. A Swift/iOS test CI workflow would automatically validate pull requests, ensure the Example app builds correctly, and run the new test suite. This prevents regressions and ensures contributors' code compiles on main branches.

• [ ] Create .github/workflows/tests.yml
• [ ] Configure workflow to run on: pull_request, push to main
• [ ] Add steps to build Example/Example.xcodeproj and run XCTest suite
• [ ] Optional: Add linting step for Swift code style (SwiftLint)

Document the Attachable.swift protocol and its usage in README.md

Attachable.swift exists in the codebase but is not mentioned in README.md. This protocol is likely central to how FaceAware extends UIImageView, but new contributors won't understand the architecture. The README snippet cuts off mid-sentence and lacks API documentation.

• [ ] Review Attachable.swift to understand protocol design and requirements
• [ ] Add 'API Documentation' or 'Usage' section to README.md explaining the Attachable protocol
• [ ] Document public methods in UIImageView+FaceAware.swift (e.g., any set image functions mentioned in the description)
• [ ] Add code example showing how to use FaceAware with a UIImageView instance
• [ ] Include note about face detection privacy/limitations (e.g., only detects frontal faces via Vision framework)

• Add unit tests for UIImageView+FaceAware.swift: create a Tests/ directory and write XCTest cases for the face detection logic, the focusOnFaces property observer, and the didFocusOnFaces closure invocation using sample images in Assets.xcassets/.
• Implement async face detection: refactor the face detection code in UIImageView+FaceAware.swift to run on a background queue (DispatchQueue.global()) to prevent main thread blocking on large images, then dispatch the content adjustment back to the main thread.
• Add documentation comments to UIImageView+FaceAware.swift: write Swift Doc comments for all public properties (focusOnFaces, didFocusOnFaces, debug) and methods (set(image:focusOnFaces:), drawFaceRectangles()) to improve IDE autocomplete and generated docs.

FaceAware is a relatively lightweight iOS framework with limited external dependencies, which reduces attack surface. The primary security concerns are around input validation for image processing and privacy implications of face detection. The codebase lacks formal security documentation and vulnerability disclosure policies. No critical vulnerabilities were identified, but medium-severity issues around image input validation and code signing configuration should be addressed. The framework uses Apple's official Vision framework which is well-maintained and secure. Overall security posture is good for a specialized utility framework, but could be improved with better documentation and input sanitization.

• Medium · Missing Code Signing Configuration — FaceAware/UIImageView+FaceAware.swift, FaceAware/Attachable.swift. The FaceAware framework uses Core Image and Vision frameworks for face detection without explicit code signing verification. While not a direct vulnerability, proper code signing is critical for iOS frameworks to prevent tampering and ensure integrity. Fix: Ensure the framework is properly code-signed with a valid Apple Developer certificate in Xcode build settings and validate code signatures during integration.
• Medium · Lack of Input Validation on Image Processing — FaceAware/UIImageView+FaceAware.swift. The framework processes user-provided images without apparent validation of image metadata, size constraints, or memory bounds. Large or malformed images could potentially cause memory exhaustion or denial of service. Fix: Implement image validation checks including: maximum image size limits, format validation, and memory consumption guards before processing with Vision framework.
• Low · Missing Privacy Disclosures — Example/Example/Info.plist, FaceAware/Info.plist. The framework uses Core Image and Vision frameworks for face detection without explicit privacy policy documentation or NSFaceDetectionDescription in Info.plist. Users should be informed that face detection is occurring. Fix: Add privacy descriptions to Info.plist for face detection capabilities and document privacy implications in README and framework documentation.
• Low · No Security.md or Vulnerability Disclosure Policy — Repository root. There is no documented security policy, responsible disclosure guidelines, or security contact information for reporting vulnerabilities in the framework. Fix: Create a SECURITY.md file with responsible vulnerability disclosure guidelines and security contact information.
• Low · Outdated or Unspecified Dependency Versions — FaceAware.podspec. The FaceAware.podspec file is present but content not provided. Podspec should pin dependency versions to prevent unexpected breaking changes or security issues from transitive dependencies. Fix: Review and pin specific versions of all dependencies in the podspec file. Document minimum supported iOS version and SDK requirements.

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.