@craft-native/ios 0.0.202 → 0.0.203

package/README.md

@@ -129,6 +129,9 @@ authorization or requiring local notifications to be enabled.
 Keyboard frame changes update the native controller's additional safe area, so
 focused inputs and responsive `onLayout` measurements move with the keyboard.
 
+Shared view transforms, z-order, and view/text shadows are applied by UIKit
+with the same style keys as Android; `elevation` remains Android-specific.
+
 The opt-in `native` renderer hosts compiled `.stx` screens in JavaScriptCore and renders their `View`, `SafeAreaView`, `Text`, `Button`, `Link`, `Checkbox`, `TextInput`, `Picker`, `DatePicker`, `Switch`, `Slider`, `ActivityIndicator`, `Icon`, `Image`, `ImageBackground`, `Video`, `Map`, `Svg`, `G`, `SvgText`, `ScrollView`, `SectionList`, and recycling `FlatList` nodes as UIKit controls. `Map` uses MapKit for trail polylines and marker taps; its overlays carry flat latitude/longitude `geometry` arrays and can fit the visible region to their bounds. `Svg` is a DOM-free drawing surface; grouped `G` and `SvgText` nodes are painted inside it. `Icon` uses SF Symbols with the shared symbol/name contract and accessibility metadata. `SectionList` uses the same native scroll host for ordinary `.stx` slot children; grouped section data should use `FlatList` until the section-data protocol is available. `FlatList` uses `UICollectionView` with stable keyed rows, incremental diffs, grids, horizontal and inverted layouts, list chrome, and end-reached pagination. Native views support `onLayout` callbacks with point-based frame measurements that refresh after safe-area or orientation changes. Flex items support `flex`, `flexGrow`, `flexShrink`, and numeric `flexBasis` for main-axis space distribution. Native screens also expose the versioned capability bridge: JSON storage and SQLite survive relaunch, lifecycle and deep-link events are scoped to the top route, and local notifications use `UNUserNotificationCenter`. Enable each capability in `craft.config.json`; disabled calls preserve Craft's `CAPABILITY_DISABLED` rejection code and every request has deterministic timeout/cancellation behavior. The default remains `web`; existing iOS apps are unchanged. `Checkbox` supports controlled `checked`/`value`, indeterminate state, and boolean `onValueChange`; `Picker` renders `<select>`/`<option>` values with `onValueChange` or `onChange`; `DatePicker` emits local date/time values plus ISO and millisecond timestamps; `Switch` supports state-aware `trackColor`, `thumbColor`, and iOS `ios_backgroundColor`; `Slider` supports track/thumb tint props and `step` snapping; `Image` reports load lifecycle events and structured failures; `Video` uses an `AVPlayerViewController` attached to the native screen for URI playback, native controls, and route-safe teardown. The portable component, capability, list, style, image-source, event, accessibility, and reconciliation behavior is specified in the [Native STX guide](../../docs/guides/native-stx.md).
 
 ```bash
@@ -996,6 +999,10 @@ Options:
   -s, --simulator           Run on simulator
 ```
 
+Simulator selection uses the active Xcode's iOS Simulator SDK. Runtimes newer
+than that SDK are excluded, including already booted devices. Select a matching
+Xcode or install a compatible runtime when none is available.
+
 ## Requirements
 
 - macOS with Xcode 15+

package/dist/cli.js

@@ -1123,21 +1123,34 @@ async function open(options) {
   console.log(`\uD83D\uDE80 Opening ${xcodeproj}...`);
   await $`open ${projectPath}`;
 }
