craft-native 0.0.172 → 0.0.173

package/dist/macos/templates/CraftMacRuntime.swift

@@ -0,0 +1,266 @@
+import AppKit
+import ZigJS
+import Foundation
+
+/// One zig-js context per STX window. No DOM and no browser view.
+final class CraftMacRuntime {
+    let context = ZigJSContext()!
+    let route: String
+    let network: CraftMacNetwork
+    weak var scene: CraftMacScene?
+    private var timers: [Int: DispatchWorkItem] = [:]
+    private var tasks: [String: URLSessionTask] = [:]
+    private var disposed = false
+    var errors: [String] = []
+    let document = CraftNativeMutationDocument()
+
+    init(route: String, params: [String: Any], network: CraftMacNetwork) {
+        self.route = route
+        self.network = network
+        context.exceptionHandler = { [weak self] _, value in
+            let message = value?.objectForKeyedSubscript("message")?.toString() ?? "Native script failed"
+            let stack = value?.objectForKeyedSubscript("stack")?.toString() ?? ""
+            self?.errors.append(message)
+            fputs("[craft native] \(message)\n\(stack)\n", stderr)
+        }
+        let post: @convention(block) (String) -> Void = { [weak self] text in self?.receive(text) }
+        let schedule: @convention(block) (Int, Double) -> Void = { [weak self] id, delay in
+            guard let self, !self.disposed else { return }
+            let work = DispatchWorkItem { [weak self] in
+                guard let self, self.timers.removeValue(forKey: id) != nil, !self.disposed else { return }
+                self.context.objectForKeyedSubscript("__craftNativeFireTimer")?.call(withArguments: [id])
+                ZJSContextRunMicrotasks(self.context)
+            }
+            self.timers[id] = work
+            DispatchQueue.main.asyncAfter(deadline: .now() + max(0, min(delay.isFinite ? delay : 0, 2_147_483_647)) / 1000, execute: work)
+        }
+        let cancel: @convention(block) (Int) -> Void = { [weak self] id in self?.timers.removeValue(forKey: id)?.cancel() }
+        let log: @convention(block) (String, String) -> Void = { [weak self] level, text in
+            if level == "error" { self?.errors.append(text) }
+            fputs("[stx \(level)] \(text)\n", stderr)
+        }
+        context.setObject(post, forKeyedSubscript: "craftNativePostMessage" as NSString)
+        context.setObject(schedule, forKeyedSubscript: "craftNativeScheduleTimer" as NSString)
+        context.setObject(cancel, forKeyedSubscript: "craftNativeCancelTimer" as NSString)
+        context.setObject(log, forKeyedSubscript: "craftNativeLog" as NSString)
+        context.setObject(route, forKeyedSubscript: "__stxNativeRoute" as NSString)
+        context.setObject(params, forKeyedSubscript: "__stxNativeParams" as NSString)
+        let info = Bundle.main.infoDictionary ?? [:]
+        let bridge: [String: Any] = [
+            "platform": "macos", "mutationProtocolVersion": 1, "capabilityProtocolVersion": 1,
+            "capabilityTimeoutMs": 30_000, "capabilities": ["desktop", "fetch", "eventStream", "storage", "clipboard", "dialog", "linking", "haptics", "notifications"],
+            "initialAppState": "active", "colorScheme": CraftMacColor.isDark ? "dark" : "light",
+            "appURL": network.base.absoluteString, "appVersion": info["CFBundleShortVersionString"] as? String ?? "", "appBuild": info["CFBundleVersion"] as? String ?? ""
+        ]
+        let bridgeJSON = String(data: try! JSONSerialization.data(withJSONObject: bridge), encoding: .utf8)!
+        context.evaluateScript("""
+        globalThis.__stxNativeCallback = null;
+        globalThis.__stxNativeBridge = \(bridgeJSON);
+        __stxNativeBridge.postMessage = function(text) { craftNativePostMessage(text); };
+        __stxNativeBridge.onMessage = function(callback) { globalThis.__stxNativeCallback = callback; };
+        globalThis.console = {};
+        ['log','info','warn','error','debug'].forEach(function(level) {
+            console[level] = function() { craftNativeLog(level, Array.from(arguments).map(String).join(' ')); };
+        });
+        (function() {
+            var timers = new Map(), sequence = 0;
+            globalThis.setTimeout = function(callback, delay) {
+                var args = Array.prototype.slice.call(arguments, 2), id = ++sequence;
+                timers.set(id, function() { if (typeof callback === 'function') callback.apply(undefined, args); });
+                craftNativeScheduleTimer(id, Number(delay) || 0); return id;
+            };
+            globalThis.clearTimeout = function(id) { if (timers.delete(id)) craftNativeCancelTimer(id); };
+            globalThis.__craftNativeFireTimer = function(id) {
+                var callback = timers.get(id); if (!callback) return; timers.delete(id); callback();
+            };
+            var intervals = new Map();
+            globalThis.setInterval = function(callback, delay) {
+                var id = ++sequence, args = Array.prototype.slice.call(arguments, 2);
+                function tick() { if (!intervals.has(id)) return; intervals.set(id, setTimeout(tick, Math.max(1, Number(delay) || 0))); callback.apply(undefined,args); }
+                intervals.set(id, setTimeout(tick, Math.max(1, Number(delay) || 0))); return id;
+            };
+            globalThis.clearInterval = function(id) { clearTimeout(intervals.get(id)); intervals.delete(id); };
+        })();
+        """)
+    }
+
+    func load(_ bundle: String) { context.evaluateScript(bundle); ZJSContextRunMicrotasks(context) }
+
+    func dispose() {
+        guard !disposed else { return }
+        context.objectForKeyedSubscript("__stxNativeUnmount")?.call(withArguments: [])
+        disposed = true
+        timers.values.forEach { $0.cancel() }; timers.removeAll()
+        tasks.values.forEach { $0.cancel() }; tasks.removeAll()
+        network.cancelStreams(owner: self)
+    }
+
+    func send(_ type: String, _ payload: [String: Any], correlation: String? = nil) {
+        guard !disposed else { return }
+        var message: [String: Any] = ["id": UUID().uuidString, "type": type, "timestamp": Date().timeIntervalSince1970 * 1000, "source": "native", "payload": payload]
+        if let correlation { message["correlationId"] = correlation }
+        guard let bytes = try? JSONSerialization.data(withJSONObject: message), let text = String(data: bytes, encoding: .utf8) else { return }
+        DispatchQueue.main.async { [weak self] in
+            guard let self, !self.disposed else { return }
+            self.context.objectForKeyedSubscript("__stxNativeCallback")?.call(withArguments: [text])
+            ZJSContextRunMicrotasks(self.context)
+        }
+    }
+
+    func event(_ id: String?, payload: [String: Any] = [:]) {
+        guard let id, !id.isEmpty else { return }
+        send("EVENT", ["handlerId": id, "nativeEvent": payload])
+    }
+
+    private func receive(_ text: String) {
+        guard let data = text.data(using: .utf8), let message = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return }
+        let payload = message["payload"] as? [String: Any] ?? [:]
+        switch message["type"] as? String {
+        case "RENDER":
+            guard let tree = payload["document"] as? [String: Any] else { return }
+            document.replace(with: tree)
+            scene?.renderer.render(tree)
+        case "MUTATE":
+            do {
+                let result = try document.apply(payload)
+                if let tree = result.document { scene?.renderer.render(tree) }
+                send("MUTATION_ACK", ["version": 1, "batchId": result.batchId, "revision": result.revision])
+            } catch let error as CraftNativeMutationFailure {
+                send("MUTATION_ERROR", ["version": 1, "batchId": payload["batchId"] ?? "", "code": error.code, "message": error.message])
+            } catch { errors.append(error.localizedDescription) }
+        case "API_REQUEST":
+            guard let id = message["id"] as? String else { return }
+            guard payload["version"] as? Int == 1 else { fail(id, "UNSUPPORTED_VERSION", "Native capability version must be 1"); return }
+            perform(id, payload["module"] as? String ?? "", payload["method"] as? String ?? "", payload["args"] as? [Any] ?? [])
+        case "API_CANCEL":
+            if let id = payload["requestId"] as? String { tasks.removeValue(forKey: id)?.cancel() }
+        default: break
+        }
+    }
+
+    func answer(_ id: String, _ value: Any = NSNull()) {
+        tasks.removeValue(forKey: id)
+        send("API_RESPONSE", ["version": 1, "requestId": id, "data": value], correlation: id)
+    }
+    func fail(_ id: String, _ code: String, _ message: String) {
+        tasks.removeValue(forKey: id)
+        send("API_ERROR", ["version": 1, "requestId": id, "code": code, "message": message], correlation: id)
+    }
+
+    private func perform(_ id: String, _ module: String, _ method: String, _ args: [Any]) {
+        let options = args.first as? [String: Any] ?? [:]
+        switch module {
+        case "Network":
+            if method == "cancelStream" { network.cancelStream(args.first as? String ?? "", owner: self); answer(id); return }
+            guard let request = network.request(options) else { fail(id, "INVALID_ARGUMENT", "Network.fetch requires an HTTP URL"); return }
+            if method == "stream" {
+                network.stream(request, id: options["id"] as? String ?? id, owner: self, requestId: id)
+                return
+            }
+            guard method == "fetch" else { fail(id, "UNSUPPORTED_METHOD", method); return }
+            let task = network.session.dataTask(with: request) { [weak self] data, response, error in
+                DispatchQueue.main.async {
+                    guard let self, !self.disposed else { return }
+                    if let error { self.fail(id, "NETWORK_ERROR", error.localizedDescription); return }
+                    guard let http = response as? HTTPURLResponse else { self.fail(id, "NETWORK_ERROR", "Invalid HTTP response"); return }
+                    if (data?.count ?? 0) > 32 * 1024 * 1024 { self.fail(id, "RESPONSE_TOO_LARGE", "Response exceeds 32 MB"); return }
+                    self.answer(id, CraftMacNetwork.response(http, original: request.url, body: String(decoding: data ?? Data(), as: UTF8.self)))
+                }
+            }
+            tasks[id] = task; task.resume()
+        case "Storage":
+            let prefix = "craft.native."
+            let key = prefix + (args.first as? String ?? "")
+            switch method {
+            case "get": answer(id, UserDefaults.standard.object(forKey: key) ?? NSNull())
+            case "set": if args.count > 1 { UserDefaults.standard.set(args[1], forKey: key) }; answer(id)
+            case "remove": UserDefaults.standard.removeObject(forKey: key); answer(id)
+            case "keys": answer(id, UserDefaults.standard.dictionaryRepresentation().keys.filter { $0.hasPrefix(prefix) }.map { String($0.dropFirst(prefix.count)) })
+            default: fail(id, "UNSUPPORTED_METHOD", method)
+            }
+        case "Clipboard":
+            if method == "read" { answer(id, NSPasteboard.general.string(forType: .string) ?? "") }
+            else { NSPasteboard.general.clearContents(); NSPasteboard.general.setString(args.first as? String ?? "", forType: .string); answer(id) }
+        case "Haptics": NSHapticFeedbackManager.defaultPerformer.perform(.alignment, performanceTime: .default); answer(id)
+        case "Dialog":
+            let alert = NSAlert(); alert.messageText = options["title"] as? String ?? ""; alert.informativeText = options["message"] as? String ?? options["body"] as? String ?? ""
+            alert.addButton(withTitle: options["confirmText"] as? String ?? "OK")
+            if method == "confirm" { alert.addButton(withTitle: options["cancelText"] as? String ?? "Cancel") }
+            let accepted = alert.runModal() == .alertFirstButtonReturn
+            answer(id, method == "confirm" ? accepted : NSNull())
+        case "Linking":
+            guard let text = args.first as? String, let url = URL(string: text), let scheme = url.scheme, ["https", "http", "imessage", "sms", "mailto", "x-apple.systempreferences"].contains(scheme) else { fail(id, "INVALID_ARGUMENT", "Unsupported URL scheme"); return }
+            answer(id, method == "canOpenURL" ? NSWorkspace.shared.urlForApplication(toOpen: url) != nil : NSWorkspace.shared.open(url))
+        case "Desktop": CraftMacApplication.shared.perform(method, args: args, scene: scene, reply: { [weak self] value in self?.answer(id, value) })
+        case "Notifications": CraftMacApplication.shared.notification(method, options: options, reply: { [weak self] value in self?.answer(id, value) })
+        default: fail(id, "CAPABILITY_DISABLED", "Unsupported native capability \(module).\(method)")
+        }
+    }
+}
+
+/// A session shared by native windows, with an isolated, HttpOnly cookie store.
+final class CraftMacNetwork: NSObject, URLSessionDataDelegate {
+    let base: URL
+    lazy var session: URLSession = {
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.timeoutIntervalForRequest = 300
+        configuration.timeoutIntervalForResource = 7 * 24 * 60 * 60
+        return URLSession(configuration: configuration, delegate: self, delegateQueue: .main)
+    }()
+    private struct Stream { let id: String; weak var owner: CraftMacRuntime?; let requestId: String; var opened: Bool = false; var carry = Data() }
+    private var streams: [Int: Stream] = [:]
+    init(base: URL) { self.base = base }
+    func request(_ options: [String: Any]) -> URLRequest? {
+        guard let address = options["url"] as? String, let url = URL(string: address, relativeTo: base)?.absoluteURL,
+              ["http", "https"].contains(url.scheme ?? ""), url.host != nil else { return nil }
+        var request = URLRequest(url: url)
+        request.httpMethod = (options["method"] as? String ?? "GET").uppercased()
+        for (key, value) in options["headers"] as? [String: String] ?? [:] { request.setValue(value, forHTTPHeaderField: key) }
+        if let body = options["body"] as? String { request.httpBody = Data(body.utf8) }
+        return request
+    }
+    static func response(_ response: HTTPURLResponse, original: URL?, body: String = "") -> [String: Any] {
+        ["url": response.url?.absoluteString ?? "", "status": response.statusCode,
+         "statusText": HTTPURLResponse.localizedString(forStatusCode: response.statusCode), "body": body,
+         "redirected": response.url != original,
+         "headers": Dictionary(response.allHeaderFields.map { (String(describing: $0.key).lowercased(), String(describing: $0.value)) }, uniquingKeysWith: { _, value in value })]
+    }
+    func stream(_ request: URLRequest, id: String, owner: CraftMacRuntime, requestId: String) {
+        let task = session.dataTask(with: request)
+        streams[task.taskIdentifier] = Stream(id: id, owner: owner, requestId: requestId)
+        task.resume()
+    }
+    func cancelStream(_ id: String, owner: CraftMacRuntime) {
+        let identifiers = streams.filter { $0.value.id == id && $0.value.owner === owner }.map(\.key)
+        session.getAllTasks { tasks in DispatchQueue.main.async { for task in tasks where identifiers.contains(task.taskIdentifier) { self.streams.removeValue(forKey: task.taskIdentifier); task.cancel() } } }
+    }
+    func cancelStreams(owner: CraftMacRuntime) { for stream in streams.values where stream.owner === owner { cancelStream(stream.id, owner: owner) } }
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive response: URLResponse, completionHandler: @escaping (URLSession.ResponseDisposition) -> Void) {
+        guard var stream = streams[dataTask.taskIdentifier] else { completionHandler(.allow); return }
+        guard let http = response as? HTTPURLResponse else { completionHandler(.cancel); stream.owner?.fail(stream.requestId, "NETWORK_ERROR", "Invalid stream response"); return }
+        stream.opened = true; streams[dataTask.taskIdentifier] = stream
+        stream.owner?.answer(stream.requestId, Self.response(http, original: dataTask.originalRequest?.url))
+        completionHandler(.allow)
+    }
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        guard var stream = streams[dataTask.taskIdentifier] else { return }
+        let bytes = [UInt8](stream.carry + data)
+        var cut = bytes.count, back = 1
+        while back <= min(3, bytes.count) {
+            let byte = bytes[bytes.count - back]
+            if byte & 0xC0 == 0x80 { back += 1; continue }
+            let length = byte >= 0xF0 ? 4 : byte >= 0xE0 ? 3 : byte >= 0xC0 ? 2 : 1
+            if length > back { cut -= back }
+            break
+        }
+        stream.carry = Data(bytes[cut...]); streams[dataTask.taskIdentifier] = stream
+        let text = String(decoding: bytes[..<cut], as: UTF8.self)
+        if !text.isEmpty { stream.owner?.send("NETWORK_STREAM", ["id": stream.id, "chunk": text]) }
+    }
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        guard let stream = streams.removeValue(forKey: task.taskIdentifier) else { return }
+        if !stream.opened { stream.owner?.fail(stream.requestId, "NETWORK_ERROR", error?.localizedDescription ?? "Stream failed") }
+        else if let error { stream.owner?.send("NETWORK_STREAM", ["id": stream.id, "error": error.localizedDescription]) }
+        else { stream.owner?.send("NETWORK_STREAM", ["id": stream.id, "done": true]) }
+    }
+}

