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/andreamazz/AMPopTip 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

• 14 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 75% 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 andreamazz/AMPopTip repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/andreamazz/AMPopTip.

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

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

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

# 4. Critical files exist
test -f "AMPopTip.podspec" \\
  && ok "AMPopTip.podspec" \\
  || miss "missing critical file: AMPopTip.podspec"
test -f "AMPopTip/AMPopTip.h" \\
  && ok "AMPopTip/AMPopTip.h" \\
  || miss "missing critical file: AMPopTip/AMPopTip.h"
test -f ".github/workflows/Test.yml" \\
  && ok ".github/workflows/Test.yml" \\
  || miss "missing critical file: .github/workflows/Test.yml"
test -f "AMPopTip.xcodeproj/project.pbxproj" \\
  && ok "AMPopTip.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: AMPopTip.xcodeproj/project.pbxproj"
test -f "Demo/Podfile" \\
  && ok "Demo/Podfile" \\
  || miss "missing critical file: Demo/Podfile"

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

AMPopTip is a Swift-based animated popover UI component that displays contextual tips and onboarding messages by popping out from a specified frame with an arrow pointing to the origin. It allows developers to show subtle, visually polished hints with customizable direction (up, down, left, right, none, or auto), colors, fonts, and border radius without building popover logic from scratch. Single-framework structure: core popover logic lives in AMPopTip/ (main Swift source), with a Demo/ directory containing a CocoaPods-based example app. AMPopTip.podspec defines the package for CocoaPods distribution, and test infrastructure is in .github/workflows/. No monorepo; straightforward library layout.

iOS app developers building user onboarding flows, feature discovery overlays, and contextual UI tips who need a production-ready popover component that handles arrow positioning and animation automatically.

Actively maintained and production-ready. The library has been through major version updates (v2.0 rewrote in Swift, v3.0+ added Swift 4+ support), includes CI via GitHub Actions (see .github/workflows/Test.yml), snapshot testing with Nimble-Snapshots, and a working demo app. Recent activity visible in versioning and CI setup indicates ongoing care.

Low risk for a UI component library. Single maintainer (andreamazz) is a potential concern for long-term support, but the codebase is small (~65K Swift), well-tested with snapshot tests, and has no external dependencies beyond test frameworks. The API is stable post-v2.0; breaking changes are documented in CHANGELOG.md.

The repository appears stable with infrequent updates. The CI pipeline (Test.yml) is configured and presumably runs on commits. No active feature branches or PRs are evident from the file list, suggesting the library is in maintenance mode rather than active development.

Clone the repo, navigate to Demo/, and install dependencies: git clone https://github.com/andreamazz/AMPopTip.git && cd Demo && pod install && open *.xcworkspace. Then build and run the demo in Xcode.

Daily commands: Open Demo/AMPopTip.xcworkspace in Xcode and run the AMPopTip scheme. The demo app will launch showing interactive examples of PopTip in various directions and configurations.

• AMPopTip.podspec — Pod specification defining the library version, dependencies, and deployment targets—essential for understanding distribution and compatibility requirements.
• AMPopTip/AMPopTip.h — Public header file exposing the main AMPopTip API; all contributors need to understand the public interface contract.
• .github/workflows/Test.yml — CI/CD pipeline configuration that validates builds and tests; critical for understanding how code is validated before merge.
• AMPopTip.xcodeproj/project.pbxproj — Xcode project configuration file defining build targets, schemes, and dependencies—must be understood when modifying build setup.
• Demo/Podfile — Demo app's dependency manifest showing how AMPopTip is consumed; essential for understanding real-world usage patterns and test setup.

• AMPopTip (Swift, Core Animation, UIView, CABasicAnimation) — Main popover component managing appearance, positioning, and animation lifecycle
  • Failure mode: If frame calculation is invalid, popover may render off-screen or with incorrect positioning
• Gesture Handlers (UIGestureRecognizer) — Responds to user tap/touch events to dismiss popover
  • Failure mode: If gesture not properly attached, popover cannot be dismissed by user
• Pod Distribution (CocoaPods, Carthage, podspec) — Packages and distributes the library via CocoaPods/Carthage to consumer projects
  • Failure mode: Broken podspec or missing files prevents installation in consumer projects

