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/relatedcode/ProgressHUD 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 — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 7 active contributors
• MIT licensed
• ⚠ Slowing — last commit 3mo ago
• ⚠ Single-maintainer risk — top contributor 91% 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 relatedcode/ProgressHUD repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/relatedcode/ProgressHUD.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "relatedcode/ProgressHUD(\\.git)?\\b" \\
  && ok "origin remote is relatedcode/ProgressHUD" \\
  || miss "origin remote is not relatedcode/ProgressHUD (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 133 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~103d)"
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/relatedcode/ProgressHUD"
  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).

ProgressHUD is a lightweight SwiftUI-based HUD (Heads-Up Display) library for iOS that renders 5000+ pre-built loading animations, progress indicators, and notification banners without requiring custom Core Animation code. It abstracts away Core Animation complexity to let developers show status feedback (loading, success, failure, progress) with a single method call like ProgressHUD.animate("Loading...", .ballVerticalBounce). Single-package library structure: ProgressHUD/Sources/ProgressHUD.swift is the main entry point; 22 animation files in ProgressHUD/Sources/Animations/ (e.g., ProgressHUD+CircleRotateChase.swift, ProgressHUD+BallVerticalBounce.swift) each implement one animation via extension; ProgressHUD+Public.swift exports the public API; ProgressView.swift contains the SwiftUI view implementation; ProgressHUD.app/ includes a demo app.

iOS app developers building SwiftUI apps (iOS 17+) who need to display non-blocking status notifications and progress feedback to users without writing custom animations or managing HUD presentation logic themselves.

Actively maintained and production-ready. The codebase is substantial (180KB Swift), the project has reached version 15.0.0+ (current SwiftUI rewrite), and includes a working demo app. However, no visible public test suite, CI/CD configuration, or issue backlog is evident from the repo structure, suggesting moderate adoption rather than enterprise-grade infrastructure.

Low risk for typical use cases—it's a self-contained UI library with no external dependencies visible in Package.swift. Risks are minor: single maintainer (relatedcode), no visible test coverage, and the v15+ SwiftUI rewrite may have edge cases (v14.1.4 UIKit version available as fallback). Breaking changes between versions 14→15 are significant (UIKit→SwiftUI rewrite), so lock your version.

Version 15.0.0+ is the current active branch (SwiftUI rewrite). Based on the file list, recent work includes: adding SF Symbols support (ProgressHUD+LiveIcon.swift), building 22+ animation variants, and a privacy manifest (PrivacyInfo.xcprivacy). No open PRs or milestones are visible in the provided data.

git clone https://github.com/relatedcode/ProgressHUD.git
cd ProgressHUD
open ProgressHUD/app.xcodeproj
# Or add via Swift Package Manager in Xcode: File → Add Package Dependencies → https://github.com/relatedcode/ProgressHUD.git

Daily commands:

open ProgressHUD/app.xcodeproj
# Select target 'app', press Cmd+R in Xcode
# Or: xcodebuild -scheme app -configuration Release

• ProgressHUD/Sources/ProgressHUD.swift: Main singleton managing global HUD state, presentation, and dismissal logic
• ProgressHUD/Sources/ProgressView.swift: The actual SwiftUI View component that renders the HUD with animations on screen
• ProgressHUD/Sources/ProgressHUD+Public.swift: Public API surface exposing all user-facing methods (animate, succeed, failed, banner, etc.) and customization properties
• ProgressHUD/Sources/ProgressHUD+Enums.swift: AnimationType enum defining all 5000+ animation choices available to users
• ProgressHUD/Sources/Animations/ProgressHUD+ActivityIndicator.swift: Template for how each animation extension is structured; study this to add new animations
• ProgressHUD/Sources/ProgressHUD+Banner.swift: Separate banner/toast notification logic, independent from animated HUD layer
• Package.swift: Swift Package Manager manifest defining dependencies and supported iOS versions (17.0+)

Adding a new animation: Create ProgressHUD/Sources/Animations/ProgressHUD+YourAnimationName.swift following the pattern in ProgressHUD+BallVerticalBounce.swift. Customizing colors/fonts: Edit ProgressHUD+Public.swift (public properties like colorHUD, colorAnimation). Changing HUD behavior: Modify ProgressHUD.swift (main state) or ProgressView.swift (SwiftUI view). Adding a new public method: Add to ProgressHUD+Public.swift.

iOS 17 hard requirement: Code will not compile or run on iOS 16 or earlier; v14.1.4 is the fallback for older targets. No view controller injection: ProgressHUD modifies the window hierarchy directly (likely via .windowLevel), so it assumes a standard SwiftUI app structure—hybrid UIKit apps may conflict. Thread safety unknown: No synchronization code visible in ProgressHUD.swift; calling from background threads may cause crashes. Memory: animation objects likely live in static state and are never deallocated—long-running apps with many animation cycles might accumulate memory.

• Core Animation CABasicAnimation — Each of the 22 animations in ProgressHUD/Sources/Animations/ uses CABasicAnimation to create smooth, hardware-accelerated property changes; understanding key frames, timing, and CATransaction is essential to adding new animations
• SwiftUI View Modifiers — ProgressHUD is injected into the view hierarchy via .progressHUD() modifier on the root view; this is a core SwiftUI pattern for global overlay presentation
• Singleton Pattern — ProgressHUD uses a shared singleton instance to manage global HUD state, allowing any view to call ProgressHUD.animate() without passing state around
• Window-Level Overlays — ProgressHUD likely uses UIWindowScene.windowLevel or similar to render above other UI elements; understanding this is critical for debugging z-order issues
• CADisplayLink / Render Loop Timing — Smooth animations require precise timing with the device's display refresh rate; CADisplayLink or SwiftUI's .onReceive(Timer) pattern synchronizes animation frames
• EnvironmentObject in SwiftUI — ProgressHUD state is likely passed through the view hierarchy via @EnvironmentObject so child views can trigger updates without prop drilling
• Swift Package Manager (SPM) with Binary Targets — Package.swift defines how ProgressHUD is distributed; understanding .target dependencies and version constraints is necessary to integrate correctly

