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/roberthein/BouncyLayout 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 6y ago

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "roberthein/BouncyLayout(\\.git)?\\b" \\
  && ok "origin remote is roberthein/BouncyLayout" \\
  || miss "origin remote is not roberthein/BouncyLayout (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/BouncyLayout/BouncyLayout.swift" \\
  && ok "Sources/BouncyLayout/BouncyLayout.swift" \\
  || miss "missing critical file: Sources/BouncyLayout/BouncyLayout.swift"
test -f "Sources/BouncyLayout/BouncyLayoutAttributes.swift" \\
  && ok "Sources/BouncyLayout/BouncyLayoutAttributes.swift" \\
  || miss "missing critical file: Sources/BouncyLayout/BouncyLayoutAttributes.swift"
test -f "Sources/BouncyLayout/BouncyLayoutBehavior.swift" \\
  && ok "Sources/BouncyLayout/BouncyLayoutBehavior.swift" \\
  || miss "missing critical file: Sources/BouncyLayout/BouncyLayoutBehavior.swift"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "Sources/BouncyLayout/ScrollViewBoundsObserver.swift" \\
  && ok "Sources/BouncyLayout/ScrollViewBoundsObserver.swift" \\
  || miss "missing critical file: Sources/BouncyLayout/ScrollViewBoundsObserver.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 2155 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2125d)"
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/roberthein/BouncyLayout"
  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).

BouncyLayout is a pure Swift 5 UICollectionViewLayout subclass that animates collection view cells with a configurable bounce physics effect as they scroll. It replaces the standard grid layout with one that applies dynamic damping and spring animations to cell positions based on scroll velocity, creating a playful elastic behavior in both horizontal and vertical directions. Monolithic single-package structure: Swift Package Manager defines the module in Package.swift, sources/ contains the BouncyLayout Swift implementation, and an example/ directory holds runnable demo apps. The .build/ directory shows it's compiled for x86_64 macOS with standard module caching.

iOS developers building consumer-facing apps who want to add delightful motion design to collection views without implementing custom CADisplayLink animations or spring physics themselves. Specifically useful for social feeds, photo galleries, or product showcases where visual polish drives user engagement.

The project appears moderately mature and actively maintained: it's written in pure Swift 5, supports multiple installation methods (CocoaPods, Carthage, SPM), and includes example implementations. However, the repo's age and star count aren't visible in provided data; the file structure shows a clean SPM-based build setup. No test suite is visible in the top 60 files, which is a gap for production use.

Low dependency risk—this is a single-file layout implementation with no external dependencies beyond UIKit. Single-maintainer risk (roberthein on GitHub) with limited visibility into issue response times or PR review cadence. No CI configuration visible in provided files, so regression testing relies on manual verification.

Unable to determine from provided file list—no recent commit hashes, PR descriptions, or open issues visible. The .build/ artifacts suggest recent local compilation, but no activity timeline is available.

git clone https://github.com/roberthein/BouncyLayout.git
cd BouncyLayout
swift build

Or add to your project via Swift Package Manager: In Xcode, File > Add Packages, paste https://github.com/roberthein/BouncyLayout.git, and select version.

Daily commands: For the example app: open example/ folder's .xcodeproj in Xcode and press Cmd+R. For library development: swift build compiles the layout, swift test runs tests (if test suite exists—not visible in file list).

• Sources/BouncyLayout/BouncyLayout.swift — Core UICollectionViewLayout subclass that implements the bounce animation effect—entry point for all layout calculations
• Sources/BouncyLayout/BouncyLayoutAttributes.swift — Custom UICollectionViewLayoutAttributes that stores bounce-specific properties and animation state for each cell
• Sources/BouncyLayout/BouncyLayoutBehavior.swift — Physics-based animation behavior that calculates bounce trajectories and damping—core algorithm for the bounce effect
• Package.swift — Swift Package Manager manifest defining module structure, targets, and dependencies
• Sources/BouncyLayout/ScrollViewBoundsObserver.swift — Monitors UICollectionView scroll events and triggers layout updates for the bounce animation
• Example/BouncyLayout.xcodeproj/project.pbxproj — Example project configuration demonstrating BouncyLayout integration patterns

• BouncyLayout (UIKit, Core Graphics) — UICollectionViewLayout subclass that manages cell frame calculation, applies bounce behavior, and invalidates layout on scroll
  • Failure mode: If scroll observer is not installed, layout will not update during scrolling and no bounce effect appears
• BouncyLayoutBehavior (Swift numerics (sin, exp, CGFloat math)) — Pure physics calculation engine that converts scroll offset delta into bounce offset, scale, and opacity values using damped harmonic motion
  • Failure mode: If damping factor or amplitude parameters are misconfigured, bounce may appear frozen or oscillate infinitely
