craft-native 0.0.113 → 0.0.118

package/dist/ios/templates/CraftNativeFlatList.swift

@@ -0,0 +1,323 @@
+import UIKit
+
+private final class CraftNativeFlatListLayout: UICollectionViewFlowLayout {
+    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
+    }
+}
+
+/// A keyed, recycling native list used by the stx-native FlatList primitive.
+/// The screen controller owns rendered row state; this view owns collection
+/// diffs, viewport state, and UICollectionView cell reuse.
+final class CraftNativeFlatList: UICollectionView, UICollectionViewDelegateFlowLayout {
+    typealias RenderItem = (_ node: [String: Any], _ identity: String, _ previous: UIView?) -> UIView
+
+    private final class Cell: UICollectionViewCell {
+        static let reuseIdentifier = "CraftNativeFlatListCell"
+
+        private(set) var representedIdentity: String?
+        private(set) var hostedView: UIView?
+        var onRecycle: ((String) -> Void)?
+
+        override func prepareForReuse() {
+            super.prepareForReuse()
+            releaseHostedView()
+        }
+
+        func host(_ view: UIView, identity: String) {
+            if representedIdentity != identity { releaseHostedView() }
+            representedIdentity = identity
+            guard hostedView !== view else { return }
+            hostedView?.removeFromSuperview()
+            hostedView = view
+            view.translatesAutoresizingMaskIntoConstraints = false
+            contentView.addSubview(view)
+            NSLayoutConstraint.activate([
+                view.topAnchor.constraint(equalTo: contentView.topAnchor),
+                view.bottomAnchor.constraint(equalTo: contentView.bottomAnchor),
+                view.leadingAnchor.constraint(equalTo: contentView.leadingAnchor),
+                view.trailingAnchor.constraint(equalTo: contentView.trailingAnchor),
+            ])
+        }
+
+        func releaseHostedView() {
+            if let identity = representedIdentity { onRecycle?(identity) }
+            hostedView?.removeFromSuperview()
+            hostedView = nil
+            representedIdentity = nil
+            onRecycle = nil
+        }
+
+        override func preferredLayoutAttributesFitting(
+            _ layoutAttributes: UICollectionViewLayoutAttributes
+        ) -> UICollectionViewLayoutAttributes {
+            guard let hostedView = hostedView else { return layoutAttributes }
+            let attributes = layoutAttributes.copy() as! UICollectionViewLayoutAttributes
+            let target = CGSize(width: layoutAttributes.size.width, height: UIView.layoutFittingCompressedSize.height)
+            let measured = hostedView.systemLayoutSizeFitting(
+                target,
+                withHorizontalFittingPriority: .required,
+                verticalFittingPriority: .fittingSizeLevel
+            )
+            attributes.size.height = max(1, measured.height)
+            return attributes
+        }
+    }
+
+    private struct Item {
+        let identity: String
+        let node: [String: Any]
+        let signature: Data
+        let isChrome: Bool
+    }
+
+    private struct ViewportAnchor {
+        let identity: String
+        let distanceFromOrigin: CGFloat
+    }
+
+    private let flowLayout: UICollectionViewFlowLayout
+    private var diffableDataSource: UICollectionViewDiffableDataSource<Int, String>!
+    private var items: [Item] = []
+    private var itemsByIdentity: [String: Item] = [:]
+    private var renderItem: RenderItem?
+    private var recycleItem: ((String) -> Void)?
+    private var endReached: (() -> Void)?
+    private var endReachedThreshold = 0.1
+    private var endReachedSignature: String?
+    private var columns = 1
+    private var isApplyingSnapshot = false
+    private var pendingApply: (() -> Void)?
+
+    init() {
+        let layout = CraftNativeFlatListLayout()
+        layout.estimatedItemSize = CGSize(width: 320, height: 44)
+        layout.minimumLineSpacing = 0
+        layout.minimumInteritemSpacing = 0
+        flowLayout = layout
+        super.init(frame: .zero, collectionViewLayout: layout)
+        backgroundColor = .clear
+        alwaysBounceVertical = true
+        delegate = self
+        register(Cell.self, forCellWithReuseIdentifier: Cell.reuseIdentifier)
+        diffableDataSource = UICollectionViewDiffableDataSource<Int, String>(collectionView: self) {
+            [weak self] collectionView, indexPath, identity in
+            guard let self = self,
+                  let item = self.itemsByIdentity[identity],
+                  let cell = collectionView.dequeueReusableCell(
+                    withReuseIdentifier: Cell.reuseIdentifier,
+                    for: indexPath
+                  ) as? Cell,
+                  let renderItem = self.renderItem else { return UICollectionViewCell() }
+            let view = renderItem(item.node, identity, cell.hostedView)
+            cell.onRecycle = self.recycleItem
+            cell.host(view, identity: identity)
+            return cell
+        }
+    }
+
+    required init?(coder: NSCoder) { nil }
+
+    var visibleItemIdentities: [String] {
+        indexPathsForVisibleItems
+            .sorted { $0.item < $1.item }
+            .compactMap { diffableDataSource.itemIdentifier(for: $0) }
+    }
+
+    func apply(
+        nodes: [[String: Any]],
+        horizontal: Bool,
+        columns: Int,
+        inverted: Bool,
+        endReachedThreshold: Double,
+        renderItem: @escaping RenderItem,
+        recycleItem: @escaping (String) -> Void,
+        endReached: (() -> Void)?
+    ) {
+        if isApplyingSnapshot {
+            pendingApply = { [weak self] in
+                self?.apply(
+                    nodes: nodes,
+                    horizontal: horizontal,
+                    columns: columns,
+                    inverted: inverted,
+                    endReachedThreshold: endReachedThreshold,
+                    renderItem: renderItem,
+                    recycleItem: recycleItem,
+                    endReached: endReached
+                )
+            }
+            return
+        }
+        isApplyingSnapshot = true
+
+        self.renderItem = renderItem
+        self.recycleItem = recycleItem
+        self.endReached = endReached
+        self.endReachedThreshold = max(0, endReachedThreshold)
+        self.columns = max(1, columns)
+
+        layoutIfNeeded()
+        let oldItems = itemsByIdentity
+        let viewportAnchor = currentViewportAnchor()
+        var seen: [String: Int] = [:]
+        var next = nodes.enumerated().map { index, node -> Item in
+            let base = Self.identity(for: node) ?? "index:\(index)"
+            let occurrence = seen[base, default: 0]
+            seen[base] = occurrence + 1
+            let identity = occurrence == 0 ? base : "\(base)#\(occurrence)"
+            let props = node["props"] as? [String: Any] ?? [:]
+            let role = props["listRole"] as? String
+            let signature = (try? JSONSerialization.data(withJSONObject: node, options: [.sortedKeys])) ?? Data()
+            return Item(identity: identity, node: node, signature: signature, isChrome: role != nil && role != "item")
+        }
+        if inverted { next.reverse() }
+        items = next
+        itemsByIdentity = Dictionary(uniqueKeysWithValues: next.map { ($0.identity, $0) })
+
+        flowLayout.scrollDirection = horizontal ? .horizontal : .vertical
+        alwaysBounceHorizontal = horizontal
+        alwaysBounceVertical = !horizontal
+        showsHorizontalScrollIndicator = horizontal
+        showsVerticalScrollIndicator = !horizontal
+        flowLayout.invalidateLayout()
+
+        let nextIds = Set(itemsByIdentity.keys)
+        for identity in oldItems.keys where !nextIds.contains(identity) { recycleItem(identity) }
+        let changed = next.compactMap { item -> String? in
+            guard let old = oldItems[item.identity], old.signature != item.signature else { return nil }
+            return item.identity
+        }
+
+        var snapshot = NSDiffableDataSourceSnapshot<Int, String>()
+        snapshot.appendSections([0])
+        snapshot.appendItems(next.map(\.identity), toSection: 0)
+        let retainedOffset = contentOffset
+        diffableDataSource.apply(snapshot, animatingDifferences: false) { [weak self] in
+            guard let self = self else { return }
+            let live = Set(self.diffableDataSource.snapshot().itemIdentifiers)
+            let changedLive = changed.filter { live.contains($0) }
+            let restoreViewport = { [weak self] in
+                guard let self = self else { return }
+                self.layoutIfNeeded()
+                if let viewportAnchor = viewportAnchor {
+                    self.restore(viewportAnchor)
+                } else {
+                    self.setContentOffset(self.clamped(retainedOffset), animated: false)
+                }
+                self.finishApplyingSnapshot()
+            }
+            if !changedLive.isEmpty {
+                var update = self.diffableDataSource.snapshot()
+                update.reconfigureItems(changedLive)
+                self.diffableDataSource.apply(update, animatingDifferences: false, completion: restoreViewport)
+            } else {
+                restoreViewport()
+            }
+        }
+
+        let dataItems = next.filter { !$0.isChrome }
+        let contentSignature = "\(dataItems.count):\(dataItems.last?.identity ?? "empty")"
+        if contentSignature != endReachedSignature { endReachedSignature = nil }
+    }
+
+    func discardAll() {
+        visibleCells.compactMap { $0 as? Cell }.forEach { $0.releaseHostedView() }
+        itemsByIdentity.keys.forEach { recycleItem?($0) }
+        items = []
+        itemsByIdentity = [:]
+        renderItem = nil
+        recycleItem = nil
+        endReached = nil
+    }
+
+    func scrollViewDidScroll(_ scrollView: UIScrollView) { evaluateEndReached() }
+
+    func collectionView(
+        _ collectionView: UICollectionView,
+        layout collectionViewLayout: UICollectionViewLayout,
+        sizeForItemAt indexPath: IndexPath
+    ) -> CGSize {
+        guard items.indices.contains(indexPath.item) else { return CGSize(width: bounds.width, height: 44) }
+        let item = items[indexPath.item]
+        if flowLayout.scrollDirection == .horizontal {
+            return CGSize(width: max(1, bounds.width * 0.8), height: max(1, bounds.height))
+        }
+        let count = item.isChrome ? 1 : columns
+        let spacing = flowLayout.minimumInteritemSpacing * CGFloat(count - 1)
+        return CGSize(width: max(1, (bounds.width - spacing) / CGFloat(count)), height: 44)
+    }
+
+    private func evaluateEndReached() {
+        guard !isApplyingSnapshot, pendingApply == nil,
+              let endReached = endReached,
+              let lastVisible = indexPathsForVisibleItems.map(\.item).max() else { return }
+        let dataIndices = items.indices.filter { !items[$0].isChrome }
+        guard !dataIndices.isEmpty,
+              let lastDataOrdinal = dataIndices.lastIndex(where: { $0 <= lastVisible }) else { return }
+        let remaining = dataIndices.count - lastDataOrdinal - 1
+        let thresholdItems = max(1, Int(ceil(Double(dataIndices.count) * endReachedThreshold)))
+        guard remaining <= thresholdItems else { return }
+        let lastIdentity = items[dataIndices[dataIndices.count - 1]].identity
+        let signature = "\(dataIndices.count):\(lastIdentity)"
+        guard endReachedSignature != signature else { return }
+        endReachedSignature = signature
+        endReached()
+    }
+
+    private func finishApplyingSnapshot() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            self.isApplyingSnapshot = false
+            if let pendingApply = self.pendingApply {
+                self.pendingApply = nil
+                pendingApply()
+                return
+            }
+            self.evaluateEndReached()
+        }
+    }
+
+    private func clamped(_ offset: CGPoint) -> CGPoint {
+        CGPoint(
+            x: min(max(-adjustedContentInset.left, offset.x), max(-adjustedContentInset.left, contentSize.width - bounds.width + adjustedContentInset.right)),
+            y: min(max(-adjustedContentInset.top, offset.y), max(-adjustedContentInset.top, contentSize.height - bounds.height + adjustedContentInset.bottom))
+        )
+    }
+
+    private func currentViewportAnchor() -> ViewportAnchor? {
+        let horizontal = flowLayout.scrollDirection == .horizontal
+        let ordered = indexPathsForVisibleItems.sorted { lhs, rhs in
+            let left = layoutAttributesForItem(at: lhs)?.frame
+            let right = layoutAttributesForItem(at: rhs)?.frame
+            return horizontal ? (left?.minX ?? 0) < (right?.minX ?? 0) : (left?.minY ?? 0) < (right?.minY ?? 0)
+        }
+        guard let indexPath = ordered.first,
+              let identity = diffableDataSource.itemIdentifier(for: indexPath),
+              let frame = layoutAttributesForItem(at: indexPath)?.frame else { return nil }
+        let distance = horizontal ? frame.minX - contentOffset.x : frame.minY - contentOffset.y
+        return ViewportAnchor(identity: identity, distanceFromOrigin: distance)
+    }
+
+    private func restore(_ anchor: ViewportAnchor) {
+        guard let indexPath = diffableDataSource.indexPath(for: anchor.identity),
+              let frame = layoutAttributesForItem(at: indexPath)?.frame else { return }
+        var offset = contentOffset
+        if flowLayout.scrollDirection == .horizontal {
+            offset.x = frame.minX - anchor.distanceFromOrigin
+        } else {
+            offset.y = frame.minY - anchor.distanceFromOrigin
+        }
+        setContentOffset(clamped(offset), animated: false)
+    }
+
+    private static func identity(for node: [String: Any]) -> String? {
+        let props = node["props"] as? [String: Any] ?? [:]
+        return [node["id"], node["key"], props["key"], props["testID"]]
+            .compactMap { $0 as? String }
+            .first { !$0.isEmpty }
+    }
+}

