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/andreamazz/BubbleTransition 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

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "andreamazz/BubbleTransition(\\.git)?\\b" \\
  && ok "origin remote is andreamazz/BubbleTransition" \\
  || miss "origin remote is not andreamazz/BubbleTransition (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/BubbleTransition.swift" \\
  && ok "Source/BubbleTransition.swift" \\
  || miss "missing critical file: Source/BubbleTransition.swift"
test -f "BubbleTransition.podspec" \\
  && ok "BubbleTransition.podspec" \\
  || miss "missing critical file: BubbleTransition.podspec"
test -f "Demo/Demo/ViewController.swift" \\
  && ok "Demo/Demo/ViewController.swift" \\
  || miss "missing critical file: Demo/Demo/ViewController.swift"
test -f "Demo/Demo/ModalViewController.swift" \\
  && ok "Demo/Demo/ModalViewController.swift" \\
  || miss "missing critical file: Demo/Demo/ModalViewController.swift"
test -f "BubbleTransition/BubbleTransition.h" \\
  && ok "BubbleTransition/BubbleTransition.h" \\
  || miss "missing critical file: BubbleTransition/BubbleTransition.h"

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

BubbleTransition is a Swift library that implements a custom iOS modal transition animation where a view controller presents/dismisses with an expanding and contracting bubble effect originating from a specified point (typically a button). It provides UIViewControllerTransitioningDelegate conformance and animates the modal using CABasicAnimation on a circular mask layer, creating a smooth bubble-pop visual effect. Simple two-project structure: BubbleTransition/ contains the core Swift framework (main logic), and Demo/ is a standalone Xcode project demonstrating usage via storyboards (ViewController.swift → ModalViewController.swift). Demo uses CocoaPods for dependency management and includes a live appetize.io preview.

iOS app developers building custom UI experiences who want to replace standard modal presentations with branded, interactive bubble animations. Specifically for teams using Swift (5.0+) or Objective-C who need control over presentation timing, color, and gesture-based dismissal in their apps.

Production-ready and actively maintained. The library is at version 3.2.0+, supports Swift 5.0+, and is distributed via CocoaPods, Carthage, and SPM. The codebase shows Swift (~10K LOC) as primary with legacy Objective-C support (~551 LOC). No visible test suite in the file list is a minor concern, but the established pod ecosystem and demo app suggest stability.

Low risk. Single maintainer (andreamazz) is the primary concern for long-term maintenance. The library has minimal dependencies (none visible in file list beyond iOS SDK), reducing supply-chain risk. No recent commit dates visible in metadata, so verify last commit before adoption. Lacks automated tests (no DemoTests content visible), making regression detection manual.

Unable to determine from file structure alone—no CHANGELOG recent entries, git history, or CI/CD pipeline visible in the file list. Check GitHub Issues and recent commits to assess current activity level.

git clone https://github.com/andreamazz/BubbleTransition.git
cd Demo
pod install
open Demo.xcworkspace
# Select Demo scheme, build and run on iOS simulator or device

Daily commands: Open Demo/Demo.xcworkspace (not .xcodeproj) in Xcode, select 'Demo' scheme, press Cmd+R. The demo app presents a storyboard with a button that triggers the bubble transition to ModalViewController. Interactive dismiss via upward swipe gesture (if BubbleInteractiveTransition is wired).

• Source/BubbleTransition.swift — Core implementation of the bubble transition animation logic; the entire library's functionality depends on this single file
• BubbleTransition.podspec — Package definition for CocoaPods distribution; required to understand dependency management and versioning
• Demo/Demo/ViewController.swift — Primary demo entry point showing how to instantiate and configure BubbleTransition in a real app
• Demo/Demo/ModalViewController.swift — Companion modal controller demonstrating the presented view hierarchy and interaction patterns
• BubbleTransition/BubbleTransition.h — Objective-C header exposing the Swift module; required for Xcode framework integration and visibility
• Package.swift — Swift Package Manager manifest; enables adoption via SPM as an alternative to CocoaPods/Carthage

• BubbleTransition class (Swift, UIKit, Core Animation) — Implements UIViewControllerAnimatedTransitioning to orchestrate bubble animation during modal presentation and dismissal; manages CABasicAnimation creation and timing
  • Failure mode: If animation context is invalid or view hierarchy is modified mid-animation, bubble may not render or animation may hang; no error recovery
• CAShapeLayer bubble (Core Animation, CAShapeLayer, CGPath) — Renders the circular bubble mask as a CAShapeLayer with radius animation from small (origin) to large (full screen)
  • Failure mode: If bounds calculations are incorrect, bubble may appear off-screen or clip unexpectedly; malformed CGPath crashes drawing
• UIViewController presentation delegate (UIKit, UIViewControllerTransitioningDelegate) — Acts as intermediary between view controller and BubbleTransition; supplies transitioningDelegate and customPresentationController if needed
  • Failure mode: If delegate is not set or returns nil animator, UIKit falls back to default presentation style, bypassing bubble effect
