@npaw/forge-react-native 9.7.1 → 9.7.3

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 = "9.7.1"
+    public static let defaultPluginVersion = "9.7.3"
     public static let defaultAppName = "apple"
     public static let defaultBuildVariant = "release"
     public static let defaultLmaEndpoint = "https://lma.npaw.com"
@@ -89,6 +89,12 @@ public final class NPAWForge: NSObject {
     private var destroyed = false
     private let lock = NSRecursiveLock()
     private var videoAdapters: [VideoAdapter] = []
+    /// Set when automatic connection type collection is on. Held so `destroy()`
+    /// can cancel the path monitor that belongs to this instance.
+    private var connectionTypeObserver: ForgeConnectionTypeObserver?
+    /// Set when the integrator allowed location observation. It reads nothing
+    /// until a capture plan carries the location bit.
+    private var locationObserver: ForgeLocationObserver?
 
     public init(kernel: ForgeApple) {
         self.kernel = kernel
@@ -102,6 +108,14 @@ public final class NPAWForge: NSObject {
         kernel.subscribeEvents(observer)
     }
 
+    /// Observes the kernel's rendered decision log - the same lines
+    /// `logLevel: trace` writes to the platform console. Registering is not
+    /// required for console output; it is for hosts that forward the stream
+    /// somewhere else, as the React Native binding does.
+    public func addLogListener(_ listener: @escaping (ForgeRenderedLog) -> Void) -> ForgeEventSubscription {
+        kernel.addLogListener(listener)
+    }
+
     /// Observes kernel-derived capture plans (bitmask + focus/limit knobs +
     /// behavior hints). The latest plan is replayed to listeners added after
     /// the first emission. The kernel intake gates remain the semantic
@@ -232,12 +246,55 @@ public final class NPAWForge: NSObject {
         defer { lock.unlock() }
         guard !destroyed else { return .ignoredDuplicate }
         destroyed = true
+        connectionTypeObserver?.stop()
+        connectionTypeObserver = nil
+        locationObserver?.stop()
+        locationObserver = nil
         let adapters = videoAdapters
         videoAdapters.removeAll()
         adapters.forEach { _ = $0.destroy() }
         return kernel.destroy()
     }
 
+    /// Reports the device's current connection class to the kernel. Called by
+    /// the automatic observer; a `connectionType` the integrator set through
+    /// content metadata keeps precedence over it.
+    @discardableResult
+    public func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome {
+        kernel.setAutoConnectionType(connectionType)
+    }
+
+    /// Forwards a location fix to the kernel, which owns every threshold.
+    @discardableResult
+    public func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome {
+        kernel.recordLocationFix(fix)
+    }
+
+    /// Starts or stops location observation to match the capture plan. Nothing
+    /// reads location - not even the authorization status - until an operator
+    /// enables one of the two motion switches.
+    func applyLocationPlan(_ plan: ForgeCapturePlan) {
+        guard let observer = locationObserver else { return }
+        if plan.bits & ForgeCapturePlan.Bits.location != 0 {
+            observer.start()
+        } else {
+            observer.stop()
+        }
+    }
+
+    func installLocationObserver(_ observer: ForgeLocationObserver) {
+        lock.lock()
+        locationObserver = observer
+        lock.unlock()
+    }
+
+    func installConnectionTypeObserver(_ observer: ForgeConnectionTypeObserver) {
+        lock.lock()
+        connectionTypeObserver = observer
+        lock.unlock()
+        observer.start()
+    }
+
     func buildVideoAdapter(
         identifier: String,
         options: VideoOptions,
@@ -299,8 +356,11 @@ public final class NPAWForge: NSObject {
         private var preSessionEventQueueMaxAgeMs: Int64 = 30_000
         private var logLevel: ForgeLogLevel = .warning
         private var autoDeviceIdentityEnabled = true
+        private var autoConnectionTypeEnabled = true
+        private var autoLocationEnabled = true
         private var deviceUuid: String?
         private var deviceInfo: ForgeDeviceInfo?
+        private var framework: String?
         private var services: ForgeAppleServices?
 
         public init(accountCode: String) {
@@ -391,6 +451,42 @@ public final class NPAWForge: NSObject {
             return self
         }
 
+        /// Disables automatic collection of the device connection type
+        /// (`connectionType`: `wifi`, `cellular`, `ethernet`, `other` or
+        /// `unknown`).
+        ///
+        /// Collection is on by default and uses `NWPathMonitor`, which needs no
+        /// entitlement and no user prompt. A `connectionType` supplied through
+        /// content metadata always wins, whether or not this is enabled.
+        @discardableResult
+        public func setAutoConnectionTypeEnabled(_ enabled: Bool) -> Builder {
+            autoConnectionTypeEnabled = enabled
+            return self
+        }
+
+        /// Disables location observation entirely, whatever an operator
+        /// configures remotely.
+        ///
+        /// Forge never requests location authorization and reads location only
+        /// when the app already holds one AND an operator enabled a motion
+        /// switch. This is the local override for integrators who would rather
+        /// Forge never touch location at all.
+        @discardableResult
+        public func setAutoLocationEnabled(_ enabled: Bool) -> Builder {
+            autoLocationEnabled = enabled
+            return self
+        }
+
+        /// Declares the framework layered on top of this facade. First-party
+        /// bindings only: React Native sets `"react-native"` so its traffic is
+        /// distinguishable in `pluginInfo`. Unknown values are dropped by the
+        /// kernel, and the reported platform stays `apple` either way.
+        @discardableResult
+        public func setFramework(_ value: String?) -> Builder {
+            framework = value
+            return self
+        }
+
         /// Overrides the automatically collected device identifier.
         @discardableResult
         public func setDeviceUuid(_ value: String?) -> Builder {
@@ -430,9 +526,34 @@ public final class NPAWForge: NSObject {
                 preSessionEventQueueMaxAgeMs: preSessionEventQueueMaxAgeMs,
                 logLevel: logLevel,
                 deviceUuid: resolvedDeviceUuid,
-                deviceInfo: resolvedDeviceInfo?.isEmpty == true ? nil : resolvedDeviceInfo
+                deviceInfo: resolvedDeviceInfo?.isEmpty == true ? nil : resolvedDeviceInfo,
+                framework: framework
             )
             let forge = NPAWForge(kernel: ForgeApple(config: config, services: resolvedServices))
+            if autoLocationEnabled {
+                // Created here but inert: it reads nothing until a capture plan
+                // carries the location bit. The plan registry replays the
+                // latest plan to a late subscriber, so this covers a plan that
+                // already arrived as well as later ones.
+                forge.installLocationObserver(
+                    ForgeLocationObserver { [weak forge] fix in
+                        forge?.recordLocationFix(fix)
+                    }
+                )
+                _ = forge.addCapturePlanListener { [weak forge] plan in
+                    forge?.applyLocationPlan(plan)
+                }
+            }
+            if autoConnectionTypeEnabled {
+                // Started once here, for the life of the instance, and
+                // cancelled in `destroy()`. A monitor per view is what would
+                // leak one per playback.
+                forge.installConnectionTypeObserver(
+                    ForgeConnectionTypeObserver { [weak forge] connectionType in
+                        forge?.setAutoConnectionType(connectionType)
+                    }
+                )
+            }
             ForgeAutomaticCaptureRegistry.installIfAvailable(forge)
             return forge
         }

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

@@ -26,6 +26,7 @@ final class UniFFIForgeRuntime: ForgeRuntime {
     private var videoPreSendHooks: [Int64: UniFFIVideoPreSendHook] = [:]
     private var sessionPreSendHook: UniFFISessionPreSendHook?
     private var capturePlanListener: UniFFICapturePlanListener?
+    private var logListener: UniFFILogListener?
 
     init(config: ForgeAppleConfig) {
         bridge = ForgeRuntimeBridge(config: AppleRuntimeConfig(
@@ -40,6 +41,7 @@ final class UniFFIForgeRuntime: ForgeRuntime {
             logLevel: config.logLevel.wireName,
             deviceUuid: config.deviceUuid,
             deviceInfoJson: config.deviceInfo?.toRuntimeJson(),
+            framework: config.framework,
             preSessionEventPolicy: ApplePreSessionEventPolicy(
                 processEventsBeforeSessionStart: config.processEventsBeforeSessionStart,
                 queueLimitEvents: UInt64(max(0, config.preSessionEventQueueLimitEvents)),
@@ -56,6 +58,19 @@ final class UniFFIForgeRuntime: ForgeRuntime {
         outcome(bridge.setLogLevel(logLevel: level.wireName))
     }
 
+    func setAutoConnectionType(_ connectionType: String?) -> ForgeOutcome {
+        outcome(bridge.setAutoConnectionType(connectionType: connectionType))
+    }
+
+    func recordLocationFix(_ fix: ForgeLocationFix) -> ForgeOutcome {
+        outcome(bridge.recordLocationFix(
+            latitude: fix.latitude,
+            longitude: fix.longitude,
+            accuracyM: fix.accuracyMetres,
+            timestampMs: u64(fix.timestampMs)
+        ))
+    }
+
     func createVideoView(timestampMs: Int64, options: VideoOptions) -> RuntimeVideoView {
         RuntimeVideoView(id: Int64(clamping: bridge.createVideoView(
             nowMs: u64(timestampMs),
@@ -245,6 +260,33 @@ final class UniFFIForgeRuntime: ForgeRuntime {
         return result
     }
 
+    func setLogListener(_ listener: ((ForgeRenderedLog) -> Void)?) -> ForgeOutcome {
+        if let listener {
+            let callback = UniFFILogListener(callback: listener)
+            // Retain the wrapper before registering: the bridge replays the
+            // logs rendered before this point synchronously, and they must
+            // land in a wrapper the runtime keeps alive.
+            callbackLock.lock()
+            logListener = callback
+            callbackLock.unlock()
+            let result = outcome(bridge.setLogListener(listener: callback))
+            if !result.isAccepted {
+                callbackLock.lock()
+                logListener = nil
+                callbackLock.unlock()
+            }
+            return result
+        }
+
+        let result = outcome(bridge.clearLogListener())
+        if result.isAccepted {
+            callbackLock.lock()
+            logListener = nil
+            callbackLock.unlock()
+        }
+        return result
+    }
+
     func capturePlan() -> ForgeCapturePlan? {
         bridge.capturePlan().map(forgeCapturePlan)
     }
@@ -269,11 +311,13 @@ final class UniFFIForgeRuntime: ForgeRuntime {
     func destroy() -> ForgeOutcome {
         let result = outcome(bridge.destroy())
         _ = bridge.clearCapturePlanListener()
+        _ = bridge.clearLogListener()
         callbackLock.lock()
         contentMetadataProviders.removeAll()
         videoPreSendHooks.removeAll()
         sessionPreSendHook = nil
         capturePlanListener = nil
+        logListener = nil
         callbackLock.unlock()
         return result
     }
@@ -593,4 +637,19 @@ private final class UniFFICapturePlanListener: AppleCapturePlanListener, @unchec
         callback(forgeCapturePlan(plan))
     }
 }
+
+private final class UniFFILogListener: AppleLogListener, @unchecked Sendable {
+    private let callback: (ForgeRenderedLog) -> Void
+
+    init(callback: @escaping (ForgeRenderedLog) -> Void) {
+        self.callback = callback
+    }
+
+    func onLog(log: AppleRenderedLog) {
+        // An unrecognized level from the bridge is dropped rather than
+        // relabelled, matching ForgeLogger.emitRendered.
+        guard let level = ForgeLogLevel.parse(log.level) else { return }
+        callback(ForgeRenderedLog(level: level, tag: log.tag, message: log.message))
+    }
+}
 #endif

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

@@ -65,10 +65,26 @@ open class PlayerAdapter: NSObject {
         if playerObject != nil { registerListeners() }
     }
 
+    /// Detaches the adapter from its view.
+    ///
+    /// The unbind happens **before** the listeners are unregistered, and that
+    /// order is the whole point. Unregistering is not instantaneous from the
+    /// player's perspective: a KVO delivery already in flight on a player
+    /// thread, or a periodic-time-observer block already enqueued on the main
+    /// queue (which `removeTimeObserver` does not cancel), can still run while
+    /// it happens. With `videoAdapter` cleared first, `record` fails closed and
+    /// those late callbacks go nowhere.
+    ///
+    /// Clearing it afterwards is what produced the tvOS phantom view: a player
+    /// being deallocated reported a transport change into a view the kernel had
+    /// just stopped, and the kernel is contracted to treat a post-stop start as
+    /// a replay, so it opened an empty replacement view for every playback
+    /// (forge-feedback `native/2026-08-13_rn-video-teardown-reinits-view`).
     func unbindFromVideoAdapter() {
-        if isBound { unregisterListeners() }
+        let wasBound = isBound
         isBound = false
         videoAdapter = nil
+        if wasBound { unregisterListeners() }
     }
 
     open func registerListeners() {}

package/ios/ForgeInstanceRegistry.swift

@@ -0,0 +1,69 @@
+/**
+ * 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 lookup from a React Native instance id to the live Forge facade, so application code can attach a native adapter to a player the shipped packages do not cover.
+ */
+
+import Foundation
+#if canImport(NPAWForgeCore)
+import NPAWForgeCore
+#elseif canImport(NPAWForgeApple)
+import NPAWForgeApple
+#endif
+
+/// Resolves the native Forge facade behind a React Native instance id.
+///
+/// **This is public API.** `resolve` and `resolveVideoAdapter` carry the usual
+/// stability commitment: they will not be renamed or removed without a major
+/// version and a release note.
+///
+/// It exists because the React Native packages bind two players — Media3 on
+/// Android and AVPlayer on Apple, both through `react-native-video` — while
+/// Forge ships native adapters for many more. Rather than wait for a
+/// first-party package per player, application code can host its own native
+/// view, resolve the facade from the instance id it already has in JS, and
+/// attach any Forge adapter to it.
+///
+/// The React Native design deliberately keeps native player instances off the
+/// bridge, and this does not weaken that: only the opaque instance id crosses
+/// it. Resolution and attachment happen entirely in native code.
+///
+/// ```swift
+/// guard let forge = ForgeInstanceRegistry.resolve(instanceId),
+///       let video = forge.getVideoAdapter() else { return }
+/// video.setPlayerAdapter(MyPlayerAdapter(player: myPlayer))
+/// ```
+///
+/// Detach symmetrically when the view goes away — the registry holds the
+/// facade, not your player, and it will not release the adapter for you.
+///
+/// The Android counterpart is `com.npaw.forge.reactnative.ForgeInstanceRegistry`
+/// and carries the same two members with the same meaning.
+public enum ForgeInstanceRegistry {
+
+    /// The live facade for `instanceId`, or `nil` if no such instance exists
+    /// or it has already been destroyed.
+    public static func resolve(_ instanceId: String) -> NPAWForge? {
+        ForgeModuleImpl.shared.resolveInstance(instanceId)
+    }
+
+    /// The video adapter registered under `identifier` on the instance's
+    /// facade, or `nil` if either the instance or the adapter is absent.
+    ///
+    /// Pass `nil` for `identifier` to get the default adapter, matching
+    /// `NPAWForge.getVideoAdapter(identifier:)`.
+    public static func resolveVideoAdapter(
+        _ instanceId: String,
+        identifier: String? = nil
+    ) -> VideoAdapter? {
+        resolve(instanceId)?.getVideoAdapter(identifier: identifier)
+    }
+}

package/ios/ForgeModuleImpl.swift

@@ -33,15 +33,23 @@ public final class ForgeModuleImpl: NSObject {
 
     /// Set by the TurboModule shell; receives the channel body for every kernel event.
     @objc public var eventSink: (([String: Any]) -> Void)?
+    /// Set by the TurboModule shell; receives the channel body for every line
+    /// of the kernel's rendered decision log.
+    @objc public var logSink: (([String: Any]) -> Void)?
 
     private let lock = NSLock()
     private var instances: [String: NPAWForge] = [:]
     private var subscriptions: [String: ForgeEventSubscription] = [:]
+    private var logSubscriptions: [String: ForgeEventSubscription] = [:]
     private var adReporters: [Int: ManualAdReporter] = [:]
     private var nextInstanceId = 1
     private var nextReporterId = 1
     private var listenerCount = 0
 
+    /// Declared to the native facade so React Native traffic is
+    /// distinguishable in `pluginInfo`; the reported platform stays `apple`.
+    static let frameworkMarker = "react-native"
+
     private static let errUnknownInstance = "E_FORGE_UNKNOWN_INSTANCE"
     private static let errUnknownReporter = "E_FORGE_UNKNOWN_REPORTER"
     private static let errBadArgument = "E_FORGE_BAD_ARGUMENT"
@@ -71,6 +79,8 @@ public final class ForgeModuleImpl: NSObject {
             return
         }
         let builder = NPAWForge.Builder(accountCode: accountCode)
+        // The binding knows what it is; this is not a host-settable config key.
+        builder.setFramework(ForgeModuleImpl.frameworkMarker)
         applyConfig(builder, config: config)
         let forge = builder.build()
 
@@ -95,6 +105,7 @@ public final class ForgeModuleImpl: NSObject {
         lock.lock()
         let forge = instances.removeValue(forKey: instanceId)
         let subscription = subscriptions.removeValue(forKey: instanceId)
+        let logSubscription = logSubscriptions.removeValue(forKey: instanceId)
         lock.unlock()
 
         guard let forge else {
@@ -102,6 +113,7 @@ public final class ForgeModuleImpl: NSObject {
             return
         }
         subscription?.cancel()
+        logSubscription?.cancel()
         resolve(Self.outcomeToDictionary(forge.destroy()))
     }
 
@@ -901,8 +913,13 @@ public final class ForgeModuleImpl: NSObject {
         lock.lock()
         listenerCount = max(0, listenerCount - count)
         let shouldCancel = listenerCount == 0
-        let cancelled = shouldCancel ? Array(subscriptions.values) : []
-        if shouldCancel { subscriptions.removeAll() }
+        let cancelled = shouldCancel
+            ? Array(subscriptions.values) + Array(logSubscriptions.values)
+            : []
+        if shouldCancel {
+            subscriptions.removeAll()
+            logSubscriptions.removeAll()
+        }
         lock.unlock()
 
         cancelled.forEach { $0.cancel() }
@@ -910,9 +927,10 @@ public final class ForgeModuleImpl: NSObject {
 
     @objc public func invalidate() {
         lock.lock()
-        let cancelled = Array(subscriptions.values)
+        let cancelled = Array(subscriptions.values) + Array(logSubscriptions.values)
         let live = Array(instances.values)
         subscriptions.removeAll()
+        logSubscriptions.removeAll()
         instances.removeAll()
         adReporters.removeAll()
         listenerCount = 0
@@ -991,8 +1009,15 @@ public final class ForgeModuleImpl: NSObject {
             guard let self, let sink = self.eventSink else { return }
             sink(Self.recordedEventToDictionary(instanceId: instanceId, event: event))
         }
+        // The kernel's decision log rides its own channel: it is not an event,
+        // and hosts subscribe to it separately.
+        let logSubscription = forge.addLogListener { [weak self] log in
+            guard let self, let sink = self.logSink else { return }
+            sink(Self.renderedLogToDictionary(instanceId: instanceId, log: log))
+        }
         lock.lock()
         subscriptions[instanceId] = subscription
+        logSubscriptions[instanceId] = logSubscription
         lock.unlock()
     }
 
@@ -1022,9 +1047,19 @@ public final class ForgeModuleImpl: NSObject {
                 builder.setPreSessionEventQueueMaxAgeMs((value as? NSNumber)?.int64Value ?? 0)
             case "allowLocalHttpForTesting":
                 builder.setLocalPlaintextTransportForTesting(value as? Bool ?? false)
-            case "deviceUuid", "autoDeviceIdentityEnabled":
-                // Android-only today: the Swift Builder lacks these setters.
-                NSLog("[NPAWForgeRN] ForgeConfig key '%@' is Android-only; ignored on iOS", key)
+            case "deviceUuid":
+                // A non-string value is ignored rather than used to clear the
+                // override: passing nil here would disable an identifier the
+                // app did configure.
+                if let deviceUuid = value as? String {
+                    builder.setDeviceUuid(deviceUuid)
+                }
+            case "autoDeviceIdentityEnabled":
+                // Matches the Android mapper: a real Bool wins, anything else
+                // is parsed leniently and falls back to false.
+                builder.setAutoDeviceIdentityEnabled(
+                    value as? Bool ?? (String(describing: value).lowercased() == "true")
+                )
             default:
                 NSLog("[NPAWForgeRN] Unknown ForgeConfig key '%@' ignored (forward compatibility)", key)
             }
@@ -1128,4 +1163,16 @@ public final class ForgeModuleImpl: NSObject {
         }
         return result
     }
+
+    static func renderedLogToDictionary(
+        instanceId: String,
+        log: ForgeRenderedLog
+    ) -> [String: Any] {
+        [
+            "instanceId": instanceId,
+            "level": log.level.wireName,
+            "tag": log.tag,
+            "message": log.message,
+        ]
+    }
 }

package/ios/NPAWForgeTurboModule.mm

@@ -25,6 +25,7 @@
 #endif
 
 static NSString *const kForgeEventChannel = @"NPAWForgeEvent";
+static NSString *const kForgeLogChannel = @"NPAWForgeLog";
 
 @interface NPAWForgeReactNative : RCTEventEmitter
 #ifdef RCT_NEW_ARCH_ENABLED
@@ -48,13 +49,16 @@ RCT_EXPORT_MODULE(NPAWForgeRN)
     ForgeModuleImpl.shared.eventSink = ^(NSDictionary<NSString *, id> *body) {
       [weakSelf sendEventWithName:kForgeEventChannel body:body];
     };
+    ForgeModuleImpl.shared.logSink = ^(NSDictionary<NSString *, id> *body) {
+      [weakSelf sendEventWithName:kForgeLogChannel body:body];
+    };
   }
   return self;
 }
 
 - (NSArray<NSString *> *)supportedEvents
 {
-  return @[ kForgeEventChannel ];
+  return @[ kForgeEventChannel, kForgeLogChannel ];
 }
 
 - (void)startObserving
@@ -70,6 +74,7 @@ RCT_EXPORT_MODULE(NPAWForgeRN)
 - (void)invalidate
 {
   ForgeModuleImpl.shared.eventSink = nil;
+  ForgeModuleImpl.shared.logSink = nil;
   [ForgeModuleImpl.shared invalidate];
   [super invalidate];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@npaw/forge-react-native",
-  "version": "9.7.1",
+  "version": "9.7.3",
   "description": "NPAW Forge analytics for React Native: New Architecture TurboModule facade over the native Forge Android/Apple SDKs.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Victor Soto <victor.soto@nicepeopleatwork.com>",
@@ -11,7 +11,9 @@
     "NPAWForgeReactNative.podspec",
     "README.md",
     "android",
+    "app.plugin.js",
     "ios",
+    "plugin",
     "src"
   ],
   "scripts": {

package/plugin/index.js

@@ -0,0 +1,82 @@
+/**
+ * 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: Expo config plugin wiring the Forge host-project mutations into expo prebuild; all mutation logic lives in ./mutations.js so it is testable without Expo installed.
+ */
+
+'use strict';
+
+const { addForgeMavenRepository, addKotlinMetadataFlag } = require('./mutations');
+
+/**
+ * @typedef {object} ForgePluginOptions
+ * @property {boolean} [artifactoryRepository=true] Add the NPAW Artifactory Maven repository.
+ * @property {boolean} [kotlinMetadataFlag=true] Add `-Xskip-metadata-version-check` to the app module.
+ */
+
+/**
+ * Applies the native host-project changes the Forge React Native packages need.
+ *
+ * Expo Go cannot load native modules, so this is for development builds and
+ * `expo prebuild`; it does not make Forge work in Expo Go. Every mutation is
+ * idempotent because prebuild runs repeatedly.
+ *
+ * ```json
+ * { "expo": { "plugins": ["@npaw/forge-react-native"] } }
+ * ```
+ *
+ * This does NOT disable bridgeless. That is a source-level change in
+ * MainApplication and AppDelegate — see ./mutations.js for why automating it
+ * would do more harm than good — and it stays a documented manual step for
+ * applications using the video adapter package.
+ */
+function withForge(config, options = {}) {
+  const { withProjectBuildGradle, withAppBuildGradle } = require('@expo/config-plugins');
+
+  const settings = {
+    artifactoryRepository: true,
+    kotlinMetadataFlag: true,
+    ...options,
+  };
+
+  let next = config;
+
+  if (settings.artifactoryRepository) {
+    next = withProjectBuildGradle(next, (mod) => {
+      if (mod.modResults.language !== 'groovy') {
+        throw new Error(
+          'Forge config plugin: the project build.gradle is not Groovy; apply the Maven repository manually',
+        );
+      }
+      mod.modResults.contents = addForgeMavenRepository(mod.modResults.contents);
+      return mod;
+    });
+  }
+
+  if (settings.kotlinMetadataFlag) {
+    next = withAppBuildGradle(next, (mod) => {
+      if (mod.modResults.language !== 'groovy') {
+        throw new Error(
+          'Forge config plugin: the app build.gradle is not Groovy; apply the Kotlin flag manually',
+        );
+      }
+      mod.modResults.contents = addKotlinMetadataFlag(mod.modResults.contents);
+      return mod;
+    });
+  }
+
+  return next;
+}
+
+module.exports = withForge;
+module.exports.default = withForge;
+// Re-exported so host projects and tests can reuse the raw mutations.
+module.exports.mutations = { addForgeMavenRepository, addKotlinMetadataFlag };