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/Ramotion/paper-onboarding 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 4y ago

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

What it runs against: a local clone of Ramotion/paper-onboarding — 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 Ramotion/paper-onboarding | 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 ≤ 1432 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Ramotion/paper-onboarding(\\.git)?\\b" \\
  && ok "origin remote is Ramotion/paper-onboarding" \\
  || miss "origin remote is not Ramotion/paper-onboarding (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 "Source/PaperOnboarding.swift" \\
  && ok "Source/PaperOnboarding.swift" \\
  || miss "missing critical file: Source/PaperOnboarding.swift"
test -f "Source/PaperOnboardingDataSource.swift" \\
  && ok "Source/PaperOnboardingDataSource.swift" \\
  || miss "missing critical file: Source/PaperOnboardingDataSource.swift"
test -f "Source/PaperOnboardingDelegate.swift" \\
  && ok "Source/PaperOnboardingDelegate.swift" \\
  || miss "missing critical file: Source/PaperOnboardingDelegate.swift"
test -f "Source/PageView/PageView.swift" \\
  && ok "Source/PageView/PageView.swift" \\
  || miss "missing critical file: Source/PageView/PageView.swift"
test -f "Source/FillAnimationView/FillAnimationView.swift" \\
  && ok "Source/FillAnimationView/FillAnimationView.swift" \\
  || miss "missing critical file: Source/FillAnimationView/FillAnimationView.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 1432 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1402d)"
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/Ramotion/paper-onboarding"
  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).

PaperOnboarding is a Swift UIView library that implements a material design onboarding slider for iOS apps. It provides animated, swipe-navigable page transitions with a distinctive 'paper' visual effect where content slides and reveals beneath a clipped circular mask, delivering a polished first-run experience without requiring developers to build custom animation logic. Modular source structure: Source/FillAnimationView/ contains the circular fill animation logic, Source/GestureControl/ handles swipe recognition, and PaperOnboardingDemo/ contains a complete working example. The library exports a single public PaperOnboarding UIView subclass (declared in PaperOnboarding.h) that consumes a dataSource protocol for page configuration.

iOS app developers (Swift) who need to implement onboarding flows and want a pre-built, production-grade UI component with material design animations. Specifically valuable for teams building consumer apps that prioritize visual polish and don't want to reinvent swipeable carousel animations from scratch.

Actively maintained and production-ready. The repo shows CocoaPods/Carthage/SPM distribution (v6.1.4+), Travis CI integration, and codebeat quality badges. The codebase is primarily Swift (58KB) with minimal dependencies, and supports iOS 10.0+. However, based on the file structure shown, this appears to be a mature, stable library without recent commit details visible—likely in maintenance mode rather than active feature development.

Low-to-moderate risk for integration. Single-owner Ramotion library with no visible Swift Package Manager breakage history. Main risks: iOS 10.0+ minimum version constraint may exclude older app targets; no test files visible in the provided structure suggests weak test coverage; depends on storyboard integration which can be brittle across Xcode versions. Last commit recency unknown from provided data.

No active development signals visible in the provided file list. The repo appears to be in stable/maintenance mode with no PRs, recent commits, or open milestones documented. Last update likely corresponds to Xcode 10.2 / iOS 10.0+ support stability.

git clone https://github.com/Ramotion/paper-onboarding.git
cd paper-onboarding
cd PaperOnboardingDemo
open PaperOnboardingDemo.xcodeproj
# Build and run on simulator or device (Xcode 10.2+)

Alternatively, for CocoaPods: add pod 'paper-onboarding' to Podfile and run pod install.

Daily commands:

xed PaperOnboardingDemo/PaperOnboardingDemo.xcodeproj
# Select simulator/device target, press Cmd+R

Or with CocoaPods (in host project): pod install && open *.xcworkspace then add PaperOnboarding() as a subview per README usage example.

