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/SvenTiigi/WhatsNewKit 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

• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 90% of recent commits

_{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 SvenTiigi/WhatsNewKit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/SvenTiigi/WhatsNewKit.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "SvenTiigi/WhatsNewKit(\\.git)?\\b" \\
  && ok "origin remote is SvenTiigi/WhatsNewKit" \\
  || miss "origin remote is not SvenTiigi/WhatsNewKit (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/Models/WhatsNew.swift" \\
  && ok "Sources/Models/WhatsNew.swift" \\
  || miss "missing critical file: Sources/Models/WhatsNew.swift"
test -f "Sources/View/WhatsNewView.swift" \\
  && ok "Sources/View/WhatsNewView.swift" \\
  || miss "missing critical file: Sources/View/WhatsNewView.swift"
test -f "Sources/Store/WhatsNewVersionStore.swift" \\
  && ok "Sources/Store/WhatsNewVersionStore.swift" \\
  || miss "missing critical file: Sources/Store/WhatsNewVersionStore.swift"
test -f "Sources/Collection/WhatsNewCollection.swift" \\
  && ok "Sources/Collection/WhatsNewCollection.swift" \\
  || miss "missing critical file: Sources/Collection/WhatsNewCollection.swift"
test -f "Sources/Environment/WhatsNewEnvironment.swift" \\
  && ok "Sources/Environment/WhatsNewEnvironment.swift" \\
  || miss "missing critical file: Sources/Environment/WhatsNewEnvironment.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 607 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~577d)"
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/SvenTiigi/WhatsNewKit"
  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).

WhatsNewKit is a Swift Package that provides a customizable, reusable UI component for showcasing new app features in iOS, macOS, and visionOS apps. It handles both automatic presentation (triggered on version updates) and manual presentation via SwiftUI modifiers, eliminating boilerplate code for feature announcement screens. SPM package with core logic in Sources/ organized by concern: Collection/ (data models for features), Environment/ (SwiftUI environment keys), Extensions/ (helper modifiers). Example app in Example/Example.xcodeproj/ demonstrates integration. GitHub Actions in .github/workflows/ handle CI, testing, and DocC deployment.

iOS/macOS/visionOS developers who need to highlight new features to users after app updates. Specifically built for SwiftUI-first developers who want a polished, out-of-the-box solution without building custom changelog UIs.

Production-ready. The repo shows active maintenance (CI/CD pipelines for build, test, and documentation in .github/workflows/), DocC documentation generation, and a fully functional example app. v2.0.0+ indicates a stable API, though maintainer is single-person (SvenTiigi).

Standard open source risks apply.

No PR or milestone data visible, but the presence of build_and_test.yml, build_example_project.yml, and deploy_documentation.yml workflows suggests continuous integration is active. README mentions v2.0.0+ with automatic & manual presentation modes, indicating recent feature completion.

git clone https://github.com/SvenTiigi/WhatsNewKit.git
cd WhatsNewKit
open Example/Example.xcodeproj
# In Xcode, select 'Example' scheme and run (Cmd+R)

Or add to your project via Xcode: File > Add Packages > paste https://github.com/SvenTiigi/WhatsNewKit.git > Up to Next Major v2.0.0.

Daily commands: Open Example/Example.xcodeproj, select scheme 'Example', press Cmd+R. Or use SPM directly: swift build in package root. Tests run via swift test (exact test locations not visible in file list).

• Sources/Models/WhatsNew.swift — Core data model that defines the WhatsNew feature showcase structure; all customization flows through this.
• Sources/View/WhatsNewView.swift — Main SwiftUI view component that renders the feature showcase UI; understand this to modify presentation logic.
• Sources/Store/WhatsNewVersionStore.swift — Protocol defining persistence abstraction for tracking shown versions; critical for understanding state management.
• Sources/Collection/WhatsNewCollection.swift — Container for managing multiple WhatsNew presentations in sequence; key for multi-feature workflows.
• Sources/Environment/WhatsNewEnvironment.swift — SwiftUI environment configuration holder that propagates settings across the view hierarchy.
• Sources/Extensions/View+WhatsNewSheet.swift — Extension providing the public API for presenting WhatsNew as a sheet; entry point for developers.
• Package.swift — SPM manifest defining package dependencies, platforms, and targets; required for build configuration.

• WhatsNew & Feature Models (Swift structs, Codable) — Define immutable data structures for showcase content, layout, and actions
  • Failure mode: Incomplete or missing feature data silently renders empty or truncated UI
• WhatsNewView — undefined

Add a New Feature to a WhatsNew Showcase

1. Create a WhatsNew instance and define one or more features using WhatsNew.Feature structs (Sources/Models/WhatsNew+Feature.swift)
2. Optionally customize layout, title, and actions via WhatsNew model properties (Sources/Models/WhatsNew.swift)
3. Present using the View extension with your configured WhatsNew instance (Sources/Extensions/View+WhatsNewSheet.swift)

Implement Custom Version Persistence

