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/ninjaprox/NVActivityIndicatorView 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 8w ago
• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 85% 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 ninjaprox/NVActivityIndicatorView repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ninjaprox/NVActivityIndicatorView.

What it runs against: a local clone of ninjaprox/NVActivityIndicatorView — 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 ninjaprox/NVActivityIndicatorView | 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 | Last commit ≤ 83 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ninjaprox/NVActivityIndicatorView(\\.git)?\\b" \\
  && ok "origin remote is ninjaprox/NVActivityIndicatorView" \\
  || miss "origin remote is not ninjaprox/NVActivityIndicatorView (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"

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

NVActivityIndicatorView is a Swift library providing 32+ pre-built loading animation styles (ballPulse, ballGridPulse, audioEqualizer, pacman, etc.) with customizable colors and sizes. It eliminates the need to hand-code loading spinners and provides polished, reusable animations as a UIView subclass that integrates directly into iOS apps. Flat library structure: Sources/Base/Animations/ contains 30+ animation subclasses (each file implements one animation type like NVActivityIndicatorAnimationBallPulse.swift), likely inheriting from a common protocol. Example/ contains a runnable iOS app demonstrating all animations. Build configured for both CocoaPods (.podspec) and SPM (Package.swift).

iOS developers building Swift apps who need drop-in loading indicators without writing custom Core Animation code. Used by teams wanting consistent, professional-looking spinners across their UIKit or SwiftUI workflows.

Production-ready and actively maintained. The repo has CocoaPods/Carthage/SPM support, CI/CD via GitHub Actions (see .github/workflows/ios.yml), comprehensive animation catalog (32 types in Sources/Base/Animations/), and a working Example app. Recent updates suggest ongoing maintenance; version 5.0.0+ indicates semantic versioning discipline.

Low risk: single-purpose, no external dependencies (pure Core Animation), small Swift codebase (~197KB Swift code). Single maintainer (ninjaprox) is a potential long-term risk, but the stable API and lack of dependency churn mitigate concerns. No evidence of breaking changes in CHANGELOG between major versions.

No specific active PRs visible in file list, but SwiftUI migration is acknowledged in README (points to LoaderUI as the SwiftUI counterpart). The privacy manifest (PrivacyInfo.xcprivacy) suggests recent iOS 17+ compliance work. Linting and build automation are in place (.swiftlint.yml, iOS CI workflow).

git clone https://github.com/ninjaprox/NVActivityIndicatorView.git
cd NVActivityIndicatorView
pod install  # if using CocoaPods locally
# Or open NVActivityIndicatorView.xcodeproj in Xcode and run the Example scheme

Daily commands: Open NVActivityIndicatorView.xcodeproj in Xcode, select the Example scheme, and press ⌘R. Or from CLI: xcodebuild -scheme Example -configuration Debug -derivedDataPath build build-for-testing | xcpretty.

• Sources/Base/Animations: Directory containing all 30+ animation implementations; each file is a concrete animation type that developers can study for patterns
• Example/ViewController.swift: Demo controller that showcases all animation types and serves as integration test / documentation
• NVActivityIndicatorView.podspec: CocoaPods manifest defining version, dependencies, and deployment targets
• Package.swift: Swift Package Manager manifest for SPM-based installations
• .github/workflows/ios.yml: CI/CD pipeline running tests and builds on push; reveals build matrix and test expectations
• .swiftlint.yml: SwiftLint configuration enforcing code style across all animations

To add a new animation: create a new file in Sources/Base/Animations/NVActivityIndicatorAnimation<YourName>.swift following the pattern of existing files (e.g., NVActivityIndicatorAnimationBallPulse.swift). Update Example/ViewController.swift to register the new animation in the demo list. Run linting: swiftlint (configured in .swiftlint.yml).

No hidden environment variables or service dependencies. The only gotcha is that animations are GPU-accelerated Core Animation, so heavy UI changes on the main thread during animation playback may cause stuttering. If using in a view hierarchy with many layers, disable rasterization on parent views. No database or network setup required.

• CABasicAnimation & CAKeyframeAnimation — Core Animation primitives used by nearly every animation file to define rotation, scaling, and positional motion paths; understanding these is essential to extending the library
• CAAnimationGroup — Technique used to synchronize multiple simultaneous animations (e.g., ballGridBeat has multiple balls animating in sync); critical for complex multi-element animations
• CADisplayLink & Rendering Loop — Implicit refresh rate synchronization that Core Animation handles; understanding CADisplayLink helps optimize performance of chained animations on high-refresh displays (120Hz iPad Pro)
• Layer Hierarchy & Transform3D — Many animations use CATransform3D for 3D rotations (ballRotate, cubeTransition); misunderstanding perspective can cause unexpected visual behavior
• Easing Curves (CAMediaTimingFunction) — Each animation uses CAMediaTimingFunction (linear, easeInEaseOut, etc.) to control pacing; swapping functions changes perceived responsiveness of spinners
• UIView Layer-backed Rendering — NVActivityIndicatorView is a UIView subclass that delegates visual work to its underlying CALayer; inefficient layer hierarchies can cause jank during scrolling or complex view updates
• Swift Protocol-based Polymorphism — The library likely uses a protocol (not visible in file list snippet) to define animation interface; understanding how each animation conforms to a shared protocol aids adding new animation types

