watchOS: App Structure, Connectivity, Workouts and the Smart Stack

<!-- FieldNotesWatch/Info.plist (excerpt) -->
<key>WKApplication</key>
<true/>
<key>WKCompanionAppBundleIdentifier</key>
<string>com.example.fieldnotes</string>
<key>WKRunsIndependentlyOfCompanionApp</key>
<true/>
<key>WKBackgroundModes</key>
<array>
    <string>workout-processing</string>
    <string>mindfulness</string>
</array>

// FieldNotesWatch/FieldNotesWatchApp.swift (updated)
import SwiftUI
import WatchKit
import FieldNotesServices

@main
struct FieldNotesWatchApp: App {
    @WKApplicationDelegateAdaptor private var delegate: WatchAppDelegate
    // The same instance that WatchAppDelegate and WatchConnectivityBridge reach through AppServices.shared.
    @State private var store = AppServices.shared.store

    var body: some Scene {
        WindowGroup {
            WatchRootView()
                .environment(store)
                .environment(WatchConnectivityBridge.shared)
                .task { await store.load() }
        }

        WKNotificationScene(controller: NoteReminderNotificationController.self,
                            category: NoteReminderScheduler.categoryIdentifier)
    }
}

// FieldNotesWatch/WatchAppDelegate.swift (updated: the delegate from App Structure and Life Cycle)
import WatchKit
import OSLog
import FieldNotesServices

final class WatchAppDelegate: NSObject, WKApplicationDelegate {
    private let log = Logger(subsystem: "com.example.fieldnotes", category: "sync")

    func applicationDidFinishLaunching() {
        // First: a background launch may exist only to deliver WatchConnectivity data.
        WatchConnectivityBridge.shared.activate()
        NoteReminderScheduler().registerCategories()   // the long look shows the Done and Snooze buttons
        RefreshScheduler.scheduleNext()
    }

    func handle(_ backgroundTasks: Set<WKRefreshBackgroundTask>) {
        for task in backgroundTasks {
            switch task {
            case let connectivity as WKWatchConnectivityRefreshBackgroundTask:
                // Completed by the bridge when WCSession has nothing more to deliver.
                WatchConnectivityBridge.shared.hold(connectivity)
            case let refresh as WKApplicationRefreshBackgroundTask:
                RefreshScheduler.scheduleNext()   // keep the chain going even if this run fails
                Task {
                    do {
                        try await AppServices.shared.store.refresh()
                    } catch {
                        log.error("Background refresh failed: \(error.localizedDescription)")
                    }
                    refresh.setTaskCompletedWithSnapshot(false)
                }
            default:
                task.setTaskCompletedWithSnapshot(false)
            }
        }
    }
}

// FieldNotesWatch/WatchRootView.swift
import SwiftUI

struct WatchRootView: View {
    enum Page: Hashable { case notes, capture, fieldTrip, observe }
    @State private var page: Page = .notes

    var body: some View {
        TabView(selection: $page) {
            NavigationStack {
                WatchNoteList()
            }
            .tag(Page.notes)

            WatchCapturePage()
                .containerBackground(.blue.gradient, for: .tabView)
                .tag(Page.capture)

            FieldTripView()              // from Health, Motion and Accessories
                .containerBackground(.green.gradient, for: .tabView)
                .tag(Page.fieldTrip)

            QuietObservationPage()
                .containerBackground(.teal.gradient, for: .tabView)
                .tag(Page.observe)
        }
        .tabViewStyle(.verticalPage)
    }
}

// FieldNotesWatch/WatchNoteList.swift (updated excerpt)
List(store.notes.sorted { $0.isPinned && !$1.isPinned }) { note in
    NavigationLink(value: note.id) {
        Label(note.title, systemImage: note.isPinned ? "pin.fill" : "note.text")
    }
}
.navigationTitle("FieldNotes")
.navigationDestination(for: Note.ID.self) { noteID in
    WatchNoteDetail(noteID: noteID)
}

// FieldNotesWatch/WatchNoteDetail.swift
import SwiftUI
import WatchKit
import FieldNotesModel
import FieldNotesServices

struct WatchNoteDetail: View {
    @Environment(NoteStore.self) private var store
    let noteID: Note.ID
    @State private var minutes = 30.0
    @State private var status: String?