1. Create a new struct conforming to WhatsNewVersionStore protocol (Sources/Store/WhatsNewVersionStore.swift)
2. Implement hasBeenPresented(for:) and setPresented(for:) methods for your storage backend (Sources/Store/UserDefaultsWhatsNewVersionStore.swift)
3. Pass your implementation to WhatsNewEnvironment during setup (Sources/Environment/WhatsNewEnvironment.swift)

Display Multiple Features Sequentially with WhatsNewCollection

1. Use WhatsNewCollectionBuilder to compose multiple WhatsNew instances (Sources/Collection/WhatsNewCollectionBuilder.swift)
2. Optionally implement WhatsNewCollectionProvider for dynamic collection updates (Sources/Collection/WhatsNewCollectionProvider.swift)
3. Present the collection view which automatically handles sequential display and version tracking (Sources/View/WhatsNewView.swift)

Customize Button Styling and Layout Appearance

1. Configure WhatsNew.Layout enum to choose between slideup, sheet, or custom layouts (Sources/Models/WhatsNew+Layout.swift)
2. Define PrimaryAction with custom label and callback (Sources/Models/WhatsNew+PrimaryAction.swift)
3. Add SecondaryAction items for additional CTAs (Sources/Models/WhatsNew+SecondaryAction.swift)
4. Modify button style directly in WhatsNewView+PrimaryButtonStyle if deeper customization needed (Sources/View/WhatsNewView+PrimaryButtonStyle.swift)

• SwiftUI — Modern, declarative UI framework for cross-platform Apple development with binding and environment support
• Swift Package Manager — Native dependency and module management for Swift, simplifying distribution and integration
• UserDefaults / iCloud Key-Value Storage — Lightweight, native persistence for version tracking without requiring a backend or external database
• Protocol-based design — Enables flexible storage backends (UserDefaults, iCloud, in-memory, custom) without tight coupling

• Protocol-based VersionStore instead of concrete implementation

  • Why: Allows developers to swap storage backends (UserDefaults → iCloud → custom) without code changes
  • Consequence: Adds slight abstraction overhead but enables testing and multi-platform flexibility

• SwiftUI-first with UIViewController wrapper rather than pure UIKit

  • Why: Aligns with modern Apple tooling and reduces code duplication for new projects
  • Consequence: Older projects must create a bridge UIViewController or adopt SwiftUI for integration

• Collection + Builder pattern instead of varargs or array direct API

  • Why: Provides type-safe, fluent syntax with result builders and dynamic provider support
  • Consequence: Slightly more verbose for simple cases but scales well for complex multi-feature sequences

• Server-side feature flagging (no remote config)
• Analytics or impression tracking (delegated to caller)
• A/B testing or multivariate testing
• Localization beyond SwiftUI's native Text system
• Animation customization beyond default SwiftUI transitions
• Web or non-Apple platform support

No obvious environment variable or secret dependencies. Key consideration: automatic presentation relies on version tracking (likely UserDefaults or iCloud Key-Value Storage based on README mentioning 'icloud-key-value-storage.png'). Watch for state persistence across app updates. SwiftUI environment propagation requires the view hierarchy to inherit WhatsNewEnvironment — missing .whatsNewSheet() modifier will silently disable features.

• SwiftUI EnvironmentKey — WhatsNewEnvironment uses EnvironmentKey to pass presentation state down the view hierarchy without explicit parameter drilling; core to how .whatsNewSheet() knows when to display
• Result Builder (Function Builders) — WhatsNewCollectionBuilder likely uses @resultBuilder to enable the fluent DSL syntax for declaring features (e.g., WhatsNewItem { ... })
• View Modifiers (Custom SwiftUI Modifiers) — The .whatsNewSheet() modifier is a custom view modifier wrapping presentation logic; understanding modifier composition is essential for customizing behavior
• Swift Package Manager (SPM) — WhatsNewKit is distributed as an SPM package; understanding Package.swift and platform declarations is required for integration and testing
• DocC (Documentation Compiler) — The repo uses DocC for auto-generated API documentation (visible in deploy_documentation.yml workflow); documenting custom features requires DocC syntax
• Automatic Feature Detection (Version Tracking) — Automatic presentation mode tracks app version changes to show features only on first launch after update; likely uses UserDefaults or iCloud Key-Value Storage

• pointfreeco/swift-composable-architecture — Complementary state management library often used with SwiftUI feature announcement flows for deterministic testing
• SDWebImageSwiftUI/SDWebImageSwiftUI — If you need to load feature images asynchronously in WhatsNewKit presentations
• nalexn/clean-architecture-ios — Reference architecture for iOS apps using SwiftUI; shows integration patterns for libraries like WhatsNewKit
• SwiftUIX/SwiftUIX — Companion library of SwiftUI extensions that could enhance WhatsNewKit's modifier ecosystem
• exyte/PopupView — Alternative presentation mechanism (PopupView) for feature announcements if you need different UX than sheets

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 WhatsNewCollection and WhatsNewCollectionBuilder

