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/timdonnelly/Advance 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.

AVOID — Looks unmaintained — solo project with stale commits

• BSD-2-Clause licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Solo or near-solo (1 contributor active in 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 timdonnelly/Advance repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/timdonnelly/Advance.

What it runs against: a local clone of timdonnelly/Advance — 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 timdonnelly/Advance | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-2-Clause | 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 ≤ 1485 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "timdonnelly/Advance(\\.git)?\\b" \\
  && ok "origin remote is timdonnelly/Advance" \\
  || miss "origin remote is not timdonnelly/Advance (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-2-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-2-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-2-Clause" \\
  || miss "license drift — was BSD-2-Clause 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 "Sources/Advance.h" \\
  && ok "Sources/Advance.h" \\
  || miss "missing critical file: Sources/Advance.h"
test -f "Sources/Spring.swift" \\
  && ok "Sources/Spring.swift" \\
  || miss "missing critical file: Sources/Spring.swift"
test -f "Sources/Animator.swift" \\
  && ok "Sources/Animator.swift" \\
  || miss "missing critical file: Sources/Animator.swift"
test -f "Sources/SpringSolver.swift" \\
  && ok "Sources/SpringSolver.swift" \\
  || miss "missing critical file: Sources/SpringSolver.swift"
test -f "Sources/Advanceable.swift" \\
  && ok "Sources/Advanceable.swift" \\
  || miss "missing critical file: Sources/Advanceable.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 1485 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1455d)"
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/timdonnelly/Advance"
  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).

Advance is a physics-based animation library for iOS, tvOS, and macOS written in Swift that uses spring dynamics and decay simulations to create realistic, responsive motion. Instead of traditional keyframe animations, it applies real-world physics principles (spring tension, damping, velocity) to animate UI properties, allowing views to move and respond naturally to user interactions. Single-package structure: Advance.xcodeproj contains the main framework code (not shown in file list but referenced in .podspec and Package.swift), separate build targets for iOS/tvOS/macOS in Advance.xcodeproj/xcshareddata/xcschemes/, and Samples/SampleApp-{iOS|macOS} containing working demo apps. Core API is Spring (animates values with physics) and Animator (flexible animation orchestration).

iOS/macOS/tvOS developers building interactive apps who need realistic gesture-driven animations, spring-based transitions, and responsive UI that feels natural—particularly those tired of rigid CABasicAnimation or seeking alternatives to UIView.animate().

Production-ready and actively maintained. The repo shows Swift 5.0+ support, multi-platform frameworks (iOS/tvOS/macOS), CocoaPods/SPM/Carthage distribution, and CI via GitHub Actions (.github/workflows/swift.yml). The codebase is 58KB of Swift with proper unit test schemes for all three platforms, indicating a stable, polished library.

Low risk. Single-maintainer repo (timdonnelly) is a concern for long-term support, but the small, focused scope (animation physics only) limits surface area. No heavy external dependencies visible in the file list. Without access to open issues or recent commit timestamps, verify the last commit date in GitHub—if >2 years old, check issue response times.

Cannot determine from file list alone—no visible git log, PRs, or issues shown. Check GitHub's Releases page and recent commits to confirm. The presence of .github/workflows/swift.yml indicates CI is active.

git clone https://github.com/timdonnelly/Advance.git
cd Advance
open Advance.xcodeproj
# For SPM: add to Package.swift
.package(url: "https://github.com/timdonnelly/Advance", from: "3.0.0")
# Or CocoaPods: pod 'Advance'

Daily commands: Xcode project: open Advance.xcodeproj, select SampleApp-iOS scheme, build & run (Cmd+R). The sample app demonstrates spring animations, decay animations, and direct manipulation. Unit tests: select Advance-UnitTests-iOS scheme and run (Cmd+U).

• Sources/Advance.h — Main public header that exports the entire animation framework API; defines the public interface that all consumers depend on
• Sources/Spring.swift — Core Spring animation class implementing physics-based motion; the primary abstraction users interact with for animating values
• Sources/Animator.swift — Central animation loop manager that coordinates all active animations and drives the CADisplayLink update cycle
• Sources/SpringSolver.swift — Physics solver implementing spring mathematics (damping, stiffness, mass); critical for correctness of animation behavior
• Sources/Advanceable.swift — Protocol defining animatable types; establishes the type system that allows springs to work with any conforming value type
• Package.swift — Swift Package Manager manifest defining multi-platform targets (iOS, tvOS, macOS) and build configuration

