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/uias/Tabman 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.

GO — Healthy across all four use cases

• Last commit 2w ago
• 12 active contributors
• MIT licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 88% 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 uias/Tabman repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/uias/Tabman.

What it runs against: a local clone of uias/Tabman — 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 uias/Tabman | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 42 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "uias/Tabman(\\.git)?\\b" \\
  && ok "origin remote is uias/Tabman" \\
  || miss "origin remote is not uias/Tabman (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/Tabman/AutoInsetter/AutoInsetter.swift" \\
  && ok "Sources/Tabman/AutoInsetter/AutoInsetter.swift" \\
  || miss "missing critical file: Sources/Tabman/AutoInsetter/AutoInsetter.swift"
test -f "Sources/Tabman/Bar/BarButton/TMBarButton.swift" \\
  && ok "Sources/Tabman/Bar/BarButton/TMBarButton.swift" \\
  || miss "missing critical file: Sources/Tabman/Bar/BarButton/TMBarButton.swift"
test -f "Sources/Tabman/Bar/BarBackgroundView/TMBarBackgroundView.swift" \\
  && ok "Sources/Tabman/Bar/BarBackgroundView/TMBarBackgroundView.swift" \\
  || miss "missing critical file: Sources/Tabman/Bar/BarBackgroundView/TMBarBackgroundView.swift"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "Sources/Tabman/AutoInsetter/InsetCalculator/InsetCalculator.swift" \\
  && ok "Sources/Tabman/AutoInsetter/InsetCalculator/InsetCalculator.swift" \\
  || miss "missing critical file: Sources/Tabman/AutoInsetter/InsetCalculator/InsetCalculator.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 42 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~12d)"
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/uias/Tabman"
  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).

Tabman is a powerful paging view controller library for iOS that wraps Pageboy with interactive, customizable indicator bars. It enables developers to build tabbed interfaces where indicator bars sync seamlessly with page scrolling, supporting multiple bar styles (ButtonBar, LineBar, etc.) that can be positioned at top, bottom, or navigation item—solving the problem of building polished tab UIs without boilerplate. Single-package structure: root contains Swift source files, Docs/ holds tutorials and API guides, .github/workflows handles CI and releases, .swiftpm/ enables SPM integration. Core architecture layers Tabman (indicator bars) atop Pageboy (page controller); bars are composed components (TMBar, TMBarItem, TMBarIndicator) allowing mix-and-match customization.

iOS developers building tabbed interfaces (social media apps, news readers, settings screens) who need production-ready indicator bars with smooth animations and minimal setup code, rather than starting from UIPageViewController scratch or assembling indicator logic manually.

Mature and actively maintained. The codebase has Swift 5+ support, Swift Package Manager integration, comprehensive docs at Docs/, CI/CD via GitHub Actions (.github/workflows/build.yml, publish.yml), and migration guides for major versions (Tabman 2 and 3 guides present). No signs of abandonment—build badges and release workflows suggest active upkeep.

Low risk. Single maintainer (uias org) is a known concern, but the library is stable (on major version 3+) with clear interfaces. Main risk: tight coupling to Pageboy (a dependency), so breaking changes in Pageboy could cascade. No obvious large open issue backlog visible in file list. Swift 6 compatibility is declared but relatively new (Xcode 16+).

CI/CD is active (build.yml triggers on push, publish.yml handles releases, docs.yml auto-generates API docs). .jazzy.yaml indicates ongoing documentation generation. Migration guides (Tabman 2/3) suggest recent major versions. Likely focused on stability and Swift 6 adoption rather than new features.

Clone and open in Xcode 16+: git clone https://github.com/uias/Tabman.git && cd Tabman && open .swiftpm/xcode/package.xcworkspace. Then run the example project or explore Docs/ for tutorials. SPM users can add via Xcode → Add Package → https://github.com/uias/Tabman.git.

Daily commands: Tabman is a library, not an executable. For development: open .swiftpm/xcode/package.xcworkspace in Xcode 16+, select a scheme (e.g., example target if present), and run. CI runs via swift build and test commands in .github/workflows/build.yml.

