pythonnative 0.36.0__py3-none-any.whl → 0.37.0__py3-none-any.whl

pythonnative/templates/ios_template/PythonNativeKit/Sources/PythonNativeKit/Components/PNWebViewManager.swift

@@ -0,0 +1,124 @@
+import UIKit
+import WebKit
+
+/// `WebView`: `WKWebView` with navigation and script-message delegates.
+///
+/// Page JavaScript reaches `on_message` through
+/// `window.webkit.messageHandlers.pythonnative.postMessage(value)`.
+public final class PNWebViewManager: PNComponentManager {
+    public override func makeView(props: [String: Any]) -> UIView {
+        let configuration = WKWebViewConfiguration()
+        let delegate = PNWebViewDelegate()
+        configuration.userContentController.add(delegate, name: "pythonnative")
+        let webView = WKWebView(frame: .zero, configuration: configuration)
+        webView.navigationDelegate = delegate
+        delegate.webView = webView
+        pendingDelegates[ObjectIdentifier(webView)] = delegate
+        return webView
+    }
+
+    private var pendingDelegates: [ObjectIdentifier: PNWebViewDelegate] = [:]
+
+    public override func createView(tag: Int64, props: [String: Any]) -> UIView {
+        let view = super.createView(tag: tag, props: props)
+        if let delegate = pendingDelegates.removeValue(forKey: ObjectIdentifier(view)) {
+            PNViewState.existing(for: view)?.retained.append(delegate)
+            delegate.injectJavaScript = PNProps.string(PNProps.value(props, "inject_javascript"))
+        }
+        return view
+    }
+
+    public override func teardown(view: UIView) {
+        guard let webView = view as? WKWebView else { return }
+        webView.configuration.userContentController.removeScriptMessageHandler(forName: "pythonnative")
+        webView.navigationDelegate = nil
+        webView.stopLoading()
+    }
+
+    public override func apply(view: UIView, props: [String: Any], initial: Bool) {
+        guard let webView = view as? WKWebView else { return }
+        if PNProps.has(props, "inject_javascript"),
+           let delegate = PNViewState.existing(for: webView)?.retained.compactMap({ $0 as? PNWebViewDelegate }).first
+        {
+            delegate.injectJavaScript = PNProps.string(PNProps.value(props, "inject_javascript"))
+        }
+        if let html = PNProps.string(PNProps.value(props, "html")), !html.isEmpty {
+            let base = PNProps.string(PNProps.value(mergedProps(webView), "base_url")).flatMap { URL(string: $0) }
+            webView.loadHTMLString(html, baseURL: base)
+        } else if let url = PNProps.string(PNProps.value(props, "url")), !url.isEmpty, let target = URL(string: url) {
+            webView.load(URLRequest(url: target))
+        }
+        if PNProps.has(props, "scroll_enabled") {
+            webView.scrollView.isScrollEnabled = PNProps.bool(PNProps.value(props, "scroll_enabled")) ?? true
+        }
+        if PNProps.has(props, "allows_back_forward_gestures") {
+            webView.allowsBackForwardNavigationGestures = PNProps.bool(PNProps.value(props, "allows_back_forward_gestures")) ?? false
+        }
+        PNViewStyler.applyCommon(webView, props)
+    }
+
+    public override func command(view: UIView, name: String, args: [String: Any]) -> Any? {
+        guard let webView = view as? WKWebView else { return nil }
+        switch name {
+        case "eval_js", "inject_javascript":
+            webView.evaluateJavaScript(PNProps.string(args["source"]) ?? PNProps.string(args["script"]) ?? "") { _, _ in }
+        case "reload": webView.reload()
+        case "go_back": webView.goBack()
+        case "go_forward": webView.goForward()
+        case "stop_loading": webView.stopLoading()
+        case "load_url":
+            if let url = PNProps.string(args["url"]).flatMap({ URL(string: $0) }) { webView.load(URLRequest(url: url)) }
+        case "get_url":
+            return webView.url?.absoluteString ?? ""
+        case "can_go_back":
+            return webView.canGoBack
+        case "can_go_forward":
+            return webView.canGoForward
+        default:
+            break
+        }
+        return nil
+    }
+}
+
+/// `WKNavigationDelegate` + `WKScriptMessageHandler` bridge.
+final class PNWebViewDelegate: NSObject, WKNavigationDelegate, WKScriptMessageHandler {
+    weak var webView: WKWebView?
+    var injectJavaScript: String?
+
+    private func currentURL() -> String {
+        webView?.url?.absoluteString ?? ""
+    }
+
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        if let js = injectJavaScript, !js.isEmpty {
+            webView.evaluateJavaScript(js) { _, _ in }
+        }
+        PNEvents.emit(webView, "on_load", [currentURL()])
+        PNEvents.emitIfWired(webView, "on_navigation_state_change", [["url": currentURL(), "loading": false, "can_go_back": webView.canGoBack, "can_go_forward": webView.canGoForward, "title": webView.title ?? ""]])
+    }
+
+    func webView(_ webView: WKWebView, didStartProvisionalNavigation navigation: WKNavigation!) {
+        PNEvents.emitIfWired(webView, "on_load_start", [currentURL()])
+        PNEvents.emitIfWired(webView, "on_navigation_state_change", [["url": currentURL(), "loading": true, "can_go_back": webView.canGoBack, "can_go_forward": webView.canGoForward, "title": webView.title ?? ""]])
+    }
+
+    func webView(_ webView: WKWebView, didFail navigation: WKNavigation!, withError error: Error) {
+        PNEvents.emit(webView, "on_error", [error.localizedDescription])
+    }
+
+    func webView(_ webView: WKWebView, didFailProvisionalNavigation navigation: WKNavigation!, withError error: Error) {
+        PNEvents.emit(webView, "on_error", [error.localizedDescription])
+    }
+
+    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+        guard let webView = webView else { return }
+        let body: String
+        if let text = message.body as? String {
+            body = text
+        } else {
+            body = PNJSON.encode(message.body)
+        }
+        PNEvents.emit(webView, "on_message", [body])
+    }
+}

