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/ChiliLabs/CHIPageControl 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

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ChiliLabs/CHIPageControl(\\.git)?\\b" \\
  && ok "origin remote is ChiliLabs/CHIPageControl" \\
  || miss "origin remote is not ChiliLabs/CHIPageControl (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 "CHIPageControl/Core/CHIBasePageControl.swift" \\
  && ok "CHIPageControl/Core/CHIBasePageControl.swift" \\
  || miss "missing critical file: CHIPageControl/Core/CHIBasePageControl.swift"
test -f "CHIPageControl/Core/CHIPageControllable.swift" \\
  && ok "CHIPageControl/Core/CHIPageControllable.swift" \\
  || miss "missing critical file: CHIPageControl/Core/CHIPageControllable.swift"
test -f "CHIPageControl/Core/CHILayer.swift" \\
  && ok "CHIPageControl/Core/CHILayer.swift" \\
  || miss "missing critical file: CHIPageControl/Core/CHILayer.swift"
test -f "CHIPageControl/CHIPageControlAji.swift" \\
  && ok "CHIPageControl/CHIPageControlAji.swift" \\
  || miss "missing critical file: CHIPageControl/CHIPageControlAji.swift"
test -f "CHIPageControl.podspec" \\
  && ok "CHIPageControl.podspec" \\
  || miss "missing critical file: CHIPageControl.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 1114 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1084d)"
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/ChiliLabs/CHIPageControl"
  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).

CHIPageControl is a Swift library providing 8 animated page control styles (Aji, Aleppo, Chimayo, Fresno, Jalapeno, Jaloro, Paprika, Puya) as drop-in replacements for UIPageControl with smooth indicator transitions. It lets iOS developers use IBDesignable custom page controls in Storyboards or programmatically, with support for touch events, dynamic progress updates, and per-indicator tint colors. Simple vertical architecture: CHIPageControl/Core/ contains the base class CHIBasePageControl.swift, the CHIPageControllable.swift protocol, and CHILayer.swift for animation primitives. Eight concrete implementations (CHIPageControlAji.swift through CHIPageControlPuya.swift) inherit from the base and customize animation behavior. Example app in Example/ demonstrates all styles; CocoaPods specs in CHIPageControl.podspec enable modular installation.

iOS developers building apps with paged content (carousels, onboarding flows, image galleries) who want visually polished, animated page indicators instead of the default static UIPageControl dots. Particularly useful for design-conscious teams influenced by Dribbble-style interactions.

Early-stage but stable: version 0.1.3 in CocoaPods shows limited public adoption and slow release cadence. The codebase is small (~61KB Swift), no visible test suite or CI pipeline in the file list, and README targets Swift 3 / iOS 8.0+ (outdated by modern standards). Likely abandoned or in maintenance mode—suitable for reference but not recommended for new production projects expecting active support.

High maintainer risk: single-author ChiliLabs library with no visible CI/CD, no test files in the repo, and no evidence of recent activity. The Swift 3 requirement and iOS 8.0 minimum are severely outdated (now Swift 5.x and iOS 13+ standard). No dependency declaration visible in the file list makes stability opaque. Forking or copying the code may be safer than consuming as a live dependency.

No active development visible. The repo structure and file list show no pending work, no recent commits mentioned, and no open milestones. Version 0.1.3 appears to be the final release; the library is in a 'done but not maintained' state.

git clone https://github.com/ChiliLabs/CHIPageControl.git
cd CHIPageControl
# Option 1: Manual integration
cp -r CHIPageControl /path/to/your/project/
# Option 2: CocoaPods
pod install CHIPageControl~>0.1.3
# Option 3: Swift Package Manager (if Package.swift exists)
swift build
# Run example
cd Example && pod install && open Example.xcworkspace

Daily commands: Open CHIPageControl.xcodeproj in Xcode, select the CHIPageControl scheme, and build (⌘B). For the example app: cd Example, run pod install, then open Example.xcworkspace and run the app on a simulator (⌘R). No build server, no npm/ruby dependencies required for the main library.