package/dist/ios/templates/CraftNativeMutation.swift

@@ -0,0 +1,365 @@
+import CoreFoundation
+import Foundation
+
+let craftNativeMutationProtocolVersion = 1
+
+struct CraftNativeMutationFailure: Error, Equatable {
+    let code: String
+    let message: String
+    let operationIndex: Int?
+
+    init(_ code: String, _ message: String, operationIndex: Int? = nil) {
+        self.code = code
+        self.message = message
+        self.operationIndex = operationIndex
+    }
+}
+
+struct CraftNativeMutationResult {
+    let batchId: String
+    let revision: Int
+    let document: [String: Any]?
+    let updatedNodeIds: [String]
+    let affectedNodeIds: [String]
+    let requiresFullRender: Bool
+}
+
+/// Validates and applies versioned native-tree mutations without touching UIKit.
+/// A batch is committed only after every operation succeeds against a copy.
+final class CraftNativeMutationDocument {
+    private struct Node {
+        let id: String
+        var type: String
+        var props: [String: Any]
+        var style: [String: Any]
+        var events: [String: Any]
+        var text: [String]
+        var children: [String]
+        var parent: String?
+    }
+
+    private var nodes: [String: Node] = [:]
+    private var rootId: String?
+    private(set) var revision = 0
+
+    func replace(with document: [String: Any]) {
+        var replacement: [String: Node] = [:]
+        let root = importNode(document, preferredId: "root", parent: nil, nodes: &replacement)
+        nodes = replacement
+        rootId = root
+        revision = 0
+    }
+
+    func apply(_ payload: [String: Any]) throws -> CraftNativeMutationResult {
+        let batchId = payload["batchId"] as? String ?? ""
+        guard !batchId.isEmpty else {
+            throw CraftNativeMutationFailure("INVALID_BATCH", "batchId must be a non-empty string")
+        }
+        guard integer(payload["version"]) == craftNativeMutationProtocolVersion else {
+            throw CraftNativeMutationFailure(
+                "UNSUPPORTED_VERSION",
+                "mutation protocol version must be \(craftNativeMutationProtocolVersion)"
+            )
+        }
+        guard let baseRevision = integer(payload["baseRevision"]), baseRevision == revision else {
+            throw CraftNativeMutationFailure(
+                "REVISION_MISMATCH",
+                "baseRevision must equal the current revision \(revision)"
+            )
+        }
+        guard let nextRevision = integer(payload["revision"]), nextRevision == revision + 1 else {
+            throw CraftNativeMutationFailure(
+                "INVALID_REVISION",
+                "revision must advance exactly once from \(revision)"
+            )
+        }
+        guard let operations = payload["operations"] as? [Any], !operations.isEmpty else {
+            throw CraftNativeMutationFailure("INVALID_BATCH", "operations must be a non-empty array")
+        }
+
+        var candidateNodes = nodes
+        var candidateRoot = rootId
+        var updatedNodeIds: [String] = []
+        var affectedNodeIds: [String] = []
+        var requiresFullRender = false
+        for (index, value) in operations.enumerated() {
+            guard let operation = value as? [String: Any], let name = operation["op"] as? String else {
+                throw CraftNativeMutationFailure(
+                    "INVALID_OPERATION",
+                    "operation must be an object with an op string",
+                    operationIndex: index
+                )
+            }
+            do {
+                switch name {
+                case "createNode":
+                    if operation["root"] as? Bool == true { requiresFullRender = true }
+                    try createNode(operation, nodes: &candidateNodes, rootId: &candidateRoot)
+                case "updateNode":
+                    try updateNode(operation, nodes: &candidateNodes)
+                    if let id = operation["id"] as? String {
+                        appendUnique(id, to: &updatedNodeIds)
+                        appendUnique(id, to: &affectedNodeIds)
+                    }
+                case "insertChild":
+                    try insertChild(operation, nodes: &candidateNodes)
+                    if let id = operation["parentId"] as? String { appendUnique(id, to: &affectedNodeIds) }
+                case "moveChild":
+                    try moveChild(operation, nodes: &candidateNodes)
+                    if let id = operation["parentId"] as? String { appendUnique(id, to: &affectedNodeIds) }
+                case "removeNode":
+                    if let id = operation["id"] as? String, let parent = candidateNodes[id]?.parent {
+                        appendUnique(parent, to: &affectedNodeIds)
+                    } else {
+                        requiresFullRender = true
+                    }
+                    try removeNode(operation, nodes: &candidateNodes, rootId: &candidateRoot)
+                default:
+                    throw CraftNativeMutationFailure("UNKNOWN_OPERATION", "unsupported operation \(name)")
+                }
+            } catch let failure as CraftNativeMutationFailure {
+                throw CraftNativeMutationFailure(failure.code, failure.message, operationIndex: index)
+            }
+        }
+        if candidateRoot == nil, !candidateNodes.isEmpty {
+            throw CraftNativeMutationFailure("MISSING_ROOT", "a non-empty document must have one root node")
+        }
+        if let candidateRoot {
+            guard let root = candidateNodes[candidateRoot], root.parent == nil else {
+                throw CraftNativeMutationFailure("INVALID_TREE", "root node must not have a parent")
+            }
+            guard descendants(of: candidateRoot, nodes: candidateNodes).count + 1 == candidateNodes.count else {
+                throw CraftNativeMutationFailure("INVALID_TREE", "all nodes must be reachable from the root")
+            }
+        }
+
+        nodes = candidateNodes
+        rootId = candidateRoot
+        revision = nextRevision
+        return CraftNativeMutationResult(
+            batchId: batchId,
+            revision: nextRevision,
+            document: candidateRoot.flatMap { materialize($0, nodes: candidateNodes) },
+            updatedNodeIds: updatedNodeIds,
+            affectedNodeIds: affectedNodeIds,
+            requiresFullRender: requiresFullRender
+        )
+    }
+
+    func node(_ id: String) -> [String: Any]? {
+        materialize(id, nodes: nodes)
+    }
+
+    private func createNode(
+        _ operation: [String: Any],
+        nodes: inout [String: Node],
+        rootId: inout String?
+    ) throws {
+        guard let id = operation["id"] as? String, !id.isEmpty else {
+            throw CraftNativeMutationFailure("INVALID_NODE", "createNode.id must be a non-empty string")
+        }
+        guard nodes[id] == nil else {
+            throw CraftNativeMutationFailure("DUPLICATE_NODE", "node \(id) already exists")
+        }
+        guard let value = operation["node"] as? [String: Any],
+              let type = value["type"] as? String, !type.isEmpty else {
+            throw CraftNativeMutationFailure("INVALID_NODE", "createNode.node.type must be a non-empty string")
+        }
+        let text = try textChildren(value["children"] ?? value["text"])
+        let makeRoot = operation["root"] as? Bool == true
+        if makeRoot, rootId != nil {
+            throw CraftNativeMutationFailure("ROOT_EXISTS", "the document already has a root node")
+        }
+        nodes[id] = Node(
+            id: id,
+            type: type,
+            props: dictionary(value["props"]),
+            style: dictionary(value["style"]),
+            events: dictionary(value["events"]),
+            text: text,
+            children: [],
+            parent: nil
+        )
+        if makeRoot { rootId = id }
+    }
+
+    private func updateNode(_ operation: [String: Any], nodes: inout [String: Node]) throws {
+        let id = try requiredId(operation, name: "updateNode")
+        guard var node = nodes[id] else {
+            throw CraftNativeMutationFailure("UNKNOWN_NODE", "node \(id) does not exist")
+        }
+        guard let patch = operation["patch"] as? [String: Any] else {
+            throw CraftNativeMutationFailure("INVALID_PATCH", "updateNode.patch must be an object")
+        }
+        let allowed = Set(["props", "style", "events", "children", "text"])
+        if let unknown = patch.keys.sorted().first(where: { !allowed.contains($0) }) {
+            throw CraftNativeMutationFailure("INVALID_PATCH", "unsupported patch field \(unknown)")
+        }
+        if patch.keys.contains("props") { node.props = dictionary(patch["props"]) }
+        if patch.keys.contains("style") { node.style = dictionary(patch["style"]) }
+        if patch.keys.contains("events") { node.events = dictionary(patch["events"]) }
+        if patch.keys.contains("children") || patch.keys.contains("text") {
+            node.text = try textChildren(patch["children"] ?? patch["text"])
+        }
+        nodes[id] = node
+    }
+
+    private func insertChild(_ operation: [String: Any], nodes: inout [String: Node]) throws {
+        let parentId = try requiredId(operation, field: "parentId", name: "insertChild")
+        let childId = try requiredId(operation, field: "childId", name: "insertChild")
+        guard var parent = nodes[parentId] else {
+            throw CraftNativeMutationFailure("UNKNOWN_PARENT", "parent node \(parentId) does not exist")
+        }
+        guard var child = nodes[childId] else {
+            throw CraftNativeMutationFailure("UNKNOWN_NODE", "node \(childId) does not exist")
+        }
+        guard acceptsChildren(parent.type) else {
+            throw CraftNativeMutationFailure("INVALID_PARENT", "node \(parentId) cannot contain child nodes")
+        }
+        guard child.parent == nil else {
+            throw CraftNativeMutationFailure("NODE_ATTACHED", "node \(childId) already has a parent")
+        }
+        guard parentId != childId, !descendants(of: childId, nodes: nodes).contains(parentId) else {
+            throw CraftNativeMutationFailure("CYCLE", "inserting node \(childId) would create a cycle")
+        }
+        let index = try insertionIndex(operation, count: parent.children.count)
+        parent.children.insert(childId, at: index)
+        child.parent = parentId
+        nodes[parentId] = parent
+        nodes[childId] = child
+    }
+
+    private func moveChild(_ operation: [String: Any], nodes: inout [String: Node]) throws {
+        let parentId = try requiredId(operation, field: "parentId", name: "moveChild")
+        let childId = try requiredId(operation, field: "childId", name: "moveChild")
+        guard var parent = nodes[parentId] else {
+            throw CraftNativeMutationFailure("UNKNOWN_PARENT", "parent node \(parentId) does not exist")
+        }
+        guard nodes[childId]?.parent == parentId, let oldIndex = parent.children.firstIndex(of: childId) else {
+            throw CraftNativeMutationFailure("NOT_A_CHILD", "node \(childId) is not a child of \(parentId)")
+        }
+        parent.children.remove(at: oldIndex)
+        let index = try insertionIndex(operation, count: parent.children.count)
+        parent.children.insert(childId, at: index)
+        nodes[parentId] = parent
+    }
+
+    private func removeNode(
+        _ operation: [String: Any],
+        nodes: inout [String: Node],
+        rootId: inout String?
+    ) throws {
+        let id = try requiredId(operation, name: "removeNode")
+        guard let node = nodes[id] else {
+            throw CraftNativeMutationFailure("UNKNOWN_NODE", "node \(id) does not exist")
+        }
+        if let parentId = node.parent, var parent = nodes[parentId] {
+            parent.children.removeAll { $0 == id }
+            nodes[parentId] = parent
+        }
+        for descendant in descendants(of: id, nodes: nodes).union([id]) { nodes.removeValue(forKey: descendant) }
+        if rootId == id { rootId = nil }
+    }
+
+    private func requiredId(
+        _ operation: [String: Any],
+        field: String = "id",
+        name: String
+    ) throws -> String {
+        guard let id = operation[field] as? String, !id.isEmpty else {
+            throw CraftNativeMutationFailure("INVALID_NODE", "\(name).\(field) must be a non-empty string")
+        }
+        return id
+    }
+
+    private func insertionIndex(_ operation: [String: Any], count: Int) throws -> Int {
+        guard let index = integer(operation["index"]), index >= 0, index <= count else {
+            throw CraftNativeMutationFailure("INVALID_INDEX", "index must be between 0 and \(count)")
+        }
+        return index
+    }
+
+    private func textChildren(_ value: Any?) throws -> [String] {
+        if value == nil || value is NSNull { return [] }
+        if let text = value as? String { return [text] }
+        guard let values = value as? [Any], values.allSatisfy({ $0 is String }) else {
+            throw CraftNativeMutationFailure(
+                "INVALID_NODE",
+                "node children may contain text only; use insertChild for node relationships"
+            )
+        }
+        return values.compactMap { $0 as? String }
+    }
+
+    private func acceptsChildren(_ type: String) -> Bool {
+        type == "View" || type == "SafeAreaView" || type == "ScrollView"
+    }
+
+    private func descendants(of id: String, nodes: [String: Node]) -> Set<String> {
+        guard let node = nodes[id] else { return [] }
+        return node.children.reduce(into: Set<String>()) { result, child in
+            result.insert(child)
+            result.formUnion(descendants(of: child, nodes: nodes))
+        }
+    }
+
+    private func materialize(_ id: String, nodes: [String: Node]) -> [String: Any]? {
+        guard let node = nodes[id] else { return nil }
+        var value: [String: Any] = [
+            "id": node.id,
+            "type": node.type,
+            "props": node.props,
+            "style": node.style,
+            "events": node.events,
+        ]
+        let text: [Any] = node.text
+        let children: [Any] = node.children.compactMap { materialize($0, nodes: nodes) }
+        value["children"] = text + children
+        return value
+    }
+
+    private func importNode(
+        _ value: [String: Any],
+        preferredId: String,
+        parent: String?,
+        nodes: inout [String: Node]
+    ) -> String {
+        let props = dictionary(value["props"])
+        let explicit = (value["id"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+        let key = ([value["key"], props["key"], props["testID"]].compactMap { $0 as? String }.first)
+        var id = explicit ?? key.map { "\(parent ?? "root")/key:\($0)" } ?? preferredId
+        if nodes[id] != nil { id = "\(preferredId)#\(nodes.count)" }
+        let children = value["children"] as? [Any] ?? []
+        nodes[id] = Node(
+            id: id,
+            type: value["type"] as? String ?? "View",
+            props: props,
+            style: dictionary(value["style"]),
+            events: dictionary(value["events"]),
+            text: children.compactMap { $0 as? String },
+            children: [],
+            parent: parent
+        )
+        let childIds = children.enumerated().compactMap { index, child -> String? in
+            guard let child = child as? [String: Any] else { return nil }
+            return importNode(child, preferredId: "\(id)/index:\(index)", parent: id, nodes: &nodes)
+        }
+        nodes[id]?.children = childIds
+        return id
+    }
+
+    private func dictionary(_ value: Any?) -> [String: Any] {
+        value as? [String: Any] ?? [:]
+    }
+
+    private func integer(_ value: Any?) -> Int? {
+        guard let number = value as? NSNumber else { return nil }
+        guard CFGetTypeID(number) != CFBooleanGetTypeID() else { return nil }
+        let candidate = number.intValue
+        return number.doubleValue == Double(candidate) ? candidate : nil
+    }
+
+    private func appendUnique(_ id: String, to values: inout [String]) {
+        if !values.contains(id) { values.append(id) }
+    }
+}