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/scalessec/Toast-Swift 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 2y ago

• 12 active contributors
• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 55% 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 scalessec/Toast-Swift repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/scalessec/Toast-Swift.

What it runs against: a local clone of scalessec/Toast-Swift — 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 scalessec/Toast-Swift | 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 ≤ 791 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "scalessec/Toast-Swift(\\.git)?\\b" \\
  && ok "origin remote is scalessec/Toast-Swift" \\
  || miss "origin remote is not scalessec/Toast-Swift (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 "Toast/Toast.swift" \\
  && ok "Toast/Toast.swift" \\
  || miss "missing critical file: Toast/Toast.swift"
test -f "Example/ViewController.swift" \\
  && ok "Example/ViewController.swift" \\
  || miss "missing critical file: Example/ViewController.swift"
test -f "Toast-Swift.podspec" \\
  && ok "Toast-Swift.podspec" \\
  || miss "missing critical file: Toast-Swift.podspec"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

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

Toast-Swift is a native Swift extension that adds lightweight, customizable toast notifications (temporary dismissible messages) to UIView objects. It ports the popular iOS Toast library to Swift with a single-line API (self.view.makeToast("message")) while supporting advanced features like activity spinners, custom positioning, styling, queueing, and tap-to-dismiss functionality. The repo uses a hybrid structure: Toast/Toast.swift contains the core extension and ToastManager singleton; Example/ViewController.swift and Example/AppDelegate.swift provide a runnable demo app; Toast-Swift.xcodeproj wraps both as an Xcode workspace; Package.swift enables Swift Package Manager integration. Configuration lives in Toast-Swift.podspec (CocoaPods) and Toast-Swift-Framework/ (framework metadata).

iOS/iPadOS developers using UIKit who need to display temporary notifications (status messages, confirmations, alerts) without the overhead of native UIAlertController or custom implementations. Particularly valuable for developers migrating from Objective-C Toast library or those building apps that prioritize lightweight, non-intrusive user feedback.

This project is production-ready and actively maintained. It is distributed via CocoaPods (v5.1.1+), Carthage, and Swift Package Manager, indicating broad adoption. The codebase is small (~44KB Swift) with clear separation between core functionality (Toast/Toast.swift) and example app, suggesting stability. However, commit recency and explicit test coverage are not visible in the provided file structure, so maintenance velocity cannot be fully assessed.

Risk is low for most use cases: the library has no external dependencies (pure UIKit extension), reducing supply-chain risk. However, it is UIKit-only (no SwiftUI support visible), which limits relevance for new projects targeting iOS 13+. The single-maintainer model (scalessec organization) and lack of visible CI/testing infrastructure (no test/ directory in file list) means breaking changes or bugs could propagate without guardrails.

Based on the file structure, the most recent activity appears to be privacy compliance (Toast/Resources/PrivacyInfo.xcprivacy suggests iOS 17+ privacy manifest support added). The Example/ app demonstrates all major features. No open PRs, milestones, or active issues are visible in the provided data, suggesting the project is in maintenance mode rather than feature development.

git clone https://github.com/scalessec/Toast-Swift.git
cd Toast-Swift
open Toast-Swift.xcodeproj
# Build & run the Example scheme in Xcode
# Or: xcodebuild -scheme Toast-Swift -workspace Toast-Swift.xcworkspace build

Daily commands: Open Toast-Swift.xcodeproj in Xcode, select the Example scheme, and press Cmd+R. The example app demonstrates makeToast(), makeToastActivity(), showToast(), hideAllToasts(), and custom styling via ToastManager.shared.style. Or use Swift Package Manager: swift build (requires Package.swift support).

• Toast/Toast.swift — The core extension that adds all toast notification methods to UIView—every contributor must understand the API surface and animation logic here.
• Example/ViewController.swift — Demonstrates all primary toast usage patterns and configuration options—essential reference for understanding the library's intended behavior.
• Toast-Swift.podspec — Defines the package metadata, version, and dependencies for CocoaPods distribution—required for release and integration management.
• Package.swift — SPM manifest that enables Swift Package Manager integration—critical for non-CocoaPods adoption paths.
• README.md — User-facing documentation with basic examples and API overview—sets expectations for all API behavior and styling.
• Example/AppDelegate.swift — Application entry point for the example app—shows initialization and lifecycle integration patterns.