    var body: some View {
        if let note = store.notes.first(where: { $0.id == noteID }) {
            ScrollView {
                VStack(alignment: .leading, spacing: 8) {
                    WatchNotePhoto(noteID: note.id)
                    Text(note.body)
                        .privacySensitive()            // blurred in Always On, see below
                    Divider()
                    Text("Remind me in \(Int(minutes)) min")
                        .focusable()
                        .digitalCrownRotation($minutes, from: 5, through: 120, by: 5,
                                              sensitivity: .low, isContinuous: false,
                                              isHapticFeedbackEnabled: true)
                    Button("Remind Me", systemImage: "bell") {
                        Task { await remind(note) }
                    }
                    .handGestureShortcut(.primaryAction)
                    if let status {
                        Text(status).font(.footnote).foregroundStyle(.secondary)
                    }
                }
            }
            .navigationTitle(note.title)
        } else {
            ContentUnavailableView("Note Removed", systemImage: "note.text")
        }
    }

    private func remind(_ note: Note) async {
        do {
            try await NoteReminderScheduler().scheduleReminder(for: note, at: .now.addingTimeInterval(minutes * 60))
            status = "Reminder set"
            WKInterfaceDevice.current().play(.success)
        } catch {
            status = error.localizedDescription
        }
    }
}

// FieldNotesWatch/QuietObservationPage.swift
import SwiftUI
import WatchKit

struct QuietObservationPage: View {
    @Environment(\.isLuminanceReduced) private var isLuminanceReduced
    @State private var timer = ObservationTimer()
    @State private var interval: ClosedRange<Date>?

    var body: some View {
        VStack(spacing: 8) {
            if let interval {
                Text(timerInterval: interval, showsHours: false)   // counts down in Always On too
                    .font(isLuminanceReduced ? .title2 : .system(.largeTitle, design: .rounded))
                    .foregroundStyle(isLuminanceReduced ? .secondary : .primary)
                    .monospacedDigit()
                Button("Stop", systemImage: "stop.fill", role: .destructive) { stop() }
            } else {
                Button { start() } label: {
                    ViewThatFits(in: .horizontal) {          // a full label on large cases, the icon on small ones
                        Label("Quiet Observation", systemImage: "leaf")
                        Image(systemName: "leaf")
                    }
                }
            }
        }
        .task(id: interval) {
            guard let interval else { return }
            do {
                try await Task.sleep(until: .now + .seconds(interval.upperBound.timeIntervalSinceNow))
            } catch {
                return   // cancelled because the person stopped early
            }
            stop()
            WKInterfaceDevice.current().play(.success)
        }
    }

    private func start() {
        timer.start()                                   // WKExtendedRuntimeSession, mindfulness type
        interval = Date.now...Date.now.addingTimeInterval(10 * 60)
    }

    private func stop() {
        timer.stop()
        interval = nil
    }
}

// FieldNotesWatch/NoteReminderNotificationController.swift
import SwiftUI
import UserNotifications
import WatchKit

final class NoteReminderNotificationController: WKUserNotificationHostingController<NoteReminderLongLook> {
    private var title = ""
    private var bodyText = ""

    override var body: NoteReminderLongLook {
        NoteReminderLongLook(title: title, bodyText: bodyText)
    }

    override func didReceive(_ notification: UNNotification) {
        title = notification.request.content.title
        bodyText = notification.request.content.body
    }
}

struct NoteReminderLongLook: View {
    let title: String
    let bodyText: String

    var body: some View {
        VStack(alignment: .leading, spacing: 4) {
            Label(title, systemImage: "note.text").font(.headline)
            Text(bodyText).font(.body).privacySensitive()
        }
    }
}

// Shared/WatchConnectivityBridge.swift (target membership: FieldNotes, FieldNotesWatch)
#if os(iOS) || os(watchOS)
import Foundation
import Observation
import OSLog
import WatchConnectivity
import FieldNotesModel
import FieldNotesServices
#if os(watchOS)
import WatchKit
import WidgetKit
#endif

/// A note on its way from the watch to iPhone.
nonisolated struct WatchNotePayload: Codable, Identifiable, Sendable {
    var id = UUID()
    var title: String
    var body: String
    var createdAt = Date.now

    var note: Note { Note(id: id, title: title, body: body, createdAt: createdAt, tags: ["watch"]) }
}

@Observable
@MainActor
final class WatchConnectivityBridge: NSObject, WCSessionDelegate {
    static let shared = WatchConnectivityBridge()

    /// The keys of the dictionaries FieldNotes exchanges.
    nonisolated enum Key {
        static let quickNote = "quickNote"            // sendMessage
        static let noteTransfer = "noteTransfer"      // transferUserInfo
        static let pinnedNoteIDs = "pinnedNoteIDs"    // updateApplicationContext
        static let nextFieldTrip = "nextFieldTrip"    // updateApplicationContext, same dictionary
        static let noteID = "noteID"                  // transferFile metadata
    }