• ninjaprox/LoaderUI — Official SwiftUI wrapper/successor to this library; use this if targeting SwiftUI apps instead of UIKit
• lottie-ios/lottie-ios — Alternative animation library with JSON-driven, After Effects-based animations; heavier but more flexible than hardcoded animations
• mac-gallagher/Loaf — Toast/notification library often paired with loading indicators for user feedback workflows
• exyte/PopupView — UIKit/SwiftUI overlay container commonly used to host loading spinners centrally over content

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 animation implementations in Sources/Base/Animations/

The repo has 30+ animation implementations (BallBeat, BallRotate, LineScale, etc.) but no visible test files. Adding unit tests would ensure animation timing, frame counts, and layer configurations are correct, preventing regressions when animations are modified. This is critical for a library focused on visual animations.

• [ ] Create Tests/ directory structure mirroring Sources/Base/Animations/
• [ ] Add unit tests for 5-10 core animations (e.g., BallPulse, LineScale, BallRotate) testing animation duration, layer setup, and transform calculations
• [ ] Test NVActivityIndicatorAnimationDelegate protocol conformance across animation types
• [ ] Add tests to verify NVActivityIndicatorShape enum cases render correctly
• [ ] Integrate test target into NVActivityIndicatorView.xcodeproj and .github/workflows/ios.yml

Add comprehensive example screens for each animation type in Example/ViewController.swift

The Example app exists but ViewController.swift likely only shows a subset of the 30+ animations. A complete showcase with all animation types, configurable parameters (colors, sizes, speeds), and descriptions would improve discoverability and help contributors understand each animation's visual behavior.

• [ ] Refactor Example/ViewController.swift to use a UITableViewController or UICollectionViewController displaying all animation types from NVActivityIndicatorViewAnimationType enum
• [ ] Add a detail screen showing individual animation with controls for color, size, and speed adjustments
• [ ] Create an AnimationTypeCell with labels matching animation names from Sources/Base/Animations/ files
• [ ] Update Example/Base.lproj/Main.storyboard to support the new layout structure

Add Swift Package Manager resources and example in Package.swift with platform-specific tests

The repo has Package.swift and .swiftpm/ folder structure, but lacks explicit iOS version targeting and organized test targets. Adding platform specifications and integrating with .github/workflows/ios.yml would ensure SPM compatibility across iOS versions and catch build issues early.

• [ ] Update Package.swift to explicitly define .iOS(.v12) or appropriate minimum deployment target and supported platforms (iOS, macOS, tvOS)
• [ ] Add a testTarget in Package.swift linking to test files created in Sources/Tests/ (not yet present, would be created in PR #1)
• [ ] Add Swift Package Manager build step to .github/workflows/ios.yml: swift build and swift test commands
• [ ] Document SPM integration in README.md with installation instructions and version compatibility matrix

• Write unit tests for 2–3 animation classes in Sources/Base/Animations/ (e.g., NVActivityIndicatorAnimationBallPulse.swift); currently, test files are not visible in the file list, suggesting test coverage gaps.
• Add documentation comments to the animation classes using Swift doc-comment syntax (///) so Jazzy (see .jazzy.yaml) can generate API docs; many animation files lack docstrings.
• Create a comparison guide in the README with before/after GIFs showing each of the 32 animations side-by-side, since the single Demo.gif only hints at the full palette.

The NVActivityIndicatorView repository shows a generally strong security posture. It's a UI library with no external dependencies, hardcoded secrets, injection risks, or database operations visible. The codebase consists primarily of animation rendering logic with minimal attack surface. Main recommendations include adding a security policy, enhancing SAST tooling in CI/CD, and ensuring proper code review practices for Objective-C interop code. No critical or high-severity vulnerabilities were identified in the provided file structure.

• Low · Missing SAST Configuration — .swiftlint.yml. The repository uses SwiftLint (.swiftlint.yml) but lacks comprehensive static analysis configuration. Consider adding additional SAST tools to catch security-related code issues. Fix: Integrate additional security scanning tools like Semgrep or dedicated Swift security linters to the CI/CD pipeline.
• Low · Potential Information Disclosure via Documentation — docs/. The repository generates and commits documentation in the /docs directory. While documentation itself is not sensitive, ensure build artifacts and generated files are properly reviewed before commit. Fix: Add documentation output to .gitignore if it's auto-generated, or ensure sensitive information is never included in generated docs.
• Low · Missing Security Policy — Repository root. No SECURITY.md or security policy file found in the repository. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process and contact information.
• Low · Bridging Header in Tests — Tests/Tests-Bridging-Header.h. The presence of Tests-Bridging-Header.h suggests Objective-C interoperability. While not inherently a security risk, ensure proper validation of any Objective-C code interfacing with Swift. Fix: Review any Objective-C code for memory safety issues and ensure proper ARC usage.

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.