• Demo application (Swift, UIKit, Storyboards) — Demonstrates practical usage: configuring BubbleTransition, setting fromFrame from button tap, and presenting modal with animation
  • Failure mode: If frame calculation is wrong or transition is not retained, modal may present without animation or appear frozen

• ViewController (user tap) → BubbleTransition instance — User taps button; ViewController creates BubbleTransition, sets transitionMode and fromFrame, then calls presentViewController()
• presentViewController() call → UIViewControllerTransitioningDelegate — UIKit queries transitioningDelegate for custom animator via animationController(forPresented:presenting:source:)
• animationController() result → BubbleTransition.animateTransition() — UIKit calls BubbleTransition's animateTransition() method with UIViewControllerContextTransitioning context object
• BubbleTransition animation logic → CABasicAnimation + CAShapeLayer — BubbleTransition creates and configures CABasicAnimation for radius/

Customize bubble transition animation parameters

1. Open Source/BubbleTransition.swift and locate the BubbleTransition class properties (duration, timingFunction, interactionController) (Source/BubbleTransition.swift)
2. Modify delay, duration, or CAMediaTimingFunction constants in the animateTransition(using:) method to adjust animation speed and easing (Source/BubbleTransition.swift)
3. Test changes using Demo/Demo/ViewController.swift by running the demo app and triggering the modal presentation (Demo/Demo/ViewController.swift)

Configure BubbleTransition for a new modal controller

1. In your view controller that presents the modal, instantiate BubbleTransition: let transition = BubbleTransition() (Demo/Demo/ViewController.swift)
2. Set the transition's transitionMode (.present or .dismiss) and configure the fromFrame property to define the bubble origin point (Source/BubbleTransition.swift)
3. Assign the transition as the modalPresentationStyle's transitioningDelegate and set dismissInteractiveGesture if interactivity is desired (Demo/Demo/ViewController.swift)
4. Present the modal controller using presentViewController(:animated:completion:) — the bubble transition will execute automatically (Demo/Demo/ViewController.swift)

Add interactive gesture-driven dismissal

1. In Source/BubbleTransition.swift, review the interactionController property and dismissInteractiveGesture configuration (Source/BubbleTransition.swift)
2. In your modal view controller, create a UIPanGestureRecognizer and attach it to trigger the transition's interactionController (Demo/Demo/ModalViewController.swift)
3. Ensure the gesture handler calls interactionController?.interruptibleAnimator(using:) when the gesture changes to integrate with the transition timing (Source/BubbleTransition.swift)

• UIViewControllerAnimatedTransitioning protocol — Apple's standard iOS API for custom modal transition animations; enables seamless integration with UIViewController's presentation system
• CABasicAnimation and CAShapeLayer — Core Animation provides GPU-accelerated, smooth bubble expansion/shrinkage with minimal CPU overhead
• Swift (5.0+) — Modern language with strong type safety and interoperability with UIKit; enables concise, maintainable animation code
• CocoaPods, Carthage, SPM — Multiple distribution channels maximize adoption across different iOS projects and dependency management preferences

• Single monolithic Source/BubbleTransition.swift file

  • Why: Simplicity and portability; the entire library is self-contained with no inter-module dependencies
  • Consequence: File may grow large if new transition modes are added; lacks modular code separation

• No external dependencies beyond UIKit

  • Why: Minimizes friction for integration into any iOS project; reduces pod bloat and compatibility issues
  • Consequence: All animation logic must be implemented from scratch using Core Animation; limits reuse of lower-level animation primitives

• Custom transition for presentation AND dismissal in single class

  • Why: Unified logic and configuration for both directions reduces code duplication
  • Consequence: The transitionMode property adds branching complexity; makes the class do two related but distinct jobs

• Does not provide interactive gesture-driven dismissal by default; requires manual UIGestureRecognizer integration
• Not a general-purpose animation library; specifically designed for bubble-expanding modal transitions only
• Does not handle orientation changes or adaptive layouts during transition
• No support for transitioning between multiple view hierarchies or complex view controller containers

No obvious environment setup required, but: (1) SPM integration requires Xcode 11+; (2) Demo uses Demo.xcworkspace not .xcodeproj—running .xcodeproj directly will fail pod dependencies; (3) Interactive gesture (BubbleInteractiveTransition) must be manually wired in UIViewController delegate methods—not automatic; (4) iOS 9.0+ minimum per podspec, but Swift 5.0 requirement may limit older Xcode versions.

• UIViewControllerTransitioningDelegate — Core protocol this library implements to inject custom animations at presentation/dismissal; essential to understanding how iOS intercepts standard transitions
• CABasicAnimation — The underlying animation engine for the expanding/contracting bubble effect; you'll modify duration, timing, and keyframes here
• CAShapeLayer mask — Technique for clipping content to a circular path; BubbleTransition uses this to create the bubble silhouette effect
• UIViewControllerAnimatedTransitioning — Protocol you conform to when implementing custom transition animations; defines transitionDuration and animateTransition callbacks
• Interactive Gesture Transitions (UIPercentDrivenInteractiveTransition) — Powers the swipe-to-dismiss feature via BubbleInteractiveTransition; allows user gesture to drive animation progress rather than fixed duration
• Modal Presentation Style (.custom) — Setting modalPresentationStyle = .custom tells iOS to use your transition delegate instead of standard UIModalPresentationStyle behavior

