@craft-native/ios 0.0.237 → 0.0.241

package/templates/CraftNativeScreen.swift

@@ -139,7 +139,7 @@ private enum CraftNativeTreeLayoutBridge {
         var alignItems: UInt32 = 3
         var alignSelf: UInt32 = 0
         var flexWrap: UInt32 = 0
-        var alignContent: UInt32 = 6
+        var alignContent: UInt32 = 5
         var marginTop: Float = 0
         var marginRight: Float = 0
         var marginBottom: Float = 0
@@ -180,7 +180,7 @@ private enum CraftNativeTreeLayoutBridge {
         var alignItems: UInt32 = 3
         var alignSelf: UInt32 = 0
         var flexWrap: UInt32 = 0
-        var alignContent: UInt32 = 6
+        var alignContent: UInt32 = 5
         var marginTop: Float = 0
         var marginRight: Float = 0
         var marginBottom: Float = 0
@@ -222,7 +222,7 @@ private enum CraftNativeTreeLayoutBridge {
         var alignItems: UInt32 = 3
         var alignSelf: UInt32 = 0
         var flexWrap: UInt32 = 0
-        var alignContent: UInt32 = 6
+        var alignContent: UInt32 = 5
         var marginTop: Float = 0
         var marginRight: Float = 0
         var marginBottom: Float = 0
@@ -1171,8 +1171,10 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
     private var authoredHeading: Double?
     private var edgePadding = UIEdgeInsets(top: 24, left: 24, bottom: 24, right: 24)
     private var markerBearings: [String: Double] = [:]
+    private var markerPinColors: [String: UIColor] = [:]
     private var tileOverlay: MKTileOverlay?
     private var tileTemplate: String?
+    private var tileAttributionBottom: NSLayoutConstraint?
     private lazy var tileAttribution: UILabel = {
         let label = UILabel()
         label.font = .systemFont(ofSize: 9)
@@ -1181,7 +1183,9 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         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)])
+        let bottom = label.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -8)
+        tileAttributionBottom = bottom
+        NSLayoutConstraint.activate([label.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -8), bottom, label.leadingAnchor.constraint(greaterThanOrEqualTo: leadingAnchor, constant: 48)])
         return label
     }()
 
@@ -1206,6 +1210,7 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         isScrollEnabled = props["scrollEnabled"] as? Bool ?? true
         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])
         showsCompass = props["showsCompass"] as? Bool ?? false
@@ -1219,6 +1224,7 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         }
         edgePadding = UIEdgeInsets(top: inset("top"), left: inset("left"), bottom: inset("bottom"), right: inset("right"))
         var nextBearings: [String: Double] = [:]
+        var nextPinColors: [String: UIColor] = [:]
         // 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.
@@ -1227,6 +1233,7 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
         var nextMarkers: [String: (coordinate: CLLocationCoordinate2D, title: String?)] = [:]
         var nextHandlers: [String: String] = [:]
         var nextPolylines: [String: (coordinates: [CLLocationCoordinate2D], color: UIColor, width: CGFloat)] = [:]
+        var nextPolylineIDs: [String] = []
         for (index, child) in children.enumerated() {
             guard let node = child as? [String: Any], let rawType = node["type"] as? String else { continue }
             let type = rawType.lowercased()
@@ -1239,6 +1246,7 @@ 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 color = childProps["pinColor"] as? String { nextPinColors[id] = Self.color(color) }
                 if let bearing = Self.numeric(childProps["bearing"]), bearing.isFinite {
                     nextBearings[id] = bearing.truncatingRemainder(dividingBy: 360)
                 }
@@ -1251,11 +1259,13 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
                 let authoredWidth = Self.numeric(childProps["strokeWidth"]) ?? 3
                 let width = CGFloat(authoredWidth)
                 guard authoredWidth.isFinite, width.isFinite, width > 0 else { continue }
+                if nextPolylines[id] == nil { nextPolylineIDs.append(id) }
                 nextPolylines[id] = (points, Self.color(childProps["strokeColor"] as? String), width)
             }
         }
 
         markerBearings = nextBearings
