@craft-native/ios 0.0.236 → 0.0.238

package/templates/CraftNativeScreen.swift

@@ -1161,8 +1161,29 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
     private var overlayWidths: [ObjectIdentifier: CGFloat] = [:]
     private var initialCameraKey: String?
     private var pendingFitKey: String?
+    private var pendingRegion: MKCoordinateRegion?
     private(set) var markerHandlers: [String: String] = [:]
     var onMarkerTap: ((String) -> Void)?
+    var onMapPress: ((CLLocationCoordinate2D) -> Void)?
+    var onRegionChangeComplete: ((MKCoordinateRegion, Double, Double) -> Void)?
+    private var userChangingCamera = false
+    private var authoredPitch: Double?
+    private var authoredHeading: Double?
+    private var edgePadding = UIEdgeInsets(top: 24, left: 24, bottom: 24, right: 24)
+    private var markerBearings: [String: Double] = [:]
+    private var tileOverlay: MKTileOverlay?
+    private var tileTemplate: String?
+    private lazy var tileAttribution: UILabel = {
+        let label = UILabel()
+        label.font = .systemFont(ofSize: 9)
+        label.textColor = .darkGray
+        label.backgroundColor = UIColor.white.withAlphaComponent(0.85)
+        label.translatesAutoresizingMaskIntoConstraints = false
+        label.numberOfLines = 2
+        addSubview(label)
+        NSLayoutConstraint.activate([label.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8), label.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8), label.leadingAnchor.constraint(greaterThanOrEqualTo: leadingAnchor, constant: 48)])
+        return label
+    }()
 
     override init(frame: CGRect) {
         super.init(frame: frame)
@@ -1170,6 +1191,9 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         showsCompass = false
         showsScale = false
         isRotateEnabled = false
+        let tap = UITapGestureRecognizer(target: self, action: #selector(pressedMap(_:)))
+        tap.cancelsTouchesInView = false
+        addGestureRecognizer(tap)
     }
 
     required init?(coder: NSCoder) {
@@ -1183,6 +1207,18 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         isZoomEnabled = props["zoomEnabled"] as? Bool ?? true
         isRotateEnabled = props["rotateEnabled"] as? Bool ?? false
         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"])
+        authoredHeading = Self.numeric(props["cameraHeading"])
+        let padding = props["edgePadding"] as? [String: Any]
+        func inset(_ name: String) -> CGFloat {
+            guard let value = Self.numeric(padding?[name]), value.isFinite else { return 24 }
+            return CGFloat(min(10_000, max(0, value)))
+        }
+        edgePadding = UIEdgeInsets(top: inset("top"), left: inset("left"), bottom: inset("bottom"), right: inset("right"))
+        var nextBearings: [String: Double] = [:]
         // Showing the user dot must not trigger a permission prompt from a
         // renderer pass. The app's existing location capability owns that
         // prompt; a map only opts in after authorization is already granted.
@@ -1203,6 +1239,9 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             if type == "mapmarker" || type == "marker" {
                 guard let point = points.first else { continue }
                 nextMarkers[id] = (point, childProps["title"] as? String)
+                if let bearing = Self.numeric(childProps["bearing"]), bearing.isFinite {
+                    nextBearings[id] = bearing.truncatingRemainder(dividingBy: 360)
+                }
                 if let handler = nonEmptyHandler(childEvents["onPress"])
                     ?? nonEmptyHandler(childEvents["onMarkerPress"]) {
                     nextHandlers[id] = handler
@@ -1216,12 +1255,14 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             }
         }
 
+        markerBearings = nextBearings
         let staleMarkers = annotationsByID.keys.filter { nextMarkers[$0] == nil }
         removeAnnotations(staleMarkers.compactMap { annotationsByID.removeValue(forKey: $0) })
         for (id, value) in nextMarkers {
             if let annotation = annotationsByID[id] {
                 annotation.coordinate = value.coordinate
                 annotation.title = value.title
+                if let view = view(for: annotation) { configureMarkerView(view, id: id) }
             } else {
                 let annotation = MKPointAnnotation()
                 annotation.coordinate = value.coordinate
@@ -1266,17 +1307,24 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             // `region` is controlled: an authored change is allowed to move
             // the camera, even when the map itself was already mounted.
             pendingFitKey = nil
-            setRegion(region, animated: false)
+            pendingRegion = bounds.width > 0 && bounds.height > 0 ? nil : region
+            if abs(self.region.center.latitude - region.center.latitude) > 0.00000001
+                || abs(self.region.center.longitude - region.center.longitude) > 0.00000001
+                || abs(self.region.span.latitudeDelta - region.span.latitudeDelta) > 0.00000001
+                || abs(self.region.span.longitudeDelta - region.span.longitudeDelta) > 0.00000001 {
+                setRegion(region, animated: false)
+            }
             initialCameraKey = nil
         } else if let initial = Self.region(props["initialRegion"]) {
             pendingFitKey = nil
             let key = "region:\(Self.regionKey(initial))"
             if initialCameraKey != key {
+                pendingRegion = bounds.width > 0 && bounds.height > 0 ? nil : initial
                 setRegion(initial, animated: false)
                 initialCameraKey = key
             }
         } else if props["fitToBounds"] as? Bool == true {
-            let key = "fit:\(Self.overlayKey(markers: nextMarkers.mapValues { $0.coordinate }, polylines: nextPolylines.mapValues { $0.coordinates }))"
+            let key = "fit:\(Self.overlayKey(markers: nextMarkers.mapValues { $0.coordinate }, polylines: nextPolylines.mapValues { $0.coordinates })):\(edgePadding)"
             if initialCameraKey != key {
                 // A native screen can reconcile before UIKit assigns the map
                 // its final safe-area-constrained bounds. Keep the fit
@@ -1292,10 +1340,96 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             initialCameraKey = nil
             pendingFitKey = nil
         }
+        applyCameraOrientation()
+    }
+
+    private func configureTiles(_ options: [String: Any]?) {
+        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 let overlay = tileOverlay { removeOverlay(overlay) }
+            tileOverlay = nil
+            tileTemplate = next
+            if let next {
+                let overlay = MKTileOverlay(urlTemplate: next)
+                overlay.canReplaceMapContent = true
+                tileOverlay = overlay
+                insertOverlay(overlay, at: 0, level: .aboveRoads)
+            }
+        }
+        tileAttribution.text = next == nil ? nil : credit
+        tileAttribution.isHidden = next == nil
+    }
+
+    private func applyCameraOrientation() {
+        // Region-to-altitude conversion needs a measured viewport. Applying
+        // pitch to the zero-altitude camera before layout clamps it to zero.
+        guard bounds.width > 0, bounds.height > 0 else { return }
+        let next = camera.copy() as! MKMapCamera
+        var changed = false
+        if let pitch = authoredPitch, pitch.isFinite {
+            let value = CGFloat(min(60, max(0, pitch)))
+            if abs(next.pitch - value) > 0.01 { next.pitch = value; changed = true }
+        }
+        if let heading = authoredHeading, heading.isFinite {
+            let value = heading.truncatingRemainder(dividingBy: 360)
+            if abs(next.heading - value) > 0.01 { next.heading = value; changed = true }
+        }
+        if changed { setCamera(next, animated: false) }
+    }
+
+    @objc private func pressedMap(_ gesture: UITapGestureRecognizer) {
+        guard gesture.state == .ended, onMapPress != nil else { return }
+        let point = gesture.location(in: self)
+        var touched = hitTest(point, with: nil)
+        while let view = touched, view !== self {
+            if view is MKAnnotationView { return }
+            touched = view.superview
+        }
+        onMapPress?(convert(point, toCoordinateFrom: self))
+    }
+
+    func mapView(_ mapView: MKMapView, regionWillChangeAnimated animated: Bool) {
+        func interacting(_ view: UIView) -> Bool {
+            if view.gestureRecognizers?.contains(where: { [.began, .changed, .ended].contains($0.state) }) == true { return true }
+            return view.subviews.contains(where: interacting)
+        }
+        userChangingCamera = userChangingCamera || interacting(self)
+    }
+
+    func mapView(_ mapView: MKMapView, regionDidChangeAnimated animated: Bool) {
+        for (id, annotation) in annotationsByID {
+            if let view = view(for: annotation) { configureMarkerView(view, id: id) }
+        }
+        if userChangingCamera {
+            userChangingCamera = false
+            onRegionChangeComplete?(region, camera.heading, Double(camera.pitch))
+        }
+    }
+
+    private func configureMarkerView(_ view: MKAnnotationView, id: String) {
+        if let bearing = markerBearings[id] {
+            let configuration = UIImage.SymbolConfiguration(pointSize: 24, weight: .semibold)
+                .applying(UIImage.SymbolConfiguration(paletteColors: [.white, .systemGreen]))
+            view.image = UIImage(systemName: "arrow.up.circle.fill", withConfiguration: configuration)
+            view.transform = CGAffineTransform(rotationAngle: CGFloat((bearing - camera.heading) * .pi / 180))
+        } else {
+            view.image = UIImage(systemName: "mappin.circle.fill", withConfiguration: UIImage.SymbolConfiguration(pointSize: 28))?
+                .withTintColor(.systemRed, renderingMode: .alwaysOriginal)
+            view.transform = .identity
+        }
     }
 
     override func layoutSubviews() {
         super.layoutSubviews()
+        if tileTemplate != nil { bringSubviewToFront(tileAttribution) }
+        if let region = pendingRegion, bounds.width > 0, bounds.height > 0 {
+            pendingRegion = nil
+            setRegion(region, animated: false)
+            applyCameraOrientation()
+        }
         guard let key = pendingFitKey else { return }
         pendingFitKey = nil
         guard fitToOverlays() else {
@@ -1303,6 +1437,7 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             return
         }
         initialCameraKey = key
+        applyCameraOrientation()
     }
 
     @discardableResult
@@ -1315,17 +1450,29 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             rect = rect.union(MKMapRect(x: point.x, y: point.y, width: 0, height: 0))
         }
         guard !rect.isNull else { return false }
-        let inset = UIEdgeInsets(top: 24, left: 24, bottom: 24, right: 24)
+        var inset = edgePadding
+        let horizontal = inset.left + inset.right
+        let vertical = inset.top + inset.bottom
+        let availableWidth = max(0, bounds.width - 40)
+        let availableHeight = max(0, bounds.height - 40)
+        if horizontal > availableWidth && horizontal > 0 {
+            inset.left *= availableWidth / horizontal
+            inset.right *= availableWidth / horizontal
+        }
+        if vertical > availableHeight && vertical > 0 {
+            inset.top *= availableHeight / vertical
+            inset.bottom *= availableHeight / vertical
+        }
         setVisibleMapRect(rect, edgePadding: inset, animated: false)
         return true
     }
 
     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") as? MKMarkerAnnotationView)