• ScrollViewBoundsObserver (Foundation KVO, UIScrollView) — KVO observer on UICollectionView bounds that detects scroll changes and triggers layout invalidation
  • Failure mode: If observer is deallocated or not retained, scroll events will not trigger layout updates
• BouncyLayoutAttributes (UIKit, CoreGraphics, CATransform3D) — Custom UICollectionViewLayoutAttributes that stores and applies 3D transforms, opacity, and z-index for bounce effect
  • Failure mode: If attributes are not properly copied or applied, bounce visual effect will not render

• UICollectionView → BouncyLayout — Requests layout attributes for visible cell index paths; provides current scroll offset via bounds
• BouncyLayout → BouncyLayoutBehavior — Passes current scroll offset and cell index to calculate bounce transform parameters
• BouncyLayoutBehavior → BouncyLayout — Returns computed bounce offset, scale factor, and opacity for each cell
• BouncyLayout → BouncyLayoutAttributes — Sets transform3D and opacity on custom attributes object
• ScrollViewBoundsObserver → BouncyLayout — Notifies layout of bounds change, triggering invalidateLayout() call
• BouncyLayout → UICollectionView — Returns array of BouncyLayoutAttributes with bounce transforms applied

Customize Bounce Intensity and Damping

1. Access BouncyLayout instance's configuration property (Sources/BouncyLayout/BouncyLayout.swift)
2. Set bounceAmplitude (affects cell offset distance) and dampingFactor (affects oscillation decay) (Sources/BouncyLayout/BouncyLayoutConfiguration.swift)
3. Call invalidateLayout() to apply changes immediately (Sources/BouncyLayout/BouncyLayout.swift)

Add Horizontal Scrolling Support

1. Set scrollDirection to .horizontal on BouncyLayout instance (Sources/BouncyLayout/BouncyLayout.swift)
2. Update BouncyLayoutBehavior calculations to use CGPoint.x instead of .y for offset (Sources/BouncyLayout/BouncyLayoutBehavior.swift)
3. Verify ScrollViewBoundsObserver correctly tracks horizontal bounds changes (Sources/BouncyLayout/ScrollViewBoundsObserver.swift)

Adjust Item Size and Spacing

1. Modify itemSize property in BouncyLayoutConfiguration (Sources/BouncyLayout/BouncyLayoutConfiguration.swift)
2. Update interitemSpacing and lineSpacing in BouncyLayout's prepareLayout() method (Sources/BouncyLayout/BouncyLayout.swift)
3. Call invalidateLayout() to recalculate all cell frames (Sources/BouncyLayout/BouncyLayout.swift)

• UICollectionViewLayout subclass — Provides deep integration with UICollectionView's layout system to intercept cell positioning and apply real-time bounce transforms without custom gesture handling
• Swift 5 — Modern, type-safe language with strong value types (CGPoint, CGSize) ideal for geometric calculations and physics simulation
• Swift Package Manager — Lightweight dependency distribution model for iOS libraries; simpler than CocoaPods or Carthage for pure Swift modules
• CADisplayLink equivalent (scroll observer pattern) — Maintains 60fps bounce animation by recalculating attributes synchronously with scroll events rather than using discrete animation blocks

• Physics-based bounce calculation per scroll event rather than pre-computed animation timeline

  • Why: Allows dynamic response to variable scroll velocity and user gestures; provides smooth interactive feel
  • Consequence: Higher CPU cost per frame; requires careful damping tuning to avoid jittery behavior

• No explicit caching of layout attributes between invalidations

  • Why: Simplifies code and ensures bounce effect always reflects current scroll position accurately
  • Consequence: Recalculates attributes for all visible cells on every scroll event; may impact performance with very large collections (100+ cells)

• Single UICollectionViewLayout class handles both horizontal and vertical scrolling

  • Why: Reduces code duplication and provides unified configuration API
  • Consequence: Requires scroll direction to be set correctly; mixing directions in same layout instance is unsupported

• Does not support nested collection views or custom supplementary views (headers, footers)
• Does not provide gesture recognizers or custom touch handling—relies on standard UICollectionView scrolling
• Does not support rotation-aware layout or safe area insets beyond standard UICollectionViewLayout behavior
• Not designed for tvOS or macOS; iOS UIKit only

• Synchronous physics calculation on every scroll event (Medium) — Sources/BouncyLayout/BouncyLayoutBehavior.swift: Each scroll pixel recalculates bounce offset using trigonometric functions (sin, exp) for all visible cells; no frame skipping or throttling
• Direct scroll offset access without scroll direction abstraction — Sources/BouncyLayout/: undefined

No test suite visible in file list—PRs may lack regression coverage. No CI configuration (GitHub Actions, Travis, CircleCI) present, so changes aren't automatically validated across iOS versions. Single BouncyLayout.swift file means one large class; refactoring physics calculations requires careful testing of edge cases (fast scrolling, cell size changes, direction reversals). No documented minimum iOS deployment target in provided snippets.

