@craft-native/ios 0.0.247 → 0.0.249

package/templates/CraftHybrid.swift

@@ -264,8 +264,8 @@ protocol CraftHybridScreenEvents: AnyObject {
     func nativeScreenDidRender(_ screen: CraftNativeScreenController)
     /// The screen could not draw its first frame: no bundle, or its script threw.
     func nativeScreen(_ screen: CraftNativeScreenController, didFail message: String)
-    /// `craft.navigation.open(path)`.
-    func nativeScreen(_ screen: CraftNativeScreenController, open path: String)
+    /// `craft.navigation.open(path, props)`.
+    func nativeScreen(_ screen: CraftNativeScreenController, open path: String, props: [String: Any])
     /// `craft.navigation.replace(path)`: finish the current flow atomically.
     func nativeScreen(_ screen: CraftNativeScreenController, replace path: String)
 }
@@ -446,11 +446,11 @@ final class CraftHybrid: NSObject {
     /// A path or a web address opened by the app script or a single-stack
     /// screen: the shell opens it (holding it until the shell exists); an app
     /// with no shell opens a web address in the in-app browser.
-    func open(_ path: String) {
+    func open(_ path: String, props: [String: Any] = [:]) {
         if let controller {
-            controller.open(path)
+            controller.open(path, props: props)
         } else if isEnabled {
-            untilShell.append { $0.open(path) }
+            untilShell.append { $0.open(path, props: props) }
         } else {
             openOutside(path)
         }
@@ -976,8 +976,8 @@ extension CraftHybrid: CraftHybridScreenEvents {
         DispatchQueue.main.async { self.startAppScript() }
     }
 
-    func nativeScreen(_ screen: CraftNativeScreenController, open path: String) {
-        open(path)
+    func nativeScreen(_ screen: CraftNativeScreenController, open path: String, props: [String: Any]) {
+        open(path, props: props)
     }
 
     func nativeScreen(_ screen: CraftNativeScreenController, replace path: String) {
@@ -1249,8 +1249,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             // create a second web root here: the shared WebView cannot draw
             // both pages during the same gesture.
             guard hybrid.routes.match(id) != nil else { return false }
-            target = CraftFramePacing.shared.measure("tab swipe mount \(id)") { makeStack(tab: id, rootPath: id) }
-            (target.topViewController as? CraftNativeScreenController)?.screenVisibilityChanged(false)
+            target = CraftFramePacing.shared.measure("tab swipe mount \(id)") { makeStack(tab: id, rootPath: id, hidden: true) }
         }
         guard current.view !== target.view,
               !(current.topViewController is CraftHybridWebSlot && target.topViewController is CraftHybridWebSlot),
@@ -1546,6 +1545,12 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
 
     private var visibleStack: UINavigationController? { stacks[currentTab] }
 
+    /// A swipe preview can be visible without owning navigation or focus.
+    /// UIKit appearance callbacks must follow the committed native stack.
+    func isFocusedScreen(_ screen: CraftNativeScreenController) -> Bool {
+        visibleStack?.topViewController === screen
+    }
+
     var webIsVisible: Bool {
         guard let webHost, let slot = visibleStack?.topViewController as? CraftHybridWebSlot else { return false }
         return webHost.view.superview === slot.view
@@ -1557,7 +1562,11 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     /// the view hierarchy, so its screen never takes the shell's chrome (the
     /// bar, the tab accessory) from the one on screen.
     private func makeStack(tab: String, rootPath: String, hidden: Bool = false) -> UINavigationController {
-        let nav = UINavigationController(rootViewController: entry(for: rootPath, isTabRoot: true, depth: nil))
+        let root = entry(for: rootPath, isTabRoot: true, depth: nil)
+        // Constructing the navigation controller can load the root's view and
+        // mount its script immediately. Set its initial focus before that.
+        if hidden { (root as? CraftNativeScreenController)?.screenVisibilityChanged(false) }
+        let nav = UINavigationController(rootViewController: root)
         nav.delegate = self
         nav.view.backgroundColor = config.resolvedBackgroundColor
         nav.additionalSafeAreaInsets.bottom = safeAreaForTabBar()
@@ -1585,11 +1594,10 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     }
 
     /// The entry for a path: its native screen, or a web entry.
-    private func entry(for path: String, isTabRoot: Bool, depth: Int?, params extra: [String: Any] = [:]) -> UIViewController {
+    private func entry(for path: String, isTabRoot: Bool, depth: Int?, props: [String: Any] = [:]) -> UIViewController {
         if hybrid.isEnabled, let match = hybrid.routes.match(path) {
-            var params = self.params(for: path, match)
-            extra.forEach { params[$0.key] = $0.value }
-            let screen = CraftNativeScreenController(config: config, routeName: match.screen, routeParams: params)
+            let params = self.params(for: path, match)
+            let screen = CraftNativeScreenController(config: config, routeName: match.screen, routeParams: params, routeProps: props)
             screen.hybridEvents = self
             nativePaths[ObjectIdentifier(screen)] = match.path
             return screen
@@ -1734,7 +1742,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
     /// an app with no web view, a path no screen draws opens in the in-app
     /// browser on the app's site. A web address on the app's site is its
     /// path; one anywhere else opens in the in-app browser.
-    func open(_ raw: String) {
+    func open(_ raw: String, props: [String: Any] = [:]) {
         if let url = URL(string: raw), let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" {
             guard CraftHybridRoutes.isSite(url, site: hybrid.siteURL) else {
                 hybrid.openOutside(raw)
@@ -1749,7 +1757,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             return
         }
         if hybrid.routes.match(raw) != nil {
-            showNative(path: raw, replace: false)
+            showNative(path: raw, replace: false, props: props)
             return
         }
         if hybrid.hasWeb {
@@ -1769,7 +1777,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
 
     /// The native screen for `raw`: the one already in the stack (popping to
     /// it), a tab's root, or a new one pushed.
-    func showNative(path raw: String, replace: Bool, fromLink: Bool = false) {
+    func showNative(path raw: String, replace: Bool, fromLink: Bool = false, props: [String: Any] = [:]) {
         guard let match = hybrid.routes.match(raw) else { return }
         interruptTabSwipe(restoringSelection: true)
         let tabs = hybrid.tabIds
@@ -1785,7 +1793,7 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
                 nav.popToRootViewController(animated: !fromLink)
             }
             // `/m/store?coach=5`: the tab's own screen, with the query.
-            (stacks[tab]?.viewControllers.first as? CraftNativeScreenController)?.receiveRouteParams(params(for: raw, match))
+            (stacks[tab]?.viewControllers.first as? CraftNativeScreenController)?.receiveRouteParams(params(for: raw, match), props: props)
             return
         }
         if fromLink, let owner = CraftHybridRoutes.tab(owning: match.path, among: tabs), owner != currentTab {
@@ -1796,10 +1804,10 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
             if existing !== nav.topViewController { nav.popToViewController(existing, animated: true) }
             // Opened again, perhaps with another query (`?person=8`): the
             // screen hears the params it was opened with this time.
-            (existing as? CraftNativeScreenController)?.receiveRouteParams(params(for: raw, match))
+            (existing as? CraftNativeScreenController)?.receiveRouteParams(params(for: raw, match), props: props)
             return
         }
-        let screen = entry(for: raw, isTabRoot: false, depth: nil)
+        let screen = entry(for: raw, isTabRoot: false, depth: nil, props: props)
         let show = { [weak nav] in
             guard let nav else { return }
             if replace, !nav.viewControllers.isEmpty {
@@ -2175,8 +2183,8 @@ final class CraftHybridController: UIViewController, UINavigationControllerDeleg
         }
     }
 
-    func nativeScreen(_ screen: CraftNativeScreenController, open path: String) {
-        open(path)
+    func nativeScreen(_ screen: CraftNativeScreenController, open path: String, props: [String: Any]) {
+        open(path, props: props)
     }
 
     func nativeScreen(_ screen: CraftNativeScreenController, replace path: String) {

package/templates/CraftLiveActivities.swift

@@ -70,7 +70,7 @@ enum CraftLiveActivities {
 
     private static func finite(_ body: [String: Any], _ key: String, _ fallback: Double? = nil) -> Double? {
         guard body.keys.contains(key) else { return fallback }
-        guard let number = body[key] as? NSNumber, number.doubleValue.isFinite else { return nil }
+        guard let number = craftNativeNumber(body[key]), number.doubleValue.isFinite else { return nil }
         return max(0, number.doubleValue)
     }
 

package/templates/CraftNativeActions.swift

@@ -1,6 +1,7 @@
 import Foundation
 import AuthenticationServices
 import LocalAuthentication
+import PassKit
 import SQLite3
 import Security
 import UIKit
@@ -41,9 +42,10 @@ enum CraftNativeActions {
     static func capabilities(config: CraftConfig) -> [String] {
         // `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"]
+        var values = ["device", "clipboard", "haptics", "storage", "lifecycle", "fetch", "dialog", "speech", "audio", "eventStream", "linking", "badge", "animation", "viewFocus", "viewMeasure", "viewReparent"]
         values.append("storageCompareAndSet")
         values.append("storageSetIfAbsent")
+        values.append("viewScroll")
         values.append("crypto")
         if config.enableBiometric { values.append("biometric") }
         if config.enableSecureStorage { values.append("secureStorage") }
@@ -51,6 +53,7 @@ enum CraftNativeActions {
         if config.enableDeepLinks { values.append("deepLinks") }
         if config.enableLocalNotifications { values.append("notifications") }
         if config.enableHealthKit { values.append("health") }
+        if config.enableWallet { values.append("wallet") }
         if config.enableLiveActivities { values.append("liveActivities") }
         // The in-app browser and the system's web sign-in sheet (CraftBrowser).
         values.append("browser")
@@ -375,6 +378,44 @@ enum CraftNativeActions {
                 complete(requestToken, result.mapError { CraftNativeActionError(code: $0.code, message: $0.message) }, completion)
             }
             return
+        case ("Wallet", "isAvailable"):
+            sync = config.enableWallet ? .success(PKPassLibrary.isPassLibraryAvailable()) : failure("CAPABILITY_DISABLED", "Wallet is disabled")
+        case ("Wallet", "has"):
+            guard config.enableWallet else {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Wallet is disabled"), completion)
+                return
+            }
+            guard let serialNumber = args.first as? String, !serialNumber.isEmpty else {
+                complete(requestToken, failure("INVALID_ARGUMENT", "Wallet.has needs a serial number"), completion)
+                return
+            }
+            sync = .success(PKPassLibrary().passes().contains { $0.serialNumber == serialNumber })
+        case ("Wallet", "add"):
+            guard config.enableWallet else {
+                complete(requestToken, failure("CAPABILITY_DISABLED", "Wallet is disabled"), completion)
+                return
+            }
+            let options = args.first as? [String: Any] ?? [:]
+            if let encoded = options["data"] as? String {
+                guard let data = Data(base64Encoded: encoded), let pass = try? PKPass(data: data) else {
+                    complete(requestToken, failure("INVALID_ARGUMENT", "Wallet.add needs a valid base64 pkpass"), completion)
+                    return
+                }
+                presentWalletPass(pass, requestToken: requestToken, completion: completion)
+                return
+            }
+            guard let address = options["url"] as? String, let url = URL(string: address), url.scheme == "https" else {
+                complete(requestToken, failure("INVALID_ARGUMENT", "Wallet.add needs base64 data or an https URL"), completion)
+                return
+            }
+            URLSession.shared.dataTask(with: url) { data, _, error in
+                guard let data, error == nil, let pass = try? PKPass(data: data) else {
+                    complete(requestToken, failure("WALLET_PASS_INVALID", "The Wallet pass could not be downloaded or parsed"), completion)
+                    return
+                }
+                DispatchQueue.main.async { self.presentWalletPass(pass, requestToken: requestToken, completion: completion) }
+            }.resume()
+            return
         case ("KeepAwake", "set"):
             guard config.enableKeepAwake else {
                 complete(requestToken, failure("CAPABILITY_DISABLED", "Keep awake is disabled"), completion)
@@ -392,7 +433,7 @@ enum CraftNativeActions {
         case ("Brightness", "set"):
             // The device's backlight, system-wide: a screen that dims it reads
             // it first and puts it back, as @stacksjs/mobile's brightness does.
-            guard let level = (args.first as? NSNumber)?.doubleValue, level.isFinite else {
+            guard let level = craftNativeNumber(args.first)?.doubleValue, level.isFinite else {
                 complete(requestToken, failure("INVALID_ARGUMENT", "Brightness.set needs a level from 0 to 1"), completion)
                 return
             }
@@ -517,9 +558,9 @@ enum CraftNativeActions {
                 CraftNativeSpeech.shared.speak(
                     text,
                     language: options["language"] as? String,
-                    rate: (options["rate"] as? NSNumber)?.doubleValue,
-                    pitch: (options["pitch"] as? NSNumber)?.doubleValue,
-                    preDelay: (options["preDelay"] as? NSNumber)?.doubleValue,
+                    rate: craftNativeNumber(options["rate"]).map { $0.doubleValue }.flatMap { $0.isFinite ? $0 : nil },
+                    pitch: craftNativeNumber(options["pitch"]).map { $0.doubleValue }.flatMap { $0.isFinite ? $0 : nil },
+                    preDelay: craftNativeNumber(options["preDelay"]).map { $0.doubleValue }.flatMap { $0.isFinite ? $0 : nil },
                     interrupt: options["interrupt"] as? Bool ?? true
                 ) { spoken in complete(requestToken, .success(spoken), completion) }
             }
@@ -570,7 +611,7 @@ enum CraftNativeActions {
             }
             return
         case ("Badge", "set"):
-            guard let value = args.first as? NSNumber,
+            guard let value = craftNativeNumber(args.first),
                   value.doubleValue.isFinite,
                   value.doubleValue >= 0,
                   value.doubleValue.rounded() == value.doubleValue else {
@@ -595,6 +636,27 @@ enum CraftNativeActions {
         complete(requestToken, sync ?? failure("UNKNOWN_ACTION", "Unsupported native API"), completion)
     }
 
+    private static var walletPresenters: [String: CraftWalletPresenter] = [:]
+
+    private static func presentWalletPass(
+        _ pass: PKPass,
+        requestToken: String,
+        completion: @escaping (Result<Any, CraftNativeActionError>) -> Void
+    ) {
+        DispatchQueue.main.async {
+            let presenter = CraftWalletPresenter { result in
+                walletPresenters.removeValue(forKey: requestToken)
+                completion(result)
+            }
+            guard let controller = PKAddPassesViewController(pass: pass), CraftPresenter.present(controller, from: nil) else {
+                completion(failure("PRESENTATION_FAILED", "Wallet could not present its add-pass sheet"))
+                return
+            }
+            controller.delegate = presenter
+            walletPresenters[requestToken] = presenter
+        }
+    }
+
     static func cancel(requestToken: String) {
         cancellationLock.lock()
         cancelledRequests.insert(requestToken)
@@ -1117,9 +1179,14 @@ enum CraftNativeActions {
                 content.body = value["body"] as? String ?? ""
                 content.sound = .default
                 if let data = value["data"] as? [String: Any] { content.userInfo = data }
-                if let badge = value["badge"] as? NSNumber { content.badge = badge }
+                if let badge = craftNativeNumber(value["badge"]),
+                   badge.doubleValue.isFinite,
+                   badge.doubleValue >= 0,
+                   badge.doubleValue.rounded() == badge.doubleValue {
+                    content.badge = badge
+                }
                 let id = (value["id"] as? String).flatMap { validKey($0) } ?? UUID().uuidString
-                let delay = (value["delay"] as? NSNumber)?.doubleValue
+                let delay = craftNativeNumber(value["delay"]).map { $0.doubleValue }.flatMap { $0.isFinite ? $0 : nil }
                 let trigger = delay.map { UNTimeIntervalNotificationTrigger(timeInterval: max($0 / 1_000, 1), repeats: false) }
                 center.add(UNNotificationRequest(identifier: id, content: content, trigger: trigger)) { addError in
                     if let addError = addError {
@@ -1236,6 +1303,18 @@ enum CraftNativeActions {
     }
 }
 
+private final class CraftWalletPresenter: NSObject, PKAddPassesViewControllerDelegate {
+    private let completion: (Result<Any, CraftNativeActionError>) -> Void
+
+    init(completion: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
+        self.completion = completion
+    }
+
+    func addPassesViewControllerDidFinish(_ controller: PKAddPassesViewController) {
+        controller.dismiss(animated: true) { [completion] in completion(.success(true)) }
+    }
+}
+
 /// The native WebAuthn half for screens without a browser context. The
 /// server still owns challenges and verifies the returned client data; this
 /// class only translates WebAuthn options into Apple's passkey sheet and

package/templates/CraftNativeFiles.swift

@@ -108,8 +108,15 @@ enum CraftNativeFiles {
     /// (no location) left in it. Answers the file, or null when the person
     /// closed the picker. Main thread.
     static func pickImage(_ options: [String: Any], cameraEnabled: Bool, done: @escaping (Result<Any, CraftNativeActionError>) -> Void) {
-        let maxPixels = min(largestMaxPixels, max(64, (options["maxPixels"] as? NSNumber)?.intValue ?? defaultMaxPixels))
-        let quality = min(1, max(0.1, (options["quality"] as? NSNumber)?.doubleValue ?? defaultQuality))
+        let maxPixels = craftNativeNumber(options["maxPixels"])
+            .map { $0.doubleValue }
+            .flatMap { value in
+                guard value.isFinite else { return nil }
+                return Int(max(64, min(Double(largestMaxPixels), value)))
+            } ?? defaultMaxPixels
+        let quality = min(1, max(0.1, craftNativeNumber(options["quality"])
+            .map { $0.doubleValue }
+            .flatMap { $0.isFinite ? $0 : nil } ?? defaultQuality))
         let source = options["source"] as? String ?? "library"
         guard activePicker == nil else {
             done(.failure(CraftNativeActionError(code: "BUSY", message: "A picker is already open")))
@@ -284,7 +291,12 @@ enum CraftNativeFiles {
             done(.failure(CraftNativeActionError(code: "BUSY", message: "A picker is already open")))
             return
         }
-        let limit = min(512 * 1024 * 1024, max(1, (options["maxBytes"] as? NSNumber)?.intValue ?? 512 * 1024 * 1024))
+        let limit = craftNativeNumber(options["maxBytes"])
+            .map { $0.doubleValue }
+            .flatMap { value in
+                guard value.isFinite else { return nil }
+                return Int(max(1, min(Double(512 * 1024 * 1024), value)))
+            } ?? 512 * 1024 * 1024
         let finish: (Result<Any, CraftNativeActionError>) -> Void = { result in
             DispatchQueue.main.async { activePicker = nil; done(result) }
         }

package/templates/CraftNativeFlatList.swift

@@ -145,6 +145,7 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
     private var itemsByIdentity: [String: Item] = [:]
     private var renderItem: RenderItem?
     private var recycleItem: ((String) -> Void)?
+    private var removeItem: ((String) -> Void)?
     private var endReached: (() -> Void)?
     var onScrollEvent: ((UIScrollView) -> Void)?
     /// Called as the visible rows move, for a screen that lays out around them.
@@ -408,6 +409,7 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
         endReachedThreshold: Double,
         renderItem: @escaping RenderItem,
         recycleItem: @escaping (String) -> Void,
+        removeItem: @escaping (String) -> Void,
         endReached: (() -> Void)?
     ) {
         if isApplyingSnapshot {
@@ -420,6 +422,7 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
                     endReachedThreshold: endReachedThreshold,
                     renderItem: renderItem,
                     recycleItem: recycleItem,
+                    removeItem: removeItem,
                     endReached: endReached
                 )
             }
@@ -429,6 +432,7 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
 
         self.renderItem = renderItem
         self.recycleItem = recycleItem
+        self.removeItem = removeItem
         self.endReached = endReached
         self.endReachedThreshold = max(0, endReachedThreshold)
         self.columns = max(1, columns)
@@ -459,7 +463,7 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
         flowLayout.invalidateLayout()
 
         let nextIds = Set(itemsByIdentity.keys)
-        for identity in oldItems.keys where !nextIds.contains(identity) { recycleItem(identity) }
+        for identity in oldItems.keys where !nextIds.contains(identity) { removeItem(identity) }
         let changed = next.compactMap { item -> String? in
             guard let old = oldItems[item.identity], old.signature != item.signature else { return nil }
             return item.identity
@@ -508,6 +512,7 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
         itemsByIdentity = [:]
         renderItem = nil
         recycleItem = nil
+        removeItem = nil
         endReached = nil
         dataContentSignature = ""
         onScrollEvent = nil
@@ -521,6 +526,18 @@ final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowL
         pendingScrollTarget = nil
     }
 
+    /// Releases callbacks and UIKit ownership that belong to a permanently
+    /// removed list node. Recycled rows intentionally use `discardAll()` only:
+    /// the same list can be rebound during the next reconciliation.
+    func resetForTeardown() {
+        setRefreshHandler(nil, refreshing: false)
+        discardAll()
+        onFittingHeightChanged = nil
+        delegate = nil
+        nativeRefreshControl.removeTarget(self, action: nil, for: .allEvents)
+        removeGestureRecognizer(keyboardTapGesture)
+    }
+
     func refreshThemeDefaults() {
         if isApplyingSnapshot {
             pendingThemeRefresh = true

package/templates/CraftNativeMutation.swift

@@ -108,6 +108,13 @@ final class CraftNativeMutationDocument {
                 case "moveChild":
                     try moveChild(operation, nodes: &candidateNodes)
                     if let id = operation["parentId"] as? String { appendUnique(id, to: &affectedNodeIds) }
+                case "reparentChild":
+                    let previousParent = try reparentChild(operation, nodes: &candidateNodes)
+                    if let id = operation["parentId"] as? String { appendUnique(id, to: &affectedNodeIds) }
+                    appendUnique(previousParent, to: &affectedNodeIds)
+                    // A child crossing parents needs the committed tree to be
+                    // reconciled so the host can move its existing native view.
+                    requiresFullRender = true
                 case "removeNode":
                     if let id = operation["id"] as? String, let parent = candidateNodes[id]?.parent {
                         appendUnique(parent, to: &affectedNodeIds)
@@ -251,6 +258,35 @@ final class CraftNativeMutationDocument {
         nodes[parentId] = parent
     }
 
+    private func reparentChild(_ operation: [String: Any], nodes: inout [String: Node]) throws -> String {
+        let parentId = try requiredId(operation, field: "parentId", name: "reparentChild")
+        let childId = try requiredId(operation, field: "childId", name: "reparentChild")
+        guard var parent = nodes[parentId] else {
+            throw CraftNativeMutationFailure("UNKNOWN_PARENT", "node \(parentId) does not exist")
+        }
+        guard var child = nodes[childId], let previousParentId = child.parent,
+              var previousParent = nodes[previousParentId] else {
+            throw CraftNativeMutationFailure("NOT_ATTACHED", "node \(childId) is not attached to a parent")
+        }
+        guard acceptsChildren(parent.type) else {
+            throw CraftNativeMutationFailure("INVALID_PARENT", "node \(parentId) cannot contain child nodes")
+        }
+        guard parentId != childId, !descendants(of: childId, nodes: nodes).contains(parentId) else {
+            throw CraftNativeMutationFailure("CYCLE", "reparenting node \(childId) would create a cycle")
+        }
+        guard parentId != previousParentId else {
+            throw CraftNativeMutationFailure("SAME_PARENT", "node \(childId) is already a child of \(parentId)")
+        }
+        let index = try insertionIndex(operation, count: parent.children.count)
+        previousParent.children.removeAll { $0 == childId }
+        parent.children.insert(childId, at: index)
+        child.parent = parentId
+        nodes[previousParentId] = previousParent
+        nodes[parentId] = parent
+        nodes[childId] = child
+        return previousParentId
+    }
+
     private func removeNode(
         _ operation: [String: Any],
         nodes: inout [String: Node],