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-switch 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

• 16 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-switch repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Ramotion/paper-switch.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Ramotion/paper-switch(\\.git)?\\b" \\
  && ok "origin remote is Ramotion/paper-switch" \\
  || miss "origin remote is not Ramotion/paper-switch (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 "PaperSwitch/RAMPaperSwitch.swift" \\
  && ok "PaperSwitch/RAMPaperSwitch.swift" \\
  || miss "missing critical file: PaperSwitch/RAMPaperSwitch.swift"
test -f "PaperSwitchDemo/PaperSwitchDemo/ViewController.swift" \\
  && ok "PaperSwitchDemo/PaperSwitchDemo/ViewController.swift" \\
  || miss "missing critical file: PaperSwitchDemo/PaperSwitchDemo/ViewController.swift"
test -f "RAMPaperSwitch.podspec" \\
  && ok "RAMPaperSwitch.podspec" \\
  || miss "missing critical file: RAMPaperSwitch.podspec"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "PaperSwitchDemo/PaperSwitchDemo/Main.storyboard" \\
  && ok "PaperSwitchDemo/PaperSwitchDemo/Main.storyboard" \\
  || miss "missing critical file: PaperSwitchDemo/PaperSwitchDemo/Main.storyboard"

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

RAMPaperSwitch is a Swift UISwitch subclass that implements Material Design by painting the parent view with the switch's onTintColor when toggled on, creating an expanding circular reveal animation. It's a drop-in replacement for UISwitch that adds sophisticated material-style visual feedback to toggle interactions. Monolithic structure: PaperSwitch/ folder contains the single RAMPaperSwitch.swift class; PaperSwitchDemo/ is a self-contained demo app with Main.storyboard UI and ViewController.swift integration example. Package.swift enables SPM adoption. Minimal external dependencies—pure Swift/UIKit implementation.

iOS app developers building apps targeting iOS 8.0+ who want to add Material Design-compliant switch components with minimal integration effort. Designers and product teams shipping polished, modern toggle UI without building custom controls from scratch.

Production-ready library with stable API surface. Supports iOS 8.0+ and Xcode 9.0+, distributed via CocoaPods and Carthage. Has Travis CI configured and generated documentation. However, no visible test suite in PaperSwitchDemoTests beyond basic placeholder tests, and no recent commit timestamps visible—activity level unclear but deployment breadth suggests stability.

Single-file core implementation (PaperSwitch/RAMPaperSwitch.swift) creates maintenance bottleneck. No automated test coverage for the core animation logic. No explicit dependency management beyond Xcode/Swift runtime. Lack of visible recent activity (commits, issue triage) suggests potential stale maintenance; verify last update date before production adoption.

Not visible from file list alone. No CHANGELOG entries, recent PRs, or issue tracker data provided. Infer from .travis.yml CI config and Package.swift that basic maintenance workflows exist, but specific active roadmap unknown.

git clone https://github.com/Ramotion/paper-switch.git && cd paper-switch && open PaperSwitchDemo/PaperSwitchDemo.xcodeproj; Xcode will build and run the demo. Alternatively, add to Podfile: pod 'RAMPaperSwitch' && pod install.

Daily commands: Open PaperSwitchDemo/PaperSwitchDemo.xcodeproj in Xcode, select iPhone simulator target, Product → Run (⌘R). Demo app loads Main.storyboard with embedded RAMPaperSwitch instances showing real-time toggle behavior.

• PaperSwitch/RAMPaperSwitch.swift — Core switch component implementing the material design paper-painting animation effect; every contributor must understand the animation logic and view hierarchy.
• PaperSwitchDemo/PaperSwitchDemo/ViewController.swift — Primary demo implementation showing how to integrate RAMPaperSwitch; reference for usage patterns and configuration.
• RAMPaperSwitch.podspec — Package definition for CocoaPods distribution; controls versioning, dependencies, and public API surface.
• Package.swift — Swift Package Manager manifest; required for SPM-based integration and dependency resolution.
• PaperSwitchDemo/PaperSwitchDemo/Main.storyboard — UI layout containing switch placement and parent view setup; essential for understanding the demo's visual structure.

• RAMPaperSwitch (UIControl, CABasicAnimation, CAShapeLayer, CGPath) — Core switch control handling toggle state, animation coordination, and event dispatching to observers
  • Failure mode: If animation is interrupted (user taps during animation), state may desynchronize; requires guarding with isAnimating flag
• ViewController (Demo) (UIViewController, IBOutlet, IBAction) — Integrates switches, manages state synchronization, updates UI (images/backgrounds) in response to switch events
  • Failure mode: If image assets are missing or outlet connections break, UI state updates will fail silently
• Storyboard (UI Layout) (Interface Builder, Auto Layout) — Defines view hierarchy, switch placement, and outlet connections between UI elements and code
  • Failure mode: Broken outlet connections will cause runtime crashes; missing constraints cause layout issues

• User touch → RAMPaperSwitch.touchesBegan/Ended —

Add a new switch instance to the demo app