• Toast Extension (UIView+Toast) (Swift, UIView, CABasicAnimation, UIGestureRecognizer) — Primary entry point; creates toast views, manages animation, positioning, and lifecycle.
  • Failure mode: Toast fails to display if UIView is not on-screen; crashes if completion closure causes view deallocation.
• ToastStyle Configuration (Swift, UIColor, UIFont) — Global singleton managing appearance properties (colors, fonts, opacity, corner radius, shadow).
  • Failure mode: Thread-unsafe mutations; style changes mid-display may cause visual glitches.
• Toast Position Logic (Swift, CGGeometry) — Calculates exact CGPoint for toast placement based on ToastPosition enum and view dimensions.
  • Failure mode: Toasts may appear off-screen on unusual aspect ratios or with notches/safe areas.
• Animation Controller (CABasicAnimation, Timer, Dispatch) — Orchestrates fade-in/fade-out transitions and manages animation completion timers.
  • Failure mode: Memory leaks if timer is not invalidated; animations may stutter on high load.

• UIViewController → UIView Extension — ViewController calls makeToast() with message, duration, position, and optional styling.
• UIView Extension → Toast Container View — Extension creates UILabel and optional UIImageView subviews, applies ToastStyle defaults.
• Toast Container → Screen Render Engine — Container is added to view hierarchy and rendered with fade-in animation.
• User Interaction / Timer → Gesture Handler / Animation Completion — Tap detection or duration expiry triggers fade-out animation and completion closure callback.
• Completion Closure → UIViewController — Closure passes boolean indicating whether toast was tapped (true) or timed out (false).

Display a Basic Toast Notification

1. Call makeToast() on any UIView instance with a message string. (Toast/Toast.swift)
2. Toast appears at default position (.bottom) with 3-second duration and standard styling. (Example/ViewController.swift)

Create a Customized Toast with Position, Duration, and Image

1. Call makeToast() with parameters: duration, position, title, and image properties. (Toast/Toast.swift)
2. Reference Example/ViewController.swift for parameter patterns and combinations. (Example/ViewController.swift)
3. Toast renders with custom layout respecting all specified options. (Toast/Toast.swift)

Handle Toast Completion Events

1. Pass a completion closure to makeToast() that receives a didTap boolean parameter. (Toast/Toast.swift)
2. The closure fires when the toast disappears or is tapped by the user. (Example/ViewController.swift)
3. Use didTap to determine whether dismissal was user-initiated or timeout-triggered. (Toast/Toast.swift)

Configure Global Toast Styling and Behavior

1. Access ToastStyle class properties in Toast.swift to adjust colors, fonts, corners, shadows, and opacity. (Toast/Toast.swift)
2. Modify defaults before displaying toasts to apply consistent styling across the app. (Example/ViewController.swift)
3. All subsequently created toasts inherit the updated default style. (Toast/Toast.swift)

• Swift UIView Extension — Allows toast functionality to be added to any UIView in one line of code without subclassing or wrappers.
• CABasicAnimation — Provides smooth, performant opacity transitions for fade-in and fade-out effects without blocking the main thread.
• UIGestureRecognizer (Tap) — Enables user dismissal and tap-detection callbacks to support interactive toast behavior.
• CocoaPods & SPM — Dual distribution models maximize compatibility across iOS development workflows (legacy and modern).

• Single monolithic Toast.swift file instead of modular components

  • Why: Simplicity and lightweight distribution—library is narrow-scoped and benefits from low file fragmentation.
  • Consequence: Makes the single file larger and harder to navigate for complex customizations; reduces separation of concerns.

• Global ToastStyle defaults instead of per-instance style objects

  • Why: Minimizes API surface and enables quick styling for common use cases.
  • Consequence: Thread-unsafe global state; difficult to have multiple independent toast themes in same app without helper wrappers.

• Manual position calculation and layout instead of Auto Layout

  • Why: Avoids Auto Layout overhead and provides deterministic, predictable positioning.
  • Consequence: Layout logic is hardcoded; complex responsive layouts or dynamic safe-area adjustments may require custom logic.

• Does not provide queue management for multiple toasts—all toasts display independently.
• Does not support custom toast view templates or full XIB/Storyboard integration.
• Does not handle accessibility features (VoiceOver, Haptics) out of the box.
• Not designed for tvOS or watchOS—UIView extension is iOS-specific.