    private(set) var isActivated = false
    private(set) var isReachable = false
    /// Watch: quick notes that iPhone hasn't confirmed yet.
    private(set) var pendingCaptures: [WatchNotePayload] = []
    /// Watch: bumped when a new photo arrives, so photo views reload.
    private(set) var photoRevision = 0

    @ObservationIgnored private var unsentCaptures: [WatchNotePayload] = []
    #if os(watchOS)
    @ObservationIgnored private var backgroundTasks: [WKWatchConnectivityRefreshBackgroundTask] = []
    @ObservationIgnored private var pendingContentObservation: NSKeyValueObservation?
    @ObservationIgnored private var activationFinished = false
    @ObservationIgnored private var updatesInFlight = 0
    #endif

    nonisolated static let log = Logger(subsystem: "com.example.fieldnotes", category: "sync")

    /// Call once, as early as possible in every launch, including background launches.
    func activate() {
        guard WCSession.isSupported() else { return }   // false on iPad: there is no paired watch
        WCSession.default.delegate = self
        WCSession.default.activate()
    }

    nonisolated func session(_ session: WCSession,
                             activationDidCompleteWith activationState: WCSessionActivationState,
                             error: (any Error)?) {
        if let error {
            Self.log.error("WCSession activation failed: \(error.localizedDescription)")
        }
        let activated = activationState == .activated
        #if os(watchOS)
        // A context that arrived while the app wasn't running is waiting here.
        let context = Self.decodeContext(session.receivedApplicationContext)
        #endif
        Task { @MainActor in
            self.isActivated = activated
            #if os(watchOS)
            self.activationFinished = true
            self.flushUnsentCaptures()                  // captures made while activation was pending
            if activated, let context { await self.apply(context) }
            self.completeBackgroundTasksIfIdle()
            #else
            if activated { self.publishContext() }
            #endif
        }
    }

    nonisolated func sessionReachabilityDidChange(_ session: WCSession) {
        let reachable = session.isReachable
        Task { @MainActor in self.isReachable = reachable }
    }

    #if os(iOS)
    nonisolated func sessionDidBecomeInactive(_ session: WCSession) {}

    nonisolated func sessionDidDeactivate(_ session: WCSession) {
        // The person switched to another Apple Watch: activate again to talk to the new one.
        WCSession.default.activate()
    }
    #endif
}
#endif

// FieldNotes/iOS/FieldNotesAppDelegate.swift (updated excerpt: the delegate from Notifications and Live Activities)
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
    UNUserNotificationCenter.current().delegate = notificationDelegate
    NoteReminderScheduler().registerCategories()
    Task { try? await NoteReminderScheduler().requestAuthorization(provisional: true) }
    application.registerForRemoteNotifications()
    #if os(iOS)
    WatchConnectivityBridge.shared.activate()                  // messages and transfers from the watch
    FieldTripWorkoutSession.companion.listenForMirroredSessions()  // hikes started on the watch (below)
    #endif
    return true
}

// Shared/WatchConnectivityBridge.swift (continued)
#if os(watchOS)
extension WatchConnectivityBridge {
    func capture(title: String, body: String = "") {
        let payload = WatchNotePayload(title: title, body: body)
        guard WCSession.isSupported() else {
            AppServices.shared.store.add(payload.note)   // no WatchConnectivity: the watch is the writer
            return
        }
        guard WCSession.default.activationState == .activated else {
            // isCompanionAppInstalled reads false until activation completes, so don't decide yet.
            unsentCaptures.append(payload)               // routed from activationDidCompleteWith
            return
        }
        route(payload)
    }

    /// Called from activationDidCompleteWith, whatever the outcome.
    fileprivate func flushUnsentCaptures() {
        let captures = unsentCaptures
        unsentCaptures.removeAll()
        captures.forEach(route)
    }

    /// Decides who writes the note, once the session state is known.
    private func route(_ payload: WatchNotePayload) {
        let session = WCSession.default
        guard session.activationState == .activated, session.isCompanionAppInstalled else {
            AppServices.shared.store.add(payload.note)   // no iPhone app (or no session): the watch is the writer
            return
        }
        pendingCaptures.append(payload)
        send(payload)
    }