• CHIPageControl/Core/CHIBasePageControl.swift — Abstract base class that all 8 page control variants inherit from; defines the core animation, sizing, and update logic
• CHIPageControl/Core/CHIPageControllable.swift — Protocol defining the required interface for all page control implementations; ensures consistent behavior across variants
• CHIPageControl/Core/CHILayer.swift — CALayer subclass managing individual indicator dots and their animations; central to all visual rendering
• CHIPageControl/CHIPageControlAji.swift — First concrete page control variant; demonstrates the pattern that all 7 other variants follow
• CHIPageControl.podspec — CocoaPods manifest defining modular subspecs for each page control variant; critical for dependency management
• Package.swift — Swift Package Manager configuration; enables distribution as a Swift package alongside CocoaPods

• CHIPageControllable (Swift protocol, computed properties) — Protocol contract: defines numberOfPages, currentPage, tint colors, and updatePageDisplay() / animateIndicator() methods
  • Failure mode: If not implemented, variant compilation fails; type safety enforced at build time
• CHIBasePageControl (UIView, Auto Layout, CABasicAnimation lifecycle) — UIView subclass orchestrating layout, dot creation, color updates, and delegating animations to subclasses
  • Failure mode: Layout calculations incorrect → dots misaligned; color updates ignored → visual state inconsistent with currentPage
• CHILayer (CALayer, CAShapeLayer, CGPath) — CALayer wrapper managing individual indicator dot shape, transform, and animation state
  • Failure mode: Animation not applied → dot frozen; shape misconfigured → dot invisible or distorted
• Variant (e.g., CHIPageControlAji) (CABasicAnimation, CAKeyframeAnimation, CATransaction) — Concrete subclass implementing animate(to:) with custom animation logic; defines the unique visual behavior
  • Failure mode: Animation timing incorrect → janky transitions; missing CATransaction wrapping → layout thrashing

• App code → CHIPageControl variant instance — Sets numberOfPages, currentPage, tint colors, and calls updatePage

Add a new animated page control variant

1. Create a new Swift file in CHIPageControl/ named CHIPageControl{VariantName}.swift (CHIPageControl/CHIPageControlAji.swift)
2. Subclass CHIBasePageControl and override the animate(to:) method with custom CABasicAnimation or CAKeyframeAnimation logic (CHIPageControl/Core/CHIBasePageControl.swift)
3. Configure layer properties (size, shape, colors) in the setup phase of init or layoutSubviews() (CHIPageControl/Core/CHILayer.swift)
4. Add a new subspec to CHIPageControl.podspec with the variant name and source path (CHIPageControl.podspec)
5. Instantiate the new variant in Example/Example/ViewController.swift and add to scroll view or collection (Example/Example/ViewController.swift)

Customize page control appearance

1. Set pageIndicatorTintColor and currentPageIndicatorTintColor properties (inherited from CHIPageControllable protocol) (CHIPageControl/Core/CHIPageControllable.swift)
2. Adjust numberOfPages property to match your content; call updatePageDisplay() to refresh (CHIPageControl/Core/CHIBasePageControl.swift)
3. Optionally modify CHILayer's shape creation (circle, pill, custom bezier) in the layer's configuration (CHIPageControl/Core/CHILayer.swift)

Integrate CHIPageControl into a UIScrollView or UIPageViewController

1. Import CHIPageControl and instantiate your chosen variant (e.g., CHIPageControlAji()) (CHIPageControl/CHIPageControlAji.swift)
2. Set numberOfPages to match your content count and add to a parent view (CHIPageControl/Core/CHIBasePageControl.swift)
3. In UIScrollViewDelegate.scrollViewDidScroll() or UIPageViewControllerDelegate methods, update currentPage and call updatePageDisplay() (Example/Example/ViewController.swift)