• Global Mutable State (ToastStyle) (Medium) — Toast/Toast.swift: ToastStyle is a mutable global singleton; concurrent toast creation may read/write style properties unsafely, causing race conditions.
• Timer-Based Dismissal Without Cancellation Check (Medium) — Toast/Toast.swift: If a view is deallocated before timer fires, the completion closure may crash; no cleanup guard exists.

1. UIView extension scope: Toast methods are global to all UIView instances; if multiple toasts are presented without queueing enabled (ToastManager.shared.isQueueEnabled = true), they may overlap.
2. Tap gesture conflicts: The library adds UITapGestureRecognizer to toasts; if your view hierarchy already has gesture recognizers, delegation order may cause unexpected behavior.
3. Storyboard/XIB caveat: ToastStyle customization requires code (no IB support), so style changes cannot be persisted in xibs/storyboards.
4. No SwiftUI bridge: This is pure UIKit; using it in SwiftUI requires UIViewRepresentable wrapping, adding boilerplate.
5. Automatic dismissal: Toasts use DispatchQueue.main.asyncAfter() for duration-based dismissal; if the view controller is deallocated before the timer fires, memory safety depends on careful weak reference handling internally.

• UIView Extension (Category in Swift) — Toast-Swift adds methods directly to UIView via extension, enabling one-liner API calls on any view; understanding this pattern is critical to modifying the library and using it idiomatically.
• Singleton Pattern (ToastManager.shared) — Global state management for shared toast style, queueing, and tap-to-dismiss settings; recognizing singletons in Swift helps avoid accidental state pollution and memory leaks.
• Gesture Recognizers (UITapGestureRecognizer) — Toasts respond to user taps via gesture recognizers; understanding how gesture delegation works prevents conflicts when adding toasts to views with existing recognizers.
• DispatchQueue.main.asyncAfter() and GCD — Toast auto-dismissal relies on Grand Central Dispatch timers; knowing GCD lifetime and cancellation semantics is crucial for avoiding retain cycles and zombie toasts.
• CABasicAnimation (Implicit Animations) — Toast presentation and dismissal likely use Core Animation for fade/slide effects; understanding CALayer implicit animations prevents unexpected behavior when customizing toast appearance.
• Closure Capture and Weak References — Completion callbacks in makeToast() and gesture handlers can create retain cycles; recognizing capture lists ([weak self]) is essential to avoid memory leaks in toast callbacks.
• Enum-Driven Configuration (ToastPosition, ToastStyle) — Toast customization uses enums and structs rather than magic strings; understanding this pattern enables safe, type-checked styling and reduces configuration errors.

• scalessec/Toast — The original Objective-C Toast library that Toast-Swift is ported from; canonical reference for cross-platform behavior parity.
• Alamofire/Alamofire — Complement for network-driven toast notifications (e.g., displaying toast on HTTP response); commonly paired in real apps.
• realm/SwiftLint — Code quality tooling used in mature Swift projects; enables Toast-Swift contributors to maintain consistent code style.
• apple/swift-package-manager — Defines the SPM ecosystem that Toast-Swift targets; understanding Package.swift and manifest format is essential for package evolution.
• kishikawakatsumi/KeychainAccess — Similar UIKit-era micro-library pattern; reference for how single-purpose Swift libraries structure distribution and documentation.

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 Toast/Toast.swift

The repo lacks test coverage for the core Toast functionality. Toast/Toast.swift contains all the main logic for toast notifications but there are no visible test files in the repository. Adding unit tests would improve code reliability, prevent regressions, and help new contributors understand expected behavior. Tests should cover makeToast variants, duration/position parameters, and edge cases.

• [ ] Create Tests directory with ToastTests.swift file
• [ ] Write unit tests for makeToast() with default parameters
• [ ] Write unit tests for makeToast with duration and position parameters
• [ ] Test edge cases: nil messages, extreme duration values, invalid positions
• [ ] Test completion closure execution in Toast/Toast.swift methods
• [ ] Add test target to Toast-Swift.xcodeproj/project.pbxproj

Add GitHub Actions CI workflow for building and testing

