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/eggswift/ESTabBarController 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 3y ago

• 24+ active contributors
• Distributed ownership (top contributor 45% of recent commits)
• MIT licensed
• CI configured
• ⚠ Stale — last commit 3y 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 eggswift/ESTabBarController repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/eggswift/ESTabBarController.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "eggswift/ESTabBarController(\\.git)?\\b" \\
  && ok "origin remote is eggswift/ESTabBarController" \\
  || miss "origin remote is not eggswift/ESTabBarController (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 "ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift" \\
  && ok "ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift" \\
  || miss "missing critical file: ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift"
test -f ".swift-version" \\
  && ok ".swift-version" \\
  || miss "missing critical file: .swift-version"
test -f "ESTabBarController-swift.podspec" \\
  && ok "ESTabBarController-swift.podspec" \\
  || miss "missing critical file: ESTabBarController-swift.podspec"
test -f ".swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata" \\
  && ok ".swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata" \\
  || miss "missing critical file: .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata"
test -f "ESTabBarControllerExample/ESTabBarControllerExample.xcodeproj/project.pbxproj" \\
  && ok "ESTabBarControllerExample/ESTabBarControllerExample.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: ESTabBarControllerExample/ESTabBarControllerExample.xcodeproj/project.pbxproj"

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

ESTabBarController is a Swift UITabBarController subclass that enables deep customization of tab bar UI, badges, and item animations while maintaining API compatibility with UITabBarController. It supports Lottie animations and allows mixing custom ESTabBarItem instances with native UITabBarItem objects in the same tab bar. Single-package structure: core ESTabBarController logic lives in the root Sources/ (inferred from .swiftpm presence), example app at ESTabBarControllerExample/ with standard Xcode project layout showing Assets (TabBar, cardboard images), and podspec at root for distribution.

iOS developers building apps with custom tab bar designs who need to modify fonts, colors, badge styling, add animations, or create oversized tab items without fighting UITabBarController's limitations.

Active and production-ready: supports Swift 5, distributed via CocoaPods/Carthage/SwiftPM, has structured example project (ESTabBarControllerExample/), and uses CI (Travis config present). Last activity visible in package resolution and maintained podspec, though commit recency not visible in file list.

Moderate risk: single-maintainer pattern common in open-source UI libraries (check GitHub for contributor count), no visible test suite in file structure (missing Tests/ directory), and deeply subclasses UITabBarController which can break across iOS releases. Lottie dependency adds external complexity but is optional.

Project appears stable rather than actively developed: file structure shows mature Swift 5 setup with SwiftPM workspace, Carthage/CocoaPods support all configured. No visible PR/milestone data in files, suggesting maintenance mode focused on compatibility rather than new features.

Clone: git clone https://github.com/eggswift/ESTabBarController.git && cd ESTabBarController. Install: pod install (CocoaPods) or open .swiftpm/xcode/package.xcworkspace for SwiftPM. Run example: open ESTabBarControllerExample/ESTabBarControllerExample.xcodeproj && select scheme 'ESTabBarController' in Xcode.

Daily commands: Open ESTabBarControllerExample/ESTabBarControllerExample.xcodeproj, select the 'ESTabBarController' scheme, and press Cmd+R. Or via SwiftPM: swift build -c release from root.

• ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift — Application entry point demonstrating ESTabBarController initialization and configuration patterns for the framework.
• .swift-version — Specifies Swift language version compatibility; critical for understanding minimum deployment requirements.
• ESTabBarController-swift.podspec — Pod specification file defining dependencies, version, and distribution metadata for CocoaPods integration.
• .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata — Swift Package Manager workspace configuration; essential for understanding modular structure and dependency management.
• ESTabBarControllerExample/ESTabBarControllerExample.xcodeproj/project.pbxproj — Xcode project configuration containing build settings, target definitions, and resource references for the example app.
• .travis.yml — CI/CD pipeline configuration defining build, test, and deployment automation for quality assurance.

• ESTabBarController (UITabBarController, UIViewController, UITabBar) — Root container managing tab selection, view controller transitions, and item state coordination.
  • Failure mode: Incorrect tab state persistence; gesture conflicts with child VCs; memory leaks from strong circular refs.
• ESTabBarItem (UITabBarItem, Lottie, CoreAnimation) — Wraps native UITabBarItem with custom appearance (icons, colors, fonts) and animation trigger logic.
  • Failure mode: Animation memory bloat if Lottie JSON not released; icon rendering delays from slow asset loading.
• Badge system (UIView, CALayer, CoreText) — Renders notification indicators on tab items with customizable appearance and update mechanisms.
  • Failure mode: Badge overflow UI clipping; memory leaks from retained animation layers if not cleared on removal.
• Example App (Swift, UIKit, Xcode) — Reference implementation demonstrating framework API usage, asset structure, and customization patterns.
  • Failure mode: Outdated example code diverging from framework API; missing edge case demonstrations.