• UIView subclass (CHIBasePageControl) — Provides seamless integration with UIKit hierarchy; allows Auto Layout, IB_DESIGNABLE, and standard view lifecycle
• CALayer and Core Animation — Enables smooth, GPU-accelerated animations without blocking the main thread; supports complex transforms, keyframes, and timing
• Swift 3 + Protocol-Oriented Design — CHIPageControllable protocol defines contracts, enabling polymorphism and variant extensibility with minimal code duplication
• CocoaPods subspecs + SPM — Allows modular distribution; users can install only their preferred variants, reducing bundle size

• All variants inherit from CHIBasePageControl rather than composing animators

  • Why: Simpler to understand and maintain; each variant overrides animate(to:) with custom logic
  • Consequence: Code duplication across variants; harder to share animation utilities. Mitigated by CHILayer abstraction

• UIView-based implementation vs. custom CALayer-only

  • Why: UIView provides Auto Layout, IB_DESIGNABLE preview, and standard lifecycle integration
  • Consequence: Slightly larger memory footprint and layout overhead; justified by ease of integration in UIKit apps

• No data binding or reactive updates

  • Why: Library stays lightweight and dependency-free; delegates all state management to caller
  • Consequence: Users must manually call updatePageDisplay() and set currentPage; no automatic synchronization with UIPageViewController events

• Does not provide automatic scroll/page sync with UIPageViewController or UICollectionView—caller must update currentPage
• Does not support horizontal or vertical scrolling indicators (only radial/grid dot layouts)
• Does not include accessibility features (VoiceOver labels, Dynamic Type) in core—delegated to caller
• Does not target macOS, watchOS, or tvOS—iOS 8.0+ only

No CocoaPods setup required beyond running pod install in Example/—the library has zero external dependencies. However, the @IBDesignable attribute in Xcode can cause Interface Builder refresh delays on slower machines; rebuild Xcode if custom page controls don't render in Storyboards. Swift 3 syntax is incompatible with Swift 4.0+ projects without modification (type inference and array literal changes). The library does not support RTL (right-to-left) layout; progress direction is always left-to-right.

• CABasicAnimation and CADisplayLink — Core Animation primitives used by all 8 page control styles to smoothly interpolate indicator positions and sizes; understanding timing curves (easeInOut, easeOut) is essential to customizing animation feel
• IBDesignable and IBInspectable — Xcode attributes that allow CHIPageControl styles to render live in Interface Builder and expose properties (radius, padding, tintColor) as editable Storyboard inspectors without code changes
• Protocol-Based Polymorphism — CHIPageControllable protocol enforces a consistent interface across 8 different animation styles, allowing drop-in style switching without changing client code
• UIView Layout and drawRect — Page control styles override layoutSubviews() to position indicator layers and may override draw() for custom rendering; understanding view hierarchy and frame calculations is critical for debugging visual bugs
• CocoaPods Subspecs — CHIPageControl.podspec defines 8 optional subspecs allowing users to install only their preferred page control style, reducing app binary size; understanding podspec structure is useful for library distribution
• Touch Event Handling in UIControl — CHIBasePageControl subclasses UIControl and handles touch events to allow tap-to-jump page navigation; understanding responder chain and gesture recognition is needed to extend touch behavior

• jonkykong/SideMenu — Alternative UIControl subclass library for iOS; demonstrates similar IBDesignable pattern and protocol-driven architecture for custom UI components
• airbnb/lottie-ios — Production-grade animation library for iOS used when page control animations become too complex; complements CHIPageControl for advanced sequencing
• Alamofire/Alamofire — Reference for Swift library packaging, CocoaPods/SPM setup, and test infrastructure that CHIPageControl lacks
• kickstarter/ios-oss — Mature iOS app using custom UIControl subclasses and reactive architecture; shows best practices for component testing that CHIPageControl could adopt

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 CHIBasePageControl and CHIPageControllable protocol

The repo lacks automated tests despite having 8 different page control implementations. Adding unit tests for the core CHIPageControl/Core/CHIBasePageControl.swift and CHIPageControl/Core/CHIPageControllable.swift would catch regressions and ensure all subclasses (Aji, Aleppo, Chimayo, etc.) correctly implement the protocol. This is especially important since these are visual components where behavior consistency matters.

