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/HeroTransitions/Hero 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

• 26+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 62% of recent commits

_{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 HeroTransitions/Hero repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/HeroTransitions/Hero.

What it runs against: a local clone of HeroTransitions/Hero — 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 HeroTransitions/Hero | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 501 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "HeroTransitions/Hero(\\.git)?\\b" \\
  && ok "origin remote is HeroTransitions/Hero" \\
  || miss "origin remote is not HeroTransitions/Hero (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 develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f ".swiftlint.yml" \\
  && ok ".swiftlint.yml" \\
  || miss "missing critical file: .swiftlint.yml"
test -f "Examples/Resources/AppDelegate.swift" \\
  && ok "Examples/Resources/AppDelegate.swift" \\
  || miss "missing critical file: Examples/Resources/AppDelegate.swift"
test -f "Examples/MainViewController.swift" \\
  && ok "Examples/MainViewController.swift" \\
  || miss "missing critical file: Examples/MainViewController.swift"
test -f "Examples/ExampleBaseViewController.swift" \\
  && ok "Examples/ExampleBaseViewController.swift" \\
  || miss "missing critical file: Examples/ExampleBaseViewController.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 501 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~471d)"
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/HeroTransitions/Hero"
  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).

Hero is a Swift library that simplifies iOS & tvOS view controller transitions by providing a declarative layer over UIKit's transition APIs. It uses a 'Magic Move' approach: matching views between screens via heroID are automatically animated between their old and new states, while unmatched views can be animated via heroModifiers. Hero handles interactive gesture-driven transitions and provides template animations (modal, navigation, tab bar) that developers can customize. Single-package library: Sources/ contains the core Hero engine (likely organized by feature: Transition, Animation, Modifier, etc.), Examples/ contains 5 runnable demo ViewControllers (MatchExample, AppStoreCardExample, BuiltInTransitionExample, etc.), and .github/workflows/ automates CI. Makefile-based build system (.makefiles/) abstracts iOS, Docker, and bundler tasks. Documentation via .jazzy.yaml suggests API doc generation.

iOS/tvOS developers building apps with custom view controller transitions who want to avoid boilerplate UIKit transition controller code. Specifically UX-focused engineers who need fluid, interactive animations without implementing complex CABasicAnimation chains or gesture recognizer coordinators manually.

Production-ready and actively maintained. The codebase has 283K+ lines of Swift, comprehensive CI/CD (GitHub Actions for build/test/lint), codecov integration, and follows semantic versioning (CocoaPods/Carthage/SPM support). Badges show Xcode 10.0+, iOS 10.0+, Swift 4.0+ support. Presence of DEVELOP.md, Makefile-based tooling, and .github workflows indicate professional maintenance.

Low risk for production use. Single-language codebase (Swift 283K LOC) with minimal dependencies (no external pod dependencies visible). GitHub workflow files show automated testing and linting. Main risk is single-maintainer dependency (lkzhao appears primary), but org is 'HeroTransitions' suggesting community stewardship. No breaking changes evident in recent activity based on file structure.

Library is in steady-state maintenance: GitHub workflows (test.yml, swiftlint.yml, build.yml, rebase.yml) run automatically; .github/stale.yml and Dangerfile suggest active PR/issue management. Recent activity includes SwiftPM compatibility testing (SwiftPMTest workflow), suggesting modernization for package manager adoption. No major version bump visible; focus is on compatibility and code quality.

Clone and install: git clone https://github.com/HeroTransitions/Hero.git && cd Hero. Install via CocoaPods (pod install), Carthage (carthage update), or Swift Package Manager. Run examples: open Hero.xcworkspace (created by CocoaPods) in Xcode 10+, select the Example app target, and build to iOS 10.0+ simulator.

Daily commands: Dev setup: make help (via .makefiles/) shows available tasks. Typical: make install-dependencies → make build → make test. For interactive testing: open Hero.xcworkspace (CocoaPods manages dependencies), select 'Example' scheme, run on iOS 10+ simulator. Xcode 10.0+ required.

