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/pkluz/PKHUD 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 3y ago

• 24+ active contributors
• Distributed ownership (top contributor 34% of recent commits)
• MIT licensed
• CI configured
• ⚠ Stale — last commit 3y ago
• ⚠ 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 pkluz/PKHUD repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pkluz/PKHUD.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pkluz/PKHUD(\\.git)?\\b" \\
  && ok "origin remote is pkluz/PKHUD" \\
  || miss "origin remote is not pkluz/PKHUD (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 "PKHUD/PKHUD.swift" \\
  && ok "PKHUD/PKHUD.swift" \\
  || miss "missing critical file: PKHUD/PKHUD.swift"
test -f "PKHUD/HUD.swift" \\
  && ok "PKHUD/HUD.swift" \\
  || miss "missing critical file: PKHUD/HUD.swift"
test -f "PKHUD/Window.swift" \\
  && ok "PKHUD/Window.swift" \\
  || miss "missing critical file: PKHUD/Window.swift"
test -f "PKHUD/PKHUDAnimation.swift" \\
  && ok "PKHUD/PKHUDAnimation.swift" \\
  || miss "missing critical file: PKHUD/PKHUDAnimation.swift"
test -f "PKHUD/PKHUDSquareBaseView.swift" \\
  && ok "PKHUD/PKHUDSquareBaseView.swift" \\
  || miss "missing critical file: PKHUD/PKHUDSquareBaseView.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 1209 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1179d)"
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/pkluz/PKHUD"
  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).

PKHUD is a Swift framework that reimplements Apple's native system HUDs (like volume, ringer, and rotation alerts) for iOS 8+. It provides a drop-in replacement using UIVisualEffectsView blur effects and includes built-in animated assets (checkmarks, progress spinners, cross icons) that developers can flash on-screen with a single method call like HUD.flash(.success, delay: 1.0). Simple, focused framework: core logic in PKHUD/ contains the main HUD controller (HUD.swift), animation protocol (PKHUDAnimating.swift), pre-built views (PKHUDProgressView.swift, PKHUDErrorView.swift), and asset management (PKHUDAssets.swift). A demo app in Demo/ showcases usage. No heavy dependencies—just UIKit + Swift stdlib, with SwiftLint configuration (.swiftlint.yml) for code quality.

iOS app developers who want to display system-style notifications and progress indicators without building custom UI from scratch. Particularly useful for teams targeting iOS 8+ who need Apple-like HUD behavior with proper device rotation support and minimal boilerplate.

Production-ready and stable. The repo has proper CI (Travis CI configured in .travis.yml), supports multiple dependency managers (CocoaPods, Carthage, SPM via PKHUD.podspec and Package.swift), and spans multiple Swift versions (2.0–4.x+). However, the last visible activity date is not provided in the file list, so recency cannot be confirmed; the framework's iOS 8 baseline is now legacy (iOS 8 EOL was 2016).

Low risk for well-maintained features, but potential staleness risk: the framework targets iOS 8 (released 2014) and there is no visible commit history provided to confirm active maintenance. The codebase is small and single-purpose, reducing dependency bloat, but a single-maintainer project (pkluz) with no visible open issues or recent updates could lag behind Swift/iOS SDK evolution. Check the actual GitHub repo for open issues and last commit date before adopting in new production code.

Unable to determine active work from the provided file structure; no recent commit messages, PR list, or milestone data are visible. The repo appears stable but potentially dormant—examine the GitHub Issues tab and recent commits to assess current maintenance level.

git clone https://github.com/pkluz/PKHUD.git
cd PKHUD
pod install  # or use Carthage (github "pkluz/PKHUD" ~> 4.0) or SPM
open PKHUD.xcodeproj  # or open the Xcode workspace if CocoaPods is used

Daily commands: Open PKHUD.xcodeproj in Xcode, select the 'PKHUD Demo' scheme, and press Cmd+R. Alternatively, from CLI: xcodebuild -scheme 'PKHUD Demo' -configuration Debug. The demo app (Demo/DemoViewController.swift) shows all HUD types in action.

