zixflow-reactnative 1.1.2 → 1.1.4

package/ios/wrappers/ZixflowReactNativeDeepLinkRequestStore.swift

@@ -0,0 +1,123 @@
+import Foundation
+
+struct ZixflowReactNativeDeepLinkRequestStore {
+    enum Acceptance: Equatable {
+        case buffered(UUID)
+        case linking(URL)
+        case handler(UUID, URL)
+    }
+
+    enum Resolution: Equatable {
+        case handled
+        case fallback(URL)
+    }
+
+    private enum DeliveryMode: Equatable {
+        case unavailable
+        case linking
+        case handler
+    }
+
+    private enum RequestState: Equatable {
+        case buffered
+        case awaitingAcknowledgement
+    }
+
+    private struct Request {
+        let id: UUID
+        let url: URL
+        var state: RequestState
+    }
+
+    private var isLinkingReady = false
+    private var requiresHandler = false
+    private var hasHandler = false
+    private var requests: [Request] = []
+
+    private var deliveryMode: DeliveryMode {
+        if hasHandler {
+            return .handler
+        }
+        if !requiresHandler, isLinkingReady {
+            return .linking
+        }
+        return .unavailable
+    }
+
+    var requiresAcknowledgedHandler: Bool {
+        requiresHandler
+    }
+
+    var canDeliverWithLinking: Bool {
+        isLinkingReady
+    }
+
+    mutating func requireAcknowledgedHandler() {
+        requiresHandler = true
+    }
+
+    mutating func accept(_ url: URL) -> Acceptance {
+        switch deliveryMode {
+        case .unavailable:
+            let request = Request(id: UUID(), url: url, state: .buffered)
+            requests.append(request)
+            return .buffered(request.id)
+        case .linking:
+            return .linking(url)
+        case .handler:
+            let request = Request(id: UUID(), url: url, state: .awaitingAcknowledgement)
+            requests.append(request)
+            return .handler(request.id, request.url)
+        }
+    }
+
+    mutating func useLinking() -> [URL] {
+        isLinkingReady = true
+        guard deliveryMode == .linking else { return [] }
+
+        let urls = requests.compactMap { request in
+            request.state == .buffered ? request.url : nil
+        }
+        requests.removeAll { $0.state == .buffered }
+        return urls
+    }
+
+    mutating func useHandler() -> [(UUID, URL)] {
+        hasHandler = true
+        var deliveries: [(UUID, URL)] = []
+        for index in requests.indices where requests[index].state == .buffered {
+            requests[index].state = .awaitingAcknowledgement
+            deliveries.append((requests[index].id, requests[index].url))
+        }
+        return deliveries
+    }
+
+    mutating func removeHandler() {
+        hasHandler = false
+    }
+
+    mutating func acknowledge(_ id: UUID, handled: Bool) -> Resolution? {
+        guard let index = requests.firstIndex(where: {
+            $0.id == id && $0.state == .awaitingAcknowledgement
+        }) else { return nil }
+
+        let url = requests.remove(at: index).url
+        return handled ? .handled : .fallback(url)
+    }
+
+    mutating func expireReadiness(_ id: UUID) -> URL? {
+        expire(id, expectedState: .buffered)
+    }
+
+    mutating func expireAcknowledgement(_ id: UUID) -> URL? {
+        expire(id, expectedState: .awaitingAcknowledgement)
+    }
+
+    private mutating func expire(_ id: UUID, expectedState: RequestState) -> URL? {
+        guard let index = requests.firstIndex(where: {
+            $0.id == id && $0.state == expectedState
+        }) else { return nil }
+
+        return requests.remove(at: index).url
+    }
+}

package/ios/wrappers/ZixflowReactNativeDeepLinkRouter.swift

