@devo-bmad-custom/agent-orchestration 1.0.1 → 1.0.3

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

@@ -1,730 +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)
+# 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)