• Developer Code → AMPopTip Instance — Configuration properties (text, color, direction) passed to popover
• AMPopTip Instance → Target UIView Frame — Reads target view frame coordinates to determine popover position and arrow direction
• Core Animation → Screen Rendering — CABasicAnimation calculates interpolated transform/opacity values each frame for smooth pop-out animation
• User Gesture → AMPopTip Instance — Tap gesture triggers dismiss animation and removal from view hierarchy

Customize popover appearance

1. Reference the AMPopTip.h header to see available styling properties (color, border radius, font, etc.) (AMPopTip/AMPopTip.h)
2. Set properties on AMPopTip instance such as backgroundColor, borderColor, borderWidth, cornerRadius, and font before calling show() (AMPopTip/AMPopTip.h)

Control popover direction and positioning

1. Check the public API in AMPopTip.h for direction parameter options (e.g., up, down, left, right) (AMPopTip/AMPopTip.h)
2. Call show() with a frame and direction parameter to position the popover relative to UI elements (AMPopTip/AMPopTip.h)

Add tests for visual regression

1. Add test case in Demo project following Nimble BDD syntax (Demo/Podfile)
2. Use Nimble-Snapshots library to capture and compare popover visual output (Demo/Pods/Nimble-Snapshots/Nimble_Snapshots/HaveValidSnapshot.swift)
3. Run tests via GitHub Actions CI pipeline on push (.github/workflows/Test.yml)

• Swift — Modern, type-safe iOS development language; version 2.0+ rewrote library from Objective-C for better maintainability and modern syntax
• Core Animation (CABasicAnimation) — Provides smooth, hardware-accelerated pop-out animations for the popover appearance
• CocoaPods & Carthage — Standard iOS dependency managers enabling easy integration into consumer projects
• GitHub Actions — Native CI/CD for automated testing on every commit and pull request

• Rewrote from Objective-C (v1.5.x) to Swift (v2.0+)

  • Why: Modern language features, safer APIs, better tooling support
  • Consequence: Breaking API changes; existing Objective-C projects must remain on v1.5.x branch

• Single animated popover component vs. composable popup system

  • Why: Focused, simple API for the common use case of UI hints and onboarding
  • Consequence: Not suitable for complex multi-popover workflows or nested popovers

• Does not provide accessibility features (VoiceOver labels, semantic descriptions)
• Does not handle complex touch interactions beyond dismiss
• Not compatible with SwiftUI (UIKit-only component)
• Does not support iPad multitasking or landscape orientation edge cases

• Avg cyclomatic complexity: ~4 — Core library is a focused UI component with moderate complexity in geometry calculations and animation timing; straightforward but not trivial
• Largest file: Demo/Pods/Nimble/Sources/Nimble/Matchers (many small files in test framework dependency) (2,000 lines)
• Estimated quality issues: ~2 — Library is well-maintained with CI/CD, but potential frame validation and nil-safety improvements could reduce runtime errors

• Missing nil coalescing on optional view references (Medium) — AMPopTip implementation (not visible in header): Accessing superview or frame properties without safe unwrapping could cause runtime crashes if view hierarchy is invalid
• No bounds checking before frame calculations (Low) — Position calculation logic (implied in AMPopTip.h show method): If target frame is outside visible bounds, popover may render off-screen without warning

• Core Animation rendering pipeline (Performance) — Heavy use of CABasicAnimation on main thread could cause frame drops if multiple popovers animate simultaneously
• View hierarchy insertion (Performance) — Adding popover to view hierarchy and removing trigger view layout passes; frequent show/hide cycles may cause jank

Frame coordinate system is absolute to the container view, not relative—you must use UIView's convert(_:toView:) to translate nested subview frames before passing to show(). The direction property is auto by default, which means the actual direction is decided at runtime; don't assume it matches your input. Demo app uses CocoaPods, not SPM, so pod install is required even to run examples.

• Auto-directional popover layout — AMPopTip's auto, autoHorizontal, and autoVertical modes decide arrow direction at runtime to avoid clipping; understanding this is key to using the library without manual direction logic.
• View coordinate system conversion — The library requires absolute frame coordinates relative to the container; misunderstanding convertRect(_:toView:) is the most common integration bug.
• Snapshot regression testing — AMPopTip uses Nimble-Snapshots for visual testing; snapshots catch rendering bugs across iOS versions and device sizes without manual QA.
• Arrow path geometry (Bézier curves) — The popover's arrow is likely drawn using UIBezierPath or CoreGraphics; understanding path math helps customize arrow shape or size.
• CABasicAnimation for popover entrance — The 'pop' effect uses Core Animation; tweaking animation duration, damping, or easing requires CABasicAnimation knowledge.
• CocoaPods spec semantics — AMPopTip.podspec defines the library's public API surface and source layout; understanding podspec format is required to modify packaging or add subspecs.