• User tap on tab bar → UITabBar gesture recognizer — Native touch event captured by UITabBar and routed to ESTabBarController delegate.
• ESTabBarController delegate → ESTabBarItem selection state — Selection index updated; item appearance (icon swap, color change) triggered.
• Item selection state → Animation engine (Lottie or CoreAnimation) — Animation configuration applied to selected tab item; playback starts if defined.
• Animation completion → ViewController presentation — After animation finishes, corresponding view controller presented/pushed to navigation stack.
• Badge model update → Tab item badge view — External notification triggers badge refresh; custom renderer updates badge count/visibility.

Add a new tab item with custom icon and animation

1. Create icon assets in Assets.xcassets directory following naming convention (e.g., home.imageset, home_1.imageset for selected state) (ESTabBarControllerExample/ESTabBarControllerExample/Assets.xcassets)
2. In AppDelegate.swift or main view controller, create ESTabBarItem instances with custom appearance and animation configurations (ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift)
3. Configure tab bar controller with viewControllers array containing the new tab's view controller (ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift)

Customize tab bar background and styling

1. Add background image assets (e.g., background.imageset, background_dark.imageset) to TabBar directory in Assets.xcassets (ESTabBarControllerExample/ESTabBarControllerExample/Assets.xcassets/TabBar)
2. Configure ESTabBarController appearance properties for colors, shadows, and selected state styling (ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift)
3. Apply theme-specific settings in AppDelegate for light/dark mode variants (ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift)

Add badge and notification indicators to tab items

1. Access ESTabBarItem's badge property through tabBar.items array in ESTabBarController (ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift)
2. Configure badge appearance (color, text, animation) on specific tab items at runtime (ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift)
3. Update badge state based on application events and notifications (ESTabBarControllerExample/ESTabBarControllerExample/AppDelegate.swift)

• Swift 5 — Modern, type-safe language for iOS development with strong stdlib support for UI customization.
• UITabBarController subclass — Leverages native iOS framework foundation while extending with custom rendering and animation capabilities.
• Lottie animation support — Enables complex vector animations on tab items without manual CoreAnimation code, improving UX polish.
• CocoaPods + SPM dual distribution — Maximizes reach to iOS developers across different dependency management preferences and iOS versions.

• Subclass UITabBarController rather than create composition wrapper

  • Why: Provides drop-in replacement capability and direct access to native tab bar delegate patterns.
  • Consequence: Couples framework to Apple's UITabBarController interface; harder to support cross-platform in future.

• Optional Lottie dependency

  • Why: Allows framework use without Lottie for simpler use cases, reduces binary size.
  • Consequence: Developers must manually integrate Lottie if animations are desired; conditional compilation complexity.

• Icon-based customization over text-only tabs

  • Why: Modern app UX convention; aligns with AppStore norms and reduces tab label clutter.
  • Consequence: Requires designers to provide icon assets in multiple scales; not suitable for text-heavy tab labels.

• Cross-platform support (Android, web, macOS)
• Real-time notification system (external push handling)
• Accessibility features beyond native UIKit support
• Dark mode automatic theming (manual configuration required)
• Built-in view controller transition animations (uses native presenters)

• Direct UITabBarItem manipulation (Medium) — AppDelegate.swift (inferred from example usage): Developers may directly modify native UITabBarItem instead of ESTabBarItem wrapper, bypassing custom animation/appearance logic.
• Lottie JSON hardcoded paths (Low) — Example app asset references: Animations loaded via string paths rather than type-safe constants; brittle to refactoring.
• Missing Lottie error handling (Medium) — Animation initialization (inferred): No visible fallback if Lottie JSON fails to load or parse; silent failures degrade UX.
• Excessive badge re-rendering (Medium) — Badge update logic (inferred): Badge view may redraw on every model update without batching; causes animation jank on rapid notifications.