There is no visible CI/CD configuration (.github/workflows missing). Adding a GitHub Actions workflow would automatically build the project on PRs, run tests, and ensure Swift version compatibility. This is especially important given the .swift-version file exists, indicating version-specific requirements.

• [ ] Create .github/workflows/swift-ci.yml
• [ ] Configure workflow to run on push and pull_request events
• [ ] Add step to build with xcodebuild for Toast-Swift.xcodeproj
• [ ] Add step to run unit tests against the test target
• [ ] Add step to verify against Swift version in .swift-version file
• [ ] Optional: Add CocoaPods pod lint step to validate Toast-Swift.podspec

Document Toast configuration options and add API reference section to README.md

The README.md snippet shows only basic usage examples but cuts off mid-sentence. The file is incomplete and missing comprehensive API documentation. Developers need to understand all available parameters, positioning options, styling options, and the completion closure behavior. This should reference actual function signatures from Toast/Toast.swift.

• [ ] Complete the truncated example in README.md
• [ ] Add 'Configuration' section documenting ToastPosition enum options (top, center, bottom)
• [ ] Add 'API Reference' section listing all makeToast() method signatures from Toast/Toast.swift
• [ ] Document available toast styling options if any exist in Toast/Toast.swift
• [ ] Add examples for using completion closures with toasts
• [ ] Add section documenting supported iOS versions and Swift version requirements from .swift-version

• Add unit tests for Toast/Toast.swift: Create Tests/ToastTests.swift with XCTest cases for makeToast() with various positions, durations, and custom styles; verify ToastManager singleton behavior and tap gesture detection.: Currently no visible test/ directory; test coverage is unknown. Adds quality gate for future contributors.
• Document all ToastPosition cases and styling options in a separate markdown file (docs/API.md): List .top, .center, .bottom, point-based positioning, and all ToastStyle properties with defaults and valid ranges.: README shows examples but lacks comprehensive API reference; new users must read Toast.swift directly to understand all options.
• Add SwiftUI example companion (Example/SwiftUIToastDemo.swift) showing how to wrap Toast-Swift for use in SwiftUI views via UIViewRepresentable.: The library is UIKit-only, which alienates SwiftUI-first projects; a clear bridge example reduces friction and shows adoption path.

Toast-Swift is a lightweight UI library with a relatively small attack surface. No critical vulnerabilities were identified in the file structure. The main security concerns are related to missing visibility into dependency management (Package.swift content), potential input validation in toast message handling, and ensuring proper privacy disclosures. The library appears to be a straightforward UI extension without database access, network calls, or complex authentication, which reduces risk exposure. Recommendations focus on dependency auditing and defensive input validation practices.

• Medium · Missing or Unclear Dependency Management — Package.swift. The Package.swift file content was not provided for review. Without visibility into the dependency declarations, it's impossible to verify if all dependencies are pinned to secure versions and if any known vulnerable packages are being used. Fix: Provide and review Package.swift to ensure all dependencies specify version constraints and that no known vulnerable packages are included. Consider using tools like swift package resolve to audit dependencies.
• Low · Incomplete Privacy Manifest Configuration — Toast/Resources/PrivacyInfo.xcprivacy. The project includes a PrivacyInfo.xcprivacy file, which is good practice for iOS 17+. However, without viewing its contents, it's unclear if all required privacy declarations are properly configured for the toast notification library. Fix: Review and ensure the PrivacyInfo.xcprivacy file contains all required privacy disclosures and is properly configured according to Apple's guidelines.
• Low · Potential Information Disclosure via Framework Headers — Toast-Swift-Framework/Toast-Swift-Framework.h. The file Toast-Swift-Framework/Toast-Swift-Framework.h exists as a bridging header. If this contains implementation details or sensitive API information, it could be exposed in compiled frameworks. Fix: Review the bridging header to ensure it only exports necessary public APIs and doesn't expose sensitive implementation details. Keep it minimal.
• Low · Missing or Unclear Input Validation in Toast Display — Toast/Toast.swift. Based on the README examples showing makeToast() methods accepting string parameters directly, there may be insufficient validation of string length or content. If toast messages can be arbitrarily long or contain unvalidated user input, it could lead to UI crashes or unintended behavior. Fix: Implement input validation for toast message strings, including length limits, character encoding checks, and sanitization of any user-provided content before displaying in toast notifications.

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.