• Source/PaperOnboarding.swift — Main entry point and orchestrator for the entire paper onboarding UI component; defines the public API that developers integrate.
• Source/PaperOnboardingDataSource.swift — Protocol defining how onboarding content is provided; every integration must conform to this to supply pages and items.
• Source/PaperOnboardingDelegate.swift — Protocol for lifecycle callbacks (page transitions, completion); essential for connecting UI events to app logic.
• Source/PageView/PageView.swift — Core component rendering the animated page slides and background fill effect; handles the material design aesthetic.
• Source/FillAnimationView/FillAnimationView.swift — Implements the signature paper-like fill animation during page transitions; core to the library's visual identity.
• Source/GestureControl/GestureControl.swift — Handles swipe and tap gestures for page navigation; critical for interactivity and user input routing.
• PaperOnboardingDemo/PaperOnboardingDemo/ViewController.swift — Reference implementation showing DataSource/Delegate integration; primary guide for new users.

• PaperOnboarding (UIView) — Root UIView; coordinates DataSource/Delegate, manages PageView state, exposes public API (dataSource, delegate, getCurrentPage()).

Add a New Onboarding Page

1. Create OnboardingContantViewItem instances with title, description, image, and button text in your DataSource (Source/OnboardingContentView/Item/OnboardingContantViewItem.swift)
2. Implement numberOfPages() in your DataSource to increase the count (Source/PaperOnboardingDataSource.swift)
3. Implement itemsForPage(_:) to return your new items for the new page index (Source/PaperOnboardingDataSource.swift)
4. Assign background colors via backgroundColorForItem(_:) in your DataSource (Source/PaperOnboardingDataSource.swift)

Handle Onboarding Completion Events

1. Conform to PaperOnboardingDelegate protocol in your view controller (Source/PaperOnboardingDelegate.swift)
2. Implement onboardingDidFinish(_ onboarding:) to receive completion callback (Source/PaperOnboardingDelegate.swift)
3. Optionally implement onboardingWillTransition(_:) to track page changes during navigation (Source/PaperOnboardingDelegate.swift)
4. Set your delegate instance as the paperOnboarding.delegate in your view controller (Source/PaperOnboarding.swift)

Customize Colors and Styling

1. Implement backgroundColorForItem(_:) in DataSource to set page background colors (Source/PaperOnboardingDataSource.swift)
2. Modify text attributes and font sizes in OnboardingContentView initialization (Source/OnboardingContentView/OnboardingContentView.swift)
3. Adjust FillAnimationView duration and easing in PageView transitions if needed (Source/FillAnimationView/FillAnimationView.swift)

• Swift UIKit (AutoLayout) — Native iOS framework for declarative layout; enables smooth 60fps animations and material design transitions.
• CABasicAnimation & CAShapeLayer — Core Animation provides hardware-accelerated path-based fill animations for the signature paper reveal effect.
• UIGestureRecognizer (Tap/Swipe) — Standard iOS gesture handling for responsive page navigation and accessibility.
• Swift Package Manager + Cocoapods — Dual distribution approach maximizes adoption; enables easy integration into existing iOS projects.

• UIKit over SwiftUI

  • Why: Library targets iOS 9.0+; SwiftUI support would require iOS 13.0+ minimum and reduce compatibility.
  • Consequence: Larger user base but more verbose layout code; manual constraint management required.

• Programmatic UI over Storyboards

  • Why: Easier to maintain, version control, and test across variants without binary XML conflicts.
  • Consequence: Steeper learning curve for contributors; no visual Interface Builder preview.

• DataSource/Delegate pattern over Closure-based API

  • Why: Aligns with UIKit conventions (UITableViewDataSource/Delegate); more familiar to iOS developers.
  • Consequence: More boilerplate than modern closure-based APIs; requires protocol conformance.

• Single-pass animation per transition

  • Why: Simpler implementation and predictable performance; avoids stacking concurrent animations.
  • Consequence: Cannot interrupt mid-animation; users must wait for transition to complete before next swipe.