    private func send(_ payload: WatchNotePayload) {
        let data: Data
        do {
            data = try PropertyListEncoder().encode(payload)
        } catch {
            Self.log.error("Could not encode a quick note: \(error.localizedDescription)")
            return
        }
        let session = WCSession.default
        guard session.isReachable else {
            session.transferUserInfo([Key.noteTransfer: data])   // queued until iPhone can take it
            return
        }
        session.sendMessage([Key.quickNote: data], replyHandler: { @Sendable reply in
            let received = reply["received"] as? Bool ?? false
            Task { @MainActor in
                if received { self.confirm(payload.id) }
            }
        }, errorHandler: { @Sendable error in
            // Not delivered in time (for example, iPhone went out of range): queue it instead.
            Self.log.notice("Quick note message failed, queuing it: \(error.localizedDescription)")
            WCSession.default.transferUserInfo([Key.noteTransfer: data])
        })
    }

    fileprivate func confirm(_ id: WatchNotePayload.ID) {
        pendingCaptures.removeAll { $0.id == id }
    }
}
#endif

extension WatchConnectivityBridge {
    nonisolated func session(_ session: WCSession, didFinish userInfoTransfer: WCSessionUserInfoTransfer,
                             error: (any Error)?) {
        if let error {
            Self.log.error("A queued transfer failed: \(error.localizedDescription)")
            return
        }
        #if os(watchOS)
        guard let payload = Self.decodePayload(userInfoTransfer.userInfo[Key.noteTransfer]) else { return }
        Task { @MainActor in self.confirm(payload.id) }   // delivered to iPhone
        #endif
    }

    nonisolated static func decodePayload(_ value: Any?) -> WatchNotePayload? {
        guard let data = value as? Data else { return nil }
        do {
            return try PropertyListDecoder().decode(WatchNotePayload.self, from: data)
        } catch {
            log.error("Could not decode a quick note: \(error.localizedDescription)")
            return nil
        }
    }
}

// Shared/WatchConnectivityBridge.swift (continued)
extension WatchConnectivityBridge {
    nonisolated func session(_ session: WCSession, didReceiveMessage message: [String: Any],
                             replyHandler: @escaping ([String: Any]) -> Void) {
        let payload = Self.decodePayload(message[Key.quickNote])
        replyHandler(["received": payload != nil])
        #if os(iOS)
        if let payload { Task { @MainActor in await self.save(payload) } }
        #endif
    }

    nonisolated func session(_ session: WCSession, didReceiveUserInfo userInfo: [String: Any]) {
        #if os(iOS)
        guard let payload = Self.decodePayload(userInfo[Key.noteTransfer]) else { return }
        Task { @MainActor in await self.save(payload) }
        #endif
    }

    #if os(iOS)
    private func save(_ payload: WatchNotePayload) async {
        let store = AppServices.shared.store
        if store.notes.isEmpty {
            await store.load()          // a cold background launch: read the library first
        }
        guard !store.notes.contains(where: { $0.id == payload.id }) else { return }
        store.add(payload.note)
        await store.waitForPendingWrites()
    }
    #endif
}

// FieldNotesWatch/WatchCapturePage.swift
import SwiftUI

struct WatchCapturePage: View {
    @Environment(WatchConnectivityBridge.self) private var bridge
    @State private var text = ""

    var body: some View {
        List {
            TextField("Dictate a note", text: $text)     // dictation, Scribble or the keyboard
                .onSubmit { Task { await capture() } }
            if !bridge.pendingCaptures.isEmpty {
                Section("Sending to iPhone") {
                    ForEach(bridge.pendingCaptures) { payload in
                        Label(payload.title, systemImage: "clock")
                    }
                }
            }
        }
    }

    private func capture() async {
        let dictation = text.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !dictation.isEmpty else { return }
        text = ""
        var title = String(dictation.prefix(40))
        #if canImport(FoundationModels)
        if #available(watchOS 27, *), let suggested = await WatchTitleSuggester.title(for: dictation) {
            title = suggested                            // new in watchOS 27, see the last section
        }
        #endif
        bridge.capture(title: title, body: dictation)
    }
}

// Shared/WatchConnectivityBridge.swift (continued)
extension WatchConnectivityBridge {
    #if os(iOS)
    /// iPhone: sends the current pinned list and the next field trip. Cheap to call on every change.
    func publishContext() {
        let session = WCSession.default
        guard session.activationState == .activated, session.isPaired, session.isWatchAppInstalled else { return }
        let pinned = AppServices.shared.store.notes.filter(\.isPinned).map(\.id.uuidString)
        var context: [String: Any] = [Key.pinnedNoteIDs: pinned]
        do {
            if let trip = NextFieldTripSnapshot.load() {
                context[Key.nextFieldTrip] = try JSONEncoder().encode(trip)
            }
            try session.updateApplicationContext(context)
        } catch {
            Self.log.error("Could not update the watch's context: \(error.localizedDescription)")
        }
    }
    #endif