-            ?? MKMarkerAnnotationView(annotation: annotation, reuseIdentifier: "craft-native-marker")
+        let view = dequeueReusableAnnotationView(withIdentifier: "craft-native-marker")
+            ?? MKAnnotationView(annotation: annotation, reuseIdentifier: "craft-native-marker")
         view.annotation = annotation
-        view.markerTintColor = .systemRed
+        configureMarkerView(view, id: id)
         view.accessibilityIdentifier = id
         return view
     }
@@ -1337,6 +1484,7 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
     }
 
     func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {
+        if let tiles = overlay as? MKTileOverlay { return MKTileOverlayRenderer(tileOverlay: tiles) }
         let renderer = MKPolylineRenderer(overlay: overlay)
         renderer.strokeColor = overlayColors[ObjectIdentifier(overlay)] ?? .systemBlue
         renderer.lineWidth = overlayWidths[ObjectIdentifier(overlay)] ?? 3
@@ -4649,7 +4797,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             CraftNativeConsole.write(level, category: category, message: message)
         }
         let storageGet: @convention(block) (String) -> String? = { key in
-            CraftNativeActions.storageJSON(forKey: key)
+            do { return try CraftNativeActions.storageJSON(forKey: key) }
+            catch {
+                if let context = JSContext.current() {
+                    context.exception = JSValue(newErrorFromMessage: "STORAGE_ERROR: Unable to read stored value", in: context)
+                }
+                return nil
+            }
         }
         let storageSet: @convention(block) (String, JSValue) -> Bool = { key, value in
             CraftNativeActions.setStorageJSON(value.isNull || value.isUndefined ? nil : value.toString(), forKey: key)
@@ -6298,6 +6452,18 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         case "Map":
             let map = result as! CraftNativeMapView
             let mapMarkerHandler = nonEmptyHandler(events["onMarkerPress"])
+            map.onMapPress = { [weak self] coordinate in
+                guard let self, let handler = self.nonEmptyHandler(events["onPress"]) else { return }
+                self.send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["latitude": coordinate.latitude, "longitude": coordinate.longitude]])
+            }
+            map.onRegionChangeComplete = { [weak self] region, heading, pitch in
+                guard let self, let handler = self.nonEmptyHandler(events["onRegionChangeComplete"]) else { return }
+                self.send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": [
+                    "center": ["latitude": region.center.latitude, "longitude": region.center.longitude],
+                    "span": ["latitudeDelta": region.span.latitudeDelta, "longitudeDelta": region.span.longitudeDelta],
+                    "heading": heading, "pitch": pitch,
+                ]])
+            }
             map.configure(props: props, children: children) { [weak self, weak map] markerID in
                 guard let self, let map,
                       let handler = map.markerHandlers[markerID] ?? mapMarkerHandler else { return }
@@ -7337,13 +7503,14 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             .font: font,
         ]
         if let spacing = number(style["letterSpacing"]) { attributes[.kern] = spacing }