• [ ] Create Tests/ directory with CHIBasePageControlTests.swift
• [ ] Add tests verifying CHIPageControllable protocol conformance
• [ ] Test numberOfPages, currentPage, and tintColor properties for each implementation
• [ ] Add tests for CHILayer.swift animation and rendering logic
• [ ] Configure Example/Example.xcodeproj to run tests in Xcode scheme

Add Swift Package Manager (SPM) support with proper module definitions

Package.swift exists but the repo currently relies on CocoaPods/Carthage. SPM support is critical for modern iOS development. The current Package.swift likely lacks proper product definitions for the 8 individual page control variants that are offered as separate CocoaPods subspecs, making it impossible to install specific controls via SPM.

• [ ] Update Package.swift to define 8 library products (matching CocoaPods subspecs: Aji, Aleppo, Chimayo, Fresno, Jalapeno, Jaloro, Paprika, Puya)
• [ ] Add .product dependencies linking each control to CHIPageControl/Core module
• [ ] Test SPM integration by adding the package to Example/Example via Xcode
• [ ] Update README.md with SPM installation instructions matching CocoaPods snippet format

Add GitHub Actions CI workflow for iOS builds and automated testing

No CI configuration exists (.github/workflows/ is missing). With Swift code supporting iOS 8.0+ and Xcode 8+, a GitHub Actions workflow would validate that all 8 page control implementations compile across supported platforms and that the example app builds without errors. This catches breaking changes early.

• [ ] Create .github/workflows/ios-build.yml with xcodebuild steps for CHIPageControl.xcodeproj
• [ ] Add step to build Example/Example.xcodeproj as integration test
• [ ] Configure matrix testing against iOS 12, 14, 16+ (representing supported versions)
• [ ] Add automated pod spec lint step to validate CHIPageControl.podspec
• [ ] Update README.md with CI badge showing build status

• Add unit tests for CHIBasePageControl progress updates and touch event delegation under a new Tests/ folder—the repo has zero test coverage visible in the file list
• Create Swift 5 compatibility branch and update README to reflect modern iOS 13+ / Xcode 12+ support; current Swift 3 and iOS 8.0 targets are unmaintainable
• Implement snapshot tests for each of the 8 page control styles (Aji through Puya) using FBSnapshotTestCase to prevent visual regression on animation changes

CHIPageControl is a UI library with minimal security risks due to its limited scope (pure UI animation library with no data processing, networking, or storage functionality). The primary security concerns are related to outdated dependencies and lack of modern Swift version support. The codebase does not contain injection vulnerabilities, hardcoded secrets, or infrastructure misconfigurations. The project would benefit from updating to modern Swift versions and establishing formal security practices.

• Low · Outdated Swift Version Requirement — README.md, CHIPageControl.podspec. The README specifies Swift 3 and iOS 8.0+ as requirements. Swift 3 was released in 2016 and is significantly outdated. This may indicate the codebase hasn't been updated with modern security patches and Swift language improvements that address security concerns. Fix: Update the project to support modern Swift versions (Swift 5.0+) and iOS 12.0+. Ensure all dependencies are compatible with current Swift versions and receive regular security updates.
• Low · Unspecified Pod Version in Podfile — Example/Podfile. The Example/Podfile appears to be truncated in the provided content. If it uses loose version constraints or unspecified versions for dependencies, it could lead to unpredictable dependency resolution and potential security issues from transitive dependencies. Fix: Specify exact or conservative version constraints for all CocoaPods dependencies. Use the lock file (Podfile.lock) to ensure reproducible builds.
• Low · Missing Security Configuration Documentation — Root directory. The codebase lacks explicit documentation about security considerations, data handling practices, or security update policies. There is no SECURITY.md file or security guidelines for contributors. Fix: Create a SECURITY.md file documenting security practices, vulnerability reporting procedures, and the project's security update policy.

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.