    nonisolated func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
        #if os(watchOS)
        guard let context = Self.decodeContext(applicationContext) else { return }
        Task { @MainActor in await self.apply(context) }
        #endif
    }

    #if os(watchOS)
    nonisolated struct WatchContext: Sendable {
        var pinnedIDs: Set<Note.ID>
        var nextTrip: NextFieldTripSnapshot?
    }

    nonisolated static func decodeContext(_ dictionary: [String: Any]) -> WatchContext? {
        guard let raw = dictionary[Key.pinnedNoteIDs] as? [String] else { return nil }   // empty before the first update
        var nextTrip: NextFieldTripSnapshot?
        if let data = dictionary[Key.nextFieldTrip] as? Data {
            do {
                nextTrip = try JSONDecoder().decode(NextFieldTripSnapshot.self, from: data)
            } catch {
                log.error("Could not decode the next field trip: \(error.localizedDescription)")
            }
        }
        return WatchContext(pinnedIDs: Set(raw.compactMap(UUID.init(uuidString:))), nextTrip: nextTrip)
    }

    /// Watch: applies the pins to the local store, stores the next trip for the complication, reloads widgets.
    fileprivate func apply(_ context: WatchContext) async {
        updatesInFlight += 1
        defer {
            updatesInFlight -= 1
            completeBackgroundTasksIfIdle()
        }
        if let trip = context.nextTrip { trip.save() } else { NextFieldTripSnapshot.clear() }

        let store = AppServices.shared.store
        if store.notes.isEmpty { await store.load() }
        for note in store.notes where note.isPinned != context.pinnedIDs.contains(note.id) {
            store.togglePin(note)       // notes not synced yet arrive later from CloudKit, already pinned
        }
        await store.waitForPendingWrites()
        WidgetCenter.shared.reloadTimelines(ofKind: SharedNoteAccess.pinnedNotesWidgetKind)
        WidgetCenter.shared.reloadTimelines(ofKind: NextFieldTripSnapshot.widgetKind)
    }
    #endif
}

// FieldNotes/FieldNotesApp.swift (excerpt: the iOS main window)
WindowGroup {
    ContentView()
        .environment(store)
        #if os(iOS)
        .onChange(of: store.notes.filter(\.isPinned).map(\.id)) {
            WatchConnectivityBridge.shared.publishContext()
        }
        #endif
}

// Shared/WatchConnectivityBridge.swift (continued)
extension WatchConnectivityBridge {
    #if os(iOS)
    /// iPhone: sends a JPEG thumbnail (a few hundred pixels wide) for a pinned note.
    func sendPhoto(_ fileURL: URL, for noteID: Note.ID) {
        guard WCSession.default.activationState == .activated else { return }
        WCSession.default.transferFile(fileURL, metadata: [Key.noteID: noteID.uuidString])
    }
    #endif

    nonisolated static func photoURL(for noteID: Note.ID) -> URL {
        let group = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: "group.com.example.fieldnotes")
            ?? URL.cachesDirectory
        return group.appending(path: "WatchPhotos/\(noteID.uuidString).jpg")
    }

    nonisolated func session(_ session: WCSession, didReceive file: WCSessionFile) {
        guard let raw = file.metadata?[Key.noteID] as? String, let noteID = UUID(uuidString: raw) else { return }
        let destination = Self.photoURL(for: noteID)
        let files = FileManager.default
        do {
            try files.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)
            if files.fileExists(atPath: destination.path(percentEncoded: false)) {
                try files.removeItem(at: destination)
            }
            try files.moveItem(at: file.fileURL, to: destination)   // before returning: the system deletes it
        } catch {
            Self.log.error("Could not keep a received photo: \(error.localizedDescription)")
            return
        }
        Task { @MainActor in self.photoRevision += 1 }
    }
}

// Shared/WatchConnectivityBridge.swift (continued)
#if os(watchOS)
extension WatchConnectivityBridge {
    func hold(_ task: WKWatchConnectivityRefreshBackgroundTask) {
        backgroundTasks.append(task)
        if pendingContentObservation == nil {
            pendingContentObservation = WCSession.default.observe(\.hasContentPending) { @Sendable [weak self] _, _ in
                Task { @MainActor in self?.completeBackgroundTasksIfIdle() }
            }
        }
        completeBackgroundTasksIfIdle()
    }