+        markerPinColors = nextPinColors
         let staleMarkers = annotationsByID.keys.filter { nextMarkers[$0] == nil }
         removeAnnotations(staleMarkers.compactMap { annotationsByID.removeValue(forKey: $0) })
         for (id, value) in nextMarkers {
@@ -1282,7 +1292,8 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             }
             overlayCoordinatesByID.removeValue(forKey: id)
         }
-        for (id, value) in nextPolylines {
+        for id in nextPolylineIDs {
+            guard let value = nextPolylines[id] else { continue }
             if let overlay = overlaysByID[id],
                let coordinates = overlayCoordinatesByID[id],
                Self.coordinatesEqual(coordinates, value.coordinates),
@@ -1302,6 +1313,19 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
             overlayWidths[ObjectIdentifier(overlay)] = value.width
             addOverlay(overlay)
         }
+        // Keep authored casing/foreground order when an earlier line changes
+        // or retained children move. Exchanging native overlays preserves the
+        // unchanged objects, tile levels and current camera.
+        let ownedOverlayIDs = Set(overlaysByID.values.map { ObjectIdentifier($0) })
+        var orderedOverlays = overlays.compactMap { $0 as? MKPolyline }
+            .filter { ownedOverlayIDs.contains(ObjectIdentifier($0)) }
+        for (index, id) in nextPolylineIDs.enumerated() {
+            guard let overlay = overlaysByID[id], index < orderedOverlays.count,
+                  orderedOverlays[index] !== overlay,
+                  let previousIndex = orderedOverlays.firstIndex(where: { $0 === overlay }) else { continue }
+            exchangeOverlay(orderedOverlays[index], with: orderedOverlays[previousIndex])
+            orderedOverlays.swapAt(index, previousIndex)
+        }
 
         if let region = Self.region(props["region"]) {
             // `region` is controlled: an authored change is allowed to move
@@ -1411,20 +1435,27 @@ private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
 
     private func configureMarkerView(_ view: MKAnnotationView, id: String) {
         if let bearing = markerBearings[id] {
-            let configuration = UIImage.SymbolConfiguration(pointSize: 24, weight: .semibold)
+            let configuration = UIImage.SymbolConfiguration(pointSize: 16, weight: .semibold)
                 .applying(UIImage.SymbolConfiguration(paletteColors: [.white, .systemGreen]))
-            view.image = UIImage(systemName: "arrow.up.circle.fill", withConfiguration: configuration)
+            // MapKit otherwise tints this as a monochrome template and loses
+            // the contrasting route arrow when displayed over map content.
+            view.image = UIImage(systemName: "arrow.up.circle.fill", withConfiguration: configuration)?
+                .withRenderingMode(.alwaysOriginal)
             view.transform = CGAffineTransform(rotationAngle: CGFloat((bearing - camera.heading) * .pi / 180))
         } else {
+            view.tintColor = markerPinColors[id] ?? .systemRed
             view.image = UIImage(systemName: "mappin.circle.fill", withConfiguration: UIImage.SymbolConfiguration(pointSize: 28))?
-                .withTintColor(.systemRed, renderingMode: .alwaysOriginal)
+                .withTintColor(view.tintColor, renderingMode: .alwaysOriginal)
             view.transform = .identity
         }
     }
 
     override func layoutSubviews() {
         super.layoutSubviews()
-        if tileTemplate != nil { bringSubviewToFront(tileAttribution) }
+        if tileTemplate != nil {
+            tileAttributionBottom?.constant = -min(edgePadding.bottom, max(0, bounds.height - 40)) - 8
+            bringSubviewToFront(tileAttribution)
+        }
         if let region = pendingRegion, bounds.width > 0, bounds.height > 0 {
             pendingRegion = nil
             setRegion(region, animated: false)
@@ -2681,11 +2712,24 @@ private class CraftNativeFlowView: UIStackView {
                 var fixedHeight = style.top != nil && style.bottom != nil
                     ? max(0, content.height - (style.top ?? 0) - (style.bottom ?? 0))
                     : style.height?.resolve(content.height)
+                let authoredWidth = fixedWidth != nil
+                let authoredHeight = fixedHeight != nil
                 (fixedWidth, fixedHeight) = aspectDimensions(style, width: fixedWidth, height: fixedHeight)
-                let measured = CraftNativeFlexLayout.measure(child, width: fixedWidth, height: fixedHeight, maxWidth: content.width, maxHeight: content.height)
-                let x = style.left ?? (style.right.map { content.width - $0 - measured.width } ?? 0)
-                let y = style.top ?? (style.bottom.map { content.height - $0 - measured.height } ?? 0)
-                frames.append((child, CGRect(x: content.minX + x, y: content.minY + y, width: measured.width, height: measured.height)))
+                var measured = CraftNativeFlexLayout.measure(child, width: fixedWidth, height: fixedHeight, maxWidth: content.width, maxHeight: content.height)
+                var boundedWidth = clamp(measured.width, style.minWidth?.resolve(content.width), style.maxWidth?.resolve(content.width))
+                let proposedHeight = !authoredHeight && style.aspectRatio != nil ? boundedWidth / style.aspectRatio! : fixedHeight
+                if abs(boundedWidth - measured.width) > 0.0001 || proposedHeight != fixedHeight {
+                    // A narrower label or container must wrap before its
+                    // height and bottom anchor are resolved.
+                    measured = CraftNativeFlexLayout.measure(child, width: boundedWidth, height: proposedHeight, maxWidth: content.width, maxHeight: content.height)
+                }
+                let boundedHeight = clamp(measured.height, style.minHeight?.resolve(content.height), style.maxHeight?.resolve(content.height))
+                if !authoredWidth, authoredHeight, let ratio = style.aspectRatio {
+                    boundedWidth = clamp(boundedHeight * ratio, style.minWidth?.resolve(content.width), style.maxWidth?.resolve(content.width))
+                }
+                let x = style.left ?? (style.right.map { content.width - $0 - boundedWidth } ?? 0)
+                let y = style.top ?? (style.bottom.map { content.height - $0 - boundedHeight } ?? 0)
+                frames.append((child, CGRect(x: content.minX + x, y: content.minY + y, width: boundedWidth, height: boundedHeight)))
             }
         }
         return (size, frames)
@@ -3370,6 +3414,8 @@ private final class CraftNativeModalView: UIView {
         let generation = animationGeneration
         layer.removeAllAnimations()
         guard visible else {
+            craftScreenController?.forgetFocusedInput(in: self)
+            endEditing(true)
             if animationType == "slide" && wasVisible {
                 let distance = max(bounds.height, superview?.bounds.height ?? UIScreen.main.bounds.height)
                 UIView.animate(withDuration: 0.24, animations: {
@@ -3409,6 +3455,8 @@ private final class CraftNativeModalView: UIView {
     }
 
     func resetForTeardown() {
+        craftScreenController?.forgetFocusedInput(in: self)
+        endEditing(true)
         animationGeneration += 1
         layer.removeAllAnimations()
         isHidden = true
@@ -4326,6 +4374,11 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     func forgetFocusedInput(_ input: UIView? = nil) {
         if input == nil || lastFocusedInput === input { lastFocusedInput = nil }
     }
+    func forgetFocusedInput(in container: UIView) {
+        if let input = lastFocusedInput, input === container || input.isDescendant(of: container) {
+            lastFocusedInput = nil
+        }
+    }
     private var flatListRows: [ObjectIdentifier: [String: RenderedNode]] = [:]
     private var flatListOwners: [String: String] = [:]
     /// A drawing's shapes are not views: a change to one redraws its `Svg`.
@@ -4797,7 +4850,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)
@@ -6048,6 +6107,11 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private func restoreFocus(_ focused: UIView?) {
         guard let focused, focused.window != nil, !focused.isFirstResponder,
               lastFocusedInput === focused, firstResponder(in: rootStack) == nil else { return }
+        var ancestor: UIView? = focused
+        while let view = ancestor {
+            if view.isHidden { return }
+            ancestor = view.superview
+        }
         // A delayed acknowledgement belongs to the input that scheduled it.
         // A newer field or an explicit dismissal owns focus now.
         _ = focused.becomeFirstResponder()
@@ -7497,13 +7561,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

@@ -21,6 +21,7 @@ import Darwin
 ///   tap <text>            first hittable element whose label contains text
 ///   tapif <text>          tap it when it is on screen, else carry on (the big timer's "Show the controls")
 ///   tapid <identifier>
+///   longpressid <identifier> holds a hittable native element to open its edit menu
 ///   touches <JSON>       timed normalized touch paths in one native dispatch
 ///   tapxy <x> <y>         normalised 0…1 of the screen
 ///   tapexact <label>      a button whose label is exactly this
@@ -29,11 +30,14 @@ import Darwin
 ///   return                the keyboard's return key (Go on a sign-in form)
 ///   field <n> <text>      tap the n-th text field (0-based, secure fields after plain) and type
 ///   typeid <identifier> <text>  tap the element with this identifier and type
+///   sliderid <identifier> <0…1> adjusts a hittable native slider
+///   expectapp <bundle-id> [| secs] asserts a native app handoff reached the foreground
 ///   expect <text> [| secs]  waits for an element containing text; logs PASS/FAIL
 ///   expectexact <label> [| secs]  a button or text whose label is exactly this
 ///   absent <text>         logs PASS when no element contains text
 ///   expectid <id> [| secs] / absentid <id>   the same by accessibility identifier (testID)
 ///   labelid <id> <text>   that element's label is exactly text (a count, a status)
+///   valueid <id> <text>   that element's actual string value is exactly text
 ///   tabbar shown|hidden   the native tab bar (Today, Calendar, …) can be tapped, or not
 ///   selected <tab>        the tab bar's selected button is this one
 ///   tab <name>            tap a tab bar button
@@ -53,6 +57,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 +145,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)
@@ -290,6 +301,14 @@ final class DriverTests: XCTestCase {
             let target = identified(arg)
             if target.waitForExistence(timeout: 10) { press(target); note("tapid \(arg): ok") }
             else { XCTFail("Element not found"); note("FAIL tapid \(arg): NOT FOUND") }
+        case "longpressid":
+            let target = identified(arg)
+            guard target.waitForExistence(timeout: 10), target.isHittable else {
+                check(false, "longpressid \(arg) is hittable")
+                return
+            }
+            target.press(forDuration: 1.2)
+            note("longpressid \(arg): ok")
         case "touches":
             do {
                 guard let data = arg.data(using: .utf8),
@@ -360,6 +379,23 @@ final class DriverTests: XCTestCase {
                 app.typeText(idParts.count > 1 ? idParts[1] : "")
                 note("typeid \(idParts[0]): ok")
             } else { XCTFail("Element not found"); note("FAIL typeid \(idParts[0]): NOT FOUND") }
+        case "sliderid":
+            let parts = arg.split(separator: " ", maxSplits: 1).map(String.init)
+            guard parts.count == 2, let position = Double(parts[1]), position.isFinite, (0...1).contains(position) else {
+                check(false, "sliderid requires an identifier and normalized position")
+                return
+            }
+            let slider = app.sliders.matching(NSPredicate(format: "identifier == %@", parts[0])).firstMatch
+            guard slider.waitForExistence(timeout: 10), slider.isHittable else {
+                check(false, "sliderid \(parts[0]) is hittable")
+                return
+            }
+            slider.adjust(toNormalizedSliderPosition: CGFloat(position))
+            note("sliderid \(parts[0]): \(position)")
+        case "expectapp":
+            let (bundle, seconds) = split(arg)
+            let target = XCUIApplication(bundleIdentifier: bundle)
+            check(target.wait(for: .runningForeground, timeout: seconds), "expectapp \(bundle)")
         case "field":
             let fieldParts = arg.split(separator: " ", maxSplits: 1).map(String.init)
             let index = Int(fieldParts[0]) ?? 0
@@ -385,6 +421,14 @@ final class DriverTests: XCTestCase {
             let want = idParts.count > 1 ? idParts[1] : ""
             let seen = target.waitForExistence(timeout: 5) ? target.label : "(missing)"
             check(seen == want, "labelid \(idParts[0]) \(want) (saw \(seen))")
+        case "valueid":
+            let idParts = arg.split(separator: " ", maxSplits: 1).map(String.init)
+            let target = identified(idParts[0])
+            let want = idParts.count > 1 ? idParts[1] : ""
+            let matched = poll(5) {
+                target.exists && (target.value as? String) == want ? target : nil
+            }
+            check(matched != nil, "valueid \(idParts[0]) \(want)")
         case "absentid":
             check(!identified(arg).exists, "absentid \(arg)")
         case "absent":