• PKHUD/PKHUD.swift — Main entry point and singleton manager for the HUD system—all display operations route through this facade.
• PKHUD/HUD.swift — Core HUD view controller logic and lifecycle management; handles presentation, dismissal, and content updates.
• PKHUD/Window.swift — Custom UIWindow subclass that manages HUD window placement above app content; critical for overlay rendering.
• PKHUD/PKHUDAnimation.swift — Defines the animation protocol and default animations; enables all visual transitions in the HUD.
• PKHUD/PKHUDSquareBaseView.swift — Base view class for square HUD presentations; parent for Success, Error, and Progress variants.
• PKHUD/PKHUDAssets.swift — Centralized asset loader for images and resources; required for consistent visual styling across all HUD types.
• PKHUD/FrameView.swift — Layout container for HUD content with blur effect and visual framing; applies UIVisualEffectView for iOS HUD aesthetic.

Add a new HUD content view type

1. Create a new subclass of PKHUDSquareBaseView or PKHUDWideBaseView in PKHUD/ folder (PKHUD/PKHUDCustomView.swift)
2. Override setupUI() to configure your content (labels, images, etc.) (PKHUD/PKHUDCustomView.swift)
3. Add a convenience static method to PKHUD.swift to expose the new view type (PKHUD/PKHUD.swift)
4. Test in Demo/DemoViewController.swift by adding a button that calls your new method (Demo/DemoViewController.swift)

Add custom animation behavior

1. Create a new struct conforming to PKHUDAnimation protocol in PKHUD/ folder (PKHUD/PKHUDCustomAnimation.swift)
2. Implement entryAnimation() and exitAnimation() using CABasicAnimation or UIView.animate() (PKHUD/PKHUDCustomAnimation.swift)
3. Pass your animation to HUD.show(content:animation:) or set as default in PKHUD.swift (PKHUD/PKHUD.swift)

Add new asset (icon/image)

1. Add PDF or PNG to PKHUD/Images.xcassets/ in the appropriate imageset folder (PKHUD/Images.xcassets)
2. Register the asset name in PKHUDAssets.swift in the image(named:) method (PKHUD/PKHUDAssets.swift)
3. Use the new asset in your custom view by calling PKHUDAssets.image(named:) (PKHUD/PKHUDCustomView.swift)

Customize HUD styling (colors, blur effect, size)

1. Modify FrameView.swift to adjust blur style, frame insets, or corner radius (PKHUD/FrameView.swift)
2. Update PKHUDSquareBaseView.swift or PKHUDWideBaseView.swift for layout changes (PKHUD/PKHUDSquareBaseView.swift)
3. Adjust Window.swift safe area insets or positioning logic if needed (PKHUD/Window.swift)

• UIVisualEffectView with UIBlurEffect — Native iOS blur effect matching system HUDs (Volume, Ringer); provides performance and consistency.
• Custom UIWindow subclass — Ensures HUD renders above all view controllers, alerts, and presented content without z-order conflicts.
• CABasicAnimation + UIView.animate() — Smooth entry/exit transitions; protocol-driven design allows custom animations without framework coupling.
• Asset Catalog (xcassets) with PDF images — Vector-based assets scale without pixelation on all device sizes; centralized resource management.
• Swift with no external dependencies — Lightweight, easy to integrate; minimal app bundle impact; reduces dependency tree complexity.

• Single custom UIWindow for all HUD instances

  • Why: Simplifies window management and avoids multiple key windows competing.
  • Consequence: Only one HUD can be displayed at a time; queuing/stacking not supported.

• View-based animations instead of CADisplayLink

  • Why: Simpler API and less boilerplate; leverages UIView's built-in animation system.
  • Consequence: Less precise control over frame-by-frame animation; less suitable for real-time progress curves.

• Static PKHUD singleton instead of instance manager

  • Why: Easy, zero-setup usage—developers don't manage lifecycle.
  • Consequence: Not thread-safe; assumes main thread usage; harder to test in isolation.