pythonnative/templates/ios_template/PythonNativeKit/Sources/PythonNativeKit/Gestures/PNGestureCoordinator.swift

@@ -0,0 +1,260 @@
+import UIKit
+
+/// Installs `UIGestureRecognizer`s from the `gestures` prop and emits
+/// `gesture:<index>` events with the payload dict Python's
+/// `GestureEvent` expects.
+///
+/// Spec fields:
+/// - `kind`: `tap`, `long_press`, `pan`, `swipe`, `fling`, `pinch`, `rotation`
+/// - per-kind config (`n_taps`, `max_distance`, `min_duration_ms`,
+///   `min_distance`, `direction`, `n_pointers`, `min_velocity`)
+/// - `simultaneous`: indices allowed to recognize together
+/// - `wait_for`: indices that must fail before this one may begin
+public final class PNGestureCoordinator: NSObject, UIGestureRecognizerDelegate {
+    public static let shared = PNGestureCoordinator()
+
+    /// Bookkeeping for one installed recognizer.
+    final class Entry {
+        let index: Int
+        let kind: String
+        var simultaneous: Set<Int>
+        var minVelocity: CGFloat
+        var direction: String
+        var lastLocation: CGPoint = .zero
+
+        init(index: Int, kind: String, simultaneous: Set<Int>, minVelocity: CGFloat, direction: String) {
+            self.index = index
+            self.kind = kind
+            self.simultaneous = simultaneous
+            self.minVelocity = minVelocity
+            self.direction = direction
+        }
+    }
+
+    private var entries: [ObjectIdentifier: Entry] = [:]
+
+    private override init() {
+        super.init()
+    }
+
+    // MARK: - Wiring
+
+    /// Replace the recognizers on `view` with the ones described by `specs`.
+    public func wire(view: UIView, specs: Any?) {
+        unwire(view: view)
+        guard let state = PNViewState.existing(for: view) else { return }
+        let list = ((specs as? [Any]) ?? []).map { ($0 as? [String: Any]) ?? [:] }
+        guard !list.isEmpty else { return }
+        // A spec may own several recognizers (an any-direction swipe is
+        // one `UISwipeGestureRecognizer` per direction), so relationships
+        // are wired spec-to-spec across every recognizer on each side.
+        var built: [Int: [UIGestureRecognizer]] = [:]
+        for (index, spec) in list.enumerated() {
+            let recognizers = makeRecognizers(spec)
+            if recognizers.isEmpty {
+                PNLog.once(PNLog.gestures, key: "kind:\(PNProps.string(spec["kind"]) ?? "")", "unsupported gesture kind '\(PNProps.string(spec["kind"]) ?? "")'")
+                continue
+            }
+            for (recognizer, direction) in recognizers {
+                let entry = Entry(
+                    index: index,
+                    kind: PNProps.string(spec["kind"]) ?? "",
+                    simultaneous: Set(((spec["simultaneous"] as? [Any]) ?? []).compactMap { PNProps.int($0) }),
+                    minVelocity: CGFloat(PNProps.double(spec["min_velocity"]) ?? 300),
+                    direction: direction ?? PNProps.string(spec["direction"]) ?? "any"
+                )
+                entries[ObjectIdentifier(recognizer)] = entry
+                recognizer.delegate = self
+                recognizer.cancelsTouchesInView = false
+                recognizer.addTarget(self, action: #selector(handle(_:)))
+                view.addGestureRecognizer(recognizer)
+                state.gestureRecognizers.append(recognizer)
+                built[index, default: []].append(recognizer)
+            }
+        }
+        for (index, spec) in list.enumerated() {
+            guard let recognizers = built[index] else { continue }
+            for wait in ((spec["wait_for"] as? [Any]) ?? []).compactMap({ PNProps.int($0) }) {
+                guard wait != index, let others = built[wait] else { continue }
+                for recognizer in recognizers {
+                    for other in others {
+                        recognizer.require(toFail: other)
+                    }
+                }
+            }
+        }
+        view.isUserInteractionEnabled = true
+    }
+
+    /// Remove every recognizer previously installed on `view`.
+    public func unwire(view: UIView) {
+        guard let state = PNViewState.existing(for: view) else { return }
+        for recognizer in state.gestureRecognizers {
+            recognizer.removeTarget(self, action: nil)
+            view.removeGestureRecognizer(recognizer)
+            entries.removeValue(forKey: ObjectIdentifier(recognizer))
+        }
+        state.gestureRecognizers = []
+    }
+
+    // MARK: - Recognizer construction
+
+    /// Build the recognizer(s) for one spec as `(recognizer, direction)`
+    /// pairs. `direction` is set only for swipe / fling recognizers: a
+    /// `UISwipeGestureRecognizer` reports its configured mask rather than
+    /// the direction it resolved, so `direction = "any"` installs one
+    /// recognizer per direction and tags each with its own name.
+    func makeRecognizers(_ spec: [String: Any]) -> [(UIGestureRecognizer, String?)] {
+        switch PNProps.string(spec["kind"]) ?? "" {
+        case "tap":
+            let tap = UITapGestureRecognizer()
+            tap.numberOfTapsRequired = max(1, PNProps.int(spec["n_taps"]) ?? 1)
+            return [(tap, nil)]
+        case "long_press":
+            let press = UILongPressGestureRecognizer()
+            press.minimumPressDuration = max(0.01, (PNProps.double(spec["min_duration_ms"]) ?? 500) / 1000)
+            press.allowableMovement = CGFloat(PNProps.double(spec["max_distance"]) ?? 12)
+            return [(press, nil)]
+        case "pan":
+            return [(PNPanGestureRecognizer(minDistance: CGFloat(PNProps.double(spec["min_distance"]) ?? 10)), nil)]
+        case "swipe", "fling":
+            let requested = PNProps.string(spec["direction"]) ?? "any"
+            let directions = PNGestureCoordinator.swipeDirectionNames.contains(requested)
+                ? [requested]
+                : PNGestureCoordinator.swipeDirectionNames
+            let touches = max(1, PNProps.int(spec["n_pointers"]) ?? 1)
+            return directions.map { name in
+                let swipe = UISwipeGestureRecognizer()
+                swipe.direction = PNGestureCoordinator.swipeDirection(name)
+                swipe.numberOfTouchesRequired = touches
+                return (swipe, name)
+            }
+        case "pinch":
+            return [(UIPinchGestureRecognizer(), nil)]
+        case "rotation":
+            return [(UIRotationGestureRecognizer(), nil)]
+        default:
+            return []
+        }
+    }
+
+    /// The single-direction names a swipe spec may request.
+    public static let swipeDirectionNames = ["left", "right", "up", "down"]
+
+    /// Map a Python direction name to `UISwipeGestureRecognizer.Direction`.
+    public static func swipeDirection(_ name: String) -> UISwipeGestureRecognizer.Direction {
+        switch name {
+        case "left": return .left
+        case "right": return .right
+        case "up": return .up
+        case "down": return .down
+        default: return [.left, .right, .up, .down]
+        }
+    }
+
+    // MARK: - Relationship lookups (exposed for tests)
+
+    /// The spec index recorded for `recognizer`, if it was installed by the coordinator.
+    public func index(of recognizer: UIGestureRecognizer) -> Int? {
+        entries[ObjectIdentifier(recognizer)]?.index
+    }
+
+    /// Whether the two recognizers are allowed to recognize together.
+    public func allowsSimultaneous(_ a: UIGestureRecognizer, _ b: UIGestureRecognizer) -> Bool {
+        guard let ea = entries[ObjectIdentifier(a)], let eb = entries[ObjectIdentifier(b)] else {
+            // One side isn't ours (Pressable, scroll view): don't block it.
+            return true
+        }
+        if a.view !== b.view { return true }
+        return ea.simultaneous.contains(eb.index) || eb.simultaneous.contains(ea.index)
+    }
+
+    // MARK: - UIGestureRecognizerDelegate
+
+    public func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer, shouldRecognizeSimultaneouslyWith other: UIGestureRecognizer) -> Bool {
+        allowsSimultaneous(gestureRecognizer, other)
+    }
+
+    // MARK: - Emission
+
+    @objc private func handle(_ recognizer: UIGestureRecognizer) {
+        guard let view = recognizer.view, let entry = entries[ObjectIdentifier(recognizer)] else { return }
+        let location = recognizer.location(in: view)
+        var payload: [String: Any] = [
+            "kind": entry.kind,
+            "x": Double(location.x),
+            "y": Double(location.y),
+            "translation_x": 0.0,
+            "translation_y": 0.0,
+            "velocity_x": 0.0,
+            "velocity_y": 0.0,
+            "scale": 1.0,
+            "rotation": 0.0,
+            "pointer_count": recognizer.numberOfTouches,
+            "direction": NSNull(),
+        ]
+        var state = PNGestureCoordinator.stateName(recognizer.state)
+        switch recognizer {
+        case let pan as UIPanGestureRecognizer:
+            let translation = pan.translation(in: view)
+            let velocity = pan.velocity(in: view)
+            payload["translation_x"] = Double(translation.x)
+            payload["translation_y"] = Double(translation.y)
+            payload["velocity_x"] = Double(velocity.x)
+            payload["velocity_y"] = Double(velocity.y)
+        case let pinch as UIPinchGestureRecognizer:
+            payload["scale"] = Double(pinch.scale)
+            payload["velocity_x"] = Double(pinch.velocity)
+        case let rotation as UIRotationGestureRecognizer:
+            payload["rotation"] = Double(rotation.rotation)
+            payload["velocity_x"] = Double(rotation.velocity)
+        case let swipe as UISwipeGestureRecognizer:
+            // UIKit reports swipes as a single `.ended`; Python expects `ended`.
+            guard swipe.state == .ended || swipe.state == .recognized else { return }
+            state = "ended"
+            payload["direction"] = entry.direction
+            payload["pointer_count"] = max(1, swipe.numberOfTouchesRequired)
+        case is UITapGestureRecognizer:
+            guard recognizer.state == .ended || recognizer.state == .recognized else { return }
+            state = "ended"
+        default:
+            break
+        }
+        guard state != "possible" else { return }
+        payload["state"] = state
+        PNEvents.emit(view, "gesture:\(entry.index)", [payload])
+    }
+
+    static func stateName(_ state: UIGestureRecognizer.State) -> String {
+        switch state {
+        case .began: return "began"
+        case .changed: return "changed"
+        case .ended: return "ended"
+        case .cancelled: return "cancelled"
+        case .failed: return "failed"
+        default: return "possible"
+        }
+    }
+
+    /// The direction name recorded for a swipe / fling recognizer (exposed for tests).
+    public func direction(of recognizer: UIGestureRecognizer) -> String? {
+        guard let entry = entries[ObjectIdentifier(recognizer)], entry.kind == "swipe" || entry.kind == "fling" else {
+            return nil
+        }
+        return entry.direction
+    }
+}
+
+/// A pan recognizer that records the Python `min_distance` threshold.
+///
+/// UIKit applies its own ~10 pt hysteresis before a pan begins, which
+/// matches the Python default; the value is kept for diagnostics and
+/// for future tuning rather than overriding UIKit's touch pipeline.
+final class PNPanGestureRecognizer: UIPanGestureRecognizer {
+    let minDistance: CGFloat
+
+    init(minDistance: CGFloat) {
+        self.minDistance = max(0, minDistance)
+        super.init(target: nil, action: nil)
+    }
+}