@@ -0,0 +1,312 @@
+@_spi(Internal) import ZixflowInternalCommon
+import Foundation
+import UIKit
+
+enum ZixflowReactNativeDeepLinkRouter {
+    private static let readinessTimeout: TimeInterval = 10
+    private static let acknowledgementTimeout: TimeInterval = 10
+    private static let sceneManifestKey = "UIApplicationSceneManifest"
+    private static let sceneConfigurationsKey = "UISceneConfigurations"
+    private static let sceneOpenURLContextsSelector = NSSelectorFromString("scene:openURLContexts:")
+    // React Native 0.83.6 and 0.88.0-nightly-20260823-0c7f63a4e use this
+    // notification name and payload for Linking URL events.
+    private static let openURLNotification = Notification.Name("RCTOpenURLNotification")
+    private static let stateLock = NSLock()
+    private static var requestStore = ZixflowReactNativeDeepLinkRequestStore()
+    private static var handlerEmitter: ((_ id: String, _ url: String) -> Void)?
+    private static var handlerToken: UUID?
+
+    static var requiresAcknowledgedHandler: Bool {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        return requestStore.requiresAcknowledgedHandler
+    }
+
+    private static var hasSceneManifest: Bool {
+        guard let manifest = Bundle.main.object(forInfoDictionaryKey: sceneManifestKey) as? [String: Any],
+              let configurations = manifest[sceneConfigurationsKey] as? [String: Any]
+        else { return false }
+
+        return !configurations.isEmpty
+    }
+
+    /// Mirrors `RCTIsSceneDelegateApp()` without linking to the internal symbol, and also requires
+    /// React Native's scene-Linking entry point. A scene manifest alone does not make older React
+    /// Native versions scene-aware.
+    static var isSceneLifecycleEnabled: Bool {
+        guard hasSceneManifest,
+              let linkingManager = NSClassFromString("RCTLinkingManager")
+        else { return false }
+
+        return linkingManager.responds(to: sceneOpenURLContextsSelector)
+    }
+
+    /// Expo owns scene-to-Linking forwarding even when its React Native version does not expose
+    /// the scene selector itself.
+    static var isExpoSceneLifecycleEnabled: Bool {
+        hasSceneManifest && NSClassFromString("EXExpoAppSceneDelegate") != nil
+    }
+
+    static func install() {
+        guard isSceneLifecycleEnabled else { return }
+        installCallback(requiringAcknowledgedHandler: false)
+    }
+
+    static func installAcknowledgedHandler() {
+        guard isSceneLifecycleEnabled else {
+            DIGraphShared.shared.logger.error(
+                "Zixflow could not install acknowledged deep-link routing because the host " +
+                    "does not expose a supported React Native scene lifecycle"
+            )
+            return
+        }
+        installCallback(requiringAcknowledgedHandler: true)
+    }
+
+    /// Expo owns scene-to-Linking forwarding even on React Native versions that do not expose the
+    /// scene selector themselves. Prefer the generic React Native capability when available, then
+    /// fall back to Expo's scene delegate capability.
+    static func installForExpoSceneLifecycle() {
+        guard isSceneLifecycleEnabled || isExpoSceneLifecycleEnabled else {
+            DIGraphShared.shared.logger.error(
+                "Zixflow could not install Expo scene deep-link routing because the host " +
+                    "does not expose a supported React Native or Expo scene lifecycle"
+            )
+            return
+        }
+        installCallback(requiringAcknowledgedHandler: false)
+    }
+
+    private static func installCallback(requiringAcknowledgedHandler: Bool) {
+        stateLock.lock()
+        if requiringAcknowledgedHandler {
+            requestStore.requireAcknowledgedHandler()
+        }
+        stateLock.unlock()
+        DIGraphShared.shared.deepLinkUtil.setDeepLinkCallback { url in
+            accept(url)
+            return true
+        }
+    }
+
+    static func accept(_ url: URL) {
+        stateLock.lock()
+        let acceptance = requestStore.accept(url)
+        stateLock.unlock()
+
+        switch acceptance {
+        case let .buffered(id):
+            DIGraphShared.shared.logger.info(
+                "Zixflow buffered an SDK deep link until a React Native route is ready"
+            )
+            scheduleReadinessExpiration(for: id)
+        case let .linking(url):
+            route(url)
+        case let .handler(id, url):
+            publishToHandler(id: id, url: url)
+        }
+    }
+
+    static func markReactNativeReady() {
+        let markReady = {
+            stateLock.lock()
+            let urls = requestStore.useLinking()
+            stateLock.unlock()
+
+            urls.forEach(route)
+        }
+        if Thread.isMainThread {
+            markReady()
+        } else {
+            DispatchQueue.main.async(execute: markReady)
+        }
+    }
+
+    static func registerHandler(
+        _ emitter: @escaping (_ id: String, _ url: String) -> Void
+    ) -> UUID {
+        let token = UUID()
+        stateLock.lock()
+        let hasAcknowledgedHandlerConfiguration = requestStore.requiresAcknowledgedHandler
+        handlerToken = token
+        handlerEmitter = emitter
+        let deliveries = requestStore.useHandler()
+        stateLock.unlock()
+
+        if !hasAcknowledgedHandlerConfiguration {
+            DIGraphShared.shared.logger.error(
+                "Zixflow registered an acknowledged deep-link handler without configuring " +
+                    "acknowledged scene routing before React Native started"
+            )
+        }
+        for (id, url) in deliveries {
+            publishToHandler(id: id, url: url)
+        }
+        return token
+    }
+
+    static func unregisterHandler(_ token: UUID) {
+        stateLock.lock()
+        guard handlerToken == token else {
+            stateLock.unlock()
+            return
+        }
+        handlerToken = nil
+        handlerEmitter = nil
+        requestStore.removeHandler()
+        stateLock.unlock()
+    }
+
+    static func acknowledge(_ id: String, handled: Bool) {
+        guard let requestId = UUID(uuidString: id) else {
+            DIGraphShared.shared.logger.error(
+                "Zixflow ignored an invalid React Native deep-link acknowledgement"
+            )
+            return
+        }
+
+        stateLock.lock()
+        let resolution = requestStore.acknowledge(requestId, handled: handled)
+        stateLock.unlock()
+
+        switch resolution {
+        case .handled:
+            DIGraphShared.shared.logger.info(
+                "React Native acknowledged the Zixflow deep link"
+            )
+        case let .fallback(url):
+            DIGraphShared.shared.logger.info(
+                "React Native declined the Zixflow deep link; using the native fallback"
+            )
+            fallback(url)
+        case nil:
+            DIGraphShared.shared.logger.info(
+                "Zixflow ignored a late or unknown React Native deep-link acknowledgement; " +
+                    "the native fallback may have already routed the destination"
+            )
+        }
+    }
+
+    static func route(_ url: URL) {
+        let publish = {
+            // React Native's AppDelegate URL entry point rejects scene-based hosts. Linking listens
+            // for this notification in both lifecycle modes, so publish the URL without choosing a scene.
+            DIGraphShared.shared.logger.info(
+                "Zixflow published an SDK deep link to React Native Linking"
+            )
+            NotificationCenter.default.post(
+                name: openURLNotification,
+                object: nil,
+                userInfo: ["url": url.absoluteString]
+            )
+        }
+        if Thread.isMainThread {
+            publish()
+        } else {
+            DispatchQueue.main.async(execute: publish)
+        }
+    }
+
+    private static func publishToHandler(id: UUID, url: URL) {
+        let publish = {
+            stateLock.lock()
+            let emitter = handlerEmitter
+            stateLock.unlock()
+
+            emitter?(id.uuidString, url.absoluteString)
+            DispatchQueue.main.asyncAfter(deadline: .now() + acknowledgementTimeout) {
+                expireAcknowledgement(id)
+            }
+        }
+        if Thread.isMainThread {
+            publish()
+        } else {
+            DispatchQueue.main.async(execute: publish)
+        }
+    }
+
+    private static func scheduleReadinessExpiration(for id: UUID) {
+        DispatchQueue.main.asyncAfter(deadline: .now() + readinessTimeout) {
+            expireReadiness(id)
+        }
+    }
+
+    private static func expireReadiness(_ id: UUID) {
+        stateLock.lock()
+        let url = requestStore.expireReadiness(id)
+        stateLock.unlock()
+
+        guard let url else { return }
+
+        DIGraphShared.shared.logger.error(
+            "Zixflow is using the native fallback because React Native deep-link routing " +
+                "did not become ready in time"
+        )
+        fallback(url)
+    }
+
+    private static func expireAcknowledgement(_ id: UUID) {
+        stateLock.lock()
+        let url = requestStore.expireAcknowledgement(id)
+        stateLock.unlock()
+
+        guard let url else { return }
+
+        DIGraphShared.shared.logger.error(
+            "Zixflow is using the native fallback because the React Native deep-link " +
+                "handler did not acknowledge the URL in time"
+        )
+        fallback(url)
+    }
+
+    private static func fallback(_ url: URL) {
+        let open = {
+            let uiKit = DIGraphShared.shared.uIKitWrapper
+            if uiKit.continueNSUserActivity(webpageURL: url) {
+                DIGraphShared.shared.logger.info(
+                    "Zixflow deep link was handled by the host AppDelegate fallback"
+                )
+            } else if isAppOwnedCustomScheme(url) {
+                stateLock.lock()
+                let linkingIsReady = requestStore.canDeliverWithLinking
+                stateLock.unlock()
+                route(url)
+                if linkingIsReady {
+                    DIGraphShared.shared.logger.info(
+                        "Zixflow forwarded the host app's custom-scheme deep link to React " +
+                            "Native Linking"
+                    )
+                } else {
+                    DIGraphShared.shared.logger.error(
+                        "Zixflow published the host app's custom-scheme deep link before " +
+                            "React Native Linking was marked ready; the destination may not be handled"
+                    )
+                }
+            } else {
+                uiKit.open(url: url)
+                DIGraphShared.shared.logger.info(
+                    "Zixflow opened the deep link through the system fallback"
+                )
+            }
+        }
+        if Thread.isMainThread {
+            open()
+        } else {
+            DispatchQueue.main.async(execute: open)
+        }
+    }
+
+    private static func isAppOwnedCustomScheme(_ url: URL) -> Bool {
+        guard let scheme = url.scheme,
+              scheme.caseInsensitiveCompare("http") != .orderedSame,
+              scheme.caseInsensitiveCompare("https") != .orderedSame,
+              let urlTypes = Bundle.main.object(forInfoDictionaryKey: "CFBundleURLTypes")
+              as? [[String: Any]]
+        else { return false }
+
+        return urlTypes.contains { urlType in
+            guard let schemes = urlType["CFBundleURLSchemes"] as? [String] else { return false }
+            return schemes.contains { $0.caseInsensitiveCompare(scheme) == .orderedSame }
+        }
+    }
+}