+        // UIKit otherwise resets the field's alignment to natural when these attributes are applied.
+        let paragraph = NSMutableParagraphStyle()
+        paragraph.alignment = alignment
         if let lineHeight = number(style["lineHeight"]) {
-            let paragraph = NSMutableParagraphStyle()
             paragraph.minimumLineHeight = lineHeight
             paragraph.maximumLineHeight = lineHeight
-            paragraph.alignment = alignment
-            attributes[.paragraphStyle] = paragraph
         }
+        attributes[.paragraphStyle] = paragraph
         addTextDecorationAttributes(style, to: &attributes)
         if let shadow = textShadow(style) { attributes[.shadow] = shadow }
         return attributes

package/templates/CraftPersistentStorage.swift

@@ -0,0 +1,99 @@
+import CryptoKit
+import Foundation
+import CoreFoundation
+
+/// The existing Storage API's durable, process-wide serialized backing store.
+/// Tombstones prevent an old UserDefaults value from reappearing after removal.
+enum CraftPersistentStorage {
+    private static let lock = NSRecursiveLock()
+    private static var directory: URL {
+        FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0].appendingPathComponent("craft-native-storage")
+    }
+    private static func path(_ key: String, directory: URL) -> URL {
+        let digest = SHA256.hash(data: Data(key.utf8)).map { String(format: "%02x", $0) }.joined()
+        return directory.appendingPathComponent(digest + ".json")
+    }
+    static func get(_ key: String, prefix: String, storageDirectory: URL? = nil) throws -> Data? {
+        lock.lock(); defer { lock.unlock() }
+        let source = path(key, directory: storageDirectory ?? directory)
+        if FileManager.default.fileExists(atPath: source.path) {
+            guard let saved = try JSONSerialization.jsonObject(with: Data(contentsOf: source)) as? [String: Any], saved["key"] as? String == key else {
+                throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Invalid stored value")
+            }
+            if saved["deleted"] as? Bool == true { return nil }
+            guard let value = saved["value"] else { throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Missing stored value") }
+            return try JSONSerialization.data(withJSONObject: value, options: .fragmentsAllowed)
+        }
+        guard let legacy = UserDefaults.standard.data(forKey: prefix + key) else { return nil }
+        // Only valid legacy JSON qualifies for deferred migration on I/O failure.
+        _ = try JSONSerialization.jsonObject(with: legacy, options: .fragmentsAllowed)
+        // Reading a valid legacy checkpoint must survive a full disk. Migration
+        // can be retried on a later read; only a successful set promises a new
+        // durable checkpoint and permits the application to acknowledge it.
+        do { try set(key, data: legacy, prefix: prefix, storageDirectory: storageDirectory) }
+        catch { print("Unable to migrate an existing storage value: \(error)") }
+        return legacy
+    }
+    static func set(_ key: String, data: Data?, prefix: String, storageDirectory: URL? = nil, writer: CraftRecordingArchive.Writer = CraftRecordingArchive.writeAtomically) throws {
+        lock.lock(); defer { lock.unlock() }
+        var entry: [String: Any] = ["key": key, "deleted": data == nil]
+        if let data { entry["value"] = try JSONSerialization.jsonObject(with: data, options: .fragmentsAllowed) }
+        try writer(JSONSerialization.data(withJSONObject: entry), path(key, directory: storageDirectory ?? directory))
+        if let data { UserDefaults.standard.set(data, forKey: prefix + key) }
+        else { UserDefaults.standard.removeObject(forKey: prefix + key) }
+    }
+
+    static func jsonEqual(_ left: Any, _ right: Any) -> Bool {
+        if left is NSNull { return right is NSNull }
+        if let a = left as? NSNumber, let b = right as? NSNumber {
+            let aBoolean = CFGetTypeID(a) == CFBooleanGetTypeID()
+            let bBoolean = CFGetTypeID(b) == CFBooleanGetTypeID()
+            return aBoolean == bBoolean && a.compare(b) == .orderedSame
+        }
+        if let a = left as? String, let b = right as? String { return a == b }
+        if let a = left as? [Any], let b = right as? [Any] {
+            return a.count == b.count && zip(a, b).allSatisfy { jsonEqual($0.0, $0.1) }
+        }
+        if let a = left as? [String: Any], let b = right as? [String: Any] {
+            return a.count == b.count && a.allSatisfy { key, value in b[key].map { jsonEqual(value, $0) } ?? false }
+        }
+        return false
+    }
+
+    /// An existing-key conditional checkpoint, serialized with every reader
+    /// and writer. A deletion that reached this store first can never recreate.
+    static func compareAndSet(_ key: String, expected: Any, value: Any, prefix: String, storageDirectory: URL? = nil, writer: CraftRecordingArchive.Writer = CraftRecordingArchive.writeAtomically) throws -> Bool {
+        lock.lock(); defer { lock.unlock() }
+        guard let data = try get(key, prefix: prefix, storageDirectory: storageDirectory) else { return false }
+        let current = try JSONSerialization.jsonObject(with: data, options: .fragmentsAllowed)
+        guard jsonEqual(current, expected) else { return false }
+        let next = try JSONSerialization.data(withJSONObject: value, options: .fragmentsAllowed)
+        try set(key, data: next, prefix: prefix, storageDirectory: storageDirectory, writer: writer)
+        return true
+    }
+
+    static func setIfAbsent(_ key: String, value: Any, prefix: String, storageDirectory: URL? = nil, writer: CraftRecordingArchive.Writer = CraftRecordingArchive.writeAtomically) throws -> Bool {
+        lock.lock(); defer { lock.unlock() }
+        guard try get(key, prefix: prefix, storageDirectory: storageDirectory) == nil else { return false }
+        let next = try JSONSerialization.data(withJSONObject: value, options: .fragmentsAllowed)
+        try set(key, data: next, prefix: prefix, storageDirectory: storageDirectory, writer: writer)
+        return true
+    }
+    static func keys(prefix: String) throws -> [String] {
+        lock.lock(); defer { lock.unlock() }
+        var result = Set(UserDefaults.standard.dictionaryRepresentation().keys.filter { $0.hasPrefix(prefix) }.map { String($0.dropFirst(prefix.count)) })
+        if FileManager.default.fileExists(atPath: directory.path) {
+            for source in try FileManager.default.contentsOfDirectory(at: directory, includingPropertiesForKeys: nil) where source.pathExtension == "json" {
+                guard let entry = try JSONSerialization.jsonObject(with: Data(contentsOf: source)) as? [String: Any], let key = entry["key"] as? String else {
+                    throw CraftNativeActionError(code: "STORAGE_CORRUPT", message: "Invalid stored value")
+                }
+                if entry["deleted"] as? Bool == true { result.remove(key) } else { result.insert(key) }
+            }
+        }
+        return result.sorted()
+    }
+    static func clear(prefix: String) throws {
+        lock.lock(); defer { lock.unlock() }
+        for key in try keys(prefix: prefix) { try set(key, data: nil, prefix: prefix) }
+    }
+}

