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/AugustRush/Stellar 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 7y ago

• 4 active contributors
• MIT licensed
• CI configured
• ⚠ Stale — last commit 7y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits
• ⚠ 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 AugustRush/Stellar repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/AugustRush/Stellar.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "AugustRush/Stellar(\\.git)?\\b" \\
  && ok "origin remote is AugustRush/Stellar" \\
  || miss "origin remote is not AugustRush/Stellar (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 "Sources/Physical.swift" \\
  && ok "Sources/Physical.swift" \\
  || miss "missing critical file: Sources/Physical.swift"
test -f "Sources/DynamicItem.swift" \\
  && ok "Sources/DynamicItem.swift" \\
  || miss "missing critical file: Sources/DynamicItem.swift"
test -f "Sources/AnimationContext.swift" \\
  && ok "Sources/AnimationContext.swift" \\
  || miss "missing critical file: Sources/AnimationContext.swift"
test -f "Sources/UIDynamicBehavior+Commit.swift" \\
  && ok "Sources/UIDynamicBehavior+Commit.swift" \\
  || miss "missing critical file: Sources/UIDynamicBehavior+Commit.swift"
test -f "Sources/AnimationSequence.swift" \\
  && ok "Sources/AnimationSequence.swift" \\
  || miss "missing critical file: Sources/AnimationSequence.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 2505 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2475d)"
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/AugustRush/Stellar"
  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).

Stellar is a physics-based animation library for Swift that wraps and extends UIKit's UIDynamics to provide simple, chainable APIs for complex animations. It goes beyond basic spring animations to support gravity, snapping, attachments, push forces, and custom behaviors, making it easy to build interactive UI animations with realistic physical properties. Flat modular structure: Sources/ contains ~25 Swift files organized by animation type (Basic, Gravity, Snap, Attachment) and core infrastructure. Key files include Physical.swift (main API), DynamicItem.swift (animated object wrapper), CALayer+*.swift extensions for view/layer animation, and AnimationContext.swift/AnimationSequence.swift for chaining. No separation between public API and implementation.

iOS developers building interactive UIs who want to add physics-driven animations (bouncing, gravity, elastic snapping) without deep UIDynamics boilerplate. Particularly useful for teams building gesture-driven interfaces, interactive transitions, or microsynthesis animations that feel natural.

Moderately mature but showing age: the repo is actively maintained (Travis CI + Carthage support), has a solid feature set (basic, gravity, snap, attachment behaviors), but the commit history and issue tracker are not visible in the provided data. Supports iOS 8+ and is available via CocoaPods and Carthage, suggesting production adoption. However, collision detection is marked 'coming soon', indicating incomplete feature parity with UIDynamics.

Low to moderate risk: single-language codebase (338KB Swift) with minimal external dependencies (only build tools visible: Carthage, CocoaPods). Risk factors include potential Swift language evolution breakage (no version pinning visible), lack of visible test suite in the 60-file sample, and reliance on UIDynamics which is deprecated in favor of Metal/SceneKit on modern iOS. Unmaintained state relative to UIKit's trajectory is a concern.

No recent activity visible in the provided snapshot. The repo structure shows Carthage build artifacts and CI configuration (.travis.yml) but no explicit branch/PR/issue data. Features marked 'coming soon' (collision detection, file configuration) suggest the roadmap stalled or was deprioritized.

Clone and build via Carthage: git clone https://github.com/AugustRush/Stellar.git && cd Stellar && carthage update --platform iOS. For CocoaPods: add pod 'Stellar', :git => 'https://github.com/AugustRush/Stellar.git' to Podfile, then pod install. Manually: drag Sources/ folder into Xcode project or include StellarDemo.xcodeproj in workspace.

Daily commands: Not a runnable CLI tool. Import framework and use in Xcode: import Stellar; view.moveX(100).duration(2).easing(.SwiftOut).start(). Example gifs show usage with leftLines.enumerate() and chained animations. Run StellarDemo.xcodeproj in Xcode for interactive examples.

• Sources/Physical.swift — Core animation engine that orchestrates all physics-based animation behaviors and is the main entry point for the library.
• Sources/DynamicItem.swift — Base protocol defining animatable items; all animations operate through conforming types that bridge UIView/CALayer to physics behaviors.
• Sources/AnimationContext.swift — Central state manager tracking active animations, their progression, and lifecycle; required to understand animation execution flow.
• Sources/UIDynamicBehavior+Commit.swift — Extension bridging UIKit's UIDynamicBehavior to Stellar's animation system; handles attachment and execution of behaviors.
• Sources/AnimationSequence.swift — Manages chaining and sequencing of multiple animations; critical for understanding how complex animation workflows are built.
• Sources/Chainable.swift — Protocol enabling fluent API design for animation configuration; defines the builder pattern used throughout the library.
• Sources/TimingType.swift — Defines timing curves and easing functions; fundamental to controlling animation pacing and acceleration.

Add a New Animation Behavior Type