package/ios/wrappers/geofence/NativeGeofence.mm

@@ -0,0 +1,46 @@
+#import <React/RCTBridgeModule.h>
+#import <RNZixflowSpec/RNZixflowSpec.h>
+
+// Objective-C wrapper for new architecture TurboModule implementation
+@interface RCTNativeZixflowGeofence : NSObject <NativeZixflowGeofenceSpec>
+// Bridge to Swift implementation for cross-language compatibility
+@property(nonatomic, strong) id<NativeZixflowGeofenceSpec> swiftBridge;
+@end
+
+@implementation RCTNativeZixflowGeofence
+
+RCT_EXPORT_MODULE()
+
+// Create TurboModule instance for new architecture JSI integration
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params {
+  return std::make_shared<facebook::react::NativeZixflowGeofenceSpecJSI>(params);
+}
+
+- (instancetype)init {
+  if (self = [super init]) {
+    // Use runtime class lookup - NativeGeofence class only exists when the ZixflowLocationGeofence subspec is installed
+    Class swiftClass = NSClassFromString(@"NativeZixflowGeofence");
+    if (swiftClass) {
+      _swiftBridge = [[swiftClass alloc] init];
+    }
+  }
+  return self;
+}
+
+// Module initialization can happen on background thread
++ (BOOL)requiresMainQueueSetup {
+  return NO;
+}
+
+- (void)refreshFromCurrentLocation {
+  if (!_swiftBridge) return;
+  [_swiftBridge refreshFromCurrentLocation];
+}
+
+// Export class factory function for React Native component registration
+Class<RCTBridgeModule> NativeZixflowGeofenceCls(void) {
+  return RCTNativeZixflowGeofence.class;
+}
+
+@end