package/templates/CraftRecordingArchive.swift

@@ -0,0 +1,85 @@
+import CryptoKit
+import Foundation
+import Darwin
+
+/// Immutable completed recordings and durable acknowledgement tombstones.
+/// IDs are opaque values; their SHA-256, never caller path text, names a file.
+enum CraftRecordingArchive {
+    typealias Writer = (Data, URL) throws -> Void
+    static func writeAtomically(_ data: Data, _ url: URL) throws {
+        try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+        let temporary = url.deletingLastPathComponent().appendingPathComponent(".craft-atomic-" + UUID().uuidString)
+        defer { try? FileManager.default.removeItem(at: temporary) }
+        try data.write(to: temporary, options: .withoutOverwriting)
+        let file = try FileHandle(forWritingTo: temporary)
+        do { try file.synchronize(); try file.close() }
+        catch { try? file.close(); throw error }
+        try FileManager.default.setAttributes([.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication], ofItemAtPath: temporary.path)
+        var protected = temporary
+        var values = URLResourceValues()
+        values.isExcludedFromBackup = true
+        try protected.setResourceValues(values)
+        let result = temporary.path.withCString { source in url.path.withCString { destination in Darwin.rename(source, destination) } }
+        if result != 0 { throw NSError(domain: NSPOSIXErrorDomain, code: Int(errno)) }
+    }
+
+    private static func url(_ directory: URL, _ kind: String, _ id: String, acknowledged: Bool = false) -> URL {
+        let digest = SHA256.hash(data: Data(id.utf8)).map { String(format: "%02x", $0) }.joined()
+        return directory.appendingPathComponent("craft-\(kind)-\(acknowledged ? "ack" : "completed")-\(digest).json")
+    }
+    static func startId(_ options: [String: Any], directory: URL, kind: String, currentId: String?) throws -> String {
+        let id: String
+        if options.keys.contains("recordingId") {
+            guard let requested = options["recordingId"] as? String,
+                  !requested.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+                throw CraftNativeActionError(code: "INVALID_ARGUMENT", message: "recordingId must be a nonempty recording ID")
+            }
+            id = requested
+        } else { id = UUID().uuidString }
+        let acknowledged = try isAcknowledged(directory, kind, id)
+        if id == currentId || acknowledged || FileManager.default.fileExists(atPath: url(directory, kind, id).path) {
+            throw CraftNativeActionError(code: "RECORDING_CONFLICT", message: "Recording IDs cannot be reused")
+        }
+        return id
+    }
+    static func isAcknowledged(_ directory: URL, _ kind: String, _ id: String) throws -> Bool {
+        let marker = url(directory, kind, id, acknowledged: true)
+        guard FileManager.default.fileExists(atPath: marker.path) else { return false }
+        guard try Data(contentsOf: marker) == Data(id.utf8) else {
+            throw CraftNativeActionError(code: "RECORDING_STORAGE_ERROR", message: "Invalid recording acknowledgement")
+        }
+        return true
+    }
+    static func read(_ directory: URL, _ kind: String, _ id: String) throws -> [String: Any]? {
+        if try isAcknowledged(directory, kind, id) {
+            try acknowledge(directory, kind, id)
+            throw CraftNativeActionError(code: "RECORDING_NOT_FOUND", message: "This recording has been acknowledged")
+        }
+        let source = url(directory, kind, id)
+        guard FileManager.default.fileExists(atPath: source.path) else { return nil }
+        let data = try Data(contentsOf: source)
+        guard let value = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+              value["id"] as? String == id, value["active"] as? Bool == false,
+              value[kind == "location" ? "locations" : "samples"] is [[String: Any]] else {
+            throw CraftNativeActionError(code: "RECORDING_STORAGE_ERROR", message: "Invalid completed recording archive")
+        }
+        return value
+    }
+    static func save(_ directory: URL, _ kind: String, _ state: [String: Any], samples: [[String: Any]], writer: Writer = writeAtomically) throws {
+        guard let id = state["id"] as? String else { return }
+        if try isAcknowledged(directory, kind, id) { try acknowledge(directory, kind, id); return }
+        if try read(directory, kind, id) != nil { return }
+        var completed = state
+        completed["active"] = false
+        completed["paused"] = false
+        completed["sampleCount"] = samples.count
+        completed[kind == "location" ? "locations" : "samples"] = samples
+        try writer(JSONSerialization.data(withJSONObject: completed), url(directory, kind, id))
+    }
+    static func acknowledge(_ directory: URL, _ kind: String, _ id: String) throws {
+        let marker = url(directory, kind, id, acknowledged: true)
+        if try !isAcknowledged(directory, kind, id) { try writeAtomically(Data(id.utf8), marker) }
+        let archive = url(directory, kind, id)
+        if FileManager.default.fileExists(atPath: archive.path) { try FileManager.default.removeItem(at: archive) }
+    }
+}