pythonnative/templates/ios_template/PythonNativeKit/Sources/PythonNativeKit/Modules/AlertModule.swift

@@ -0,0 +1,92 @@
+import UIKit
+
+/// Presents `UIAlertController`s from the top view controller.
+public enum PNAlertPresenter {
+    /// Show an alert or action sheet. `buttons` are
+    /// `{"label", "style": "default"|"cancel"|"destructive"}` dicts;
+    /// `completion` receives the tapped index, or `-1` on dismissal.
+    public static func present(
+        title: String?, message: String?, buttons: [[String: Any]], style: String,
+        completion: @escaping (Int) -> Void
+    ) {
+        guard let top = PNWindow.topViewController() else {
+            completion(-1)
+            return
+        }
+        let preferred: UIAlertController.Style = style == "action_sheet" ? .actionSheet : .alert
+        let alert = UIAlertController(title: title, message: message, preferredStyle: preferred)
+        var settled = false
+        let finish: (Int) -> Void = { index in
+            if settled { return }
+            settled = true
+            completion(index)
+        }
+        let list = buttons.isEmpty ? [["label": "OK"]] : buttons
+        for (index, button) in list.enumerated() {
+            let label = PNProps.string(button["label"]) ?? PNProps.string(button["title"]) ?? "OK"
+            let actionStyle: UIAlertAction.Style
+            switch PNProps.string(button["style"]) {
+            case "cancel": actionStyle = .cancel
+            case "destructive": actionStyle = .destructive
+            default: actionStyle = .default
+            }
+            alert.addAction(UIAlertAction(title: label, style: actionStyle) { _ in finish(index) })
+        }
+        if preferred == .actionSheet, let popover = alert.popoverPresentationController {
+            popover.sourceView = top.view
+            popover.sourceRect = CGRect(x: top.view.bounds.midX, y: top.view.bounds.maxY - 1, width: 1, height: 1)
+            popover.permittedArrowDirections = []
+        }
+        top.present(alert, animated: true)
+        // A sheet dismissed by tapping outside (iPad popover) never runs
+        // an action; report -1 once it disappears.
+        PNAlertDismissWatcher.watch(alert) { finish(-1) }
+    }
+}
+
+/// Observes an alert's disappearance to report an outside-tap dismissal.
+final class PNAlertDismissWatcher: NSObject, UIPopoverPresentationControllerDelegate {
+    private let onDismiss: () -> Void
+    private static var watchers: [ObjectIdentifier: PNAlertDismissWatcher] = [:]
+
+    private init(onDismiss: @escaping () -> Void) {
+        self.onDismiss = onDismiss
+    }
+
+    static func watch(_ alert: UIAlertController, onDismiss: @escaping () -> Void) {
+        let watcher = PNAlertDismissWatcher(onDismiss: onDismiss)
+        watchers[ObjectIdentifier(alert)] = watcher
+        alert.popoverPresentationController?.delegate = watcher
+    }
+
+    func presentationControllerDidDismiss(_ presentationController: UIPresentationController) {
+        onDismiss()
+        PNAlertDismissWatcher.watchers.removeValue(forKey: ObjectIdentifier(presentationController.presentedViewController))
+    }
+}
+
+/// `Alert`: `present` (async, resolves the tapped index) and `show` (fire-and-forget).
+public final class AlertModule: PNNativeModule {
+    public static let name = "Alert"
+
+    public init() {}
+
+    public func call(_ method: String, args: [String: Any], promise: PNPromise) {
+        switch method {
+        case "present", "show":
+            let buttons = ((args["buttons"] as? [Any]) ?? []).compactMap { $0 as? [String: Any] }
+            let fireAndForget = method == "show"
+            if fireAndForget { promise.resolve(nil) }
+            PNAlertPresenter.present(
+                title: PNProps.string(args["title"]),
+                message: PNProps.string(args["message"]),
+                buttons: buttons,
+                style: PNProps.string(args["style"]) ?? "alert"
+            ) { index in
+                if !fireAndForget { promise.resolve(index) }
+            }
+        default:
+            promise.reject("Alert has no method '\(method)'", code: "unknown_method")
+        }
+    }
+}