package/ios/wrappers/geofence/NativeGeofence.swift

@@ -0,0 +1,27 @@
+#if ZIXFLOW_GEOFENCE_ENABLED
+import ZixflowDataPipelines
+import ZixflowLocationGeofence
+
+/// Registers the optional geofence module with the native iOS SDK and exposes its app-facing
+/// methods. The reference to `GeofenceModule` is isolated here so it is only compiled when the
+/// geofence subspec is installed. Geofence depends on the location module, which the caller
+/// registers alongside it.
+@objc(NativeZixflowGeofence)
+public class NativeGeofence: NSObject {
+
+    /// Returns a `GeofenceModule` when the app opts into geofence via the `geofence` config,
+    /// applying the optional `locationMode` (defaults to `.automatic`).
+    static func module(from config: [String: Any]) -> GeofenceModule? {
+        guard let geofenceConfig = config["geofence"] as? [String: Any] else { return nil }
+        let locationModeValue = geofenceConfig["locationMode"] as? String
+        let locationMode: GeofenceLocationMode =
+            locationModeValue?.uppercased() == "MANUAL" ? .manual : .automatic
+        return GeofenceModule(config: GeofenceModuleConfig(locationMode: locationMode))
+    }
+
+    @objc
+    func refreshFromCurrentLocation() {
+        Zixflow.geofence.refreshFromCurrentLocation()
+    }
+}
+#endif