• PDF + image assets in bundle instead of programmatic drawing

  • Why: Designer-friendly; consistent styling; easy to customize without code changes.
  • Consequence: Larger bundle size; asset duplication if shared across projects.

• Real-time progress tracking (no continuous callbacks or observables)
• Accessibility features (no VoiceOver narration or dynamic type support emphasized)
• Multi-window HUD stacking or queuing
• Custom content view composition with SwiftUI (UIKit-only)
• Thread-safe concurrent HUD displays
• Rotation animations or device-agnostic transforms beyond standard iOS rotation

• UIVisualEffectView availability: The framework assumes iOS 8+, but UIVisualEffectsView behaves differently across iOS versions; test on target OS versions if customizing blur effects.
• Main thread requirement: HUD operations must run on the main thread; background thread calls will silently fail or crash with no clear error.
• Rotation handling: The README advertises 'proper rotation support', but this relies on correct superview setup (UIApplication.shared.windows[0]); non-standard view hierarchies may break auto-layout.
• Asset naming: Image assets in PKHUD/Images.xcassets/ must exactly match filenames referenced in PKHUDAssets.swift; typos cause runtime nil crashes.
• No explicit testing framework visible: No /Tests directory in the file list; the project may lack unit test coverage.

• UIVisualEffectsView and Blur Effect Composition — PKHUD's core visual identity relies on UIVisualEffectsView to match iOS system HUDs; understanding blur effect rendering, transparency, and vibrancy is essential for customizing the framework's appearance
• Protocol-based View Architecture (PKHUDAnimating) — The framework uses Swift protocols to define animatable content without inheritance; this pattern allows injecting arbitrary custom views into HUDs—a key extensibility mechanism
• Core Animation (CABasicAnimation, CADisplayLink) — Spinning progress indicators and animated assets rely on Core Animation for smooth, efficient frame-by-frame updates; understanding CABasicAnimation is required to modify or extend animations
• Window-level View Hierarchy and Safe Area — PKHUD floats above normal view controllers by inserting itself into UIApplication.shared.windows[0]; proper Safe Area and rotation handling depend on deep understanding of iOS window management
• Auto Layout and Trait Collection for Device Agnosticism — The README claims 'Size/Device agnostic' behavior; this is achieved through constraint-based layout and trait collection observers, not fixed frame sizes—critical for iPad/iPhone support
• Singleton Pattern (HUD.shared) — PKHUD exposes a global singleton HUD for convenience; understanding singleton risks (state leakage, testing complexity) is important for working with or extending the framework
• Asset Catalogs and PDF Vector Assets — PKHUD stores icons (checkmark, cross, progress) as .pdf files in Images.xcassets; understanding Xcode's vector asset rendering and @1x/@2x/@3x scaling is needed to add or modify assets

• loopeer/DGActivityIndicatorView — Alternative animated activity indicator library for iOS; useful for comparing different spinner animation techniques and design patterns
• SVProgressHUD/SVProgressHUD — Older, widely-used HUD library (Objective-C era); PKHUD is a modern Swift successor; comparing API and feature set is instructive
• jrendel/SwiftKeychainWrapper — Common companion library for iOS projects; examples of clean Swift wrapping patterns around system frameworks, similar to PKHUD's UIVisualEffectsView pattern
• apple/swift-evolution — Swift language and stdlib evolution; relevant for understanding why PKHUD's protocol-based design (PKHUDAnimating) is idiomatic modern Swift

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 UIKit integration tests for PKHUDAnimating protocol conformance

The repo has PKHUDAnimating.swift and multiple view classes (PKHUDSuccessView, PKHUDErrorView, PKHUDProgressView, etc.) that implement animation protocols, but PKHUDDemoUITests/PKHUDDemoUITests.swift appears minimal. Add comprehensive UI tests validating animation lifecycle, frame transitions, and state management for each HUD view type to prevent regressions.

• [ ] Review existing PKHUDDemoUITests/PKHUDDemoUITests.swift to understand current coverage
• [ ] Create test cases for PKHUDSuccessView, PKHUDErrorView, and PKHUDProgressView animation start/stop cycles
• [ ] Add tests for Window.swift and WindowRootViewController.swift lifecycle and view hierarchy
• [ ] Verify animations complete within expected timing using XCTestExpectation
• [ ] Add tests for rotation support (mentioned in README) by simulating device orientation changes