• UICollectionViewLayout subclassing — BouncyLayout achieves bounce effects by overriding layoutAttributesForElements(_:) and invalidateLayout(withContext:) to compute custom cell frames; understanding UICollectionViewLayout's layout lifecycle is essential for modifying or debugging bounce behavior
• Spring physics simulation — The 'bounce' effect requires modeling spring-damper systems; BouncyLayout likely uses velocity-based spring calculations to create elastic behavior proportional to scroll speed
• CADisplayLink and animation timing — Smooth 60 FPS bounce animations depend on frame-by-frame position updates; BouncyLayout may use CADisplayLink or -layoutSubviews invalidation to synchronize physics calculations with screen refresh
• Scroll view delegate callbacks — BouncyLayout must hook into UICollectionView's scroll events (via UIScrollViewDelegate) to detect velocity and direction, then adjust layout attributes accordingly in real time
• Coordinate system transforms and view hierarchy — Bounce calculations must account for scroll offset, content inset, and cell position relative to viewport; incorrect transforms cause physics animations to apply to wrong coordinates
• Swift Package Manager module definitions — BouncyLayout's SPM Package.swift must correctly expose BouncyLayout as a public module; improper declarations prevent downstream consumers from importing and using the library

• uias/Pageboy — Alternative UICollectionViewLayout wrapper adding page-scrolling behavior; shows SPM+Carthage dual-packaging pattern applicable to BouncyLayout
• airbnb/lottie-ios — Complex motion library for iOS; demonstrates how to wrap low-level animations in reusable components similar to BouncyLayout's physics approach
• jdg/MBProgressHUD — Single-purpose, high-polish iOS utility library with similar standalone architecture and multi-installation-method support (CocoaPods, Carthage, manual)
• nicklockwood/iCarousel — Scroll-based carousel layout with physics-driven positioning; direct competitor implementing similar bounce/elastic scroll effects via custom UICollectionViewLayout
• roberthein/Ease — Companion library from same author; likely provides easing functions and animation helpers that BouncyLayout could leverage for smoother bounce curves

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.

Complete Carthage installation documentation in README

The README.md has an incomplete Carthage section that cuts off mid-sentence ('BouncyLayout is'). This is a quick win that improves discoverability for developers using Carthage as their dependency manager.

• [ ] Complete the Carthage section in README.md with the proper installation instructions
• [ ] Add the required github line following Carthage's standard format
• [ ] Test that the Carthage instructions work by validating against Carthage documentation
• [ ] Ensure consistency with the CocoaPods section formatting

Add unit tests for BouncyLayout core functionality

The repo lacks test coverage for the layout engine. With only build artifacts visible and no Tests directory in the structure, adding unit tests for bounce calculations, scroll position handling, and cell size changes would significantly improve code quality and prevent regressions.

• [ ] Create Tests/ directory structure with BouncyLayoutTests.swift
• [ ] Add tests for bounce animation calculations (amplitude, frequency)
• [ ] Add tests for horizontal vs vertical scrolling behavior
• [ ] Add tests for dynamic cell size change handling
• [ ] Verify tests run with swift test (SPM) or xcodebuild

Add Swift Package Manager (SPM) manifest validation and CI workflow

The repo uses Swift Package Manager (inferred from .build/ structure) but has no GitHub Actions workflow to validate the Package.swift manifest or run tests on push/PR. This prevents catching Swift version incompatibilities and build failures early.

• [ ] Create .github/workflows/swift.yml with matrix testing for iOS 13+
• [ ] Add steps to: swift build, swift test, and validate Package.swift syntax
• [ ] Ensure the workflow tests on macOS (for library validation) and optionally iOS simulator
• [ ] Update README.md with a build status badge showing the workflow runs

• Add unit tests for BouncyLayout: write XCTests under Tests/BouncyLayoutTests/ covering bounce calculations at different scroll velocities, both scroll axes, and cell size changes. Currently no test suite visible.
• Create animated GIF documentation: capture the three example animations (.gif files mentioned in README but not in file list), optimize them, and add to repo's art/ folder with alt-text for accessibility.
• Document the bounce configuration API: the README doesn't show available properties (e.g., damping, spring constant, max bounce distance). Add a 'Configuration' section to README with concrete example: let layout = BouncyLayout(); layout.damping = 0.8.

BouncyLayout is a lightweight UICollectionView layout library with minimal security attack surface. The codebase is a pure Swift iOS library focused on UI animations with no external dependencies listed, no database interactions, no network calls, and no user input processing. The build artifacts and cached modules are standard Swift Package Manager outputs. No credentials, secrets, injection points, or infrastructure misconfigurations were detected. The primary security considerations are standard iOS development best practices around dependency management and code review, which appear well-maintained.

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.