package/dist/macos/templates/CraftNativeMutation.swift

@@ -0,0 +1,390 @@
+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)
+    }
+
+    /// The committed parent of a node: nil for the root or a node it does not hold.
+    func parentId(of id: String) -> String? {
+        nodes[id]?.parent
+    }
+
+    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") { mergePatch(patch["props"], into: &node.props) }
+        if patch.keys.contains("style") { mergePatch(patch["style"], into: &node.style) }
+        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"])
+        }
+        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 }
+    }
+
+    /// Every type the renderer draws children of (CraftNativeScreen's
+    /// reconcile), by the names it accepts (`canonicalType`, so `svg` is
+    /// `Svg`). Only View, SafeAreaView and ScrollView used to be here, so a
+    /// drawing revealed after the first paint (an `:if` around an `<svg>`)
+    /// had its shapes refused as INVALID_PARENT, and the whole screen was
+    /// drawn again; Android's host already took the same list.
+    static let containerTypes: Set<String> = [
+        "View", "SafeAreaView", "ScrollView", "KeyboardAvoidingView", "Modal", "Pressable",
+        "TouchableOpacity", "TouchableHighlight", "ImageBackground", "FlatList", "SectionList",
+        "Fragment", "Svg", "G",
+    ]
+    private static let containerTypeKeys = Set(containerTypes.map { $0.lowercased() })
+
+    private func acceptsChildren(_ type: String) -> Bool {
+        Self.containerTypeKeys.contains(type.lowercased())
+    }
+
+    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 mergePatch(_ value: Any?, into target: inout [String: Any]) {
+        for (key, next) in dictionary(value) {
+            if next is NSNull { target.removeValue(forKey: key) }
+            else { target[key] = next }
+        }
+    }
+
+    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) }
+    }
+}