• Does not handle user onboarding data persistence (e.g., 'mark onboarding as completed')
• Does not support custom gesture recognizers beyond tap and swipe
• Does not include internationalization or RTL layout support
• Does not provide analytics or event tracking integration
• Does not support landscape orientation (portrait-only by design)

No obvious environment variables or external service dependencies. Key gotcha: the library expects a dataSource conforming to PaperOnboardingDataSource protocol with required methods; missing implementation will crash silently. Storyboard integration (via custom UIView class + IB inspector) may not work reliably across Xcode versions—code-based initialization is safer. The iOS 10.0+ floor is restrictive for apps targeting iOS 11+; no conditional compatibility shims visible.

• CABasicAnimation & CAShapeLayer — The entire visual effect relies on Core Animation framework's property-based animation and mask layers; understanding these is essential to modify or debug the fill animation
• UIGestureRecognizer (Swipe/Pan) — GestureControl module uses UISwipeGestureRecognizer and UIPanGestureRecognizer to detect user swipe intent and drive page transitions; critical for interactivity
• Delegation Pattern & DataSource Protocol — PaperOnboarding uses a dataSource protocol (like UITableViewDataSource) for decoupled configuration; understanding delegation is essential for integration and customization
• CADisplayLink & Synchronized Animation — Used internally to sync animations with screen refresh rates for smooth, jank-free transitions; understanding this pattern prevents animation stuttering in custom extensions
• Material Design Principles (Circular Reveal Pattern) — The 'paper peel' circular mask effect is a specific Material Design animation; knowing this pattern helps understand design intent and predict UX behavior across iOS versions
• UIView Subclassing & View Hierarchy — PaperOnboarding is a UIView subclass managing a complex hierarchy of CALayers and gesture recognizers; understanding view lifecycle and responder chain is critical for debugging layout issues

• Ramotion/folding-cell — Sibling Ramotion UI library providing animated cell transitions; same design philosophy and integration pattern for onboarding-adjacent use cases
• Ramotion/animated-tab-bar — Another Ramotion animation-heavy UIView component using CABasicAnimation; reference for CALayer animation patterns in this codebase
• pagervi/FlutterPageSlider — Cross-platform analog (Flutter) solving the same onboarding slider problem; useful for feature/UX comparison if building multi-platform apps
• Carthage/Carthage — Dependency manager explicitly supported by this library; needed for non-CocoaPods/SPM integration workflows

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 PaperOnboarding core components

The repo lacks test coverage for core components like PaperOnboarding.swift, PaperOnboardingDataSource.swift, and GestureControl.swift. This is critical for a UI library where gesture handling and animation state management are complex. New contributors could add XCTest cases to verify gesture recognition, page transitions, and delegate callbacks work correctly.

• [ ] Create Tests/ directory with PaperOnboardingTests.swift for PaperOnboarding.swift main class
• [ ] Add GestureControlTests.swift to verify pan gesture handling and page index updates in Source/GestureControl/
• [ ] Add FillAnimationViewTests.swift to test animation timing and completion callbacks in Source/FillAnimationView/
• [ ] Create mock implementations of PaperOnboardingDataSource and PaperOnboardingDelegate protocols for testing
• [ ] Update .travis.yml to run xcodebuild test in the test phase

Add GitHub Actions CI workflow for iOS builds and testing

The repo uses .travis.yml (legacy) but lacks modern GitHub Actions. A contributor could add a workflow file that builds the demo app and runs tests on every PR, ensuring compatibility with recent Xcode and Swift versions. This would catch regressions early.

• [ ] Create .github/workflows/ios-build.yml with matrix testing for iOS 14+ and latest Xcode
• [ ] Add build step for PaperOnboardingDemo.xcodeproj using xcodebuild
• [ ] Add test step to run unit tests from the Tests/ directory
• [ ] Add linting/analysis step using swiftlint (if not already integrated)
• [ ] Document the workflow in CONTRIBUTING.md or README.md