• Sources/Tabman/AutoInsetter/AutoInsetter.swift — Core auto-insetting logic that automatically adjusts child view controller content insets—foundational for the framework's primary value proposition
• Sources/Tabman/Bar/BarButton/TMBarButton.swift — Base bar button component that all interactive indicator bar buttons inherit from; essential for customization and extension
• Sources/Tabman/Bar/BarBackgroundView/TMBarBackgroundView.swift — Background rendering layer for the indicator bar; critical for visual styling and theme implementation
• Package.swift — Swift Package definition; defines all public API surface, dependencies, and deployment targets
• Sources/Tabman/AutoInsetter/InsetCalculator/InsetCalculator.swift — Abstract inset calculation strategy; enables extensibility for different scroll view types (table, collection, custom)
• Sources/Tabman/Bar/BarButton/TMBarButtonController.swift — Orchestrates bar button state, interaction, and lifecycle; bridges view and state management

• AutoInsetter (UIViewController scroll view detection, Auto Layout constraint manipulation) — Detects child scroll views, calculates appropriate insets to account for bar height, and applies them automatically
  • Failure mode: If scroll view not detected, content may be hidden under bar; if inset calculation wrong, content may overlap or have extra padding
• TMBarButton & TMBarButtonController (UIView, CABasicAnimation, Delegate pattern) — Renders individual tab buttons, manages selection state, and coordinates appearance transitions (color, scale, badge)
  • Failure mode: Button states can become out-of-sync if page scrolls rapidly or user interactions race; badge rendering may overlap for long text
• TMBarBackgroundView (CALayer, CGPath, CABasicAnimation) — Renders the bar background (solid, gradient, shadow, border) and indicator underline position
  • Failure mode: Indicator may lag during fast swipes if animation not optimized; background may flicker on device rotation
• InsetCalculator hierarchy (Geometry calculations, KVO for scroll view observation) — Computes content insets for specific scroll view types (UIScrollView, UITableView, UICollectionView) based on bar geometry
  • Failure mode: Wrong inset type chosen → content misaligned; inset not recalculated on bar resize → content overlap on orientation change

• TabmanViewController (page index) → TMBarButtonController — Page index updates trigger button state changes (selection, color, badge)
• User swipe gesture (on page scroll) → Indicator animation engine — Scroll offset mapped to indicator position; animated in real-time following finger
• Child view controller (scroll view reference) → AutoInsetter — undefined

Create a Custom Indicator Bar

1. Subclass TMBarButton to define custom button appearance and behavior (Sources/Tabman/Bar/BarButton/TMBarButton.swift)
2. Override TMBarButtonController to add custom state management or animation logic (Sources/Tabman/Bar/BarButton/TMBarButtonController.swift)
3. Create a custom background view by extending TMBarBackgroundView (Sources/Tabman/Bar/BarBackgroundView/TMBarBackgroundView.swift)
4. Compose custom bar by instantiating buttons and background, then configure via TabmanViewController

Add Auto-Inset Support for a Custom Scroll View

1. Create a new inset calculator by subclassing InsetCalculator (Sources/Tabman/AutoInsetter/InsetCalculator/InsetCalculator.swift)
2. Implement calculate() method to compute appropriate insets for your scroll view type (Sources/Tabman/AutoInsetter/InsetCalculator/InsetCalculations.swift)
3. Register your calculator in AutoInsetter or InsetStore (Sources/Tabman/AutoInsetter/AutoInsetter.swift)
4. Configure AutoInsetSpec on your TabmanViewController with your custom calculator

Customize Bar Button Badges

1. Extend TMBadgeView to customize appearance (color, size, font) (Sources/Tabman/Bar/BarButton/Badge/TMBadgeView.swift)
2. Update TMBarButton to use your custom badge view in its initialization (Sources/Tabman/Bar/BarButton/TMBarButton.swift)
3. Set badge state via TMBarButtonController's badge property

• UIPageViewController (via Pageboy) — Provides native iOS page view controller semantics with swipe navigation and bounce behavior
• Swift 5 / Swift Package Manager — Modern type-safe language with zero-dependency distribution model suitable for UI framework
• Auto Layout constraints — Enables responsive bar sizing and positioning across device sizes and orientations
• Strategy pattern (InsetCalculator hierarchy) — Allows extensible support for different scroll view types without modifying core auto-insetting logic

• Built on Pageboy (external dependency) rather than raw UIPageViewController

  • Why: Reduces boilerplate for page view controller setup and provides better event delivery
  • Consequence: Adds one external dependency but simplifies integration and improves stability

• AutoInsetter automatically applies insets rather than requiring manual configuration

  • Why: Reduces developer cognitive load and prevents common layout bugs
  • Consequence: Less control for advanced use cases; requires opt-out mechanisms for custom layouts