1. Add a RAMPaperSwitch outlet to ViewController.swift and instantiate it with desired frame and color (PaperSwitchDemo/PaperSwitchDemo/ViewController.swift)
2. Connect the switch to a target-action method in ViewController to handle state changes (PaperSwitchDemo/PaperSwitchDemo/ViewController.swift)
3. Add corresponding image assets to Images.xcassets for on/off states (PaperSwitchDemo/PaperSwitchDemo/Images.xcassets)
4. Update Main.storyboard to layout the new switch within the view hierarchy (PaperSwitchDemo/PaperSwitchDemo/Main.storyboard)

Customize RAMPaperSwitch appearance and behavior

1. Open RAMPaperSwitch.swift and adjust CABasicAnimation timing, opacity curves, or color calculations in the toggle methods (PaperSwitch/RAMPaperSwitch.swift)
2. Modify the animationDuration property or add new customizable properties (e.g., shadowColor, cornerRadius) to match your design system (PaperSwitch/RAMPaperSwitch.swift)
3. Test changes in ViewController by creating instances with different configurations (PaperSwitchDemo/PaperSwitchDemo/ViewController.swift)

Release a new version to CocoaPods

1. Update version number and changelog in RAMPaperSwitch.podspec and CHANGELOG.md (RAMPaperSwitch.podspec)
2. Update version in Package.swift to match the podspec version (Package.swift)
3. Tag the release in git and run 'pod trunk push RAMPaperSwitch.podspec' to publish to CocoaPods repository (RAMPaperSwitch.podspec)

• UIControl subclass — Provides native iOS event handling (target-action pattern) familiar to iOS developers; integrates seamlessly with UIKit
• CABasicAnimation — Enables smooth, GPU-accelerated animations for the expanding paper effect without blocking the main thread
• Core Graphics (CGPath, CAShapeLayer) — Allows precise control over circle geometry and masking for the material design expanding effect
• Swift + CocoaPods + SPM — Provides dual package manager support for maximum developer reach; Swift syntax ensures modern iOS development compatibility

• Animation in foreground with parent view masking

  • Why: Material Design requires expanding circle to visually paint over the parent; alternative would be changing parent background directly
  • Consequence: Requires careful CATransaction management to avoid unexpected view state changes; animation duration is fixed for predictability

• No built-in accessibility labels or haptic feedback

  • Why: Keeps component lightweight and customizable; developers must add accessibility via ViewController
  • Consequence: Apps using RAMPaperSwitch must implement VoiceOver and Haptic Engine support separately

• Single-purpose UIControl (toggle only, not tri-state)

  • Why: Reduces complexity and aligns with Material Design switch specifications
  • Consequence: Cannot represent indeterminate states; developers needing tri-state must use different component

• Does not provide localization or RTL (right-to-left) layout support
• Not designed for tvOS, watchOS, or macOS—iOS-only component
• Does not include Objective-C compatibility layer
• Not a complete design system—only a single switch control
• Does not support SwiftUI natively (UIViewRepresentable wrapper required)

No environment variables or runtime dependencies required. Core gotcha: animation duration must be set programmatically (no Interface Builder property)—see duration property in RAMPaperSwitch.swift. Ensure parent view has clip to bounds disabled or use proper view hierarchy to see the paint-over effect. No Swift version constraints explicitly locked; verify Xcode 9.0+ for syntax compatibility.

• Material Design Circular Reveal Animation — Core visual mechanic of RAMPaperSwitch—expanding circular overlay from switch origin is the signature Material Design pattern this library implements
• CABasicAnimation — RAMPaperSwitch uses Core Animation's CABasicAnimation for performant property interpolation (color, scale, opacity); understanding frame-based animation is essential to modifying behavior
• UIView Hierarchy Traversal & Parent View Manipulation — RAMPaperSwitch must locate and paint over its superview; requires understanding responder chain and view tree navigation to apply overlay layers correctly
• Target-Action Pattern (UIControl Events) — RAMPaperSwitch inherits from UISwitch/UIControl; animation triggers on .valueChanged events via addTarget(:action:for:) callback mechanism
• CAShapeLayer & Bezier Paths — Circular reveal effect likely uses CAShapeLayer with UIBezierPath for masking; understanding layer composition and path-based rendering enables customization of reveal geometry
• Swift Property Observers (didSet/willSet) — RAMPaperSwitch configuration (onTintColor, duration) uses property observers to trigger layout updates; essential for understanding reactive property binding in the implementation

• Ramotion/folding-cell — Companion Ramotion library providing Material Design animated cells; shared design language and animation philosophy for iOS UI components
• Ramotion/gliding-collection — Another Ramotion Material Design module; patterns for custom UIView animation and view controller transitions applicable to paper-switch architecture
• CosmicMind/Material — Comprehensive Material Design framework for iOS—covers toggles, switches, and animation utilities; reference for extended Material Design switch implementations
• mamaral/Neon — Auto-layout DSL often paired with custom control libraries like RAMPaperSwitch for responsive layout integration in demo apps
• IBAnimatable/IBAnimatable — Interface Builder-native animation library; alternative approach to adding Material Design animations via storyboard configuration vs. RAMPaperSwitch's programmatic API

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 comprehensive unit tests for RAMPaperSwitch.swift core functionality

