@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/mapkit-location/references/corelocation-patterns.md

@@ -0,0 +1,730 @@
+# CoreLocation Patterns Reference
+
+Extended patterns for CoreLocation on iOS 17+ with modern Swift concurrency.
+Import `CoreLocation` in every file that uses these APIs.
+
+```swift
+import CoreLocation
+```
+
+---
+
+## Contents
+
+- [CLLocationUpdate.liveUpdates() (iOS 17+)](#cllocationupdateliveupdates-ios-17)
+- [CLServiceSession (iOS 18+)](#clservicesession-ios-18)
+- [CLMonitor for Geofencing (iOS 17+)](#clmonitor-for-geofencing-ios-17)
+- [CLBackgroundActivitySession](#clbackgroundactivitysession)
+- [Significant Location Change Monitoring](#significant-location-change-monitoring)
+- [Visit Monitoring](#visit-monitoring)
+- [Region Monitoring Migration (CLCircularRegion to CLMonitor)](#region-monitoring-migration-clcircularregion-to-clmonitor)
+- [Location Accuracy Management](#location-accuracy-management)
+- [Testing Location in Simulator](#testing-location-in-simulator)
+- [Privacy and Info.plist Keys](#privacy-and-infoplist-keys)
+- [Common Pitfalls](#common-pitfalls)
+- [References](#references)
+
+## CLLocationUpdate.liveUpdates() (iOS 17+)
+
+### Basic Usage
+
+```swift
+func startReceivingLocation() async {
+    for try await update in CLLocationUpdate.liveUpdates() {
+        guard let location = update.location else { continue }
+        print("Lat: \(location.coordinate.latitude), Lon: \(location.coordinate.longitude)")
+        print("Accuracy: \(location.horizontalAccuracy)m")
+    }
+}
+```
+
+### Full Implementation with Filtering
+
+Filter out stale, inaccurate, or duplicate updates to avoid unnecessary UI
+refreshes and reduce battery impact.
+
+```swift
+@Observable
+final class LocationService: @unchecked Sendable {
+    var currentLocation: CLLocation?
+    var isTracking = false
+
+    private var trackingTask: Task<Void, Never>?
+    private var lastReportedLocation: CLLocation?
+
+    /// Minimum distance in meters between reported locations.
+    private let distanceFilter: CLLocationDistance = 10
+    /// Maximum acceptable horizontal accuracy in meters.
+    private let accuracyThreshold: CLLocationAccuracy = 100
+
+    func startTracking() {
+        guard !isTracking else { return }
+        isTracking = true
+
+        trackingTask = Task { [weak self] in
+            guard let self else { return }
+            let updates = CLLocationUpdate.liveUpdates(.default)
+
+            for try await update in updates {
+                if Task.isCancelled { break }
+
+                // Skip updates without a location
+                guard let location = update.location else { continue }
+
+                // Skip inaccurate readings
+                guard location.horizontalAccuracy >= 0,
+                      location.horizontalAccuracy < self.accuracyThreshold else {
+                    continue
+                }
+
+                // Skip if the user has not moved enough
+                if let last = self.lastReportedLocation,
+                   location.distance(from: last) < self.distanceFilter {
+                    continue
+                }
+
+                self.lastReportedLocation = location
+
+                await MainActor.run {
+                    self.currentLocation = location
+                }
+            }
+
+            await MainActor.run {
+                self.isTracking = false
+            }
+        }
+    }
+
+    func stopTracking() {
+        trackingTask?.cancel()
+        trackingTask = nil
+        isTracking = false
+    }
+}
+```
+
+### LiveConfiguration Options
+
+`CLLocationUpdate.liveUpdates(_:)` accepts a `LiveConfiguration` parameter:
+
+```swift
+// Default: balanced power and accuracy
+CLLocationUpdate.liveUpdates(.default)
+
+// Best for navigation: highest accuracy, most frequent updates
+CLLocationUpdate.liveUpdates(.automotiveNavigation)
+
+// Fitness tracking
+CLLocationUpdate.liveUpdates(.fitness)
+
+// Other-navigation (non-automotive)
+CLLocationUpdate.liveUpdates(.otherNavigation)
+
+// Airborne: for drone or aviation apps
+CLLocationUpdate.liveUpdates(.airborne)
+```
+
+### Handling Stationary and Error States (iOS 18+)
+
+```swift
+for try await update in CLLocationUpdate.liveUpdates() {
+    // Check authorization status (iOS 18+)
+    if update.authorizationDenied {
+        // User denied location; prompt to open Settings
+        break
+    }
+
+    if update.authorizationDeniedGlobally {
+        // Location Services disabled system-wide
+        break
+    }
+
+    if update.insufficientlyInUse {
+        // App does not meet in-use requirements
+        continue
+    }
+
+    if update.locationUnavailable {
+        // Temporarily unable to determine location; keep iterating
+        continue
+    }
+
+    if update.stationary {
+        // Device stopped moving; updates will pause
+        continue
+    }
+
+    guard let location = update.location else { continue }
+    // Use location
+}
+```
+
+Note: `authorizationDenied`, `authorizationDeniedGlobally`,
+`insufficientlyInUse`, `locationUnavailable`, and `stationary` are only
+available on iOS 18+. On iOS 17, check `update.location == nil` to detect
+unavailable location.
+
+---
+
+## CLServiceSession (iOS 18+)
+
+### Setup and Lifecycle
+
+`CLServiceSession` declares your authorization requirements for a feature.
+Hold a strong reference for the session's entire duration.
+
+```swift
+@Observable
+final class LocationFeature {
+    private var serviceSession: CLServiceSession?
+    private var locationTask: Task<Void, Never>?
+
+    func activate() {
+        // Declare that this feature needs when-in-use authorization
+        serviceSession = CLServiceSession(authorization: .whenInUse)
+
+        locationTask = Task {
+            for try await update in CLLocationUpdate.liveUpdates() {
+                guard let location = update.location else { continue }
+                // process location
+            }
+        }
+    }
+
+    func deactivate() {
+        locationTask?.cancel()
+        locationTask = nil
+        // Release the session to signal you no longer need location
+        serviceSession = nil
+    }
+}
+```
+
+### Full Accuracy Request
+
+Request full accuracy when the user has granted approximate-only permission:
+
+```swift
+// Requires Info.plist:
+// NSLocationTemporaryUsageDescriptionDictionary
+//   NearbySearchPurpose: "Show nearby stores within walking distance."
+
+let session = CLServiceSession(
+    authorization: .whenInUse,
+    fullAccuracyPurposeKey: "NearbySearchPurpose"
+)
+```
+
+### Always Authorization
+
+Only use `.always` when you need the system to relaunch your app in the
+background for significant location changes after termination.
+
+```swift
+let session = CLServiceSession(authorization: .always)
+```
+
+Requires `NSLocationAlwaysAndWhenInUseUsageDescription` in Info.plist.
+
+### Implicit vs. Explicit Sessions
+
+On iOS 18+, `CLLocationUpdate.liveUpdates()` and `CLMonitor` create an
+implicit `CLServiceSession` behind the scenes if you do not create one. You
+need an explicit session when:
+
+- You require `.always` authorization
+- You need full accuracy via `fullAccuracyPurposeKey`
+- You want to enforce explicit session management (add
+  `NSLocationRequireExplicitServiceSession` to Info.plist)
+
+---
+
+## CLMonitor for Geofencing (iOS 17+)
+
+### Basic Setup
+
+`CLMonitor` replaces `CLLocationManager` region monitoring. It is an `actor`,
+so all its APIs require `await`.
+
+```swift
+@available(iOS 17, *)
+actor GeofenceMonitor {
+    private var monitor: CLMonitor?
+    private var monitoringTask: Task<Void, any Error>?
+
+    func startMonitoring(regions: [GeofenceRegion]) async {
+        let monitor = await CLMonitor("myAppGeofences")
+        self.monitor = monitor
+
+        // Add circular geographic conditions
+        for region in regions {
+            let condition = CLMonitor.CircularGeographicCondition(
+                center: region.center,
+                radius: region.radius
+            )
+            await monitor.add(condition, identifier: region.id)
+        }
+
+        // Listen for events
+        monitoringTask = Task {
+            for try await event in await monitor.events {
+                switch event.state {
+                case .satisfied:
+                    // Device entered the region
+                    handleEntry(identifier: event.identifier)
+                case .unsatisfied:
+                    // Device exited the region
+                    handleExit(identifier: event.identifier)
+                case .unknown:
+                    break
+                default:
+                    break
+                }
+            }
+        }
+    }
+
+    func stopMonitoring() async {
+        monitoringTask?.cancel()
+        monitoringTask = nil
+
+        if let monitor {
+            for identifier in await monitor.identifiers {
+                await monitor.remove(identifier)
+            }
+        }
+        monitor = nil
+    }
+
+    private func handleEntry(identifier: String) {
+        print("Entered region: \(identifier)")
+    }
+
+    private func handleExit(identifier: String) {
+        print("Exited region: \(identifier)")
+    }
+}
+
+struct GeofenceRegion: Identifiable {
+    let id: String
+    let center: CLLocationCoordinate2D
+    let radius: CLLocationDistance
+}
+```
+
+### Critical CLMonitor Rules
+
+1. **Maximum 20 conditions per app.** Adding more causes excess conditions
+   to report `unmonitored` state. This limit is per-app, not per-monitor.
+
+2. **Do not recreate CLMonitor instances rapidly.** Creating a monitor with
+   the same name while one is still alive crashes the app. Reuse the instance
+   and call `add`/`remove` to change conditions.
+
+3. **Subscribe to `events` exactly once per CLMonitor.** Cancelling and
+   re-subscribing causes the new subscription to immediately cancel. Keep a
+   single long-lived subscription.
+
+4. **Use diffing for condition updates.** Instead of removing all conditions
+   and re-adding them, calculate which to add and which to remove.
+
+5. **Target iOS 18+ for best results.** Pair `CLMonitor` with
+   `CLServiceSession` for reliable authorization management.
+
+### Adding Conditions with Initial State
+
+Specify an assumed initial state to avoid spurious events on first add:
+
+```swift
+await monitor.add(condition, identifier: "office", assuming: .unsatisfied)
+```
+
+Use `.unsatisfied` when you believe the device is outside the region. Use
+`.satisfied` when you believe the device is inside.
+
+### Updating Conditions Dynamically
+
+```swift
+func updateRegions(_ newRegions: [GeofenceRegion]) async {
+    guard let monitor else { return }
+
+    let existingIDs = Set(await monitor.identifiers)
+    let newIDs = Set(newRegions.map(\.id))
+
+    // Remove stale conditions
+    for id in existingIDs.subtracting(newIDs) {
+        await monitor.remove(id)
+    }
+
+    // Add new conditions
+    for region in newRegions where !existingIDs.contains(region.id) {
+        let condition = CLMonitor.CircularGeographicCondition(
+            center: region.center,
+            radius: region.radius
+        )
+        await monitor.add(condition, identifier: region.id, assuming: .unsatisfied)
+    }
+}
+```
+
+### Checking Last Known State
+
+```swift
+if let record = await monitor.record(for: "office") {
+    let lastState = record.lastEvent.state
+    let lastDate = record.lastEvent.date
+    print("Region 'office' was \(lastState) at \(lastDate)")
+}
+```
+
+---
+
+## CLBackgroundActivitySession
+
+Allow a when-in-use authorized app to receive location updates in the
+background. Requires the `Location updates` background mode capability.
+
+```swift
+@available(iOS 17, *)
+actor BackgroundLocationTracker {
+    private var backgroundSession: CLBackgroundActivitySession?
+    private var serviceSession: CLServiceSession?
+    private var trackingTask: Task<Void, Never>?
+
+    func startBackgroundTracking() {
+        // Declare authorization intent (iOS 18+)
+        serviceSession = CLServiceSession(authorization: .whenInUse)
+
+        // Start background activity session -- shows blue location indicator
+        backgroundSession = CLBackgroundActivitySession()
+
+        trackingTask = Task {
+            for try await update in CLLocationUpdate.liveUpdates(.fitness) {
+                guard let location = update.location else { continue }
+                // Record location for fitness tracking, navigation, etc.
+                await recordLocation(location)
+            }
+        }
+    }
+
+    func stopBackgroundTracking() {
+        trackingTask?.cancel()
+        trackingTask = nil
+        backgroundSession?.invalidate()
+        backgroundSession = nil
+        serviceSession = nil
+    }
+
+    private func recordLocation(_ location: CLLocation) async {
+        // Persist to database, update Live Activity, etc.
+    }
+}
+```
+
+### Background Requirements Summary
+
+To receive location in the background you need ALL of these:
+
+1. `Background Modes > Location updates` capability enabled.
+2. `NSLocationWhenInUseUsageDescription` in Info.plist.
+3. `.whenInUse` or `.always` authorization granted.
+4. Either a `CLBackgroundActivitySession` held or a Live Activity running.
+5. An active `CLLocationUpdate` or `CLMonitor` subscription.
+
+`.always` authorization is NOT required for background location. The
+difference: with `.always`, the system can relaunch your terminated app for
+significant location changes. With `.whenInUse` + background session, the
+app must be running (foreground or suspended).
+
+---
+
+## Significant Location Change Monitoring
+
+Use when you only need coarse location updates at ~500-meter intervals.
+Extremely battery efficient because it piggybacks on cellular tower changes.
+
+```swift
+// Legacy CLLocationManager approach (still valid, no modern replacement)
+let manager = CLLocationManager()
+manager.startMonitoringSignificantLocationChanges()
+
+// The delegate receives updates when the device moves ~500m+ from the
+// last reported location. Updates arrive 1-5 minutes apart.
+```
+
+There is no `CLLocationUpdate` equivalent for significant location changes.
+Use `CLLocationManager` for this specific use case.
+
+---
+
+## Visit Monitoring
+
+Detect when the user arrives at or departs from a place. Useful for
+journaling, check-in, and context-aware features.
+
+```swift
+let manager = CLLocationManager()
+manager.startMonitoringVisits()
+
+// Delegate callback:
+func locationManager(_ manager: CLLocationManager, didVisit visit: CLVisit) {
+    let coordinate = visit.coordinate
+    let arrivalDate = visit.arrivalDate
+    let departureDate = visit.departureDate
+    // departureDate == .distantFuture means the user is still at the location
+}
+```
+
+---
+
+## Region Monitoring Migration (CLCircularRegion to CLMonitor)
+
+### Legacy Approach (Deprecated)
+
+```swift
+// DEPRECATED
+let region = CLCircularRegion(center: coordinate, radius: 200, identifier: "office")
+region.notifyOnEntry = true
+region.notifyOnExit = true
+manager.startMonitoring(for: region)
+```
+
+### Modern Approach (iOS 17+)
+
+```swift
+// MODERN
+let monitor = await CLMonitor("appMonitor")
+let condition = CLMonitor.CircularGeographicCondition(center: coordinate, radius: 200)
+await monitor.add(condition, identifier: "office")
+
+for try await event in await monitor.events {
+    if event.identifier == "office" {
+        switch event.state {
+        case .satisfied: handleEntry()
+        case .unsatisfied: handleExit()
+        default: break
+        }
+    }
+}
+```
+
+Key differences:
+
+| Aspect | CLCircularRegion | CLMonitor |
+|--------|-----------------|-----------|
+| API style | Delegate callbacks | Async sequence |
+| Max regions | 20 per app | 20 per app |
+| Entry/exit | Separate booleans | State enum (satisfied/unsatisfied) |
+| Concurrency | @objc delegate | Actor-based |
+| Min iOS | iOS 7 | iOS 17 |
+
+---
+
+## Location Accuracy Management
+
+### Accuracy Levels for CLLocationManager
+
+```swift
+manager.desiredAccuracy = kCLLocationAccuracyBest             // GPS, ~5m, highest power
+manager.desiredAccuracy = kCLLocationAccuracyNearestTenMeters // ~10m
+manager.desiredAccuracy = kCLLocationAccuracyHundredMeters    // WiFi, ~100m
+manager.desiredAccuracy = kCLLocationAccuracyKilometer        // Cell tower, ~1km
+manager.desiredAccuracy = kCLLocationAccuracyThreeKilometers  // ~3km, lowest power
+manager.desiredAccuracy = kCLLocationAccuracyReduced          // ~5km, privacy-safe
+```
+
+### Activity Type (Influences Power Management)
+
+```swift
+manager.activityType = .other                 // Default
+manager.activityType = .automotiveNavigation  // Highway speeds, high accuracy
+manager.activityType = .fitness               // Walking/running
+manager.activityType = .otherNavigation       // Boats, trains
+manager.activityType = .airborne              // Drones, aircraft (iOS 12+)
+```
+
+### CLLocationUpdate has no filtering
+
+`CLLocationUpdate.liveUpdates()` does not support `desiredAccuracy` or
+`distanceFilter`. Filter the stream yourself:
+
+```swift
+for try await update in CLLocationUpdate.liveUpdates() {
+    guard let location = update.location,
+          location.horizontalAccuracy < 50,
+          location.horizontalAccuracy >= 0 else { continue }
+    // Use filtered location
+}
+```
+
+---
+
+## Testing Location in Simulator
+
+### Set a fixed simulated location
+
+In Xcode: Debug > Simulate Location > choose a city or custom coordinate.
+
+### GPX File for a Moving Route
+
+Create a `.gpx` file and add it to your Xcode project:
+
+```xml
+<?xml version="1.0"?>
+<gpx version="1.1" creator="Xcode">
+    <wpt lat="37.3349" lon="-122.0090">
+        <time>2025-01-01T00:00:00Z</time>
+        <name>Apple Park</name>
+    </wpt>
+    <wpt lat="37.3318" lon="-122.0312">
+        <time>2025-01-01T00:01:00Z</time>
+        <name>Infinite Loop</name>
+    </wpt>
+    <wpt lat="37.3230" lon="-122.0322">
+        <time>2025-01-01T00:02:00Z</time>
+        <name>De Anza College</name>
+    </wpt>
+</gpx>
+```
+
+Set this file in the scheme: Edit Scheme > Run > Options > Default Location.
+
+The simulator interpolates between waypoints using timestamps. Playback loops
+automatically when it reaches the last waypoint.
+
+### Programmatic Simulation in Tests
+
+Use `CLLocationManager` with XCTest by injecting a location protocol:
+
+```swift
+protocol LocationProviding: Sendable {
+    func updates() -> AsyncStream<CLLocation>
+}
+
+// Production
+struct LiveLocationProvider: LocationProviding {
+    func updates() -> AsyncStream<CLLocation> {
+        AsyncStream { continuation in
+            Task {
+                for try await update in CLLocationUpdate.liveUpdates() {
+                    if let location = update.location {
+                        continuation.yield(location)
+                    }
+                }
+                continuation.finish()
+            }
+        }
+    }
+}
+
+// Test mock
+struct MockLocationProvider: LocationProviding {
+    let locations: [CLLocation]
+
+    func updates() -> AsyncStream<CLLocation> {
+        AsyncStream { continuation in
+            for location in locations {
+                continuation.yield(location)
+            }
+            continuation.finish()
+        }
+    }
+}
+```
+
+---
+
+## Privacy and Info.plist Keys
+
+### Required Keys
+
+| Key | When to add |
+|-----|-------------|
+| `NSLocationWhenInUseUsageDescription` | Always, for any location use |
+| `NSLocationAlwaysAndWhenInUseUsageDescription` | Only if requesting `.always` |
+
+### Optional Keys
+
+| Key | Purpose |
+|-----|---------|
+| `NSLocationTemporaryUsageDescriptionDictionary` | Per-feature full-accuracy descriptions |
+| `NSLocationRequireExplicitServiceSession` | Force explicit `CLServiceSession` usage (iOS 18+) |
+| `NSLocationDefaultAccuracyReduced` | Default to approximate location |
+| `UIBackgroundModes` (includes `location`) | Background location updates |
+
+### Usage Description Best Practices
+
+**Good:** "Shows nearby coffee shops within walking distance so you can find your next stop quickly."
+
+**Bad:** "This app uses your location."
+
+App Review rejects vague usage descriptions. Be specific about what the user
+gains from sharing their location.
+
+---
+
+## Common Pitfalls
+
+### CLMonitor crash on rapid recreation
+
+```swift
+// CRASH -- creating a monitor with a name already in use
+let monitorA = await CLMonitor("myMonitor")
+// ... immediately discard monitorA ...
+let monitorB = await CLMonitor("myMonitor") // NSInternalInconsistencyException
+```
+
+Fix: reuse the existing monitor instance. Only create a new one after the
+old one has been fully torn down (conditions removed, reference released,
+NOT in the same run loop).
+
+### CLLocationUpdate.liveUpdates() returns nothing on iOS 17 without full accuracy
+
+On iOS 17 (not iOS 18+), `liveUpdates()` may return no updates when the user
+has denied full accuracy. This is resolved in iOS 18. Target iOS 18+ or
+fall back to `CLLocationManager` if you need to handle approximate-only
+location on iOS 17.
+
+### Forgetting to hold CLBackgroundActivitySession
+
+```swift
+// WRONG -- session is immediately deallocated
+func startBackground() {
+    let _ = CLBackgroundActivitySession()
+    // ^ No strong reference; session ends immediately
+}
+
+// CORRECT -- hold as a stored property
+private var bgSession: CLBackgroundActivitySession?
+
+func startBackground() {
+    bgSession = CLBackgroundActivitySession()
+}
+```
+
+### Not checking horizontalAccuracy
+
+```swift
+// WRONG -- using location with negative accuracy (invalid)
+guard let location = update.location else { continue }
+updateMap(location) // May have accuracy of -1 (invalid)
+
+// CORRECT
+guard let location = update.location,
+      location.horizontalAccuracy >= 0 else { continue }
+updateMap(location)
+```
+
+A `horizontalAccuracy` of -1 means the coordinate is invalid.
+
+---
+
+## References
+
+- Apple docs: [CLLocationUpdate](https://sosumi.ai/documentation/CoreLocation/CLLocationUpdate)
+- Apple docs: [CLServiceSession](https://sosumi.ai/documentation/CoreLocation/CLServiceSession)
+- Apple docs: [CLMonitor](https://sosumi.ai/documentation/CoreLocation/CLMonitor)
+- Apple docs: [CLBackgroundActivitySession](https://sosumi.ai/documentation/CoreLocation/CLBackgroundActivitySession)
+- Apple docs: [Requesting authorization](https://sosumi.ai/documentation/CoreLocation/requesting-authorization-to-use-location-services)
+- Apple docs: [Handling background location](https://sosumi.ai/documentation/CoreLocation/handling-location-updates-in-the-background)