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/exyte/PopupView 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 — Mixed signals — read the receipts

• Last commit 1w ago
• 19 active contributors
• MIT licensed
• ⚠ Concentrated ownership — top contributor handles 64% 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 exyte/PopupView repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/exyte/PopupView.

What it runs against: a local clone of exyte/PopupView — 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 exyte/PopupView | 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 | 3 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 38 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "exyte/PopupView(\\.git)?\\b" \\
  && ok "origin remote is exyte/PopupView" \\
  || miss "origin remote is not exyte/PopupView (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 "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "PopupExample/PopupExample.xcodeproj/project.pbxproj" \\
  && ok "PopupExample/PopupExample.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: PopupExample/PopupExample.xcodeproj/project.pbxproj"
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"

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

PopupView is a SwiftUI library that provides reusable components for displaying toasts, alerts, popups, and sheets with customizable animations and positioning. It abstracts away the boilerplate of managing presentation state and transitions, letting developers display temporary notifications and modal content with minimal code while maintaining full visual control. Swift Package structure: Package.swift at root defines the library; PopupExample/ is a reference app demonstrating all four presentation types (Floaters, Toasts, Popups, Sheets). Assets live in PopupExample/Assets.xcassets/ with color definitions and avatar imagery. No visible separation of core library code in the file list, suggesting a flat or simple src layout.

iOS/macOS developers building SwiftUI apps who need to display non-blocking notifications (toasts/floaters), modal dialogs, or alert sheets without reimplementing presentation logic for each use case.

The project appears actively maintained (Swift Package Manager setup, organized example app in PopupExample/) with clear release tagging (per version badge in README). However, the file list shows primarily assets and configuration files—actual source code files aren't detailed, making full maturity assessment difficult. Cocoapods support was deprecated after v4.0.0, suggesting a shift to SPM-only distribution.

Single-maintainer (Exyte) risk is inherent. No visible test directory in the file listing suggests weak test coverage. The repo's Swift-heavy codebase (139,502 lines) with minimal Objective-C (507 lines) means it's modern but offers no backwards compatibility bridge. Breaking API changes appear possible given the version management and Cocoapods deprecation without longer transition period.

The file list does not include git history or PR data, so active development status cannot be determined from the provided structure alone. The presence of Package.resolved and SwiftPM workspace configuration suggests recent SPM integration or updates.

1. Clone: git clone https://github.com/exyte/PopupView.git && cd PopupView
2. Open in Xcode: open .swiftpm/xcode/package.xcworkspace/
3. Run example app: Select PopupExample scheme and build/run (⌘R).

Daily commands: Open PopupExample scheme in Xcode workspace (.swiftpm/xcode/package.xcworkspace) and press ⌘R, or use xcodebuild -workspace .swiftpm/xcode/package.xcworkspace -scheme PopupExample -configuration Debug from terminal.

• Package.swift — Swift Package manifest defining the library structure, target configuration, and platform requirements for PopupView.
• PopupExample/PopupExample.xcodeproj/project.pbxproj — Primary Xcode project file containing build configuration and example app setup for testing the library.
• .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata — SwiftPM workspace configuration enabling integrated development and testing within Xcode.

• PopupView Library Core (SwiftUI, Combine (reactive state)) — Provides reusable .popup() and toast() modifiers with configuration (position, animation, interaction) for SwiftUI views.
  • Failure mode: Misconfigured animation timing, missed dismissal callbacks, Z-order conflicts if misused in complex hierarchies.
• PopupExample App (SwiftUI, custom fonts (NunitoSans), asset catalogs) — Demonstrates library features across multiple scenes: success/error toasts, dialogs, snackbars, custom animations.
  • Failure mode: UI layout issues on smaller devices, font loading failures if TTF files missing, asset catalog corruption.
• Animation Engine (SwiftUI Animation, CABasicAnimation equivalent) — Abstracts SwiftUI Animation API to provide smooth entry/exit transitions (scale, fade, slide) with customizable easing.
  • Failure mode: Frame rate drops on low-end devices, jank if animation curves poorly tuned, missed completion callbacks.