• Spring<T> (Swift Generic, Protocol-bound) — Holds current and target value, configuration; manages lifecycle and onChange notifications
  • Failure mode: Infinite vibration if configuration causes underdamping (damping < 2√(stiffness×mass)); user must tune parameters
• SpringSolver (Math library (sin/cos for oscillation), floating-point arithmetic) — Numerically integrates differential equations of damped harmonic motion each frame
  • Failure mode: Numerical instability if timestep too large or spring extremely stiff; typically not an issue at 60 fps
• Animator (CADisplayLink, NSMutableSet or similar collection) — Global singleton coordinating CADisplayLink, maintaining set of active springs, triggering frame updates
  • Failure mode: If display link fails to schedule (e.g., app backgrounded), animations pause; resumes automatically on foreground
• Advanceable Protocol — Type contract enabling interpol

Make a Custom Type Animatable

1. Define your custom type (struct or class) that you want to animate (Sources/Advanceable.swift)
2. Conform to the Advanceable protocol by implementing advance(towards:by:) method that interpolates between two values (Sources/Advanceable.swift)
3. Create a Spring with your type: let spring = Spring(initialValue: myCustomValue) and set spring.onChange closure (Sources/Spring.swift)
4. Update the target: spring.target = newValue to trigger physics-based animation

Add a Platform-Specific Demo

1. Create a new ViewController subdirectory in the appropriate platform sample app (e.g., Samples/SampleApp-iOS/Sources/) (Samples/SampleApp-iOS/Sources/SpringsViewController.swift)
2. Implement your demo controller using UIViewController (iOS/tvOS) or NSViewController (macOS) subclass (Samples/SampleApp-iOS/Sources/DemoViewController.swift)
3. Create Spring instances with your animated values and bind them to UI updates via onChange closures (Samples/SampleApp-iOS/Sources/SpringView.swift)
4. Register your demo in the BrowserViewController or main app navigation structure (Samples/SampleApp-iOS/Sources/BrowserViewController.swift)

Tune Spring Physics for Desired Motion

1. Examine SpringConfiguration struct to understand tunable parameters (Sources/SpringConfiguration.swift)
2. Create or modify a Spring with custom configuration: Spring(initialValue: value, configuration: SpringConfiguration(damping: 0.7, stiffness: 100)) (Sources/Spring.swift)
3. Use the iOS sample app SpringConfigurationView to interactively adjust damping/stiffness and preview the effect in real-time (Samples/SampleApp-iOS/Sources/SpringConfigurationView.swift)
4. Export your tuned configuration as a preset constant for reuse across your app

Integrate with User Gesture Recognition

1. Review the DirectManipulationGestureRecognizer for pattern on tracking user input (Samples/SampleApp-iOS/Sources/DirectManipulationGestureRecognizer.swift)
2. Create a Spring instance to manage the animated property you want to control (Sources/Spring.swift)
3. In your gesture recognizer handler, update spring.target based on gesture location/velocity (Samples/SampleApp-iOS/Sources/GesturesViewController.swift)
4. Bind spring.onChange to update your UI element, achieving natural momentum-like motion

• CADisplayLink — Synchronizes animation updates to the display refresh rate (60 fps iOS, 120 fps ProMotion); critical for smooth, jitter-free motion that users perceive as natural
• Swift Generics & Protocols — Advanceable protocol enables type-safe animations on any value (CGPoint, CGAffineTransform, custom structs); avoids boxing/unboxing and preserves compiler optimizations
• Physics-based Solver (Damped Harmonic Oscillator) — Produces natural, momentum-aware motion that responds realistically to mass, damping, and stiffness rather than artificial easing curves
• Swift Package Manager + CocoaPods — Dual distribution maximizes adoption; SPM for modern Swift projects, CocoaPods for legacy Objective-C and mixed codebases

• No built-in gesture/input handling—only Spring abstraction

  • Why: Keeps framework focused and lightweight; gesture logic varies per use case (UIPan, custom recognizers, etc.)
  • Consequence: Developers must wire gestures to spring.target updates themselves; see GesturesViewController sample for pattern

• Single global Animator instance coordinating all springs

  • Why: Reduces system overhead and ensures all animations update in lock-step with display refresh
  • Consequence: Simplifies API but means framework controls the update schedule; users cannot create isolated animation contexts

• No completion callbacks or explicit animation cancellation API

  • Why: Physics solver naturally decays to zero velocity; animation implicitly stops when value stabilizes
  • Consequence: Simpler mental model but less control if you need to trigger actions at specific animation milestones