pythonnative/templates/ios_template/PythonNativeKit/Sources/PythonNativeKit/Modules/HostModule.swift

@@ -0,0 +1,158 @@
+import UIKit
+
+/// `Host`: screen root attachment, stack navigation, viewport queries,
+/// and the main-queue pump.
+public final class HostModule: PNNativeModule {
+    public static let name = "Host"
+
+    public init() {}
+
+    public func call(_ method: String, args: [String: Any], promise: PNPromise) {
+        switch method {
+        case "post":
+            DispatchQueue.main.async {
+                PNBridge.shared.callPython(kind: "pump", tag: 0, name: "", payload: "")
+            }
+            promise.resolve(nil)
+        case "is_main_thread":
+            promise.resolve(Thread.isMainThread)
+        case "attach_root":
+            guard let controller = screen(args, promise) else { return }
+            guard let tag = PNProps.int(args["tag"]), let view = PNViewRegistry.shared.view(for: Int64(tag)) else {
+                promise.reject("attach_root: unknown view tag", code: "unknown_tag")
+                return
+            }
+            controller.attachRoot(view)
+            promise.resolve(controller.viewport())
+        case "detach_root":
+            guard let controller = screen(args, promise) else { return }
+            if let tag = PNProps.int(args["tag"]), let view = PNViewRegistry.shared.view(for: Int64(tag)) {
+                controller.detachRoot(view)
+            }
+            promise.resolve(nil)
+        case "viewport":
+            guard let controller = screen(args, promise) else { return }
+            promise.resolve(controller.viewport())
+        case "set_options":
+            guard let controller = screen(args, promise) else { return }
+            HostModule.applyOptions(PNProps.dict(args["options"]) ?? [:], to: controller)
+            promise.resolve(nil)
+        case "push":
+            guard let controller = screen(args, promise) else { return }
+            let next = HostModule.makeScreen(args, from: controller)
+            promise.resolve(HostModule.runNavOp(controller) { nav in nav.pushViewController(next, animated: true) })
+        case "pop":
+            guard let controller = screen(args, promise) else { return }
+            let count = max(1, PNProps.int(args["count"]) ?? 1)
+            promise.resolve(HostModule.runNavOp(controller) { nav in
+                if count <= 1 {
+                    nav.popViewController(animated: true)
+                    return
+                }
+                let controllers = nav.viewControllers
+                let target = max(0, controllers.count - 1 - count)
+                nav.popToViewController(controllers[target], animated: true)
+            })
+        case "pop_to_root":
+            guard let controller = screen(args, promise) else { return }
+            promise.resolve(HostModule.runNavOp(controller) { nav in nav.popToRootViewController(animated: true) })
+        case "replace":
+            guard let controller = screen(args, promise) else { return }
+            let next = HostModule.makeScreen(args, from: controller)
+            promise.resolve(HostModule.runNavOp(controller) { nav in
+                var controllers = nav.viewControllers
+                if let index = controllers.firstIndex(where: { $0 === controller }) {
+                    controllers[index] = next
+                } else if controllers.isEmpty {
+                    controllers = [next]
+                } else {
+                    controllers[controllers.count - 1] = next
+                }
+                nav.setViewControllers(controllers, animated: true)
+            })
+        case "reset":
+            guard let controller = screen(args, promise) else { return }
+            let specs = ((args["screens"] as? [Any]) ?? []).compactMap { $0 as? [String: Any] }
+            let screens = specs.map { HostModule.makeScreen($0, from: controller) }
+            promise.resolve(HostModule.runNavOp(controller) { nav in
+                guard let root = nav.viewControllers.first else {
+                    nav.setViewControllers(screens, animated: true)
+                    return
+                }
+                nav.setViewControllers([root] + screens, animated: true)
+            })
+        default:
+            promise.reject("Host has no method '\(method)'", code: "unknown_method")
+        }
+    }
+
+    // MARK: - Helpers
+
+    private func screen(_ args: [String: Any], _ promise: PNPromise) -> PNViewController? {
+        guard let id = PNProps.int(args["screen"]) else {
+            promise.reject("missing 'screen' id", code: "bad_args")
+            return nil
+        }
+        guard let controller = PNScreenRegistry.shared.controller(for: Int64(id)) else {
+            promise.reject("no screen with id \(id)", code: "unknown_screen")
+            return nil
+        }
+        return controller
+    }
+
+    /// Build a sibling screen controller of the same class as `source`.
+    static func makeScreen(_ args: [String: Any], from source: PNViewController) -> PNViewController {
+        let next = type(of: source).init(nibName: nil, bundle: nil)
+        next.requestedScreenPath = PNProps.string(args["path"])
+        if let screenArgs = args["args"], !(screenArgs is NSNull) {
+            next.requestedScreenArgsJSON = (screenArgs as? String) ?? PNJSON.encode(screenArgs)
+        }
+        next.devRoot = source.devRoot
+        if let title = PNProps.string(args["title"]) {
+            next.title = title
+        }
+        if let options = PNProps.dict(args["options"]) {
+            applyOptions(options, to: next)
+        }
+        return next
+    }
+
+    static func applyOptions(_ options: [String: Any], to controller: UIViewController) {
+        if let title = PNProps.string(options["title"]) {
+            controller.title = title
+        }
+        if let hidden = PNProps.bool(options["header_shown"]) {
+            controller.navigationController?.setNavigationBarHidden(!hidden, animated: false)
+        }
+        if let hidesBack = PNProps.bool(options["hide_back_button"]) {
+            controller.navigationItem.hidesBackButton = hidesBack
+        }
+        if let color = PNColor.parse(options["header_tint_color"]) {
+            controller.navigationController?.navigationBar.tintColor = color
+        }
+        if let color = PNColor.parse(options["header_background_color"]) {
+            let appearance = UINavigationBarAppearance()
+            appearance.configureWithOpaqueBackground()
+            appearance.backgroundColor = color
+            controller.navigationItem.standardAppearance = appearance
+            controller.navigationItem.scrollEdgeAppearance = appearance
+        }
+    }
+
+    /// Run `op` on the controller's navigation stack unless a transition
+    /// is in flight (UIKit doesn't queue navigation calls). Returns
+    /// whether the op ran.
+    @discardableResult
+    static func runNavOp(_ controller: UIViewController, _ op: (UINavigationController) -> Void) -> Bool {
+        guard let nav = controller.navigationController else {
+            PNLog.screens.error("navigation requested but the screen is not inside a UINavigationController")
+            return false
+        }
+        if nav.transitionCoordinator != nil {
+            PNLog.rateLimited(PNLog.screens, key: "nav-inflight", "navigation op dropped: transition in flight")
+            return false
+        }
+        op(nav)
+        return true
+    }
+}