    fileprivate func completeBackgroundTasksIfIdle() {
        let session = WCSession.default
        let delivered = session.activationState == .activated ? !session.hasContentPending : activationFinished
        guard delivered, updatesInFlight == 0, !backgroundTasks.isEmpty else { return }
        backgroundTasks.forEach { $0.setTaskCompletedWithSnapshot(false) }
        backgroundTasks.removeAll()
    }
}
#endif

// FieldNotes/Health/FieldTripWorkoutSession.swift (updated: mirroring between Apple Watch and iPhone)
#if os(iOS) || os(watchOS)
import HealthKit
import OSLog

/// The live numbers the watch sends to iPhone while a mirrored hike runs.
nonisolated struct MirroredFieldTripStats: Codable, Sendable {
    var distanceMeters: Double
    var activeKilocalories: Double
    var heartRate: Double?
}

extension FieldTripWorkoutSession {
    nonisolated private static let mirrorLog = Logger(subsystem: "com.example.fieldnotes", category: "sync")

    #if os(watchOS)
    /// Watch: called at the end of start(). iPhone receives a mirrored session.
    func mirrorToPhone() async {
        guard let session else { return }
        do {
            try await session.startMirroringToCompanionDevice()
        } catch {
            // No iPhone nearby, or FieldNotes isn't installed there: the hike still records on the watch.
            Self.mirrorLog.notice("Mirroring unavailable: \(error.localizedDescription)")
        }
    }

    /// Watch: sends the latest numbers to the mirrored session.
    func sendStatsToPhone() {
        guard let session, session.type == .primary else { return }
        let stats = MirroredFieldTripStats(distanceMeters: distanceMeters,
                                           activeKilocalories: activeKilocalories, heartRate: heartRate)
        Task {
            do {
                try await session.sendToRemoteWorkoutSession(data: JSONEncoder().encode(stats))
            } catch {
                Self.mirrorLog.notice("Could not send stats to iPhone: \(error.localizedDescription)")
            }
        }
    }
    #endif

    #if os(iOS)
    /// iPhone: the one instance that adopts sessions the watch mirrors. It lives for the whole process.
    static let companion = FieldTripWorkoutSession()

    /// iPhone: set at every launch, before didFinishLaunching returns.
    func listenForMirroredSessions() {
        healthStore.workoutSessionMirroringStartHandler = { [weak self] mirrored in
            Task { @MainActor in self?.adopt(mirrored) }
        }
    }

    private func adopt(_ mirrored: HKWorkoutSession) {
        mirrored.delegate = self
        session = mirrored
        state = .running
    }
    #endif
}

// In start() (updated excerpt), after `try await builder.beginCollection(at: startDate)`:
//     #if os(watchOS)
//     await mirrorToPhone()
//     #endif
//
// In workoutBuilder(_:didCollectDataOf:) (updated excerpt), at the end of its main-actor Task:
//     #if os(watchOS)
//     self.sendStatsToPhone()
//     #endif

// The existing HKWorkoutSessionDelegate conformance from page 32 already covers this type; these two methods
// are added to it here, so the extension below doesn't restate `: HKWorkoutSessionDelegate` (Swift rejects a
// second conformance declaration for the same protocol on the same type).
extension FieldTripWorkoutSession {
    // workoutSession(_:didChangeTo:from:date:) and workoutSession(_:didFailWithError:) as before.

    nonisolated func workoutSession(_ workoutSession: HKWorkoutSession,
                                    didReceiveDataFromRemoteWorkoutSession data: [Data]) {
        guard let latest = data.last else { return }
        let stats: MirroredFieldTripStats
        do {
            stats = try JSONDecoder().decode(MirroredFieldTripStats.self, from: latest)
        } catch {
            Self.mirrorLog.error("Unreadable stats from the watch: \(error.localizedDescription)")
            return
        }
        Task { @MainActor in
            self.distanceMeters = stats.distanceMeters
            self.activeKilocalories = stats.activeKilocalories
            self.heartRate = stats.heartRate
        }
    }

    nonisolated func workoutSession(_ workoutSession: HKWorkoutSession,
                                    didDisconnectFromRemoteDeviceWithError error: (any Error)?) {
        Task { @MainActor in self.state = .ended }
    }
}
#endif

// FieldNotes/Health/FieldTripPlanner.swift
#if os(iOS)
import Foundation
import HealthKit
import WorkoutKit