• .github/workflows/build.yml — Defines the primary CI/CD build pipeline for all branches; any build failures block merges.
• .swiftlint.yml — Enforces code style and quality standards across the entire codebase; violations block CI.
• Examples/Resources/AppDelegate.swift — Application entry point and configuration for the example app demonstrating Hero's core functionality.
• Examples/MainViewController.swift — Primary navigation and example showcase controller; hub for understanding Hero's public API surface.
• Examples/ExampleBaseViewController.swift — Base class for all example controllers; establishes patterns for Hero transition usage and setup.
• .jazzy.yaml — Documentation generation configuration; defines public API documentation for the library.
• DEVELOP.md — Developer guide covering contribution workflow, testing, and local environment setup.

• Example Application (Swift, UIKit) — Demonstrates Hero's capabilities through concrete use cases (AppStore cards, collection view matches, built-in transitions).
  • Failure mode: Examples crash or animations fail to execute; blocks validation of library functionality.
• CI/CD Pipeline (GitHub Actions, SwiftLint, Jazzy) — Automates building, testing, linting, documentation generation, and deployment to CocoaPods.
  • Failure mode: Build failure prevents merging; broken tests or lint errors halt releases; documentation generation fails.
• Code Quality Enforcement (SwiftLint, .swiftlint.yml) — Enforces consistent Swift style and prevents common bugs via static analysis.
  • Failure mode: Inconsistent code style; bugs slip into production; maintenance burden increases.
• API Documentation (Jazzy, .jazzy.yaml) — Generates and publishes human-readable API reference for developers integrating Hero.
  • Failure mode: Documentation is outdated or missing; adoption friction increases; API misuse by developers.
• Package Distribution (CocoaPods, GitHub releases) — Publishes versioned library to CocoaPods for dependency management.
  • Failure mode: Library unavailable to developers; version conflicts; installation failures.

• Developer → GitHub repository — Pushes code changes to develop or feature branches.
• GitHub webhook → GitHub Actions CI/CD — undefined

Add a New Example Transition

1. Create a new Swift file in Examples/ directory following the naming pattern {FeatureName}Example.swift (Examples/{NewExample}Example.swift)
2. Inherit from ExampleBaseViewController which provides Hero setup and lifecycle hooks (Examples/ExampleBaseViewController.swift)
3. Configure Hero animations in setupHero() method and implement transition UI logic (Examples/{NewExample}Example.swift)
4. Register the new example in MainViewController's example list for navigation (Examples/MainViewController.swift)

Update Code Quality Standards

1. Modify SwiftLint rules in the configuration file to enforce new linting standards (.swiftlint.yml)
2. Update CI/CD to run linting checks and fail builds if violations are found (.github/workflows/swiftlint.yml)
3. Document rule changes and rationale for developers (DEVELOP.md)

Publish a New Release

1. Document all changes, bug fixes, and new features in this file with version number (CHANGELOG.md)
2. Verify all tests pass and code quality checks succeed in the build workflow (.github/workflows/build.yml)
3. Tag commit with version in Git; GitHub Actions will automatically build and publish to CocoaPods (.github/workflows/build.yml)

Configure API Documentation Generation

1. Update Jazzy configuration with new module or structure paths for auto-documentation (.jazzy.yaml)
2. Add inline documentation comments to Swift source code following standard format (Examples/{SourceFile}.swift)
3. Verify documentation builds locally and renders correctly before committing (.jazzy.yaml)

• Swift 4.0+ — Native iOS language enabling type-safe, readable declarative transition code.
• UIKit — Foundation framework required for iOS view controller transitions and animation APIs.
• GitHub Actions — Native CI/CD integration enabling automated testing, linting, and deployment on every push.
• SwiftLint — Enforces consistent Swift code style and catches common anti-patterns automatically.
• Jazzy — Auto-generates professional API documentation from Swift inline comments.
• CocoaPods — Standard iOS dependency manager for library distribution and version management.

• Declarative transition API on top of UIKit's imperative APIs

  • Why: Reduces boilerplate and mental overhead for developers writing custom transitions.
  • Consequence: Introduces abstraction layer requiring maintainers to map high-level concepts to low-level UIKit calls; potential performance overhead from wrapper code.

• Single library focused only on view controller transitions

  • Why: Deep focus enables elegant, battle-tested solutions without feature creep.
  • Consequence: Developers need complementary libraries for other animation needs (gesture recognition, physics-based animations); limits market scope.

