pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native/ios/Sources/PythonNativeKit/Animation/PNAnimator.swift

@@ -0,0 +1,312 @@
+import UIKit
+
+/// Drives the `animate(tag, request)` protocol for animatable props
+/// (`opacity`, `background_color`, `color`, `translate_x`, `translate_y`,
+/// `scale`, `scale_x`, `scale_y`, `rotate`).
+///
+/// - `set` applies one Python-driven frame immediately.
+/// - `start` runs `timing` / `spring` with `UIViewPropertyAnimator` and
+///   `decay` with a display-link integrator; completion posts
+///   `callback("animation", 0, "", {"id": n, "finished": bool})`.
+/// - `cancel` stops the animation and returns the presentation value.
+public final class PNAnimator {
+    public static let shared = PNAnimator()
+
+    /// Prop names accepted by `set` and `start`.
+    public static let animatableProps: Set<String> = [
+        "opacity", "background_color", "color", "translate_x", "translate_y", "scale", "scale_x", "scale_y", "rotate",
+    ]
+
+    final class Running {
+        weak var view: UIView?
+        let prop: String
+        var animator: UIViewPropertyAnimator?
+        var decay: PNDecayDriver?
+        init(view: UIView, prop: String) {
+            self.view = view
+            self.prop = prop
+        }
+    }
+
+    private var running: [Int64: Running] = [:]
+
+    private init() {}
+
+    // MARK: - Request routing
+
+    /// Handle one decoded `animate` request for the view with `tag`.
+    public func handle(tag: Int64, request: [String: Any]) -> Any? {
+        let op = PNProps.string(request["op"]) ?? ""
+        switch op {
+        case "graph":
+            PNAnimationGraph.install(request["graph"] as? [String: Any] ?? [:])
+            return nil
+        case "set":
+            guard let record = PNViewRegistry.shared.resolve(tag), let prop = PNProps.string(request["prop"]) else { return nil }
+            record.manager.setAnimatedProperty(view: record.view, prop: prop, value: request["value"])
+            return nil
+        case "start":
+            guard let record = PNViewRegistry.shared.resolve(tag), let prop = PNProps.string(request["prop"]),
+                  let id = PNProps.int(request["id"])
+            else { return ["ok": false] }
+            let spec = PNProps.dict(request["spec"]) ?? [:]
+            if prop.hasPrefix("_pn_graph:"), let node = Int64(prop.dropFirst(10)) {
+                return ["ok": PNAnimationGraph.start(Int64(id), node: node, spec: spec)]
+            }
+            let ok = record.manager.startAnimation(view: record.view, id: Int64(id), prop: prop, spec: spec)
+            return ["ok": ok]
+        case "cancel":
+            guard let id = PNProps.int(request["id"]) else { return nil }
+            if let value = PNAnimationGraph.cancel(Int64(id)) { return ["value": value] }
+            let value: Any?
+            if let record = PNViewRegistry.shared.resolve(tag) {
+                value = record.manager.cancelAnimation(view: record.view, id: Int64(id))
+            } else {
+                value = cancel(id: Int64(id))
+            }
+            guard let value = value else { return nil }
+            return ["value": value]
+        default:
+            PNLog.rateLimited(PNLog.animation, key: "op:\(op)", "unknown animate op '\(op)'")
+            return nil
+        }
+    }
+
+    // MARK: - Frame application
+
+    /// Apply one value of `prop` to `view` immediately.
+    public func applyValue(view: UIView, prop: String, value: Any?) {
+        if prop.hasPrefix("_pn_graph:"), let node = Int64(prop.dropFirst(10)), let value = PNProps.double(value) {
+            PNAnimationGraph.set(node, value)
+            return
+        }
+        switch prop {
+        case "opacity":
+            if let v = PNProps.double(value) { view.alpha = CGFloat(v) }
+        case "background_color":
+            if let color = PNColor.parse(value) { view.backgroundColor = color }
+        case "color":
+            guard let color = PNColor.parse(value) else { return }
+            if let label = view as? UILabel {
+                label.textColor = color
+            } else if let field = view as? UITextField {
+                field.textColor = color
+            } else if let textView = view as? UITextView {
+                textView.textColor = color
+            } else if let button = view as? UIButton {
+                button.setTitleColor(color, for: .normal)
+            }
+        case "translate_x", "translate_y", "scale", "scale_x", "scale_y", "rotate":
+            guard let v = PNProps.double(value), v.isFinite else { return }
+            PNTransform.apply(view, spec: [[prop: v]])
+        default:
+            PNLog.once(PNLog.animation, key: "prop:\(prop)", "ignoring unknown animated prop '\(prop)'")
+        }
+    }
+
+    /// Read the value of `prop` currently on screen (presentation layer when animating).
+    public func presentationValue(view: UIView, prop: String) -> Any? {
+        let layer = view.layer.presentation() ?? view.layer
+        switch prop {
+        case "opacity":
+            return Double(layer.opacity)
+        case "background_color":
+            return layer.backgroundColor.map { PNColor.hexString(UIColor(cgColor: $0)) }
+        case "translate_x", "translate_y", "scale", "scale_x", "scale_y", "rotate":
+            let t = layer.affineTransform()
+            let parts = PNTransform.decompose(t)
+            switch prop {
+            case "translate_x": return Double(parts.translateX)
+            case "translate_y": return Double(parts.translateY)
+            case "scale", "scale_x": return Double(parts.scaleX)
+            case "scale_y": return Double(parts.scaleY)
+            default: return Double(parts.rotateDegrees)
+            }
+        default:
+            return nil
+        }
+    }
+
+    // MARK: - Start / cancel
+
+    /// Start a native animation. Returns `false` when the spec must be
+    /// ticked by Python instead.
+    public func start(view: UIView, id: Int64, prop: String, spec: [String: Any]) -> Bool {
+        guard PNAnimator.animatableProps.contains(prop), Thread.isMainThread else { return false }
+        let kind = PNProps.string(spec["kind"]) ?? ""
+        let entry = Running(view: view, prop: prop)
+        switch kind {
+        case "timing", "spring":
+            guard spec["to"] != nil else { return false }
+            if let from = spec["from"] { applyValue(view: view, prop: prop, value: from) }
+            let timing = PNAnimator.timingParameters(kind: kind, spec: spec)
+            let animator = UIViewPropertyAnimator(duration: timing.duration, timingParameters: timing.parameters)
+            animator.isUserInteractionEnabled = true
+            animator.addAnimations { [weak self, weak view] in
+                guard let self = self, let view = view else { return }
+                self.applyValue(view: view, prop: prop, value: spec["to"])
+            }
+            animator.addCompletion { [weak self] position in
+                guard let self = self, self.running[id] != nil else { return }
+                self.running.removeValue(forKey: id)
+                PNAnimator.reportCompletion(id: id, finished: position == .end)
+            }
+            entry.animator = animator
+            running[id] = entry
+            let delay = max(0, (PNProps.double(spec["delay_ms"]) ?? 0) / 1000)
+            animator.startAnimation(afterDelay: delay)
+            return true
+        case "decay":
+            guard let from = PNProps.double(spec["from"]), let velocity = PNProps.double(spec["velocity"]) else { return false }
+            let deceleration = max(1e-6, PNProps.double(spec["deceleration"]) ?? 0.997)
+            let driver = PNDecayDriver(from: from, velocity: velocity, deceleration: deceleration) { [weak self, weak view] value in
+                guard let self = self, let view = view else { return }
+                self.applyValue(view: view, prop: prop, value: value)
+            } completion: { [weak self] in
+                guard let self = self, self.running[id] != nil else { return }
+                self.running.removeValue(forKey: id)
+                PNAnimator.reportCompletion(id: id, finished: true)
+            }
+            entry.decay = driver
+            running[id] = entry
+            driver.start()
+            return true
+        default:
+            return false
+        }
+    }
+
+    /// Stop animation `id`, leaving the view at its presentation value.
+    /// Returns that value (or `nil` when the animation isn't running).
+    public func cancel(id: Int64) -> Any? {
+        guard let entry = running.removeValue(forKey: id) else { return nil }
+        var value: Any?
+        if let view = entry.view {
+            value = presentationValue(view: view, prop: entry.prop)
+        }
+        if let animator = entry.animator {
+            animator.stopAnimation(true)
+        }
+        if let decay = entry.decay {
+            value = decay.currentValue
+            decay.stop()
+        }
+        if let view = entry.view, let value = value {
+            view.layer.removeAllAnimations()
+            applyValue(view: view, prop: entry.prop, value: value)
+        }
+        return value
+    }
+
+    /// Drop bookkeeping for animations targeting `view` (on destroy).
+    public func forget(view: UIView) {
+        for (id, entry) in running where entry.view === view || entry.view == nil {
+            entry.animator?.stopAnimation(true)
+            entry.decay?.stop()
+            running.removeValue(forKey: id)
+        }
+    }
+
+    // MARK: - Helpers
+
+    static func reportCompletion(id: Int64, finished: Bool) {
+        PNBridge.shared.callPython(kind: "animation", tag: 0, name: "", payload: PNJSON.encode(["id": id, "finished": finished]))
+    }
+
+    /// Resolve `timing` / `spring` specs to UIKit timing parameters.
+    static func timingParameters(kind: String, spec: [String: Any]) -> (duration: TimeInterval, parameters: UITimingCurveProvider) {
+        if kind == "spring" {
+            let stiffness = max(1e-3, PNProps.double(spec["stiffness"]) ?? 100)
+            let damping = max(1e-3, PNProps.double(spec["damping"]) ?? 10)
+            let mass = max(1e-3, PNProps.double(spec["mass"]) ?? 1)
+            let omega0 = sqrt(stiffness / mass)
+            let zeta = damping / (2 * sqrt(stiffness * mass))
+            let duration = zeta < 1 ? min(10, max(0.15, 4 / max(0.05, zeta * omega0))) : min(10, max(0.15, 4 / omega0))
+            let distance = abs((PNProps.double(spec["to"]) ?? 0) - (PNProps.double(spec["from"]) ?? 0))
+            let v0 = PNProps.double(spec["initial_velocity"]) ?? 0
+            let normalized = distance > 1e-9 ? v0 / distance : 0
+            let parameters = UISpringTimingParameters(
+                mass: CGFloat(mass), stiffness: CGFloat(stiffness), damping: CGFloat(damping),
+                initialVelocity: CGVector(dx: normalized, dy: normalized)
+            )
+            return (duration, parameters)
+        }
+        let duration = max(0, (PNProps.double(spec["duration_ms"]) ?? 300) / 1000)
+        return (duration, curve(for: spec["easing"]))
+    }
+
+    /// Map an easing name (or `[x1, y1, x2, y2]` control points) to a timing curve.
+    static func curve(for easing: Any?) -> UITimingCurveProvider {
+        if let points = easing as? [Any], points.count == 4 {
+            let values = points.compactMap { PNProps.double($0) }
+            if values.count == 4 {
+                return UICubicTimingParameters(
+                    controlPoint1: CGPoint(x: values[0], y: values[1]), controlPoint2: CGPoint(x: values[2], y: values[3])
+                )
+            }
+        }
+        switch PNProps.string(easing) ?? "ease_in_out" {
+        case "linear": return UICubicTimingParameters(animationCurve: .linear)
+        case "ease_in", "ease_in_quad": return UICubicTimingParameters(animationCurve: .easeIn)
+        case "ease_out", "ease_out_quad": return UICubicTimingParameters(animationCurve: .easeOut)
+        case "ease", "ease_in_out": return UICubicTimingParameters(animationCurve: .easeInOut)
+        case "bounce":
+            // No CoreAnimation equivalent; approximate with an overshoot curve.
+            return UICubicTimingParameters(controlPoint1: CGPoint(x: 0.34, y: 1.56), controlPoint2: CGPoint(x: 0.64, y: 1))
+        default: return UICubicTimingParameters(animationCurve: .easeInOut)
+        }
+    }
+}
+
+/// Integrates the `decay` model on a `CADisplayLink`, mirroring the
+/// Python ticker: `v(t) = v0 * e^(-k * 1000 * t)` with `t` in seconds and
+/// `v0` in units per second, so the closed-form position is
+/// `from + v0 / (k * 1000) * (1 - e^(-k * 1000 * t))`.
+final class PNDecayDriver {
+    private(set) var currentValue: Double
+    private let from: Double
+    private let velocity0: Double
+    private let k: Double
+    private let frame: (Double) -> Void
+    private let completion: () -> Void
+    private var link: CADisplayLink?
+    private var startTime: CFTimeInterval = 0
+    private let restVelocity = 0.001
+
+    init(from: Double, velocity: Double, deceleration: Double, frame: @escaping (Double) -> Void, completion: @escaping () -> Void) {
+        self.from = from
+        currentValue = from
+        velocity0 = velocity
+        k = deceleration
+        self.frame = frame
+        self.completion = completion
+    }
+
+    func start() {
+        startTime = CACurrentMediaTime()
+        if abs(velocity0) < restVelocity {
+            completion()
+            return
+        }
+        let link = CADisplayLink(target: self, selector: #selector(tick(_:)))
+        link.add(to: .main, forMode: .common)
+        self.link = link
+    }
+
+    func stop() {
+        link?.invalidate()
+        link = nil
+    }
+
+    @objc private func tick(_ link: CADisplayLink) {
+        let elapsed = max(0, link.targetTimestamp - startTime)
+        let decayFactor = exp(-k * 1000 * elapsed)
+        let velocity = velocity0 * decayFactor
+        currentValue = from + velocity0 / (k * 1000) * (1 - decayFactor)
+        frame(currentValue)
+        if abs(velocity) < restVelocity {
+            stop()
+            completion()
+        }
+    }
+}

pythonnative/native/ios/Sources/PythonNativeKit/Bridge/PNBridge.swift

@@ -0,0 +1,255 @@
+import Foundation
+import UIKit
+
+/// The version of the wire protocol compiled into this library. Python
+/// refuses to start when `pythonnative.bridge.PROTOCOL_VERSION` differs.
+public let PNProtocolVersion: Int32 = 2
+
+/// The C signature Python registers through `pn_bridge_set_callback`.
+///
+/// `(kind, tag, name, payload_json) -> optional JSON string owned by
+/// Python and valid until the next callback returns`.
+public typealias PNCallbackFn = @convention(c) (
+    UnsafePointer<CChar>?, Int64, UnsafePointer<CChar>?, UnsafePointer<CChar>?
+) -> UnsafePointer<CChar>?
+
+/// Swift-side entry point for the reverse direction (native -> Python) and
+/// the owner of the registered C callback.
+public final class PNBridge {
+    public static let shared = PNBridge()
+
+    private let pythonQueue = DispatchQueue(label: "dev.pythonnative.events")
+    private struct Message {
+        let kind: String; let tag: Int64; let name: String; let payload: String
+        var continuous: Bool {
+            guard kind == "event" else { return false }
+            if ["on_scroll", "on_selection_change", "on_gesture_update"].contains(name) { return true }
+            if name.hasPrefix("gesture:"), let args = PNJSON.decodeObject(payload)["args"] as? [[String: Any]] {
+                return args.first?["state"] as? String == "changed"
+            }
+            return false
+        }
+    }
+    private let mailboxLock = NSLock()
+    private var mailbox: [Message] = []
+    private var draining = false
+    private var callback: PNCallbackFn?
+    private var registrationWaiters: [() -> Void] = []
+
+    private init() {
+        // Reference every exported entry point so the linker never
+        // dead-strips them out of the host executable; Python resolves
+        // them through `dlsym` at runtime.
+        _ = PNBridge.exportedSymbols
+    }
+
+    /// Whether Python has registered its callback yet.
+    public var hasCallback: Bool { callback != nil }
+
+    /// Install (or clear) the Python callback. Runs any pending
+    /// `whenCallbackRegistered` blocks when a callback becomes available.
+    public func setCallback(_ fn: PNCallbackFn?) {
+        callback = fn
+        guard fn != nil else { return }
+        let waiters = registrationWaiters
+        registrationWaiters = []
+        for waiter in waiters { waiter() }
+    }
+
+    /// Run `block` immediately if the callback is registered, otherwise
+    /// once it is. Used to buffer deep links and other early events.
+    public func whenCallbackRegistered(_ block: @escaping () -> Void) {
+        if callback != nil {
+            block()
+        } else {
+            registrationWaiters.append(block)
+        }
+    }
+
+    /// Invoke the Python callback. Returns the JSON string Python returned
+    /// (copied immediately), or `nil` when Python returned NULL or no
+    /// callback is registered.
+    @discardableResult
+    public func callPython(kind: String, tag: Int64, name: String, payload: String) -> String? {
+        let message = Message(kind: kind, tag: tag, name: name, payload: payload)
+        mailboxLock.lock()
+        if message.continuous, let last = mailbox.last, last.continuous,
+           last.tag == tag, last.name == name {
+            mailbox[mailbox.count - 1] = message
+        } else { mailbox.append(message) }
+        let schedule = !draining
+        draining = true
+        mailboxLock.unlock()
+        if schedule { pythonQueue.async { [self] in drainMailbox() } }
+        return nil
+    }
+
+    private func drainMailbox() {
+        while true {
+            mailboxLock.lock()
+            if mailbox.isEmpty { draining = false; mailboxLock.unlock(); return }
+            let message = mailbox.removeFirst()
+            mailboxLock.unlock()
+            guard let callback = callback else { continue }
+            message.kind.withCString { kind in
+                message.name.withCString { name in
+                    message.payload.withCString { payload in
+                        _ = callback(kind, message.tag, name, payload)
+                    }
+                }
+            }
+        }
+    }
+
+    static func onUI<T>(_ body: () -> T) -> T {
+        if Thread.isMainThread { return body() }
+        return DispatchQueue.main.sync(execute: body)
+    }
+
+    /// Emit a view event: `callback("event", tag, name, args_array_json)`.
+    @discardableResult
+    public func emitEvent(tag: Int64, name: String, args: [Any?]) -> String? {
+        PNAnimationGraph.event(tag, name, args)
+        var editRevision = 0
+        if name == "on_change", let view = PNViewRegistry.shared.view(for: tag),
+           view is UITextInput, let state = PNViewState.existing(for: view) {
+            editRevision = (state.extras["edit_revision"] as? Int ?? 0) + 1
+            state.extras["edit_revision"] = editRevision
+        }
+        return callPython(kind: "event", tag: tag, name: name, payload: PNCommit.event(args, editRevision: editRevision))
+    }
+
+    /// Log when an entry point is reached off the main thread. Python
+    /// always calls from the main thread, so this only guards misuse.
+    static func ensureMainThread(_ context: String) {
+        if !Thread.isMainThread {
+            PNLog.rateLimited(PNLog.bridge, key: "off-main:\(context)", "\(context) called off the main thread; running inline")
+        }
+    }
+
+    /// Copy a Swift string into a `strdup`'d buffer Python frees via `pn_bridge_free`.
+    static func duplicate(_ string: String?) -> UnsafeMutablePointer<CChar>? {
+        guard let string = string else { return nil }
+        return strdup(string)
+    }
+
+    private static let exportedSymbols: [Any] = [
+        pn_bridge_apply as Any,
+        pn_bridge_measure as Any,
+        pn_bridge_command as Any,
+        pn_bridge_animate as Any,
+        pn_bridge_call as Any,
+        pn_bridge_free as Any,
+        pn_bridge_set_callback as Any,
+        pn_bridge_protocol_version as Any,
+    ]
+}
+
+// MARK: - C exports
+
+/// Apply one serialized transaction (a JSON array of ops).
+@_cdecl("pn_bridge_apply")
+public func pn_bridge_apply(_ transactionJSON: UnsafePointer<CChar>?) -> UnsafeMutablePointer<CChar>? {
+    guard let transactionJSON = transactionJSON else { return nil }
+    let json = String(cString: transactionJSON)
+    return PNBridge.onUI { PNBridge.duplicate(PNCommit.apply(json)) }
+}
+
+/// Measure the view with `tag` under the given constraints (`1e6` means unconstrained).
+@_cdecl("pn_bridge_measure")
+public func pn_bridge_measure(
+    _ tag: Int64, _ maxW: Double, _ maxH: Double,
+    _ outW: UnsafeMutablePointer<Double>?, _ outH: UnsafeMutablePointer<Double>?
+) {
+    PNBridge.onUI {
+
+    PNBridge.ensureMainThread("pn_bridge_measure")
+    var size = CGSize.zero
+    if let record = PNViewRegistry.shared.resolve(tag) {
+        size = record.manager.measure(view: record.view, maxW: CGFloat(maxW), maxH: CGFloat(maxH))
+    }
+    outW?.pointee = size.width.isFinite ? Double(size.width) : 0
+    outH?.pointee = size.height.isFinite ? Double(size.height) : 0
+    }
+}
+
+/// Run an imperative command on one view; returns an optional JSON result.
+@_cdecl("pn_bridge_command")
+public func pn_bridge_command(
+    _ tag: Int64, _ name: UnsafePointer<CChar>?, _ argsJSON: UnsafePointer<CChar>?
+) -> UnsafeMutablePointer<CChar>? {
+    return PNBridge.onUI {
+
+    PNBridge.ensureMainThread("pn_bridge_command")
+    guard let name = name, let record = PNViewRegistry.shared.resolve(tag) else { return nil }
+    let args = PNJSON.decodeObject(argsJSON.map { String(cString: $0) })
+    let result = record.manager.command(view: record.view, name: String(cString: name), args: args)
+    guard let result = result else { return nil }
+    return PNBridge.duplicate(PNJSON.encode(result))
+    }
+}
+
+/// Drive a view's animatable properties (`set` / `start` / `cancel`).
+@_cdecl("pn_bridge_animate")
+public func pn_bridge_animate(
+    _ tag: Int64, _ requestJSON: UnsafePointer<CChar>?
+) -> UnsafeMutablePointer<CChar>? {
+    return PNBridge.onUI {
+
+    PNBridge.ensureMainThread("pn_bridge_animate")
+    let request = PNJSON.decodeObject(requestJSON.map { String(cString: $0) })
+    let result = PNAnimator.shared.handle(tag: tag, request: request)
+    guard let result = result else { return nil }
+    return PNBridge.duplicate(PNJSON.encode(result))
+    }
+}
+
+/// Call a native module method. The result is `{"ok":..}`, `{"pending":true}`, or an error envelope.
+@_cdecl("pn_bridge_call")
+public func pn_bridge_call(
+    _ module: UnsafePointer<CChar>?, _ method: UnsafePointer<CChar>?, _ argsJSON: UnsafePointer<CChar>?
+) -> UnsafeMutablePointer<CChar>? {
+    return PNBridge.onUI {
+
+    PNBridge.ensureMainThread("pn_bridge_call")
+    guard let module = module, let method = method else {
+        return PNBridge.duplicate(PNJSON.encode(["ok": false, "error": "missing module or method"]))
+    }
+    let envelope = PNJSON.decodeObject(argsJSON.map { String(cString: $0) })
+    if String(cString: module) == "Runtime" {
+        return PNBridge.duplicate(PNJSON.encode(["ok": true, "value": [
+            "protocol": 2, "yoga": "3.2.1", "schema": PNContracts.fingerprint,
+            "animation_graph": true, "logical_lists": true, "native_layout": true]]))
+    }
+    if String(cString: module) == "Layout" {
+        return PNBridge.duplicate(PNJSON.encode(["ok": true, "value": PNLayout.compute(envelope["args"] as? [String: Any] ?? [:])]))
+    }
+    let result = PNModuleDispatcher.shared.call(
+        module: String(cString: module), method: String(cString: method), envelope: envelope
+    )
+    return PNBridge.duplicate(PNJSON.encode(result))
+    }
+}
+
+/// Free a string previously returned by a `pn_bridge_*` function.
+@_cdecl("pn_bridge_free")
+public func pn_bridge_free(_ ptr: UnsafeMutablePointer<CChar>?) {
+    free(ptr)
+}
+
+/// Register the Python callback used for every native -> Python message.
+@_cdecl("pn_bridge_set_callback")
+public func pn_bridge_set_callback(_ fn: PNCallbackFn?) {
+    PNBridge.onUI {
+
+    PNBridge.ensureMainThread("pn_bridge_set_callback")
+    PNRegistry.shared.ensureBuiltins()
+    PNBridge.shared.setCallback(fn)
+    }
+}
+
+/// The protocol version this library speaks.
+@_cdecl("pn_bridge_protocol_version")
+public func pn_bridge_protocol_version() -> Int32 {
+    PNProtocolVersion
+}

pythonnative/native/ios/Sources/PythonNativeKit/Bridge/PNCommit.swift

@@ -0,0 +1,104 @@
+import Foundation
+
+/// Validates complete surface transactions before invoking a view manager.
+enum PNCommit {
+    private static var application = ""
+    private static var surface = 0
+    private static var revision = 0
+    private static var parents: [Int64: Int64] = [:]
+    private static var live: Set<Int64> = []
+    private static var types: [Int64: String] = [:]
+    private static var failed = false
+
+    private static var sequence = 0
+    static func event(_ args: [Any?], editRevision: Int = 0) -> String {
+        sequence += 1
+        return PNJSON.encode(["application": application, "surface": surface,
+                              "revision": revision, "sequence": sequence, "args": args, "edit_revision": editRevision])
+    }
+
+    static func apply(_ json: String) -> String {
+        let envelope = PNJSON.decodeObject(json)
+        let app = envelope["application"] as? String ?? ""
+        let target = envelope["surface"] as? Int ?? 0
+        let next = envelope["revision"] as? Int ?? 0
+        func error(_ message: String) -> String {
+            PNJSON.encode(["ok": false, "application": app, "surface": target,
+                           "revision": next, "error": message])
+        }
+        guard envelope["version"] as? Int == 2, !app.isEmpty, target > 0,
+              let raw = envelope["ops"] as? [[Any]] else { return error("invalid v2 envelope") }
+        let replacing = app != application
+        guard next == (replacing ? 1 : revision + 1), replacing || (!failed && target == surface)
+        else { return error("stale revision or failed surface") }
+        var tags: Set<Int64> = replacing ? [] : live
+        var links: [Int64: Int64] = replacing ? [:] : parents
+        var names: [Int64: String] = replacing ? [:] : types
+        var decoded: [PNTransaction.Op] = []
+        do {
+            for (index, parts) in raw.enumerated() {
+                guard let code = parts.first as? String,
+                      parts.count == ["c": 4, "u": 3, "i": 4, "d": 2, "f": 6][code],
+                      let number = parts[1] as? NSNumber, number.doubleValue > 0,
+                      number.doubleValue.rounded() == number.doubleValue else {
+                    throw PNTransaction.DecodeError.malformedOp(index: index)
+                }
+                let tag = number.int64Value
+                if code == "c" {
+                    guard !tags.contains(tag), let type = parts[2] as? String, !type.isEmpty,
+                          parts[3] is [String: Any] else { return error("invalid create") }
+                    guard PNRegistry.shared.componentNames.contains(type) else { return error("unknown component") }
+                    guard PNContracts.validate(type, parts[3] as! [String: Any]) else { return error("invalid typed props") }
+                    tags.insert(tag)
+                    names[tag] = type
+                } else {
+                    guard tags.contains(tag) else { return error("unknown tag") }
+                    if code == "u" {
+                        guard let props = parts[2] as? [String: Any] else { return error("invalid props") }
+                        if let type = names[tag], !PNContracts.validate(type, props, partial: true) { return error("invalid typed update") }
+                    }
+                    if code == "i" {
+                        guard let child = parts[2] as? Int64, tags.contains(child),
+                              let position = parts[3] as? Int, position >= 0 else { return error("invalid insertion") }
+                        var ancestor: Int64? = tag
+                        while let current = ancestor {
+                            if current == child { return error("cycle") }
+                            ancestor = links[current]
+                        }
+                        let siblings = links.filter { $0.value == tag && $0.key != child }.count
+                        guard position <= siblings else { return error("insertion index exceeds child count") }
+                        links[child] = tag
+                    }
+                    if code == "d" {
+                        guard !links.values.contains(tag) else { return error("destroy children first") }
+                        tags.remove(tag)
+                        names.removeValue(forKey: tag)
+                        links.removeValue(forKey: tag)
+                    }
+                    if code == "f" {
+                        for value in parts[2...] {
+                            guard let number = value as? NSNumber, number.doubleValue.isFinite else { return error("invalid frame") }
+                        }
+                        guard (parts[4] as! NSNumber).doubleValue >= 0,
+                              (parts[5] as! NSNumber).doubleValue >= 0 else { return error("negative size") }
+                    }
+                }
+                decoded.append(try PNTransaction.decodeOp(parts, index: index))
+            }
+        } catch { return PNJSON.encode(["ok": false, "error": String(describing: error)]) }
+        if replacing {
+            for tag in live { PNTransaction.apply([.destroy(tag: tag)]) }
+            PNLayout.reset()
+        }
+        PNTransaction.apply(decoded)
+        PNLayout.observe(decoded)
+        application = app
+        surface = target
+        revision = next
+        live = tags
+        types = names
+        parents = links
+        failed = false
+        return PNJSON.encode(["ok": true, "application": app, "surface": target, "revision": next])
+    }
+}