package/templates/testing/DriverTests.swift.template

@@ -53,6 +53,7 @@ final class DriverTests: XCTestCase {
     let control = ProcessInfo.processInfo.environment["CRAFT_TEST_CONTROL"] ?? {{CONTROL_URL}}
     let app = XCUIApplication(bundleIdentifier: {{BUNDLE_ID}})
     let tabs: [String] = {{TABS}}
+    let tabIdentifiers: [String: String] = {{TAB_IDENTIFIERS}}
     private var bundledJourney = false
 
     func get(_ path: String, timeout: Double = 15) -> Data? {
@@ -140,9 +141,15 @@ final class DriverTests: XCTestCase {
 
     /// The native tab bar's button: Craft's floating bar is not a UITabBar, and
     /// XCUITest calls its buttons not hittable, so it is the button with this
-    /// label in the bottom fifth of the window.
+    /// label in the bottom fifth of the window. A configured stable identifier
+    /// keeps dynamic captions from changing the tab's native identity.
     func tabButton(_ name: String) -> XCUIElement? {
         let height = app.windows.firstMatch.frame.height
+        if let identifier = tabIdentifiers[name] {
+            let candidate = app.buttons.matching(NSPredicate(format: "identifier == %@", identifier)).firstMatch
+            if candidate.exists && candidate.frame.minY > height * 0.8 && candidate.frame.maxY <= height + 1 && candidate.frame.width > 0 { return candidate }
+            return nil
+        }
         let matches = app.buttons.matching(NSPredicate(format: "label == %@", name))
         for index in 0..<min(matches.count, 10) {
             let candidate = matches.element(boundBy: index)