• Gesture & Interaction Layer (SwiftUI GestureRecognizer (.onTapGesture, .gesture)) — Captures tap-to-dismiss, swipe-to-dismiss, and custom button actions; coordinates with animation engine for smooth exit.
  • Failure mode: Double-dismiss crashes if state not guarded, gesture conflicts with underlying content (e.g., nested buttons).

• Developer code → PopupView modifier — Configuration struct (content, position, animation type, dismissal conditions) passed as modifier argument.
• PopupView modifier → Animation Engine — Visibility state (@State isPresented) and animation type trigger entry/exit animation sequences.
• Animation Engine → SwiftUI View Layer — Computed frame/opacity/scale values applied each animation frame; SwiftUI re-renders affected views.
• User interaction (tap/gesture) → Gesture handler — Tap outside or swipe gesture triggers isPresented.toggle() or custom closure callback.
• Gesture handler → Developer callback — Dismiss or action callback returned to parent view to update app state or perform side effects.

Add a new Toast Variant to the Example App

1. Create a new Swift file in PopupExample/ directory to define your toast component (PopupExample/YourToastView.swift)
2. Add color assets if needed to PopupExample/Assets.xcassets/Color/ for consistent theming (PopupExample/Assets.xcassets/Color/yourColor.colorset/Contents.json)
3. Reference your new toast in the example app's main view and add a trigger button (PopupExample/PopupExample.xcodeproj/project.pbxproj)

Add Core PopupView Feature

1. Create new Swift files in the library source (referenced in Package.swift targets) (Package.swift)
2. Update Package.swift to include new public API types in the library target (Package.swift)
3. Add example usage demonstrating the feature in PopupExample for documentation (PopupExample/Assets.xcassets)

Customize Theme or Styling

1. Add new color sets to PopupExample/Assets.xcassets/Color/ for theme variants (PopupExample/Assets.xcassets/Color/Contents.json)
2. Add or modify custom fonts in PopupExample/Font/ directory (PopupExample/Font/NunitoSans_7pt-Regular.ttf)
3. Update example app to reference new colors and fonts (PopupExample/PopupExample.xcodeproj/project.pbxproj)

• SwiftUI — Modern declarative UI framework enabling reactive, composable popup and toast components with minimal boilerplate.
• Swift Package Manager — Standard iOS dependency management allowing easy integration and version pinning without CocoaPods overhead.
• Custom font assets (NunitoSans TTF) — Ensures consistent typography across example app and enables preview of library capabilities with production-grade design.

• Library-only approach (no server-side rendering)

  • Why: PopupView is a client-side UI component library for SwiftUI apps, not a backend service.
  • Consequence: All logic executes locally; no network dependency but also no cross-device state synchronization.

• Example app bundled in same repo rather than separate showcase

  • Why: Single source of truth for features, simpler onboarding, and contributors can test changes immediately.
  • Consequence: Larger repo size but tighter feedback loop and easier version alignment.

• Does not provide backend toast/popup service or cloud state persistence
• Does not handle iOS < 14 (SwiftUI-only, iOS 14+ required)
• Does not include UIKit bridge (SwiftUI-exclusive, though UIViewRepresentable wrappers possible externally)
• Does not manage notification center or system alerts (only custom overlays)

• Avg cyclomatic complexity: ~5 — PopupView is a lean UI library with straightforward modifier-based API and animation logic; SwiftUI handles most complexity. Example app adds moderate complexity with multi-scene demo state.
• Largest file: PopupExample/PopupExample.xcodeproj/project.pbxproj (3,500 lines)

• Potential State Synchronization Issues (Medium) — PopupExample (demo app): Multiple independent popup/toast state variables (@State) across different view scenes could lead to missed dismissals if callbacks not properly wired; consider centralized state container.
• Asset Duplication Risk (Low) — PopupExample/Assets.xcassets: Multiple similar color and image assets (e.g., avatar1–6, shop_* variants) increase bundle size and maintenance burden; could benefit from dynamic theming or consolidated asset strategy.
• Font File Inclusion (Medium) — PopupExample/Font/: Custom TTF fonts bundled in example app; if library depends on these, font loading failures could break demos. Fonts should be optional or clearly documented as example-only.