package/ios/wrappers/inapp/NativeMessagingInApp.mm

@@ -66,11 +66,29 @@ RCT_EXPORT_MODULE(NativeZixflowMessagingInApp)
   [_swiftBridge dismissMessage];
 }
 
+// Signature matches the Codegen protocol, which declares the argument nonnull. ObjC does not
+// enforce that at runtime, so a JavaScript null still arrives here as nil and is forwarded; the
+// Swift side takes an optional and reports it rather than trapping.
+- (void)setColorScheme:(NSString *)colorScheme {
+  [self assertBridgeAvailable:@"during setColorScheme"];
+  [_swiftBridge setColorScheme:colorScheme];
+}
+
 - (void)setupInboxListener {
   [self assertBridgeAvailable:@"during setupInboxListener"];
   [_swiftBridge setupInboxListener];
 }
 
+- (void)registerInboxEventListener {
+  [self assertBridgeAvailable:@"during registerInboxEventListener"];
+  [_swiftBridge registerInboxEventListener];
+}
+
+- (void)unregisterInboxEventListener {
+  [self assertBridgeAvailable:@"during unregisterInboxEventListener"];
+  [_swiftBridge unregisterInboxEventListener];
+}
+
 - (void)getMessages:(NSString *)topic
             resolve:(RCTPromiseResolveBlock)resolve
              reject:(RCTPromiseRejectBlock)reject {
@@ -110,6 +128,10 @@ RCT_EXPORT_MODULE(NativeZixflowMessagingInApp)
   [super emitOnInAppEventReceived:value];
 }
 
+- (void)emitOnInboxEventReceived:(NSDictionary *)value {
+  [super emitOnInboxEventReceived:value];
+}
+
 - (void)emitSubscribeToMessagesChanged:(NSDictionary *)value {
   [super emitSubscribeToMessagesChanged:value];
 }

package/ios/wrappers/inapp/NativeMessagingInApp.swift

@@ -50,6 +50,48 @@ public class NativeMessagingInApp: NSObject {
         // Clear in-app event listener to prevent leaks
         clearInAppEventListener()
         clearInboxChangeListener()
+        clearInboxEventListener()
+    }
+
+    // MARK: - Inbox Event Listener
+
+    /// Registers the native inbox event forwarder with the SDK and wires it to the ObjC event
+    /// emitter. Called by React Native when a JS inbox event listener is registered.
+    @objc(registerInboxEventListener)
+    public func registerInboxEventListener() {
+        ReactInboxEventListener.shared.setEventEmitter { [weak self] data in
+            guard let self else { return }
+            // Filter out nil values to convert [String: Any?] to [String: Any]
+            let body = data.compactMapValues { $0 }
+            self.sendInboxEvent(body: body)
+        }
+        MessagingInApp.shared.setInboxEventListener(ReactInboxEventListener.shared)
+    }
+
+    /// Unregisters the native inbox event forwarder from the SDK, restoring the SDK's default action
+    /// handling. Called by React Native when the JS inbox event listener is removed.
+    @objc(unregisterInboxEventListener)
+    public func unregisterInboxEventListener() {
+        MessagingInApp.shared.setInboxEventListener(nil)
+        ReactInboxEventListener.shared.clearEventEmitter()
+    }
+
+    private func clearInboxEventListener() {
+        MessagingInApp.shared.setInboxEventListener(nil)
+        ReactInboxEventListener.shared.clearEventEmitter()
+    }
+
+    // Send inbox event to React Native layer using ObjC event emitter
+    private func sendInboxEvent(body: [String: Any]) {
+        guard let emitter = objcEventEmitter else {
+            return
+        }
+
+        let selector = Selector(("emitOnInboxEventReceived:"))
+        guard emitter.responds(to: selector) else {
+            return
+        }
+        _ = emitter.perform(selector, with: body as NSDictionary)
     }
 
     /// Dismisses any currently displayed in-app message
@@ -58,6 +100,54 @@ public class NativeMessagingInApp: NSObject {
         MessagingInApp.shared.dismissMessage()
     }
 
