@craft-native/ios 0.0.304 → 0.0.319

package/README.md

@@ -1324,3 +1324,21 @@ and detents; Android sizes its native bottom panel to the selected detent
 without an extra dependency. Omitting presentationStyle keeps the existing
 full-screen overlay. A native sheet's close request still belongs to its
 owner, which sets visible to false.
+
+
+### Controlled native paging and font families
+
+A horizontal `ScrollView` with `pagingEnabled: true` and a numeric `pageIndex`
+uses viewport-sized direct children. The host advertises `nativePager` and emits
+`onPageSelected` with `{ index, count }` after initial layout, count changes and
+settled user selection. Updates to `pageIndex` select a page; removed pages clamp
+the index and resizing preserves it. Offscreen pages stay mounted but are hidden
+from native accessibility. `scrollEnabled: false` locks swiping while retaining
+controls in the selected page. Without `pageIndex`, scroll content keeps its
+ordinary intrinsic layout; this is an opt-in contract for a shared Pager.
+
+Text `fontFamily` accepts a CSS fallback list. Bundled/custom fonts take priority
+when available. `monospace`/`ui-monospace`, `serif`/`ui-serif` and
+`sans-serif`/`ui-sans-serif`/`system-ui` select platform fonts, retaining requested
+weight, italic style and system text scaling. A missing custom face falls through
+to the next family rather than silently replacing a requested mono font with sans.

package/dist/index.js