@MainActor
enum FieldTripPlanner {
    /// Schedules a hike in the Workout app on Apple Watch and tells the FieldNotes watch app about it.
    static func schedule(on date: Date, distanceKilometers: Double) async -> Bool {
        guard WorkoutScheduler.isSupported else { return false }
        let scheduler = WorkoutScheduler.shared
        guard await scheduler.requestAuthorization() == .authorized else { return false }

        let hike = SingleGoalWorkout(activity: .hiking, location: .outdoor,
                                     goal: .distance(distanceKilometers, .kilometers))
        let components = Calendar.current.dateComponents([.year, .month, .day, .hour, .minute], from: date)
        await scheduler.schedule(WorkoutPlan(.goal(hike)), at: components)

        NextFieldTripSnapshot(date: date, distanceKilometers: distanceKilometers).save()
        WatchConnectivityBridge.shared.publishContext()
        return true
    }
}
#endif

// Shared/NextFieldTripSnapshot.swift (target membership: FieldNotes, FieldNotesWatch, FieldNotesWatchWidgets)
import Foundation
import OSLog
import FieldNotesServices

nonisolated struct NextFieldTripSnapshot: Codable, Sendable {
    static let widgetKind = "NextFieldTripComplication"
    private static let key = "nextFieldTrip"
    private static let log = Logger(subsystem: "com.example.fieldnotes", category: "ui")

    var date: Date
    var distanceKilometers: Double?

    static func load() -> NextFieldTripSnapshot? {
        guard let data = UserDefaults.fieldNotesShared.data(forKey: key) else { return nil }
        do {
            return try JSONDecoder().decode(Self.self, from: data)
        } catch {
            log.error("Unreadable next field trip: \(error.localizedDescription)")
            return nil
        }
    }

    func save() {
        do {
            UserDefaults.fieldNotesShared.set(try JSONEncoder().encode(self), forKey: Self.key)
        } catch {
            Self.log.error("Could not store the next field trip: \(error.localizedDescription)")
        }
    }

    static func clear() {
        UserDefaults.fieldNotesShared.removeObject(forKey: key)
    }
}

// FieldNotesWatchWidgets/NextFieldTripComplication.swift
#if os(watchOS)
import SwiftUI
import WidgetKit

struct NextFieldTripEntry: TimelineEntry {
    let date: Date
    let trip: NextFieldTripSnapshot?
    var relevance: TimelineEntryRelevance?
}

struct NextFieldTripProvider: TimelineProvider {
    func placeholder(in context: Context) -> NextFieldTripEntry {
        NextFieldTripEntry(date: .now, trip: NextFieldTripSnapshot(date: .now.addingTimeInterval(86_400),
                                                                   distanceKilometers: 8))
    }

    func getSnapshot(in context: Context, completion: @escaping @Sendable (NextFieldTripEntry) -> Void) {
        completion(context.isPreview ? placeholder(in: context)
                                     : NextFieldTripEntry(date: .now, trip: NextFieldTripSnapshot.load()))
    }

    func getTimeline(in context: Context, completion: @escaping @Sendable (Timeline<NextFieldTripEntry>) -> Void) {
        let now = Date.now
        guard let trip = NextFieldTripSnapshot.load(), trip.date > now else {
            // The watch app reloads this kind when a new trip arrives.
            completion(Timeline(entries: [NextFieldTripEntry(date: now, trip: nil)], policy: .never))
            return
        }
        var entries = [NextFieldTripEntry(date: now, trip: trip, relevance: TimelineEntryRelevance(score: 10))]
        let leadTime = trip.date.addingTimeInterval(-3 * 3600)
        if leadTime > now {
            entries.append(NextFieldTripEntry(date: leadTime, trip: trip,
                                              relevance: TimelineEntryRelevance(score: 80, duration: 3 * 3600)))
        }
        completion(Timeline(entries: entries, policy: .after(trip.date)))
    }
}

struct NextFieldTripComplication: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: NextFieldTripSnapshot.widgetKind, provider: NextFieldTripProvider()) { entry in
            NextFieldTripView(entry: entry)
                .containerBackground(.fill.tertiary, for: .widget)
        }
        .configurationDisplayName("Next Field Trip")
        .description("When your next planned field trip starts.")
        .supportedFamilies([.accessoryCircular, .accessoryRectangular, .accessoryInline, .accessoryCorner])
    }
}

struct NextFieldTripView: View {
    @Environment(\.widgetFamily) private var family
    let entry: NextFieldTripEntry

