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/AMScrollingNavbar 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

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "andreamazz/AMScrollingNavbar(\\.git)?\\b" \\
  && ok "origin remote is andreamazz/AMScrollingNavbar" \\
  || miss "origin remote is not andreamazz/AMScrollingNavbar (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 "Demo/ScrollingNavbarDemo/ViewControllers/ScrollViewController.swift" \\
  && ok "Demo/ScrollingNavbarDemo/ViewControllers/ScrollViewController.swift" \\
  || miss "missing critical file: Demo/ScrollingNavbarDemo/ViewControllers/ScrollViewController.swift"
test -f "Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationController.swift" \\
  && ok "Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationController.swift" \\
  || miss "missing critical file: Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationController.swift"
test -f "Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationViewController.swift" \\
  && ok "Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationViewController.swift" \\
  || miss "missing critical file: Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationViewController.swift"
test -f "Demo/Pods/AMScrollingNavbar/Source/ScrollingNavbar+Sizes.swift" \\
  && ok "Demo/Pods/AMScrollingNavbar/Source/ScrollingNavbar+Sizes.swift" \\
  || miss "missing critical file: Demo/Pods/AMScrollingNavbar/Source/ScrollingNavbar+Sizes.swift"
test -f "AMScrollingNavbar.podspec" \\
  && ok "AMScrollingNavbar.podspec" \\
  || miss "missing critical file: AMScrollingNavbar.podspec"

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

AMScrollingNavbar is a Swift UINavigationController subclass that makes the navigation bar hide/show dynamically as the user scrolls content in a UIScrollView or UITableView. It solves the common iOS UX pattern where the navbar collapses upward during scroll-down to maximize content space, then re-appears on scroll-up, implemented as a drop-in replacement controller in the UIKit navigation stack. Single-package layout: AMScrollingNavbar/ contains the Swift source (ScrollingNavigationController.swift, ScrollingNavigationViewController.swift, ScrollingNavbar+Sizes.swift); the Demo/ folder contains a CocoaPods-integrated example app. The core logic lives in the main package root with a standard Xcode project structure.

iOS developers building content-heavy apps (news readers, social feeds, documentation browsers) who want the standard iOS scrolling navbar behavior without building custom scroll detection and animation logic. Both Swift and Objective-C developers can use it via CocoaPods.

Production-ready. The project has existed since at least v1.x (Objective-C era), now in v5.x with Swift 5 support. CI is configured via GitHub Actions (Test.yml workflow), and the codebase uses SwiftLint for code quality. However, the activity level appears moderate—typical of a mature, stable library in maintenance mode rather than active heavy development.

Low risk for adoption. The codebase is stable Swift with minimal dependencies (CocoaPods/Carthage compatible, no external lib dependencies visible), but it's a single-maintainer library (andreamazz) with the standard maintenance burden that implies. No breaking changes visible in recent history, though pre-5.x versions required Swift syntax migrations.

The project appears in maintenance mode. No active feature PRs or ongoing milestones are visible from the file structure. The GitHub Actions Test.yml workflow is configured and likely runs on each commit, but commit recency cannot be inferred from the file list alone.

git clone https://github.com/andreamazz/AMScrollingNavbar.git
cd AMScrollingNavbar
pod install  # if you want to run the Demo app
# Or use as a CocoaPod dependency: add 'pod "AMScrollingNavbar"' to your Podfile

Daily commands: For the demo app: cd Demo && pod install && open Pods/Pods.xcodeproj then build and run the ScrollingNavbarDemo scheme. For development: open AMScrollingNavbar.xcodeproj and run the test suite via xcodebuild test -scheme AMScrollingNavbar.

• Demo/ScrollingNavbarDemo/ViewControllers/ScrollViewController.swift — Primary demo implementation showing how to integrate the scrolling navbar with a UIScrollView and observe scroll events
• Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationController.swift — Core controller that manages navbar visibility/hiding logic based on scroll events—essential to understand the library's behavior
• Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationViewController.swift — Base view controller subclass that integrates scrolling navbar functionality; contributors must understand the extension API
• Demo/Pods/AMScrollingNavbar/Source/ScrollingNavbar+Sizes.swift — Handles navbar size calculations and transformations during scroll; critical for layout logic
• AMScrollingNavbar.podspec — Pod specification defines dependencies, Swift version, and library metadata for distribution
• AMScrollingNavbar/AMScrollingNavbar.h — Umbrella header exposing the public API surface of the library
• .swiftlint.yml — Code style rules enforced across the codebase; contributors must run linter before submitting PRs

