@craft-native/ios 0.0.272 → 0.0.278

package/README.md

@@ -594,6 +594,28 @@ stopListening()
 // sends a made-up watch reading every 5 s instead: someone settling into slow
 // breathing, from about 72 toward 60 bpm.
 
+// Live workout sessions (iOS 26+, requires enableHealthKit: true). The OS
+// keeps the session alive while the app is backgrounded; samples arrive as
+// typed craftHealthWorkout events. Ask for the workout/heart-rate grants before
+// starting a session.
+await health.requestAuthorization(['workouts', 'heartRate', 'activeEnergy', 'distance'], { write: true })
+const stopWorkout = health.onWorkout(event => {
+  if (event.event === 'metrics') showMetrics(event.heartRateBpm, event.activeEnergyCalories, event.distanceMeters)
+  if (event.event === 'state') showWorkoutState(event.state)
+  if (event.event === 'error') showWorkoutError(event.message)
+})
+const live = await health.startWorkout({ type: 'running', location: 'outdoor' })
+await health.pauseWorkout()
+await health.resumeWorkout()
+const saved = await health.endWorkout() // { id, workoutId, endDate, durationSeconds }
+stopWorkout()
+
+`startWorkout`, `pauseWorkout`, `resumeWorkout`, and `endWorkout` reject with
+`Live workouts are unavailable` when the build does not include HealthKit or
+when the OS is older than iOS 26. `onWorkout` receives lifecycle events plus
+live `heartRateBpm`, `activeEnergyCalories`, and `distanceMeters` metrics; the
+existing post-hoc `saveWorkout` API remains separate.
+
 // Screen Capture
 const screenshotBase64 = await window.craft.takeScreenshot();
 
