craft-native 0.0.424 → 0.0.436

package/dist/ios/templates/CraftNativeScreen.swift

@@ -2716,6 +2716,8 @@ enum CraftNativeFlexLayout {
                 ? label.sizeThatFits(CGSize(width: resolvedWidth, height: unbounded)).height
                 : maxContent.height)
             return CGSize(width: resolvedWidth, height: resolvedHeight)
+        case let image as CraftNativePositionedImageView where image.image == nil:
+            return CGSize(width: width ?? 0, height: height ?? 0)
         case let image as UIImageView where image.image == nil:
             return CGSize(width: width ?? 0, height: height ?? 0)
         default:
@@ -4165,25 +4167,37 @@ private extension UIImage {
 }
 
 /// Explicit CSS-facing image geometry; the loader and semantic view stay retained.
-class CraftNativePositionedImageView: UIImageView {
+class CraftNativePositionedImageView: UIView {
     private var storedImage: UIImage?
-    private var fittedImage: UIImageView?
+    private let fittedImage = UIImageView()
     private var fit: String?
     private var position = CGPoint(x: 0.5, y: 0.5)
 
-    override var image: UIImage? {
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        isUserInteractionEnabled = false
+        fittedImage.isUserInteractionEnabled = false
+        fittedImage.isAccessibilityElement = false
+        addSubview(fittedImage)
+    }
+
+    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+    // Keep source identity separate from UIKit's image renderer. A UIImageView
+    // host with this stored-image getter painted an extra copy even with
+    // super.image set to nil; only the child owns image drawing now.
+    var image: UIImage? {
         get { storedImage }
         set {
             storedImage = newValue
-            super.image = fit == nil ? newValue : nil
-            fittedImage?.image = newValue
+            fittedImage.image = newValue
             invalidateIntrinsicContentSize()
             setNeedsLayout()
         }
     }
 
     override var intrinsicContentSize: CGSize {
-        fit == nil ? super.intrinsicContentSize : storedImage?.craftIntrinsicSize ?? CGSize(width: UIView.noIntrinsicMetric, height: UIView.noIntrinsicMetric)
+        fit == nil ? fittedImage.intrinsicContentSize : storedImage?.craftIntrinsicSize ?? CGSize(width: UIView.noIntrinsicMetric, height: UIView.noIntrinsicMetric)
     }
 
     func configureObjectGeometry(props: [String: Any], style: [String: Any]) {
@@ -4197,22 +4211,28 @@ class CraftNativePositionedImageView: UIImageView {
             let requested = rawFit as? String ?? "fill"
             fit = ["fill", "contain", "cover", "none", "scale-down"].contains(requested) ? requested : "fill"
             position = Self.objectPosition(rawPosition)
-            if fittedImage == nil {
-                let child = UIImageView()
-                child.isUserInteractionEnabled = false
-                child.isAccessibilityElement = false
-                child.contentMode = .scaleToFill
-                insertSubview(child, at: 0)
-                fittedImage = child
-            }
         } else { fit = nil }
-        fittedImage?.isHidden = fit == nil
-        super.image = fit == nil ? storedImage : nil
-        fittedImage?.image = storedImage
+        fittedImage.contentMode = fit == nil ? contentMode : .scaleToFill
         invalidateIntrinsicContentSize()
         setNeedsLayout()
     }
 
+    override var contentMode: UIView.ContentMode {
+        didSet {
+            fittedImage.contentMode = fit == nil ? contentMode : .scaleToFill
+            setNeedsLayout()
+        }
+    }
+
+    override func sizeThatFits(_ size: CGSize) -> CGSize {
+        fit == nil ? fittedImage.sizeThatFits(size) : intrinsicContentSize
+    }
+
+    override func tintColorDidChange() {
+        super.tintColorDidChange()
+        fittedImage.tintColor = tintColor
+    }
+
     var usesObjectGeometry: Bool { fit != nil }
     var objectCovers: Bool { fit == "cover" }
 
@@ -4234,7 +4254,8 @@ class CraftNativePositionedImageView: UIImageView {
 
     override func layoutSubviews() {
         super.layoutSubviews()
-        guard let fit, let child = fittedImage else { return }
+        let child = fittedImage
+        guard let fit else { child.frame = bounds; return }
         let source = storedImage?.craftIntrinsicSize ?? .zero
         guard source.width > 0, source.height > 0 else { child.frame = .zero; return }
         let contain = min(bounds.width / source.width, bounds.height / source.height)
@@ -9203,7 +9224,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         case "Icon":
             configureIcon(result as! UIImageView, props: props, style: style)
         case "Image":
-            let image = result as! UIImageView
+            let image = result as! CraftNativePositionedImageView
             let imageID = ObjectIdentifier(image)
             if let tint = color(style["tintColor"]) {
                 tintedImages.insert(imageID)
@@ -9215,7 +9236,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if let current = image.image { image.image = imageForDisplay(current, view: image) }
             let requestedResizeMode = style["resizeMode"] as? String ?? props["resizeMode"] as? String
             image.contentMode = imageContentMode(requestedResizeMode)
-            (image as? CraftNativePositionedImageView)?.configureObjectGeometry(props: props, style: style)
+            image.configureObjectGeometry(props: props, style: style)
             applyImageClipping(image, contentMode: image.contentMode, style: style)
             updateAuxiliaryHandler(events["onLoadStart"], in: &imageLoadStartHandlers, for: image)
             updateAuxiliaryHandler(events["onLoad"], in: &imageLoadHandlers, for: image)
@@ -10347,7 +10368,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         view.clipsToBounds = overflow == "hidden"
             || (view is UIScrollView && overflow != "visible")
             || (view is UILabel && (view.craftRequestedCornerRadius ?? 0) > 0)
-            || (view is UIImageView && (borderRadius > 0 || hasCornerRadii))
+            || ((view is UIImageView || view is CraftNativePositionedImageView) && (borderRadius > 0 || hasCornerRadii))
             // Per-corner rounding clips its content, as its mask did.
             || hasCornerRadii
         view.layer.masksToBounds = view.clipsToBounds
@@ -10659,7 +10680,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// The pixels a picture is drawn at, when its style fixes its size (a
     /// 40-point avatar, a card's photo): nil otherwise, for a picture whose
     /// own size lays it out, which must keep its full size.
-    static func displayPixels(of view: UIImageView) -> (size: CGSize, scale: CGFloat)? {
+    static func displayPixels(of view: UIView) -> (size: CGSize, scale: CGFloat)? {
         let style = view.craftLayoutStyle
         let points: CGSize
         switch (style.width, style.height, style.aspectRatio) {
@@ -10742,16 +10763,16 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         return candidate
     }
 
-    private func applyImageClipping(_ view: UIImageView, contentMode: UIView.ContentMode, style: [String: Any]) {
+    private func applyImageClipping(_ view: CraftNativePositionedImageView, contentMode: UIView.ContentMode, style: [String: Any]) {
         let authored = (style["overflow"] as? String) == "hidden"
             || (view.craftRequestedCornerRadius ?? 0) > 0
             || view.craftRequestedCornerRadii != nil
-        let clips = authored || contentMode == .scaleAspectFill || (view as? CraftNativePositionedImageView)?.usesObjectGeometry == true
+        let clips = authored || contentMode == .scaleAspectFill || view.usesObjectGeometry
         view.clipsToBounds = clips
         view.layer.masksToBounds = clips
     }
 
-    private func updateImage(_ view: UIImageView, source: Any?, defaultSource: Any? = nil) {
+    private func updateImage(_ view: CraftNativePositionedImageView, source: Any?, defaultSource: Any? = nil) {
         let sourceObject = source as? [String: Any]
         let uri = (source as? String) ?? sourceObject?["uri"] as? String
         let headers = (sourceObject?["headers"] as? [String: Any])?.reduce(into: [String: String]()) { result, entry in
@@ -10793,7 +10814,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         if let url = imageURL(for: uri) {
             // Decoded at the size it is drawn, when the style fixes that size.
             let pixels = Self.displayPixels(of: view)
-            let fill = (view as? CraftNativePositionedImageView)?.objectCovers == true || view.contentMode == .scaleAspectFill
+            let fill = view.objectCovers || view.contentMode == .scaleAspectFill
             // media.keep owns private/offline copies keyed by the authored URL.
             // Read before the decoded/network cache, without retaining private
             // pixels there after the app clears its media on sign-out.
@@ -10884,7 +10905,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         return !uri.contains(":") ? UIImage(named: uri) : nil
     }
 
-    private func imageFailure(_ view: UIImageView, uri: String?, message: String) {
+    private func imageFailure(_ view: CraftNativePositionedImageView, uri: String?, message: String) {
         imageErrors[ObjectIdentifier(view)] = message
         view.image = nil
         imageDidChange(view)
@@ -10895,19 +10916,19 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         NSLog("[craft native] %@: %@", message, uri ?? "<missing>")
     }
 
-    private func imageDidChange(_ view: UIImageView) {
+    private func imageDidChange(_ view: CraftNativePositionedImageView) {
         view.invalidateIntrinsicContentSize()
         CraftNativeFlexLayout.invalidateAncestors(of: view)
     }
 
-    private func imageForDisplay(_ image: UIImage, view: UIImageView) -> UIImage {
+    private func imageForDisplay(_ image: UIImage, view: CraftNativePositionedImageView) -> UIImage {
         let displayed = image.withRenderingMode(tintedImages.contains(ObjectIdentifier(view)) ? .alwaysTemplate : .alwaysOriginal)
         displayed.craftIntrinsicSize = image.craftIntrinsicSize
         return displayed
     }
 
     private func emitImageEvent(
-        _ view: UIImageView,
+        _ view: CraftNativePositionedImageView,
         handler: String?,
         nativeEvent: [String: Any] = [:]
     ) {
@@ -10961,7 +10982,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         switch role ?? type.lowercased() {
         case "tablist": traits.insert(.tabBar)
         case "button", "checkbox": traits.insert(.button)
-        case "image": traits.insert(.image)
+        case "image", "imagebackground": traits.insert(.image)
         case "header": traits.insert(.header)
         case "link": traits.insert(.link)
         case "search": traits.insert(.searchField)
@@ -11023,11 +11044,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     @objc private func buttonPressed(_ sender: UIButton) {
         let focused = firstResponder(in: rootStack) ?? lastFocusedInput
-        if let target = linkTargets[ObjectIdentifier(sender)] {
-        hybridEvents?.nativeScreen(self, open: target, props: [:])
+        let id = ObjectIdentifier(sender)
+        // An authored handler owns navigation; the asynchronous bridge cannot
+        // wait for preventDefault before opening the link.
+        guard let handler = handlers[id] else {
+            if let target = linkTargets[id] { hybridEvents?.nativeScreen(self, open: target, props: [:]) }
             return
         }
-        guard let handler = handlers[ObjectIdentifier(sender)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": [:]])
         restoreFocus(focused)
         DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) { [weak self, weak focused] in
@@ -11191,7 +11214,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     @objc private func solidSwitchChanged(_ sender: CraftNativeSolidSwitch) {
         guard sender.isEnabled, let handler = handlers[ObjectIdentifier(sender)] else { return }
-        send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["value": sender.isOn]])
+        sendAfterThumb(handler: handler, value: sender.isOn)
     }
 
     @objc private func switchChanged(_ sender: UISwitch) {
@@ -11202,7 +11225,28 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             self.switchUserValues.removeValue(forKey: id)
         }
         guard let handler = handlers[id] else { return }
-        send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["value": sender.isOn]])
+        sendAfterThumb(handler: handler, value: sender.isOn)
+    }
+
+    /// A switch's value, told to the script after UIKit has been left to draw
+    /// the thumb.
+    ///
+    /// On the default main-thread script a handler runs inline, inside the
+    /// control's own action, so the touch's CATransaction stays open until the
+    /// script has finished its work and whatever render it causes. UIKit has
+    /// already set the new value by then, so the thumb does not travel: the
+    /// switch sits still for as long as the script takes and then appears in
+    /// its new state. Yielding the runloop turn first lets that transaction
+    /// commit, the animation is handed to the render server, and the script's
+    /// work no longer holds the thumb. A background script never blocks the
+    /// main thread, so it is told at once.
+    private func sendAfterThumb(handler: String, value: Bool) {
+        let payload: [String: Any] = ["handlerName": handler, "nativeEvent": ["value": value]]
+        guard !CraftNativeScriptThread.isBackground else {
+            send(type: "EVENT", payload: payload)
+            return
+        }
+        DispatchQueue.main.async { [weak self] in self?.send(type: "EVENT", payload: payload) }
     }
 
     @objc private func sliderChanged(_ sender: UISlider) {
@@ -11385,11 +11429,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     @objc private func viewPressed(_ sender: UITapGestureRecognizer) {
         guard let view = sender.view else { return }
         let id = ObjectIdentifier(view)
-        if let target = linkTargets[id] {
-        hybridEvents?.nativeScreen(self, open: target, props: [:])
+        guard let handler = handlers[id] else {
+            if let target = linkTargets[id] { hybridEvents?.nativeScreen(self, open: target, props: [:]) }
             return
         }
-        guard let handler = handlers[id] else { return }
         if pressInHandlers[id] == nil, pressOutHandlers[id] == nil,
            let pressable = view as? CraftNativeFlowView, let activeOpacity = pressable.pressActiveOpacity {
             UIView.animate(withDuration: 0.1, animations: { pressable.alpha = pressable.pressBaseOpacity * activeOpacity }) { _ in

package/dist/ios/templates/CraftVoiceRecording.swift

@@ -69,6 +69,7 @@ final class CraftVoiceRecording {
         var recorder: CraftVoiceRecorder? // audio queue only
         var completion: ((Result<Any, CraftNativeActionError>) -> Void)? // main only
         var deadline: DispatchWorkItem?
+        var stopping = false // main only
         private let lock = NSLock()
         private var cancelled = false
         init(key: String, completion: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
@@ -86,15 +87,29 @@ final class CraftVoiceRecording {
         }
     }
     private var current: Session?
+    /// Each microphone step in the unified log (`subsystem == "craft.native"`,
+    /// category `voice-recording`), so a recording that never finished says
+    /// whether its stop arrived, and where AVFoundation held it.
+    private static func trace(_ message: String) {
+        CraftNativeConsole.write("info", category: "voice-recording", message: message)
+    }
     private let audioQueue: DispatchQueue
     private let permission: (@escaping (Bool) -> Void) -> Void
     private let makeRecorder: (URL) throws -> CraftVoiceRecorder
     private let deactivate: () -> Void
+    /// Releasing the audio session runs here, never on `audioQueue`: a
+    /// deactivation that stalls (seen on simulators with a virtual input)
+    /// must not hold the next recording's start or stop behind it.
+    private let releaseQueue = DispatchQueue(label: "craft.voice-recording-release", qos: .utility)
+    private let generationLock = NSLock()
+    private var generation = 0
     private let startupTimeout: TimeInterval
+    private let stopTimeout: TimeInterval
     private var backgroundObserver: NSObjectProtocol?
 
     init(audioQueue: DispatchQueue = DispatchQueue(label: "craft.voice-recording", qos: .userInitiated),
          startupTimeout: TimeInterval = 15,
+         stopTimeout: TimeInterval = 10,
          permission: @escaping (@escaping (Bool) -> Void) -> Void = { answer in
              #if CRAFT_PERMISSION_MICROPHONE
              AVAudioSession.sharedInstance().requestRecordPermission(answer)
@@ -116,6 +131,7 @@ final class CraftVoiceRecording {
         Self.prepareForLaunch()
         self.audioQueue = audioQueue
         self.startupTimeout = startupTimeout
+        self.stopTimeout = stopTimeout
         self.permission = permission
         self.makeRecorder = makeRecorder
         self.deactivate = deactivate
@@ -128,7 +144,17 @@ final class CraftVoiceRecording {
         session.recorder?.stop()
         session.recorder = nil
         if let file = session.file { CraftNativeFiles.remove(file.path) }
-        deactivate()
+        releaseAudioSession()
+    }
+
+    /// Deactivate off the recording queue, and not at all once a newer
+    /// recording has started: it would only take the microphone from it.
+    private func releaseAudioSession() {
+        let mine = generationLock.withLock { generation }
+        releaseQueue.async { [weak self] in
+            guard let self, self.generationLock.withLock({ self.generation }) == mine else { return }
+            self.deactivate()
+        }
     }
 
     private func clear(_ error: CraftNativeActionError = CraftNativeActionError(code: "RECORDING_CANCELLED", message: "Recording was cancelled")) {
@@ -150,6 +176,7 @@ final class CraftVoiceRecording {
     private func performOnMain(method: String, args: [Any], isActive: @escaping () -> Bool, completion: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
         func fail(_ code: String, _ message: String) { completion(.failure(CraftNativeActionError(code: code, message: message))) }
         guard let key = args.first as? String, UUID(uuidString: key) != nil else { fail("INVALID_ARGUMENT", "A recording owner UUID is required"); return }
+        Self.trace("\(method) \(key.prefix(8)) (current \(current.map { String($0.key.prefix(8)) } ?? "none"))")
         if method == "cancel" {
             if current?.key == key { clear() }
             completion(.success(true))
@@ -157,11 +184,36 @@ final class CraftVoiceRecording {
         }
         if method == "stop" {
             guard let session = current, session.key == key, let file = session.file else { fail("RECORDING_NOT_FOUND", "This recording is no longer available"); return }
+            guard !session.stopping else { fail("RECORDING_BUSY", "This recording is already finishing"); return }
+            session.stopping = true
+            // Answered exactly once: by the encoder's result, or by the
+            // deadline when AVFoundation never returns (a stalled encoder or
+            // audio route), which then erases the recording like a cancel.
+            var settled = false
+            var timeout: DispatchWorkItem?
+            func settle(_ result: Result<Any, CraftNativeActionError>) {
+                timeout?.cancel()
+                guard !settled else { return }
+                settled = true
+                completion(result)
+            }
+            let late = CraftNativeActionError(code: "RECORDING_TIMEOUT", message: "The recording took too long to finish. Please try again.")
+            timeout = DispatchWorkItem { [weak self] in
+                guard !settled else { return }
+                Self.trace("stop \(key.prefix(8)) timed out waiting for the encoder")
+                if let self, self.current === session { self.clear(late) }
+                settle(.failure(late))
+            }
+            DispatchQueue.main.asyncAfter(deadline: .now() + stopTimeout, execute: timeout!)
             audioQueue.async {
-                guard !session.isCancelled else { return DispatchQueue.main.async { fail("RECORDING_CANCELLED", "Recording was cancelled") } }
+                guard !session.isCancelled else {
+                    return DispatchQueue.main.async { settle(.failure(CraftNativeActionError(code: "RECORDING_CANCELLED", message: "Recording was cancelled"))) }
+                }
                 session.recorder?.stop()
                 session.recorder = nil
-                self.deactivate()
+                Self.trace("stop \(key.prefix(8)): encoder stopped")
+                // Read the finished file before releasing the audio session:
+                // the answer must not wait on a deactivation that can stall.
                 let result: Result<Any, CraftNativeActionError>
                 if let audio = try? AVAudioFile(forReading: file), audio.length > 0 {
                     let duration = Double(audio.length) / audio.processingFormat.sampleRate
@@ -170,14 +222,17 @@ final class CraftVoiceRecording {
                     result = .failure(CraftNativeActionError(code: "EMPTY_RECORDING", message: "The recording was empty"))
                 }
                 DispatchQueue.main.async {
+                    guard !settled else { return }
                     guard self.current === session, isActive(), !session.isCancelled else {
                         if self.current === session { self.clear() }
-                        fail("RECORDING_CANCELLED", "Recording was cancelled")
+                        settle(.failure(CraftNativeActionError(code: "RECORDING_CANCELLED", message: "Recording was cancelled")))
                         return
                     }
                     if case .failure = result { self.clear() }
-                    completion(result)
+                    Self.trace("stop \(key.prefix(8)) answered")
+                    settle(result)
                 }
+                self.releaseAudioSession()
             }
             return
         }
@@ -209,6 +264,7 @@ final class CraftVoiceRecording {
                 self.audioQueue.async {
                     do {
                         guard !session.isCancelled else { return }
+                        self.generationLock.withLock { self.generation += 1 }
                         session.recorder = try self.makeRecorder(file)
                         guard !session.isCancelled else { self.erase(session); return }
                         guard session.recorder?.record(forDuration: max(0.5, seconds - 0.25)) == true else {
@@ -220,6 +276,7 @@ final class CraftVoiceRecording {
                                 if self.current === session { self.clear() }
                                 return
                             }
+                            Self.trace("start \(key.prefix(8)): recording")
                             session.finish(.success(true))
                         }
                     }

package/dist/ios/templates/testing/CraftTimedInput.m

@@ -1,6 +1,8 @@
 #import "CraftTimedInput.h"
 #import <UIKit/UIKit.h>
 #import <math.h>
+#import <dlfcn.h>
+#import <XCTest/XCTest.h>
 
 // XCTest's own touch-record API is private. Look up classes and check every
 // selector at runtime; unsupported Xcode versions fail rather than skipping or
@@ -12,6 +14,16 @@
 - (id)initWithName:(NSString *)name interfaceOrientation:(NSInteger)orientation;
 - (void)addPointerEventPath:(id)path;
 - (BOOL)synthesizeWithError:(NSError **)error;
++ (id)eventStreamWithEventActions:(void (^)(id))actions;
+- (void)advanceTime:(double)seconds;
+- (void)touchDown:(CGPoint)point;
+- (void)liftUp:(CGPoint)point;
+- (id)underlyingPlayer;
+- (BOOL)prewarmForEventStream:(id)stream withError:(NSError **)error;
+- (void)setNeedsInitialDelay:(BOOL)value;
+- (void)setIgnoresCompletionDelay:(BOOL)value;
+- (void)playEventStream:(id)stream options:(id)options completion:(void (^)(void))completion;
+- (void)tearDown;
 @end
 
 @implementation CraftTimedInput
@@ -21,6 +33,68 @@
     return NO;
 }
 
+// The simulator's XCTest touch-path translator omits idle intervals between
+// fingers and rounds stationary moves to its sample interval. Submit stationary,
+// non-overlapping taps as one native HID stream with explicit clock advances.
+// Moving/overlapping paths retain the existing XCTest gesture implementation.
++ (BOOL)synthesizeStationaryPaths:(NSArray *)paths frame:(CGRect)frame error:(NSError **)error {
+    static dispatch_once_t once;
+    static void *recap;
+    dispatch_once(&once, ^{
+        recap = dlopen("/System/Library/PrivateFrameworks/Recap.framework/Recap", RTLD_NOW | RTLD_LOCAL);
+    });
+    Class streamClass = NSClassFromString(@"RCPSyntheticEventStream");
+    Class playerClass = NSClassFromString(@"RCPInlinePlayer");
+    if (!recap || ![streamClass respondsToSelector:@selector(eventStreamWithEventActions:)])
+        return [self fail:@"Native timed tap streams are unavailable on this runtime" error:error];
+    for (NSString *name in @[@"advanceTime:", @"touchDown:", @"liftUp:"])
+        if (![streamClass instancesRespondToSelector:NSSelectorFromString(name)])
+            return [self fail:@"Native timed tap stream cannot preserve the schedule" error:error];
+    for (NSString *name in @[@"underlyingPlayer", @"setNeedsInitialDelay:", @"setIgnoresCompletionDelay:",
+                             @"playEventStream:options:completion:", @"tearDown"])
+        if (![playerClass instancesRespondToSelector:NSSelectorFromString(name)])
+            return [self fail:@"Native timed tap playback is unavailable" error:error];
+
+    id stream = [streamClass eventStreamWithEventActions:^(id builder) {
+        double previous = 0;
+        for (NSArray *points in paths) {
+            NSDictionary *first = points.firstObject, *last = points.lastObject;
+            double start = [first[@"at"] doubleValue], end = [last[@"at"] doubleValue];
+            CGPoint point = CGPointMake(frame.origin.x + [first[@"x"] doubleValue] * frame.size.width,
+                                         frame.origin.y + [first[@"y"] doubleValue] * frame.size.height);
+            [builder advanceTime:start - previous];
+            [builder touchDown:point];
+            [builder advanceTime:end - start];
+            [builder liftUp:point];
+            previous = end;
+        }
+    }];
+    if (!stream) return [self fail:@"Native timed tap stream could not be constructed" error:error];
+    id player = [playerClass new];
+    id underlying = [player underlyingPlayer];
+    if (![underlying respondsToSelector:@selector(prewarmForEventStream:withError:)]) {
+        [player tearDown];
+        return [self fail:@"Native timed tap delivery cannot be prepared" error:error];
+    }
+    // Preparing the HID delivery service emits no touches. Do not add a warm-up
+    // touch or an initial/completion sleep to make the receiver appear reliable.
+    if (![underlying prewarmForEventStream:stream withError:error]) {
+        [player tearDown];
+        return NO;
+    }
+    [player setNeedsInitialDelay:NO];
+    [player setIgnoresCompletionDelay:YES];
+    XCTestExpectation *done = [[XCTestExpectation alloc] initWithDescription:@"Native timed tap completion"];
+    [player playEventStream:stream options:nil completion:^{
+        [player tearDown];
+        [done fulfill];
+    }];
+    // Validated streams end within 12s. A timeout is a failure, never a retry.
+    if ([XCTWaiter waitForExpectations:@[done] timeout:20] != XCTWaiterResultCompleted)
+        return [self fail:@"Native timed tap playback did not complete" error:error];
+    return YES;
+}
+
 + (BOOL)synthesizePaths:(NSArray *)paths frame:(CGRect)frame error:(NSError **)error {
     if (![paths isKindOfClass:NSArray.class] || paths.count == 0 || paths.count > 64
         || CGRectIsEmpty(frame) || !isfinite(frame.size.width) || !isfinite(frame.size.height))
@@ -43,6 +117,21 @@
             previous = at;
         }
     }
+    NSArray *ordered = [paths sortedArrayUsingComparator:^NSComparisonResult(NSArray *left, NSArray *right) {
+        return [left.firstObject[@"at"] compare:right.firstObject[@"at"]];
+    }];
+    BOOL stationary = [ordered.firstObject[0][@"at"] doubleValue] == 0;
+    double previousEnd = 0;
+    for (NSArray *points in ordered) {
+        NSDictionary *first = points.firstObject;
+        if ([first[@"at"] doubleValue] < previousEnd) stationary = NO;
+        for (NSDictionary *point in points)
+            if ([point[@"x"] doubleValue] != [first[@"x"] doubleValue]
+                || [point[@"y"] doubleValue] != [first[@"y"] doubleValue]) stationary = NO;
+        previousEnd = [points.lastObject[@"at"] doubleValue];
+    }
+    if (stationary) return [self synthesizeStationaryPaths:ordered frame:frame error:error];
+
     Class recordClass = NSClassFromString(@"XCSynthesizedEventRecord");
     Class pathClass = NSClassFromString(@"XCPointerEventPath");
     for (NSString *name in @[@"initWithName:interfaceOrientation:", @"addPointerEventPath:", @"synthesizeWithError:"])
@@ -68,7 +157,7 @@
         [path liftUpAtOffset:[points.lastObject[@"at"] doubleValue]];
         [record addPointerEventPath:path];
     }
-    // One dispatch retains the native offsets between different fingers/taps.
+    // One dispatch preserves the existing moving/overlapping gesture path.
     // Individual XCUICoordinate.tap() calls would wait for app quiescence.
     return [record synthesizeWithError:error];
 }