• Animation frame rendering (SwiftUI) (Performance / Rendering) — Complex nested popups with simultaneous animations may cause frame rate drops on older devices (iPhone 8/7); animation curves and layer counts should be profiled.
• Asset catalog loading (PopupExample) (Resource / Startup) — Large color set and image asset catalogs increase app launch time and memory footprint; lazy loading or asset streaming could help.
• Gesture conflict resolution (Logic / UX) — Overlapping tap gestures (popup dismiss vs. underlying button action) may require careful hit-testing; poorly tuned priority could cause missed user interactions.

No hidden traps explicitly identifiable from the file structure, but watch for: (1) SPM-only distribution means Cocoapods users cannot upgrade past v4.0.0 without migrating build systems; (2) No visible Package.resolved detailed dependencies, so any transitive dependency conflicts only surface at integration time; (3) Asset references in PopupExample/ use hardcoded paths (avatar1–6 images, color names)—renaming these will break the example app silently.

• View Modifiers (SwiftUI) — PopupView likely uses the modifier pattern to attach popup behavior to existing views (e.g., .popup(...) or .toast(...)), a core SwiftUI design pattern that new contributors must understand.
• Transition & Animation (SwiftUI) — Controlling how popups appear and disappear (scale, opacity, slide) is fundamental to PopupView's four presentation types; mastering SwiftUI transitions is essential for customization work.
• State Management via @State, @Binding, EnvironmentObject — PopupView must track presentation state (shown/hidden, content, position) and pass it between parent and child views; understanding SwiftUI's reactive property wrappers is critical.
• Swift Package Manager (SPM) — PopupView is distributed via SPM (Package.swift is the manifest); contributors must understand target declarations, product exports, and dependency resolution.
• Z-ordering and View Layering — Floaters, toasts, popups, and sheets all require careful layering on the screen; understanding view hierarchy and ZStack placement ensures correct visual stacking without conflicts.
• Geometry Reader (SwiftUI) — Positioning popups relative to screen size, safe areas, or parent view bounds likely requires GeometryReader; contributors need this for responsive popup placement.
• Platform Abstraction (iOS/macOS target support) — PopupView targets both iOS and macOS (per badge in README), requiring conditional compilation and cross-platform gesture/event handling; contributors must test on both platforms.

• pointfreeco/swiftui-navigation — Alternative SwiftUI navigation & presentation library that handles routing and state management for modal presentations, complementary to PopupView's focus on visual presentation.
• realm/SwiftUI-Realm — Demonstrates Swift Package structure and SwiftUI integration patterns similar to PopupView; useful as a reference for package organization best practices.
• exyte/Grid — Sibling library from Exyte using the same SwiftUI + SPM architecture; learning its patterns directly informs PopupView contribution workflow.
• SDWebImageSwiftUI/SDWebImageSwiftUI — Popular SwiftUI wrapper around a core library, similar distribution model (SPM, clear example app) and state management patterns applicable to PopupView enhancements.
• apple/swift-algorithms — Canonical Swift Package example from Apple; defines documentation and testing standards that PopupView could adopt for maturity.

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 SwiftUI Preview support for all popup variants in PopupExample

The PopupExample app has extensive assets and color schemes defined, but there's no indication of #Preview macros for different popup types. Adding comprehensive previews for Toast, Dialog, Sheet, and custom popup variants would help contributors visualize changes and reduce manual testing. This is especially valuable given the visual nature of a UI library.

• [ ] Identify all popup view types in Sources/PopupView (Toast, Dialog, Sheet, etc.)
• [ ] Create preview files in PopupExample/ with #Preview macros for each variant
• [ ] Include previews for different color schemes (light/dark) using the defined color assets (dark.colorset, light.colorset, etc.)
• [ ] Add previews demonstrating different animation states and transitions
• [ ] Document preview usage in README or CONTRIBUTING guide