Refactor and document OnboardingContentView and PageView item architecture

The file structure shows OnboardingContentView/Item/OnboardingContantViewItem.swift and PageView/Item/PageViewItem.swift (note the typo in 'Contant'). These item classes likely handle rendering and animations but lack inline documentation. A contributor could rename the misspelled file, add comprehensive documentation for the Item classes explaining the view hierarchy, and potentially extract shared item logic into a base protocol or class.

• [ ] Rename Source/OnboardingContentView/Item/OnboardingContantViewItem.swift to OnboardingContentViewItem.swift and update imports
• [ ] Add detailed documentation comments to OnboardingContentViewItem.swift explaining how items render content and handle animations
• [ ] Add detailed documentation comments to Source/PageView/Item/PageViewItem.swift explaining the page indicator rendering logic
• [ ] Create a shared ItemConfiguring protocol if both item types share common configuration patterns
• [ ] Update PaperOnboardingDemo/PaperOnboardingDemo/ViewController.swift with code comments showing item usage

• Add unit tests for FillAnimationView.swift animation timing and CALayer frame calculations—currently no test files visible in structure
• Create SwiftUI wrapper view (PaperOnboardingWrapper.swift) to bridge the UIKit library for SwiftUI-first projects, given industry shift toward SwiftUI
• Document the exact dataSource protocol methods and lifecycle in a code example file (INTEGRATION_GUIDE.md), as current README shows minimal API detail beyond the snippet

The PaperOnboarding library demonstrates a reasonable security posture as a UI component library. Primary concerns are organizational and dependency management related rather than code-level vulnerabilities. The main risks involve the inability to verify dependency security without seeing Package.swift contents, absence of a security disclosure policy, and typical iOS development hygiene practices. For a UI library with no apparent network operations, database access, or authentication logic, the attack surface is minimal. Recommendations focus on improving development practices and dependency management rather than fixing critical security flaws.

• Medium · Missing Package.swift Dependency Information — Package.swift. The Package.swift file is listed but its content was not provided. Unable to verify if dependencies are pinned to secure versions or if any vulnerable dependencies are included. Swift Package Manager should specify exact versions or version ranges to prevent unexpected updates to vulnerable packages. Fix: Ensure all dependencies in Package.swift specify exact versions or narrow version ranges. Regularly audit dependencies using tools like swift package diagnose-api-breaking-changes and keep dependencies up to date.
• Low · Xcode Project File in Version Control — PaperOnboardingDemo/PaperOnboardingDemo.xcodeproj/project.pbxproj. The Xcode project file (project.pbxproj) is committed to the repository. While not a direct security vulnerability, this can lead to merge conflicts and makes it harder to manage build configurations securely across teams. Fix: Consider using SPM (Swift Package Manager) or Carthage for dependency management instead of Xcode project files. If keeping Xcode projects, document build configuration management and use git merge strategies.
• Low · Custom Fonts Bundled Without Validation — PaperOnboardingDemo/Fonts/*.ttf. TTF font files are bundled in the repository without apparent validation or signature verification. Malicious font files could potentially cause issues on devices processing them. Fix: Source fonts from trusted providers only. Consider documenting the origin and integrity (hash) of bundled font files. Validate font files before including them in the application.
• Low · No Security Policy or SECURITY.md File — Repository root. The repository does not appear to have a SECURITY.md file or security policy for reporting vulnerabilities. This makes it difficult for security researchers to responsibly disclose issues. Fix: Create a SECURITY.md file in the repository root with instructions for reporting security vulnerabilities. Follow the GitHub standard for security advisory handling.
• Low · Build Artifacts and Generated Files in Repository — docs/ directory. Documentation files (docs/) and generated HTML files are committed to the repository. While not a direct security risk, this inflates the repository size and can hide actual code changes. Fix: Add generated documentation to .gitignore and generate it during CI/CD pipeline instead. Store documentation separately or use a documentation hosting service.

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.