@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/core-motion/references/motion-patterns.md

@@ -1,436 +1,336 @@
-# CoreMotion Extended Patterns
+# Motion patterns
 
-Overflow reference for the `core-motion` skill. Contains advanced patterns that
-exceed the main skill file's scope.
+Companion material for the core-motion skill. Each section is a self-contained
+pattern that goes beyond the basics in [../SKILL.md](../SKILL.md).
 
 ## Contents
 
-- [SwiftUI Integration with `@Observable`](#swiftui-integration-with-observable)
-- [CMBatchedSensorManager (High-Frequency)](#cmbatchedsensormanager-high-frequency)
-- [Headphone Motion](#headphone-motion)
-- [Pedometer SwiftUI View](#pedometer-swiftui-view)
-- [Activity-Based Navigation](#activity-based-navigation)
-- [Water Submersion (watchOS)](#water-submersion-watchos)
+- [A shared @Observable motion service for SwiftUI](#a-shared-observable-motion-service-for-swiftui)
+- [CMBatchedSensorManager for high-rate capture](#cmbatchedsensormanager-for-high-rate-capture)
+- [Head tracking with CMHeadphoneMotionManager](#head-tracking-with-cmheadphonemotionmanager)
+- [A step dashboard](#a-step-dashboard)
+- [Switching app modes from activity](#switching-app-modes-from-activity)
+- [Water submersion on watchOS](#water-submersion-on-watchos)
 
-## SwiftUI Integration with `@Observable`
+## A shared @Observable motion service for SwiftUI
 
-### Motion Manager Service
+Keep the single `CMMotionManager` inside one main-actor service. Views observe
+its published angles and never touch the manager directly.
 
 ```swift
 import CoreMotion
-import SwiftUI
-
-@Observable
-@MainActor
-final class MotionService {
-    static let shared = MotionService()
-
-    private let manager = CMMotionManager()
-
-    var pitch: Double = 0
-    var roll: Double = 0
-    var yaw: Double = 0
-    var userAcceleration: CMAcceleration = CMAcceleration()
-    var isActive = false
-
-    func startDeviceMotion(interval: TimeInterval = 1.0 / 60.0) {
-        guard manager.isDeviceMotionAvailable, !isActive else { return }
-
-        manager.deviceMotionUpdateInterval = interval
-        manager.startDeviceMotionUpdates(
-            using: .xArbitraryZVertical,
-            to: .main
-        ) { [weak self] motion, error in
-            guard let self, let motion else { return }
-            self.pitch = motion.attitude.pitch
-            self.roll = motion.attitude.roll
-            self.yaw = motion.attitude.yaw
-            self.userAcceleration = motion.userAcceleration
+import Observation
+
+@Observable @MainActor
+final class TiltService {
+    static let shared = TiltService()
+
+    private let hardware = CMMotionManager()
+    private(set) var pitch = 0.0
+    private(set) var roll = 0.0
+    private(set) var yaw = 0.0
+    private(set) var push = CMAcceleration()
+    private(set) var isRunning = false
+
+    private init() {}
+
+    func begin(every interval: TimeInterval = 1.0 / 30.0) {
+        guard hardware.isDeviceMotionAvailable, !isRunning else { return }
+        hardware.deviceMotionUpdateInterval = interval
+        hardware.startDeviceMotionUpdates(using: .xArbitraryZVertical, to: .main) { [weak self] sample, _ in
+            guard let sample else { return }
+            MainActor.assumeIsolated {   // the handler runs on OperationQueue.main
+                guard let self else { return }
+                self.pitch = sample.attitude.pitch
+                self.roll = sample.attitude.roll
+                self.yaw = sample.attitude.yaw
+                self.push = sample.userAcceleration
+            }
         }
-        isActive = true
+        isRunning = true
     }
 
-    func stop() {
-        manager.stopDeviceMotionUpdates()
-        isActive = false
+    func end() {
+        hardware.stopDeviceMotionUpdates()
+        isRunning = false
     }
 }
 ```
 
-### SwiftUI View Using Motion
+A bubble level built on it. The surface counts as level while both pitch and
+roll stay under 0.05 radians; 30 Hz is enough for smooth movement.
 
 ```swift
-struct TiltView: View {
-    @State private var motionService = MotionService.shared
-
-    var body: some View {
-        VStack {
-            Circle()
-                .fill(.blue)
-                .frame(width: 60, height: 60)
-                .offset(
-                    x: motionService.roll * 100,
-                    y: motionService.pitch * 100
-                )
-
-            Text("Roll: \(motionService.roll, format: .number.precision(.fractionLength(2)))")
-            Text("Pitch: \(motionService.pitch, format: .number.precision(.fractionLength(2)))")
-        }
-        .onAppear { motionService.startDeviceMotion() }
-        .onDisappear { motionService.stop() }
-    }
-}
-```
-
-### Level Indicator
+import SwiftUI
 
-```swift
-struct LevelIndicator: View {
-    @State private var motionService = MotionService.shared
+struct BubbleLevel: View {
+    private let tilt = TiltService.shared
+    private let tolerance = 0.05
+    private static let angle = FloatingPointFormatStyle<Double>.number.precision(.fractionLength(2))
 
-    private var isLevel: Bool {
-        abs(motionService.pitch) < 0.05 && abs(motionService.roll) < 0.05
+    private var isFlat: Bool {
+        abs(tilt.pitch) < tolerance && abs(tilt.roll) < tolerance
     }
 
     var body: some View {
-        ZStack {
+        VStack(spacing: 24) {
             Circle()
-                .stroke(isLevel ? .green : .gray, lineWidth: 3)
-                .frame(width: 200, height: 200)
-
-            Circle()
-                .fill(isLevel ? .green : .red)
-                .frame(width: 20, height: 20)
-                .offset(
-                    x: motionService.roll * 100,
-                    y: motionService.pitch * -100
-                )
+                .fill(isFlat ? .green : .orange)
+                .frame(width: 44, height: 44)
+                .offset(x: tilt.roll * 120, y: tilt.pitch * 120)
+            Text("Pitch \(tilt.pitch.formatted(Self.angle))")
+            Text("Roll \(tilt.roll.formatted(Self.angle))")
         }
-        .onAppear { motionService.startDeviceMotion(interval: 1.0 / 30.0) }
-        .onDisappear { motionService.stop() }
+        .onAppear { tilt.begin(every: 1.0 / 30.0) }
+        .onDisappear { tilt.end() }
     }
 }
 ```
 
-## CMBatchedSensorManager (High-Frequency)
-
-`CMBatchedSensorManager` delivers batches of high-frequency accelerometer and
-device-motion data for workout-style motion analysis, such as golf swings or bat
-swings. The async update sequences are watchOS 10+ APIs; check availability and
-authorization before starting updates.
+## CMBatchedSensorManager for high-rate capture
 
-### AsyncSequence Pattern
+`CMBatchedSensorManager` hands over accelerometer and device-motion samples in
+batches at a high rate, which suits swing and stroke analysis. The async
+update sequences need watchOS 10 or later. Before starting, confirm
+`CMBatchedSensorManager.isAccelerometerSupported` and that
+`authorizationStatus` is neither `.denied` nor `.restricted`.
 
 ```swift
 import CoreMotion
 
-@Observable
+#if os(watchOS)
+@available(watchOS 10.0, *)
 @MainActor
-final class BatchedMotionService {
-    private let batchedManager = CMBatchedSensorManager()
-    private var updateTask: Task<Void, Never>?
-
-    var latestAcceleration: CMAcceleration?
-
-    func startBatchedAccelerometer() {
-        let authorization = CMBatchedSensorManager.authorizationStatus
-        guard CMBatchedSensorManager.isAccelerometerSupported,
-              authorization != .denied,
-              authorization != .restricted else { return }
-
-        updateTask = Task {
-            for await batch in batchedManager.accelerometerUpdates() {
-                guard !Task.isCancelled else { break }
-                // Process entire batch
-                for sample in batch {
-                    // sample.acceleration, sample.timestamp
-                }
-                // Update UI with most recent
-                if let latest = batch.last {
-                    latestAcceleration = latest.acceleration
+final class SwingRecorder {
+    private let batcher = CMBatchedSensorManager()
+    private var reader: Task<Void, Never>?
+    private(set) var lastSample: CMAccelerometerData?
+
+    func record() {
+        guard CMBatchedSensorManager.isAccelerometerSupported else { return }
+        switch CMBatchedSensorManager.authorizationStatus {
+        case .denied, .restricted: return
+        default: break
+        }
+        reader = Task { [weak self, batcher] in
+            do {
+                for try await chunk in batcher.accelerometerUpdates() {
+                    if Task.isCancelled { break }
+                    for sample in chunk {
+                        _ = (sample.acceleration, sample.timestamp)  // feed the analyzer
+                    }
+                    self?.lastSample = chunk.last
                 }
+            } catch {
+                // surface the stream failure to the UI
             }
         }
     }
 
-    func stop() {
-        updateTask?.cancel()
-        updateTask = nil
-        batchedManager.stopAccelerometerUpdates()
+    func finish() {
+        reader?.cancel()
+        reader = nil
+        batcher.stopAccelerometerUpdates()
     }
 }
+#endif
 ```
 
-### Reading Frequency
-
-```swift
-let batchedManager = CMBatchedSensorManager()
-
-// Start updates, then read the frequency the device reports.
-batchedManager.startAccelerometerUpdates()
-let reportedHz = batchedManager.accelerometerDataFrequency
-```
-
-`accelerometerDataFrequency` and `deviceMotionDataFrequency` are read-only. Do
-not assign them; use the reported values to size buffers, throttle UI updates, or
-downsample processed results.
+To learn the delivered rate, start the stream (for example with
+`startAccelerometerUpdates()`) and then read `accelerometerDataFrequency`;
+`deviceMotionDataFrequency` is the device-motion counterpart. Both are
+read-only. Use the numbers to size ring buffers, throttle what the UI redraws,
+or pick a downsampling factor.
 
-## Headphone Motion
+## Head tracking with CMHeadphoneMotionManager
 
-Track head motion using AirPods Pro / AirPods Max via `CMHeadphoneMotionManager`.
-On iOS and macOS, include `NSMotionUsageDescription`. Use connection-status
-updates when the app needs connect/disconnect events outside an active motion
-session.
+`CMHeadphoneMotionManager` reports head orientation from supported AirPods,
+such as AirPods Pro and AirPods Max. On iOS and macOS the app needs
+`NSMotionUsageDescription`.
 
 ```swift
 import CoreMotion
 
-@Observable
 @MainActor
-final class HeadphoneMotionService: NSObject {
-    private let headphoneManager = CMHeadphoneMotionManager()
-
-    var isConnected = false
-    var headPitch: Double = 0
-    var headYaw: Double = 0
-
-    func start() {
-        guard headphoneManager.isDeviceMotionAvailable else { return }
-
-        headphoneManager.delegate = self
-        headphoneManager.startConnectionStatusUpdates()
-        headphoneManager.startDeviceMotionUpdates(to: .main) { [weak self] motion, error in
-            guard let self, let motion else { return }
-            self.headPitch = motion.attitude.pitch
-            self.headYaw = motion.attitude.yaw
+final class HeadTracker: NSObject, CMHeadphoneMotionManagerDelegate {
+    private let earbuds = CMHeadphoneMotionManager()
+    private(set) var isConnected = false
+
+    func begin() {
+        guard earbuds.isDeviceMotionAvailable else { return }
+        earbuds.delegate = self
+        earbuds.startConnectionStatusUpdates()
+        earbuds.startDeviceMotionUpdates(to: .main) { motion, error in
+            guard let pose = motion?.attitude, error == nil else { return }
+            _ = (pose.pitch, pose.yaw)   // nod and turn
         }
     }
 
-    func stop() {
-        headphoneManager.stopDeviceMotionUpdates()
-        headphoneManager.stopConnectionStatusUpdates()
+    func end() {
+        earbuds.stopDeviceMotionUpdates()
+        earbuds.stopConnectionStatusUpdates()
     }
-}
 
-extension HeadphoneMotionService: CMHeadphoneMotionManagerDelegate {
-    nonisolated func headphoneMotionManagerDidConnect(
-        _ manager: CMHeadphoneMotionManager
-    ) {
-        Task { @MainActor in isConnected = true }
+    nonisolated func headphoneMotionManagerDidConnect(_ source: CMHeadphoneMotionManager) {
+        Task { @MainActor in self.isConnected = true }
     }
 
-    nonisolated func headphoneMotionManagerDidDisconnect(
-        _ manager: CMHeadphoneMotionManager
-    ) {
-        Task { @MainActor in isConnected = false }
+    nonisolated func headphoneMotionManagerDidDisconnect(_ source: CMHeadphoneMotionManager) {
+        Task { @MainActor in self.isConnected = false }
     }
 }
 ```
 
-## Pedometer SwiftUI View
+`startConnectionStatusUpdates()` delivers connect and disconnect callbacks even
+while no motion session is running. Stop both the motion stream and the
+connection updates when finished.
 
-### Step Counter Dashboard
+## A step dashboard
 
 ```swift
 import CoreMotion
+import Observation
 import SwiftUI
 
-@Observable
-@MainActor
-final class PedometerService {
-    private let pedometer = CMPedometer()
-
-    var todaySteps: Int = 0
-    var todayDistance: Double = 0
-    var floorsAscended: Int = 0
+@Observable @MainActor
+final class StepTally {
+    private let counter = CMPedometer()
+    private(set) var steps = 0
+    private(set) var meters = 0.0
+    private(set) var floorsUp = 0
 
-    func fetchToday() {
+    func begin() {
         guard CMPedometer.isStepCountingAvailable() else { return }
+        let midnight = Calendar.current.startOfDay(for: .now)
 
-        let startOfDay = Calendar.current.startOfDay(for: Date())
-
-        pedometer.queryPedometerData(from: startOfDay, to: Date()) { [weak self] data, error in
-            guard let self, let data else { return }
-            Task { @MainActor in
-                self.todaySteps = data.numberOfSteps.intValue
-                self.todayDistance = data.distance?.doubleValue ?? 0
-                self.floorsAscended = data.floorsAscended?.intValue ?? 0
-            }
+        counter.queryPedometerData(from: midnight, to: .now) { data, _ in
+            guard let data else { return }
+            Task { @MainActor in self.apply(data) }
         }
-    }
-
-    func startLiveUpdates() {
-        guard CMPedometer.isStepCountingAvailable() else { return }
-
-        let startOfDay = Calendar.current.startOfDay(for: Date())
-
-        pedometer.startUpdates(from: startOfDay) { [weak self] data, error in
-            guard let self, let data else { return }
-            Task { @MainActor in
-                self.todaySteps = data.numberOfSteps.intValue
-                self.todayDistance = data.distance?.doubleValue ?? 0
-                self.floorsAscended = data.floorsAscended?.intValue ?? 0
-            }
+        counter.startUpdates(from: midnight) { data, _ in
+            guard let data else { return }
+            Task { @MainActor in self.apply(data) }
         }
     }
 
-    func stopLiveUpdates() {
-        pedometer.stopUpdates()
+    func end() { counter.stopUpdates() }
+
+    private func apply(_ data: CMPedometerData) {
+        steps = data.numberOfSteps.intValue
+        meters = data.distance?.doubleValue ?? meters
+        floorsUp = data.floorsAscended?.intValue ?? floorsUp
     }
 }
-```
-
-### SwiftUI Dashboard View
 
-```swift
-struct StepDashboard: View {
-    @State private var pedometerService = PedometerService()
+struct DailyStepsView: View {
+    @State private var tally = StepTally()
 
     var body: some View {
         List {
-            Section("Today") {
-                LabeledContent("Steps") {
-                    Text("\(pedometerService.todaySteps)")
-                }
-                LabeledContent("Distance") {
-                    Text(
-                        Measurement(value: pedometerService.todayDistance, unit: UnitLength.meters),
-                        format: .measurement(width: .abbreviated)
-                    )
-                }
-                if CMPedometer.isFloorCountingAvailable() {
-                    LabeledContent("Floors Climbed") {
-                        Text("\(pedometerService.floorsAscended)")
-                    }
-                }
+            LabeledContent("Steps", value: tally.steps, format: .number)
+            LabeledContent("Distance") {
+                Text(Measurement(value: tally.meters, unit: UnitLength.meters),
+                     format: .measurement(width: .abbreviated))
+            }
+            if CMPedometer.isFloorCountingAvailable() {
+                LabeledContent("Floors climbed", value: tally.floorsUp, format: .number)
             }
         }
-        .onAppear { pedometerService.startLiveUpdates() }
-        .onDisappear { pedometerService.stopLiveUpdates() }
+        .onAppear { tally.begin() }
+        .onDisappear { tally.end() }
     }
 }
 ```
 
-## Activity-Based Navigation
+## Switching app modes from activity
 
-Switch between driving and walking modes automatically:
+A navigation-style app can change its presentation when the user starts
+driving or cycling. Ignore low-confidence readings, check the flags in
+priority order, and keep the current mode while stationary so a red light
+does not flip a driver back to walking.
 
 ```swift
 import CoreMotion
 
-@Observable
-@MainActor
-final class NavigationModeService {
-    private let activityManager = CMMotionActivityManager()
-
-    enum Mode: String {
-        case walking, driving, cycling, unknown
-    }
+enum TravelMode { case walking, cycling, driving }
 
-    var currentMode: Mode = .unknown
+@MainActor
+final class TravelModeDetector {
+    private let classifier = CMMotionActivityManager()
+    private(set) var mode: TravelMode = .walking
 
-    func startMonitoring() {
+    func begin() {
         guard CMMotionActivityManager.isActivityAvailable() else { return }
-
-        activityManager.startActivityUpdates(to: .main) { [weak self] activity in
-            guard let self, let activity,
-                  activity.confidence != .low else { return }
-
-            Task { @MainActor in
-                if activity.automotive {
-                    self.currentMode = .driving
-                } else if activity.cycling {
-                    self.currentMode = .cycling
-                } else if activity.walking || activity.running {
-                    self.currentMode = .walking
-                } else if activity.stationary {
-                    // Keep previous mode when stationary (e.g., at a stoplight)
+        classifier.startActivityUpdates(to: .main) { [weak self] update in
+            guard let update, update.confidence != .low else { return }
+            MainActor.assumeIsolated {
+                guard let self else { return }
+                if update.automotive {
+                    self.mode = .driving
+                } else if update.cycling {
+                    self.mode = .cycling
+                } else if update.running || update.walking {
+                    self.mode = .walking
                 }
+                // stationary: leave mode unchanged
             }
         }
     }
 
-    func stopMonitoring() {
-        activityManager.stopActivityUpdates()
-    }
+    func end() { classifier.stopActivityUpdates() }
 }
 ```
 
-## Water Submersion (watchOS)
+## Water submersion on watchOS
 
-Track water depth and temperature for dive apps on supported Apple Watch
-hardware. Use `waterSubmersionAvailable` rather than hard-coding model checks:
-Apple Watch Ultra supports submersion data, and Apple Watch Series 10 supports
-the Shallow Depth and Pressure capability.
+Decide support with `CMWaterSubmersionManager.waterSubmersionAvailable`, never
+with a model list. Apple Watch Ultra supports submersion, and Apple Watch
+Series 10 supports Shallow Depth and Pressure, so do not describe the feature
+as Ultra-only.
 
-Setup checklist:
+Setup:
 
-- Add `NSMotionUsageDescription`.
-- Add the Shallow Depth and Pressure capability for dives up to 6 meters, or
-  apply for the full Submerged Depth and Pressure entitlement for dives up to
-  40 meters.
-- Add `WKBackgroundModes` with `underwater-depth` so the app can remain
-  frontmost and eligible for dive autolaunch.
-- Check availability before instantiating `CMWaterSubmersionManager`.
+1. Add `NSMotionUsageDescription`.
+2. Choose the capability. Dives no deeper than 6 m are covered by the
+   capability named Shallow Depth and Pressure. Deeper dives, to 40 m, need the Submerged Depth and Pressure
+   entitlement, which requires an application to Apple.
+3. Add `underwater-depth` to `WKBackgroundModes`. That keeps the app frontmost
+   during a dive and makes it eligible to launch automatically on submersion.
+
+Check availability before creating the manager, keep a strong reference to
+it, and assign its `delegate`.
 
 ```swift
 import CoreMotion
 
-@Observable
-@MainActor
-final class DiveService: NSObject {
-    private var submersionManager: CMWaterSubmersionManager?
-
-    var isSubmerged = false
-    var currentDepth: Double?
-    var waterTemperature: Double?
+final class DiveMonitor: NSObject, CMWaterSubmersionManagerDelegate {
+    private var sensor: CMWaterSubmersionManager?
 
-    func start() {
+    func begin() {
         guard CMWaterSubmersionManager.waterSubmersionAvailable else { return }
         let manager = CMWaterSubmersionManager()
         manager.delegate = self
-        submersionManager = manager
+        sensor = manager
     }
-}
 
-extension DiveService: CMWaterSubmersionManagerDelegate {
-    nonisolated func manager(
-        _ manager: CMWaterSubmersionManager,
-        didUpdate event: CMWaterSubmersionEvent
-    ) {
-        Task { @MainActor in
-            isSubmerged = event.state == .submerged
-        }
+    func manager(_ source: CMWaterSubmersionManager, didUpdate event: CMWaterSubmersionEvent) {
+        let underwater = event.state == .submerged
+        _ = underwater
     }
 
-    nonisolated func manager(
-        _ manager: CMWaterSubmersionManager,
-        didUpdate measurement: CMWaterSubmersionMeasurement
-    ) {
-        Task { @MainActor in
-            currentDepth = measurement.depth?.value
-        }
+    func manager(_ source: CMWaterSubmersionManager, didUpdate measurement: CMWaterSubmersionMeasurement) {
+        if let depth = measurement.depth { _ = depth.value }   // meters
     }
 
-    nonisolated func manager(
-        _ manager: CMWaterSubmersionManager,
-        didUpdate temperature: CMWaterTemperature
-    ) {
-        Task { @MainActor in
-            waterTemperature = temperature.temperature.value
-        }
+    func manager(_ source: CMWaterSubmersionManager, didUpdate measurement: CMWaterTemperature) {
+        _ = measurement.temperature.value
     }
 
-    nonisolated func manager(
-        _ manager: CMWaterSubmersionManager,
-        errorOccurred error: any Error
-    ) {
-        print("Submersion error: \(error)")
+    func manager(_ source: CMWaterSubmersionManager, errorOccurred error: any Error) {
+        // CMError.notEntitled arrives here when the capability is missing
     }
 }
 ```
 
-**Important:** `CMWaterSubmersionManager` requires the
-Shallow Depth and Pressure capability or the full Submerged Depth and Pressure
-entitlement. If the app lacks the entitlement, the delegate receives
-`CMError.notEntitled` and no submersion data.
+An app that lacks the capability or entitlement gets `CMError.notEntitled` in
+`manager(_:errorOccurred:)` and no depth data.