• Bar component architecture is mix-and-match (buttons, backgrounds, indicators separate)

  • Why: Maximizes flexibility and allows granular customization without forking
  • Consequence: More initial boilerplate for custom bars; requires understanding of all components

• Does not provide built-in paging view controller—relies on Pageboy for that functionality
• Does not handle state persistence or caching of page content
• Does not provide theme libraries or pre-built design systems
• Not a real-time or reactive framework; uses delegation and manual property setting

No obvious environment variables or secrets required. Main trap: Tabman tightly depends on Pageboy (must be compatible version); version mismatch causes scroll sync bugs. Another: iOS 14+ requirement is strict—code targeting iOS 13 will fail to build. Swift 6 support requires Xcode 16+; older Xcode will not work. Bar layout customization via TMBar.Layout.transitionStyle affects scroll behavior non-obviously—snap vs. progressive styles require different delegate implementations.

• Interactive Scroll Synchronization — Tabman's core feature syncs indicator position with page scroll progress; understanding scroll delegates and progress callbacks is essential to debug or extend bar animations
• Component-Based Architecture (Mix-and-Match) — Tabman bars compose TMBarItem, TMBarIndicator, and custom layouts; understanding composition over inheritance enables creating custom bar types
• View Controller Containment & Auto-Insetting — Tabman automatically adjusts child VC safe area insets when bars are added; misunderstanding this leads to layout bugs and overlapping content
• Transition Style Patterns (Snap vs. Progressive) — TMBar.Layout.transitionStyle controls whether indicator moves discretely (snap) or smoothly (progressive); each requires different scroll tracking logic
• Data Source Pattern (Delegation) — Tabman uses PageboyViewControllerDataSource and TMBarDataSource delegates; understanding when each is queried (and for what) prevents off-by-one errors and stale data
• Swift Package Manager (SPM) Workspace Structure — Tabman is SPM-native with .swiftpm/xcode/ workspace; understanding Package.swift manifest and product declarations is needed to build or extend the library
• Badge & State Indicators (TMBadgeView) — Tabman supports badge overlays on tab items for notifications/counts; understanding when badges are updated (via data source refresh) prevents stale badge displays

• uias/Pageboy — The foundation Tabman is built on; Pageboy provides the page view controller engine that Tabman's bars wrap and sync with
• SnapKit/SnapKit — Auto-layout DSL used in many Tabman projects for positioning bars and child controllers; complementary constraint tool
• realm/SwiftLint — Code style enforcer likely used in Tabman CI (implied by CONTRIBUTING.md practices); maintains code consistency
• danielgindi/Charts — Common companion library for data-heavy tabbed interfaces (dashboards); often paired with Tabman for charting apps
• PagerDuty/ios-pagerduty — Example production app using similar tabbed patterns; reference for enterprise-grade Tabman integration

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 unit tests for TMBadgeView and indicator customization components

The repo has comprehensive documentation in Docs/Sections/TMBadgeView.md and Docs/Sections/Indicator.md, but no visible test files in the Sources directory for testing badge view behavior, appearance changes, and indicator animations. This is critical for a customizable UI component library to ensure badge rendering, sizing, and indicator transitions work reliably across iOS 14+.

• [ ] Create Tests/TMBadgeViewTests.swift with unit tests for badge initialization, text updates, visibility toggles, and custom styling
• [ ] Create Tests/IndicatorTests.swift testing indicator position calculations, animation timing, and custom appearance delegates
• [ ] Add tests verifying badge/indicator behavior under constraint changes and view lifecycle events
• [ ] Integrate test target into Package.swift and GitHub Actions build workflow

Create migration guide documentation for iOS 14+ API changes and deprecations

The repo has Tabman 2 and 3 migration guides (Docs/Tabman 2 Migration Guide.md and Docs/Tabman 3 Migration Guide.md) but the README indicates iOS 14+ requirement. There's no documented guide for API changes, deprecated UIKit patterns, or SwiftUI integration patterns that users upgrading to newer iOS versions might encounter with this framework.

• [ ] Create Docs/iOS 14+ Migration Guide.md documenting any UIViewController, paging, or indicator bar APIs affected by iOS 14+ changes
• [ ] Document SwiftUI integration patterns if applicable, or create Docs/SwiftUI Integration.md if not yet covered
• [ ] Add specific examples in Docs/Sections/ for iOS 14+ constraint and safe area handling given the 'Automatically insets child view controller contents' feature
• [ ] Link new guide from README.md