• ScrollingNavigationController (UIViewController, CABasicAnimation, UIView.animate) — Core logic: tracks scroll events, calculates navbar visibility threshold, triggers hide/show animations
  • Failure mode: Scroll events not observed → navbar stays static; animation failures would cause navbar to freeze mid-transition
• ScrollingNavigationViewController (extension) (Swift protocol extension) — Integration point: provides scrollViewDidScroll() hook for client code to call with scroll offset
  • Failure mode: If not called, navbar won't respond to scroll; if called with wrong offset, animations become jerky
• ScrollingNavbar+Sizes (utility) (CGRect, CGPoint, CGAffineTransform) — Frame calculations: computes navbar height deltas, content inset adjustments, and transform matrices
  • Failure mode: Incorrect size calculations cause navbar to clip content or appear misaligned
• UINavigationBar subclass/extension (UIView.layer, CATransaction) — Visual rendering: applies transform animations to show/hide navbar while preserving safe area layout
  • Failure mode: Transform artifacts or safe area miscalculation causes layout broken or nav items hidden

• UIScrollView (contentOffset) → ScrollingNavigationController — Scroll position delta passed via scrollViewDidScroll() delegate callback
• ScrollingNavigationController → ScrollingNavbar+Sizes — Scroll offset → frame delta calculation for navbar height/transform
• ScrollingNavbar+Sizes → UINavigationBar (layer.transform) — Computed CGAffineTransform applied to navbar to show/hide with animation
• UINavigationBar visibility state → UIScrollView content inset — Navbar frame changes adjust scroll view's contentInset to prevent content overlap

Add a new scrolling view controller example

1. Create new view controller file in Demo/ScrollingNavbarDemo/ViewControllers/ (Demo/ScrollingNavbarDemo/ViewControllers/YourViewController.swift)
2. Subclass from UIViewController and adopt ScrollingNavigationViewController extension pattern (Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationViewController.swift)
3. Create UIScrollView property and call scrollViewDidScroll() to observe navbar changes (Demo/ScrollingNavbarDemo/ViewControllers/ScrollViewController.swift)
4. Register view controller in Main.storyboard and add navigation controller embedding (Demo/ScrollingNavbarDemo/Base.lproj/Main.storyboard)

Modify navbar scroll threshold or animation timing

1. Edit the scroll offset delta logic in ScrollingNavigationController (Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationController.swift)
2. Adjust frame transformation calculations in ScrollingNavbar+Sizes (Demo/Pods/AMScrollingNavbar/Source/ScrollingNavbar+Sizes.swift)
3. Test changes using any demo view controller (e.g., ScrollViewController) (Demo/ScrollingNavbarDemo/ViewControllers/ScrollViewController.swift)

Release a new version

1. Update version and CHANGELOG entries (AMScrollingNavbar.podspec)
2. Update CHANGELOG.md with release notes (CHANGELOG.md)
3. Run SwiftLint to ensure code quality compliance (.swiftlint.yml)
4. Create git tag and push to trigger GitHub Actions Test workflow (.github/workflows/Test.yml)

• Swift 5 — Modern iOS development standard; enables type safety and performance optimizations over Objective-C
• UINavigationController subclass pattern — Leverages native iOS navigation hierarchy without requiring complex view injection or swizzling
• CocoaPods distribution — Standardized iOS library distribution mechanism enabling easy integration and dependency management

• Navbar visibility hidden by scrolling offset, not content reveal

  • Why: Simpler implementation that doesn't require custom scroll view subclassing
  • Consequence: Navbar collapse/expand is animation-based rather than interactive; less flexible for custom timing

• Extension-based integration (UIViewController category/protocol)

  • Why: Non-intrusive; library users don't need to change their base controller classes
  • Consequence: Requires manual method calls in scroll delegates; more boilerplate than injection-based approaches