The Sources/Collection directory contains core collection management logic (WhatsNewCollection.swift, WhatsNewCollectionBuilder.swift, WhatsNewCollectionProvider.swift) but there are no visible test files in the repo. These builder and collection classes handle critical feature showcase logic that needs test coverage to prevent regressions and document expected behavior.

• [ ] Create Tests directory structure mirroring Sources/Collection
• [ ] Add unit tests for WhatsNewCollectionBuilder validating DSL syntax and feature aggregation
• [ ] Add unit tests for WhatsNewCollection validating version management and feature filtering
• [ ] Add integration tests for WhatsNewCollectionProvider with both InMemoryWhatsNewVersionStore and NSUbiquitousKeyValueWhatsNewVersionStore
• [ ] Integrate test execution into existing build_and_test.yml workflow

Add tests for WhatsNewVersionStore implementations (InMemory and NSUbiquitous)

The two version store implementations in Sources/Store (InMemoryWhatsNewVersionStore.swift and NSUbiquitousKeyValueWhatsNewVersionStore.swift) are critical for version tracking but lack visible test coverage. These stores need thorough testing to ensure version persistence works correctly across app launches and iCloud scenarios.

• [ ] Create Tests/Store directory
• [ ] Add unit tests for InMemoryWhatsNewVersionStore covering read/write/clear operations
• [ ] Add unit tests for NSUbiquitousKeyValueWhatsNewVersionStore with mocked NSUbiquitousKeyValueStore behavior
• [ ] Add tests validating thread-safety and concurrent access patterns
• [ ] Add integration tests verifying version persistence across mock app lifecycle

Add UI snapshot tests for WhatsNew views using SwiftUI preview combinations

The Sources/Models directory defines numerous WhatsNew components (WhatsNew.swift, Feature.swift, PrimaryAction.swift, SecondaryAction.swift, Layout.swift) that render UI, but no snapshot tests exist to catch regressions in visual output. With the Example app already set up, snapshot tests would validate UI consistency across iOS/macOS and different configuration combinations.

• [ ] Set up snapshot testing dependency and configure in Package.swift
• [ ] Create Tests/Views directory for UI snapshot tests
• [ ] Add snapshot tests for WhatsNew main view with various Layout configurations (default, detailed, compact)
• [ ] Add snapshot tests for Feature rendering with different Image types and text variations
• [ ] Add snapshot tests for PrimaryAction and SecondaryAction button states
• [ ] Integrate snapshot reference updates into CI/CD workflow for managing baseline images

• Add unit tests for WhatsNewCollectionBuilder to verify fluent API chain validation; currently no test files visible in Sources/.
• Document the automatic vs. manual presentation modes with code examples in a new Docs/ folder — README hints at this but full guide is missing.
• Add macOS and visionOS-specific examples to Example/ExamplesView.swift; currently shows only iOS layout patterns.

WhatsNewKit is a well-structured Swift Package with generally good security posture. As a UI framework library for showcasing app features, it has minimal attack surface. The main considerations are: (1) ensuring dependency versions are pinned in Package.swift, (2) verifying that the iCloud Key-Value storage implementation doesn't persist sensitive data, and (3) confirming the Privacy Manifest accurately reflects data practices. No critical or high-severity vulnerabilities were identified. The codebase follows standard Swift package conventions and includes CI/CD testing workflows.

• Low · Missing dependency version pinning in Package.swift — Package.swift. The Package.swift file content was not provided for analysis. Without explicit version constraints on dependencies, the package may be vulnerable to unexpected breaking changes or security issues in transitive dependencies. Fix: Ensure all dependencies in Package.swift specify explicit version constraints (e.g., .upToNextMajor, .exact) to prevent automatic updates to untested versions.
• Low · Potential insecure storage in NSUbiquitousKeyValueWhatsNewVersionStore — Sources/Store/NSUbiquitousKeyValueWhatsNewVersionStore.swift. The NSUbiquitousKeyValueWhatsNewVersionStore uses iCloud Key-Value storage to persist version information. Sensitive user data stored via this mechanism is encrypted in transit and at rest by Apple, but the implementation details should be reviewed to ensure no sensitive information beyond version tracking is stored. Fix: Review the implementation to ensure only non-sensitive version metadata is stored. Do not store user credentials, authentication tokens, or other sensitive information in iCloud Key-Value storage.
• Low · No input validation visible for UIVisualEffectView extension — Sources/Extensions/UIVisualEffectView+Representable.swift. The UIVisualEffectView+Representable.swift extension creates native UIKit views from SwiftUI. Without visible input validation, there could be potential for misuse if external input is processed. Fix: Ensure any parameters passed to UIVisualEffectView are properly validated and sanitized before use.
• Low · Missing Content Security Policy in Privacy Info — Sources/Resources/PrivacyInfo.xcprivacy. While a PrivacyInfo.xcprivacy file exists, the actual content was not provided for review. Privacy manifest files should correctly declare all data collection and usage to comply with Apple's privacy requirements. Fix: Review the PrivacyInfo.xcprivacy manifest to ensure it accurately declares all data collection, usage, and third-party integrations as per Apple's Privacy Manifest requirements.

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.