1. Create a new behavior configuration protocol conforming to BasicConfigurable in a new file Sources/YourBehaviorConfigurable.swift (Sources/BasicConfigurable.swift)
2. Add the new behavior type to the AnimationType enum in Sources/AnimationType.swift (Sources/AnimationType.swift)
3. Implement behavior application logic in Sources/DynamicItem+Behavior.swift by adding a case handler (Sources/DynamicItem+Behavior.swift)
4. Add a convenience extension method on Chainable in Sources/BasicChainable.swift to expose the new behavior type (Sources/BasicChainable.swift)
5. Create example usage in StellarDemo/StellarDemo/ExampleNViewController.swift (StellarDemo/StellarDemo/Example1ViewController.swift)

Animate a Custom Object Type

1. Make your object conform to DynamicItem protocol by implementing required properties (Sources/DynamicItem.swift)
2. Implement the Vectorial protocol for properties that should be interpolated during animation (Sources/Vectorial.swift)
3. Use Physical.animatableView() or Physical.animatableLayer() to create an animator for your object, or directly call animation methods (Sources/Physical.swift)
4. Chain animation configurations using methods from Chainable protocol (Sources/Chainable.swift)

Create a Sequenced Animation Chain

1. Start with a view/layer and call animation method (e.g., .snap()) which returns a Chainable instance (Sources/UIView+Stellar.swift)
2. Chain additional animations using .then() method from AnimationSequence (Sources/AnimationSequence.swift)
3. Add completion/update callbacks via .onProgress() and .onComplete() methods (Sources/AnimationContext.swift)
4. Control sequence execution with methods from StepControllable protocol if dynamic control needed (Sources/StepControllable.swift)

Customize Timing/Easing for an Animation

1. After calling an animation method, call .timingFunction() with a TimingType from the enumeration (Sources/TimingType.swift)
2. Or provide a custom TimingFunction implementing cubic Bézier parameters for fine-grained control (Sources/TimingFunction.swift)
3. The timing is applied during interpolation in Interpolatable conformers automatically (Sources/Interpolatable.swift)

• UIKit UIDynamicAnimator — Provides built-in physics simulation engine; Stellar extends and abstracts it for cleaner, more composable API.
• CADisplayLink — Synchronizes value updates to device refresh rate (60 FPS) for smooth, frame-accurate

No visible hidden traps in the file list, but verify: (1) UIView/CALayer animation thread safety when using from background threads (not visible in snapshot); (2) UIDynamics behavior adds/removes from UIViewController.view—ensure animation container is managed correctly; (3) Easing curve enums (Default, EaseIn, etc.) may not map to exact CAMediaTimingFunction equivalents—test custom curves; (4) No version-locked Swift syntax visible—may break on Swift 5.0+ depending on implementation; (5) Carthage build artifacts present but test targets not visible—unclear if CI actually runs tests.

• UIKit's UIDynamics — Stellar wraps UIDynamics to provide high-level APIs; understanding gravity behaviors, snap behaviors, and attachment behaviors is essential to using Stellar correctly and knowing its limitations
• Physics-based animation (spring damping, velocity) — Stellar's core value is simulating realistic physics (springs, gravity, collisions) instead of linear time-based tweens; understanding damping ratio and stiffness affects animation feel
• CALayer and CADisplayLink (frame-based rendering) — Stellar animates UIView/CALayer properties and coordinates with the display link refresh cycle; misunderstanding this leads to performance or synchronization bugs
• Protocol-based polymorphism (Swift generics) — Stellar uses Interpolatable protocol and Configurable protocols to enable generic animation of any type; this design pattern enables framework extensibility without boilerplate
• Fluent API / method chaining — Stellar's ergonomic API (view.moveX(200).duration(2).easing(.SwiftOut)) relies on method chaining returning self; understanding this pattern is critical for readability and API extension
• Easing curves and timing functions — Stellar provides 18+ easing functions (SwiftOut, ElasticIn, BounceOut, etc.) to control animation acceleration/deceleration; choosing the right curve is key to polished UX

• realm/SwiftyJSON — Not directly related but shows mature Swift framework patterns with Carthage/CoCoaPods dual support that Stellar could learn from
• ramotion/animated-tab-bar — Solves similar animation-for-iOS problem but focused on tab bar interactions; complementary example of physics-inspired UI in Swift
• facebook/pop — Predecessor physics animation library (Objective-C) that inspired UIKit's UIDynamics; Stellar is the modern Swift equivalent
• onmyway133/Poke — Similar Swift animation library wrapping CADisplayLink; shows alternative approach to Stellar's UIDynamics-based architecture
• CocoaPods/CocoaPods — Stellar is distributed via CoCoaPods; users will interact with the spec repository and dependency resolver

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.

Migrate from Travis CI to GitHub Actions workflow

The repo uses outdated .travis.yml for CI/CD. GitHub Actions is now standard and integrates seamlessly with GitHub. This would modernize the CI pipeline, improve build reliability, and provide better visibility into test results directly in PRs.