• ramotion/circle-menu — Similar circular-geometry-based UI transition library by another prolific iOS animator; reference for alternative bubble/radial animation techniques
• ramotion/paper-onboarding — Companion library by same philosophy (custom transitions + gesture interactivity); useful for learning multi-screen transition patterns
• Ramotion/cardslider-ios — Ecosystem peer: custom transition + UIViewControllerTransitioningDelegate; reference implementation for interactive dismissal
• lkzhao/Hero — Competing solution: declarative custom view controller transitions with motion semantics; study alternative to delegation-based approach

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 BubbleTransition core animation logic

The repo currently has minimal test coverage (only Demo/DemoTests/DemoTests.swift exists). The BubbleTransition framework lacks unit tests for critical animation components like transition timing, bubble size calculations, and dismiss behavior. This would catch regressions and make the library more maintainable for contributors.

• [ ] Create BubbleTransition/Tests directory structure mirroring the framework
• [ ] Add unit tests for BubbleTransitionAnimator's animation duration and timing curve properties
• [ ] Add tests for bubble radius calculations and center point positioning logic
• [ ] Add tests for interactive gesture dismissal behavior and edge cases
• [ ] Integrate test target into BubbleTransition.xcodeproj with proper build phases

Add Swift Package Manager (SPM) support alongside CocoaPods/Carthage

The repo supports CocoaPods and Carthage (as noted in README badges) but lacks a Package.swift manifest. SPM is now the standard for Swift package distribution and would significantly improve accessibility for modern Swift projects and make the library dependency management easier.

• [ ] Create Package.swift in repo root with proper product and target definitions
• [ ] Define correct minimum Swift version matching .swift-version file requirement
• [ ] Test SPM installation by adding to a test project's Package.swift
• [ ] Update README.md with SPM installation instructions and badge
• [ ] Verify all source files in BubbleTransition/ are properly included in package targets

Add GitHub Actions CI workflow for automated testing and release validation

The repo has GitHub Issue templates but no .github/workflows directory for continuous integration. This would ensure pull requests are validated against Swift 5.0+, catch breaking changes early, and automate release consistency checks before CocoaPods/Carthage updates.

• [ ] Create .github/workflows/test.yml for running swift test and building on multiple macOS versions
• [ ] Add workflow matrix testing for Swift 5.0 through latest version
• [ ] Create .github/workflows/release.yml to validate podspec linting before releases
• [ ] Configure workflows to validate example app builds don't break in Demo/ directory
• [ ] Add workflow status badges to README.md

• Add unit tests for BubbleTransition animation timing in Demo/DemoTests/DemoTests.swift—currently empty. Test that duration parameter is respected and bubble expands/contracts symmetrically.
• Document the Objective-C usage in README.md with a code example (gist link exists but not in main docs). Include BubbleTransition.h import and setup equivalent to the Swift example.
• Add support for custom bubble animation curve (CAMediaTimingFunction) as a public property. Currently hardcoded; allowing .easeInOut, .easeOut, etc. would enhance customization without breaking API.

This is a Swift UI library (BubbleTransition) with a minimal attack surface. No critical or high-severity vulnerabilities were identified. The codebase lacks hardcoded secrets, injection vulnerabilities, or dangerous dependencies based on the available file structure. The primary concerns are minor: use of legacy configuration mechanisms and external service dependencies in documentation. The project maintains good security practices with no exposed credentials, dangerous patterns, or infrastructure misconfigurations visible. The library is well-maintained with modern Swift 5.0 support and proper package management through CocoaPods and Carthage.

• Low · Outdated Swift Version Specification — .swift-version. The .swift-version file exists in the repository, indicating a legacy Swift version constraint mechanism. This is outdated and should be managed through modern package configuration (Package.swift or Xcode build settings). While not a direct security vulnerability, it may lead to the use of older Swift versions with unpatched security issues. Fix: Remove .swift-version file and specify Swift language version requirements in Package.swift or through Xcode build settings instead.
• Low · Potential Information Disclosure via CocoaPods Badge URL — README.md - CocoaPods badge. The README contains a CocoaPods badge URL that uses an external service (cocoapod-badges.herokuapp.com). External service dependencies can be a supply chain risk if the service is compromised. Fix: Consider using static badges or self-hosted badge services. Verify the external service's security practices.
• Low · Live Demo Link via Third-party Service — README.md - Appetize.io demo link. The README contains a live demo link via appetize.io. While convenient, this creates a dependency on a third-party service that could potentially be compromised or misused. Fix: Monitor the security posture of the demo service. Consider adding a security disclaimer for users accessing external services.

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.