• No real-time scroll tracking synchronization

  • Why: Reduces computational overhead and keeps animations smooth
  • Consequence: Navbar visibility lags slightly behind scroll position; not suitable for synchronized parallax effects

• Does not support interactive/interactive UIViewControllerTransition animations
• Does not handle custom navbar subclasses with complex layouts
• Not compatible with SwiftUI or modern compositional layouts
• Does not provide real-time scroll position synchronization for parallax effects

• Tight coupling between ScrollingNavigationController and UINavigationBar (Medium) — Demo/Pods/AMScrollingNavbar/Source/ScrollingNavigationController.swift: Direct manipulation of UINavigationBar.layer.transform makes the library sensitive to iOS UIKit internals; could break on future iOS versions
• Manual scroll event forwarding required from client code (Low) — Demo/ScrollingNavbarDemo/ViewControllers/ScrollViewController.swift: Clients must remember to call scrollViewDidScroll() in their scroll delegate, creating boilerplate and risk of forgotten calls
• No thread-safety guarantees for: undefined

No unusual environment setup required. Key gotcha: the followScrollView(_:delay:) method must be called in viewWillAppear(_:) or later in the VC lifecycle, not in init(), otherwise the scroll view may not be laid out. The delay parameter controls scroll delta threshold (in points) before navbar animation starts—set too low and navbar flickers; too high and response feels sluggish. Safe area handling differs between iOS 11+ and earlier; test on target iOS versions. Demo app requires CocoaPods; don't try building it without running pod install first.

• UIScrollViewDelegate scroll tracking — AMScrollingNavbar hooks into scrollViewDidScroll(_:) to detect velocity and direction; understanding delegate callbacks is essential to modifying animation behavior
• CABasicAnimation and frame-based layout — The navbar collapse/expand uses Core Animation to smoothly translate the navbar's Y position; frame manipulation and animation timing are core to the library's visual polish
• UINavigationController subclassing and view hierarchy — The library subclasses UINavigationController and manipulates its child VC layout; understanding the navigation controller's view stack is necessary to extend or debug behavior
• Safe area and view insets (iOS 11+) — AMScrollingNavbar+Sizes.swift carefully accounts for notches and safe area insets; incorrect inset math breaks layout on modern iPhones
• CocoaPods podspec and dependency management — The AMScrollingNavbar.podspec defines how the library integrates into host projects; understanding podspec syntax is needed to update distribution or add transitive dependencies

• jlyonarm/ScrollableSegmentedControl — Complementary library for scrollable UISegmentedControl that pairs well with AMScrollingNavbar for tabbed navigation in content-heavy apps
• matteocrippa/awesome-swift — Community curated list of Swift libraries; AMScrollingNavbar is referenced as a canonical example of UIKit customization patterns
• realm/realm-swift — Common dependency pairing in iOS demo apps; if you're using AMScrollingNavbar with data-driven table views, Realm often handles persistence
• Alamofire/Alamofire — Typical networking dependency in apps using AMScrollingNavbar to fetch content for scrollable feeds (not a direct dependency, but ecosystem adjacency)

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 ScrollingNavbar+Sizes.swift

The repo has CI/CD configured (.github/workflows/Test.yml) but the Source directory contains core logic files (ScrollingNavbar+Sizes.swift, ScrollingNavigationController.swift, ScrollingNavigationViewController.swift) with no corresponding test files visible in the repo structure. The Sizes extension likely handles critical navbar dimension calculations that should be tested across different device configurations and scroll scenarios.

• [ ] Create Tests directory in AMScrollingNavbar.xcodeproj if not present
• [ ] Add ScrollingNavbar+SizesTests.swift with test cases for: navbar height calculations, safe area inset handling, and custom size overrides
• [ ] Add test cases covering different device sizes (iPhone SE, regular, Plus) and safe area scenarios (notch, dynamic island)
• [ ] Update .github/workflows/Test.yml to ensure new test targets run in CI pipeline

Add integration tests for ScrollingNavigationController.swift

The main ScrollingNavigationController class handles the core scrolling behavior (navbar follows scrollview). There are no visible UI/integration test files. This is critical functionality that needs validation across different scroll states (up, down, edge cases like bouncing, deceleration).

