Changelog - SwiftAI Boilerplate Pro

All notable changes to SwiftAI Boilerplate Pro.

Complete changelog: CHANGELOG.md in the repo

Latest Version

v2.2.0 - App Store 4.3 Hardening & Swift 6 Substrate - 2026-06-15

Summary: Ships a first-party App Store Guideline 4.3(a) playbook (audit gate + checklist + rebrand helper), a machine-readable template.manifest.json single source of truth, hero archetype recipes for differentiating apps, a new TestSupport package with a unified workspace test plan (~598 tests in one run), a localized error surface (en + es), single-source app identity, and a production-hardening pass. Same toolchain floor as v2.0: Xcode 26.2+ (iOS 26 SDK), iOS 17+ runtime.

App Store 4.3(a) playbook

scripts/appstore-43-audit.sh — Release-binary strings audit gate; fails on un-rebranded production fingerprints
docs/checklists/APP_STORE_4_3_HARDENING.md — binary audit, branding map, metadata, Review Notes, module removal
docs/prompts/AppStore4_3Hardening.prompts.md — prompt packs incl. the must-run starter-fingerprint clearing prompt (SwiftAI, Boilerplate, DesignSystem/SAI)
scripts/rebrand-design-system-prefix.sh — swaps the SAI design-system prefix

template.manifest.json

Repo-root machine-readable single source of truth
Identity surface, module graph (removable packages + couplings), config schema, canonical fingerprint list
Differentiation rules, recipes, verification commands
Consumed by the audit script + CI; validated by scripts/validate-template-manifest.sh

Hero archetype recipes

docs/recipes/hero/: DashboardGrid, FeedTimeline, MapCanvas, GuidedTaskFlow, ConversationalHome
Plus onboarding / paywall / feature recipes (docs/recipes/onboarding|paywall|features/)
4.3 differentiation enforced by mandatory archetype selection, not randomness

TestSupport + single test plan

New TestSupport package — unified lock-protected URLProtocolStub
Boilerplate.xctestplan rebuilt; scheme now references it
~598 tests across 12 package test targets + the app test suites (one xcodebuild test run)

Localized error surface

AppError.localizedUserMessage (en + es) in the Localization package
Localization now linked by the app target, FeatureSettings, and FeatureChat
All UI error call sites migrated

Single-source app identity

Every target’s bundle ID + app-group entitlements derive from one APP_BUNDLE_ID in Config/App.xcconfig
Stale upstream fingerprints purged from project metadata

Production hardening:

No https://api.example.com fallback. Production app-linked code fails through an explicit unconfigured-backend HTTP client path instead of a silent placeholder.
DEBUG-only mock auth. MockAuthClient and its literals (Debug User, debug-token) are kept out of Release binaries.
Configurable legal URLs. Legal views point at configured HTTPS legal URLs; [DATE] / [CONTACT EMAIL] placeholder bodies and generic legal markdown are excluded from the Release bundle.
Account deletion. AccountDeletionClient plumbing plus a supabase/functions/delete-account/ Edge Function template for authenticated deletion.
Bundle packaging fix. The app target no longer copies local Packages/ source directories or Boilerplate.xctestplan into the .app bundle as resources.

Coupling gotcha: LLMClient / LLMMessage live in FeatureChat, and the AI package re-exports FeatureChat. Removing chat without moving those types breaks Packages/AI — the 4.3 module-removal notes cover the safe path. Toolchain (unchanged from v2.0): build with Xcode 26.2+ (iOS 26 SDK / Liquid Glass symbols); .xcode-version pins 26.3. Runtime supports iOS 17+ via the SwiftUI Material fallback. Stuck on older Xcode? Stay on v1.9.0.

The macOS App Generator — which drives your own coding-agent CLI (Claude Code / Codex / Gemini / Cursor) to produce a differentiated, 4.3-safe app from this template — is now a separate product with its own repository and license. It is not bundled in the boilerplate and ships no LLM; the manifest, hero recipes, and single-source identity here are the template-side foundation it builds on. It is coming soon. See the license & pricing page for the pricing model and grandfathered-buyer benefits.