• Real-time interactive scrubbing or manual frame control—framework is CADisplayLink-driven only
• Keyframe animations or path-based motion—strictly value interpolation via physics
• AnimationGroup or sequence orchestration—manage multiple springs independently
• Constraint-based animations or layout-integrated animations—purely value-driven
• Linux or Windows support—Apple platforms only (iOS, tvOS, macOS)

No obvious environment variables or service dependencies. Key gotchas: (1) Physics parameters (tension, damping, threshold) are tuning-sensitive—small changes yield dramatically different animation feel, so experiment with values in your app, not just copy-paste examples. (2) The library updates every frame via display links—ensure animations are stopped/reset if views are deallocated to avoid orphaned update handlers. (3) Multi-platform support requires testing on actual iOS/tvOS/macOS devices or simulators; behavior may differ due to screen refresh rates (60Hz vs. 120Hz).

• Spring Physics (Hooke's Law) — The core of this library: understanding F = -kx (tension) and damping forces explains why Spring parameters (tension, damping) control animation feel and convergence time
• Display Link / Frame Synchronization — Advance uses CADisplayLink (iOS/tvOS) and CVDisplayLink (macOS) to update animations every screen refresh; understanding this explains why animations appear smooth and tie to device refresh rate (60/120 Hz)
• Decay Simulation (Friction/Drag) — Beyond springs, Advance supports decay animations that realistically slow down over time with friction, mimicking inertial scrolling—critical for gesture-driven interactions
• Threshold Convergence (Numerical Stability) — Springs never mathematically reach their target; Advance uses a threshold value to detect when oscillations are negligible enough to stop updates, preventing infinite animation loops and CPU waste
• Value Interpolation & Closure-Based Binding — Advance uses observer pattern (Spring.onChange closure) instead of direct property binding; this allows you to transform/constrain animated values before applying them to UI, enabling complex interactions without subclassing
• Multi-Platform Framework Targets — Advance builds separate frameworks for iOS/tvOS/macOS (visible in xcschemes), using conditional compilation and platform-specific display links; understanding this is essential for contributing platform-specific fixes

• jonduan/JDAnimationKit — iOS animation library using similar spring physics concepts, though less actively maintained; useful for comparing animation API design
• material-motion/material-motion-swift — Google's motion design library for iOS; also physics-based, larger scope with composition patterns
• Ramotion/paper-switch — Popular iOS custom animation example; demonstrates gesture-driven physics animations similar to Advance's direct manipulation patterns
• facebook/pop — Facebook's POPAnimation engine (Objective-C, predecessor era); inspired many physics-based animation libraries; Advance is its Swift-native successor in spirit
• kinomap/DeformationBase — Companion for physics-based deformations on iOS; complements Advance for advanced gesture-driven shape animations

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 tvOS sample app implementation (Samples/SampleApp-tvOS)

The tvOS sample app structure exists in the file tree but is incomplete (only Resources folder listed). tvOS is explicitly supported per the README and Package.swift, but there's no working demo. This is a high-value contribution because it: (1) ensures tvOS build compatibility is actually tested, (2) provides a reference implementation for tvOS developers using Advance, (3) mirrors the complete iOS and macOS sample apps that already exist.

• [ ] Create Samples/SampleApp-tvOS/Sources/ directory structure
• [ ] Implement AppDelegate.swift and main view controllers (adapt from Samples/SampleApp-iOS/Sources or Samples/SampleApp-macOS/Sources with tvOS-specific UIKit patterns)
• [ ] Create Samples/SampleApp-tvOS/Resources/Info.plist following the pattern in Samples/SampleApp-iOS/Resources/Info.plist
• [ ] Add Assets.xcassets with tvOS app icon
• [ ] Verify SampleApp-tvOS.xcscheme is properly configured in Advance.xcodeproj/xcshareddata/xcschemes/
• [ ] Test that the tvOS sample app builds and runs successfully

Add missing unit tests for macOS and tvOS frameworks

The repo has xcschemes for Advance-UnitTests-macOS.xcscheme and Advance-UnitTests-tvOS.xcscheme, plus Resources/UnitTests-Info-macOS.plist and Resources/UnitTests-Info-tvOS.plist, indicating test targets exist. However, there's no visibility into whether these targets actually contain test cases or if they're just placeholders. This is valuable because: (1) it ensures the physics engine works correctly across all supported platforms, (2) CI workflow (swift.yml) likely needs these tests to run, (3) prevents platform-specific regressions.

• [ ] Audit existing test files to identify which platform-specific tests already exist
• [ ] Add platform-specific unit tests to validate Spring, Animator, and physics calculations on macOS (especially for NSView compatibility vs UIView)
• [ ] Add platform-specific unit tests for tvOS gesture handling and view interactions
• [ ] Ensure .github/workflows/swift.yml includes test scheme invocations for all three platforms (iOS, macOS, tvOS)
• [ ] Run all test schemes locally to confirm they execute and pass

Add API documentation comments to core animation classes (Advance framework sources)

The repo has .jazzy.yaml configured for documentation generation (indicating a Jazzy/Xcode documentation build process), but the incomplete README snippet shows user-facing code examples without complete API reference. The Sources directory structure is not shown in the file listing. This is valuable because: (1) developers need to understand Spring, Animator, and value animation APIs, (2) .jazzy.yaml indicates docs are expected to be generated, (3) complete HeaderDoc/documentation comments enable IDE autocomplete and generated reference docs on the website.

• [ ] Identify core source files in Sources/ directory (e.g., Spring.swift, Animator.swift, animation value types)
• [ ] Add comprehensive documentation comments (///) with parameter descriptions, return value docs, and usage examples for public APIs
• [ ] Include code examples in documentation for commonly-used classes (Spring, Animator, etc.)
• [ ] Run jazzy locally to verify documentation builds correctly and is rendered properly
• [ ] Ensure generated documentation is linked from README.md or DOCUMENTATION.md file

• Add comprehensive unit tests for edge cases in Spring physics calculations (e.g., very high tension, zero damping, negative velocity)—the test schemes exist but specifics aren't visible; auditing would improve reliability
• Enhance sample app documentation: add inline comments and a 'Tutorial' view controller walking through Spring parameters (tension, damping, threshold) with live sliders—currently only DecayViewController and DirectManipulationGestureRecognizer are shown
• Add SwiftUI integration examples: create a SampleApp-iOS/Sources/SwiftUIExamples.swift demonstrating how to use Advance animations with SwiftUI state bindings (e.g., Binding<CGFloat> backed by a Spring), addressing the gap between UIKit-focused samples and modern Swift development

The Advance physics animation library demonstrates a generally secure posture for an open-source Swift framework. No critical vulnerabilities such as hardcoded secrets, SQL injection points, or XSS risks were identified in the file structure provided. However, there are minor gaps in security documentation and build pipeline visibility. The main concerns are: (1) lack of visible SECURITY.md policy, (2) potential GitHub Actions misconfiguration, (3) dependency management practices, and (4) unreviewed platform-specific permissions in sample apps. The codebase is primarily focused on UI animation logic with no obvious data processing, authentication, or network communication components that would introduce typical injection or credential exposure risks.

• Medium · Missing CHANGELOG and Security Policy — Repository root. The repository does not appear to have a SECURITY.md or CHANGELOG file visible in the provided structure. This makes it difficult for users and security researchers to report vulnerabilities responsibly or track security-related fixes. Fix: Create a SECURITY.md file with responsible disclosure guidelines and maintain a CHANGELOG documenting security fixes.
• Low · Build Configuration Exposure — .github/workflows/swift.yml. The .github/workflows/swift.yml file is present but not shown in full detail. GitHub Actions workflows can potentially expose sensitive information if not properly configured (e.g., storing secrets in logs, exposing build artifacts). Fix: Review GitHub Actions workflow configuration to ensure: (1) No secrets are logged, (2) Build artifacts are not publicly accessible, (3) Dependencies are pinned to specific versions, (4) OIDC token permissions are minimized.
• Low · Podspec Without Version Pinning — Advance.podspec. The Advance.podspec file may specify dependencies without strict version constraints, potentially allowing installation of vulnerable transitive dependencies. Fix: Review and pin all dependency versions in the podspec to known-good versions. Use pessimistic version constraints (~>) to allow patch updates but prevent breaking changes.
• Low · Sample App Permissions Not Reviewed — Samples/SampleApp-*/Resources/Info.plist, Samples/SampleApp-macOS/Resources/SampleApp_macOS.entitlements. The sample applications across iOS, macOS, and tvOS platforms include Info.plist and entitlements files. Without reviewing these, potential over-privileged permission requests cannot be verified. Fix: Review all Info.plist files and entitlements to ensure minimum necessary permissions are requested. Remove any unused permissions.

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.