@@ -841,6 +863,14 @@ if (await window.craft.scheduledWorkouts.isSupported()) {
 // FormData through fetch, or hand its path to the share sheet.
 const photo = await craft.files.pickImage({ maxPixels: 2048, quality: 0.85 });
 // { path, name: 'IMG_1234.jpg', type: 'image/jpeg', size, width, height }
+// General documents use the same owned-file path and can be selected more
+// than one at a time. Filters are MIME types, UTIs, or filename extensions.
+const attachments = await craft.files.pickFile({
+  contentTypes: ['application/pdf', 'csv', 'gpx', 'fit'],
+  maxSelections: 4,
+  maxBytes: 20 * 1024 * 1024,
+});
+// [{ path, name, type, size }], or [] when the picker is dismissed.
 const form = new FormData();
 form.append('photo', photo);                      // multipart, built natively
 await fetch('https://example.com/upload', { method: 'POST', body: form });
@@ -1004,6 +1034,26 @@ await window.craft.watch.updateContext({
   status: 'active'
 });
 
+// A planned workout is delivered through application context, so the latest
+// plan replaces an older one while the watch is offline and is replayed when
+// the companion launches. The watch persists its current plan and metrics in
+// its own UserDefaults store, then publishes a `watch-state` context back.
+await window.craft.watch.updateContext({
+  type: 'planned-session',
+  plan: {
+    id: 'morning-run',
+    activity: 'running',
+    startDate: Date.now() + 60 * 60 * 1000,
+    targetDistanceMeters: 5000,
+  },
+});
+
+// Watch controls include a protocol version and requestId. Use requestId for
+// idempotency when a queued command arrives after a reconnect. The watch's
+// `watch-state` context includes a monotonically increasing stateVersion; use
+// the highest version when a queued command and a reconnect snapshot cross.
+await window.craft.watch.send({ type: 'recording-control', action: 'start' });
+
 // Listen for messages from watch
 window.craft.watch.onMessage((message) => {
   console.log('Watch message:', message);

package/dist/cli.js

@@ -589,12 +589,15 @@ function renderWatchEntitlements(config) {
     <array>
 ${plistArray(config.appGroups)}
     </array>
+` : "";
+  const healthKit = config.enableHealthKit ? `    <key>com.apple.developer.healthkit</key>
+    <true/>
 ` : "";
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-${appGroups}</dict>
+${appGroups}${healthKit}</dict>
 </plist>
 `;
 }
@@ -995,7 +998,7 @@ function writeShell(output, config) {
     if (!enabled)
       continue;
     mkdirSync(join3(output, folder), { recursive: true });
-    const source = readFileSync(join3(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
+    const source = readFileSync(join3(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{HEALTH_KIT_ENABLED\}\}/g, config.enableHealthKit ? "true" : "false");
     writeFileSync(join3(output, folder, filename), source);
   }
 }
@@ -1128,7 +1131,8 @@ ${nativeDependencies.join(`
     const watchInfo = readFileSync(join3(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
     writeFileSync(join3(output, "WatchApp", "Info.plist"), watchInfo);
     writeFileSync(join3(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
-    const watchExtensionInfo = readFileSync(join3(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+    const watchExtensionInfo = readFileSync(join3(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{HEALTH_USAGE_DESCRIPTIONS\}\}/g, config.enableHealthKit ? `${plistString("NSHealthShareUsageDescription", `${displayName} reads health data you choose to share.`)}
+${plistString("NSHealthUpdateUsageDescription", `${displayName} writes health data only with your permission.`)}` : "");
     writeFileSync(join3(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
     writeFileSync(join3(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }

package/dist/index.js

@@ -776,12 +776,15 @@ function renderWatchEntitlements(config) {
     <array>
 ${plistArray(config.appGroups)}
     </array>
+` : "";
+  const healthKit = config.enableHealthKit ? `    <key>com.apple.developer.healthkit</key>
+    <true/>
 ` : "";
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-${appGroups}</dict>
+${appGroups}${healthKit}</dict>
 </plist>
 `;
 }
@@ -1195,7 +1198,7 @@ function writeShell(output, config) {
     if (!enabled)
       continue;
     mkdirSync2(join3(output, folder), { recursive: true });
-    const source = readFileSync2(join3(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name);
+    const source = readFileSync2(join3(TEMPLATES_DIR, template), "utf8").replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{HEALTH_KIT_ENABLED\}\}/g, config.enableHealthKit ? "true" : "false");
     writeFileSync2(join3(output, folder, filename), source);
   }
 }
@@ -1328,7 +1331,8 @@ ${nativeDependencies.join(`
     const watchInfo = readFileSync2(join3(TEMPLATES_DIR, "WatchApp.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
     writeFileSync2(join3(output, "WatchApp", "Info.plist"), watchInfo);
     writeFileSync2(join3(output, "WatchApp", "Watch.entitlements"), renderWatchEntitlements(config));
-    const watchExtensionInfo = readFileSync2(join3(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId);
+    const watchExtensionInfo = readFileSync2(join3(TEMPLATES_DIR, "WatchExtension.Info.plist.template"), "utf8").replace(/\{\{APP_NAME\}\}/g, xmlEscape(displayName)).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{HEALTH_USAGE_DESCRIPTIONS\}\}/g, config.enableHealthKit ? `${plistString("NSHealthShareUsageDescription", `${displayName} reads health data you choose to share.`)}
+${plistString("NSHealthUpdateUsageDescription", `${displayName} writes health data only with your permission.`)}` : "");
     writeFileSync2(join3(output, "WatchExtension", "Info.plist"), watchExtensionInfo);
     writeFileSync2(join3(output, "WatchExtension", "Watch.entitlements"), renderWatchEntitlements(config));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/ios",
-  "version": "0.0.272",
+  "version": "0.0.278",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/ios#readme",
   "repository": {
     "type": "git",

package/templates/CraftHybrid.swift

@@ -357,6 +357,7 @@ final class CraftHybrid: NSObject {
         isConfigured = true
         self.config = config
         CraftNativeScriptThread.isBackground = config.nativeScriptThread == "background"
+        if CraftNativeScriptThread.isBackground { CraftNativeBundle.prewarm() }
         hasWeb = config.renderer != "native"
         siteURL = config.devServerURL.flatMap(URL.init(string:)).flatMap { url in
             ["http", "https"].contains((url.scheme ?? "").lowercased()) ? url : nil
@@ -2295,13 +2296,15 @@ final class CraftFramePacing: NSObject {
         }
     }
 
-    /// One main-thread block, timed: a screen mount, a bundle evaluation.
+    /// One block, timed: a screen mount, a bundle evaluation. Labelled by the
+    /// thread it ran on, since a screen's script now runs off the main thread
+    /// and a bundle's time there costs no frames.
     @discardableResult
     func measure<T>(_ name: String, _ work: () -> T) -> T {
         guard enabled else { return work() }
         let started = CACurrentMediaTime()
         let result = work()
-        write(String(format: "%@ main=%.1fms", name, (CACurrentMediaTime() - started) * 1000))
+        write(String(format: "%@ %@=%.1fms", name, Thread.isMainThread ? "main" : "script", (CACurrentMediaTime() - started) * 1000))
         return result
     }
 

package/templates/CraftNativeActions.swift

@@ -253,6 +253,12 @@ enum CraftNativeActions {
                 CraftNativeFiles.pickVideo(options) { complete(requestToken, $0, completion) }
             }
             return
+        case ("Files", "pickFile"):
+            let options = args.first as? [String: Any] ?? [:]
+            DispatchQueue.main.async {
+                CraftNativeFiles.pickFile(options) { complete(requestToken, $0, completion) }
+            }
+            return
         case ("Files", "download"):
             download(requestToken: requestToken, args: args, completion: completion)
             return

package/templates/CraftNativeFiles.swift

@@ -328,6 +328,142 @@ enum CraftNativeFiles {
         }
     }
 
+    // MARK: Picking a general file
+
+    /// Pick one or more documents and copy them into app-owned storage while
+    /// the security-scoped URLs are valid. `contentTypes` accepts MIME types,
+    /// UTIs, or filename extensions; an empty list means any document.
+    static func pickFile(_ options: [String: Any], done: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
+        guard activePicker == nil else {
+            done(.failure(CraftNativeActionError(code: "BUSY", message: "A picker is already open")))
+            return
+        }
+        let limit = craftNativeNumber(options["maxBytes"])
+            .map { $0.doubleValue }
+            .flatMap { value in
+                guard value.isFinite else { return nil }
+                return Int(max(1, min(Double(512 * 1024 * 1024), value)))
+            } ?? 512 * 1024 * 1024
+        let selectionLimit = craftNativeNumber(options["maxSelections"])
+            .map { $0.intValue }
+            .map { max(1, min(20, $0)) } ?? 1
+        let types: [UTType]
+        do {
+            types = try documentTypes(options["contentTypes"])
+        } catch let error as CraftNativeActionError {
+            done(.failure(error))
+            return
+        } catch {
+            done(.failure(CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.pickFile contentTypes are invalid")))
+            return
+        }
+        let finish: (Result<Any, CraftNativeActionError>) -> Void = { result in
+            DispatchQueue.main.async { activePicker = nil; done(result) }
+        }
+        let delegate = FileDocumentDelegate(limit: limit, done: finish)
+        let picker = UIDocumentPickerViewController(forOpeningContentTypes: types, asCopy: true)
+        picker.allowsMultipleSelection = selectionLimit > 1
+        picker.delegate = delegate
+        activePicker = delegate
+        if !CraftPresenter.present(picker, from: nil) {
+            activePicker = nil
+            done(.failure(CraftNativeActionError(code: "PICKER_ERROR", message: "Unable to present the file picker")))
+        }
+    }
+
+    /// Resolve an app-supplied content filter without silently broadening it.
+    /// A MIME type, UTI, or extension is enough for `UTType`; applications can
+    /// therefore ask for `application/pdf`, `com.adobe.pdf`, or `pdf` alike.
+    private static func documentTypes(_ value: Any?) throws -> [UTType] {
+        guard let value else { return [.item] }
+        guard let entries = value as? [Any] else {
+            throw CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.pickFile contentTypes must be an array")
+        }
+        guard !entries.isEmpty else { return [.item] }
+        var types: [UTType] = []
+        for entry in entries {
+            guard let raw = entry as? String else {
+                throw CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.pickFile contentTypes must be strings")
+            }
+            let name = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !name.isEmpty,
+                  let type = UTType(mimeType: name) ?? UTType(name) ?? UTType(filenameExtension: name.trimmingCharacters(in: CharacterSet(charactersIn: "."))) else {
+                throw CraftNativeActionError(code: "INVALID_ARGUMENT", message: "files.pickFile contentType is not a MIME type, UTI, or extension: \(raw)")
+            }
+            types.append(type)
+        }
+        return types
+    }
+
+    /// Copy an arbitrary selected document into Craft's private file area and
+    /// return the same descriptor used by downloads, writes, and uploads.
+    static func copyFile(_ source: URL, limit: Int) -> Result<Any, CraftNativeActionError> {
+        do {
+            let values = try source.resourceValues(forKeys: [.fileSizeKey, .contentTypeKey])
+            let size: Int
+            if let fileSize = values.fileSize {
+                size = fileSize
+            } else {
+                size = ((try? FileManager.default.attributesOfItem(atPath: source.path))?[.size] as? NSNumber)?.intValue ?? 0
+            }
+            guard size > 0, size <= limit else {
+                return .failure(CraftNativeActionError(code: "FILE_TOO_LARGE", message: "Choose a nonempty file under \(limit / 1024 / 1024)MB."))
+            }
+            let destination = try newFile(named: source.lastPathComponent)
+            do { try FileManager.default.copyItem(at: source, to: destination) }
+            catch { try? FileManager.default.removeItem(at: destination.deletingLastPathComponent()); throw error }
+            let type = mimeType(for: source, contentType: values.contentType)
+            return .success(describe(destination, type: type))
+        } catch {
+            return .failure(CraftNativeActionError(code: "READ_ERROR", message: error.localizedDescription))
+        }
+    }
+
+    private static func mimeType(for source: URL, contentType: UTType?) -> String {
+        let generic = "application/octet-stream"
+        if let preferred = contentType?.preferredMIMEType, preferred != generic { return preferred }
+        if let preferred = UTType(filenameExtension: source.pathExtension)?.preferredMIMEType, preferred != generic {
+            return preferred
+        }
+        switch source.pathExtension.lowercased() {
+        case "gpx": return "application/gpx+xml"
+        case "tcx": return "application/vnd.garmin.tcx+xml"
+        case "fit": return "application/vnd.ant.fit"
+        case "csv": return "text/csv"
+        case "json": return "application/json"
+        case "txt": return "text/plain"
+        default: return generic
+        }
+    }
+
+    private final class FileDocumentDelegate: NSObject, UIDocumentPickerDelegate {
+        let limit: Int
+        let done: (Result<Any, CraftNativeActionError>) -> Void
+        init(limit: Int, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) { self.limit = limit; self.done = done }
+        func documentPickerWasCancelled(_ controller: UIDocumentPickerViewController) { done(.success([])) }
+        func documentPicker(_ controller: UIDocumentPickerViewController, didPickDocumentsAt urls: [URL]) {
+            guard !urls.isEmpty else { done(.success([])); return }
+            let (limit, done) = (self.limit, self.done)
+            DispatchQueue.global(qos: .userInitiated).async {
+                var results: [[String: Any]] = []
+                for url in urls {
+                    let granted = url.startAccessingSecurityScopedResource()
+                    defer { if granted { url.stopAccessingSecurityScopedResource() } }
+                    switch CraftNativeFiles.copyFile(url, limit: limit) {
+                    case .success(let value):
+                        guard let info = value as? [String: Any] else { done(.failure(CraftNativeActionError(code: "READ_ERROR", message: "The selected file could not be described"))); return }
+                        results.append(info)
+                    case .failure(let error):
+                        results.compactMap { $0["path"] as? String }.forEach { CraftNativeFiles.remove($0) }
+                        done(.failure(error))
+                        return
+                    }
+                }
+                done(.success(results))
+            }
+        }
+    }
+
     static func copyVideo(_ source: URL, limit: Int) -> Result<Any, CraftNativeActionError> {
         let ext = source.pathExtension.lowercased()
         let types = ["mp4": "video/mp4", "m4v": "video/x-m4v", "mov": "video/quicktime", "webm": "video/webm"]

package/templates/CraftNativeMutation.swift

@@ -115,6 +115,9 @@ final class CraftNativeMutationDocument {
                     // A child crossing parents needs the committed tree to be
                     // reconciled so the host can move its existing native view.
                     requiresFullRender = true
+                case "replaceChildren":
+                    let parentId = try replaceChildren(operation, nodes: &candidateNodes)
+                    appendUnique(parentId, to: &affectedNodeIds)
                 case "removeNode":
                     if let id = operation["id"] as? String, let parent = candidateNodes[id]?.parent {
                         appendUnique(parent, to: &affectedNodeIds)
@@ -287,6 +290,54 @@ final class CraftNativeMutationDocument {
         return previousParentId
     }
 
+    /// Replaces a container's ordered child snapshot in one atomic mutation.
+    ///
+    /// The list protocol uses this operation when a keyed `:for` expansion
+    /// produces a new row set. Existing nodes may stay attached to the same
+    /// parent; removed children become detached and can be reused or removed
+    /// by later operations in the same batch.
+    private func replaceChildren(_ operation: [String: Any], nodes: inout [String: Node]) throws -> String {
+        let parentId = try requiredId(operation, field: "parentId", name: "replaceChildren")
+        guard var parent = nodes[parentId] else {
+            throw CraftNativeMutationFailure("UNKNOWN_PARENT", "node \(parentId) does not exist")
+        }
+        guard acceptsChildren(parent.type) else {
+            throw CraftNativeMutationFailure("INVALID_PARENT", "node \(parentId) cannot contain child nodes")
+        }
+        guard let values = operation["children"] as? [Any] else {
+            throw CraftNativeMutationFailure("INVALID_CHILDREN", "replaceChildren.children must be an array")
+        }
+        var childIds: [String] = []
+        for value in values {
+            guard let childId = value as? String, !childId.isEmpty else {
+                throw CraftNativeMutationFailure("INVALID_CHILDREN", "replaceChildren.children must contain non-empty ids")
+            }
+            guard !childIds.contains(childId) else {
+                throw CraftNativeMutationFailure("DUPLICATE_CHILD", "child \(childId) appears more than once")
+            }
+            guard let child = nodes[childId] else {
+                throw CraftNativeMutationFailure("UNKNOWN_NODE", "node \(childId) does not exist")
+            }
+            guard childId != parentId, !descendants(of: childId, nodes: nodes).contains(parentId) else {
+                throw CraftNativeMutationFailure("CYCLE", "attaching node \(childId) would create a cycle")
+            }
+            guard child.parent == nil || child.parent == parentId else {
+                throw CraftNativeMutationFailure("NODE_ATTACHED", "node \(childId) already has a parent")
+            }
+            childIds.append(childId)
+        }
+        let removedChildIds = parent.children.filter { !childIds.contains($0) }
+        for oldChildId in removedChildIds {
+            for descendant in descendants(of: oldChildId, nodes: nodes).union([oldChildId]) {
+                nodes.removeValue(forKey: descendant)
+            }
+        }
+        parent.children = childIds
+        nodes[parentId] = parent
+        for childId in childIds { nodes[childId]?.parent = parentId }
+        return parentId
+    }
+
     private func removeNode(
         _ operation: [String: Any],
         nodes: inout [String: Node],

package/templates/CraftNativeScreen.swift

@@ -1345,6 +1345,64 @@ private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate
     deinit { stop() }
 }
 
+/// A map pin that answers being activated as it answers a tap.
+final class CraftMarkerAnnotationView: MKAnnotationView {
+    var onActivate: (() -> Void)?
+
+    override func accessibilityActivate() -> Bool {
+        guard let onActivate else { return super.accessibilityActivate() }
+        onActivate()
+        return true
+    }
+
+    override func prepareForReuse() {
+        super.prepareForReuse()
+        onActivate = nil
+    }
+}
+
+/// A tile overlay whose tiles are kept on disk.
+///
+/// MKTileOverlay asked the network for every tile on every pan back over the
+/// same ground, and drew nothing where a tile had not come yet. These go
+/// through one session with a cache of its own (Caches/craft-map-tiles), so
+/// ground seen before draws at once and offline, and a phone on a trail
+/// does not fetch the same hillside twice.
+final class CraftCachedTileOverlay: MKTileOverlay {
+    static let session: URLSession = {
+        let configuration = URLSessionConfiguration.default
+        let directory = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?.appendingPathComponent("craft-map-tiles", isDirectory: true)
+        configuration.urlCache = URLCache(memoryCapacity: 48 << 20, diskCapacity: 512 << 20, directory: directory)
+        // Topography and imagery change on the scale of months: a tile held
+        // is used without asking again.
+        configuration.requestCachePolicy = .returnCacheDataElseLoad
+        configuration.httpMaximumConnectionsPerHost = 8
+        return URLSession(configuration: configuration)
+    }()
+
+    override func loadTile(at path: MKTileOverlayPath, result: @escaping (Data?, Error?) -> Void) {
+        let request = URLRequest(url: url(forTilePath: path), cachePolicy: .returnCacheDataElseLoad, timeoutInterval: 20)
+        Self.session.dataTask(with: request) { data, response, error in
+            if let status = (response as? HTTPURLResponse)?.statusCode, !(200..<300).contains(status) {
+                result(nil, error ?? URLError(.badServerResponse))
+                return
+            }
+            result(data, error)
+        }.resume()
+    }
+}
+
+/// The basemaps a `Map` names with `basemap`, drawn the best way each
+/// platform can: Apple's vector map (with real terrain from iOS 16) for
+/// standard, imagery and hybrid, and topography with contours over a muted
+/// Apple map for outdoors.
+enum CraftBasemap: String {
+    case standard, outdoors, satellite, hybrid
+
+    static let outdoorTiles = "https://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/{z}/{y}/{x}"
+    static let outdoorCredit = "Topography: Esri, USGS, NOAA, OpenStreetMap contributors"
+}
+
 private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
     private var annotationsByID: [String: MKPointAnnotation] = [:]
     private var overlaysByID: [String: MKPolyline] = [:]
@@ -1371,6 +1429,8 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
     private var markerPinColors: [String: UIColor] = [:]
     private var tileOverlay: MKTileOverlay?
     private var tileTemplate: String?
+    private var tileReplacesMap = true
+    private var appliedBasemap: CraftBasemap?
     private var tileAttributionBottom: NSLayoutConstraint?
     private lazy var tileAttribution: UILabel = {
         let label = UILabel()
@@ -1395,6 +1455,10 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         isRotateEnabled = false
         let tap = UITapGestureRecognizer(target: self, action: #selector(pressedMap(_:)))
         tap.cancelsTouchesInView = false
+        // Alongside MapKit's own recognizers, not instead of them: on its own
+        // this tap won the touch, MapKit never selected the pin under it, and
+        // a pin's onPress (Explore's trail card) never fired on a phone.
+        tap.delegate = CraftMapTapDelegate.shared
         addGestureRecognizer(tap)
     }
 
@@ -1429,8 +1493,13 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         isZoomEnabled = props["zoomEnabled"] as? Bool ?? true
         isRotateEnabled = props["rotateEnabled"] as? Bool ?? false
         isPitchEnabled = props["pitchEnabled"] as? Bool ?? true
-        mapType = Self.mapType(props["mapType"] as? String)
-        configureTiles(props["tileOverlay"] as? [String: Any])
+        if let basemap = (props["basemap"] as? String).flatMap({ CraftBasemap(rawValue: $0.lowercased()) }) {
+            applyBasemap(basemap)
+        } else {
+            appliedBasemap = nil
+            mapType = Self.mapType(props["mapType"] as? String)
+            configureTiles(props["tileOverlay"] as? [String: Any])
+        }
         showsCompass = props["showsCompass"] as? Bool ?? false
         showsScale = props["showsScale"] as? Bool ?? false
         authoredPitch = Self.numeric(props["cameraPitch"])
@@ -1562,7 +1631,9 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             overlayCoordinatesByID[id] = value.coordinates
             overlayColors[ObjectIdentifier(overlay)] = value.color
             overlayWidths[ObjectIdentifier(overlay)] = value.width
-            addOverlay(overlay)
+            // Above labels, as a basemap's topography is: at a lower level
+            // the outdoors layer covered every route drawn on it.
+            addOverlay(overlay, level: .aboveLabels)
         }
         let stalePolygons = polygonsByID.keys.filter { nextPolygons[$0] == nil }
         for id in stalePolygons {
@@ -1595,7 +1666,7 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             polygonFills[ObjectIdentifier(polygon)] = value.fill
             polygonStrokes[ObjectIdentifier(polygon)] = value.stroke
             polygonWidths[ObjectIdentifier(polygon)] = value.width
-            addOverlay(polygon)
+            addOverlay(polygon, level: .aboveLabels)
         }
         // Keep authored casing/foreground order when an earlier line changes
         // or retained children move. Exchanging native overlays preserves the
@@ -1684,20 +1755,48 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         tileAttribution.isHidden = true
     }
 
-    private func configureTiles(_ options: [String: Any]?) {
+    /// A named basemap. Applied once per change: setting a map configuration
+    /// again redraws the whole map.
+    private func applyBasemap(_ basemap: CraftBasemap) {
+        if appliedBasemap != basemap {
+            appliedBasemap = basemap
+            if #available(iOS 16.0, *) {
+                switch basemap {
+                case .satellite: preferredConfiguration = MKImageryMapConfiguration(elevationStyle: .realistic)
+                case .hybrid: preferredConfiguration = MKHybridMapConfiguration(elevationStyle: .realistic)
+                // Flat under the topography, so the overlay's contours sit
+                // on the ground they describe.
+                case .outdoors: preferredConfiguration = MKStandardMapConfiguration(elevationStyle: .flat, emphasisStyle: .muted)
+                case .standard: preferredConfiguration = MKStandardMapConfiguration(elevationStyle: .realistic)
+                }
+            }
+            else {
+                mapType = basemap == .satellite ? .satellite : basemap == .hybrid ? .hybrid : basemap == .outdoors ? .mutedStandard : .standard
+            }
+        }
+        configureTiles(basemap == .outdoors ? ["urlTemplate": CraftBasemap.outdoorTiles, "attribution": CraftBasemap.outdoorCredit] : nil, replacesMap: false)
+    }
+
+    /// `replacesMap`: an authored `tileOverlay` replaces Apple's map, as it
+    /// always has. A basemap's topography draws over it instead, above its
+    /// labels, so ground whose tiles have not come yet shows the map rather
+    /// than an empty grid.
+    private func configureTiles(_ options: [String: Any]?, replacesMap: Bool = true) {
         let template = options?["urlTemplate"] as? String
         let credit = options?["attribution"] as? String ?? ""
         let valid = template.map { value in value.hasPrefix("https://") && ["{z}", "{x}", "{y}"].allSatisfy { value.contains($0) } } ?? false
         let next = valid && !credit.isEmpty ? template : nil
-        if tileTemplate != next {
+        if tileTemplate != next || tileReplacesMap != replacesMap {
             if let overlay = tileOverlay { removeOverlay(overlay) }
             tileOverlay = nil
             tileTemplate = next
+            tileReplacesMap = replacesMap
             if let next {
-                let overlay = MKTileOverlay(urlTemplate: next)
-                overlay.canReplaceMapContent = true
+                let overlay = CraftCachedTileOverlay(urlTemplate: next)
+                overlay.canReplaceMapContent = replacesMap
+                overlay.maximumZ = 19
                 tileOverlay = overlay
-                insertOverlay(overlay, at: 0, level: .aboveRoads)
+                insertOverlay(overlay, at: 0, level: replacesMap ? .aboveRoads : .aboveLabels)
             }
         }
         tileAttribution.text = next == nil ? nil : credit
@@ -1756,11 +1855,27 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             view.tintColor = color
             view.image = Self.markerImage(color: color, direction: true)
             view.transform = CGAffineTransform(rotationAngle: CGFloat((bearing - camera.heading) * .pi / 180))
+            // Direction marks thin themselves: MapKit hides the ones that
+            // would overlap at this zoom and brings them back closer in, so
+            // a trail reads as a line with chevrons along it, not a column of
+            // badges over the route.
+            view.displayPriority = .defaultLow
+            view.collisionMode = .circle
+            // Decoration along the route: not a stop for VoiceOver.
+            view.isAccessibilityElement = false
         } else {
             let color = (markerPinColors[id] ?? .systemRed).resolvedColor(with: traitCollection)
             view.tintColor = color
             view.image = Self.markerImage(color: color, direction: false)
             view.transform = .identity
+            view.displayPriority = .required
+            view.collisionMode = .rectangle
+            // Above the user's own location: at a trailhead - where the map
+            // is most often opened - the dot sat on the trail's pin and took
+            // every tap meant for it.
+            if #available(iOS 14.0, *) { view.zPriority = .max }
+            view.isAccessibilityElement = true
+            view.accessibilityTraits = .button
         }
     }
 
@@ -1771,9 +1886,10 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
     }()
 
     private static func markerImage(color: UIColor, direction: Bool) -> UIImage {
-        let key = "\(direction ? "direction" : "pin"):\(color.description)" as NSString
+        let key = "\(direction ? "chevron" : "pin"):\(color.description)" as NSString
         if let cached = markerImages.object(forKey: key) { return cached }
-        let size = direction ? CGSize(width: 20, height: 24) : CGSize(width: 28, height: 28)
+        if direction { return directionImage(color: color, key: key) }
+        let size = CGSize(width: 28, height: 28)
         // Explicit native drawing preserves the light backing independently
         // of MapKit's tint and SF Symbols' multicolor rendering preferences.
         let image = UIGraphicsImageRenderer(size: size).image { _ in
@@ -1787,7 +1903,32 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             let symbol = UIImage(systemName: direction ? "arrow.up" : "mappin",
                 withConfiguration: UIImage.SymbolConfiguration(pointSize: 16, weight: .semibold))?
                 .withTintColor(color, renderingMode: .alwaysOriginal)
-            symbol?.draw(in: direction ? CGRect(x: 5, y: 6, width: 10, height: 12) : CGRect(x: 7, y: 5, width: 14, height: 18))
+            symbol?.draw(in: CGRect(x: 7, y: 5, width: 14, height: 18))
+        }.withRenderingMode(.alwaysOriginal)
+        markerImages.setObject(image, forKey: key)
+        return image
+    }
+
+    /// A route's direction: a 16-point chevron in the route's colour with a
+    /// white edge, so it sits on the line it describes and stays legible
+    /// over topography and imagery alike.
+    private static func directionImage(color: UIColor, key: NSString) -> UIImage {
+        let size = CGSize(width: 16, height: 16)
+        let image = UIGraphicsImageRenderer(size: size).image { context in
+            let chevron = UIBezierPath()
+            chevron.move(to: CGPoint(x: 8, y: 2.5))
+            chevron.addLine(to: CGPoint(x: 13.5, y: 12))
+            chevron.addLine(to: CGPoint(x: 8, y: 9.25))
+            chevron.addLine(to: CGPoint(x: 2.5, y: 12))
+            chevron.close()
+            chevron.lineJoinStyle = .round
+            context.cgContext.setShadow(offset: .zero, blur: 1.5, color: UIColor.black.withAlphaComponent(0.25).cgColor)
+            UIColor.white.setStroke()
+            chevron.lineWidth = 3
+            chevron.stroke()
+            context.cgContext.setShadow(offset: .zero, blur: 0, color: nil)
+            color.setFill()
+            chevron.fill()
         }.withRenderingMode(.alwaysOriginal)
         markerImages.setObject(image, forKey: key)
         return image
@@ -1844,9 +1985,12 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
 
     func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {
         guard let id = annotationsByID.first(where: { $0.value === annotation })?.key else { return nil }
-        let view = dequeueReusableAnnotationView(withIdentifier: "craft-native-marker")
-            ?? MKAnnotationView(annotation: annotation, reuseIdentifier: "craft-native-marker")
+        let view = (dequeueReusableAnnotationView(withIdentifier: "craft-native-marker") as? CraftMarkerAnnotationView)
+            ?? CraftMarkerAnnotationView(annotation: annotation, reuseIdentifier: "craft-native-marker")
         view.annotation = annotation
+        // Activated (VoiceOver, Switch Control, a UI test) as a tap would:
+        // the plain annotation view did nothing when activated.
+        view.onActivate = { [weak self] in self?.onMarkerTap?(id) }
         configureMarkerView(view, id: id)
         view.accessibilityIdentifier = id
         return view
@@ -3998,6 +4142,16 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate {
     }
 }
 
+/// The delegate of a map's own tap (`Map`'s onPress): it watches beside
+/// MapKit's recognizers, so a tap on a pin still selects it.
+final class CraftMapTapDelegate: NSObject, UIGestureRecognizerDelegate {
+    static let shared = CraftMapTapDelegate()
+
+    func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer, shouldRecognizeSimultaneouslyWith otherGestureRecognizer: UIGestureRecognizer) -> Bool {
+        true
+    }
+}
+
 /// The delegate of a Pressable's press-in/out feedback. That recognizer is
 /// a long press of no duration, so it begins the moment a finger lands; on its
 /// own it would claim the touch, and the tap that is the Pressable's onPress
@@ -5095,6 +5249,17 @@ enum CraftNativeBundle {
     /// is not parsed again. Each screen keeps a global object of its own.
     static let virtualMachine = JSVirtualMachine()!
 
+    /// JavaScriptCore's first machine and context, made on the script thread
+    /// at launch instead of on the main thread by the first screen: that one-
+    /// time setup was a quarter of a second of the first tab's mount, all of
+    /// it in front of the first frame. Nothing is evaluated, so the main
+    /// thread never waits on the machine for it.
+    static func prewarm() {
+        CraftNativeScriptThread.queue.async {
+            _ = JSContext(virtualMachine: virtualMachine)
+        }
+    }
+
     private static let sources: NSCache<NSString, NSString> = {
         let cache = NSCache<NSString, NSString>()
         // Room for the one-file bundle, or a dozen route files.
@@ -8649,8 +8814,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// Views that take their own touches whatever handlers the screen gives
     /// them: native controls, a scroll view, a modal, and a video's controls (with
     /// interaction off, its play, scrubber and full screen never answered).
+    /// A map and a wheel picker too: neither is a UIControl, so a map with no
+    /// long-press handler - every map - was made non-interactive, and could
+    /// not be panned, zoomed, or have a pin tapped; a picker could not be spun.
     private func ownsTouches(_ view: UIView) -> Bool {
         view is UIControl || view is UIScrollView || view is CraftNativeModalView || view is CraftNativeVideoView
+            || view is MKMapView || view is UIPickerView
     }
 
     private func updatePressHandler(_ handler: String?, for view: UIView) {

package/templates/CraftWatchApp.swift.template

@@ -1,4 +1,5 @@
 import SwiftUI
+import HealthKit
 import WatchConnectivity
 
 @main
@@ -15,14 +16,28 @@ struct {{APP_NAME}}WatchApp: App {
 
 @MainActor
 final class CraftWatchSession: NSObject, ObservableObject {
+    private static let protocolVersion = 1
+    private static let persistedStateKey = "craft.watch.state.v1"
+    private static let healthKitEnabled = {{HEALTH_KIT_ENABLED}}
+
     @Published private(set) var isPhoneReachable = false
     @Published private(set) var isRecording = false
     @Published private(set) var isPaused = false
     @Published private(set) var distanceMeters = 0.0
     @Published private(set) var durationSeconds = 0.0
     @Published private(set) var status = "Ready"
+    @Published private(set) var plannedSession: [String: Any]?
+    @Published private(set) var heartRateBpm: Double?
+    @Published private(set) var heartRateZone: Int?
+    @Published private(set) var lastWorkout: [String: Any]?
 
     private let session: WCSession?
+    private let healthStore = HKHealthStore()
+    private var stateVersion = 0
+    private var workoutSession: HKWorkoutSession?
+    private var workoutBuilder: HKLiveWorkoutBuilder?
+    private var workoutId: String?
+    private var workoutStartedAt: Date?
 
     override init() {
         if WCSession.isSupported() {
@@ -32,49 +47,320 @@ final class CraftWatchSession: NSObject, ObservableObject {
         }
         super.init()
         session?.delegate = self
+        restoreState()
         session?.activate()
     }
 
     func toggleRecording() {
-        let action: String
         if !isRecording {
-            action = "start"
+            if Self.healthKitEnabled {
+                startHealthWorkout { [weak self] started in
+                    if started { self?.send(action: "start") }
+                }
+            } else {
+                send(action: "start")
+            }
         } else if isPaused {
-            action = "resume"
+            resumeHealthWorkout()
+            send(action: "resume")
         } else {
-            action = "pause"
+            pauseHealthWorkout()
+            send(action: "pause")
         }
-        send(action: action)
     }
 
     func finishRecording() {
-        send(action: "finish")
+        if Self.healthKitEnabled, workoutSession != nil {
+            endHealthWorkout { [weak self] _ in self?.send(action: "finish") }
+        } else {
+            send(action: "finish")
+        }
+    }
+
+    /// The phone sends a planned session through application context. Context
+    /// is the right transport here: it replaces stale plans while the watch is
+    /// offline and is replayed when the app launches again.
+    func clearPlannedSession() {
+        plannedSession = nil
+        persistState()
+        publishState()
     }
 
     private func send(action: String) {
         guard let session, session.activationState == .activated else {
             status = "Open WildLoop on iPhone"
+            persistState()
             return
         }
-        let message: [String: Any] = ["type": "recording-control", "action": action]
+        let message: [String: Any] = [
+            "protocolVersion": Self.protocolVersion,
+            "requestId": UUID().uuidString,
+            "type": "recording-control",
+            "action": action,
+        ]
         if session.isReachable {
             session.sendMessage(message, replyHandler: { [weak self] reply in
                 Task { @MainActor in self?.apply(reply) }
             }, errorHandler: { [weak self] _ in
-                Task { @MainActor in self?.status = "Could not reach iPhone" }
+                Task { @MainActor in
+                    self?.status = "Could not reach iPhone"
+                    self?.persistState()
+                    self?.publishState()
+                }
             })
         } else {
             session.transferUserInfo(message)
             status = "Command queued"
+            persistState()
+            publishState()
         }
     }
 
     private func apply(_ payload: [String: Any]) {
+        if let plan = payload["plan"] as? [String: Any], payload["type"] as? String == "planned-session" {
+            plannedSession = plan
+            status = "Plan ready"
+        } else if let plan = payload["plannedSession"] as? [String: Any] {
+            plannedSession = plan
+        }
         if let recording = payload["recording"] as? Bool { isRecording = recording }
         if let paused = payload["paused"] as? Bool { isPaused = paused }
         if let distance = payload["distanceMeters"] as? Double { distanceMeters = max(distance, 0) }
         if let duration = payload["durationSeconds"] as? Double { durationSeconds = max(duration, 0) }
         if let value = payload["status"] as? String { status = value }
+        if let heartRate = payload["heartRateBpm"] as? Double, heartRate.isFinite { heartRateBpm = max(heartRate, 0) }
+        if let zone = payload["heartRateZone"] as? Int { heartRateZone = min(max(zone, 1), 5) }
+        if let workout = payload["workout"] as? [String: Any] { lastWorkout = workout }
+        persistState()
+        publishState()
+    }
+
+    private func restoreState() {
+        guard let state = UserDefaults.standard.dictionary(forKey: Self.persistedStateKey) else { return }
+        if let recording = state["recording"] as? Bool { isRecording = recording }
+        if let paused = state["paused"] as? Bool { isPaused = paused }
+        if let distance = state["distanceMeters"] as? Double { distanceMeters = max(distance, 0) }
+        if let duration = state["durationSeconds"] as? Double { durationSeconds = max(duration, 0) }
+        if let value = state["status"] as? String { status = value }
+        if let version = state["stateVersion"] as? Int { stateVersion = max(version, stateVersion) }
+        plannedSession = state["plannedSession"] as? [String: Any]
+        if let heartRate = state["heartRateBpm"] as? Double { heartRateBpm = max(heartRate, 0) }
+        if let zone = state["heartRateZone"] as? Int { heartRateZone = min(max(zone, 1), 5) }
+        lastWorkout = state["lastWorkout"] as? [String: Any]
+    }
+
+    private func persistState() {
+        stateVersion += 1
+        var state: [String: Any] = [
+            "protocolVersion": Self.protocolVersion,
+            "stateVersion": stateVersion,
+            "recording": isRecording,
+            "paused": isPaused,
+            "distanceMeters": distanceMeters,
+            "durationSeconds": durationSeconds,
+            "status": status,
+        ]
+        if let plannedSession { state["plannedSession"] = plannedSession }
+        if let heartRateBpm { state["heartRateBpm"] = heartRateBpm }
+        if let heartRateZone { state["heartRateZone"] = heartRateZone }
+        if let lastWorkout { state["lastWorkout"] = lastWorkout }
+        UserDefaults.standard.set(state, forKey: Self.persistedStateKey)
+    }
+
+    private func publishState() {
+        guard let session, session.activationState == .activated else { return }
+        var state: [String: Any] = [
+            "protocolVersion": Self.protocolVersion,
+            "stateVersion": stateVersion,
+            "type": "watch-state",
+            "recording": isRecording,
+            "paused": isPaused,
+            "distanceMeters": distanceMeters,
+            "durationSeconds": durationSeconds,
+            "status": status,
+        ]
+        if let plannedSession { state["plannedSession"] = plannedSession }
+        if let heartRateBpm { state["heartRateBpm"] = heartRateBpm }
+        if let heartRateZone { state["heartRateZone"] = heartRateZone }
+        if let lastWorkout { state["workout"] = lastWorkout }
+        try? session.updateApplicationContext(state)
+    }
+
+    private func startHealthWorkout(completion: @escaping (Bool) -> Void) {
+        guard HKHealthStore.isHealthDataAvailable() else {
+            status = "HealthKit unavailable"
+            persistState()
+            completion(false)
+            return
+        }
+        let shareTypes: Set<HKSampleType> = [HKObjectType.workoutType()]
+        var readTypes: Set<HKObjectType> = [HKObjectType.workoutType()]
+        if let heartRate = HKQuantityType.quantityType(forIdentifier: .heartRate) { readTypes.insert(heartRate) }
+        if let distance = HKQuantityType.quantityType(forIdentifier: .distanceWalkingRunning) { readTypes.insert(distance) }
+        if let energy = HKQuantityType.quantityType(forIdentifier: .activeEnergyBurned) { readTypes.insert(energy) }
+        healthStore.requestAuthorization(toShare: shareTypes, read: readTypes) { [weak self] success, error in
+            DispatchQueue.main.async {
+                guard let self else { return completion(false) }
+                guard success else {
+                    self.status = error?.localizedDescription ?? "HealthKit authorization denied"
+                    self.persistState()
+                    return completion(false)
+                }
+                self.beginHealthWorkout(completion: completion)
+            }
+        }
+    }
+
+    private func beginHealthWorkout(completion: @escaping (Bool) -> Void) {
+        guard workoutSession == nil else { completion(true); return }
+        let configuration = HKWorkoutConfiguration()
+        configuration.activityType = .running
+        configuration.locationType = .outdoor
+        do {
+            let session = try HKWorkoutSession(healthStore: healthStore, configuration: configuration)
+            let builder = session.associatedWorkoutBuilder()
+            session.delegate = self
+            builder.delegate = self
+            builder.shouldCollectWorkoutEvents = true
+            builder.dataSource = HKLiveWorkoutDataSource(healthStore: healthStore, workoutConfiguration: configuration)
+            workoutSession = session
+            workoutBuilder = builder
+            workoutId = UUID().uuidString.lowercased()
+            let start = Date()
+            workoutStartedAt = start
+            session.startActivity(with: start)
+            builder.beginCollection(withStart: start) { [weak self] success, error in
+                DispatchQueue.main.async {
+                    guard let self else { return completion(false) }
+                    guard success else {
+                        self.clearHealthWorkout()
+                        self.status = error?.localizedDescription ?? "Workout could not start"
+                        self.persistState()
+                        return completion(false)
+                    }
+                    self.isRecording = true
+                    self.isPaused = false
+                    self.status = "Recording"
+                    self.persistState()
+                    self.publishState()
+                    completion(true)
+                }
+            }
+        } catch {
+            status = error.localizedDescription
+            persistState()
+            completion(false)
+        }
+    }
+
+    private func pauseHealthWorkout() {
+        guard let workoutSession else { return }
+        workoutSession.pause()
+        isPaused = true
+        status = "Paused"
+        persistState()
+        publishState()
+    }
+
+    private func resumeHealthWorkout() {
+        guard let workoutSession else { return }
+        workoutSession.resume()
+        isPaused = false
+        status = "Recording"
+        persistState()
+        publishState()
+    }
+
+    private func endHealthWorkout(completion: @escaping ([String: Any]?) -> Void) {
+        guard let workoutSession, let workoutBuilder, let id = workoutId else {
+            completion(nil)
+            return
+        }
+        let end = Date()
+        workoutSession.end()
+        workoutBuilder.endCollection(withEnd: end) { [weak self] success, error in
+            guard let self else { return }
+            guard success else {
+                DispatchQueue.main.async {
+                    self.status = error?.localizedDescription ?? "Workout could not finish"
+                    self.persistState()
+                    completion(nil)
+                }
+                return
+            }
+            workoutBuilder.finishWorkout { [weak self] workout, finishError in
+                DispatchQueue.main.async {
+                    guard let self else { return completion(nil) }
+                    guard let workout else {
+                        self.status = finishError?.localizedDescription ?? "Workout could not be saved"
+                        self.persistState()
+                        return completion(nil)
+                    }
+                    let result: [String: Any] = [
+                        "id": id,
+                        "workoutId": workout.uuid.uuidString,
+                        "startDate": (self.workoutStartedAt ?? workout.startDate).timeIntervalSince1970 * 1000,
+                        "endDate": end.timeIntervalSince1970 * 1000,
+                        "durationSeconds": workout.duration,
+                        "distanceMeters": self.distanceMeters,
+                    ]
+                    self.lastWorkout = result
+                    self.isRecording = false
+                    self.isPaused = false
+                    self.status = "Saved to Apple Health"
+                    self.clearHealthWorkout()
+                    self.persistState()
+                    self.publishState()
+                    completion(result)
+                }
+            }
+        }
+    }
+
+    private func clearHealthWorkout() {
+        workoutSession = nil
+        workoutBuilder = nil
+        workoutId = nil
+        workoutStartedAt = nil
+    }
+
+    private func updateHealthMetrics(_ builder: HKLiveWorkoutBuilder) {
+        if let heartRate = HKQuantityType.quantityType(forIdentifier: .heartRate),
+           let value = builder.statistics(for: heartRate)?.mostRecentQuantity()?.doubleValue(for: HKUnit.count().unitDivided(by: .minute())),
+           value.isFinite {
+            heartRateBpm = max(value, 0)
+            let maximum = (plannedSession?["maxHeartRateBpm"] as? Double) ?? 190
+            heartRateZone = min(max(Int(ceil(value / maximum * 5)), 1), 5)
+        }
+        if let distance = HKQuantityType.quantityType(forIdentifier: .distanceWalkingRunning),
+           let value = builder.statistics(for: distance)?.sumQuantity()?.doubleValue(for: .meter()),
+           value.isFinite {
+            distanceMeters = max(value, 0)
+        }
+        if let start = workoutStartedAt { durationSeconds = max(Date().timeIntervalSince(start), 0) }
+        persistState()
+        publishState()
+    }
+}
+
+extension CraftWatchSession: HKWorkoutSessionDelegate, HKLiveWorkoutBuilderDelegate {
+    nonisolated func workoutSession(_ workoutSession: HKWorkoutSession, didChangeTo toState: HKWorkoutSessionState, from fromState: HKWorkoutSessionState, date: Date) {}
+
+    nonisolated func workoutSession(_ workoutSession: HKWorkoutSession, didFailWithError error: Error) {
+        Task { @MainActor in
+            status = error.localizedDescription
+            isRecording = false
+            isPaused = false
+            clearHealthWorkout()
+            persistState()
+            publishState()
+        }
+    }
+
+    nonisolated func workoutBuilderDidCollectEvent(_ workoutBuilder: HKLiveWorkoutBuilder) {}
+
+    nonisolated func workoutBuilder(_ workoutBuilder: HKLiveWorkoutBuilder, didCollectDataOf types: Set<HKSampleType>) {
+        Task { @MainActor in updateHealthMetrics(workoutBuilder) }
     }
 }
 
@@ -84,11 +370,15 @@ extension CraftWatchSession: WCSessionDelegate {
             isPhoneReachable = session.isReachable
             status = error == nil ? "Ready" : "Connection unavailable"
             apply(session.receivedApplicationContext)
+            publishState()
         }
     }
 
     nonisolated func sessionReachabilityDidChange(_ session: WCSession) {
-        Task { @MainActor in isPhoneReachable = session.isReachable }
+        Task { @MainActor in
+            isPhoneReachable = session.isReachable
+            if session.isReachable { publishState() }
+        }
     }
 
     nonisolated func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
@@ -129,6 +419,10 @@ struct CraftWatchRecordingView: View {
                     metric(distance, label: "Distance")
                     metric(duration, label: "Time")
                 }
+                if let heartRate = session.heartRateBpm {
+                    metric(String(format: "%.0f bpm", heartRate), label: "Heart rate")
+                    if let zone = session.heartRateZone { Text("Zone \(zone) of 5").font(.caption2).foregroundStyle(.secondary) }
+                }
                 Button(session.isRecording && !session.isPaused ? "Pause" : session.isPaused ? "Resume" : "Start") {
                     session.toggleRecording()
                 }

package/templates/WatchExtension.Info.plist.template

@@ -30,5 +30,6 @@
         <key>NSExtensionPointIdentifier</key>
         <string>com.apple.watchkit</string>
     </dict>
+    {{HEALTH_USAGE_DESCRIPTIONS}}
 </dict>
 </plist>