Add GitHub Action workflow for SPM compatibility testing across iOS 14-17

While .github/workflows/build.yml exists, there's a Package.swift file indicating SwiftPM support (and README confirms SwiftPM compatibility badge). A dedicated SPM resolution and build workflow testing multiple Swift versions and iOS deployment targets would ensure package integrity and catch dependency resolution issues early.

• [ ] Create .github/workflows/spm-test.yml running 'swift build' and 'swift test' against Swift 5.5+ versions
• [ ] Add matrix testing for iOS 14, 15, 16, 17 minimum deployment targets in Package.swift configurations
• [ ] Verify Pageboy dependency resolution across matrix to catch transitive dependency issues
• [ ] Integrate workflow into build status checks and reference in CONTRIBUTING.md

• Add API documentation examples to Docs/Sections/Bar.md for each TMBar subclass (e.g., ButtonBar, LineBar) showing initialization and common customization patterns—currently missing concrete code samples
• Create a troubleshooting guide entry under Docs/Troubleshooting.md for 'Bar doesn't sync with scroll' scenario, documenting common causes (dataSource not set, indicator frame bugs, scroll delegate conflicts)
• Add Swift 6 strict concurrency compatibility checks: audit Tabman source for @MainActor annotations on UI delegates and fix any missing thread-safety markers in TMBar and indicator classes

This is a well-structured Swift package for iOS development with no obvious critical vulnerabilities visible from the file structure alone. The codebase appears to be a UI library (Tabman) focused on paging view controllers, which inherently has limited exposure to typical injection attacks or data leakage risks. However, the security analysis is limited due to unavailable source code contents. Key concerns include: (1) Unverified dependencies in Package.swift and Gemfile.lock, (2) Unknown configurations in GitHub Actions workflows, (3) Unreviewed custom build scripts, and (4) Missing analysis of actual Swift source code. Recommend conducting a full code review of critical components, dependency auditing, and CI/CD security assessment.

• Medium · Missing Dependency Lock File Information — Package.swift, Package.resolved, Gemfile.lock. While Package.resolved exists, the Package.swift and Gemfile.lock files are present but their contents were not provided for analysis. This makes it impossible to verify if any Swift Package Manager dependencies or Ruby gems have known vulnerabilities. Fix: Review Package.swift for any dependencies from untrusted sources. Regularly run 'swift package resolve' and review Package.resolved. For Ruby dependencies, run 'bundle audit' to check for known vulnerabilities in Gemfile.lock.
• Low · Build and CI/CD Configuration Requires Review — .github/workflows/. GitHub Actions workflows are present (.github/workflows/build.yml, publish.yml, docs.yml) but their contents were not provided. Workflows can introduce security risks if they contain insecure configurations, such as excessive permissions, insecure secret handling, or running untrusted code. Fix: Audit all GitHub Actions workflows to ensure: (1) Secrets are not logged or exposed in output, (2) Workflows use specific action versions (not 'latest'), (3) Least privilege principle is applied to permissions, (4) Third-party actions come from trusted sources.
• Low · Documentation Build Script Security — .scripts/. Custom build scripts are present (.scripts/doc-processor, generate-docs, update-gh-pages) but their contents were not provided. Custom scripts can introduce security risks if they execute untrusted code or handle sensitive operations insecurely. Fix: Review all shell scripts for: (1) Proper input validation, (2) Secure handling of temporary files, (3) Appropriate file permissions, (4) No execution of user-controlled code. Ensure scripts follow the principle of least privilege.
• Low · Xcode Project Configuration Not Analyzed — Sources/Tabman.xcodeproj/project.pbxproj, Sources/Examples.xcodeproj/project.pbxproj. Multiple .pbxproj files exist but were not provided for analysis. These files contain project configuration and could have security-relevant settings that should be reviewed. Fix: Review Xcode project settings for: (1) Code signing configuration, (2) Build settings that could affect security (e.g., stack protection), (3) Framework linking and embedding, (4) Proper capability configuration.
• Low · Swift Lint Configuration Requires Review — Sources/.swiftlint.yml. A .swiftlint.yml configuration file exists but was not provided for analysis. SwiftLint rules can help catch security issues, and misconfiguration could leave security issues undetected. Fix: Ensure .swiftlint.yml includes security-relevant rules and that they are not disabled. Consider enabling rules for: force unwrapping warnings, implicitly unwrapped optionals, and other unsafe patterns.

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.