@craft-native/ios 0.0.236 → 0.0.238

package/templates/CraftApp.swift

@@ -205,6 +205,12 @@ final class CraftAppDelegate: NSObject, UIApplicationDelegate, UNUserNotificatio
         // push, a refresh, a route recording's location) draws nothing, and
         // its events still need someone to hear them.
         CraftHybrid.shared.configure(config)
+        if let shortcuts = config.appShortcuts {
+            application.shortcutItems = shortcuts.prefix(4).map { shortcut in
+                UIApplicationShortcutItem(type: shortcut.id, localizedTitle: shortcut.title, localizedSubtitle: shortcut.subtitle,
+                    icon: UIApplicationShortcutIcon(systemImageName: shortcut.symbol), userInfo: ["url": shortcut.url as NSString])
+            }
+        }
         if let shortcut = launchOptions?[.shortcutItem] as? UIApplicationShortcutItem {
             CraftEventManager.shared.handleShortcut(shortcut)
             // Returning false tells UIKit the launch-time item was handled and
@@ -415,6 +421,12 @@ class CraftEventManager {
         }
     }
 
+    /// Zig already delivers to the page; native-only delivery must not repeat it.
+    func sendToAppScript(_ event: String, data: [String: Any]) {
+        guard listener == .appScript else { return }
+        sendToWeb(event, data: data)
+    }
+
     /// An event no one will hear: logged, and background work it holds is
     /// answered at once.
     private func drop(_ event: String, data: [String: Any]) {
@@ -607,6 +619,12 @@ struct CraftApp: App {
 // images and all, and a tab bar or a splash that waited for it would be late
 // on every launch.
 
+/// Finger tracking changes only the indicator. Publishing it on CraftChrome
+/// invalidated the glass surface, every tab and the splash for every pan event.
+final class CraftTabSwipeProgress: ObservableObject {
+    @Published var position: CGFloat?
+}
+
 final class CraftChrome: ObservableObject {
     static let shared = CraftChrome()
 
@@ -619,6 +637,21 @@ final class CraftChrome: ObservableObject {
         var titleOverride: String? = nil
         var iconTint: String? = nil
         var iconPulse = false
+        var selectedSymbol: String? = nil
+        var selectedIconTint: String? = nil
+        var selectedIconPulse: Bool? = nil
+
+        static func normalizedSelectedSymbol(_ value: String?) -> String? {
+            guard let name = value?.trimmingCharacters(in: .whitespacesAndNewlines), !name.isEmpty else { return nil }
+            return name
+        }
+
+        func iconAppearance(selected: Bool, motionAllowed: Bool) -> (symbol: String, tint: String?, pulse: Bool) {
+            let name = selected ? selectedSymbol ?? symbol : symbol
+            let tint = selected ? selectedIconTint ?? iconTint : iconTint
+            let pulse = selected ? selectedIconPulse ?? iconPulse : iconPulse
+            return (name, tint, pulse && motionAllowed)
+        }
         var displayTitle: String { titleOverride ?? title }
         var accessibilityLabel: String? = nil
         var image: String? = nil
@@ -627,7 +660,11 @@ final class CraftChrome: ObservableObject {
     @Published var tabs: [Tab] = []
     @Published var tabAccessory: Tab?
     @Published var selected: String?
-    @Published private(set) var tabSwipePosition: CGFloat?
+    let tabSwipeProgress = CraftTabSwipeProgress()
+    private(set) var tabSwipePosition: CGFloat? {
+        get { tabSwipeProgress.position }
+        set { tabSwipeProgress.position = newValue }
+    }
     @Published var tabBarVisible = false
     @Published var splashVisible = true
     @Published var tint: UIColor?
@@ -669,7 +706,7 @@ final class CraftChrome: ObservableObject {
         splashVisible = splash
         tabSwipeEnabled = true
         guard !configured.isEmpty else { return }
-        tabs = configured.map { Tab(id: $0.id, title: $0.title, symbol: $0.symbol ?? "circle", badge: nil) }
+        tabs = configured.map { Tab(id: $0.id, title: $0.title, symbol: $0.symbol ?? "circle", badge: nil, selectedSymbol: Tab.normalizedSelectedSymbol($0.selectedSymbol), selectedIconTint: $0.selectedIconTint, selectedIconPulse: $0.selectedIconPulse) }
         self.selected = selected ?? configured.first?.id
         tabBarVisible = true
     }
@@ -682,27 +719,42 @@ final class CraftChrome: ObservableObject {
     /// Change one tab's caption or icon without replacing stacks or selection.
     func updateTab(_ item: [String: Any]) {
         guard let id = item["id"] as? String, let index = tabs.firstIndex(where: { $0.id == id }) else { return }
+        // One live reading is one change. Mutating a member of a Published
+        // array sends objectWillChange for every field, including equal ones,
+        // rebuilding the glass bar repeatedly while its content scrolls.
+        var next = tabs[index]
         if item.keys.contains("iconText") {
-            tabs[index].iconText = (item["iconText"] as? String).flatMap { $0.isEmpty ? nil : String($0.prefix(8)) }
+            next.iconText = (item["iconText"] as? String).flatMap { $0.isEmpty ? nil : String($0.prefix(8)) }
         }
         if item.keys.contains("title") {
-            tabs[index].titleOverride = (item["title"] as? String).flatMap { $0.isEmpty ? nil : String($0.prefix(40)) }
+            next.titleOverride = (item["title"] as? String).flatMap { $0.isEmpty ? nil : String($0.prefix(40)) }
         }
         if item.keys.contains("iconTint") {
-            tabs[index].iconTint = (item["iconTint"] as? String).flatMap { UIColor(hex: $0) == nil ? nil : $0 }
+            next.iconTint = (item["iconTint"] as? String).flatMap { UIColor(hex: $0) == nil ? nil : $0 }
         }
         if item.keys.contains("iconPulse") {
-            tabs[index].iconPulse = item["iconPulse"] as? Bool ?? false
+            next.iconPulse = item["iconPulse"] as? Bool ?? false
+        }
+        if item.keys.contains("selectedSymbol") {
+            next.selectedSymbol = Tab.normalizedSelectedSymbol(item["selectedSymbol"] as? String)
+        }
+        if item.keys.contains("selectedIconTint") {
+            next.selectedIconTint = (item["selectedIconTint"] as? String).flatMap { UIColor(hex: $0) == nil ? nil : $0 }
+        }
+        if item.keys.contains("selectedIconPulse") {
+            next.selectedIconPulse = item["selectedIconPulse"] as? Bool
         }
         if item.keys.contains("accessibilityLabel") {
-            tabs[index].accessibilityLabel = (item["accessibilityLabel"] as? String).map { String($0.prefix(160)) }
+            next.accessibilityLabel = (item["accessibilityLabel"] as? String).map { String($0.prefix(160)) }
         }
         if item.keys.contains("image") {
-            tabs[index].image = (item["image"] as? String).flatMap { URL(string: $0)?.scheme == "https" ? $0 : nil }
+            next.image = (item["image"] as? String).flatMap { URL(string: $0)?.scheme == "https" ? $0 : nil }
         }
         if item.keys.contains("badge") {
-            tabs[index].badge = (item["badge"] as? String).flatMap { $0.isEmpty ? nil : String($0.prefix(8)) }
+            next.badge = (item["badge"] as? String).flatMap { $0.isEmpty ? nil : String($0.prefix(8)) }
         }
+        guard next != tabs[index] else { return }
+        tabs[index] = next
     }
     /// A destination beside the tab pill, outside the tab stacks and swipe order.
     func updateTabAccessory(_ item: [String: Any]?) {
@@ -746,7 +798,10 @@ final class CraftChrome: ObservableObject {
             tabs = (body["tabs"] as? [[String: Any]] ?? []).compactMap { item in
                 guard let id = item["id"] as? String, let title = item["title"] as? String else { return nil }
                 let badge = (item["badge"] as? String).flatMap { $0.isEmpty ? nil : $0 }
-                return Tab(id: id, title: title, symbol: item["symbol"] as? String ?? "circle", badge: badge)
+                return Tab(id: id, title: title, symbol: item["symbol"] as? String ?? "circle", badge: badge,
+                    selectedSymbol: Tab.normalizedSelectedSymbol(item["selectedSymbol"] as? String),
+                    selectedIconTint: (item["selectedIconTint"] as? String).flatMap { UIColor(hex: $0) == nil ? nil : $0 },
+                    selectedIconPulse: item["selectedIconPulse"] as? Bool)
             }
             if let selected = body["selected"] as? String {
                 self.selected = selected
@@ -1102,18 +1157,7 @@ struct CraftTabBarView: View {
             }
         }
         .background {
-            GeometryReader { geometry in
-                if let position = chrome.tabSwipePosition
-                    ?? chrome.tabs.firstIndex(where: { $0.id == chrome.selected }).map({ CGFloat($0) }) {
-                    let width = geometry.size.width / CGFloat(max(1, chrome.tabs.count))
-                    Capsule()
-                        .fill(Color.primary.opacity(0.09))
-                        .frame(width: width, height: geometry.size.height)
-                        .offset(x: position * width)
-                }
-            }
-            .allowsHitTesting(false)
-            .accessibilityHidden(true)
+            CraftTabSelectionIndicator(selected: chrome.tabs.firstIndex(where: { $0.id == chrome.selected }), count: chrome.tabs.count)
         }
     }
 
@@ -1123,13 +1167,15 @@ struct CraftTabBarView: View {
 
     /// Live styling belongs to the icon, leaving selection and the caption clear.
     @ViewBuilder private func tabSymbol(_ tab: CraftChrome.Tab, selected: Bool) -> some View {
-        let color = tab.iconTint.flatMap { UIColor(hex: $0) }.map { Color($0) } ?? (selected ? selectedColor : Color.primary)
-        let icon = Image(systemName: symbol(tab.symbol, selected: selected))
+        let appearance = tab.iconAppearance(selected: selected, motionAllowed: !reduceMotion && scenePhase == .active && chrome.tabBarVisible)
+        let color = appearance.tint.flatMap { UIColor(hex: $0) }.map { Color($0) } ?? (selected ? selectedColor : Color.primary)
+        let name = selected && tab.selectedSymbol != nil ? appearance.symbol : symbol(appearance.symbol, selected: selected)
+        let icon = Image(systemName: name)
             .font(.system(size: iconSize, weight: selected ? .semibold : .regular))
             .foregroundStyle(color)
             .frame(height: iconSize + 6)
         if #available(iOS 17.0, *) {
-            icon.symbolEffect(.pulse, options: .repeating, isActive: tab.iconPulse && !reduceMotion && scenePhase == .active)
+            icon.symbolEffect(.pulse, options: .repeating, isActive: appearance.pulse)
         } else {
             icon
         }
@@ -1142,6 +1188,26 @@ struct CraftTabBarView: View {
     }
 }
 
+private struct CraftTabSelectionIndicator: View {
+    @ObservedObject private var progress = CraftChrome.shared.tabSwipeProgress
+    let selected: Int?
+    let count: Int
+
+    var body: some View {
+        GeometryReader { geometry in
+            if let position = progress.position ?? selected.map({ CGFloat($0) }) {
+                let width = geometry.size.width / CGFloat(max(1, count))
+                Capsule()
+                    .fill(Color.primary.opacity(0.09))
+                    .frame(width: width, height: geometry.size.height)
+                    .offset(x: position * width)
+            }
+        }
+        .allowsHitTesting(false)
+        .accessibilityHidden(true)
+    }
+}
+
 /// The launch screen, held until the page is ready: the same colour and the
 /// same logo at the same place, so the hand-over from the system's launch
 /// screen cannot be seen.
@@ -1399,7 +1465,17 @@ extension CraftConfig {
 }
 
 // MARK: - Configuration
+struct CraftConfiguredShortcut: Codable {
+    var id: String
+    var title: String
+    var subtitle: String?
+    var symbol: String
+    var url: String
+    var phrases: [String]
+}
+
 struct CraftConfig: Codable {
+    var appShortcuts: [CraftConfiguredShortcut]? = nil
     var appName: String = "Craft App"
     var bundleId: String = "com.craft.app"
     /// Opt-in UIKit + JavaScriptCore screen; existing apps keep WKWebView.
@@ -1501,6 +1577,9 @@ struct CraftConfig: Codable {
         var id: String
         var title: String
         var symbol: String? = nil
+        var selectedSymbol: String? = nil
+        var selectedIconTint: String? = nil
+        var selectedIconPulse: Bool? = nil
     }
 
     struct BackgroundRefresh: Codable {
@@ -1919,6 +1998,8 @@ struct CraftWebView: UIViewRepresentable {
         private var isLocationRecordingPaused = false
         private var locationRecordingId: String?
         private var locationRecordingStartedAt: TimeInterval?
+        private let recordingDirectory: URL?
+        private var locationRecordingRestoreError: Error?
 
         // Network monitoring
         private var networkMonitor: NWPathMonitor?
@@ -1984,7 +2065,8 @@ struct CraftWebView: UIViewRepresentable {
         // SQLite database
         private var db: OpaquePointer?
 
-        init(config: CraftConfig) {
+        init(config: CraftConfig, recordingDirectory: URL? = nil) {
+            self.recordingDirectory = recordingDirectory
             self.config = config
             super.init()
             if config.enableSpeechRecognition {
@@ -1999,7 +2081,8 @@ struct CraftWebView: UIViewRepresentable {
                 // relaunch restore — see `CraftZigRuntime.adoptLocationRecording`.
                 // Running both would leave two managers appending to one track.
                 if !CraftZigRuntime.adoptLocationRecording() {
-                    restoreLocationRecordingState()
+                    do { try restoreLocationRecordingState() }
+                    catch { locationRecordingRestoreError = error }
                 }
             }
             if config.enableContacts {
@@ -2149,6 +2232,13 @@ struct CraftWebView: UIViewRepresentable {
         /// `craft_ios_deliver_result` instead of evaluating JavaScript here —
         /// one reply path, owned by whichever side received the page's message.
         func dispatch(action: String, body: [String: Any], callbackId: String?) {
+            if ["startLocationRecording", "pauseLocationRecording", "resumeLocationRecording", "stopLocationRecording", "getLocationRecordingState", "readLocationRecording", "acknowledgeLocationRecording"].contains(action),
+               locationRecordingRestoreError != nil {
+                rejectCallback(callbackId, error: "Unable to restore recording data", code: "RECORDING_STORAGE_ERROR")
+                return
+            }
+            if ["getLocationRecordingState", "readLocationRecording", "stopLocationRecording"].contains(action),
+               archivedLocationAction(action, body: body, callbackId: callbackId) { return }
             if let answer = CraftNativeActions.perform(action: action, body: body, config: config) {
                 switch answer {
                 case .success(let value): resolveCallback(callbackId, result: value)
@@ -2345,20 +2435,22 @@ struct CraftWebView: UIViewRepresentable {
                 resolveCallback(callbackId, result: true)
             case "startLocationRecording":
                 if config.enableGeolocation {
-                    startLocationRecording(callbackId: callbackId)
+                    startLocationRecording(body: body, callbackId: callbackId)
                 } else {
                     rejectCallback(callbackId, error: "Geolocation is disabled", code: "CAPABILITY_DISABLED")
                 }
             case "pauseLocationRecording":
-                pauseLocationRecording(callbackId: callbackId)
+                if requireLocationRecordingOwner(body, callbackId: callbackId) { pauseLocationRecording(callbackId: callbackId) }
             case "resumeLocationRecording":
-                resumeLocationRecording(callbackId: callbackId)
+                if requireLocationRecordingOwner(body, callbackId: callbackId) { resumeLocationRecording(callbackId: callbackId) }
             case "stopLocationRecording":
-                stopLocationRecording(callbackId: callbackId)
+                if requireLocationRecordingOwner(body, callbackId: callbackId) { stopLocationRecording(callbackId: callbackId) }
             case "getLocationRecordingState":
                 getLocationRecordingState(callbackId: callbackId)
             case "readLocationRecording":
-                readLocationRecording(callbackId: callbackId)
+                if requireLocationRecordingOwner(body, callbackId: callbackId) { readLocationRecording(callbackId: callbackId) }
+            case "acknowledgeLocationRecording":
+                _ = archivedLocationAction(action, body: body, callbackId: callbackId)
             // App Badge
             case "setBadge":
                 if let count = body["count"] as? Int {
@@ -3666,6 +3758,9 @@ struct CraftWebView: UIViewRepresentable {
                     pushNotifications: \(config.enablePushNotifications),
                     secureStorage: \(config.enableSecureStorage),
                     geolocation: \(config.enableGeolocation),
+                    crypto: true,
+                    locationRecordingOwnership: \(config.enableGeolocation && CraftZigRuntime.supportsRecordingOwnership),
+                    locationRecordingIntentIdentity: \(config.enableGeolocation && CraftZigRuntime.supportsRecordingIntentIdentity),
                     backgroundLocation: \(config.enableBackgroundLocation),
                     healthKit: \(config.enableHealthKit),
                     liveActivities: \(config.enableLiveActivities),
@@ -3682,6 +3777,8 @@ struct CraftWebView: UIViewRepresentable {
                     brightness: true,
                     music: \(config.enableAppleMusic),
                     heartRate: \(config.enableHeartRate),
+                    heartRateRecordingOwnership: \(config.enableHeartRate),
+                    heartRateRecordingIntentIdentity: \(config.enableHeartRate),
                     scheduledWorkouts: \(config.enableScheduledWorkouts),
                     speech: true,
                     crashReporter: \(CraftCrashReporter.shared.enabled),
@@ -5266,6 +5363,20 @@ struct CraftWebView: UIViewRepresentable {
                     browserOpen: true
                 };
                 craft._invoke = function(action, payload) {
+                    var recordingOptions = action === 'heartRate' && payload && ['startRecording', 'pauseRecording', 'resumeRecording', 'stopRecording', 'readRecording', 'getRecordingState', 'acknowledgeRecording'].indexOf(payload.method) !== -1
+                        ? payload.options : ['startLocationRecording', 'pauseLocationRecording', 'resumeLocationRecording', 'stopLocationRecording', 'readLocationRecording', 'getLocationRecordingState', 'acknowledgeLocationRecording'].indexOf(action) !== -1 ? payload : null;
+                    if (recordingOptions && Object.prototype.hasOwnProperty.call(recordingOptions, 'recordingId') &&
+                        (typeof recordingOptions.recordingId !== 'string' || !recordingOptions.recordingId.trim())) {
+                        var invalidStart = new Error('recordingId must be a nonempty recording ID');
+                        invalidStart.code = 'INVALID_ARGUMENT';
+                        return Promise.reject(invalidStart);
+                    }
+                    if (recordingOptions && Object.prototype.hasOwnProperty.call(recordingOptions, 'expectedId') &&
+                        (typeof recordingOptions.expectedId !== 'string' || !recordingOptions.expectedId.trim())) {
+                        var invalid = new Error('expectedId must be a nonempty recording ID');
+                        invalid.code = 'INVALID_ARGUMENT';
+                        return Promise.reject(invalid);
+                    }
                     var self = craft;
                     var id = 'cb_' + (++self._callbackId);
                     var message = Object.assign({}, payload || {}, {action: action, callbackId: id});
@@ -5403,6 +5514,7 @@ struct CraftWebView: UIViewRepresentable {
                     legacyLocationWatchCallbacks.length = 0;
                     return stopLocationWatchIfUnused();
                 };
+                craft.crypto = { randomUUID: function() { return craft._invoke('cryptoRandomUUID'); } };
                 craft.location = {
                     getCurrentPosition: function(options) { return legacyGeolocation.getCurrentPosition(options || {}); },
                     watchPosition: function(callback) {
@@ -5421,12 +5533,13 @@ struct CraftWebView: UIViewRepresentable {
                         if (!locationWatchCallbacks.delete(id)) return;
                         void stopLocationWatchIfUnused().catch(function() {});
                     },
-                    startRecording: function() { return craft._invoke('startLocationRecording'); },
-                    pauseRecording: function() { return craft._invoke('pauseLocationRecording'); },
-                    resumeRecording: function() { return craft._invoke('resumeLocationRecording'); },
-                    stopRecording: function() { return craft._invoke('stopLocationRecording'); },
-                    getRecordingState: function() { return craft._invoke('getLocationRecordingState'); },
-                    readRecording: function() { return craft._invoke('readLocationRecording'); }
+                    startRecording: function(options) { return craft._invoke('startLocationRecording', options || {}); },
+                    pauseRecording: function(options) { return craft._invoke('pauseLocationRecording', options || {}); },
+                    resumeRecording: function(options) { return craft._invoke('resumeLocationRecording', options || {}); },
+                    stopRecording: function(options) { return craft._invoke('stopLocationRecording', options || {}); },
+                    getRecordingState: function(options) { return craft._invoke('getLocationRecordingState', options || {}); },
+                    acknowledgeRecording: function(options) { return craft._invoke('acknowledgeLocationRecording', options || {}); },
+                    readRecording: function(options) { return craft._invoke('readLocationRecording', options || {}); }
                 };
                 craft.health = {
                     requestAuthorization: function(types, options) {
@@ -5514,12 +5627,13 @@ struct CraftWebView: UIViewRepresentable {
                         connect: function(id) { return heartRate('connect', {id: typeof id === 'string' ? id : id && id.id}); },
                         reconnect: function() { return heartRate('reconnect'); },
                         disconnect: function(options) { return heartRate('disconnect', {forget: !!(options && options.forget)}); },
-                        startRecording: function() { return heartRate('startRecording'); },
-                        pauseRecording: function() { return heartRate('pauseRecording'); },
-                        resumeRecording: function() { return heartRate('resumeRecording'); },
-                        stopRecording: function() { return heartRate('stopRecording'); },
-                        getRecordingState: function() { return heartRate('getRecordingState'); },
-                        readRecording: function(options) { return heartRate('readRecording', {since: options && typeof options.since === 'number' ? options.since : null}); }
+                        startRecording: function(options) { return heartRate('startRecording', options || {}); },
+                        pauseRecording: function(options) { return heartRate('pauseRecording', options || {}); },
+                        resumeRecording: function(options) { return heartRate('resumeRecording', options || {}); },
+                        stopRecording: function(options) { return heartRate('stopRecording', options || {}); },
+                        getRecordingState: function(options) { return heartRate('getRecordingState', options || {}); },
+                        acknowledgeRecording: function(options) { return heartRate('acknowledgeRecording', options || {}); },
+                        readRecording: function(options) { return heartRate('readRecording', options || {}); }
                     };
                 })();
                 // Structured workouts on the paired Apple Watch (WorkoutKit,
@@ -6344,12 +6458,12 @@ struct CraftWebView: UIViewRepresentable {
         }
 
         private var locationRecordingStateURL: URL {
-            FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+            (recordingDirectory ?? FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0])
                 .appendingPathComponent("craft-location-recording-state.json")
         }
 
         private var locationRecordingTrackURL: URL {
-            FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+            (recordingDirectory ?? FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0])
                 .appendingPathComponent("craft-location-recording.jsonl")
         }
 
@@ -6366,54 +6480,142 @@ struct CraftWebView: UIViewRepresentable {
             locationManager?.showsBackgroundLocationIndicator = config.enableBackgroundLocation
         }
 
-        private func persistLocationRecordingState() {
-            let state: [String: Any] = [
-                "active": isRecordingLocation,
-                "paused": isLocationRecordingPaused,
-                "id": locationRecordingId ?? NSNull(),
-                "startedAt": locationRecordingStartedAt ?? NSNull(),
-            ]
-            do {
-                let directory = locationRecordingStateURL.deletingLastPathComponent()
-                try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
-                let data = try JSONSerialization.data(withJSONObject: state)
-                try data.write(to: locationRecordingStateURL, options: .atomic)
-                protectLocationFile(locationRecordingStateURL)
-            } catch {
-                print("Unable to persist location recording state: \(error)")
-            }
+        private func persistLocationRecordingState() throws {
+            let state: [String: Any] = ["active": isRecordingLocation, "paused": isLocationRecordingPaused, "id": locationRecordingId ?? NSNull(), "startedAt": locationRecordingStartedAt ?? NSNull()]
+            try CraftRecordingArchive.writeAtomically(JSONSerialization.data(withJSONObject: state), locationRecordingStateURL)
         }
 
-        private func restoreLocationRecordingState() {
-            guard let data = try? Data(contentsOf: locationRecordingStateURL),
-                  let state = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
-                  state["active"] as? Bool == true else { return }
-            isRecordingLocation = true
+        private func restoreLocationRecordingState() throws {
+            guard FileManager.default.fileExists(atPath: locationRecordingStateURL.path) else {
+                if FileManager.default.fileExists(atPath: locationRecordingTrackURL.path), !(try Data(contentsOf: locationRecordingTrackURL)).isEmpty {
+                    throw CraftNativeActionError(code: "RECORDING_STORAGE_ERROR", message: "Recording metadata is missing")
+                }
+                return
+            }
+            let data = try Data(contentsOf: locationRecordingStateURL)
+            guard let state = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+                  let active = state["active"] as? Bool else {
+                throw CraftNativeActionError(code: "RECORDING_STORAGE_ERROR", message: "Invalid recording metadata")
+            }
+            isRecordingLocation = active
             isLocationRecordingPaused = state["paused"] as? Bool ?? false
             locationRecordingId = state["id"] as? String
             locationRecordingStartedAt = state["startedAt"] as? TimeInterval
-            if !isLocationRecordingPaused {
+            if let id = locationRecordingId, try CraftRecordingArchive.isAcknowledged(recordingBaseDirectory, "location", id) {
+                try CraftRecordingArchive.acknowledge(recordingBaseDirectory, "location", id)
+                if FileManager.default.fileExists(atPath: locationRecordingTrackURL.path) { try FileManager.default.removeItem(at: locationRecordingTrackURL) }
+                locationRecordingId = nil
+                locationRecordingStartedAt = nil
+                isRecordingLocation = false
+                isLocationRecordingPaused = false
+                try persistLocationRecordingState()
+            }
+            if isRecordingLocation && !isLocationRecordingPaused {
                 locationManager?.delegate = self
                 configureBackgroundLocationIfNeeded()
                 locationManager?.startUpdatingLocation()
             }
         }
 
-        private func startLocationRecording(callbackId: String?) {
+        /// Same serial main-queue dispatch as the operation it protects.
+        private func requireLocationRecordingOwner(_ body: [String: Any], callbackId: String?) -> Bool {
+            guard body.keys.contains("expectedId") else { return true }
+            guard let expected = body["expectedId"] as? String,
+                  !expected.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+                rejectCallback(callbackId, error: "expectedId must be a nonempty recording ID", code: "INVALID_ARGUMENT")
+                return false
+            }
+            guard locationRecordingId == expected else {
+                rejectCallback(callbackId, error: "The active location recording has changed", code: "RECORDING_CONFLICT")
+                return false
+            }
+            return true
+        }
+
+        private var recordingBaseDirectory: URL {
+            recordingDirectory ?? FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
+        }
+
+        private func archivedLocationAction(_ action: String, body: [String: Any], callbackId: String?) -> Bool {
+            guard body.keys.contains("expectedId") else {
+                if action == "acknowledgeLocationRecording" {
+                    rejectCallback(callbackId, error: "Acknowledgement needs expectedId", code: "INVALID_ARGUMENT")
+                    return true
+                }
+                return false
+            }
+            guard let id = body["expectedId"] as? String, !id.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+                rejectCallback(callbackId, error: "expectedId must be a nonempty recording ID", code: "INVALID_ARGUMENT")
+                return true
+            }
+            do {
+                if action == "acknowledgeLocationRecording" {
+                    if locationRecordingId == id && isRecordingLocation {
+                        rejectCallback(callbackId, error: "The recording is still active", code: "RECORDING_ALREADY_ACTIVE")
+                        return true
+                    }
+                    var known = try locationRecordingId == id || CraftRecordingArchive.isAcknowledged(recordingBaseDirectory, "location", id)
+                    if !known { known = try CraftRecordingArchive.read(recordingBaseDirectory, "location", id) != nil }
+                    guard known else {
+                        rejectCallback(callbackId, error: "Unknown recording ID", code: "RECORDING_CONFLICT")
+                        return true
+                    }
+                    try CraftRecordingArchive.acknowledge(recordingBaseDirectory, "location", id)
+                    if locationRecordingId == id {
+                        if FileManager.default.fileExists(atPath: locationRecordingTrackURL.path) { try FileManager.default.removeItem(at: locationRecordingTrackURL) }
+                        locationRecordingId = nil
+                        locationRecordingStartedAt = nil
+                        try persistLocationRecordingState()
+                    }
+                    resolveCallback(callbackId, result: true)
+                    return true
+                }
+                if var saved = try CraftRecordingArchive.read(recordingBaseDirectory, "location", id) {
+                    if action == "readLocationRecording" { resolveCallback(callbackId, result: saved["locations"] ?? []) }
+                    else {
+                        if action == "getLocationRecordingState" { saved.removeValue(forKey: "locations") }
+                        resolveCallback(callbackId, result: saved)
+                    }
+                    return true
+                }
+                return !requireLocationRecordingOwner(body, callbackId: callbackId)
+            } catch let error as CraftNativeActionError {
+                rejectCallback(callbackId, error: error.message, code: error.code)
+            } catch { rejectCallback(callbackId, error: "Unable to persist the recording", code: "RECORDING_STORAGE_ERROR") }
+            return true
+        }
+
+        private func startLocationRecording(body: [String: Any], callbackId: String?) {
+            guard !isRecordingLocation else {
+                rejectCallback(callbackId, error: "A location recording is already active", code: "RECORDING_ALREADY_ACTIVE")
+                return
+            }
             let directory = locationRecordingTrackURL.deletingLastPathComponent()
+            let id: String
             do {
+                id = try CraftRecordingArchive.startId(body, directory: recordingBaseDirectory, kind: "location", currentId: locationRecordingId)
+                try CraftRecordingArchive.save(recordingBaseDirectory, "location", locationRecordingSummary(), samples: try loadRecordedLocationsStrict())
                 try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
                 try Data().write(to: locationRecordingTrackURL, options: .atomic)
                 protectLocationFile(locationRecordingTrackURL)
+            } catch let error as CraftNativeActionError {
+                rejectCallback(callbackId, error: error.message, code: error.code)
+                return
             } catch {
                 rejectCallback(callbackId, error: "Unable to create the location recording", code: "RECORDING_STORAGE_ERROR")
                 return
             }
-            locationRecordingId = UUID().uuidString
+            let previous = (locationRecordingId, locationRecordingStartedAt, isRecordingLocation, isLocationRecordingPaused)
+            locationRecordingId = id
             locationRecordingStartedAt = Date().timeIntervalSince1970 * 1000
             isRecordingLocation = true
             isLocationRecordingPaused = false
-            persistLocationRecordingState()
+            do { try persistLocationRecordingState() }
+            catch {
+                (locationRecordingId, locationRecordingStartedAt, isRecordingLocation, isLocationRecordingPaused) = previous
+                rejectCallback(callbackId, error: "Unable to persist the location recording", code: "RECORDING_STORAGE_ERROR")
+                return
+            }
             locationManager?.delegate = self
             requestLocationAuthorization()
             configureBackgroundLocationIfNeeded()
@@ -6426,8 +6628,14 @@ struct CraftWebView: UIViewRepresentable {
                 rejectCallback(callbackId, error: "No active location recording", code: "NO_ACTIVE_RECORDING")
                 return
             }
+            let previous = isLocationRecordingPaused
             isLocationRecordingPaused = true
-            persistLocationRecordingState()
+            do { try persistLocationRecordingState() }
+            catch {
+                isLocationRecordingPaused = previous
+                rejectCallback(callbackId, error: "Unable to persist the location recording", code: "RECORDING_STORAGE_ERROR")
+                return
+            }
             if !isWatchingLocation { locationManager?.stopUpdatingLocation() }
             resolveCallback(callbackId, result: locationRecordingSummary())
         }
@@ -6437,8 +6645,14 @@ struct CraftWebView: UIViewRepresentable {
                 rejectCallback(callbackId, error: "No active location recording", code: "NO_ACTIVE_RECORDING")
                 return
             }
+            let previous = isLocationRecordingPaused
             isLocationRecordingPaused = false
-            persistLocationRecordingState()
+            do { try persistLocationRecordingState() }
+            catch {
+                isLocationRecordingPaused = previous
+                rejectCallback(callbackId, error: "Unable to persist the location recording", code: "RECORDING_STORAGE_ERROR")
+                return
+            }
             // Set here too: a recording restored at launch while paused never
             // got a delegate, so resuming it started updates nobody received
             // and the route stopped at the pause.
@@ -6450,17 +6664,21 @@ struct CraftWebView: UIViewRepresentable {
         }
 
         private func stopLocationRecording(callbackId: String?) {
-            isRecordingLocation = false
-            isLocationRecordingPaused = false
-            persistLocationRecordingState()
-            if !isWatchingLocation {
-                locationManager?.stopUpdatingLocation()
-                locationManager?.allowsBackgroundLocationUpdates = false
-            }
-            let locations = loadRecordedLocations()
-            var summary = locationRecordingSummary()
-            summary["locations"] = locations
-            resolveCallback(callbackId, result: summary)
+            do {
+                let locations = try loadRecordedLocationsStrict()
+                let previous = (isRecordingLocation, isLocationRecordingPaused)
+                isRecordingLocation = false
+                isLocationRecordingPaused = false
+                do { try persistLocationRecordingState() }
+                catch { (isRecordingLocation, isLocationRecordingPaused) = previous; throw error }
+                if !isWatchingLocation {
+                    locationManager?.stopUpdatingLocation()
+                    locationManager?.allowsBackgroundLocationUpdates = false
+                }
+                var summary = locationRecordingSummary()
+                summary["locations"] = locations
+                resolveCallback(callbackId, result: summary)
+            } catch { rejectCallback(callbackId, error: "Unable to persist the location recording", code: "RECORDING_STORAGE_ERROR") }
         }
 
         private func getLocationRecordingState(callbackId: String?) {
@@ -6470,7 +6688,8 @@ struct CraftWebView: UIViewRepresentable {
         }
 
         private func readLocationRecording(callbackId: String?) {
-            resolveCallback(callbackId, result: loadRecordedLocations())
+            do { resolveCallback(callbackId, result: try loadRecordedLocationsStrict()) }
+            catch { rejectCallback(callbackId, error: "Unable to read the location recording", code: "RECORDING_STORAGE_ERROR") }
         }
 
         private func locationRecordingSummary() -> [String: Any] {
@@ -6505,8 +6724,11 @@ struct CraftWebView: UIViewRepresentable {
             try? protectedURL.setResourceValues(values)
         }
 
-        private func loadRecordedLocations() -> [[String: Any]] {
-            guard let text = try? String(contentsOf: locationRecordingTrackURL, encoding: .utf8) else { return [] }
+        private func loadRecordedLocations() -> [[String: Any]] { (try? loadRecordedLocationsStrict()) ?? [] }
+
+        private func loadRecordedLocationsStrict() throws -> [[String: Any]] {
+            if locationRecordingId == nil { return [] }
+            let text = try String(contentsOf: locationRecordingTrackURL, encoding: .utf8)
             return text.split(separator: "\n").compactMap { line in
                 guard let data = line.data(using: .utf8) else { return nil }
                 return try? JSONSerialization.jsonObject(with: data) as? [String: Any]
@@ -6515,13 +6737,14 @@ struct CraftWebView: UIViewRepresentable {
 
         func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
             guard let location = locations.last else { return }
-            let data = locationData(location)
+            var data = locationData(location)
 
             if let callbackId = singleLocationCallbackId {
                 finishSingleLocationRequest()
                 resolveCallback(callbackId, result: data)
             }
 
+            if isRecordingLocation, let id = locationRecordingId { data["recordingId"] = id }
             appendRecordedLocation(data)
             if isWatchingLocation || isRecordingLocation {
                 sendToWeb("craftLocationUpdate", data: data)
@@ -8816,6 +9039,60 @@ final class CraftZigRuntime: NSObject {
         UnsafePointer<CChar>, UInt, UnsafePointer<CChar>, UInt, Int64
     ) -> Bool
     private typealias AdoptLocationRecordingFn = @convention(c) () -> Bool
+    private typealias RecordingOwnershipVersionFn = @convention(c) () -> Int32
+    private typealias RecordingReplyFn = @convention(c) (UnsafeMutableRawPointer?, Bool, UnsafePointer<CChar>, UInt) -> Void
+    private typealias PerformRecordingFn = @convention(c) (UnsafePointer<CChar>, UInt, UnsafePointer<CChar>, UInt, UnsafeMutableRawPointer?, RecordingReplyFn) -> Bool
+    private final class RecordingReply {
+        var answered = false
+        var result: Result<Any, CraftNativeActionError>?
+
+    }
+    private static let performRecordingFn: PerformRecordingFn? = {
+        guard let sym = dlsym(image, "craft_ios_perform_recording_action") else { return nil }
+        return unsafeBitCast(sym, to: PerformRecordingFn.self)
+    }()
+
+    /// Synchronous native recorder requests use the exact page owner and reply
+    /// envelope, without loading a page or creating a second location manager.
+    static func performRecording(action: String, body: [String: Any], completion: @escaping (Result<Any, CraftNativeActionError>) -> Void) -> Bool {
+        guard supportsRecordingOwnership, let performRecordingFn else {
+            if !isLinked { return false }
+            completion(.failure(CraftNativeActionError(code: "RECORDING_OWNERSHIP_UNSUPPORTED", message: "The linked runtime lacks the shared recorder API")))
+            return true
+        }
+        guard let payload = try? JSONSerialization.data(withJSONObject: body),
+              let json = String(data: payload, encoding: .utf8) else {
+            completion(.failure(CraftNativeActionError(code: "INVALID_ARGUMENT", message: "Recording options must be JSON")))
+            return true
+        }
+        let reply = RecordingReply()
+        let served = withExtendedLifetime(reply) {
+            action.withCString { a in json.withCString { p in
+                performRecordingFn(a, UInt(strlen(a)), p, UInt(strlen(p)), Unmanaged.passUnretained(reply).toOpaque()) { context, failed, bytes, count in
+                    guard let context else { return }
+                    let reply = Unmanaged<RecordingReply>.fromOpaque(context).takeUnretainedValue()
+                    guard !reply.answered else { return }
+                    reply.answered = true
+                    let data = Data(bytes: bytes, count: Int(count))
+                    guard let result = try? JSONSerialization.jsonObject(with: data, options: .fragmentsAllowed) else {
+                        reply.result = .failure(CraftNativeActionError(code: "INVALID_RESPONSE", message: "Invalid recorder response"))
+                        return
+                    }
+                    if failed {
+                        let error = result as? [String: Any] ?? [:]
+                        reply.result = .failure(CraftNativeActionError(code: error["code"] as? String ?? "CRAFT_ERROR", message: error["message"] as? String ?? "Recording failed"))
+                    } else { reply.result = .success(result) }
+                }
+            } }
+        }
+        // The C scope has ended before application code can reenter a bridge.
+        if served, let result = reply.result { completion(result) }
+        else {
+            completion(.failure(CraftNativeActionError(code: "RECORDING_OWNERSHIP_UNSUPPORTED", message: "The linked recorder did not serve its synchronous request")))
+        }
+        return true
+    }
+
 
     private static let image: UnsafeMutableRawPointer? = dlopen(nil, RTLD_NOW)
 
@@ -8843,6 +9120,19 @@ final class CraftZigRuntime: NSObject {
     /// because "is Zig linked" is the first question to ask when an action
     /// behaves like the Swift one after a migration was supposed to move it.
     @objc static var isLinked: Bool { handleActionFn != nil }
+    static var supportsRecordingOwnership: Bool {
+        if !isLinked { return true }
+        guard performRecordingFn != nil,
+              let symbol = dlsym(image, "craft_ios_recording_ownership_version") else { return false }
+        return unsafeBitCast(symbol, to: RecordingOwnershipVersionFn.self)() >= 1
+    }
+
+    static var supportsRecordingIntentIdentity: Bool {
+        if !isLinked { return true }
+        guard performRecordingFn != nil,
+              let symbol = dlsym(image, "craft_ios_recording_ownership_version") else { return false }
+        return unsafeBitCast(symbol, to: RecordingOwnershipVersionFn.self)() >= 2
+    }
 
     /// Give Zig the webview its replies are evaluated against.
     ///
@@ -8963,6 +9253,9 @@ enum CraftWebServices {
                 completion(.failure(CraftNativeActionError(code: "CAPABILITY_DISABLED", message: "\(action) needs the app's web view, which this app does not have")))
                 return
             }
+            if action.hasSuffix("LocationRecording") || action == "getLocationRecordingState" {
+                if CraftZigRuntime.performRecording(action: action, body: body, completion: completion) { return }
+            }
             let id = "native:\(UUID().uuidString)"
             waiting[id] = completion
             coordinator.dispatch(action: action, body: body, callbackId: id)
@@ -9005,6 +9298,17 @@ enum CraftWebServices {
 /// how this codebase accumulated five envelopes.
 @objc(CraftSwiftShim)
 final class CraftSwiftShim: NSObject {
+    /// Called on main by Zig after serializing its native event once. The
+    /// existing page delivery remains in Zig; these are the native listeners.
+    @objc(forwardNativeEvent:payload:)
+    static func forwardNativeEvent(_ event: String, payload: String) {
+        guard CraftWebServices.forwardedEvents.contains(event),
+              let bytes = payload.data(using: .utf8),
+              let detail = try? JSONSerialization.jsonObject(with: bytes) as? [String: Any] else { return }
+        CraftWebServices.forward(event, data: detail)
+        CraftEventManager.shared.sendToAppScript(event, data: detail)
+    }
+
     /// The coordinator serving hand-offs. Set by `makeCoordinator`, or in an
     /// app with no web view by `CraftHybrid.configure`, which holds it.
     static weak var coordinator: CraftWebView.Coordinator?