• GitHub Actions for CI/CD instead of self-hosted runners

  • Why: Zero infrastructure maintenance, free for open source, tightly integrated with repository.
  • Consequence: Limited customization for specialized build requirements; potential latency during high-traffic periods.

• Does not handle app-level gesture recognition or pan interaction logic (delegates to host app).
• Not a real-time networking or persistence library.
• Does not support Android or other non-Apple platforms.
• Does not replace UIViewController lifecycle or view hierarchy management.

No major hidden traps detected, but note: (1) Hero relies on matching view hierarchies via heroID — if source/dest views have different UIView subclasses or frame aspect ratios, animations may appear janky (no auto-correction). (2) Interactive transitions require manual gesture recognizer setup in your ViewController; Hero only handles animation, not gesture binding. (3) tvOS support is claimed but Examples are iOS-focused; test on tvOS simulator if targeting it. (4) Xcode 10.0+ requirement means you cannot use this in older projects without upgrading.

• CABasicAnimation & CAKeyframeAnimation — Hero abstracts these Core Animation primitives to drive geometry-based view transitions; understanding their timing curves and property paths is essential for debugging non-linear animations
• UIViewControllerAnimatedTransitioning — Core UIKit protocol Hero implements to inject custom transitions between view controllers; you must understand transitionDuration() and animateTransition() to extend Hero
• Interactive Transitions via UIViewControllerInteractiveTransitioning — Hero's gesture-driven interruptibility relies on this protocol; understanding percentComplete and finish()/cancel() is critical for gesture-responsive animations
• View Geometry Matching & Interpolation — Hero's 'Magic Move' core: it computes delta between source view frame/transform/opacity and destination, then linearly interpolates. Non-obvious: views must have same aspect ratio or interpolation looks wrong
• Gesture Recognizer Coordination with Animation State — Hero transitions are interruptible; you must coordinate gesture recognizer targets with the animator's state machine to avoid dropped frames or inconsistent state
• View Controller Transition Delegate Pattern — Hero plugs into UINavigationControllerDelegate, UIViewControllerTransitioningDelegate to vend custom animators; understanding delegation hooks is required to wire Hero into your ViewController
• CADisplayLink & Render Loop Synchronization — Hero likely syncs animations to the display refresh cycle (60 FPS on standard iPhone, 120 FPS on ProMotion); understanding frame-based vs time-based animation is critical for performance tuning

• Ramotion/folding-cell — Similar animation-focused iOS library; shows Ramotion's approach to custom UIView animations vs Hero's UIViewController transition focus
• ParkGrew/CleanArchitectureRxSwift — Demonstrates how to integrate Hero transitions into a Clean Architecture + RxSwift app structure for larger projects
• facebook/pop — Pop is Facebook's animation framework that Hero may internally use or complement; predecessor/companion for spring-physics-based transitions
• realm/realm-swift — Common dependency in iOS apps using Hero; shows patterns for integrating Hero with Realm-backed data in transitions
• Alamofire/Alamofire — Typical companion library in Hero-using apps; Hero handles UI transitions while Alamofire handles network layer for data driving those transitions

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 comprehensive unit tests for Hero transition engine core

The repo has GitHub Actions workflows for testing (.github/workflows/test.yml) and codecov integration (.codecov.yml), but the file structure shows no visible Tests/ or Sources/ directories. Hero's core transition logic likely lacks unit test coverage for critical paths like view controller transition lifecycle, animation timing, and gesture recognition. This directly impacts reliability of the declarative transition layer mentioned in the README.

• [ ] Examine .github/workflows/test.yml to understand current test setup
• [ ] Create Tests/ directory structure mirroring Sources/ (if it exists outside the provided file list)
• [ ] Add unit tests for transition initialization, frame calculations, and view snapshotting
• [ ] Add integration tests for gesture-driven transitions and interactive dismissal
• [ ] Ensure codecov.yml thresholds are met and integrate coverage reporting to CI

Complete SwiftLint configuration enforcement and add CI checks

The repo has .swiftlint.yml configuration and a GitHub Action workflow (.github/workflows/swiftlint.yml), but lacks clear enforcement in the build process. Given this is a widely-used UIKit library with multiple example files, adding strict linting gates to PR checks ensures code quality consistency across contributions.