The repo has a test file (PaperSwitchDemoTests.swift) but it appears to be a demo test rather than focused unit tests for the core RAMPaperSwitch class. The main library file (PaperSwitch/RAMPaperSwitch.swift) lacks dedicated test coverage for animation logic, state management, and gesture handling. This is critical for a UI library where visual behavior is the core feature.

• [ ] Create PaperSwitch/RAMPaperSwitchTests.swift with unit tests for switch state transitions
• [ ] Add tests for the animation timing and view painting behavior when toggled
• [ ] Test gesture recognition and user interaction edge cases
• [ ] Verify accessibility features and state callbacks are properly tested
• [ ] Add to .travis.yml configuration if not already running these tests

Add GitHub Actions workflow for Swift testing and deployment

The repo uses .travis.yml for CI, but Travis CI is legacy and no longer widely recommended. The project should have a modern GitHub Actions workflow that tests across multiple iOS SDK versions and validates the Swift Package Manager (Package.swift exists but untested), CocoaPods (RAMPaperSwitch.podspec exists), and Xcode builds. This ensures the library works reliably across different integration methods.

• [ ] Create .github/workflows/swift-tests.yml to test on multiple macOS/iOS SDK versions
• [ ] Add workflow step to validate Swift Package Manager build (test Package.swift)
• [ ] Add workflow step to validate CocoaPods integration (test RAMPaperSwitch.podspec)
• [ ] Add workflow step to build and test the demo app (PaperSwitchDemo.xcodeproj)
• [ ] Consider adding code coverage reporting to the workflow

Add detailed usage documentation and API reference to README.md

The README snippet shows the header and introduction but is incomplete. The RAMPaperSwitch class clearly has customizable properties (based on the pod spec) but there's no documented API reference, configuration examples, or customization guide in the README. The docs/ folder has generated documentation but new contributors need clear inline examples.

• [ ] Add 'Installation' section with CocoaPods, SPM, and manual installation instructions
• [ ] Add 'Usage' section with code examples showing basic switch setup and state handling
• [ ] Document key properties and methods (color customization, animation duration, state callbacks) with code examples
• [ ] Add 'Customization' section explaining how to configure appearance and behavior
• [ ] Include troubleshooting section or link to issues for common integration problems

• Add unit tests to PaperSwitchDemoTests/PaperSwitchDemoTests.swift covering animation timing, color assignment, and state transitions—currently only placeholder tests exist.
• Document the animation timing curve and easing function used in RAMPaperSwitch.swift; add code comments explaining the CABasicAnimation configuration for newcomers.
• Add accessibility support: implement UIAccessibility protocol in RAMPaperSwitch.swift to announce switch state changes and animation events for VoiceOver users.

The RAMPaperSwitch repository appears to be a UI library with a relatively straightforward structure. No critical vulnerabilities were identified from the visible file structure. However, the analysis is limited by: (1) unavailable dependency information preventing CVE verification, (2) no visible security policy, and (3) incomplete CI/CD configuration details. The codebase is an iOS UI component library with minimal external attack surface, but dependency management practices and security documentation should be improved. Recommendations focus on dependency verification, adding security disclosure guidelines, and ensuring secure CI/CD practices.

• Medium · Missing or Outdated Dependency Verification — Package.swift. The Package.swift file content was not provided for analysis. Swift Package Manager dependencies cannot be verified for known security vulnerabilities, outdated versions, or malicious packages. Fix: Provide Package.swift contents and verify all dependencies against Swift Package Index security advisories. Use tools like swift package show-dependencies and maintain updated dependency versions.
• Medium · Incomplete Dependency Metadata — Project root / Package management files. The 'Dependencies/Package file content' section is empty, preventing analysis of direct and transitive dependencies for known CVEs. Fix: Maintain an SBOM (Software Bill of Materials) and regularly scan dependencies using tools like OWASP Dependency-Check or Swift Package Manager auditing tools.
• Low · No Security Policy Documentation — Repository root. No SECURITY.md or security disclosure policy is evident in the repository structure, making it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with responsible disclosure guidelines and contact information for reporting vulnerabilities.
• Low · Build Configuration Exposure — PaperSwitchDemo/PaperSwitchDemo.xcodeproj/project.pbxproj. The project.pbxproj file is committed to version control. While necessary for Xcode projects, it can contain sensitive build settings or path information if misconfigured. Fix: Audit project.pbxproj for hardcoded secrets, API keys, or sensitive paths. Use environment-based configuration for sensitive build settings.
• Low · Limited Code Review Evidence — .travis.yml. No visible evidence of code signing, commit signing, or CI/CD security scanning (Travis CI config present but no details provided). Fix: Implement code signing, require signed commits, and enable security scanning in CI/CD pipeline (SAST, dependency scanning).

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.