@npaw/forge-react-native 10.1.0 → 10.2.0

package/ios/ForgeApple/Sources/NPAWForgeCore/ForgeApple.swift

@@ -159,12 +159,29 @@ public final class ForgeApple {
     private var latestCapturePlan: ForgeCapturePlan?
     private var logObservers: [UUID: (ForgeRenderedLog) -> Void] = [:]
     /// Guarded by its own lock, not `lock`: requests arrive on the runtime's
-    /// worker thread, and `destroy()` holds `lock` while the runtime joins
-    /// that worker - a request landing in that window must not need `lock`.
+    /// worker thread, which must never wait on the facade lock - a host call
+    /// holding `lock` would stall the kernel for as long as it runs.
     private let deviceSampleRequestLock = NSLock()
     private var deviceSampleRequestObservers: [UUID: ([String]) -> Void] = [:]
+    /// Remote command listeners keyed by command name, guarded by their own
+    /// lock for the same reason as the device-sample observers: commands
+    /// arrive on the runtime worker thread.
+    private let commandLock = NSLock()
+    private var commandListeners: [String: [(id: UUID, listener: ForgeCommandListener)]] = [:]
 
-    public init(config: ForgeAppleConfig, services: ForgeAppleServices) {
+    public convenience init(config: ForgeAppleConfig, services: ForgeAppleServices) {
+        self.init(config: config, services: services, initialCommandListeners: [])
+    }
+
+    /// `initialCommandListeners` are subscribed before the runtime starts, so
+    /// a command riding the very first response already finds them. They are
+    /// registered in the order given (the Builder keeps registration order),
+    /// so the subscription sets the runtime sees are deterministic.
+    public init(
+        config: ForgeAppleConfig,
+        services: ForgeAppleServices,
+        initialCommandListeners: [(name: String, listener: ForgeCommandListener)]
+    ) {
         let safeConfig = config.withPluginVersion(NPAWForge.defaultPluginVersion)
         self.config = safeConfig
         self.services = services
@@ -183,6 +200,14 @@ public final class ForgeApple {
         _ = runtime.setDeviceSampleListener { [weak self] families in
             self?.dispatchDeviceSampleRequest(families)
         }
+        // Also before start(): a command nobody subscribed to is answered
+        // `handled=false` by the kernel and never re-delivered.
+        _ = runtime.setCommandListener { [weak self] command in
+            self?.dispatchCommandRequest(command)
+        }
+        for registration in initialCommandListeners {
+            _ = addCommandListener(registration.name, registration.listener)
+        }
         _ = runtime.start()
         if safeConfig.startSessionOnInitialize {
             _ = startSession()
@@ -476,6 +501,107 @@ public final class ForgeApple {
         }
     }
 
+    /// Listens for a remote command by name. Adding or removing a listener
+    /// re-sends the full subscription set to the kernel, which auto-answers
+    /// `handled=false` any command whose name nobody subscribed to and never
+    /// re-delivers it. Blank or malformed names and the 65th distinct name
+    /// are refused with a diagnostic. Listeners run on the runtime worker
+    /// thread: return quickly; the answer may be sent later from any thread.
+    public func addCommandListener(_ name: String, _ listener: @escaping ForgeCommandListener) -> ForgeEventSubscription {
+        guard let normalized = ForgeCommandNames.normalize(name) else {
+            recordDiagnostic(
+                code: "forge_command_name_invalid",
+                message: "command names are 1-64 characters of [A-Za-z0-9_.-]",
+                attributes: ["name": String(name.prefix(64))]
+            )
+            return ForgeEventSubscription {}
+        }
+        let id = UUID()
+        commandLock.lock()
+        if commandListeners[normalized] == nil, commandListeners.count >= ForgeCommandNames.maxSubscriptions {
+            commandLock.unlock()
+            recordDiagnostic(
+                code: "forge_command_subscriptions_limit",
+                message: "at most \(ForgeCommandNames.maxSubscriptions) distinct command names can be subscribed",
+                attributes: ["name": normalized]
+            )
+            return ForgeEventSubscription {}
+        }
+        commandListeners[normalized, default: []].append((id: id, listener: listener))
+        commandLock.unlock()
+        syncCommandSubscriptions()
+        return ForgeEventSubscription { [weak self] in
+            guard let self else { return }
+            self.commandLock.lock()
+            if var listeners = self.commandListeners[normalized] {
+                listeners.removeAll { $0.id == id }
+                if listeners.isEmpty {
+                    self.commandListeners.removeValue(forKey: normalized)
+                } else {
+                    self.commandListeners[normalized] = listeners
+                }
+            }
+            self.commandLock.unlock()
+            self.syncCommandSubscriptions()
+        }
+    }
+
+    /// The remote command names currently subscribed, sorted.
+    public func commandSubscriptions() -> [String] {
+        commandLock.lock()
+        defer { commandLock.unlock() }
+        return commandListeners.keys.sorted()
+    }
+
+    /// Answers a delivered remote command by id. Normally reached through the
+    /// ``ForgeCommandAnswer`` handed to a listener; exposed for hosts that
+    /// correlate answers themselves (React Native). The kernel keeps the first
+    /// answer per command id.
+    @discardableResult
+    public func answerCommand(id: String, handled: Bool, details: [String: String] = [:]) -> ForgeOutcome {
+        // Same shape as `syncCommandSubscriptions`: `destroyed` is read under
+        // `lock`, which is released before the runtime call. Answers may come
+        // from a listener running on the runtime worker thread, and that
+        // thread must never wait on `lock` for longer than a state read.
+        lock.lock()
+        let isDestroyed = destroyed
+        lock.unlock()
+        guard !isDestroyed else { return .ignoredInvalidState }
+        return runtime.answerCommand(id: id, handled: handled, details: details)
+    }
+
+    private func syncCommandSubscriptions() {
+        lock.lock()
+        let isDestroyed = destroyed
+        lock.unlock()
+        guard !isDestroyed else { return }
+        _ = runtime.setCommandSubscriptions(commandSubscriptions())
+    }
+
+    /// Runs on the runtime's worker thread. Every listener of the name gets
+    /// its own once-guarded answer; a name without listeners (a race with an
+    /// unsubscribe) is left unanswered - the kernel auto-answers only names
+    /// nobody subscribed to.
+    private func dispatchCommandRequest(_ command: ForgeCommand) {
+        commandLock.lock()
+        let listeners = commandListeners[command.name]?.map { $0.listener } ?? []
+        commandLock.unlock()
+        for listener in listeners {
+            let answer = ForgeCommandAnswer { [weak self] handled, details in
+                self?.answerCommand(id: command.id, handled: handled, details: details) ?? .ignoredInvalidState
+            }
+            listener(command, answer)
+        }
+    }
+
+    /// The Apple services carry no diagnostics sink (listener closures cannot
+    /// throw here), so refused registrations surface as facade warnings.
+    private func recordDiagnostic(code: String, message: String, attributes: [String: String]) {
+        var details = attributes
+        details["code"] = code
+        logger.warning(family: .diagnostics, action: message, details: details)
+    }
+
     public func effectiveLogLevel() -> ForgeLogLevel {
         logger.effectiveLevel()
     }
@@ -658,23 +784,38 @@ public final class ForgeApple {
         return recordedEvents
     }
 
+    /// `lock` covers only the state flip and the observer registries; the
+    /// runtime calls run unlocked on purpose. The native runtime's `destroy()`
+    /// joins its worker thread, and a listener still running on that worker
+    /// (answering a command, forwarding a log or a plan) takes `lock` on its
+    /// way back in - holding it across the join would make both threads wait
+    /// on each other forever. Every entry point re-checks `destroyed` under
+    /// `lock`, so nothing new reaches the runtime in the meantime, and a
+    /// second `destroy()` still reports `.ignoredDuplicate` at once.
     public func destroy() -> ForgeOutcome {
         lock.lock()
-        defer { lock.unlock() }
-        guard !destroyed else { return .ignoredDuplicate }
+        guard !destroyed else {
+            lock.unlock()
+            return .ignoredDuplicate
+        }
         destroyed = true
         eventObservers.removeAll()
         onSendRequestListeners.removeAll()
         capturePlanObservers.removeAll()
         logObservers.removeAll()
+        recordedEvents.removeAll()
+        lock.unlock()
         deviceSampleRequestLock.lock()
         deviceSampleRequestObservers.removeAll()
         deviceSampleRequestLock.unlock()
-        recordedEvents.removeAll()
+        commandLock.lock()
+        commandListeners.removeAll()
+        commandLock.unlock()
         _ = runtime.registerSessionPreSendHook(nil)
         _ = runtime.setCapturePlanListener(nil)
         _ = runtime.setLogListener(nil)
         _ = runtime.setDeviceSampleListener(nil)
+        _ = runtime.setCommandListener(nil)
         return runtime.destroy()
     }
 

package/ios/ForgeApple/Sources/NPAWForgeCore/ForgeCommands.swift

@@ -0,0 +1,113 @@
+/**
+ * Copyright (C) NPAW - All Rights Reserved
+ *
+ * This source code is protected under international copyright law. All rights
+ * reserved and protected by the copyright holders. This file is confidential
+ * and only available to authorized individuals with the permission of the
+ * copyright holders. If you encounter this file and do not have permission,
+ * please contact the copyright holders and delete this file.
+ *
+ *
+ * @author: Victor Soto <victor.soto@nicepeopleatwork.com>
+ * @description: Public remote-command types for Apple (forge-commands): the command the backend addressed to this client, the once-guarded answer handle whose first call becomes the kernel's `command-answer` event, the Objective-C mirrors, and the name validation shared with the kernel.
+ */
+import Foundation
+
+/// A remote command the backend addressed to this client, delivered in the
+/// `npaw-command` header of an NQS response. `args` are positional strings in
+/// header order; `id` is opaque and echoed as `commandId` on the answer.
+public struct ForgeCommand: Equatable {
+    public let id: String
+    public let name: String
+    public let args: [String]
+
+    public init(id: String, name: String, args: [String]) {
+        self.id = id
+        self.name = name
+        self.args = args
+    }
+}
+
+/// Answers one delivered command. The first `send` forwards `handled` plus the
+/// optional flat string `details` to the kernel, which reports them as a
+/// `command-answer` analytics event carrying the command id and name; later
+/// calls return `.ignoredDuplicate` locally. Across listeners the kernel keeps
+/// the first answer per command id. Safe to call from any thread, later than
+/// the listener invocation.
+@objc(NPAWForgeCommandAnswer)
+public final class ForgeCommandAnswer: NSObject {
+    private let forward: (Bool, [String: String]) -> ForgeOutcome
+    private let lock = NSLock()
+    private var answered = false
+
+    init(forward: @escaping (Bool, [String: String]) -> ForgeOutcome) {
+        self.forward = forward
+    }
+
+    @objc
+    @discardableResult
+    public func send(handled: Bool, details: [String: String] = [:]) -> ForgeOutcome {
+        lock.lock()
+        if answered {
+            lock.unlock()
+            return .ignoredDuplicate
+        }
+        answered = true
+        lock.unlock()
+        return forward(handled, details)
+    }
+
+    /// True once `send` ran.
+    @objc public var isAnswered: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return answered
+    }
+}
+
+/// Receives remote commands of the name it was registered for. Every listener
+/// of a name runs, on the native runtime thread: return quickly and do slow
+/// work on a queue of your own; the answer may be sent later.
+public typealias ForgeCommandListener = (ForgeCommand, ForgeCommandAnswer) -> Void
+
+/// Objective-C mirror of ``ForgeCommand``.
+@objc(NPAWForgeCommand)
+public final class NPAWForgeCommandObjC: NSObject {
+    @objc public let id: String
+    @objc public let name: String
+    @objc public let args: [String]
+
+    public init(_ command: ForgeCommand) {
+        self.id = command.id
+        self.name = command.name
+        self.args = command.args
+    }
+}
+
+/// Objective-C handle for cancelling a subscription made through the wrapper.
+@objc(NPAWForgeSubscription)
+public final class NPAWForgeSubscriptionObjC: NSObject {
+    private let subscription: ForgeEventSubscription
+
+    public init(_ subscription: ForgeEventSubscription) {
+        self.subscription = subscription
+    }
+
+    @objc public func cancel() {
+        subscription.cancel()
+    }
+}
+
+enum ForgeCommandNames {
+    /// Distinct command names one host may subscribe to (the kernel cap).
+    static let maxSubscriptions = 64
+
+    /// Trims and validates a command name; nil when the kernel would refuse it.
+    static func normalize(_ name: String) -> String? {
+        let trimmed = name.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, trimmed.count <= 64 else { return nil }
+        let allowed = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "_.-"))
+        guard trimmed.unicodeScalars.allSatisfy({ $0.isASCII && allowed.contains($0) }) else { return nil }
+        return trimmed
+    }
+}

package/ios/ForgeApple/Sources/NPAWForgeCore/ForgeRuntime.swift

@@ -89,6 +89,17 @@ public protocol ForgeRuntime: AnyObject {
     /// request is not replayed to a late listener - the kernel asks again on
     /// the next tick.
     func setDeviceSampleListener(_ listener: (([String]) -> Void)?) -> ForgeOutcome
+    /// Replaces the full set of remote command names this host listens to.
+    /// Commands with any other name are auto-answered `handled=false` by the
+    /// kernel. Accepted before `start()`.
+    func setCommandSubscriptions(_ names: [String]) -> ForgeOutcome
+    /// Answers a command delivered through ``setCommandListener(_:)``; the
+    /// kernel emits the first answer per command id as a `command-answer`
+    /// session event.
+    func answerCommand(id: String, handled: Bool, details: [String: String]) -> ForgeOutcome
+    /// Registers (or clears with `nil`) the receiver of subscribed remote
+    /// commands. A command is delivered once and never replayed.
+    func setCommandListener(_ listener: ((ForgeCommand) -> Void)?) -> ForgeOutcome
     func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView
     func recordEvent(_ event: ForgeRecordedEvent) -> ForgeOutcome
     /// Records a typed identity transition (`loginSuccess`, `loginFailed`,
@@ -162,6 +173,11 @@ public extension ForgeRuntime {
     /// Additive default: no kernel means no cadence, so registration succeeds
     /// and simply never delivers a request.
     func setDeviceSampleListener(_ listener: (([String]) -> Void)?) -> ForgeOutcome { .accepted }
+    /// Additive defaults: a runtime with no kernel behind it receives no
+    /// commands, so subscriptions and answers are accepted and forgotten.
+    func setCommandSubscriptions(_ names: [String]) -> ForgeOutcome { .accepted }
+    func answerCommand(id: String, handled: Bool, details: [String: String]) -> ForgeOutcome { .accepted }
+    func setCommandListener(_ listener: ((ForgeCommand) -> Void)?) -> ForgeOutcome { .accepted }
 }
 
 public protocol ForgeRuntimeFactory: AnyObject {
@@ -181,6 +197,11 @@ public final class UnavailableForgeRuntime: ForgeRuntime {
     public func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome { .accepted }
     public func recordDeviceSample(_ sample: ForgeDeviceSample) -> ForgeOutcome { .accepted }
     public func setDeviceSampleListener(_ listener: (([String]) -> Void)?) -> ForgeOutcome { .accepted }
+    public func setCommandSubscriptions(_ names: [String]) -> ForgeOutcome { .accepted }
+    /// An answer is an event the missing kernel cannot emit: it fails like
+    /// `recordEvent`, so the host is not told a `command-answer` went out.
+    public func answerCommand(id: String, handled: Bool, details: [String: String]) -> ForgeOutcome { failed() }
+    public func setCommandListener(_ listener: ((ForgeCommand) -> Void)?) -> ForgeOutcome { .accepted }
     public func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView { RuntimeVideoView(id: -1) }
     public func recordEvent(_ event: ForgeRecordedEvent) -> ForgeOutcome { failed() }
     public func recordIdentityEvent(kind: String, timemarkMs: Int64, fields: [String: String]) -> ForgeOutcome { failed() }
@@ -255,6 +276,21 @@ public final class RecordingForgeRuntime: ForgeRuntime {
     /// The device sample request listener currently registered, `nil` once
     /// cleared.
     public private(set) var deviceSampleListener: (([String]) -> Void)?
+    /// Every remote-command subscription set forwarded, in order.
+    public private(set) var commandSubscriptions: [[String]] = []
+    /// Every remote-command answer forwarded, in order.
+    public private(set) var commandAnswers: [(id: String, handled: Bool, details: [String: String])] = []
+    /// The remote command listener currently registered, `nil` once cleared.
+    public private(set) var commandListener: ((ForgeCommand) -> Void)?
+    /// Runtime calls in order (`start`, `subscriptions:a,b`,
+    /// `commandListener:set`, `commandListener:clear`), so a test can assert
+    /// that Builder listeners and the command listener are in place before
+    /// `start()`.
+    public private(set) var calls: [String] = []
+    /// Runs inside `destroy()`, at the point where the native runtime joins
+    /// its worker thread. A test models a delivery still running on that
+    /// worker by blocking here until it returns.
+    public var destroyHook: (() -> Void)?
     /// Device samples arrive from the collector's utility queue while a test
     /// reads them from the main thread; only those two members are guarded.
     private let recordingLock = NSLock()
@@ -262,12 +298,43 @@ public final class RecordingForgeRuntime: ForgeRuntime {
 
     public init() {}
 
-    public func start() -> ForgeOutcome { .accepted }
+    public func start() -> ForgeOutcome {
+        calls.append("start")
+        return .accepted
+    }
     public func setLogLevel(_ level: ForgeLogLevel) -> ForgeOutcome { .accepted }
     public func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome {
         publishedConnectionTypes.append(connectionType)
         return .accepted
     }
+    public func setCommandSubscriptions(_ names: [String]) -> ForgeOutcome {
+        recordingLock.lock()
+        defer { recordingLock.unlock() }
+        commandSubscriptions.append(names)
+        calls.append("subscriptions:" + names.joined(separator: ","))
+        return .accepted
+    }
+    public func answerCommand(id: String, handled: Bool, details: [String: String]) -> ForgeOutcome {
+        recordingLock.lock()
+        defer { recordingLock.unlock() }
+        commandAnswers.append((id: id, handled: handled, details: details))
+        return .accepted
+    }
+    public func setCommandListener(_ listener: ((ForgeCommand) -> Void)?) -> ForgeOutcome {
+        recordingLock.lock()
+        defer { recordingLock.unlock() }
+        commandListener = listener
+        calls.append(listener == nil ? "commandListener:clear" : "commandListener:set")
+        return .accepted
+    }
+    /// Test hook mirroring the kernel's command delivery: hands the command to
+    /// the registered listener, if any. Nothing is replayed.
+    public func emitCommandRequest(_ command: ForgeCommand) {
+        recordingLock.lock()
+        let listener = commandListener
+        recordingLock.unlock()
+        listener?(command)
+    }
     public func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome {
         recordedLocationFixes.append(fix)
         return .accepted
@@ -374,7 +441,10 @@ public final class RecordingForgeRuntime: ForgeRuntime {
         return .accepted
     }
     public func snapshotEvents() -> [ForgeRecordedEvent] { events }
-    public func destroy() -> ForgeOutcome { .accepted }
+    public func destroy() -> ForgeOutcome {
+        destroyHook?()
+        return .accepted
+    }
     public func setCapturePlanListener(_ listener: ((ForgeCapturePlan) -> Void)?) -> ForgeOutcome {
         capturePlanListener = listener
         if let listener, let latest = latestCapturePlan {

package/ios/ForgeApple/Sources/NPAWForgeCore/NPAWForge.swift

@@ -40,7 +40,7 @@ public final class NPAWForge: NSObject {
     /// `scripts/apple/publish-local-shipped.sh` rewrites this literal to the
     /// release version when staging the shipped package, and fails loudly if
     /// it cannot find it. Keep it a plain stored literal for that reason.
-    public static let defaultPluginVersion = "10.1.0"
+    public static let defaultPluginVersion = "10.2.0"
     public static let defaultAppName = "apple"
     public static let defaultBuildVariant = "release"
     public static let defaultLmaEndpoint = "https://lma.npaw.com"
@@ -139,6 +139,32 @@ public final class NPAWForge: NSObject {
         kernel.addOnSendRequestListener(listener)
     }
 
+    /// Listens for a remote command by name. The backend delivers commands in
+    /// the responses of Forge's own analytics requests, so they arrive only
+    /// while events flow; a command nobody subscribed to is answered
+    /// `handled=false` by the kernel and never re-delivered - register early
+    /// (or through `Builder.addCommandListener`, which runs before the runtime
+    /// starts). Every listener of the name runs; call
+    /// ``ForgeCommandAnswer/send(handled:details:)`` at most once per listener,
+    /// and the first answer per command id is reported as a `command-answer`
+    /// event. Listeners run on an internal runtime thread: return quickly.
+    public func onCommand(_ name: String, _ listener: @escaping ForgeCommandListener) -> ForgeEventSubscription {
+        kernel.addCommandListener(name, listener)
+    }
+
+    /// Answers a delivered remote command by id, for hosts that correlate
+    /// answers themselves. Prefer the ``ForgeCommandAnswer`` handed to the
+    /// listener. The kernel keeps the first answer per command id.
+    @discardableResult
+    public func answerCommand(id: String, handled: Bool, details: [String: String] = [:]) -> ForgeOutcome {
+        kernel.answerCommand(id: id, handled: handled, details: details)
+    }
+
+    /// The remote command names currently subscribed, sorted.
+    public func commandSubscriptions() -> [String] {
+        kernel.commandSubscriptions()
+    }
+
     public func snapshotEvents() -> [ForgeRecordedEvent] {
         kernel.snapshotEvents()
     }
@@ -420,6 +446,11 @@ public final class NPAWForge: NSObject {
         private var deviceInfo: ForgeDeviceInfo?
         private var framework: String?
         private var services: ForgeAppleServices?
+        /// Registration-ordered: the facade subscribes these one by one before
+        /// the runtime starts, so the order decides the subscription sets the
+        /// runtime sees. A dictionary would make that order hash-seed
+        /// dependent.
+        private var commandListeners: [(name: String, listener: ForgeCommandListener)] = []
 
         public init(accountCode: String) {
             self.accountCode = accountCode
@@ -570,6 +601,15 @@ public final class NPAWForge: NSObject {
             return self
         }
 
+        /// Registers a remote command listener before the runtime starts, so
+        /// a command riding the very first response already finds it. Same
+        /// semantics as ``NPAWForge/onCommand(_:_:)``.
+        @discardableResult
+        public func addCommandListener(_ name: String, _ listener: @escaping ForgeCommandListener) -> Builder {
+            commandListeners.append((name: name, listener: listener))
+            return self
+        }
+
         public func build() -> NPAWForge {
             // Services first: resolving the device UUID needs the storage the
             // integrator supplied, so it cannot wait until after the config.
@@ -599,7 +639,11 @@ public final class NPAWForge: NSObject {
                 deviceInfo: resolvedDeviceInfo?.isEmpty == true ? nil : resolvedDeviceInfo,
                 framework: framework
             )
-            let forge = NPAWForge(kernel: ForgeApple(config: config, services: resolvedServices))
+            let forge = NPAWForge(kernel: ForgeApple(
+                config: config,
+                services: resolvedServices,
+                initialCommandListeners: commandListeners
+            ))
             if autoLocationEnabled {
                 // Created here but inert: it reads nothing until a capture plan
                 // carries the location bit. The plan registry replays the

package/ios/ForgeApple/Sources/NPAWForgeCore/NativeUniFFIRuntime.swift

@@ -28,6 +28,9 @@ final class UniFFIForgeRuntime: ForgeRuntime {
     private var capturePlanListener: UniFFICapturePlanListener?
     private var logListener: UniFFILogListener?
     private var deviceSampleListener: UniFFIDeviceSampleListener?
+    /// Readable by the bridge tests, which check the wrapper is released once
+    /// the listener is cleared.
+    private(set) var commandListener: UniFFICommandListener?
 
     init(config: ForgeAppleConfig) {
         bridge = ForgeRuntimeBridge(config: AppleRuntimeConfig(
@@ -104,6 +107,39 @@ final class UniFFIForgeRuntime: ForgeRuntime {
         return result
     }
 
+    func setCommandSubscriptions(_ names: [String]) -> ForgeOutcome {
+        outcome(bridge.setCommandSubscriptions(names: names))
+    }
+
+    func answerCommand(id: String, handled: Bool, details: [String: String]) -> ForgeOutcome {
+        outcome(bridge.answerCommand(commandId: id, handled: handled, details: details))
+    }
+
+    func setCommandListener(_ listener: ((ForgeCommand) -> Void)?) -> ForgeOutcome {
+        if let listener {
+            let callback = UniFFICommandListener(callback: listener)
+            // Retained before registering, like the other listeners.
+            callbackLock.lock()
+            commandListener = callback
+            callbackLock.unlock()
+            let result = outcome(bridge.setCommandListener(listener: callback))
+            if !result.isAccepted {
+                callbackLock.lock()
+                commandListener = nil
+                callbackLock.unlock()
+            }
+            return result
+        }
+
+        let result = outcome(bridge.clearCommandListener())
+        if result.isAccepted {
+            callbackLock.lock()
+            commandListener = nil
+            callbackLock.unlock()
+        }
+        return result
+    }
+
     func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView {
         RuntimeVideoView(id: Int64(clamping: bridge.createVideoView(
             nowMs: u64(timestampMs),
@@ -355,6 +391,7 @@ final class UniFFIForgeRuntime: ForgeRuntime {
         _ = bridge.clearCapturePlanListener()
         _ = bridge.clearLogListener()
         _ = bridge.clearDeviceSampleListener()
+        _ = bridge.clearCommandListener()
         callbackLock.lock()
         contentMetadataProviders.removeAll()
         videoPreSendHooks.removeAll()
@@ -362,6 +399,7 @@ final class UniFFIForgeRuntime: ForgeRuntime {
         capturePlanListener = nil
         logListener = nil
         deviceSampleListener = nil
+        commandListener = nil
         callbackLock.unlock()
         return result
     }
@@ -769,4 +807,19 @@ private final class UniFFIDeviceSampleListener: AppleDeviceSampleListener, @unch
         callback(families)
     }
 }
+
+/// Receives subscribed remote commands on the runtime worker thread and hands
+/// them to the Swift facade, which fans out to the `onCommand` listeners.
+/// Module-internal (not private) so the bridge tests can pin the mapping.
+final class UniFFICommandListener: AppleCommandListener, @unchecked Sendable {
+    private let callback: (ForgeCommand) -> Void
+
+    init(callback: @escaping (ForgeCommand) -> Void) {
+        self.callback = callback
+    }
+
+    func onCommand(command: AppleCommandRequest) {
+        callback(ForgeCommand(id: command.id, name: command.name, args: command.args))
+    }
+}
 #endif

package/ios/ForgeApple/Sources/NPAWForgeCore/ObjectiveCWrappers.swift

@@ -93,6 +93,20 @@ public final class NPAWForgeObjC: NSObject {
         swiftForge.trackSessionEvent(name: name, metadata: metadata.toStringAnyMap())
     }
 
+    /// Listens for a remote command by name; see `NPAWForge.onCommand`.
+    @objc(onCommandWithName:listener:)
+    public func onCommand(name: String, listener: @escaping (NPAWForgeCommandObjC, ForgeCommandAnswer) -> Void) -> NPAWForgeSubscriptionObjC {
+        NPAWForgeSubscriptionObjC(swiftForge.onCommand(name) { command, answer in
+            listener(NPAWForgeCommandObjC(command), answer)
+        })
+    }
+
+    /// Answers a delivered remote command by id; see `NPAWForge.answerCommand`.
+    @objc(answerCommandWithId:handled:details:)
+    public func answerCommand(id: String, handled: Bool, details: NSDictionary?) -> ForgeOutcome {
+        swiftForge.answerCommand(id: id, handled: handled, details: details.toStringStringMap())
+    }
+
     @objc(trackSessionErrorWithCode:message:metadata:)
     public func trackSessionError(code: String, message: String, metadata: NSDictionary?) -> ForgeOutcome {
         swiftForge.trackSessionError(errorCode: code, errorMessage: message, metadata: metadata.toStringAnyMap())