• [ ] Review current .swiftlint.yml rules and enable stricter rulesets for production code
• [ ] Modify .github/workflows/swiftlint.yml to fail builds on warnings (not just errors)
• [ ] Add SwiftLint exceptions for Examples/ directory if needed, but enforce strict rules for core library code
• [ ] Document linting requirements in DEVELOP.md with setup instructions
• [ ] Configure Dangerfile to comment SwiftLint violations directly on PRs for visibility

Expand Example app documentation and add missing transition examples

The Examples/ directory contains several example files (AppStoreCardExample, BuiltInTransitionExample, MatchExample, MatchInCollectionExample) but lacks structured documentation. Given Hero's focus on declarative transitions, adding documented examples for common patterns (modals, custom gestures, interactive transitions) would significantly aid contributor understanding and serve as regression tests.

• [ ] Add README.md to Examples/ directory explaining each example's purpose and code structure
• [ ] Create a new example file for gesture-driven interactive transitions (e.g., GestureInteractiveExample.swift)
• [ ] Add code comments and inline documentation to existing example files explaining Hero-specific APIs used
• [ ] Link examples in main README.md and DEVELOP.md for easier onboarding
• [ ] Verify each example compiles and runs by integrating example builds into CI (.github/workflows/build.yml)

• Add tvOS-specific example: Create Examples/TVOSExample.swift demonstrating navigation gesture (remote swipe) driving an interactive Hero transition, since README claims tvOS support but Examples/ only shows iOS.: Visible gap: tvOS support is advertised but underdocumented with no tvOS-specific runnable example
• Expand MatchInCollectionExample.swift with doc comments: Add ///-style documentation explaining heroID matching inside UICollectionViewCell reuse cycles, which is a common gotcha developers hit.: Complex use case (cell reuse + heroID matching) lacks inline docs; would clarify for junior contributors
• Add unit tests for edge case: Create Tests/HeroModifierEdgeCaseTests.swift covering (1) nil heroModifiers, (2) heroID mismatch with fallback behavior, (3) concurrent gestures interrupting transitions, mirroring test.yml coverage expectations.: CI runs tests via test.yml but no test files visible in file list; test coverage likely incomplete for modifier edge cases

The Hero library demonstrates a reasonably secure posture for an iOS transition library. As a UI framework focused on view controller transitions, it has minimal surface area for common vulnerabilities like SQL injection or XSS. However, minor issues include deprecated CDN usage in documentation, absence of a security policy file for responsible disclosure, and inability to verify dependency security due to missing lock files. No hardcoded credentials or critical misconfigurations were identified. The codebase appears well-maintained with proper GitHub Actions workflows and linting configuration.

• Medium · Insecure CDN Link in README — README.md - Hero.svg image reference. The README references an SVG file from a raw GitHub CDN URL (cdn.rawgit.com). This service is deprecated and unreliable. While not a direct security vulnerability, it could be exploited if the domain is compromised or redirected. Modern alternatives like jsDelivr or GitHub's official CDN should be used. Fix: Replace 'https://cdn.rawgit.com/lkzhao/Hero/427d5f2/Resources/Hero.svg' with a more secure CDN or GitHub's raw.githubusercontent.com URL
• Low · Missing Security Policy File — Repository root. The repository does not contain a SECURITY.md or security policy file. This makes it difficult for security researchers to responsibly disclose vulnerabilities. Fix: Add a SECURITY.md file with instructions for responsible vulnerability disclosure and security contact information
• Low · Potential Exposure of Internal Configuration — .github/workflows/*.yml, .makefiles/*. Multiple makefiles and GitHub Actions workflows are present. While this is common, ensure that no sensitive environment variables or credentials are hardcoded in .github/workflows files or Makefiles. Fix: Review all workflow files and Makefiles to ensure no credentials, API keys, or sensitive data are hardcoded. Use GitHub Secrets for sensitive values
• Low · No Dependency Lock File Provided — Root directory / package management configuration. No Package.resolved, Podfile.lock, or similar dependency lock file was provided for analysis. This makes it impossible to identify if specific versions of dependencies contain known vulnerabilities. Fix: Ensure dependency lock files are committed to version control and regularly audit dependencies using tools like npm audit, pod audit, or OWASP Dependency-Check

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.