-function orderSimulators(devices) {
-  return devices.filter((device) => device.runtime.startsWith("iOS")).sort((left, right) => {
+function orderSimulators(devices, sdkVersion) {
+  const sdk = sdkVersion?.match(/^(\d+)\.(\d+)/);
+  if (sdkVersion !== undefined && !sdk)
+    throw new Error(`Invalid iOS Simulator SDK version: ${sdkVersion}`);
+  return devices.filter((device) => device.runtime.startsWith("iOS")).filter((device) => {
+    if (!sdk)
+      return true;
+    const runtime = device.runtime.match(/^iOS-(\d+)-(\d+)/);
+    if (!runtime)
+      return false;
+    return Number(runtime[1]) < Number(sdk[1]) || Number(runtime[1]) === Number(sdk[1]) && Number(runtime[2]) <= Number(sdk[2]);
+  }).sort((left, right) => {
     const booted = Number(right.state === "Booted") - Number(left.state === "Booted");
     if (booted !== 0)
       return booted;
     const phone = Number(right.name.startsWith("iPhone")) - Number(left.name.startsWith("iPhone"));
     if (phone !== 0)
       return phone;
-    return right.runtime.localeCompare(left.runtime);
+    return right.runtime.localeCompare(left.runtime, undefined, { numeric: true });
   });
 }
 async function pickSimulator() {
   const listed = await $`xcrun simctl list devices available --json`.quiet().nothrow();
   if (listed.exitCode !== 0)
     return null;
+  const sdk = await $`xcrun --sdk iphonesimulator --show-sdk-version`.quiet().nothrow();
+  if (sdk.exitCode !== 0)
+    throw new Error("Could not determine the selected Xcode iOS Simulator SDK");
   let parsed;
   try {
     parsed = JSON.parse(listed.stdout.toString());
@@ -1149,7 +1162,7 @@ async function pickSimulator() {
     for (const device of list)
       devices.push({ ...device, runtime: runtime.split(".").pop() ?? runtime });
   }
-  return orderSimulators(devices)[0] ?? null;
+  return orderSimulators(devices, sdk.stdout.toString().trim())[0] ?? null;
 }
 async function bootSimulator(device) {
   if (device.state !== "Booted")

package/dist/index.d.ts

@@ -524,7 +524,7 @@ export interface SimulatorDevice {
  * Exported because the choice is worth testing without a simulator present -
  * `pickSimulator` is the policy and this is the data it reads.
  */
-export declare function orderSimulators(devices: SimulatorDevice[]): SimulatorDevice[];
+export declare function orderSimulators(devices: SimulatorDevice[], sdkVersion?: string): SimulatorDevice[];
 /**
  * The device to run on.
  *

package/dist/index.js

@@ -1260,21 +1260,34 @@ async function open(options) {
   console.log(`\uD83D\uDE80 Opening ${xcodeproj}...`);
   await $`open ${projectPath}`;
 }
-function orderSimulators(devices) {
-  return devices.filter((device) => device.runtime.startsWith("iOS")).sort((left, right) => {
+function orderSimulators(devices, sdkVersion) {
+  const sdk = sdkVersion?.match(/^(\d+)\.(\d+)/);
+  if (sdkVersion !== undefined && !sdk)
+    throw new Error(`Invalid iOS Simulator SDK version: ${sdkVersion}`);
+  return devices.filter((device) => device.runtime.startsWith("iOS")).filter((device) => {
+    if (!sdk)
+      return true;
+    const runtime = device.runtime.match(/^iOS-(\d+)-(\d+)/);
+    if (!runtime)
+      return false;
+    return Number(runtime[1]) < Number(sdk[1]) || Number(runtime[1]) === Number(sdk[1]) && Number(runtime[2]) <= Number(sdk[2]);
+  }).sort((left, right) => {
     const booted = Number(right.state === "Booted") - Number(left.state === "Booted");
     if (booted !== 0)
       return booted;
     const phone = Number(right.name.startsWith("iPhone")) - Number(left.name.startsWith("iPhone"));
     if (phone !== 0)
       return phone;
-    return right.runtime.localeCompare(left.runtime);
+    return right.runtime.localeCompare(left.runtime, undefined, { numeric: true });
   });
 }
 async function pickSimulator() {
   const listed = await $`xcrun simctl list devices available --json`.quiet().nothrow();
   if (listed.exitCode !== 0)
     return null;
+  const sdk = await $`xcrun --sdk iphonesimulator --show-sdk-version`.quiet().nothrow();
+  if (sdk.exitCode !== 0)
+    throw new Error("Could not determine the selected Xcode iOS Simulator SDK");
   let parsed;
   try {
     parsed = JSON.parse(listed.stdout.toString());
@@ -1286,7 +1299,7 @@ async function pickSimulator() {
     for (const device of list)
       devices.push({ ...device, runtime: runtime.split(".").pop() ?? runtime });
   }
-  return orderSimulators(devices)[0] ?? null;
+  return orderSimulators(devices, sdk.stdout.toString().trim())[0] ?? null;
 }
 async function bootSimulator(device) {
   if (device.state !== "Booted")

package/package.json

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

package/templates/CraftHybrid.swift

@@ -972,9 +972,26 @@ final class CraftHybridWebSlot: UIViewController {
     /// page's stack is all the page's.
     var depth: Int?
     let isTabRoot: Bool
-    /// The page has not reached `path` yet: the entry shows its background,
-    /// not the page it is leaving, until it has.
+    /// The page has not reached `path` yet: retain its last rendered content
+    /// until the replacement is ready.
     var awaitingPage = false
+    /// A slow page keeps the last rendered content until its replacement is
+    /// ready. This belongs to the incoming slot, beyond the push animation.
+    private(set) var waitingPageSnapshot: UIView?
+
+    func keepPageVisible(_ snapshot: UIView) {
+        waitingPageSnapshot?.removeFromSuperview()
+        snapshot.frame = view.bounds
+        snapshot.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        snapshot.accessibilityElementsHidden = true
+        view.addSubview(snapshot)
+        waitingPageSnapshot = snapshot
+    }
+
+    func pageBecameVisible() {
+        waitingPageSnapshot?.removeFromSuperview()
+        waitingPageSnapshot = nil
+    }
 
     init(path: String, depth: Int?, isTabRoot: Bool) {
         self.path = path
@@ -1331,6 +1348,10 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         snapshot.autoresizingMask = [.flexibleWidth, .flexibleHeight]
         source.view.addSubview(snapshot)
         webTransitionSnapshots.append(snapshot)
+        if slot.awaitingPage,
+           let waiting = webHost.view.snapshotView(afterScreenUpdates: false) {
+            slot.keepPageVisible(waiting)
+        }
     }
 
     private var visibleStack: UINavigationController? { stacks[currentTab] }
@@ -1423,6 +1444,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         attachWeb()
         moveWeb(to: slot, in: slot.view)
         webHost.view.alpha = slot.awaitingPage ? 0 : 1
+        if !slot.awaitingPage { slot.pageBecameVisible() }
         hybrid.setPageBase(slot.isTabRoot ? nil : slot.depth)
     }
 
@@ -1534,7 +1556,10 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     private func reveal(_ slot: CraftHybridWebSlot) {
         slot.awaitingPage = false
         guard let webHost, webHost.view.superview === slot.view else { return }
-        UIView.animate(withDuration: 0.15) { webHost.view.alpha = 1 }
+        // Commit the ready page and remove its placeholder in the same frame.
+        // Fading it up from zero exposed the slot's empty background again.
+        webHost.view.alpha = 1
+        slot.pageBecameVisible()
     }
 
     /// Back from the web entry on top, as the page's Back at that entry asks.

package/templates/CraftNativeFiles.swift

@@ -555,11 +555,13 @@ enum CraftNativeMedia {
         let staging = root.appendingPathComponent(UUID().uuidString + ".part")
         defer { try? fm.removeItem(at: staging) }
         do {
-            let size = (try location.resourceValues(forKeys: [.fileSizeKey])).fileSize ?? 0
+            // URL resource values can retain a previous size when a retry
+            // reuses a temporary location. Validate the current file itself.
+            let size = (try fm.attributesOfItem(atPath: location.path)[.size] as? NSNumber)?.int64Value ?? 0
             // URLSession normally rejects a truncated transfer; also guard this boundary.
             let expected = response.expectedContentLength
             let encoded = response.value(forHTTPHeaderField: "Content-Encoding")
-            if size <= 0 || (encoded == nil && expected >= 0 && Int64(size) != expected) {
+            if size <= 0 || (encoded == nil && expected >= 0 && size != expected) {
                 return .failure(CraftNativeActionError(code: "NETWORK_ERROR", message: "media.keep received an incomplete file"))
             }
             var folder = root

package/templates/CraftNativeFlatList.swift

@@ -1,11 +1,40 @@
 import UIKit
 
 private final class CraftNativeFlatListLayout: UICollectionViewFlowLayout {
+    private var preparedExtent: CGFloat?
+
+    override func prepare() {
+        // Content-size queries can prepare layout before layoutSubviews runs.
+        (collectionView as? CraftNativeFlatList)?.updateItemEstimate()
+        super.prepare()
+        preparedExtent = collectionView.map { extent(of: $0.bounds) }
+    }
+
+    private func extent(of bounds: CGRect) -> CGFloat {
+        scrollDirection == .vertical ? bounds.width : bounds.height
+    }
+
     override func shouldInvalidateLayout(forBoundsChange newBounds: CGRect) -> Bool {
-        guard let current = collectionView?.bounds else { return true }
-        return scrollDirection == .vertical
-            ? abs(current.width - newBounds.width) > .ulpOfOne
-            : abs(current.height - newBounds.height) > .ulpOfOne
+        guard let preparedExtent else { return true }
+        return abs(preparedExtent - extent(of: newBounds)) > .ulpOfOne
+    }
+
+    override func invalidationContext(forBoundsChange newBounds: CGRect) -> UICollectionViewLayoutInvalidationContext {
+        let context = super.invalidationContext(forBoundsChange: newBounds)
+        if shouldInvalidateLayout(forBoundsChange: newBounds), let flow = context as? UICollectionViewFlowLayoutInvalidationContext {
+            flow.invalidateFlowLayoutDelegateMetrics = true
+            flow.invalidateFlowLayoutAttributes = true
+            // Self-sized item dimensions are cached separately from flow
+            // metrics. Clear them before a narrower viewport validates old
+            // widths, while keeping the cells and their rendered state.
+            if let collectionView {
+                let paths = (0..<collectionView.numberOfSections).flatMap { section in
+                    (0..<collectionView.numberOfItems(inSection: section)).map { IndexPath(item: $0, section: section) }
+                }
+                flow.invalidateItems(at: paths)
+            }
+        }
+        return context
     }
 }
 
@@ -190,9 +219,30 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
     /// room again as they are.
     func fittingHeight(width: CGFloat) -> CGFloat {
         guard !isScrollEnabled else { return 0 }
-        if abs(bounds.width - width) > 0.5 { frame.size.width = width }
-        layoutIfNeeded()
-        let content = flowLayout.collectionViewContentSize.height
+        // Flex measurement proposes several widths before committing a frame.
+        // Mutating the collection here lets self-sizing cache a provisional
+        // width and can reenter parent measurement through contentSize.didSet.
+        // Read the committed measurement, or estimate until layout measures
+        // rows at their actual width and onFittingHeightChanged asks for room.
+        let content: CGFloat
+        if abs(bounds.width - width) <= 0.5, contentSize.height > 0 {
+            content = contentSize.height
+        } else if flowLayout.scrollDirection == .horizontal {
+            content = items.isEmpty ? 0 : 44
+        } else {
+            var rows = 0
+            var pending = 0
+            for item in items {
+                if item.isChrome {
+                    rows += (pending + columns - 1) / columns + 1
+                    pending = 0
+                } else {
+                    pending += 1
+                }
+            }
+            rows += (pending + columns - 1) / columns
+            content = CGFloat(rows) * 44 + CGFloat(max(0, rows - 1)) * flowLayout.minimumLineSpacing
+        }
         return max(0, ceil(content + contentInset.top + contentInset.bottom))
     }
 
@@ -208,13 +258,17 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
         return max(1, (width - spacing) / CGFloat(count))
     }
 
-    override func layoutSubviews() {
+    fileprivate func updateItemEstimate() {
         let estimate = flowLayout.scrollDirection == .horizontal
             ? CGSize(width: 44, height: itemExtent(isChrome: true))
             : CGSize(width: itemExtent(isChrome: false), height: 44)
         if flowLayout.estimatedItemSize != estimate, bounds.width > 0 {
             flowLayout.estimatedItemSize = estimate
         }
+    }
+
+    override func layoutSubviews() {
+        updateItemEstimate()
         super.layoutSubviews()
         craftApplyCornerRadius()
     }

package/templates/CraftNativeScreen.swift

@@ -4650,16 +4650,22 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         }
         /// The scroll view the screen starts with, when nothing sits above it:
         /// the root's first child, its first, and so on, none padded on top.
-        func leading(_ node: RenderedNode) -> UIScrollView? {
-            if let scroll = node.view as? CraftNativeScrollView { return scroll.isVertical && scroll.isScrollEnabled ? scroll : nil }
+        func leading(_ node: RenderedNode) -> RenderedNode? {
+            if let scroll = node.view as? CraftNativeScrollView { return scroll.isVertical && scroll.isScrollEnabled ? node : nil }
             if let list = node.view as? CraftNativeFlatList {
-                return list.isScrollEnabled && (list.collectionViewLayout as? UICollectionViewFlowLayout)?.scrollDirection != .horizontal ? list : nil
+                return list.isScrollEnabled && (list.collectionViewLayout as? UICollectionViewFlowLayout)?.scrollDirection != .horizontal ? node : nil
             }
             guard paddingInsets(node.style).top == 0,
                   let first = node.children.first(where: { $0.type != "Modal" && !$0.view.isHidden }) else { return nil }
             return leading(first)
         }
         let scroll = find(renderedRoot)
+        let leadingScroll = leading(renderedRoot)
+        // Only the screen's leading scroller draws beneath floating chrome.
+        // A bounded list inside a form must clip its rows to its viewport.
+        if let leadingScroll, leadingScroll.style["overflow"] as? String != "hidden" {
+            leadingScroll.view.clipsToBounds = false
+        }
         // Under a large title the screen runs edge to edge, as UIKit's own
         // screens do: the scroll view starts under the bar and insets its
         // content by it, so the title collapses and pull to refresh draws
@@ -4667,7 +4673,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         // view: its content scrolls up under the bar behind iOS's scroll edge
         // effect, rather than over the bar's back button. Other screens stay
         // inside the safe area.
-        let edgeToEdge = scroll != nil && (prefersLargeTitle == true || scroll === leading(renderedRoot))
+        let edgeToEdge = scroll != nil && (prefersLargeTitle == true || scroll === leadingScroll?.view)
         let fullEdgeToEdge = rootIsSafeAreaView
         let topEdgeToEdge = fullEdgeToEdge || edgeToEdge
         rootTopToSafeArea?.isActive = !topEdgeToEdge
@@ -5801,6 +5807,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         case "sectionlist": return "SectionList"
         case "flatlist": return "FlatList"
         case "svg": return "Svg"
+        case "g": return "G"
+        case "svgtext", "svg-text": return "SvgText"
         case "touchableopacity": return "TouchableOpacity"
         case "touchablehighlight": return "TouchableHighlight"
         case "pressable": return "Pressable"
@@ -5848,7 +5856,20 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             stack.removeArrangedSubview(spacer)
             spacer.removeFromSuperview()
         }
-        let nodes = children.compactMap { $0 as? [String: Any] }
+        // STX permits text directly inside containers (including HTML links).
+        // Give it a native label, inheriting typography without duplicating
+        // the parent's padding, dimensions or flex layout.
+        let typography = style.filter { key, _ in
+            key == "color" || key == "letterSpacing" || key == "lineHeight"
+                || key.hasPrefix("font") || key.hasPrefix("text")
+        }
+        let nodes = children.compactMap { child -> [String: Any]? in
+            if let node = child as? [String: Any] { return node }
+            if let text = child as? String {
+                return ["type": "Text", "style": typography, "children": [text]]
+            }
+            return nil
+        }
         let keys = nodes.compactMap { explicitKey($0, props: $0["props"] as? [String: Any] ?? [:]) }
         let counts = Dictionary(keys.map { ($0, 1) }, uniquingKeysWith: +)
         let old = Dictionary(uniqueKeysWithValues: parent.children.map { ($0.identity, $0) })
@@ -6157,10 +6178,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     /// Views that take their own touches whatever handlers the screen gives
-    /// them: a scroll view, a modal, and a video's system controls (with
+    /// them: native controls, a scroll view, a modal, and a video's controls (with
     /// interaction off, its play, scrubber and full screen never answered).
     private func ownsTouches(_ view: UIView) -> Bool {
-        view is UIScrollView || view is CraftNativeModalView || view is CraftNativeVideoView
+        view is UIControl || view is UIScrollView || view is CraftNativeModalView || view is CraftNativeVideoView
     }
 
     private func updatePressHandler(_ handler: String?, for view: UIView) {
@@ -6172,7 +6193,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             let recognizer = UITapGestureRecognizer(target: self, action: #selector(viewPressed(_:)))
             tapRecognizers[id] = recognizer
             view.addGestureRecognizer(recognizer)
-        } else if handler == nil, let recognizer = tapRecognizers.removeValue(forKey: id) {
+        } else if !actionable, let recognizer = tapRecognizers.removeValue(forKey: id) {
             view.removeGestureRecognizer(recognizer)
         }
         // A container keeps receiving touches without a handler of its own,
@@ -6420,11 +6441,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         )
         // A label paints its background inside its own bounds, so a rounded
         // chip of text clips to its corners.
-        // A scroll view does not clip either: its content runs on under the
-        // floating tab bar and the home indicator, as iOS 26's own screens'
-        // does. At the top, a screen that starts with one runs edge to edge
-        // (trackContentScrollView), so nothing scrolls over the bar.
-        view.clipsToBounds = style["overflow"] as? String == "hidden"
+        // Native scrollers clip their viewport unless explicitly made
+        // visible. trackContentScrollView opens only the leading scroller
+        // beneath the screen's floating chrome.
+        let overflow = style["overflow"] as? String
+        view.clipsToBounds = overflow == "hidden"
+            || (view is UIScrollView && overflow != "visible")
             || (view is UILabel && (view.craftRequestedCornerRadius ?? 0) > 0)
         view.layer.masksToBounds = view.clipsToBounds
         view.craftLayoutStyle = CraftNativeLayoutStyle(style)
@@ -6809,7 +6831,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         } else if type != "TextInput" {
             view.accessibilityValue = nil
         }
-        let role = props["accessibilityRole"] as? String
+        let hasLinkTarget = ["href", "to"].contains { !(props[$0] as? String ?? "").isEmpty }
+        let linkedControl = ["Link", "TouchableOpacity", "TouchableHighlight", "Pressable"].contains(type) && hasLinkTarget
+        let role = (props["accessibilityRole"] as? String) ?? (linkedControl ? "link" : 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