View Release Notes

Previous Versions

v2.0.0 - Swift 6 & iOS 26 Liquid Glass - 2026-04-12

Summary: Major release. The toolchain floor moves to Xcode 26.2+, the entire codebase builds under Swift 6 strict concurrency, and the DesignSystem ships a Liquid Glass primitive that uses the iOS 26 Glass material with an automatic SwiftUI Material fallback on iOS 17–25. Every file over 400 lines was split into extension siblings, public APIs intact.

iOS 26 Liquid Glass

New SAIGlass primitive in DesignSystem
SAIGlassStyle (.regular / .clear), .saiGlass(...) modifier
SAIGlassContainer merges adjacent glass surfaces
saiScrollEdgeGlass, saiSidebarAdaptable, saiTabBarMinimize
Progressive: iOS 26 uses Glass, iOS 17–25 falls back to Material

Swift 6 Strict Concurrency

@MainActor-pinned storage repositories
@Observable throughout (no ObservableObject, no .onReceive)
Explicit any on every protocol-typed property
Zero DispatchQueue.main in app code
Full build under strict concurrency checking

≤ 400-line file rule

SessionManager → +SignIn, +Refresh, +Persistence
L10n.swift → L10n+<Namespace>.swift per enum
SettingsView → ≤ 125-line root + Views/Settings/*
ChatViewModel → ChatViewModel+Memory.swift
Public API unchanged; no downstream breakage from the split

Backend + tooling

New Supabase migration: 20260408000000_fix_conversation_stats_auth
ai edge function updated and ready to redeploy
Secrets pre-commit hook in .githooks/
.xcode-version pinned to 26.3

Breaking-ish changes (most have zero call-site impact):

Xcode 26.2+ required. v2.0 uses iOS 26 SDK symbols; older toolchains cannot compile, even behind #available. Stay on v1.9.0 until you can upgrade.
Storage repositories are now @MainActor. If downstream code built MessageRepositoryImpl, ConversationRepositoryImpl, or SettingsRepositoryImpl from a non-main actor, add an await.
DeepLinkBus and ToastCenter are @Observable. Migrate any .onReceive($center.currentToast) to .onChange(of: center.currentToast).
Paywall CTAs use standard .borderedProminent / .bordered. If you themed them via .background(), switch to .tint() so Liquid Glass renders correctly.
Stop fighting glass. Remove .background(DSColors.background) on SwiftUI containers and DSColors.background.ignoresSafeArea() under sheets.

Upgrade path: follow Upgrading from v1.9 to v2.0. It covers toolchain install, Supabase migration, edge function redeploy, hook setup, downstream customisation reapply, glass cleanup, and paywall theming. View Release Notes | Migration Guide

v1.9.0 - Agent-Optimized Documentation - 2026-03-06

Summary: Every package in the boilerplate now has its own README and PROMPTS.md, and CLAUDE.md is environment-aware. Agents get different build instructions depending on whether they run through Xcode MCP or Claude Code in the terminal.

Environment-Aware CLAUDE.md

Detects Xcode MCP vs Claude Code CLI automatically
Different build instructions per environment
File organization patterns and naming conventions
Supabase, RevenueCat, OpenRouter integration specifics
Expanded anti-patterns (no UIKit, no ObservableObject, no raw URLSession)

Per-Module Documentation

READMEs for all 11 packages (3 were missing)
PROMPTS.md in every package with 2-4 example prompts
Prompts reference actual types, protocols, and patterns
DesignSystem, FeatureRating, FeatureSettings now documented

Bugfix: EchoLLMClient now activates correctly in debug mode. The guard previously checked for “YOUR” in PROXY_BASE_URL, but the default placeholder value contains “placeholder” instead. Fixed in both createLLMClient() and the proxyBaseURL property. All tests pass. Upgrade Notes: Pull the latest and your coding agent will automatically pick up the improved context. No code changes required.

v1.8.0 - Agentic Development - 2026-03-01

Summary: CLAUDE.md rewritten for agentic development with Claude Code. New distribution email infrastructure for notifying buyers about updates. Package count corrected to 11 across all files.

Agentic Development

CLAUDE.md updated for Claude Code workflow
FeatureRating and Localization modules documented
New guide: Agentic Coding on iOS
Package count corrected to 11

Distribution Infrastructure

Email notification system for version updates
Buyer email list with manual and automated capture
Paddle webhook integration for new buyers
GitHub vs ZIP delivery routing

Upgrade Notes: Pull the latest to get the updated CLAUDE.md. No code changes required.

v1.7.0 - Smart App Rating Prompts - 2026-02-10

Summary: New FeatureRating module for smart, sentiment-based app rating prompts. Track positive and negative user actions, automatically show a beautiful pre-prompt popup at the right moment, and trigger the native App Store review dialog when users are happiest. Includes a stopAskingAfterRating flag that permanently stops prompting once a user taps “Rate on App Store”.

⭐ Smart Rating Engine

Sentiment-based scoring with configurable weights
Time-based decay for inactive users
Cooldowns (30-day default) and yearly limits (3/year)
stopAskingAfterRating flag (default: true)
25+ unit tests with MockRatingStorage

🎨 Pre-Prompt Popup

Beautiful themed popup before native dialog
Fully customizable text, icon, and styling
Works across all 5 themes
Dark mode and VoiceOver support
One-line .ratingPrompt() modifier

Quick Integration:

import FeatureRating

// Record positive actions at key moments
ratingClient.record(.positive("task_done", weight: 2.0))
ratingClient.record(.positive("milestone_reached", weight: 3.0))

// Pre-defined templates
ratingClient.record(.taskCompleted)
ratingClient.record(.purchaseCompleted)

// The system handles the rest: pre-prompt popup + native review dialog

Upgrade Notes: This feature is optional. Existing code works without changes. The package is already included; customize RatingConfig in CompositionRoot.swift and add .record() calls at key moments.

View Release Notes

v1.6.0 - Localization & Accessibility Modules - 2026-01-04

Summary: New Localization module and comprehensive Accessibility features. Type-safe localization with L10n enum and full accessibility support with A11y labels and modifiers for building inclusive apps.

🌍 Localization Module

New Localization Swift Package
L10n enum with nested namespaces
Built-in pluralization via .stringsdict
English & Spanish included
Zero configuration required

♿ Accessibility Features

A11yLabel struct for type-safe labels
A11y enum with pre-defined labels
9 new accessibility modifiers
A11yAudit debug tool
Dynamic Type & Reduce Motion support

Localization Usage:

import Localization

// Type-safe, organized string access
Text(L10n.Auth.tagline)
Text(L10n.Chat.sendButton)

// Pluralization support
Text(L10n.Chat.messagesRemaining(count))

Accessibility Modifiers:

import DesignSystem

// Apply type-safe accessibility labels
Button("Send") { }
    .saiAccessible(A11y.Chat.sendButton)

// Dynamic Type support
Text("Title")
    .saiScaledFont(.title)

// Respect Reduce Motion
.saiMotionAwareAnimation(.spring())

// High Contrast mode
.saiHighContrastSupport(normal: .secondary, highContrast: .primary)

New Accessibility Modifiers:

.saiAccessible(_:) - Apply type-safe accessibility labels
.saiAccessibilityHidden() - Hide decorative elements
.saiAccessibilityGroup() - Combine related elements
.saiAccessibilityValue(_:) - Dynamic value announcements
.saiAccessibilitySortPriority(_:) - Custom reading order
.saiScaledFont(_:) - Dynamic Type support
.saiMotionAwareAnimation(_:) - Respect Reduce Motion
.saiHighContrastSupport(normal:highContrast:) - High Contrast mode
.saiFocusIndicator(_:) - Visible focus rings for Switch Control

Upgrade Notes: Both features are optional - existing code works without changes. Just import and use when ready. View Release Notes | Localization Guide | Accessibility Guide

v1.5.0 - OneSignal Push Notifications & Session Fix - 2025-12-20

Summary: Complete OneSignal push notifications integration and critical fix for session management that was logging users out unexpectedly.

🔔 Push Notifications

Complete OneSignal SDK integration
Rich notifications (images, buttons, badges)
Confirmed delivery analytics
Graceful degradation without config

🔴 Critical Session Fix

Fixed unexpected logouts after ~1 hour
Proper token refresh with retry logic
Users stay logged in 7+ days
Shows refreshing state during refresh

Session Management Fix:

Scenario	Before (Bug)	After (Fixed)
Open app after 2 hours	❌ Logged out	✅ Silent refresh
Open app after 3 days	❌ Logged out	✅ Silent refresh
Open app after 14+ days	❌ Logged out	✅ Graceful logout

Upgrade Notes:

Session fix is automatic - just update
Push notifications are optional - add ONESIGNAL_APP_ID to Secrets.xcconfig if needed

View Release Notes | OneSignal Setup Guide

v1.4.0 - Bug Fixes & Profile/Settings Restructure - 2025-12-01

Summary: Profile is now the main tab with Settings as a sheet, plus critical validation fixes and enhanced RevenueCat error handling.

🏗️ UI Restructure

Profile is now a main tab
Settings accessible via gear icon
New ‘Already Subscribed’ Paywall UI
Better subscription status display

🐛 Critical Fixes

Fixed Sign In/Sign Up validation deadlock
Enhanced RevenueCat error handling
Better StoreKit error messages
Comprehensive purchase flow logging

Sign In/Sign Up Fix: Users could get stuck with a disabled submit button due to validation errors that weren’t cleared when editing. Now all fields properly clear errors on change. Payment Improvements:

PaywallViewModel catches PaymentsError explicitly
Better messages for receipt issues, invalid purchases, config problems
Comprehensive logging for debugging purchase issues

New Paywall ‘Already Subscribed’ UI:

Success state showing Pro status with checkmark
Feature list of what Pro users have access to
Continue and Manage Subscription buttons

View Release Notes

v1.3.0 - AI-Assisted Development Configurations - 2025-11-18

Summary: Comprehensive Cursor AI and Bolt AI configurations for accelerated development with consistent, high-quality code generation.

Cursor AI Rules

4 comprehensive .mdc rule files
Automatic code quality enforcement
DesignSystem usage enforced
Protocol-based dependencies
MVVM architecture patterns

Bolt AI Chat Modes

12 specialized AI assistants
Context-aware development
Domain-specific expertise
From architecture to deployment
Instant mode switching

Key Features:

Cursor Rules (.cursor/rules/): Architecture enforcement, SwiftUI patterns, DesignSystem usage, modular design
Bolt Chat Modes (.bolt/): iOS Developer, Architecture, SwiftUI, Feature Dev, Integration, Testing, Debug, Performance, Package, Deploy, Accessibility, Documentation
Zero Setup: Works automatically when you open the project
SEO Optimized: Cursor AI, Bolt AI, .MDC rules, AI-assisted iOS development

Benefits:

✅ Consistent code quality across AI-generated code
✅ Automatic adherence to architecture patterns
✅ Proper DesignSystem usage (DSColors, DSFonts, DSSpacing)
✅ Protocol-based dependencies for testability
✅ Comprehensive error handling
✅ Swift best practices (async/await, @MainActor, Sendable)

Example AI Prompts That Work Perfectly:

"Create a new settings view using DesignSystem components"
"Add a profile ViewModel following MVVM pattern"
"Create a new feature package for Notifications"
"Refactor this to use repository pattern"

View Release Notes | Read AI Development Guide

v1.2.1 - Device & Archive Build Fixes - 2025-11-18

Summary: Critical bug fix for device and App Store archive builds.

Bug Fix

Fixed build failures when building for physical devices or creating App Store archives. Preview code now properly excluded from release builds.

Issues Fixed:

Preview Code Errors: #Preview blocks now properly wrapped in #if DEBUG
Bundle Extension Error: Moved Bundle extension outside debug block
Device Builds: Can now build for physical devices
Archive Builds: Can now archive for App Store submission

Files Fixed:

ChatGPTStyleView.swift - Preview blocks wrapped
DualStyleChatView.swift - Preview blocks wrapped
SettingsView.swift - Bundle extension moved

View Release Notes

v1.2.0 - Authentication & Payments Improvements - 2025-11-17

Summary: Enhanced authentication error handling and added RevenueCat StoreKit Configuration support for simulator testing.

Authentication

Fixed misleading error messages
Improved sign-out navigation
Better error context
Email confirmation support

RevenueCat

StoreKit Configuration added
Simulator testing fixed
Integration checklist created
Comprehensive troubleshooting

Key Changes:

Auth Error Messages: More specific and helpful error messages instead of generic “Network error occurred”
Sign-Out Fix: Users now immediately return to auth screen when signing out
Simulator Testing: Added StoreKit Configuration file with correct Xcode scheme path
Product ID Guidance: Clear documentation on matching product IDs across all systems
Integration Checklist: New step-by-step verification checklist for RevenueCat setup

Files Changed:

Enhanced error handling in Auth package
Added StoreKitConfiguration.storekit for simulator testing
Created REVENUECAT_INTEGRATION.md checklist
Updated RevenueCat documentation with new Step 11

View Release Notes

v1.1.0 - Documentation & Testing Overhaul - 2025-10-13

Summary: Complete documentation restructure with a comprehensive test suite achieving 85-90% coverage.

Documentation

Single-path approach
60KB+ of guides
Example-first
LLM-friendly

Testing

Comprehensive test suite added
85-90% coverage
CI enforcement
Comprehensive error scenarios

Added

Core Documentation:

README.md - 10-minute Quick Start
docs/INDEX.md - Central documentation hub
docs/foundations/Architecture.md - System design
BUILDING_YOUR_APP.md - 60KB customization guide with LLM prompts
docs/testing-guide.md - Comprehensive testing guide

Module Documentation (12 modules):

Core, Networking, Storage, Auth, Payments, AI
FeatureChat, FeatureSettings, DesignSystem
Composition, plus 3 feature-specific docs

Migration Guides:

Supabase setup (auth + AI proxy)
RevenueCat setup (subscriptions)
Chat sync setup (22KB guide)
Profile photo setup (12KB guide)

Testing Infrastructure:

Comprehensive unit, integration, and UI test coverage across the modules
CI/CD with coverage enforcement

Changed

Documentation structure: Single-path, example-first
Quick Start reduced from 30 to 10 minutes
All module docs follow consistent template
Test coverage increased from ~60% to 85-90%

Removed

18 legacy/duplicate documentation files
Scattered guides consolidated
Outdated status tracking docs

Earlier Versions

Initial Release - 2024

Complete boilerplate with:

9 Swift Package modules (now 11 with Localization & FeatureRating; accessibility lives in DesignSystem)
MVVM architecture
Dual-style chat UI
Supabase + RevenueCat integration
5 built-in themes
Comprehensive error handling
Mock implementations
Production-ready patterns

Version Format

We use semantic versioning: MAJOR.MINOR.PATCH

MAJOR - Incompatible API changes
MINOR - New features (backward compatible)
PATCH - Bug fixes (backward compatible)

Release Notes

Documentation Overhaul (Oct 2025)

Focus: Developer experienceKey improvements:

60KB customization guide with LLM prompts
Comprehensive test suite with 85-90% coverage
CI enforcement prevents regressions
Single-path documentation
Example-first approach

Time saved: 30+ hours of documentation reading time

Initial Release (2024)

Focus: Production-ready foundationKey features:

Complete iOS app architecture
AI chat with 500+ models
Authentication (Supabase + Apple)
Subscriptions (RevenueCat)
Design system with 5 themes
Testing infrastructure
Comprehensive documentation

Time saved: 400+ hours of development

Upcoming

The macOS App Generator is the next product on the roadmap — a separate, standalone tool that drives your own coding-agent CLI to produce a differentiated, App Store Guideline 4.3-safe app from this template. It is coming soon with its own repository and license. See the license & pricing page for details and grandfathered-buyer benefits.

Migration Guides

When upgrading between versions:

Read Changelog

Check what changed in the new version.

Update Dependencies

In Xcode: File → Packages → Update to Latest Package Versions.

Run Tests

One pass covers the whole workspace via Boilerplate.xctestplan:

./scripts/run-tests.sh

Fix Breaking Changes

Follow the migration notes for your version.

View Complete Changelog

Complete version history with detailed change notes

Features

Complete feature list

Architecture

System design

Building Guide

Customization guide

Testing

Testing guide

​Latest Version

​v2.2.0 - App Store 4.3 Hardening & Swift 6 Substrate - 2026-06-15

App Store 4.3(a) playbook

template.manifest.json

Hero archetype recipes

TestSupport + single test plan

Localized error surface

Single-source app identity

​Previous Versions

​v2.0.0 - Swift 6 & iOS 26 Liquid Glass - 2026-04-12

iOS 26 Liquid Glass

Swift 6 Strict Concurrency

≤ 400-line file rule

Backend + tooling

​v1.9.0 - Agent-Optimized Documentation - 2026-03-06

Environment-Aware CLAUDE.md

Per-Module Documentation

​v1.8.0 - Agentic Development - 2026-03-01

Agentic Development

Distribution Infrastructure

​v1.7.0 - Smart App Rating Prompts - 2026-02-10

⭐ Smart Rating Engine

🎨 Pre-Prompt Popup

​View Release Notes

​v1.6.0 - Localization & Accessibility Modules - 2026-01-04

🌍 Localization Module

♿ Accessibility Features

​v1.5.0 - OneSignal Push Notifications & Session Fix - 2025-12-20

🔔 Push Notifications

🔴 Critical Session Fix

​v1.4.0 - Bug Fixes & Profile/Settings Restructure - 2025-12-01

🏗️ UI Restructure

🐛 Critical Fixes

​v1.3.0 - AI-Assisted Development Configurations - 2025-11-18

Cursor AI Rules

Bolt AI Chat Modes

​v1.2.1 - Device & Archive Build Fixes - 2025-11-18

Bug Fix

​v1.2.0 - Authentication & Payments Improvements - 2025-11-17

Authentication

RevenueCat

​v1.1.0 - Documentation & Testing Overhaul - 2025-10-13

Documentation

Testing

​Added

​Changed

​Removed

​Earlier Versions

​Initial Release - 2024

​Version Format

​Release Notes

​Upcoming

​Migration Guides

​View Complete Changelog

View Complete Changelog

​Related

Features

Architecture

Building Guide

Testing

Latest Version

v2.2.0 - App Store 4.3 Hardening & Swift 6 Substrate - 2026-06-15

Previous Versions

v2.0.0 - Swift 6 & iOS 26 Liquid Glass - 2026-04-12

v1.9.0 - Agent-Optimized Documentation - 2026-03-06

v1.8.0 - Agentic Development - 2026-03-01

v1.7.0 - Smart App Rating Prompts - 2026-02-10

View Release Notes

v1.6.0 - Localization & Accessibility Modules - 2026-01-04

v1.5.0 - OneSignal Push Notifications & Session Fix - 2025-12-20

v1.4.0 - Bug Fixes & Profile/Settings Restructure - 2025-12-01

v1.3.0 - AI-Assisted Development Configurations - 2025-11-18

v1.2.1 - Device & Archive Build Fixes - 2025-11-18

v1.2.0 - Authentication & Payments Improvements - 2025-11-17

v1.1.0 - Documentation & Testing Overhaul - 2025-10-13

Added

Changed

Removed

Earlier Versions

Initial Release - 2024

Version Format

Release Notes

Upcoming

Migration Guides

View Complete Changelog

Related