@craft-native/ios 0.0.254 → 0.0.272

package/templates/CraftNativeScreen.swift

@@ -1090,6 +1090,8 @@ private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate
     private var playingObservation: NSKeyValueObservation?
     private var timeObserver: Any?
     private var loops = false
+    private var requestedTime: Double?
+    private var pendingSeek: Double?
     private var wasPlaying: Bool?
     private var playIntent: Bool?
     private var userPaused = false
@@ -1097,7 +1099,8 @@ private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate
     /// This video holds a claim on the audio session (`CraftNativeSounds`).
     private var claimedSession = false
     /// The screen's handlers by event name (`onEnd`, `onPlay`, `onPause`,
-    /// `onProgress`, `onLoad`, `onError`), and how an event reaches them.
+    /// `onProgress`, `onLoadStart`, `onLoad`, `onLoadEnd`, `onError`), and how
+    /// an event reaches them.
     var handlers: [String: String] = [:]
     var emit: ((_ handler: String, _ nativeEvent: [String: Any]) -> Void)?
 
@@ -1170,8 +1173,21 @@ private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate
         CraftNativeSounds.releaseSession()
     }
 
-    func configure(source: Any?, autoplay: Bool, paused: Bool, loop: Bool, muted: Bool, controls: Bool, resizeMode: String?, pictureInPicture: Bool = false) {
+    private func applyPendingSeek() {
+        guard let target = pendingSeek, let player, let item = player.currentItem, item.status == .readyToPlay else { return }
+        let current = seconds(player.currentTime())
+        pendingSeek = nil
+        guard abs(current - target) > 0.25 else { return }
+        player.seek(to: CMTime(seconds: target, preferredTimescale: 600))
+    }
+
+    func configure(source: Any?, autoplay: Bool, paused: Bool, loop: Bool, muted: Bool, currentTime: Any?, controls: Bool, resizeMode: String?, pictureInPicture: Bool = false) {
         let uri = (source as? String) ?? (source as? [String: Any])?["uri"] as? String ?? ""
+        let nextTime = number(currentTime).map(Double.init).map { max(0, $0) }
+        if nextTime != requestedTime {
+            requestedTime = nextTime
+            pendingSeek = nextTime
+        }
         let nextShouldPlay = autoplay && !paused
         if playIntent != nextShouldPlay {
             userPaused = false
@@ -1184,6 +1200,7 @@ private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate
             userPaused = false
             ended = false
             loops = false
+            pendingSeek = requestedTime
             // The copy `craft.media.keep` put on the phone plays in place of
             // the address, so a kept video plays with no signal.
             let kept = CraftNativeMedia.local(uri)
@@ -1200,11 +1217,13 @@ private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate
                 return
             }
             let next = AVPlayer(url: url)
+            fire("onLoadStart")
             player = next
             playerController.player = next
             observe(next)
         }
         guard let player else { return }
+        applyPendingSeek()
         player.isMuted = muted
         // A muted video makes no sound, so it leaves the session as it is.
         if muted { releaseSession() } else { claimSession() }
@@ -1258,7 +1277,10 @@ private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate
                 DispatchQueue.main.async {
                     guard let self, self.player?.currentItem === item else { return }
                     switch item.status {
-                    case .readyToPlay: self.fire("onLoad", ["duration": self.seconds(item.duration)])
+                    case .readyToPlay:
+                        self.applyPendingSeek()
+                        self.fire("onLoad", ["duration": self.seconds(item.duration)])
+                        self.fire("onLoadEnd")
                     case .failed: self.fire("onError", ["message": item.error?.localizedDescription ?? "The video could not be played"])
                     default: break
                     }
@@ -1306,6 +1328,8 @@ private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate
         playerController.player = nil
         playerController.delegate = nil
         sourceURI = ""
+        requestedTime = nil
+        pendingSeek = nil
         playIntent = nil
         userPaused = false
         ended = false
@@ -2022,6 +2046,8 @@ private struct CraftNativeLayoutStyle {
     let bottom: CGFloat?
     let left: CGFloat?
     let alignSelf: String?
+    /// CSS/Yoga order; equal values retain source order.
+    let order: Int
     let flexGrow: CGFloat
     /// Nil when the style does not say: the parent picks the default for the
     /// kind of view (text shrinks along a row, a box does not).
@@ -2059,6 +2085,7 @@ private struct CraftNativeLayoutStyle {
         left = number(raw["left"])
         let align = raw["alignSelf"] as? String
         alignSelf = align == "auto" ? nil : align
+        order = number(raw["order"]).map { Int($0.rounded(.towardZero)) } ?? 0
         // `flex: n` is the web's and React Native's shorthand: a positive
         // number grows by n, shrinks, and starts from nothing, so `flex-1`
         // siblings share a row equally whatever their content.
@@ -2137,6 +2164,13 @@ extension UIView {
         set { objc_setAssociatedObject(self, &craftNativeLayoutStyleKey, CraftNativeLayoutStyleBox(newValue), .OBJC_ASSOCIATION_RETAIN_NONATOMIC) }
     }
 
+    /// The margins this view's style asks for, for a container that places
+    /// it without a flex parent (a FlatList cell).
+    var craftLayoutMargins: UIEdgeInsets {
+        let style = craftLayoutStyle
+        return UIEdgeInsets(top: max(0, style.marginTop), left: max(0, style.marginLeft), bottom: max(0, style.marginBottom), right: max(0, style.marginRight))
+    }
+
     /// The corner radius the style asked for. The layer gets at most half the
     /// shortest side: Core Animation draws nothing at all for a radius larger
     /// than the view (`rounded-full` is 9999).
@@ -2516,6 +2550,7 @@ final class CraftNativeCelebration {
             group.duration = 2.2 + Double(spread) * 0.45
             group.beginTime = now + Double(index % 7) * 0.018
             group.fillMode = .backwards
+            group.atDisplayRate()
             piece.add(group, forKey: "craft.celebration.particle")
         }
 
@@ -2529,6 +2564,7 @@ final class CraftNativeCelebration {
         entrance.stiffness = 160
         entrance.mass = 1
         entrance.duration = 0.95
+        entrance.atDisplayRate()
         view.layer.add(entrance, forKey: "craft.celebration.entrance")
 
         let sheen = CAGradientLayer()
@@ -2554,6 +2590,7 @@ final class CraftNativeCelebration {
         shine.animations = [sweep, light]
         shine.duration = 1.15
         shine.beginTime = now + 0.55
+        shine.atDisplayRate()
         sheen.add(shine, forKey: "craft.celebration.sweep")
         let cleanup = DispatchWorkItem { [weak self] in self?.stop() }
         self.cleanup = cleanup
@@ -2886,7 +2923,15 @@ private class CraftNativeFlowView: UIStackView {
 
     /// Children that take part in the flow: shown, not a modal overlay.
     private var visibleChildren: [UIView] {
-        flowChildren.filter { $0.superview === self && !$0.isHidden && !($0 is CraftNativeModalView) }
+        flowChildren.enumerated()
+            .filter { $0.element.superview === self && !$0.element.isHidden && !($0.element is CraftNativeModalView) }
+            .sorted {
+                if $0.element.craftLayoutStyle.order != $1.element.craftLayoutStyle.order {
+                    return $0.element.craftLayoutStyle.order < $1.element.craftLayoutStyle.order
+                }
+                return $0.offset < $1.offset
+            }
+            .map(\.element)
     }
 
     /// Builds the eligible portion of this container for the host-neutral
@@ -3088,7 +3133,8 @@ private class CraftNativeFlowView: UIStackView {
                 frames: &frames
             )
         }
-        if place, flow.count == children.count, let sharedTree = sharedTreeFrames(flow, width: width, height: height), (sharedTree.nodes.count > flow.count + 1 || grid) {
+        if place, flow.count == children.count, let sharedTree = sharedTreeFrames(flow, width: width, height: height),
+           (sharedTree.nodes.count > flow.count + 1 || grid || reverse || wrapReverse || gridAutoRows != nil || gridRows != nil) {
             frames = []
             for index in 1..<sharedTree.nodes.count {
                 guard let view = sharedTree.nodes[index].view else { continue }
@@ -3795,6 +3841,17 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate {
         didSet { blocker.backgroundColor = transparent ? .clear : UIColor.black.withAlphaComponent(0.32) }
     }
 
+    /// Existing Modal nodes block by default. A non-modal popup keeps the
+    /// screen-level overlay but lets hit testing fall through outside its
+    /// interactive content.
+    var blocksBackground = true {
+        didSet { blocker.isUserInteractionEnabled = blocksBackground }
+    }
+    /// An opt-in non-modal dismissal policy. The default popup remains
+    /// pass-through; when enabled, an outside tap is consumed and routed to
+    /// onRequestClose instead of reaching the view below.
+    var dismissOnOutsideTap = false
+
     override init(frame: CGRect) {
         super.init(frame: frame)
         isUserInteractionEnabled = true
@@ -3876,10 +3933,13 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate {
         transform = .identity
         alpha = 0
         isUserInteractionEnabled = true
+        blocksBackground = true
+        dismissOnOutsideTap = false
         onRequestClose = nil
     }
 
     func requestClose(reason: String = "backdrop") {
+        guard blocksBackground || dismissOnOutsideTap else { return }
         guard let onRequestClose else { return }
         isUserInteractionEnabled = false
         onRequestClose(reason)
@@ -3912,6 +3972,14 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate {
                 candidate = view.superview
             }
         }
+        if !blocksBackground {
+            // A dismissible popup consumes its outside hit so the close event
+            // cannot also activate the screen below. Otherwise it owns the
+            // hit only when a blocking modal is underneath it; with no modal
+            // below, the screen remains pass-through.
+            if dismissOnOutsideTap { return self }
+            return craftScreenController?.hasBlockingModalBelow(self) == true ? self : nil
+        }
         return blocker.hitTest(blocker.convert(point, from: self), with: event)
     }
 
@@ -4267,9 +4335,13 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
 /// 3 quadratic, 4 close, in viewBox units - and scaled to the view. Paint is
 /// inherited down the tree as SVG does; `dark:` classes arrive already
 /// resolved for the appearance, so a redraw is all a theme change needs.
-private final class CraftNativeSvgView: UIView {
+final class CraftNativeSvgView: UIView {
     var drawing: [String: Any] = [:] {
-        didSet { setNeedsDisplay() }
+        didSet {
+            animates = Self.hasAnimation(drawing["children"] as? [Any] ?? [])
+            setNeedsDisplay()
+            updateFrames()
+        }
     }
 
     override init(frame: CGRect) {
@@ -4277,10 +4349,123 @@ private final class CraftNativeSvgView: UIView {
         isOpaque = false
         backgroundColor = .clear
         contentMode = .redraw
+        NotificationCenter.default.addObserver(self, selector: #selector(reduceMotionChanged), name: UIAccessibility.reduceMotionStatusDidChangeNotification, object: nil)
     }
 
     required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
 
+    deinit { CraftNativeFrameClock.shared.cancel(self) }
+
+    // MARK: Animation
+
+    /// Whether a shape carries keyframes (SMIL `<animate attributeName="d">`,
+    /// stx's `Animate`: an exercise's moving figure).
+    private var animates = false
+    /// When this drawing's repetition began: each one starts from its first
+    /// pose when it comes on screen, as a page's SMIL starts when it loads.
+    private var animationStart: CFTimeInterval?
+
+    /// Moving now: on display, and the person has not asked for less motion,
+    /// when each shape keeps its own outline (the still pose).
+    var isAnimating: Bool { animates && window != nil && !isHidden && !UIAccessibility.isReduceMotionEnabled }
+
+    override func didMoveToWindow() {
+        super.didMoveToWindow()
+        updateFrames()
+    }
+
+    override var isHidden: Bool {
+        didSet { if isHidden != oldValue { updateFrames() } }
+    }
+
+    @objc private func reduceMotionChanged() {
+        updateFrames()
+        setNeedsDisplay()
+    }
+
+    /// Frames from the screens' display link (CraftNativeFrameClock, up to
+    /// 120Hz) while moving; none at all while still or out of sight.
+    private func updateFrames() {
+        if isAnimating {
+            if animationStart == nil { animationStart = CACurrentMediaTime() }
+            CraftNativeFrameClock.shared.request(self) { [weak self] in self?.nextFrame() }
+        } else {
+            animationStart = nil
+            CraftNativeFrameClock.shared.cancel(self)
+        }
+    }
+
+    private func nextFrame() {
+        guard isAnimating else { return updateFrames() }
+        // Drawn only while some of it is on screen; a row scrolled away keeps
+        // its time and is right when it comes back.
+        if let window, window.bounds.intersects(convert(bounds, to: window)) { setNeedsDisplay() }
+        CraftNativeFrameClock.shared.request(self) { [weak self] in self?.nextFrame() }
+    }
+
+    private static func hasAnimation(_ children: [Any]) -> Bool {
+        children.contains { child in
+            guard let node = child as? [String: Any] else { return false }
+            if node["type"] as? String == "Animate" { return (node["props"] as? [String: Any])?["frames"] != nil }
+            return hasAnimation(node["children"] as? [Any] ?? [])
+        }
+    }
+
+    /// A shape's outline now: between the keyframes either side of `elapsed`
+    /// seconds into its animation (SMIL's linear `calcMode`), or its own
+    /// outline when it has none, the animation has ended, or motion is reduced.
+    private func outline(of shape: [String: Any]) -> Any? {
+        let geometry = (shape["props"] as? [String: Any])?["geometry"]
+        guard isAnimating, let start = animationStart,
+              let animate = (shape["children"] as? [Any])?.lazy.compactMap({ $0 as? [String: Any] }).first(where: { $0["type"] as? String == "Animate" }),
+              let current = Self.keyframe(animate["props"] as? [String: Any] ?? [:], at: CACurrentMediaTime() - start) else { return geometry }
+        return current
+    }
+
+    /// The outline `elapsed` seconds into an `Animate`'s repetitions; nil
+    /// when it does not animate path data or its repetitions are over.
+    static func keyframe(_ props: [String: Any], at elapsed: CFTimeInterval) -> [Any]? {
+        guard props["attributeName"] as? String == "d",
+              let duration = number(props["duration"]), duration > 0, duration.isFinite,
+              let frames = (props["frames"] as? [Any])?.compactMap({ ($0 as? [Any])?.compactMap(number) }),
+              frames.count >= 2, elapsed >= 0 else { return nil }
+        if let count = number(props["repeatCount"]), elapsed >= Double(count * duration) { return nil }
+        let given = (props["frameTimes"] as? [Any])?.compactMap(number) ?? []
+        let times = given.count == frames.count ? given : frames.indices.map { CGFloat($0) / CGFloat(frames.count - 1) }
+        let phase = CGFloat(elapsed.truncatingRemainder(dividingBy: Double(duration))) / duration
+        var index = 0
+        while index < frames.count - 2, times[index + 1] <= phase { index += 1 }
+        let from = frames[index]
+        let to = frames[index + 1]
+        let span = times[index + 1] - times[index]
+        let share = span > 0 ? min(1, max(0, (phase - times[index]) / span)) : 0
+        return interpolate(from, to, share).map { NSNumber(value: Double($0)) }
+    }
+
+    /// Two outlines with the same commands, a share of the way from one to
+    /// the other; the first as it is when their commands differ.
+    static func interpolate(_ from: [CGFloat], _ to: [CGFloat], _ share: CGFloat) -> [CGFloat] {
+        guard from.count == to.count, share > 0 else { return from }
+        var out = from
+        var i = 0
+        while i < from.count {
+            let command = Int(from[i])
+            guard to[i] == from[i] else { return from }
+            let count: Int
+            switch command {
+            case 0, 1: count = 2
+            case 2: count = 6
+            case 3: count = 4
+            case 4: count = 0
+            default: return from
+            }
+            guard i + count < from.count else { return from }
+            if count > 0 { for k in 1...count { out[i + k] = from[i + k] + (to[i + k] - from[i + k]) * share } }
+            i += count + 1
+        }
+        return out
+    }
+
     var viewBox: CGRect? {
         let props = drawing["props"] as? [String: Any] ?? [:]
         guard let box = props["viewBox"] as? [Any], box.count == 4 else { return nil }
@@ -4400,8 +4585,10 @@ private final class CraftNativeSvgView: UIView {
                 draw(children: shape["children"] as? [Any] ?? [], paint: own, in: context)
             case "SvgText":
                 drawText(shape, paint: own)
+            case "Animate":
+                continue
             default:
-                guard let path = CraftNativeSvgView.path((shape["props"] as? [String: Any])?["geometry"]) else { continue }
+                guard let path = CraftNativeSvgView.path(outline(of: shape)) else { continue }
                 context.saveGState()
                 path.usesEvenOddFillRule = own.fillRule == "evenodd"
                 if let fill = own.resolve(own.fill) {
@@ -4798,9 +4985,24 @@ enum CraftNativeScriptThread {
     static let queue = DispatchQueue(label: "craft.native.script", qos: .userInteractive)
 
     /// `work` where the screens' JavaScript runs: now on the main thread, or
-    /// queued in order on the script thread.
-    static func run(_ work: @escaping () -> Void) {
-        if isBackground { queue.async(execute: work) } else { work() }
+    /// queued in order on the script thread. With frame pacing on
+    /// (`CRAFT_FRAME_PACING=1`), work that waited or ran for 4ms or more is
+    /// logged under `label`, so a slow screen can be told from a queued one.
+    static func run(label: @autoclosure @escaping () -> String = "script", _ work: @escaping () -> Void) {
+        let pacing = CraftFramePacing.shared
+        guard pacing.enabled else {
+            if isBackground { queue.async(execute: work) } else { work() }
+            return
+        }
+        let queued = CACurrentMediaTime()
+        let timed = {
+            let started = CACurrentMediaTime()
+            work()
+            let ran = CACurrentMediaTime() - started
+            let waited = started - queued
+            if waited + ran >= 0.004 { pacing.scriptWork(label(), waited: waited, ran: ran) }
+        }
+        if isBackground { queue.async(execute: timed) } else { timed() }
     }
 
     /// From the script thread, `work` on the main thread, not waited for.
@@ -4824,6 +5026,62 @@ enum CraftNativeScriptThread {
     }
 }
 
+extension CAAnimation {
+    /// Asks for the display's full rate, up to 120Hz on ProMotion. Core
+    /// Animation otherwise picks a rate for the motion and often stays at 60;
+    /// a transition or a spring the eye follows reads smoother at 120.
+    func atDisplayRate() {
+        if #available(iOS 15.0, *) { preferredFrameRateRange = CAFrameRateRange(minimum: 80, maximum: 120, preferred: 120) }
+    }
+}
+
+/// `requestAnimationFrame` for native screens: one display link, at the
+/// display's own rate (up to 120Hz on a ProMotion iPhone, which the app
+/// allows with `CADisableMinimumFrameDurationOnPhone`), running only while a
+/// screen on display is waiting for a frame. Each frame hands every waiting
+/// screen one `__craftNativeFireFrame`, where its script runs; a screen asks
+/// again for the frame after, as a browser's page does. A screen out of sight
+/// waits until it is shown, as a browser pauses a hidden tab's frames, and as
+/// Craft's Android host does (Choreographer). Main thread only.
+final class CraftNativeFrameClock: NSObject {
+    static let shared = CraftNativeFrameClock()
+
+    private var waiting: [ObjectIdentifier: () -> Void] = [:]
+    private var link: CADisplayLink?
+
+    /// How many screens wait for the next frame.
+    var waitingCount: Int { waiting.count }
+    /// Whether the display link is counting frames now.
+    var isRunning: Bool { link.map { !$0.isPaused } ?? false }
+
+    /// `deliver` on the next frame, once. Asking again before it comes keeps one.
+    func request(_ owner: AnyObject, _ deliver: @escaping () -> Void) {
+        waiting[ObjectIdentifier(owner)] = deliver
+        if link == nil {
+            let link = CADisplayLink(target: self, selector: #selector(frame(_:)))
+            if #available(iOS 15.0, *) {
+                link.preferredFrameRateRange = CAFrameRateRange(minimum: 30, maximum: 120, preferred: 120)
+            }
+            link.add(to: .main, forMode: .common)
+            self.link = link
+        }
+        link?.isPaused = false
+    }
+
+    /// `owner` no longer waits: it went out of sight or away.
+    func cancel(_ owner: AnyObject) {
+        waiting.removeValue(forKey: ObjectIdentifier(owner))
+        if waiting.isEmpty { link?.isPaused = true }
+    }
+
+    @objc private func frame(_ link: CADisplayLink) {
+        let due = waiting
+        waiting.removeAll()
+        if waiting.isEmpty { link.isPaused = true }
+        due.values.forEach { $0() }
+    }
+}
+
 /// The native screens' JavaScript. A screen is a JavaScriptCore context of
 /// its own and evaluates the whole file it is given, so each route has a file
 /// of its own when stx wrote one (`dist/native-screens/<route>.js`, stx's
@@ -4900,6 +5158,25 @@ enum CraftNativeBundle {
     }
 }
 
+private final class CraftNativeScreenRootView: UIView {
+    weak var controller: CraftNativeScreenController?
+
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        // A popup's host frame is only its authored card, so UIKit would not
+        // ask it about an outside point. Shield that point at the screen root
+        // only when a blocking modal is underneath; ordinary non-modal
+        // overlays remain pass-through.
+        if let controller {
+            for modal in controller.view.subviews.compactMap({ $0 as? CraftNativeModalView }).reversed()
+                where !modal.blocksBackground && !modal.isHidden && modal.alpha > 0.01 {
+                let local = modal.convert(point, from: self)
+                if !modal.bounds.contains(local) && (modal.dismissOnOutsideTap || controller.hasBlockingModalBelow(modal)) { return modal }
+            }
+        }
+        return super.hitTest(point, with: event)
+    }
+}
+
 final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate, UITextFieldDelegate, UITextViewDelegate, UIPickerViewDataSource, UIPickerViewDelegate {
     private final class RenderedNode {
         /// A recycled list row's root takes the identity of the row it shows next.
@@ -4952,6 +5229,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private var scrollMomentumEndHandlers: [ObjectIdentifier: String] = [:]
     private var sliderCompleteHandlers: [ObjectIdentifier: String] = [:]
     private var sliderSteps: [ObjectIdentifier: Float] = [:]
+    /// A controlled switch can be reconciled while UIKit is still animating
+    /// the user's tap. Remember that native value briefly so the echo does not
+    /// interrupt the animation and leave the thumb painted at its old edge.
+    private var switchUserValues: [ObjectIdentifier: Bool] = [:]
     private var pickerOptions: [ObjectIdentifier: [(value: String, label: String)]] = [:]
     private var modalVisibility: [ObjectIdentifier: Bool] = [:]
     private var modalFocusRestore: [ObjectIdentifier: UIView] = [:]
@@ -5026,6 +5307,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         var pending: [Int: DispatchWorkItem] = [:]
     }
     private let timers = Timers()
+    /// The script asked for an animation frame it has not had yet
+    /// (`requestAnimationFrame`, CraftNativeFrameClock). Main thread only.
+    private var frameWanted = false
     private var lifecycleObservers: [NSObjectProtocol] = []
     private var deepLinkListener: UUID?
     private var keyboardSafeAreaInset: CGFloat = 0
@@ -5056,6 +5340,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         fatalError("init(coder:) has not been implemented")
     }
 
+    override func loadView() {
+        let root = CraftNativeScreenRootView()
+        root.controller = self
+        view = root
+    }
+
     deinit {
         disposeRuntime()
         imageTasks.values.forEach { $0.cancel() }
@@ -5092,7 +5382,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         let pacing = CraftFramePacing.shared
         let inputs = scriptInputs()
         let name = routeName ?? "screen"
-        CraftNativeScriptThread.run { [self] in
+        CraftNativeScriptThread.run(label: "mount \(name)") { [self] in
             pacing.measure("mount \(name) setup") { setupJavaScript(inputs) }
             pacing.measure("mount \(name) bundle") { loadBundle() }
         }
@@ -5153,8 +5443,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         screenVisibilityChanged(false)
         stopCelebrations(in: view)
         // Release only this screen's accessory. A retained or prepared screen
-        // can disappear after the destination has already published its own.
-        CraftChrome.shared.clearTabAccessory(ownedBy: self)
+        // can disappear after the destination has already published its own;
+        // released, it stays drawn until the destination says what it wants.
+        CraftChrome.shared.releaseTabAccessory(ownedBy: self)
         // Popped (or its stack dismissed) while the bar was away: it comes
         // back for whatever shows next, a web page included.
         if tabBarHidden, isMovingFromParent || isBeingDismissed || navigationController?.isBeingDismissed == true {
@@ -5199,7 +5490,29 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private func restoreShellChrome() {
         guard !isAppScript else { return }
         CraftChrome.shared.setHiddenByScreen(tabBarHidden)
-        CraftChrome.shared.updateTabAccessory(tabAccessory, owner: self)
+        // A screen not yet asked about the accessory (one shown for the first
+        // time, before its script has run) leaves the bar as it is; one that
+        // has drawn without asking for it takes off what nobody claims.
+        if tabAccessoryDeclared { CraftChrome.shared.updateTabAccessory(tabAccessory, owner: self) }
+        else if hybridRendered { CraftChrome.shared.clearUnclaimedTabAccessory() }
+    }
+
+    /// `requestAnimationFrame`: the next display frame, for a screen on display
+    /// (or the app script, which is never shown). One out of sight keeps the
+    /// request until it is shown again (screenVisibilityChanged).
+    private func requestFrame() {
+        guard !runtimeDisposed, !frameWanted else { return }
+        frameWanted = true
+        guard isAppScript || reportedVisible != false else { return }
+        CraftNativeFrameClock.shared.request(self) { [weak self] in self?.fireFrame() }
+    }
+
+    private func fireFrame() {
+        guard frameWanted, !runtimeDisposed else { return }
+        frameWanted = false
+        let context = jsContext
+        let route = routeName ?? "screen"
+        CraftNativeScriptThread.run(label: "frame \(route)") { context.objectForKeyedSubscript("__craftNativeFireFrame")?.call(withArguments: []) }
     }
 
     /// The screen came on screen or went off it: a screen pushed over it was
@@ -5216,6 +5529,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         // preview also restores a screen that never lost focus, so restore its
         // chrome even when no new SCREEN_FOCUS event is needed.
         if visible { restoreShellChrome() }
+        if visible, frameWanted { CraftNativeFrameClock.shared.request(self) { [weak self] in self?.fireFrame() } }
+        if !visible { CraftNativeFrameClock.shared.cancel(self) }
         guard visible != reportedVisible else { return }
         let first = reportedVisible == nil
         reportedVisible = visible
@@ -5232,7 +5547,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         routeProps = props
         guard isViewLoaded, !runtimeDisposed else { return }
         let context = jsContext
-        CraftNativeScriptThread.run {
+        let route = routeName ?? "screen"
+        CraftNativeScriptThread.run(label: "params \(route)") {
             context.setObject(params as NSDictionary, forKeyedSubscript: "__stxNativeParams" as NSString)
             context.setObject(props as NSDictionary, forKeyedSubscript: "__stxNativeProps" as NSString)
         }
@@ -5242,9 +5558,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     private func disposeRuntime() {
         guard !runtimeDisposed else { return }
         runtimeDisposed = true
+        frameWanted = false
+        CraftNativeFrameClock.shared.cancel(self)
         disposeRenderedTree()
         let context = jsContext
-        CraftNativeScriptThread.run { context.objectForKeyedSubscript("__stxNativeUnmount")?.call(withArguments: []) }
+        let route = routeName ?? "screen"
+        CraftNativeScriptThread.run(label: "unmount \(route)") { context.objectForKeyedSubscript("__stxNativeUnmount")?.call(withArguments: []) }
         audio.close()
         sounds.close()
         streams.close()
@@ -5312,9 +5631,58 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if bar.intersects(view.bounds) { insets.top = max(insets.top, bar.maxY) }
         }
         for modal in modals {
-            if modal.frame != view.bounds { modal.frame = view.bounds }
-            modal.contentInsets = insets
+            guard !modal.blocksBackground else {
+                if modal.frame != view.bounds { modal.frame = view.bounds }
+                modal.contentInsets = insets
+                continue
+            }
+
+            // Non-modal overlays are viewport children, not full-screen
+            // scrims. Their absolute style uses the same full screenViewport
+            // origin that View.measure returns. Safe-area-aware placement is
+            // owned by the caller (for example, STX's anchor/clamp logic), so
+            // an authored left/top is never shifted by an implicit inset.
+            let viewport = view.bounds
+            let style = modal.craftLayoutStyle
+            let width = style.left != nil && style.right != nil
+                ? max(0, viewport.width - (style.left ?? 0) - (style.right ?? 0))
+                : style.width?.resolve(viewport.width)
+                    ?? min(viewport.width, modal.contentStack.sizeThatFits(viewport.size).width)
+            let height = style.top != nil && style.bottom != nil
+                ? max(0, viewport.height - (style.top ?? 0) - (style.bottom ?? 0))
+                : style.height?.resolve(viewport.height)
+                    ?? min(viewport.height, modal.contentStack.sizeThatFits(viewport.size).height)
+            let x = viewport.minX + (style.left ?? (style.right.map { viewport.width - $0 - width } ?? 0))
+            let y = viewport.minY + (style.top ?? (style.bottom.map { viewport.height - $0 - height } ?? 0))
+            let frame = CGRect(x: x, y: y, width: width, height: height)
+            if modal.frame != frame { modal.frame = frame }
+            // The frame already excludes the safe area; inset the content no
+            // further or authored top/left coordinates would be shifted twice.
+            modal.contentInsets = .zero
+        }
+    }
+
+    /// A non-modal popup above a blocking modal must not leak its outside tap
+    /// to the modal's scrim and dismiss the wrong layer.
+    fileprivate func hasBlockingModalBelow(_ modal: CraftNativeModalView) -> Bool {
+        guard let index = view.subviews.firstIndex(where: { $0 === modal }) else { return false }
+        return view.subviews[..<index].contains { candidate in
+            guard let other = candidate as? CraftNativeModalView else { return false }
+            return other.blocksBackground && !other.isHidden && other.alpha > 0.01
+        }
+    }
+
+    /// The native route's Back button dismisses the top presented modal before
+    /// it pops the route, matching Android's activity back callback.
+    @discardableResult
+    func handleBackForModal() -> Bool {
+        let modal = view.subviews.reversed().compactMap { $0 as? CraftNativeModalView }.first {
+            !$0.isHidden && $0.alpha > 0.01 && ($0.blocksBackground || $0.dismissOnOutsideTap)
         }
+        guard let modal else { return false }
+        let hasHandler = modal.onRequestClose != nil
+        modal.requestClose(reason: "back")
+        return hasHandler
     }
 
     private static func safeJavaScriptString(_ value: JSValue?) -> String? {
@@ -5415,6 +5783,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         }
         jsContext.setObject(scheduleTimer, forKeyedSubscript: "craftNativeScheduleTimer" as NSString)
         jsContext.setObject(cancelTimer, forKeyedSubscript: "craftNativeCancelTimer" as NSString)
+        // The next display frame, from the script's thread; the frame itself
+        // comes back there as `__craftNativeFireFrame`.
+        let requestFrame: @convention(block) () -> Void = { [weak self] in
+            CraftNativeScriptThread.toMain { self?.requestFrame() }
+        }
+        jsContext.setObject(requestFrame, forKeyedSubscript: "craftNativeRequestFrame" as NSString)
         let capabilityJSON = inputs.capabilityJSON
         // The app's site and build, as JSON strings: the site an all-native
         // app's paths and links belong to (`devServerURL`), and the version a
@@ -5450,6 +5824,41 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         jsContext.evaluateScript(Self.nativeWebAPICompatibilityPrelude)
         installHostAPIs()
         jsContext.evaluateScript("""
+            // requestAnimationFrame on the display's frames (CraftNativeFrameClock),
+            // at its own rate, 120 a second on ProMotion: a timer guessing at 60
+            // would cap every animation a screen draws itself. One request covers
+            // every callback for the frame; a callback that throws does not stop
+            // the others, and is reported after them.
+            if (typeof globalThis.requestAnimationFrame !== 'function') {
+                (function() {
+                    var frames = [];
+                    var cancelled = new Set();
+                    var nextFrame = 0;
+                    globalThis.requestAnimationFrame = function(callback) {
+                        if (typeof callback !== 'function') return 0;
+                        var id = ++nextFrame;
+                        frames.push({ id: id, callback: callback });
+                        if (frames.length === 1) craftNativeRequestFrame();
+                        return id;
+                    };
+                    globalThis.cancelAnimationFrame = function(id) {
+                        if (frames.some(function(frame) { return frame.id === id; })) cancelled.add(id);
+                    };
+                    globalThis.__craftNativeFireFrame = function() {
+                        var due = frames;
+                        var skip = cancelled;
+                        frames = [];
+                        cancelled = new Set();
+                        var now = globalThis.performance && typeof globalThis.performance.now === 'function' ? globalThis.performance.now() : Date.now();
+                        var failures = [];
+                        for (var i = 0; i < due.length; i++) {
+                            if (skip.has(due[i].id)) continue;
+                            try { due[i].callback(now); } catch (error) { failures.push(error); }
+                        }
+                        failures.forEach(function(error) { globalThis.setTimeout(function() { throw error; }, 0); });
+                    };
+                })();
+            }
             if (typeof globalThis.setTimeout !== 'function') {
                 (function() {
                     var timers = new Map();
@@ -5955,6 +6364,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// The app's tab bar away while this screen shows (`tabBarHidden`).
     private var tabBarHidden = false
     private var tabAccessory: [String: Any]?
+    /// Whether the screen has said anything about the accessory yet
+    /// (`tabAccessory`, null included): until it has, the bar keeps showing
+    /// the one it had (CraftChrome.releaseTabAccessory).
+    private var tabAccessoryDeclared = false
     /// Whether a back-swipe may leave this screen at all, the edge's
     /// included (`swipeBack: false`): a screen that steps through its own
     /// pages with a Back of its own (a first-run tour's questions) would
@@ -6003,6 +6416,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         guard !isAppScript else { return }
         if options.keys.contains("tabAccessory") {
             tabAccessory = options["tabAccessory"] as? [String: Any]
+            tabAccessoryDeclared = true
             if navigationController?.topViewController === self, view.window != nil {
                 CraftChrome.shared.updateTabAccessory(tabAccessory, owner: self)
             }
@@ -6392,7 +6806,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 let previous = info["previous"] as? String
                 self.send(type: "SESSION_CHANGED", payload: ["key": key, "token": token ?? NSNull(), "previous": previous ?? NSNull()])
                 let context = self.jsContext
-                CraftNativeScriptThread.run { context.objectForKeyedSubscript("__craftSessionChanged")?.call(withArguments: [token ?? NSNull(), previous ?? NSNull()]) }
+                CraftNativeScriptThread.run(label: "session \(self.routeName ?? "screen")") { context.objectForKeyedSubscript("__craftSessionChanged")?.call(withArguments: [token ?? NSNull(), previous ?? NSNull()]) }
             })
         }
         if config.enablePushNotifications {
@@ -6677,8 +7091,15 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             }
             let module = payload["module"] as? String ?? ""
             let method = payload["method"] as? String ?? ""
+            // With frame pacing on: how long the capability took to answer,
+            // which a screen's script waits on (a request, the keychain).
+            let pacing = CraftFramePacing.shared
+            let asked = pacing.enabled ? CACurrentMediaTime() : 0
+            let route = routeName ?? "screen"
+            let what = module == "Network" ? "\(module).\(method) \(((args.first as? [String: Any])?["url"] as? String).flatMap { URL(string: $0)?.path } ?? "")" : "\(module).\(method)"
             let reply: (Result<Any, CraftNativeActionError>) -> Void = { [weak self] answer in
                 guard let self = self, self.pendingCapabilityRequests.remove(requestToken) != nil else { return }
+                if pacing.enabled { pacing.capability("\(what) \(route)", took: CACurrentMediaTime() - asked) }
                 self.pendingCapabilityDeadlines.removeValue(forKey: requestToken)?.cancel()
                 self.screenRequestCancellers.removeValue(forKey: requestToken)
                 switch answer {
@@ -6907,6 +7328,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             hybridRendered = true
             // The app script's drawing is never on screen: not a first frame.
             if !isAppScript { hybridEvents?.nativeScreenDidRender(self) }
+            // Drawn without a word about the accessory: it wants none.
+            if !isAppScript, !tabAccessoryDeclared, isShownOnScreen { CraftChrome.shared.clearUnclaimedTabAccessory() }
             let waiting = renderWaiters
             renderWaiters.removeAll()
             waiting.forEach { $0() }
@@ -7328,6 +7751,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             let modal = result as! CraftNativeModalView
             let focusBeforeContent = firstResponder(in: rootStack) ?? lastFocusedInput
             modal.transparent = props["transparent"] as? Bool == true
+            modal.blocksBackground = props["nonModal"] as? Bool != true
+            modal.dismissOnOutsideTap = props["dismissOnOutsideTap"] as? Bool == true
             let visible: Bool
             if let propVisible = props["visible"] as? Bool {
                 // An explicit visible prop owns modal visibility. The
@@ -7385,7 +7810,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 // UIKit has already changed the value before emitting the
                 // event. Echoing it through the script must not restart its
                 // native animation.
-                if toggle.isOn != value { toggle.isOn = value }
+                let id = ObjectIdentifier(toggle)
+                if switchUserValues[id] != value, toggle.isOn != value {
+                    // Programmatic changes should settle immediately. A
+                    // native tap is handled above without touching UIKit
+                    // while its own thumb animation is in flight.
+                    toggle.setOn(value, animated: false)
+                }
             }
             toggle.isEnabled = props["disabled"] as? Bool != true
             if let track = props["trackColor"] as? [String: Any] {
@@ -7512,6 +7943,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 paused: (props["paused"] as? Bool) == true,
                 loop: (props["loop"] as? Bool) == true,
                 muted: (props["muted"] as? Bool) == true,
+                currentTime: props["currentTime"],
                 controls: (props["controls"] as? Bool) == true,
                 resizeMode: style["resizeMode"] as? String ?? props["resizeMode"] as? String,
                 pictureInPicture: (props["pictureInPicture"] as? Bool) == true
@@ -8104,6 +8536,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         imageLoadEndHandlers.removeValue(forKey: id)
         imageErrorHandlers.removeValue(forKey: id)
         checkboxIndeterminate.removeValue(forKey: id)
+        switchUserValues.removeValue(forKey: id)
         if let video = node.view as? CraftNativeVideoView { video.stop() }
         if let map = node.view as? CraftNativeMapView { map.destroy() }
         for child in node.children { forgetHandlers(child, preservingInputDrafts: preservingInputDrafts) }
@@ -9086,7 +9519,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         let hasLinkTarget = ["href", "to"].contains { !(props[$0] as? String ?? "").isEmpty }
         let linkedControl = ["Link", "TouchableOpacity", "TouchableHighlight", "Pressable"].contains(type) && hasLinkTarget
         let touchable = ["TouchableOpacity", "TouchableHighlight", "Pressable"].contains(type)
-        let role = (props["accessibilityRole"] as? String) ?? (linkedControl ? "link" : touchable ? "button" : nil)
+        let role = (props["accessibilityRole"] as? String)
+            ?? (linkedControl ? "link" : touchable ? "button" : ["FlatList", "SectionList"].contains(type) ? "list" : nil)
         // A scroll view, a list or a group of controls holds what VoiceOver
         // reads: its label names the group, as a tab strip or a pager's
         // name, and never stands in for its content. As an element of its
@@ -9281,7 +9715,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     @objc private func switchChanged(_ sender: UISwitch) {
-        guard let handler = handlers[ObjectIdentifier(sender)] else { return }
+        let id = ObjectIdentifier(sender)
+        switchUserValues[id] = sender.isOn
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.35) { [weak self, weak sender] in
+            guard let self, let sender, self.switchUserValues[id] == sender.isOn else { return }
+            self.switchUserValues.removeValue(forKey: id)
+        }
+        guard let handler = handlers[id] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["value": sender.isOn]])
     }
 
@@ -9555,7 +9995,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         guard let data = try? JSONSerialization.data(withJSONObject: message),
               let json = String(data: data, encoding: .utf8) else { return }
         let context = jsContext
-        CraftNativeScriptThread.run { context.objectForKeyedSubscript("__stxNativeCallback")?.call(withArguments: [json]) }
+        let route = routeName ?? "screen"
+        CraftNativeScriptThread.run(label: "\(type) \(route)") { context.objectForKeyedSubscript("__stxNativeCallback")?.call(withArguments: [json]) }
     }
 
     private func number(_ value: Any?) -> CGFloat? {
@@ -9962,6 +10403,7 @@ extension CraftNativeScreenController {
             }
             animation.fromValue = from
             let key = "\(CraftNativeRunningAnimation.key).\(keyPath)"
+            animation.atDisplayRate()
             layer.add(animation, forKey: key)
             running.layers.append((layer, key))
         }