Add GitHub Actions workflow for SwiftUI/iOS compatibility testing

The repo has a .swiftpm/xcode configuration but no visible CI/CD workflow. Adding a GitHub Action to test the package on multiple iOS versions and Swift compiler versions would catch regressions early and ensure broad compatibility across Apple's ecosystem.

• [ ] Create .github/workflows/swift-tests.yml with matrix testing for iOS 14+, 15, 16, 17
• [ ] Add build verification for macOS and tvOS targets if applicable
• [ ] Include SPM package resolution testing using Package.resolved as baseline
• [ ] Add linting checks for Swift code style (e.g., SwiftLint)
• [ ] Configure workflow to run on PR submissions and pushes to main branch

Create comprehensive example screens demonstrating each popup type with the color assets

The PopupExample app has 10+ color assets defined (dark, darkBlue, purple, yellow, etc.) and avatar assets, but the current file structure suggests incomplete example implementations. Adding dedicated example screens for each popup variant styled with these colors would showcase library capabilities and serve as documentation.

• [ ] Create separate SwiftUI View files in PopupExample/ for ToastExampleView, DialogExampleView, SheetExampleView
• [ ] Implement examples using defined color assets (lightBlue.colorset, darkText.colorset, etc.) and avatars
• [ ] Add navigation/menu View to switch between different popup type examples
• [ ] Include interactive controls to demonstrate customization options (animation, duration, position)
• [ ] Update PopupExample root view to display the new example screens

• Add unit tests for animation transitions in each popup type (Floaters, Toasts, Popups, Sheets). Create Tests/ directory with XCTest files for each presentation variant, covering entry/exit animations.: Test coverage is not evident in the file list, and animation correctness is critical for UX. Starting here provides low-risk, high-impact improvements.
• Document the public API with inline code comments and a USAGE.md guide. Map each of the four popup types in PopupExample/ to concrete code snippets showing initialization, customization, and dismissal.: The example app exists but lacks corresponding API docs. A new contributor can learn by reading PopupExample code, then codify that knowledge in docs.
• Extract PopupExample's color definitions (PopupExample/Assets.xcassets/Color/) into a theme configuration system or preset file (e.g., PopupTheme.swift). Allow users to define custom color schemes without modifying assets.: Currently colors are baked into xcassets; a theme abstraction would unblock custom branding and provide a clear extension point for contributors.

The PopupView SwiftUI library demonstrates a relatively secure posture with no critical vulnerabilities identified in the available file structure. As a UI library with no apparent backend integration, injection attacks and credential exposure risks are minimal. Primary concerns are: (1) dependency management transparency - the Package.resolved file requires review to ensure no vulnerable versions are locked, (2) lack of visible security configuration documentation, and (3) no SBOM (Software Bill of Materials) provided. The codebase appears to be pure SwiftUI with no database, API integration, or authentication logic, which significantly reduces the attack surface. Recommended improvements include publishing a security policy, conducting regular dependency audits, and providing security documentation for maintainers.

• Medium · Missing Package.resolved Dependency Verification — Package.resolved. The Package.resolved file is present but its contents were not provided for analysis. This file locks dependency versions and should be reviewed to ensure no known vulnerable versions are pinned. Without visibility into actual dependencies, transitive vulnerabilities cannot be fully assessed. Fix: Provide and regularly audit Package.resolved contents. Use Swift Package Manager's security advisories and tools like swift package diagnose to identify vulnerable dependencies.
• Low · Example Application Assets Not Validated — PopupExample/Assets.xcassets/. The PopupExample directory contains numerous image assets (PNG, PDF) without visible integrity checks or validation. While this is an example app, untrusted image files could potentially contain malicious metadata or steganographic content. Fix: Ensure all example assets come from trusted sources. Consider adding asset validation and sanitization during the build process if user-supplied images are processed.

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.