• joseBaseba/SDCAlertView — Similar popover/alert component library for iOS, alternative approach to contextual UI hints
• pkluz/PKHUD — HUD and toast notification library; overlaps with AMPopTip's use case for onboarding and subtle feedback
• material-components/material-components-ios — Material Design popover and tooltip components; broader UI framework that includes similar popover patterns
• kishikawakatsumi/IBPCollectionViewCompositionalLayout — Complementary layout library often used in iOS onboarding demos alongside popover components

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 snapshot tests for popover positioning and arrow directions

The repo has Nimble-Snapshots dependencies installed in Demo/Pods but no visible snapshot test suite. Given that AMPopTip is a visual component with multiple arrow directions and positioning options, snapshot tests would catch unintended visual regressions. This is critical for a UI library.

• [ ] Create Tests/SnapshotTests.swift to test all popover arrow directions (up, down, left, right)
• [ ] Add snapshot tests for different popover sizes and content
• [ ] Integrate snapshot tests into .github/workflows/Test.yml CI pipeline
• [ ] Generate and commit baseline snapshots to the repo

Add comprehensive unit tests for AMPopTip.swift core logic

The Test.yml workflow exists but there's no visible test directory structure in the file listing. A modern Swift UI library needs unit tests for frame calculations, positioning logic, and animation parameters to ensure reliability across iOS versions.

• [ ] Create Tests/AMPopTipTests.swift with unit tests for frame calculations
• [ ] Add tests for popover positioning relative to target frame in all directions
• [ ] Test edge cases: popovers near screen edges, very small/large content sizes
• [ ] Add tests for animation timing and completion handlers

Complete the README with CocoaPods and SPM installation instructions

The README snippet ends abruptly at '# Setup with CocoaP' (truncated). The podspec exists (AMPopTip.podspec) but installation instructions are incomplete. This blocks new users from easily adopting the library.

• [ ] Complete the CocoaPods setup section in README.md with Podfile example
• [ ] Add Swift Package Manager installation instructions (add Package.swift if not present)
• [ ] Add Carthage setup instructions if supported
• [ ] Include basic usage example with code snippet showing initialization and presentation

• Add SwiftUI preview modifier: create a PreviewContainer or @main wrapper in Demo to showcase PopTip states (up/down/left/right/none) as SwiftUI Previews, filling the gap between Objective-C and modern SwiftUI adoption patterns.
• Expand snapshot test coverage: add snapshot tests for edge cases (very long text, custom fonts, small max widths) under Demo/ using the existing Nimble-Snapshots infrastructure, catching layout regressions early.
• Document frame conversion examples: add a code snippet to README showing the exact convertRect() pattern for nested views (e.g., button inside a nested container view), since the current README only mentions the concept.

The AMPopTip library demonstrates a generally secure posture for an iOS UI library. No critical vulnerabilities were identified in the available codebase structure. The main concerns are operational: managing dependencies through version control, establishing a security disclosure policy, and ensuring documentation is complete. The library itself is a UI component with minimal attack surface (no network calls, database access, or cryptographic operations visible). Recommended improvements include implementing a SECURITY.md policy, optimizing dependency management practices, and regular dependency audits.

• Low · Dependency Management Visibility — Demo/Pods/. The repository contains a Demo/Pods directory with extensive dependency files (Nimble, Nimble-Snapshots, etc.). While CocoaPods is a standard package manager for iOS, having pod dependencies checked into version control increases repository size and can obscure dependency vulnerabilities. Fix: Ensure CocoaPods dependencies are managed through Podfile.lock and consider using .gitignore to exclude Pods directory from version control. Regularly audit dependencies using tools like pod outdated or CocoaPods vulnerability scanners.
• Low · Missing Security Policy — Repository root. No SECURITY.md or security vulnerability disclosure policy file is present in the repository. This makes it difficult for security researchers to responsibly report vulnerabilities. Fix: Create a SECURITY.md file in the repository root with clear instructions for reporting security vulnerabilities, following the GitHub security guidelines.
• Low · Incomplete README Documentation — README.md. The README snippet appears truncated at 'Setup with CocoaP', indicating incomplete security or setup documentation that might miss important security considerations. Fix: Complete the README with full setup instructions, security considerations, and best practices for using the library.

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.