• [ ] Create ScrollingNavigationControllerTests.swift in Tests directory
• [ ] Add test cases for: navbar hide/show on scroll up/down, scrolling performance with large content, navbar state persistence during view controller transitions
• [ ] Include tests for edge cases: rapid scrolling, scrolling past bounds, empty scroll views
• [ ] Verify tests run in CI workflow and update Test.yml if needed

Add Swift API documentation and DocC coverage for public ScrollingNavigationViewController API

The repo targets Swift 5 and supports modern iOS development, but there's no visible Documentation.docc or inline API documentation for ScrollingNavigationViewController.swift. This is a public-facing class that developers inherit from. Proper documentation will reduce support burden and improve adoption.

• [ ] Add inline Swift documentation comments (///) to ScrollingNavigationViewController.swift covering: class purpose, key methods (viewDidLoad lifecycle, scroll configuration), example usage patterns
• [ ] Create Documentation.docc directory in project with a ScrollingNavigationViewController article showing code examples for setup and common configurations
• [ ] Document key properties like scrollViewToFollow, scrollingNavbarDelegate, and their expected behaviors
• [ ] Update README.md with link to generated documentation or quick API reference section

• Add unit tests for ScrollingNavbar+Sizes.swift calculations, particularly edge cases for notched devices and landscape orientation—currently no test files visible in the structure.
• Document the delay parameter behavior with a code example in the README showing how it affects navbar responsiveness, since it's counter-intuitive (higher = less responsive).
• Add a Swift Package Manager (SPM) manifest (Package.swift) to support swift package adoption alongside CocoaPods/Carthage, matching modern iOS development workflows.

The AMScrollingNavbar repository demonstrates reasonable security practices for an open-source UIKit library. It uses standard dependency management through CocoaPods and includes GitHub workflow automation for testing. However, there are opportunities for improvement: implementing automated dependency vulnerability scanning in the CI/CD pipeline, establishing a formal security vulnerability disclosure process, and ensuring strict dependency version pinning. The codebase itself appears to be a UI component library with minimal external dependencies, reducing the attack surface. No hardcoded secrets, injection vulnerabilities, or infrastructure misconfigurations were detected in the provided file structure. The primary recommendation is to establish formal security practices including vulnerability disclosure procedures and automated dependency scanning.

• Medium · Dependency Management via CocoaPods without Lock File Verification — AMScrollingNavbar.podspec, Demo/Podfile. The project uses CocoaPods for dependency management. While a Podfile.lock exists in the Demo directory, there is no evidence of strict dependency pinning or verification mechanisms in the main library configuration. The AMScrollingNavbar.podspec file should specify explicit version constraints for any dependencies to prevent unexpected updates that could introduce vulnerabilities. Fix: Ensure all dependencies in AMScrollingNavbar.podspec have explicit version constraints (e.g., '~> 1.0' or '= 1.0.0'). Regularly audit and update dependencies. Use pod install --repo-update only when intentionally updating dependencies.
• Low · No Security Policy or Vulnerability Disclosure Process — .github/. The repository does not contain a SECURITY.md file or documented security vulnerability disclosure process. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file in the root or .github directory outlining the vulnerability disclosure process, contact information, and expected response timelines.
• Low · Missing Dependency Vulnerability Scanning — .github/workflows/Test.yml. No evidence of automated dependency vulnerability scanning tools (such as Dependabot, OWASP Dependency-Check, or CocoaPods vulnerability scanning) in the CI/CD pipeline (.github/workflows/Test.yml). Fix: Integrate automated dependency scanning into the CI/CD pipeline using tools like GitHub's Dependabot, or CocoaPods security scanning, to identify known vulnerabilities in dependencies before release.
• Low · Swift Package Manager Migration Not Evident — AMScrollingNavbar.podspec. The project relies on CocoaPods for distribution. While CocoaPods is still valid, Swift Package Manager (SPM) is the modern standard for Swift package distribution and has better security integration with Xcode. Fix: Consider adding Swift Package Manager support alongside or as a replacement for CocoaPods to align with modern Swift dependency management best practices.

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.