@@ -189,7 +189,12 @@ function serializeSimulatorSteps(steps) {
   };
   const line = (step) => {
     let arg = "";
-    if ("paths" in step) {
+    if (step.command === "holdtab") {
+      const seconds = step.seconds ?? 6;
+      if (!step.text.trim() || step.text.includes("|") || number(seconds) < 2 || seconds > 10)
+        throw new Error("holdtab needs a nonempty tab name and 2\u201310 seconds");
+      arg = `${step.text} | ${seconds}`;
+    } else if ("paths" in step) {
       if (!step.paths.length || step.paths.length > 64)
         throw new Error("Expected 1\u201364 touch paths");
       for (const path of step.paths) {

package/dist/testing.d.ts

@@ -61,6 +61,12 @@ export type SimulatorStep = {
  | {
     command: 'touches';
     paths: TimedTouchPoint[][];
+}
+/** Standard XCTest tab hold; independent screenshots must be captured before release. */
+ | {
+    command: 'holdtab';
+    text: string;
+    seconds?: number;
 } | {
     command: 'field';
     index: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-native/ios",
-  "version": "0.0.304",
+  "version": "0.0.319",
   "homepage": "https://github.com/craft-native/craft/tree/main/packages/ios#readme",
   "repository": {
     "type": "git",

package/templates/CraftApp.swift

@@ -766,6 +766,13 @@ final class CraftChrome: ObservableObject {
     @Published var tabAccessory: Tab?
     private weak var tabAccessoryOwner: AnyObject?
     @Published var selected: String?
+    /// The visible destination may be the accessory, independently of its owning stack.
+    @Published var visiblePath: String?
+    var accessorySelected: Bool {
+        guard let path = visiblePath, let accessory = tabAccessory?.id else { return false }
+        return path == accessory || path.hasPrefix(accessory + "/")
+    }
+    var highlightedTab: String? { accessorySelected ? nil : selected }
     let tabSwipeProgress = CraftTabSwipeProgress()
     private(set) var tabSwipePosition: CGFloat? {
         get { tabSwipeProgress.position }
@@ -1172,6 +1179,18 @@ final class CraftChromeRelay: NSObject, WKScriptMessageHandler {
 
 /// The floating tab bar: Liquid Glass on iOS 26 and later, a material capsule before.
 struct CraftTabBarView: View {
+    @Environment(\.dynamicTypeSize) private var dynamicTypeSize
+
+    var body: some View {
+        // ScaledMetric reads the environment of its owning view. Put the
+        // metrics in a child so this compact-chrome cap reaches them too.
+        CraftTabBarContent(viewerTextSize: dynamicTypeSize)
+            .dynamicTypeSize(...DynamicTypeSize.xxxLarge)
+    }
+}
+
+private struct CraftTabBarContent: View {
+    let viewerTextSize: DynamicTypeSize
     @ObservedObject private var chrome = CraftChrome.shared
     @Environment(\.accessibilityReduceMotion) private var reduceMotion
     @Environment(\.scenePhase) private var scenePhase
@@ -1183,7 +1202,7 @@ struct CraftTabBarView: View {
     @ScaledMetric(relativeTo: .caption2) private var badgeSize: CGFloat = 10
 
     var body: some View {
-        if chrome.tabBarVisible && !chrome.tabs.isEmpty {
+        if !chrome.tabs.isEmpty {
             HStack(spacing: 8) {
                 bar
                 if let accessory = chrome.tabAccessory {
@@ -1191,8 +1210,13 @@ struct CraftTabBarView: View {
                         surface {
                             Image(systemName: accessory.symbol)
                                 .font(.system(size: iconSize))
-                                .foregroundStyle(Color.primary)
+                                .foregroundStyle(chrome.accessorySelected ? selectedColor : Color.primary)
                                 .frame(width: 62, height: 62)
+                                .background {
+                                    if chrome.accessorySelected {
+                                        Circle().fill(selectedColor.opacity(0.14)).padding(4)
+                                    }
+                                }
                         }
                             .contentShape(Rectangle())
                             .overlay(alignment: .topTrailing) {
@@ -1207,9 +1231,17 @@ struct CraftTabBarView: View {
                             }
                     }
                     .buttonStyle(.plain)
+                    .accessibilityShowsLargeContentViewer {
+                        Image(systemName: accessory.symbol)
+                        Text(accessory.accessibilityLabel ?? accessory.title)
+                    }
+                    // Keep accessibility intent for the viewer; displayed
+                    // sizes come from the bounded metrics owned above.
+                    .environment(\.dynamicTypeSize, viewerTextSize)
                     .accessibilityLabel(accessory.accessibilityLabel ?? accessory.title)
                     .accessibilityValue(accessory.badge ?? "")
                     .accessibilityIdentifier("craft-tab-accessory")
+                    .accessibilityAddTraits(chrome.accessorySelected ? .isSelected : [])
                 }
             }
                 .padding(.horizontal, 16)
@@ -1219,9 +1251,14 @@ struct CraftTabBarView: View {
                         .onAppear { report(proxy) }
                         .onChange(of: proxy.frame(in: .global)) { _ in report(proxy) }
                 })
-                .transition(reduceMotion ? .opacity : .move(edge: .bottom).combined(with: .opacity))
+                // Keep the view mounted: a disappearing conditional inside a
+                // child does not reliably animate in the UIKit navigation transaction.
+                .offset(y: chrome.tabBarVisible || reduceMotion ? 0 : 120)
+                .opacity(chrome.tabBarVisible ? 1 : 0)
+                .allowsHitTesting(chrome.tabBarVisible)
+                .accessibilityHidden(!chrome.tabBarVisible)
+                .animation(.easeInOut(duration: reduceMotion ? 0.12 : 0.24), value: chrome.tabBarVisible)
                 .ignoresSafeArea(.keyboard)
-                .dynamicTypeSize(...DynamicTypeSize.xxxLarge)
         }
     }
 
@@ -1260,7 +1297,7 @@ struct CraftTabBarView: View {
     private var items: some View {
         HStack(spacing: 0) {
             ForEach(chrome.tabs) { tab in
-                let isSelected = tab.id == chrome.selected
+                let isSelected = tab.id == chrome.highlightedTab
                 Button { chrome.tap(tab) } label: {
                     VStack(spacing: 3) {
                         ZStack(alignment: .topTrailing) {
@@ -1305,6 +1342,7 @@ struct CraftTabBarView: View {
                     Image(systemName: symbol(tab.symbol, selected: isSelected))
                     Text(tab.displayTitle)
                 }
+                .environment(\.dynamicTypeSize, viewerTextSize)
                 .accessibilityIdentifier("craft-tab-\(tab.id)")
                 .accessibilityLabel(tab.accessibilityLabel ?? tab.badge.map { "\(tab.displayTitle), \($0)" } ?? tab.displayTitle)
                 .accessibilityAddTraits(isSelected ? [.isSelected, .isButton] : .isButton)
@@ -1312,7 +1350,7 @@ struct CraftTabBarView: View {
         }
         .background {
             CraftTabSelectionIndicator(
-                selected: chrome.tabs.firstIndex(where: { $0.id == chrome.selected }),
+                selected: chrome.tabs.firstIndex(where: { $0.id == chrome.highlightedTab }),
                 count: chrome.tabs.count,
                 cornerRadius: chrome.tabSelectionCornerRadius
             )

package/templates/CraftHybrid.swift

@@ -1664,6 +1664,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             (nav.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(true)
         }
         currentTab = id
+        if let top = nav.topViewController { CraftChrome.shared.visiblePath = nativePaths[ObjectIdentifier(top)] }
         for (key, other) in stacks { other.view.isHidden = key != id }
         nav.view.frame = view.bounds
         view.bringSubviewToFront(nav.view)
@@ -2042,6 +2043,9 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     func navigationController(_ navigationController: UINavigationController, willShow viewController: UIViewController, animated: Bool) {
         lastNavigation = CACurrentMediaTime()
         if animated { CraftFramePacing.shared.begin("navigation") }
+        if navigationController === visibleStack {
+            CraftChrome.shared.visiblePath = nativePaths[ObjectIdentifier(viewController)]
+        }
         // The page draws its own header, and a tab's root screen its own
         // title unless it asked for the bar; a pushed native screen gets the
         // bar and its Back.
@@ -2084,6 +2088,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             hybrid.pageReset(to: rootPath)
         }
         guard navigationController === visibleStack else { return }
+        // Also restore selection after a cancelled interactive pop.
+        CraftChrome.shared.visiblePath = nativePaths[ObjectIdentifier(viewController)]
         if let slot = viewController as? CraftHybridWebSlot { adoptWeb(into: slot) } else { parkWeb() }
     }
 

package/templates/CraftNativeActions.swift

@@ -43,6 +43,7 @@ enum CraftNativeActions {
         // `speech`, `audio` (background sound) and `eventStream` (a fetch read
         // as it arrives) need nothing the app has to declare.
         var values = ["device", "clipboard", "haptics", "storage", "lifecycle", "fetch", "dialog", "speech", "audio", "eventStream", "linking", "badge", "animation", "viewFocus", "viewMeasure", "viewReparent", "viewNonModalPresentation", "nativePlatformControls"]
+        values.append("nativePager")
         values.append("storageCompareAndSet")
         values.append("storageSetIfAbsent")
         values.append("viewScroll")

package/templates/CraftNativeScreen.swift

@@ -2744,6 +2744,7 @@ final class CraftNativeCelebration {
 }
 
 private class CraftNativeFlowView: UIStackView {
+    var pageViewport: CGSize? { didSet { if pageViewport != oldValue { invalidateMeasurements() } } }
     var celebration: CraftNativeCelebration?
     func configureCelebration(_ raw: Any?) {
         if raw != nil && celebration == nil { celebration = CraftNativeCelebration(view: self) }
@@ -2966,6 +2967,7 @@ private class CraftNativeFlowView: UIStackView {
     }
 
     func measure(width: CGFloat?, height: CGFloat?, maxWidth: CGFloat, maxHeight: CGFloat) -> CGSize {
+        if let page = pageViewport { return CGSize(width: page.width * CGFloat(arrangedSubviews.filter { !$0.isHidden }.count), height: page.height) }
         let key = MeasureKey(width: width, height: height, maxWidth: maxWidth, maxHeight: maxHeight)
         if let cached = measurements[key] { return cached }
         let size = layout(width: width, height: height, maxWidth: maxWidth, maxHeight: maxHeight, place: false).size
@@ -2977,6 +2979,12 @@ private class CraftNativeFlowView: UIStackView {
         super.layoutSubviews()
         craftApplyCornerRadius()
         celebration?.layout()
+        if let page = pageViewport {
+            for (index, child) in arrangedSubviews.filter({ !$0.isHidden }).enumerated() {
+                child.frame = CGRect(x: CGFloat(index) * page.width, y: 0, width: page.width, height: page.height)
+            }
+            return
+        }
         let scale = window?.screen.scale ?? traitCollection.displayScale
         let result = layout(width: bounds.width, height: bounds.height, maxWidth: bounds.width, maxHeight: bounds.height, place: true)
         var moved = false
@@ -4344,6 +4352,46 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
     private var laidOutSize: CGSize = .zero
     private let pullToRefresh = UIRefreshControl()
     private var refreshHandler: (() -> Void)?
+    private var authoredPageIndex: Int?
+    private var pendingPageIndex: Int?
+    private var currentPageIndex = 0
+    private var pageAnimating = false
+    private var reportedPage: (Int, Int)?
+    private var pageHandler: ((Int, Int) -> Void)?
+
+    /// Opt-in viewport-sized pages. Ordinary horizontal scroll strips retain
+    /// their intrinsic widths; only a controlled pageIndex enables this mode.
+    func configurePager(_ raw: Any?, onSelect: ((Int, Int) -> Void)?) {
+        let next = craftNativeNumber(raw).flatMap { number -> Int? in
+            let value = number.doubleValue
+            return value.isFinite ? Int(min(Double(Int.max / 2), max(0, value))) : nil
+        }
+        if next != authoredPageIndex { pendingPageIndex = next; contentNeedsLayout = true }
+        authoredPageIndex = next
+        pageHandler = onSelect
+        if next == nil { contentStack.pageViewport = nil; reportedPage = nil; pageAnimating = false }
+        setNeedsLayout()
+    }
+
+    func beginPageDrag() { pageAnimating = false }
+
+    func finishPageMotion() {
+        pageAnimating = false
+        DispatchQueue.main.async { [weak self] in self?.settlePage() }
+    }
+
+    func settlePage() {
+        guard authoredPageIndex != nil, bounds.width > 0, !pageAnimating,
+              !isTracking, !isDragging, !isDecelerating else { return }
+        let pages = contentStack.arrangedSubviews.filter { !$0.isHidden }
+        let index = min(max(0, Int((contentOffset.x / bounds.width).rounded())), max(0, pages.count - 1))
+        currentPageIndex = index
+        for (i, child) in pages.enumerated() { child.accessibilityElementsHidden = i != index }
+        if reportedPage?.0 != index || reportedPage?.1 != pages.count {
+            reportedPage = (index, pages.count)
+            pageHandler?(index, pages.count)
+        }
+    }
 
     override init(frame: CGRect) {
         super.init(frame: frame)
@@ -4384,6 +4432,11 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
     /// The size of the content laid out across the visible width (or, sideways,
     /// height), which is also the scroll view's own size when nothing fixes it.
     func contentFitting(width: CGFloat?, height: CGFloat?) -> CGSize {
+        if authoredPageIndex != nil && !isVertical {
+            let pageWidth = max(0, width ?? bounds.width)
+            let pageHeight = max(0, height ?? bounds.height)
+            return CGSize(width: pageWidth * CGFloat(contentStack.arrangedSubviews.filter { !$0.isHidden }.count), height: pageHeight)
+        }
         if isVertical {
             let contentWidth = max(0, (width ?? bounds.width) - adjustedContentInset.left - adjustedContentInset.right)
             return contentStack.measure(width: contentWidth, height: nil, maxWidth: contentWidth, maxHeight: CraftNativeFlexLayout.unbounded)
@@ -4406,7 +4459,9 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
         craftApplyCornerRadius()
         if contentNeedsLayout || laidOutSize != bounds.size {
             contentNeedsLayout = false
+            let resized = laidOutSize != bounds.size
             laidOutSize = bounds.size
+            if authoredPageIndex != nil && !isVertical { contentStack.pageViewport = bounds.size }
             var size = contentFitting(width: bounds.width, height: bounds.height)
             if isVertical {
                 size.width = max(0, bounds.width - adjustedContentInset.left - adjustedContentInset.right)
@@ -4416,12 +4471,31 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
             let frame = CGRect(origin: .zero, size: size)
             if contentStack.frame != frame { contentStack.frame = frame }
             if contentSize != size { contentSize = size }
+            if authoredPageIndex != nil && !isVertical {
+                contentStack.layoutIfNeeded()
+                let count = contentStack.arrangedSubviews.filter { !$0.isHidden }.count
+                let index = min(max(0, pendingPageIndex ?? currentPageIndex), max(0, count - 1))
+                let target = CGPoint(x: CGFloat(index) * bounds.width, y: 0)
+                let moves = pendingPageIndex != nil || resized || index != currentPageIndex
+                let animated = moves && target != contentOffset && !resized && !UIAccessibility.isReduceMotionEnabled
+                if moves {
+                    pageAnimating = animated
+                    setContentOffset(target, animated: animated)
+                }
+                pendingPageIndex = nil
+                currentPageIndex = index
+                if !animated && !isTracking && !isDragging && !isDecelerating { settlePage() }
+            }
         }
         // A scroll view lays out on every frame of a scroll: the sticky
         // headers follow it here, over content placed by this same pass.
         if !stickyIndices.isEmpty || pendingScrollTarget != nil { contentStack.layoutIfNeeded() }
         updateStickyHeaders()
         scrollToPendingTarget()
+        // A nonanimated target changes the offset synchronously inside this
+        // layout pass. Rebase the headers against that actual viewport, not
+        // the viewport from before the target was applied.
+        updateStickyHeaders()
     }
 
     // MARK: Sticky headers
@@ -4444,7 +4518,7 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
         view.center.y - view.bounds.height / 2
     }
 
-    private func updateStickyHeaders() {
+    fileprivate func updateStickyHeaders() {
         let children = contentStack.arrangedSubviews
         let headers = isVertical ? stickyIndices.compactMap { $0 < children.count ? children[$0] : nil }.filter { !$0.isHidden } : []
         for view in stickyViews where !headers.contains(where: { $0 === view }) {
@@ -4617,11 +4691,13 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
         craftScrollGesture(gestureRecognizer, runsWith: otherGestureRecognizer)
     }
 
-    func setAxis(_ axis: NSLayoutConstraint.Axis) {
+    func setAxis(_ axis: NSLayoutConstraint.Axis, resetBounce: Bool = true) {
         if contentStack.axis != axis { setContentNeedsLayout() }
         contentStack.axis = axis
-        alwaysBounceVertical = axis == .vertical
-        alwaysBounceHorizontal = axis == .horizontal
+        if resetBounce {
+            alwaysBounceVertical = axis == .vertical
+            alwaysBounceHorizontal = axis == .horizontal
+        }
     }
 }
 
@@ -8461,6 +8537,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             scroll.isScrollEnabled = props["scrollEnabled"] as? Bool != false
             scroll.bounces = props["bounces"] as? Bool ?? true
             scroll.isPagingEnabled = props["pagingEnabled"] as? Bool ?? false
+            let pageHandler = nonEmptyHandler(events["onPageSelected"])
+            scroll.configurePager(props["pageIndex"], onSelect: pageHandler.map { handler in
+                { [weak self] index, count in self?.send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": ["index": index, "count": count]]) }
+            })
             scroll.keyboardDismissMode = keyboardDismissMode(props["keyboardDismissMode"])
             scroll.setKeyboardShouldPersistTaps(props["keyboardShouldPersistTaps"])
             scroll.showsVerticalScrollIndicator = props["showsVerticalScrollIndicator"] as? Bool != false
@@ -8492,6 +8572,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 contentStyle.merge(override) { _, next in next }
             }
             configureStack(scroll.contentStack, style: contentStyle)
+            // Content-style defaults are vertical; the scroll host's explicit
+            // axis must survive that shared container configuration without
+            // resetting the authored bounce options applied above.
+            scroll.setAxis(direction, resetBounce: false)
             reconcileChildren(children.filter {
                 guard let child = $0 as? [String: Any] else { return true }
                 return canonicalType(child["type"] as? String ?? "") != "RefreshControl"
@@ -9712,10 +9796,28 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             for: size,
             compatibleWith: traitCollection
         )
-        var font = (style["fontFamily"] as? String).flatMap { UIFont(name: $0, size: scaledSize) }
-            ?? .systemFont(ofSize: scaledSize, weight: weight)
+        let families = (style["fontFamily"] as? String ?? "").split(separator: ",").map {
+            $0.trimmingCharacters(in: .whitespacesAndNewlines).trimmingCharacters(in: CharacterSet(charactersIn: "\"'"))
+        }
+        let selectedFont = families.lazy.compactMap { family -> UIFont? in
+            switch family.lowercased() {
+            case "monospace", "ui-monospace": return .monospacedSystemFont(ofSize: scaledSize, weight: weight)
+            case "serif", "ui-serif":
+                let system = UIFont.systemFont(ofSize: scaledSize, weight: weight)
+                return system.fontDescriptor.withDesign(.serif).map { UIFont(descriptor: $0, size: scaledSize) }
+            case "sans-serif", "ui-sans-serif", "system-ui", "-apple-system": return .systemFont(ofSize: scaledSize, weight: weight)
+            default:
+                guard let custom = UIFont(name: family, size: scaledSize) else { return nil }
+                let weighted = custom.fontDescriptor.addingAttributes([.traits: [UIFontDescriptor.TraitKey.weight: weight.rawValue]])
+                var traits = custom.fontDescriptor.symbolicTraits
+                if weight >= .semibold { traits.insert(.traitBold) } else { traits.remove(.traitBold) }
+                let descriptor = weighted.withSymbolicTraits(traits) ?? weighted
+                return UIFont(descriptor: descriptor, size: scaledSize)
+            }
+        }.first
+        var font = selectedFont ?? .systemFont(ofSize: scaledSize, weight: weight)
         if style["fontStyle"] as? String == "italic",
-           let descriptor = font.fontDescriptor.withSymbolicTraits(.traitItalic) {
+           let descriptor = font.fontDescriptor.withSymbolicTraits(font.fontDescriptor.symbolicTraits.union(.traitItalic)) {
             font = UIFont(descriptor: descriptor, size: scaledSize)
         }
         return font
@@ -10502,6 +10604,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     func scrollViewDidScroll(_ scrollView: UIScrollView) {
+        // Sticky positioning is a native scroll behavior and must also run
+        // without a JavaScript onScroll subscription, including animations.
+        (scrollView as? CraftNativeScrollView)?.updateStickyHeaders()
         guard let handler = scrollHandlers[ObjectIdentifier(scrollView)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": scrollEvent(scrollView)])
     }
@@ -10510,12 +10615,13 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     func scrollViewWillBeginDragging(_ scrollView: UIScrollView) {
         CraftFramePacing.shared.begin(pacingName)
+        (scrollView as? CraftNativeScrollView)?.beginPageDrag()
         guard let handler = scrollBeginHandlers[ObjectIdentifier(scrollView)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": scrollEvent(scrollView)])
     }
 
     func scrollViewDidEndDragging(_ scrollView: UIScrollView, willDecelerate decelerate: Bool) {
-        if !decelerate { CraftFramePacing.shared.end(pacingName) }
+        if !decelerate { CraftFramePacing.shared.end(pacingName); (scrollView as? CraftNativeScrollView)?.finishPageMotion() }
         guard let handler = scrollEndHandlers[ObjectIdentifier(scrollView)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": scrollEvent(scrollView)])
     }
@@ -10527,10 +10633,15 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
 
     func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) {
         CraftFramePacing.shared.end(pacingName)
+        (scrollView as? CraftNativeScrollView)?.finishPageMotion()
         guard let handler = scrollMomentumEndHandlers[ObjectIdentifier(scrollView)] else { return }
         send(type: "EVENT", payload: ["handlerName": handler, "nativeEvent": scrollEvent(scrollView)])
     }
 
+    func scrollViewDidEndScrollingAnimation(_ scrollView: UIScrollView) {
+        (scrollView as? CraftNativeScrollView)?.finishPageMotion()
+    }
+
     private func scrollEvent(_ scrollView: UIScrollView) -> [String: Any] {
         [
             "contentOffset": ["x": scrollView.contentOffset.x, "y": scrollView.contentOffset.y],

package/templates/testing/DriverTests.swift.template

@@ -22,6 +22,7 @@ import Darwin
 ///   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
+///   holdtab <name> [| secs] standard XCTest hold (2–10s, default 6), BEGIN/END timing receipt
 ///   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
@@ -381,6 +382,43 @@ final class DriverTests: XCTestCase {
             }
             target.press(forDuration: 1.2)
             note("longpressid \(arg): ok")
+        case "holdtab":
+            let parts = arg.components(separatedBy: "|").map { $0.trimmingCharacters(in: .whitespaces) }
+            guard parts.count <= 2, let name = parts.first, !name.isEmpty,
+                  let duration = parts.count == 2 ? Double(parts[1]) : 6,
+                  duration.isFinite, (2...10).contains(duration) else {
+                check(false, "holdtab needs a tab name and 2–10 seconds")
+                return
+            }
+            guard let button = poll(10, { tabButton(name) }) else {
+                check(false, "holdtab cannot find tab \(name)")
+                return
+            }
+            let frame = button.frame
+            let coordinate = button.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.5))
+            let startedAt = Date().timeIntervalSince1970
+            let startedUptime = ProcessInfo.processInfo.systemUptime
+            // BEGIN arms the independent screenshot watcher. XCTest still
+            // performs its normal idle checks before synthesizing the press;
+            // the watcher must wait for that synthesis, not infer touch-down.
+            note("BEGIN holdtab \(name) | \(duration) | \(startedAt)")
+            fflush(nil)
+            coordinate.press(forDuration: duration)
+            let returnedAt = Date().timeIntervalSince1970
+            let returnedUptime = ProcessInfo.processInfo.systemUptime
+            note("END holdtab \(name) | \(returnedAt)")
+            let receipt: [String: Any] = [
+                "tab": name, "requestedSeconds": duration,
+                "input": "XCUICoordinate.press(forDuration:)",
+                "startedAt": startedAt, "returnedAt": returnedAt,
+                "startedUptime": startedUptime, "returnedUptime": returnedUptime,
+                "frame": ["x": frame.minX, "y": frame.minY, "width": frame.width, "height": frame.height],
+                "note": "Call times include XCTest idle checks; during-hold screenshots require an independent synthesis-timed capture.",
+            ]
+            if let data = try? JSONSerialization.data(withJSONObject: receipt, options: [.sortedKeys]) {
+                post("/save?name=holdtab-\(Int(startedUptime * 1000)).json", data)
+            }
+            check(true, "holdtab \(name): standard \(duration)s press returned")
         case "touches":
             do {
                 guard let data = arg.data(using: .utf8),