• Asset loading in tab initialization (undefined) — Loading multiple icon assets (selected/unselected

Lottie is optional via podspec but deeply integrated in examples—ensure Lottie is installed if using animation features. UITabBarController's 'More' item behavior (when >5 items) is replicated but may differ subtly across iOS versions. SwiftPM workspace at .swiftpm/xcode/ requires opening that specific workspace, not the plain .xcodeproj, to resolve dependencies correctly.

• PagingKit/PagingKit — Alternative customizable tab/paging controller for Swift with similar goals of flexible UI without UITabBarController constraints
• Yalantis/Pager — Provides animated tab controller with swipe gestures and custom styling, common alternative in same space
• airbnb/lottie-ios — The Lottie animation library integrated optionally; critical dependency for animation features in ESTabBarController
• realm/SwiftLint — Swift code quality tool; pairs well with this UIKit project for maintaining style consistency across contributors
• apple/swift-package-manager — Underpins the .swiftpm configuration and distribution mechanism used by this library

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 GitHub Actions CI/CD workflow for Swift package validation

The repo has .travis.yml (outdated Travis CI config) but lacks modern GitHub Actions workflows. Given the SwiftPM, CocoaPods, and Carthage support mentioned in README, a GitHub Actions workflow would validate the package builds correctly across iOS versions, run SwiftLint, and test both SPM and CocoaPods installations. This is critical for maintaining compatibility given the multiple distribution methods.

• [ ] Create .github/workflows/swift.yml to build and test the Swift package
• [ ] Add matrix testing for iOS 12+ deployment targets (referenced in .swift-versions)
• [ ] Validate CocoaPods spec using 'pod lib lint' in the workflow
• [ ] Add SwiftLint validation step to maintain code quality across contributions
• [ ] Remove or deprecate .travis.yml in favor of GitHub Actions

Create unit tests for ESTabBarController core functionality

The repo contains extensive example code (ESTabBarControllerExample/) but there is no visible test directory or test targets. Core features like badge customization, animation states, and Lottie integration need dedicated unit tests to prevent regressions and make contributions safer. This is especially important for a UI framework where visual/animation changes could break existing behavior.

• [ ] Create Tests/ directory at repo root with test targets for macOS/iOS
• [ ] Add tests for ESTabBarItem initialization, badge updates, and selection state management
• [ ] Add tests for animation handlers and Lottie animation integration
• [ ] Add UI snapshot tests for tabbar layout and item rendering across device sizes
• [ ] Wire test target into the .xcodeproj and add test execution to CI workflow

Expand README with API documentation for main customization points

The README snippet shows the project is customizable with UI, badges, and animations, but doesn't document how to actually use these features. New contributors and users can't discover the public APIs. Adding a Features section with code examples for common customizations (custom badge views, animation triggers, Lottie setup) would improve adoptability and guide contributors on what to test.

• [ ] Add 'Features' section to README documenting badge customization API with example code
• [ ] Add 'Custom Animations' subsection explaining how to add custom animation handlers
• [ ] Add 'Lottie Integration' subsection with setup steps and example JSON file integration
• [ ] Add 'API Reference' section linking to major classes (ESTabBarController, ESTabBarItem, ESTabBarItemContentView)
• [ ] Create CONTRIBUTING.md with setup instructions, testing requirements, and code style guidelines

• Add unit tests for ESTabBarItem badge update logic and animation state transitions—currently no Tests/ directory visible, start with XCTest in a new Tests/ESTabBarControllerTests/ folder targeting badge badge count changes.
• Document animation API with Lottie examples—README shows feature flags but no code examples for loading .json Lottie files; add a dedicated AnimationGuide.md with GIF examples.
• Create accessibility (VoiceOver) test coverage for custom tab item interactions—UITabBarController's accessibility features may not transfer to custom ESTabBarItem rendering; add XCUITest cases in ESTabBarControllerExample.

The ESTabBarController iOS UI library presents a minimal security risk profile based on the available file structure analysis. This is a UI/presentation layer library with no apparent database interactions, network operations with secrets, or cryptographic implementations visible. Main concerns are: (1) incomplete dependency information prevents full vulnerability assessment, (2) missing explicit security documentation and policies, and (3) no visible SAST/dependency scanning in the provided CI configuration. The codebase appears well-maintained with proper version control practices (.gitignore present) and multi-platform support infrastructure. Recommendations focus on implementing security scanning in the development pipeline and establishing clear vulnerability disclosure procedures rather than addressing critical code vulnerabilities.

• Low · Missing Package Manifest File — Package.swift (missing). The repository appears to support Swift Package Manager (SwiftPM) based on the .swiftpm directory structure, but no Package.swift file is visible in the provided file listing. This could indicate incomplete dependency management configuration or missing dependency declarations. Fix: Ensure a Package.swift manifest file exists at the root of the repository with proper dependency declarations and security constraints (minimum version requirements, exact versions for critical dependencies).
• Low · Incomplete Dependency Visibility — ESTabBarControllerExample/ESTabBarControllerExample.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. The Package.resolved file exists but actual dependency content was not provided for analysis. This prevents verification of known vulnerable dependency versions or unexpected transitive dependencies. Fix: Review and audit all dependencies in Package.resolved. Implement dependency scanning tools (e.g., Swift Package Index, Snyk) in CI/CD pipeline to detect known vulnerabilities. Pin to specific stable versions rather than floating versions.
• Low · Travis CI Configuration Not Provided — .travis.yml. The .travis.yml file is present but content was not provided. This file controls CI/CD build and test processes. Without visibility into its contents, potential security misconfigurations in the build pipeline cannot be assessed. Fix: Ensure CI/CD configuration includes: code signing verification, dependency scanning, SAST tools, secure artifact handling, and no exposure of secrets in build logs.
• Low · No Visible Security Policy — Repository root. No SECURITY.md, security policy, or vulnerability disclosure guidelines are evident in the provided file structure. This makes it difficult for security researchers to responsibly report vulnerabilities. Fix: Create a SECURITY.md file documenting vulnerability disclosure process, supported versions, and security update procedures. Follow responsible disclosure practices.

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.