Migrate .travis.yml CI to GitHub Actions workflow

The project uses .travis.yml for CI/CD, but GitHub Actions is now the standard. The repo has fastlane configuration (Appfile, Fastfile, Scanfile) that can be leveraged. Migrate to GitHub Actions to reduce external dependencies and provide faster feedback with native GitHub integration.

• [ ] Create .github/workflows/ci.yml with jobs for building PKHUD scheme and PKHUDDemoUITests scheme
• [ ] Integrate existing fastlane scan command from fastlane/Scanfile into the workflow
• [ ] Add SwiftLint validation step using .swiftlint.yml configuration
• [ ] Set up SPM build verification (Package.swift) and CocoaPods build verification
• [ ] Test workflow locally and remove or archive .travis.yml after verification

Add comprehensive documentation for PKHUDView subclasses in PKHUD.swift

The main PKHUD.swift file likely contains the public API and HUD presentation logic, but there's no dedicated API documentation file. Create a DOCUMENTATION.md or API_GUIDE.md with code examples for each view type (PKHUDSuccessView, PKHUDErrorView, PKHUDTextView, etc.) and animation customization using PKHUDAnimation.swift, filling the gap mentioned in the incomplete README.

• [ ] Examine PKHUD.swift, HUD.swift, and PKHUDAnimation.swift to document public APIs and initialization patterns
• [ ] Create DOCUMENTATION.md with sections: Basic Usage, View Types, Custom Animations, and Rotation Handling
• [ ] Add code examples for each PKHUDSquareBaseView and PKHUDWideBaseView subclass from the Images.xcassets
• [ ] Document Window.swift and WindowRootViewController.swift presentation behavior
• [ ] Include examples using both direct PKHUD.show() calls and custom FrameView.swift implementations

• Add unit tests for PKHUD/HUD.swift public API methods (flash, show, hide) in a new Tests/HUDTests.swift file—the repo has no visible test suite, and core functionality lacks coverage.
• Document the PKHUDAnimating protocol with code examples in a new PKHUD/PKHUDAnimating.swift docstring or separate ANIMATING_PROTOCOL.md file, showing how to create a custom spinner or animated icon (currently undocumented).
• Add a PKHUDCustomView example to Demo/DemoViewController.swift that shows users how to pass a custom UIView+PKHUDAnimating object to HUD.show() instead of using built-in types—closes a common documentation gap.

PKHUD is a lightweight UI library with minimal security attack surface. No critical vulnerabilities identified. The codebase shows good security practices: it's a pure Swift UI implementation with no network calls, database operations, or external data processing visible. Primary recommendations focus on dependency management best practices for the build toolchain (Ruby gems, Swift packages) and standard iOS development practices. The library itself handles only UI rendering and animation, making injection attacks and data exposure risks extremely low.

• Low · Missing dependency pinning in Package.swift — Package.swift. The Package.swift file is not provided in the analysis, making it impossible to verify if Swift Package Manager dependencies are properly pinned to specific versions. This could lead to unexpected updates with potential vulnerabilities. Fix: Ensure all dependencies in Package.swift are pinned to specific, known-good versions. Regularly audit and update dependencies after security testing.
• Low · Gemfile present without lock file verification — Gemfile, Gemfile.lock. A Gemfile is present (likely for fastlane and CI/CD tools), but without visibility into the actual dependencies and their versions, there's potential for supply chain risks. Fix: Ensure Gemfile.lock is committed and reviewed. Use bundle audit to check for known vulnerabilities in Ruby dependencies used in the build pipeline.
• Low · No apparent code signing verification visible — PKHUD.xcodeproj/project.pbxproj. While this is an open-source UI library, the presence of Demo and test targets without visible code signing configurations could impact distribution security. Fix: Ensure proper code signing identities are configured for all targets. Use automatic code signing or maintain secure provisioning profiles.

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.