@craft-native/ios 0.0.395 → 0.0.396

package/package.json

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

package/templates/CraftNativeFlatList.swift

@@ -42,6 +42,10 @@ private final class CraftNativeFlatListLayout: UICollectionViewFlowLayout {
 /// The screen controller owns rendered row state; this view owns collection
 /// diffs, viewport state, and UICollectionView cell reuse.
 final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowLayout, UIGestureRecognizerDelegate {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     typealias RenderItem = (_ node: [String: Any], _ identity: String, _ previous: UIView?) -> UIView
 
     private final class Cell: UICollectionViewCell {

package/templates/CraftNativeMutation.swift

@@ -35,6 +35,9 @@ final class CraftNativeMutationDocument {
         var style: [String: Any]
         var events: [String: Any]
         var text: [String]
+        // Legacy snapshots may interleave bare text and native children.
+        // Keep each text fragment's slot among the child nodes on import.
+        var textPositions: [Int]? = nil
         var children: [String]
         var parent: String?
     }
@@ -43,6 +46,11 @@ final class CraftNativeMutationDocument {
     private var rootId: String?
     private(set) var revision = 0
 
+    /// The normalized committed tree, whose root need not be named "root".
+    var document: [String: Any]? {
+        rootId.flatMap { materialize($0, nodes: nodes) }
+    }
+
     func replace(with document: [String: Any]) {
         var replacement: [String: Node] = [:]
         let root = importNode(document, preferredId: "root", parent: nil, nodes: &replacement)
@@ -217,6 +225,7 @@ final class CraftNativeMutationDocument {
         if patch.keys.contains("events") { mergePatch(patch["events"], into: &node.events) }
         if patch.keys.contains("children") || patch.keys.contains("text") {
             node.text = try textChildren(patch["children"] ?? patch["text"])
+            node.textPositions = nil
         }
         nodes[id] = node
     }
@@ -422,9 +431,18 @@ final class CraftNativeMutationDocument {
             "events": node.events,
         ]
         if let key = node.key { value["key"] = key }
-        let text: [Any] = node.text
         let children: [Any] = node.children.compactMap { materialize($0, nodes: nodes) }
-        value["children"] = text + children
+        var content: [Any] = []
+        var textIndex = 0
+        for index in 0...children.count {
+            while textIndex < node.text.count,
+                  min(node.textPositions?[textIndex] ?? 0, children.count) == index {
+                content.append(node.text[textIndex])
+                textIndex += 1
+            }
+            if index < children.count { content.append(children[index]) }
+        }
+        value["children"] = content
         return value
     }
 
@@ -440,6 +458,12 @@ final class CraftNativeMutationDocument {
         var id = explicit ?? key.map { "\(parent ?? "root")/key:\($0)" } ?? preferredId
         if nodes[id] != nil { id = "\(preferredId)#\(nodes.count)" }
         let children = value["children"] as? [Any] ?? []
+        var textPositions: [Int] = []
+        var childCount = 0
+        for child in children {
+            if child is String { textPositions.append(childCount) }
+            else if child is [String: Any] { childCount += 1 }
+        }
         nodes[id] = Node(
             id: id,
             key: value["key"] as? String,
@@ -448,6 +472,7 @@ final class CraftNativeMutationDocument {
             style: dictionary(value["style"]),
             events: dictionary(value["events"]),
             text: children.compactMap { $0 as? String },
+            textPositions: textPositions,
             children: [],
             parent: parent
         )

package/templates/CraftNativeScreen.swift

@@ -1108,6 +1108,10 @@ private func craftNativeAlignContentCode(_ value: String) -> UInt32 {
 
 /// Keep the indicator's intrinsic size separate from authored style transforms.
 private final class CraftNativeActivityIndicatorView: UIActivityIndicatorView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     var indicatorScale: CGFloat = 1
 }
 
@@ -1122,6 +1126,10 @@ private final class CraftNativeActivityIndicatorView: UIActivityIndicatorView {
 /// `enableBackgroundAudio` writes), and comes back into its place when the
 /// app does.
 private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     private let playerController = AVPlayerViewController()
     private var player: AVPlayer?
     private var sourceURI = ""
@@ -1454,6 +1462,10 @@ private final class CraftMarkerPhotoRedirects: NSObject, URLSessionTaskDelegate
 }
 
 private final class CraftNativeMapView: MKMapView, MKMapViewDelegate {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     private var annotationsByID: [String: MKPointAnnotation] = [:]
     private var overlaysByID: [String: MKPolyline] = [:]
     private var overlayCoordinatesByID: [String: [CLLocationCoordinate2D]] = [:]
@@ -2394,6 +2406,46 @@ private final class CraftNativeLayoutStyleBox {
     init(_ style: CraftNativeLayoutStyle) { self.style = style }
 }
 
+/// Pointer policy applies to authored nodes, not UIKit's private control views.
+enum CraftNativePointerEvents: String {
+    case auto, none
+    case boxNone = "box-none"
+    case boxOnly = "box-only"
+
+    static func resolve(props: [String: Any], style: [String: Any]) -> Self {
+        let prop = props["pointerEvents"]
+        let value = prop == nil || prop is NSNull ? style["pointerEvents"] : prop
+        return (value as? String).flatMap(Self.init(rawValue:)) ?? .auto
+    }
+}
+
+private var craftNativePointerEventsKey: UInt8 = 0
+
+extension UIView {
+    // nil identifies an internal view; even authored `auto` nodes are marked.
+    var craftPointerEvents: CraftNativePointerEvents? {
+        get { (objc_getAssociatedObject(self, &craftNativePointerEventsKey) as? String).flatMap(CraftNativePointerEvents.init(rawValue:)) }
+        set { objc_setAssociatedObject(self, &craftNativePointerEventsKey, newValue?.rawValue, .OBJC_ASSOCIATION_COPY_NONATOMIC) }
+    }
+
+    func craftPointerHitTest(_ point: CGPoint, with event: UIEvent?, native: () -> UIView?) -> UIView? {
+        guard let policy = craftPointerEvents, policy != .auto else { return native() }
+        guard policy != .none, !isHidden, alpha > 0.01, isUserInteractionEnabled else { return nil }
+        if policy == .boxOnly && !self.point(inside: point, with: event) { return nil }
+        let hit = native()
+        var candidate = hit
+        var authoredChild = false
+        while let view = candidate, view !== self {
+            if view.craftPointerEvents != nil { authoredChild = true; break }
+            candidate = view.superview
+        }
+        if policy == .boxNone { return authoredChild ? hit : nil }
+        // Preserve private controls (picker wheels, text selection, map gestures),
+        // while excluding authored descendants of a box-only container.
+        return authoredChild ? self : hit ?? self
+    }
+}
+
 private var craftNativeLayoutStyleKey: UInt8 = 0
 private var craftNativeCornerRadiusKey: UInt8 = 0
 private var craftNativeCornerRadiiKey: UInt8 = 0
@@ -3021,12 +3073,14 @@ private class CraftNativeFlowView: UIStackView {
     /// is inside the view, so a floating button absolutely positioned out of a
     /// zero-height parent (a component's wrapper) drew but could not be tapped.
     override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
-        if let hit = super.hitTest(point, with: event) { return hit }
-        guard !clipsToBounds, !isHidden, alpha > 0.01, isUserInteractionEnabled else { return nil }
-        for child in subviews.reversed() where !child.isHidden && child.alpha > 0.01 && child.isUserInteractionEnabled {
-            if let hit = child.hitTest(child.convert(point, from: self), with: event) { return hit }
+        return craftPointerHitTest(point, with: event) {
+            if let hit = super.hitTest(point, with: event) { return hit }
+            guard !clipsToBounds, !isHidden, alpha > 0.01, isUserInteractionEnabled else { return nil }
+            for child in subviews.reversed() where !child.isHidden && child.alpha > 0.01 && child.isUserInteractionEnabled {
+                if let hit = child.hitTest(child.convert(point, from: self), with: event) { return hit }
+            }
+            return nil
         }
-        return nil
     }
 
     // MARK: Children
@@ -4100,10 +4154,107 @@ private final class CraftNativeKeyboardAvoidingView: CraftNativeFlowView {
     }
 }
 
+// Preserve source dimensions when the loader downsamples decoded pixels. CSS
+// scale-down/none use intrinsic dimensions, never the thumbnail's display size.
+private var craftImageIntrinsicKey: UInt8 = 0
+private extension UIImage {
+    var craftIntrinsicSize: CGSize {
+        get { (objc_getAssociatedObject(self, &craftImageIntrinsicKey) as? NSValue)?.cgSizeValue ?? size }
+        set { objc_setAssociatedObject(self, &craftImageIntrinsicKey, NSValue(cgSize: newValue), .OBJC_ASSOCIATION_RETAIN_NONATOMIC) }
+    }
+}
+
+/// Explicit CSS-facing image geometry; the loader and semantic view stay retained.
+class CraftNativePositionedImageView: UIImageView {
+    private var storedImage: UIImage?
+    private var fittedImage: UIImageView?
+    private var fit: String?
+    private var position = CGPoint(x: 0.5, y: 0.5)
+
+    override var image: UIImage? {
+        get { storedImage }
+        set {
+            storedImage = newValue
+            super.image = fit == nil ? newValue : nil
+            fittedImage?.image = newValue
+            invalidateIntrinsicContentSize()
+            setNeedsLayout()
+        }
+    }
+
+    override var intrinsicContentSize: CGSize {
+        fit == nil ? super.intrinsicContentSize : storedImage?.craftIntrinsicSize ?? CGSize(width: UIView.noIntrinsicMetric, height: UIView.noIntrinsicMetric)
+    }
+
+    func configureObjectGeometry(props: [String: Any], style: [String: Any]) {
+        func value(_ name: String) -> Any? {
+            if let raw = props[name], !(raw is NSNull) { return raw }
+            if let raw = style[name], !(raw is NSNull) { return raw }
+            return nil
+        }
+        let rawFit = value("objectFit"), rawPosition = value("objectPosition")
+        if rawFit != nil || rawPosition != nil {
+            let requested = rawFit as? String ?? "fill"
+            fit = ["fill", "contain", "cover", "none", "scale-down"].contains(requested) ? requested : "fill"
+            position = Self.objectPosition(rawPosition)
+            if fittedImage == nil {
+                let child = UIImageView()
+                child.isUserInteractionEnabled = false
+                child.isAccessibilityElement = false
+                child.contentMode = .scaleToFill
+                insertSubview(child, at: 0)
+                fittedImage = child
+            }
+        } else { fit = nil }
+        fittedImage?.isHidden = fit == nil
+        super.image = fit == nil ? storedImage : nil
+        fittedImage?.image = storedImage
+        invalidateIntrinsicContentSize()
+        setNeedsLayout()
+    }
+
+    var usesObjectGeometry: Bool { fit != nil }
+    var objectCovers: Bool { fit == "cover" }
+
+    private static func objectPosition(_ raw: Any?) -> CGPoint {
+        guard let text = raw as? String else { return CGPoint(x: 0.5, y: 0.5) }
+        var parts = text.lowercased().split(whereSeparator: { $0.isWhitespace }).map(String.init)
+        guard (1...2).contains(parts.count) else { return CGPoint(x: 0.5, y: 0.5) }
+        if parts.count == 1 {
+            parts = ["top", "bottom"].contains(parts[0]) ? ["center", parts[0]] : [parts[0], "center"]
+        } else if ["top", "bottom"].contains(parts[0]) || ["left", "right"].contains(parts[1]) { parts.swapAt(0, 1) }
+        func fraction(_ part: String, low: String, high: String) -> CGFloat? {
+            if part == low { return 0 }; if part == high { return 1 }; if part == "center" { return 0.5 }
+            guard part.hasSuffix("%"), let number = Double(part.dropLast()), number.isFinite else { return nil }
+            return CGFloat(number / 100)
+        }
+        guard let x = fraction(parts[0], low: "left", high: "right"), let y = fraction(parts[1], low: "top", high: "bottom") else { return CGPoint(x: 0.5, y: 0.5) }
+        return CGPoint(x: x, y: y)
+    }
+
+    override func layoutSubviews() {
+        super.layoutSubviews()
+        guard let fit, let child = fittedImage else { return }
+        let source = storedImage?.craftIntrinsicSize ?? .zero
+        guard source.width > 0, source.height > 0 else { child.frame = .zero; return }
+        let contain = min(bounds.width / source.width, bounds.height / source.height)
+        let scale: CGFloat = fit == "cover" ? max(bounds.width / source.width, bounds.height / source.height)
+            : fit == "none" ? 1 : fit == "scale-down" ? min(1, contain) : contain
+        let size = fit == "fill" ? bounds.size : CGSize(width: source.width * scale, height: source.height * scale)
+        child.frame = CGRect(x: bounds.minX + (bounds.width - size.width) * position.x,
+            y: bounds.minY + (bounds.height - size.height) * position.y, width: size.width, height: size.height)
+        child.tintColor = tintColor
+    }
+}
+
 /// An image-backed flex container. The image stays behind ordinary native
 /// children so `ImageBackground` keeps the same layout and interaction
 /// semantics as a `View` while using the shared image loader.
-private final class CraftNativeImageBackgroundView: UIImageView {
+private final class CraftNativeImageBackgroundView: CraftNativePositionedImageView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     let contentStack = CraftNativeFlowView()
 
     override init(frame: CGRect) {
@@ -4142,6 +4293,10 @@ private final class CraftNativeSegmentElement: UIAccessibilityElement {
 }
 
 private final class CraftNativeSegmentedControl: UISegmentedControl {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     var values: [String] = []
     private var segments: [CraftNativeSegmentElement] = []
     override var accessibilityElements: [Any]? {
@@ -4391,28 +4546,30 @@ private final class CraftNativeModalView: UIView, UIGestureRecognizerDelegate, U
     }
 
     override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
-        guard !isHidden, alpha > 0.01, isUserInteractionEnabled else { return nil }
-        let contentPoint = contentStack.convert(point, from: self)
-        if contentStack.bounds.contains(contentPoint), let hit = contentStack.hitTest(contentPoint, with: event), hit !== contentStack {
-            // Flow/layout views occupy the modal's entire content rect, but a
-            // blank part of one must still be a scrim tap. Preserve touches
-            // only when the hit view (or one of its ancestors) actually owns
-            // a control or gesture recognizer.
-            var candidate: UIView? = hit
-            while let view = candidate, view !== contentStack {
-                if view is UIControl || !(view.gestureRecognizers?.isEmpty ?? true) { return hit }
-                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)
+        return craftPointerHitTest(point, with: event) {
+            guard !isHidden, alpha > 0.01, isUserInteractionEnabled else { return nil }
+            let contentPoint = contentStack.convert(point, from: self)
+            if contentStack.bounds.contains(contentPoint), let hit = contentStack.hitTest(contentPoint, with: event), hit !== contentStack {
+                // Flow/layout views occupy the modal's entire content rect, but a
+                // blank part of one must still be a scrim tap. Preserve touches
+                // only when the hit view (or one of its ancestors) actually owns
+                // a control or gesture recognizer.
+                var candidate: UIView? = hit
+                while let view = candidate, view !== contentStack {
+                    if view is UIControl || !(view.gestureRecognizers?.isEmpty ?? true) { return hit }
+                    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)
+        }
     }
 
     override func layoutSubviews() {
@@ -4513,6 +4670,10 @@ func craftHandleKeyboardTap(in container: UIView, hit: UIView?, persistTaps: Str
 }
 
 private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDelegate {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     let contentStack = CraftNativeFlowView()
     private let keyboardTapGesture = UITapGestureRecognizer()
     private var keyboardShouldPersistTaps = "never"
@@ -4877,6 +5038,10 @@ private final class CraftNativeScrollView: UIScrollView, UIGestureRecognizerDele
 /// inherited down the tree as SVG does; `dark:` classes arrive already
 /// resolved for the appearance, so a redraw is all a theme change needs.
 final class CraftNativeSvgView: UIView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     var drawing: [String: Any] = [:] {
         didSet {
             animates = Self.hasAnimation(drawing["children"] as? [Any] ?? [])
@@ -5282,6 +5447,10 @@ private final class CraftNativeGradientLayer: CAGradientLayer {
 /// pill with its label touching the edges. The padding is added to its size
 /// and the label laid out inside it, at the alignment the style asked for.
 private final class CraftNativeButton: UIButton {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     var padding: UIEdgeInsets = .zero {
         didSet {
             guard padding != oldValue else { return }
@@ -5323,6 +5492,10 @@ private final class CraftNativeButton: UIButton {
 /// Opt-in solid switch. Draws only public UIControl content; it neither walks
 /// UISwitch's private views nor changes UIKit animations elsewhere in the app.
 final class CraftNativeSolidSwitch: UIControl {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     private(set) var isOn = false
     var onColor: UIColor? { didSet { setNeedsDisplay() } }
     var offColor: UIColor? { didSet { setNeedsDisplay() } }
@@ -5433,10 +5606,18 @@ final class CraftNativeSolidSwitch: UIControl {
 /// square/checkmark symbols while keeping the control's title and accessibility
 /// state native and keyboard/touch reachable.
 private final class CraftNativeCheckboxButton: UIButton {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     var indeterminate = false
 }
 
 private final class CraftNativeLabel: UILabel {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     var insets = UIEdgeInsets.zero {
         didSet {
             guard insets != oldValue else { return }
@@ -5470,6 +5651,10 @@ private final class CraftNativeLabel: UILabel {
 /// selection. UILabel has no selection model; UITextView supplies UIKit's
 /// standard loupe, menu and copy behavior while remaining a plain text leaf.
 private final class CraftNativeSelectableTextView: UITextView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     convenience init() {
         self.init(frame: .zero, textContainer: nil)
     }
@@ -5498,6 +5683,10 @@ private final class CraftNativeSelectableTextView: UITextView {
 /// A one-line TextInput. Its style's padding is where the text and the
 /// placeholder start, as in a web input; UITextField has no padding of its own.
 final class CraftNativeTextField: UITextField {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     var padding = UIEdgeInsets.zero {
         didSet {
             guard padding != oldValue else { return }
@@ -5529,6 +5718,10 @@ private final class CraftNativeFlexSpacer: UIView {}
 /// An SF Symbol leaf. Its natural size is the symbol's, or a 20 pt square
 /// when the style gives it no size at all.
 private final class CraftNativeIconView: UIImageView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     var defaultBox: CGFloat? { didSet { if defaultBox != oldValue { invalidateIntrinsicContentSize() } } }
 
     /// An icon says only what the screen labels it. iOS gives a symbol image
@@ -5554,6 +5747,10 @@ private final class CraftNativeIconView: UIImageView {
 }
 
 private final class CraftNativeTextView: UITextView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
     private let placeholderLabel = UILabel()
     private var nativeTextContainerInset: UIEdgeInsets?
     private var nativeLineFragmentPadding: CGFloat?
@@ -5869,6 +6066,41 @@ enum CraftNativeBundle {
     }
 }
 
+private final class CraftNativePickerView: UIPickerView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
+}
+
+private final class CraftNativeDatePickerView: UIDatePicker {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
+}
+
+private final class CraftNativeSwitch: UISwitch {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
+}
+
+private final class CraftNativeSlider: UISlider {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
+}
+
+private final class CraftNativeImageView: CraftNativePositionedImageView {
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        craftPointerHitTest(point, with: event) { super.hitTest(point, with: event) }
+    }
+
+}
+
 private final class CraftNativeScreenRootView: UIView {
     weak var controller: CraftNativeScreenController?
 
@@ -5879,7 +6111,8 @@ private final class CraftNativeScreenRootView: UIView {
         // 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 {
+                where !modal.blocksBackground && !modal.isHidden && modal.alpha > 0.01
+                    && modal.craftPointerEvents != CraftNativePointerEvents.none && modal.craftPointerEvents != .boxNone {
                 let local = modal.convert(point, from: self)
                 if !modal.bounds.contains(local) && (modal.dismissOnOutsideTap || controller.hasBlockingModalBelow(modal)) { return modal }
             }
@@ -6371,7 +6604,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         appliedTraitDefaults = traits
         view.backgroundColor = screenBackgroundColor ?? config.resolvedBackgroundColor
         applyNavigationBarAppearance()
-        if let document = mutationDocument.node("root") {
+        if let document = mutationDocument.document {
             renderCommitted(document)
         } else {
             rootStack.setNeedsLayout()
@@ -6469,6 +6702,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         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
+                && other.craftPointerEvents != CraftNativePointerEvents.none && other.craftPointerEvents != .boxNone
         }
     }
 
@@ -7674,6 +7908,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             #if compiler(>=6.2)
             if #available(iOS 26.0, *) {
                 trackedScrollView?.topEdgeEffect.isHidden = false
+                trackedScrollView?.topEdgeEffect.style = .automatic
                 trackedScrollView?.bottomEdgeEffect.isHidden = false
             }
             #endif
@@ -7684,10 +7919,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         }
         #if compiler(>=6.2)
         if #available(iOS 26.0, *) {
-            // Floating button groups carry their own material. UIKit's
-            // separate scroll-edge wash would cover the content behind
-            // and beyond them even with a transparent bar appearance.
-            scroll?.topEdgeEffect.isHidden = topEdgeToEdge && !navigationBarSolid
+            // The clock and navigation title need separation from live
+            // content. Keep UIKit's soft top scrim rather than removing
+            // it or adding an opaque bar. The floating tab pill already
+            // carries its own material, so its full-width wash stays off.
+            scroll?.topEdgeEffect.isHidden = false
+            scroll?.topEdgeEffect.style = topEdgeToEdge && !navigationBarSolid ? .soft : .automatic
             scroll?.bottomEdgeEffect.isHidden = tabbedScroll
         }
         #endif
@@ -8332,7 +8569,11 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     // Internal so simulator-hosted XCTest can assert actual UIView identity.
     func render(_ document: [String: Any]) {
         mutationDocument.replace(with: document)
-        renderCommitted(document)
+        // Import assigns protocol IDs to legacy descendants. Draw that same
+        // committed tree from the first frame, so later patches cannot turn
+        // selector/positional identities into different native controls.
+        guard let committed = mutationDocument.document else { return }
+        renderCommitted(committed)
         if !hybridRendered {
             hybridRendered = true
             // The app script's drawing is never on screen: not a first frame.
@@ -8973,6 +9214,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if let current = image.image { image.image = imageForDisplay(current, view: image) }
             let requestedResizeMode = style["resizeMode"] as? String ?? props["resizeMode"] as? String
             image.contentMode = imageContentMode(requestedResizeMode)
+            (image as? CraftNativePositionedImageView)?.configureObjectGeometry(props: props, style: style)
             applyImageClipping(image, contentMode: image.contentMode, style: style)
             updateAuxiliaryHandler(events["onLoadStart"], in: &imageLoadStartHandlers, for: image)
             updateAuxiliaryHandler(events["onLoad"], in: &imageLoadHandlers, for: image)
@@ -8992,6 +9234,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             if let current = background.image { background.image = imageForDisplay(current, view: background) }
             let requestedResizeMode = style["resizeMode"] as? String ?? props["resizeMode"] as? String
             background.contentMode = imageContentMode(requestedResizeMode)
+            background.configureObjectGeometry(props: props, style: style)
             applyImageClipping(background, contentMode: background.contentMode, style: style)
             updateAuxiliaryHandler(events["onLoadStart"], in: &imageLoadStartHandlers, for: background)
             updateAuxiliaryHandler(events["onLoad"], in: &imageLoadHandlers, for: background)
@@ -9133,6 +9376,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             )
             if disabled { result.isUserInteractionEnabled = false }
         }
+        result.craftPointerEvents = CraftNativePointerEvents.resolve(props: props, style: style)
         applyAccessibility(props, type: type, to: result)
         (result as? CraftNativeFlowView)?.configureCelebration(props["celebration"])
         return current
@@ -9179,12 +9423,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             control.addTarget(self, action: #selector(segmentChanged(_:)), for: .valueChanged)
             return control
         case "Picker":
-            let picker = UIPickerView()
+            let picker = CraftNativePickerView()
             picker.dataSource = self
             picker.delegate = self
             return picker
         case "DatePicker":
-            let picker = UIDatePicker()
+            let picker = CraftNativeDatePickerView()
             picker.preferredDatePickerStyle = .compact
             picker.addTarget(self, action: #selector(datePicked(_:)), for: .valueChanged)
             return picker
@@ -9196,11 +9440,11 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 toggle.addTarget(self, action: #selector(solidSwitchChanged(_:)), for: .valueChanged)
                 return toggle
             }
-            let toggle = UISwitch()
+            let toggle = CraftNativeSwitch()
             toggle.addTarget(self, action: #selector(switchChanged(_:)), for: .valueChanged)
             return toggle
         case "Slider":
-            let slider = UISlider()
+            let slider = CraftNativeSlider()
             slider.addTarget(self, action: #selector(sliderChanged(_:)), for: .valueChanged)
             slider.addTarget(self, action: #selector(sliderFinished(_:)), for: [.touchUpInside, .touchUpOutside, .touchCancel])
             return slider
@@ -9209,7 +9453,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         case "StatusBar", "RefreshControl":
             return CraftNativeFlowView()
         case "Image":
-            return UIImageView()
+            return CraftNativeImageView()
         case "ImageBackground":
             return CraftNativeImageBackgroundView(frame: .zero)
         case "KeyboardAvoidingView":
@@ -10462,7 +10706,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 if let image = CGImageSourceCreateThumbnailAtIndex(source, 0, options) {
                     // At the screen's scale, so its size in points is the
                     // size it is drawn at.
-                    return UIImage(cgImage: image, scale: target.scale, orientation: .up)
+                    let decoded = UIImage(cgImage: image, scale: target.scale, orientation: .up)
+                    decoded.craftIntrinsicSize = CGSize(width: width, height: height)
+                    return decoded
                 }
             }
         }
@@ -10499,7 +10745,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         let authored = (style["overflow"] as? String) == "hidden"
             || (view.craftRequestedCornerRadius ?? 0) > 0
             || view.craftRequestedCornerRadii != nil
-        let clips = authored || contentMode == .scaleAspectFill
+        let clips = authored || contentMode == .scaleAspectFill || (view as? CraftNativePositionedImageView)?.usesObjectGeometry == true
         view.clipsToBounds = clips
         view.layer.masksToBounds = clips
     }
@@ -10546,7 +10792,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         if let url = imageURL(for: uri) {
             // Decoded at the size it is drawn, when the style fixes that size.
             let pixels = Self.displayPixels(of: view)
-            let fill = view.contentMode == .scaleAspectFill
+            let fill = (view as? CraftNativePositionedImageView)?.objectCovers == true || view.contentMode == .scaleAspectFill
             // media.keep owns private/offline copies keyed by the authored URL.
             // Read before the decoded/network cache, without retaining private
             // pixels there after the app clears its media on sign-out.
@@ -10654,7 +10900,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     private func imageForDisplay(_ image: UIImage, view: UIImageView) -> UIImage {
-        image.withRenderingMode(tintedImages.contains(ObjectIdentifier(view)) ? .alwaysTemplate : .alwaysOriginal)
+        let displayed = image.withRenderingMode(tintedImages.contains(ObjectIdentifier(view)) ? .alwaysTemplate : .alwaysOriginal)
+        displayed.craftIntrinsicSize = image.craftIntrinsicSize
+        return displayed
     }
 
     private func emitImageEvent(