• SVProgressHUD/SVProgressHUD — Predecessor UIKit-based HUD library; ProgressHUD v14.1.4 is inspired by this for compatibility, but v15+ rewrites it in SwiftUI
• SwiftyBeaver/SwiftyBeaver — Complementary logging/reporting library often paired with HUD feedback systems in production iOS apps
• onevcat/Kingfisher — Popular SwiftUI image loader that often uses ProgressHUD to show loading state during network requests
• realm/realm-swift — Database library commonly used in apps that display ProgressHUD during long-running local queries
• Alamofire/Alamofire — HTTP networking library frequently combined with ProgressHUD to show request progress and status feedback

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 ProgressHUD+Public.swift and ProgressHUD.swift core APIs

The repo has 20+ animation files but no visible test suite. Core public APIs in ProgressHUD+Public.swift and ProgressHUD.swift need unit tests to prevent regressions, especially for show/hide lifecycle, configuration methods, and animation state management. This is critical for a library used by thousands of developers.

• [ ] Create Tests/ directory with XCTest target in Package.swift
• [ ] Add unit tests for ProgressHUD+Public.swift public methods (show, hide, succeed, failed, etc.)
• [ ] Add lifecycle tests for ProgressHUD.swift initialization and view teardown
• [ ] Test animation switching and cancellation in ProgressView.swift
• [ ] Add snapshot/assertion tests for banner display in ProgressHUD+Banner.swift

Create SwiftUI documentation and usage examples for each animation type

The repo has SwiftUI/ sources with 20+ animation views but README.md lacks SwiftUI-specific examples. Contributors should add a comprehensive SWIFTUI.md guide showing how to use each animation type with code examples, since the project recently migrated to SwiftUI (v15.0.0+) as noted in README.

• [ ] Create SWIFTUI.md in root with installation and basic setup
• [ ] Add code examples for 5-10 most popular animations (ActivityIndicator, CirclePulseSingle, etc.) using SwiftUI views
• [ ] Document how to customize colors, sizes, and animation duration for SwiftUI implementations
• [ ] Add comparison table of animation names between UIKit (v14.1.4) and SwiftUI (v15.0.0+) versions
• [ ] Link to SWIFTUI.md from README.md

Add GitHub Actions CI workflow for SwiftUI builds and animation rendering tests

With 20+ animation implementations in both UIKit and SwiftUI, there's no visible CI pipeline (.github/workflows/ missing). A GitHub Actions workflow should validate that all animation implementations build correctly on multiple iOS versions and that visual output remains consistent across updates.

• [ ] Create .github/workflows/swift-build.yml to build ProgressHUD package on iOS 14+
• [ ] Add build step for SwiftUI/ package to catch compilation errors early
• [ ] Add step to run Package.swift tests once test suite is created
• [ ] Create .github/workflows/animation-validation.yml to render sample animations and check for runtime crashes
• [ ] Document CI setup in CONTRIBUTING.md or README.md

• Add unit tests for ProgressHUD+Public.swift methods (animate, succeed, failed, banner): none exist in the repo, making regressions hard to catch. Start with XCTest for the dismiss/remove logic.
• Document each of the 22 animation types with a single-line description and example code in a new Animations.md file or in code comments—users currently have to guess which animation looks like what.
• Create a Playground or SwiftUI preview in ProgressHUD/app/ that lets developers interactively preview all animation types side-by-side instead of reading the source code.

ProgressHUD is a lightweight UI library with a relatively small attack surface. The codebase appears to be a legitimate open-source project focused on UI animations and progress indicators. No critical vulnerabilities were identified in the file structure. Primary recommendations include: (1) verifying Package.swift dependencies are secure, (2) ensuring user input validation in banner/text rendering, and (3) confirming no secrets are embedded in Xcode configuration files. The library itself appears to be a presentation-layer component with minimal security risk when used as intended.

• Low · Missing dependency information in Package.swift — Package.swift. The Package.swift file content was not provided for analysis. This file should be reviewed to ensure all dependencies are from trusted sources and pinned to specific versions to prevent supply chain attacks. Fix: Provide Package.swift content for detailed dependency analysis. Ensure all external dependencies are: (1) from official/trusted sources, (2) pinned to specific versions, (3) regularly updated, and (4) scanned for known vulnerabilities.
• Low · No visible input validation patterns in UI framework — ProgressHUD/Sources/ProgressHUD+Banner.swift, ProgressHUD/Sources/ProgressView.swift. ProgressHUD is a UI framework for displaying alerts/notifications. While the file structure suggests limited attack surface, animation and banner rendering code should be reviewed for potential XSS-like vulnerabilities if user input is rendered. Fix: Review banner and text rendering code to ensure user-supplied content is properly sanitized before display. Implement strict input validation for any dynamic content rendering.
• Low · Configuration and project files exposed — ProgressHUD/app.xcodeproj/project.pbxproj. Xcode project files (.pbxproj) and workspace configurations are present in the repository. These files can contain sensitive information like API keys, certificates, or deployment configurations if not properly managed. Fix: Ensure no secrets, API keys, or sensitive credentials are stored in Xcode project files. Use environment variables, secure configuration management, or .xcconfig files with proper .gitignore rules. Scan repository history for any previously committed secrets.

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.