+    /// Overrides the color scheme used to render in-app messages.
+    ///
+    /// Receives the raw value of the JavaScript `ZixflowColorScheme`, since the enum itself cannot
+    /// cross Codegen. An unrecognized value leaves the current scheme alone instead of resetting
+    /// it to `.auto`, so a typo cannot quietly undo a scheme the app set correctly earlier — the
+    /// Android bridge behaves the same way.
+    ///
+    /// The parameter is optional even though Codegen declares it non-null: untyped JavaScript can
+    /// still pass `null` or `undefined`, which the bridge forwards as `nil`. Bridging that into a
+    /// non-optional `String` would trap before the value could be reported, and Android accepts a
+    /// nullable argument for the same reason, so a non-optional type here would also leave the two
+    /// platforms behaving differently on the same input.
+    @objc(setColorScheme:)
+    public func setColorScheme(_ colorScheme: String?) {
+        guard let resolved = Self.colorScheme(fromRawValue: colorScheme) else {
+            logger.error(
+                "Unrecognized in-app colorScheme '\(colorScheme ?? "nil")', expected one of auto, light, dark. Leaving the color scheme unchanged."
+            )
+            return
+        }
+        // Without this the call is dropped in silence: `setColorScheme` forwards through the
+        // module's `implementation?`, which is nil until the SDK is initialized, and the only
+        // trace is an `.info` line the default `.error` log level discards. Android logs this
+        // case at error, so reporting it here is what keeps the two platforms diagnosable in the
+        // same way. Logged rather than failed, again to match Android, which completes the call.
+        guard MessagingInApp.shared.hasBeenInitialized else {
+            logger.error(
+                "In-app messaging is not available, so the color scheme was not applied. Ensure Zixflow SDK is initialized with the inApp configuration."
+            )
+            return
+        }
+        MessagingInApp.shared.setColorScheme(resolved)
+    }
+
+    /// Maps the wrapper's lowercase wire value onto the native `ColorScheme`.
+    ///
+    /// Matched explicitly rather than handed to `MessagingInAppConfigBuilder`, which resolves
+    /// anything unrecognized to `.auto`; here an unrecognized value has to stay distinguishable
+    /// so it can be reported.
+    private static func colorScheme(fromRawValue rawValue: String?) -> ColorScheme? {
+        switch rawValue {
+        case "auto": return .auto
+        case "light": return .light
+        case "dark": return .dark
+        default: return nil
+        }
+    }
+
     // MARK: - Inbox Methods
 
     @objc(setupInboxListener)

package/ios/wrappers/inbox/InboxHostContainment.swift

@@ -0,0 +1,40 @@
+import Foundation
+import UIKit
+
+/// Shared view-controller containment for the inbox `UIHostingController` hosts.
+///
+/// Adopting only a hosting controller's `view` leaves the controller outside the view-controller
+/// hierarchy. UIKit then has no presentation context or trait/safe-area chain for it, which showed up
+/// as a phantom top margin in the overlay's sheet (the sheet content resolved insets against the
+/// wrong container) and means no lifecycle callbacks ever reach the hosted SwiftUI. Native usage does
+/// not hit this because there the hosting controller *is* a real pushed view controller.
+///
+/// Containment has to be deferred until the Fabric view is actually in a window: React Native creates
+/// component views before mounting them, so at `init` there is no parent controller to attach to.
+enum InboxHostContainment {
+    /// Nearest view controller up the responder chain, or nil while the view is unmounted.
+    static func nearestViewController(from view: UIView?) -> UIViewController? {
+        var responder: UIResponder? = view
+        while let current = responder {
+            if let viewController = current as? UIViewController {
+                return viewController
+            }
+            responder = current.next
+        }
+        return nil
+    }
+
+    /// Attaches `child` to the controller owning `view`. No-op when already attached or unmounted.
+    static func attach(_ child: UIViewController, hostedIn view: UIView?) {
+        guard child.parent == nil, let parent = nearestViewController(from: view) else { return }
+        parent.addChild(child)
+        child.didMove(toParent: parent)
+    }
+
+    /// Detaches `child` from its parent. No-op when it was never attached.
+    static func detach(_ child: UIViewController) {
+        guard child.parent != nil else { return }
+        child.willMove(toParent: nil)
+        child.removeFromParent()
+    }
+}