• [ ] Create .github/workflows/swift-build.yml with steps to checkout, build with Swift Package Manager, and run tests across iOS/macOS platforms
• [ ] Add workflow job to validate Carthage build using carthage update --no-build && carthage build --no-skip-current
• [ ] Add workflow job to validate CocoaPods spec using pod lib lint Stellar.podspec
• [ ] Remove or archive .travis.yml once workflows are verified working
• [ ] Update README.md badges to reference GitHub Actions status instead of Travis

Add comprehensive unit tests for core animation behavior files

The Sources/ directory contains critical animation logic (AnimationContext.swift, DynamicItem.swift, UIDynamicBehavior+Commit.swift, etc.) but there's no visible Tests/ directory. Adding tests for these files would catch regressions and make the library more maintainable.

• [ ] Create Tests/AnimationContextTests.swift with tests for animation initialization, configuration, and lifecycle
• [ ] Create Tests/DynamicItemTests.swift testing DynamicItem, DynamicItemBasic, DynamicItemGravity behavior setup and property changes
• [ ] Create Tests/AnimationSequenceTests.swift for chaining and sequencing animations
• [ ] Create Tests/TimingFunctionTests.swift to validate UnitBezier calculations and TimingSolvable implementations
• [ ] Add test targets to Package.swift and StellarDemo.xcodeproj for xcodebuild integration

Document public API with code examples in Sources/ comments

While the README shows the library exists, the core source files lack detailed documentation of public APIs. Key files like Physical.swift, Chainable.swift, and the CALayer+Stellar.swift extensions lack usage examples. This makes onboarding harder for contributors and users.

• [ ] Add comprehensive doc comments to Sources/Physical.swift explaining the Physical protocol, animation types, and basic usage example
• [ ] Add doc comments to Sources/Chainable.swift and Sources/BasicChainable.swift documenting method chaining patterns with code snippets
• [ ] Add doc comments to Sources/CALayer+Stellar.swift and Sources/UIView+Stellar.swift showing practical animation examples for common use cases
• [ ] Add doc comments to Sources/AnimationStep.swift and Sources/AnimationSequence.swift explaining step-by-step and sequential animation construction
• [ ] Create Sources/README.md or update root README.md with API reference section linking to documented entry points

• Add unit tests for Interpolatable protocol: Currently no test files visible in the 60-file list. Create Tests/InterpolatableTests.swift testing Float, CGPoint, UIColor, CGRect interpolation with edge cases (zero ranges, NaN values).
• Document AnimationSequence chaining with examples: README shows one .gif example of chaining but doesn't explain the fluent API or how to compose parallel vs. sequential animations. Add a 'Chaining Guide' section with code examples for 3 real UI scenarios (cascading list animations, dependent transitions, etc.).
• Implement and expose collision behavior: Code explicitly marks Collision as 'coming soon'. Create CollisionConfigurable.swift and DynamicItemCollision.swift following the pattern of GravityConfigurable and DynamicItemGravity, wrapping UICollisionBehavior.

The Stellar animation library codebase shows generally good security posture for a Swift library. No critical vulnerabilities were identified in the source code structure. However, there are configuration and repository management issues: build artifacts and XCode user data should not be committed to version control. The library lacks explicit security documentation. No hardcoded secrets, injection risks, or infrastructure misconfigurations were identified. The primary concerns are related to repository hygiene and best practices rather than active security threats in the code itself.

• Medium · Build Artifacts Committed to Repository — Carthage/Build/iOS/. The Carthage/Build directory containing compiled frameworks, symbol maps, and debug symbols is committed to version control. This increases repository size, can expose build artifacts, and makes it harder to maintain clean build environments. Fix: Add 'Carthage/Build/' to .gitignore and instruct users to run 'carthage bootstrap' locally. Remove the directory from git history using 'git rm -r --cached Carthage/Build/'
• Medium · XCode User Data Committed to Repository — StellarDemo/StellarDemo.xcodeproj/xcuserdata/. User-specific XCode configuration files (xcuserdata, UserInterfaceState.xcuserstate, Breakpoints_v2.xcbkptlist) are committed. These should be local-only and can contain sensitive development environment information. Fix: Add '*.xcuserdata' and 'xcuserdata/' to .gitignore. Remove from git history using 'git rm -r --cached StellarDemo/StellarDemo.xcodeproj/xcuserdata/'
• Low · Missing SECURITY.md or Security Policy — Repository root. The repository lacks a SECURITY.md file or documented security policy for reporting vulnerabilities. This makes it difficult for security researchers to responsibly disclose vulnerabilities. Fix: Create a SECURITY.md file with vulnerability disclosure guidelines and contact information for security issues
• Low · Incomplete Dependency Tracking — Package.swift, Cartfile.resolved. While Cartfile.resolved is present, there is no visible Package.swift dependency lock file or explicit version pinning documentation visible in the provided content. Fix: Ensure Package.swift properly specifies exact versions or version ranges for all dependencies. Use 'swift package resolve' and commit the lock file

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.