    var body: some View {
        if let trip = entry.trip {
            switch family {
            case .accessoryCircular:
                VStack(spacing: 0) {
                    Image(systemName: "figure.hiking")
                    Text(trip.date, format: .dateTime.weekday(.abbreviated))
                }
            case .accessoryCorner:
                Image(systemName: "figure.hiking")
                    .font(.title2)
                    .widgetLabel { Text(trip.date, style: .relative) }   // curved along the dial
            case .accessoryInline:
                Label { Text(trip.date, style: .relative) } icon: { Image(systemName: "figure.hiking") }
            default:
                VStack(alignment: .leading) {
                    Text("Next field trip").font(.headline).widgetAccentable()
                    Text(trip.date, format: .dateTime.weekday(.wide).hour().minute())
                    if let kilometers = trip.distanceKilometers {
                        Text("\(kilometers, format: .number.precision(.fractionLength(1))) km")
                    }
                }
            }
        } else {
            Image(systemName: "figure.hiking")
                .widgetLabel("No trip planned")
        }
    }
}
#endif

// FieldNotesWatchWidgets/FieldNotesWatchWidgetBundle.swift (updated)
#if os(watchOS)
import WidgetKit
import SwiftUI

@main
struct FieldNotesWatchWidgetBundle: WidgetBundle {
    var body: some Widget {
        PinnedNotesWidget()
        FieldTripRelevanceWidget()
        NextFieldTripComplication()
        QuickCaptureControl()            // controls: watchOS 26+
    }
}
#endif

// FieldNotesWidgets/FieldTripLiveActivity.swift (excerpt, from Notifications and Live Activities)
ActivityConfiguration(for: FieldTripAttributes.self) { context in
    FieldTripLockScreenView(context: context)       // switches on activityFamily: .small on the watch
} dynamicIsland: { context in
    FieldTripDynamicIsland.make(context)
}
.supplementalActivityFamilies([.small])

// FieldNotesWatch/Legacy/ComplicationController.swift (kept for one release, for migration only)
@preconcurrency import ClockKit   // ClockKit predates Swift 6 concurrency: its types aren't Sendable

final class ComplicationController: NSObject, CLKComplicationDataSource, CLKComplicationWidgetMigrator {
    var widgetMigrator: any CLKComplicationWidgetMigrator { self }

    func widgetConfiguration(from complicationDescriptor: CLKComplicationDescriptor) async
        -> CLKComplicationWidgetMigrationConfiguration? {
        guard complicationDescriptor.identifier == "nextTrip" else { return nil }
        return CLKComplicationStaticWidgetMigrationConfiguration(
            kind: NextFieldTripSnapshot.widgetKind,
            extensionBundleIdentifier: "com.example.fieldnotes.watchkitapp.widgets")
    }

    // The ClockKit timeline methods are no longer called once the widget extension ships.
    func currentTimelineEntry(for complication: CLKComplication) async -> CLKComplicationTimelineEntry? { nil }
}

// FieldNotesWatch/WatchTitleSuggester.swift
#if canImport(FoundationModels)
import FoundationModels
import OSLog

@available(watchOS 27, *)
enum WatchTitleSuggester {
    /// A title of a few words for dictated text, or nil when Private Cloud Compute can't answer.
    @MainActor
    static func title(for dictation: String) async -> String? {
        let model = PrivateCloudComputeLanguageModel()
        guard case .available = model.availability, !model.quotaUsage.isLimitReached else { return nil }
        let session = LanguageModelSession(model: model, dynamicInstructions: Instructions {
            "Write a title of at most six words for this field note. Reply with the title only."
        })
        do {
            return try await session.respond(to: Prompt { dictation }).content
        } catch {
            Logger(subsystem: "com.example.fieldnotes", category: "intents")
                .notice("No title suggestion: \(error.localizedDescription)")
            return nil          // offline or over quota: the caller keeps the first words
        }
    }
}
#endif

// FieldNotesWatch/WatchPhotoLabeler.swift
#if canImport(Vision)
import Vision
import OSLog

@available(watchOS 27, *)
enum WatchPhotoLabeler {
    /// The most confident label for a thumbnail, such as "bird", or nil.
    static func label(forPhotoAt url: URL) async -> String? {
        do {
            let observations = try await ClassifyImageRequest().perform(on: url, orientation: nil)
            return observations.filter { $0.confidence > 0.6 }
                .max { $0.confidence < $1.confidence }?
                .identifier
        } catch {
            Logger(subsystem: "com.example.fieldnotes", category: "ui")
                .notice("Could not classify a photo: \(error.localizedDescription)")
            return nil
        }
    }
}
#endif