@react-native-firebase/app 26.4.0 → 27.0.0

package/firebase_spm.rb

@@ -17,10 +17,30 @@
 # limitations under the License.
 #
 
+require 'digest'
 require 'json'
 
 RNFIREBASE_SPM_EMBED_PHASE_NAME = '[RNFB] Embed Firebase SPM Frameworks'
 RNFIREBASE_SPM_SIGNATURE_FIX_PHASE_NAME = '[RNFB] Remove duplicate Firebase/Google SPM binary xcframework signature files' # rubocop:disable Layout/LineLength
+RNFIREBASE_SPM_UMBRELLA_PRODUCT = 'RNFBFirebase'
+# Pods aggregate used only by the dynamic probe. It orders the facade product
+# ahead of RNFBApp. It is not an RNFBApp package-product dependency, so Xcode
+# does not copy transitive Firebase module maps onto that pod.
+RNFIREBASE_SPM_PROBE_ORDER_TARGET = 'RNFBFirebaseProbeOrder'
+# Swift compilation condition (`#if RNFB_DYNAMIC_FIREBASE_PROBE`) that selects
+# the `import RNFBFirebase` facade path in RNFBApp and the test-rn-bare
+# AppDelegate. It is the Swift twin of the `RNFB_DYNAMIC_FIREBASE_PROBE=1`
+# GCC preprocessor define and is only set while the probe is on.
+RNFIREBASE_SPM_PROBE_SWIFT_CONDITION = 'RNFB_DYNAMIC_FIREBASE_PROBE'
+RNFIREBASE_SWIFT_CONDITIONS_SETTING = 'SWIFT_ACTIVE_COMPILATION_CONDITIONS'
+
+# CI probe only: when `RNFB_TEST_RN_BARE_DYNAMIC_FIREBASE=1`, `firebase_dependency`
+# and the app-target link helpers resolve Firebase through the local dynamic
+# package at `packages/app/ios/RNFBFirebase` instead of remote `firebase-ios-sdk`.
+# Default (unset / any other value) keeps the shipped direct `firebase-ios-sdk` path.
+def rnfirebase_probe_dynamic_firebase?
+  ENV.fetch('RNFB_TEST_RN_BARE_DYNAMIC_FIREBASE', '') == '1'
+end
 
 # Every `.binaryTarget` xcframework name reachable in the resolved SPM package
 # graph for the RNFB test app (firebase-ios-sdk 12.16.0, full module set --
@@ -76,16 +96,32 @@ module RNFirebaseSPM
       end
     end
 
+    # Absolute path is intentional: React Native's SPM manager recognizes a
+    # local package with `File.exist?`, then writes an XCLocalSwiftPackageReference.
+    def umbrella_path
+      File.join(__dir__, 'ios', RNFIREBASE_SPM_UMBRELLA_PRODUCT)
+    end
+
     # Records that `firebase_dependency` (below) took the SPM path for at
     # least one podspec in this install, and which Firebase SDK `version` it
     # resolved with. Called once, from `firebase_dependency` itself, the
     # first time it successfully takes the SPM path. `version` is stored so
-    # `rnfirebase_add_spm_core_to_app_target` can declare the same minimum
+    # `rnfirebase_add_spm_core_to_app_target` can declare the same exact
     # version requirement on the app target's own FirebaseCore product
     # dependency, without needing its own separate copy of it.
-    def activate!(version)
+    #
+    # `mode:` is `:remote` (shipped `firebase-ios-sdk`) or `:umbrella` (CI probe
+    # local `RNFBFirebase` dynamic package).
+    def activate!(version, mode: :remote)
       @active = true
       @version = version
+      @mode = mode
+    end
+
+    # True when this install resolved Firebase through the local dynamic probe
+    # package rather than remote `firebase-ios-sdk`.
+    def umbrella?
+      active? && @mode == :umbrella
     end
 
     # Whether SPM is active for this install -- read by every `rnfirebase_*`
@@ -96,7 +132,7 @@ module RNFirebaseSPM
     # without going through `activate!` above (e.g. a future refactor that
     # assigns the flag directly instead of calling it), and every downstream
     # helper that trusts this return value -- including one that links
-    # FirebaseCore into the app target at a specific minimum version -- would
+    # FirebaseCore into the app target at a specific exact version -- would
     # silently operate on incomplete state instead. Raising `Pod::Informative`
     # here (this file's own user-facing `pod install`-time error class, same
     # as `rnfirebase_fail_if_spm_static_linkage!` below) turns that into a
@@ -117,7 +153,7 @@ module RNFirebaseSPM
 
     # The Firebase SDK version `firebase_dependency` resolved with, recorded
     # by `activate!` above -- used by `rnfirebase_add_spm_core_to_app_target`
-    # to declare the same minimum version requirement on the app target's own
+    # to declare the same exact version requirement on the app target's own
     # FirebaseCore product dependency.
     attr_reader :version
 
@@ -133,20 +169,20 @@ module RNFirebaseSPM
       @active = nil
       @version = nil
       @url = nil
+      @mode = nil
     end
   end
 end
 
-# Helper to declare Firebase dependencies with SPM support and CocoaPods fallback.
+# Helper to declare Firebase dependencies via Swift Package Manager.
 #
 # When `spm_dependency` is available (React Native >= 0.75), it declares the
-# Firebase iOS SDK as a Swift Package dependency. Otherwise, it falls back to
-# the traditional CocoaPods `s.dependency` declaration.
+# Firebase iOS SDK as a Swift Package dependency.
 #
-# Set `$RNFirebaseDisableSPM = true` in your Podfile to force CocoaPods-only
-# dependency resolution. You must disable SPM when using `use_frameworks! :linkage => :static`
-# because static frameworks cause each pod to embed Firebase SPM products,
-# resulting in duplicate symbol linker errors.
+# Firebase Apple SDK 13+ is distributed exclusively through SPM and binary
+# zips — CocoaPods trunk stopped at 12.19.0. `$RNFirebaseDisableSPM = true`
+# and Expo `disableSPM: true` therefore fail `pod install` / prebuild loudly
+# instead of declaring missing CocoaPods Firebase 13 pods.
 #
 # firebase-ios-sdk SPM products are plain `.library(...)` (automatic linkage),
 # not `.library(type: .dynamic)`. See:
@@ -156,7 +192,7 @@ end
 # build and run; static pod linkage collides those per-pod copies at link time.
 # Dynamic pods avoid the link failure but still embed a private copy per pod,
 # so third-party pods cannot share one FirebaseCore/FirebaseApp with RNFB
-# under SPM (use `$RNFirebaseDisableSPM = true` + CocoaPods for that).
+# under SPM.
 #
 # Returns true only when `$RNFirebaseDisableSPM` has been explicitly set to `true`.
 #
@@ -167,6 +203,22 @@ def rnfirebase_spm_disabled?
   defined?($RNFirebaseDisableSPM) && $RNFirebaseDisableSPM == true
 end
 
+# User-facing error when a Podfile or Expo config asks for CocoaPods Firebase
+# (DisableSPM / missing `spm_dependency`). Firebase 13+ is SPM-only.
+def rnfirebase_fail_cocoapods_firebase!(reason)
+  raise Pod::Informative, <<~MESSAGE
+    [react-native-firebase] Firebase Apple SDK is no longer distributed through CocoaPods (#{reason}).
+
+    Firebase 13.0.0 and later ship exclusively via Swift Package Manager and binary distributions. React Native Firebase resolves Firebase through SPM and requires:
+
+      use_frameworks! :linkage => :dynamic
+
+    Remove `$RNFirebaseDisableSPM = true` from your Podfile (and Expo `ios.disableSPM` / `disableSPM: true` from the `@react-native-firebase/app` config plugin). React Native 0.75+ is required for `spm_dependency`.
+
+    See https://rnfirebase.io/ios-spm and https://firebase.google.com/docs/ios/cocoapods-deprecation
+  MESSAGE
+end
+
 # Normalizes a build setting value that Xcode/Xcodeproj may represent as
 # `nil`, a whitespace-separated `String`, or an `Array` into a plain `Array`
 # safe to call `include?`/`push`/`<<` on. Settings like `OTHER_LDFLAGS` or
@@ -185,6 +237,119 @@ def rnfirebase_build_setting_list(current)
   end
 end
 
+# Adds (`enabled`) or removes (`!enabled`) the probe Swift compilation
+# condition on one `build_settings` hash. Never duplicates the entry, and keeps
+# every other condition and the value's form: a non-empty Array stays an Array
+# (token appended / removed), anything else is a space-joined String. Returns
+# whether the hash changed.
+#
+# Removal restores what the add path started from, without persisted state:
+# - Array value: add never writes an Array for an unset value, so an Array is
+#   an authored value. Only the token is removed; an explicit `$(inherited)`
+#   stays.
+# - String value: add writes `$(inherited) <token>` for an unset value, which
+#   is indistinguishable from an authored `$(inherited)` once the token is
+#   there. Removal treats a remainder of exactly `$(inherited)` as "was unset"
+#   and deletes the key, so a project that never had the setting (the checked-in
+#   `testrnbare`) is byte-identical after a probe then flag-off round trip. An
+#   authored String `$(inherited)` therefore becomes unset, which resolves to
+#   the same compilation conditions.
+# - A remainder with no entries left deletes the key.
+# - String values are split on whitespace and re-joined with single spaces on
+#   add, so an authored String with tabs or repeated spaces is normalized, not
+#   byte-exact, after a probe then flag-off round trip. This only happens in
+#   probe mode, the checked-in `testrnbare` has no such setting, and the
+#   resolved value is unchanged.
+def rnfirebase_set_probe_swift_condition(build_settings, enabled) # rubocop:disable Naming/PredicateMethod
+  key = RNFIREBASE_SWIFT_CONDITIONS_SETTING
+  condition = RNFIREBASE_SPM_PROBE_SWIFT_CONDITION
+  original = build_settings[key]
+  current = rnfirebase_build_setting_list(original)
+  array_form = original.is_a?(Array) && !original.empty?
+  write = ->(entries) { build_settings[key] = array_form ? entries : entries.join(' ') }
+
+  if enabled
+    return false if current.include?(condition)
+
+    write.call(current << condition)
+    return true
+  end
+
+  return false unless current.include?(condition)
+
+  remaining = current.reject { |entry| entry == condition }
+  if remaining.empty? || (!array_form && remaining == ['$(inherited)'])
+    build_settings.delete(key)
+  else
+    write.call(remaining)
+  end
+  true
+end
+
+# Exact firebase-ios-sdk SPM requirement. CocoaPods already pins `version`
+# exactly via `spec.dependency pod, version`. SPM used to declare
+# `upToNextMajorVersion`, which lets Xcode resolve a newer 12.x than
+# `sdkVersions.ios.firebase`. `{ kind: 'exactVersion', version: version }`
+# is the Xcode/xcodeproj requirement hash RN's `spm_dependency` passes
+# through unchanged.
+def rnfirebase_spm_package_requirement(version)
+  { kind: 'exactVersion', version: version }
+end
+
+# Xcodeproj assigns a fresh random UUID on every `project.new`. The dynamic
+# probe removes the app target's FirebaseCore package reference, product
+# dependency, and PBXBuildFile, and a later normal install creates them
+# again. Random IDs would rewrite a committed pbxproj on that round trip.
+# These IDs are a pure function of the object role, so recreation writes the
+# same objects the fixture already has.
+def rnfirebase_stable_object_uuid(key)
+  Digest::SHA256.hexdigest("react-native-firebase/spm/#{key}")[0, 24].upcase
+end
+
+def rnfirebase_assign_stable_uuid!(project, object, key)
+  return unless project.respond_to?(:objects_by_uuid)
+  return unless object.respond_to?(:uuid) && !object.uuid.nil?
+
+  uuid = rnfirebase_stable_object_uuid(key)
+  return if object.uuid == uuid
+
+  objects = project.objects_by_uuid
+  # Never steal an unrelated object's id. A collision keeps the random UUID
+  # from `project.new` rather than corrupting the project.
+  return if objects[uuid] && !objects[uuid].equal?(object)
+
+  objects.delete(object.uuid)
+  object.instance_variable_set(:@uuid, uuid)
+  objects[uuid] = object
+end
+
+def rnfirebase_stable_package_uuid_key(umbrella)
+  if umbrella
+    "local-package:#{RNFIREBASE_SPM_UMBRELLA_PRODUCT}"
+  else
+    "remote-package:#{RNFirebaseSPM.url}"
+  end
+end
+
+# Rewrites a leftover `upToNextMajorVersion` (or any other kind) on an
+# existing `XCRemoteSwiftPackageReference` to the exact pin. Returns true
+# when the requirement changed so callers can mark the project dirty.
+def rnfirebase_pin_spm_package_requirement!(pkg, version = RNFirebaseSPM.version) # rubocop:disable Naming/PredicateMethod
+  return false if pkg.nil? || !pkg.respond_to?(:requirement=)
+
+  desired = rnfirebase_spm_package_requirement(version)
+  return false if pkg.requirement == desired
+
+  pkg.requirement = desired
+  true
+end
+
+# True for RNFB CocoaPods targets (`RNFBApp`, `RNFBAnalytics`, ...). Used to
+# apply `-ObjC` on the pod that statically absorbs Analytics/Measurement.
+def rnfirebase_rnfb_pod_target?(target)
+  target.respond_to?(:name) && target.name.to_s.start_with?('RNFB')
+end
+
 def rnfirebase_spm_embed_script
   <<~'SCRIPT'
     set -euo pipefail
@@ -220,8 +385,15 @@ def rnfirebase_spm_embed_script
         # Deliberate tradeoff: match `file -b` prose for "dynamically linked"
         # rather than inspecting Mach-O magic bytes. Locale-independent in
         # practice on Apple's `file`, but still a CLI string match.
-        if [ ! -f "${framework}/${binary_name}" ] || \
-           ! file -b "${framework}/${binary_name}" | grep -q 'dynamically linked'; then
+        file_description=""
+        if [ -f "${framework}/${binary_name}" ]; then
+          file_description="$(file -b "${framework}/${binary_name}")"
+        fi
+        # Do not use `file ... | grep -q` here. Under this script's
+        # `set -o pipefail`, `grep -q` exits after the first matching line of
+        # a multi-line universal-binary description, `file` receives SIGPIPE,
+        # and the otherwise-successful pipeline becomes false.
+        if [[ "${file_description}" != *"dynamically linked"* ]]; then
           echo "Skipping ${framework_name}: binary missing or not dynamically linked"
           continue
         fi
@@ -405,8 +577,7 @@ end
 # (`duplicate symbol`). Under dynamic pod linkage the app builds, but each
 # dynamic framework still keeps a private copy (runtime class duplication /
 # split FirebaseApp registries). There is no supported combination of RNFB's
-# SPM mode with static linkage; the fix is always to switch to dynamic
-# linkage or opt out of SPM entirely.
+# SPM mode with static linkage; the fix is to switch to dynamic linkage.
 #
 # Raises `Pod::Informative` -- CocoaPods' own user-facing error class, which
 # `pod install` prints as a plain, readable message with no Ruby backtrace --
@@ -432,16 +603,40 @@ def rnfirebase_fail_if_spm_static_linkage!(installer)
   end
   return if static_targets.empty?
 
-  target_names = static_targets.map(&:name).join(', ')
+  # `build_type.static?` is true for two different Podfiles: no
+  # `use_frameworks!` at all (CocoaPods' default static libraries -- the stock
+  # React Native / bare Expo Podfile) and `use_frameworks! :linkage => :static`.
+  # Name the one the user actually has so they can find it in their Podfile.
+  library_targets, framework_targets = static_targets.partition do |target|
+    !target.target_definition.uses_frameworks?
+  end
+  detected = []
+  unless library_targets.empty?
+    library_label = 'no `use_frameworks!` (or `use_frameworks! false`) -- pods build as static libraries'
+    detected << "  - #{library_label}: #{library_targets.map(&:name).join(', ')}"
+  end
+  unless framework_targets.empty?
+    framework_label = '`use_frameworks! :linkage => :static` ' \
+                      '(incl. `USE_FRAMEWORKS=static` / Expo `useFrameworks: "static"`)'
+    detected << "  - #{framework_label}: #{framework_targets.map(&:name).join(', ')}"
+  end
 
   raise Pod::Informative, <<~MESSAGE
-    [react-native-firebase] SPM + static linkage is not supported (target(s): #{target_names}).
+    [react-native-firebase] SPM + static linkage is not supported.
+
+    Detected static pod linkage:
+    #{detected.join("\n")}
 
-    firebase-ios-sdk's Swift Package products are automatic libraries (not `type: .dynamic`), so each react-native-firebase pod that resolves Firebase via SPM embeds its own copy. With `use_frameworks! :linkage => :static` those copies collide at link time as duplicate-symbol errors.
+    firebase-ios-sdk's Swift Package products are automatic libraries (not `type: .dynamic`), so each react-native-firebase pod that resolves Firebase via SPM embeds its own copy. With static pod linkage those copies collide at link time as duplicate-symbol errors.
 
-    Fix one of the following in your Podfile, then run `pod install` again:
-      - Use dynamic linkage: `use_frameworks! :linkage => :dynamic`
-      - Opt out of SPM: set `$RNFirebaseDisableSPM = true` before any target block, then use the static or dynamic linkage your project requires.
+    Fix your Podfile to use dynamic linkage, then run `pod install` again:
+
+      use_frameworks! :linkage => :dynamic
+
+    With the stock template Podfile you can instead run `USE_FRAMEWORKS=dynamic pod install`, but it must be set for every `pod install` (including CI) or linkage reverts to static; the Podfile line above is the durable fix.
+    Expo: set `ios.useFrameworks` to `"dynamic"` in the `expo-build-properties` plugin config, then re-run `npx expo prebuild`. Only if you maintain `ios/` by hand (no prebuild), set `"ios.useFrameworks": "dynamic"` in `ios/Podfile.properties.json`.
+
+    See https://rnfirebase.io/ios-spm
   MESSAGE
 end
 
@@ -589,7 +784,8 @@ def rnfirebase_run_spm_user_project_hooks(installer)
     rnfirebase_add_spm_core_to_app_target(installer)
   rescue StandardError => e
     if defined?(Pod::UI)
-      Pod::UI.warn "[react-native-firebase] Couldn't link FirebaseCore into the app target " \
+      product = RNFirebaseSPM.umbrella? ? RNFIREBASE_SPM_UMBRELLA_PRODUCT : 'FirebaseCore'
+      Pod::UI.warn "[react-native-firebase] Couldn't link #{product} into the app target " \
                    "automatically (#{e.class}: #{e.message}). " \
                    'Add `rnfirebase_add_spm_core_to_app_target(installer)` ' \
                    'to your Podfile\'s post_integrate block as a fallback if your own native code calls ' \
@@ -600,10 +796,10 @@ def rnfirebase_run_spm_user_project_hooks(installer)
     rnfirebase_remove_spm_core_from_app_target(installer)
   rescue StandardError => e
     if defined?(Pod::UI)
-      Pod::UI.warn "[react-native-firebase] Couldn't remove a stale FirebaseCore SPM link from the " \
+      Pod::UI.warn "[react-native-firebase] Couldn't remove a stale Firebase SPM link from the " \
                    "app target automatically (#{e.class}: #{e.message}). If you previously used SPM and have " \
-                   'since set `$RNFirebaseDisableSPM = true`, remove the "firebase-ios-sdk" Swift Package ' \
-                   'dependency from your app target manually in Xcode.'
+                   'since set `$RNFirebaseDisableSPM = true`, remove the firebase-ios-sdk / RNFBFirebase Swift ' \
+                   'Package dependency from your app target manually in Xcode.'
     end
   end
   begin
@@ -630,6 +826,14 @@ def rnfirebase_run_spm_user_project_hooks(installer)
                    '`FirebaseCoreInternal`/`FirebaseSharedSwift` cannot be resolved.'
     end
   end
+  begin
+    rnfirebase_sync_probe_swift_condition_on_app_targets(installer)
+  rescue StandardError => e
+    if defined?(Pod::UI)
+      Pod::UI.warn "[react-native-firebase] Couldn't sync the #{RNFIREBASE_SPM_PROBE_SWIFT_CONDITION} Swift " \
+                   "compilation condition on the app target (#{e.class}: #{e.message})."
+    end
+  end
 end
 
 # We wrap `Pod::Installer#generate_pods_project` (restore RNFB dynamic
@@ -819,12 +1023,13 @@ rescue StandardError => e
   end
 end
 
-# Adds a direct SPM product dependency on `FirebaseCore` to the *app's own*
-# native target(s) -- not just RNFB's pod targets. Runs automatically on every
-# `pod install`/`pod update` from `rnfirebase_run_spm_user_project_hooks`
-# (post_integrate on current CocoaPods; post_install fallback otherwise) --
-# see `rnfirebase_hook_cocoapods_post_install!` -- so you normally never
-# need to call this yourself.
+# Adds a direct SPM product dependency on `FirebaseCore` (shipped path) or the
+# local `RNFBFirebase` probe product to the *app's own* native target(s) -- not
+# just RNFB's pod targets. Runs automatically on every `pod install`/`pod update`
+# from `rnfirebase_run_spm_user_project_hooks` (post_integrate on current
+# CocoaPods; post_install fallback otherwise) -- see
+# `rnfirebase_hook_cocoapods_post_install!` -- so you normally never need to
+# call this yourself.
 #
 # Why this needs to exist: every react-native-firebase app is required to
 # `import Firebase` and call `FirebaseApp.configure()` (Swift) /
@@ -844,8 +1049,14 @@ end
 def rnfirebase_add_spm_core_to_app_target(installer)
   return unless RNFirebaseSPM.active?
 
-  pkg_class = Xcodeproj::Project::Object::XCRemoteSwiftPackageReference
+  umbrella = RNFirebaseSPM.umbrella?
+  pkg_class = if umbrella
+                Xcodeproj::Project::Object::XCLocalSwiftPackageReference
+              else
+                Xcodeproj::Project::Object::XCRemoteSwiftPackageReference
+              end
   ref_class = Xcodeproj::Project::Object::XCSwiftPackageProductDependency
+  product_name = umbrella ? RNFIREBASE_SPM_UMBRELLA_PRODUCT : 'FirebaseCore'
 
   installer.aggregate_targets.each do |aggregate_target|
     project = aggregate_target.user_project
@@ -856,17 +1067,22 @@ def rnfirebase_add_spm_core_to_app_target(installer)
       next unless target.respond_to?(:shell_script_build_phases)
       next unless target.shell_script_build_phases.any? { |phase| phase.name == '[CP] Embed Pods Frameworks' }
 
-      # A `FirebaseCore` product dependency already being declared on the
-      # target does *not* by itself mean this target is a genuine no-op:
-      # a pre-fix RNFB version could have committed that dependency into
-      # the consumer's `.pbxproj` without ever linking it (see the
-      # PBXBuildFile comment below) -- that's the exact broken state #9158
-      # reports, and it's already sitting in every affected consumer's
-      # project today. So checking `package_product_dependencies` alone
-      # can't tell that already-affected state apart from a healthy,
-      # already-linked one -- it has to check the build phase itself.
-      existing_ref = target.package_product_dependencies.find { |dep| dep.product_name == 'FirebaseCore' }
+      # A product dependency already being declared on the target does *not*
+      # by itself mean this target is a genuine no-op: a pre-fix RNFB version
+      # could have committed that dependency into the consumer's `.pbxproj`
+      # without ever linking it (see the PBXBuildFile comment below) -- that's
+      # the exact broken state #9158 reports, and it's already sitting in every
+      # affected consumer's project today. So checking
+      # `package_product_dependencies` alone can't tell that already-affected
+      # state apart from a healthy, already-linked one -- it has to check the
+      # build phase itself.
+      existing_ref = target.package_product_dependencies.find { |dep| dep.product_name == product_name }
       if existing_ref
+        # Pin even when the link is already healthy: a prior RNFB version
+        # may have committed `upToNextMajorVersion` on this package
+        # reference, and leaving that kind in place lets SPM float.
+        # Local packages have no requirement to pin.
+        project_modified ||= rnfirebase_pin_spm_package_requirement!(existing_ref.package) unless umbrella
         next if target.frameworks_build_phase.files.any? { |bf| bf.product_ref == existing_ref }
 
         # Healing path: reuse the dependency (and its package reference)
@@ -875,28 +1091,40 @@ def rnfirebase_add_spm_core_to_app_target(installer)
         ref = existing_ref
       else
         pkg = project.root_object.package_references.find do |candidate|
-          candidate.instance_of?(pkg_class) && candidate.repositoryURL == RNFirebaseSPM.url
+          if umbrella
+            candidate.instance_of?(pkg_class) && candidate.relative_path == RNFirebaseSPM.umbrella_path
+          else
+            candidate.instance_of?(pkg_class) && candidate.repositoryURL == RNFirebaseSPM.url
+          end
         end
-        unless pkg
+        if pkg
+          project_modified ||= rnfirebase_pin_spm_package_requirement!(pkg) unless umbrella
+        else
           pkg = project.new(pkg_class)
-          pkg.repositoryURL = RNFirebaseSPM.url
-          pkg.requirement = { kind: 'upToNextMajorVersion', minimumVersion: RNFirebaseSPM.version }
+          rnfirebase_assign_stable_uuid!(project, pkg, rnfirebase_stable_package_uuid_key(umbrella))
+          if umbrella
+            pkg.relative_path = RNFirebaseSPM.umbrella_path
+          else
+            pkg.repositoryURL = RNFirebaseSPM.url
+            pkg.requirement = rnfirebase_spm_package_requirement(RNFirebaseSPM.version)
+          end
           project.root_object.package_references << pkg
         end
 
         ref = project.new(ref_class)
+        rnfirebase_assign_stable_uuid!(project, ref, "product-dependency:#{target.name}:#{product_name}")
         ref.package = pkg
-        ref.product_name = 'FirebaseCore'
+        ref.product_name = product_name
         target.package_product_dependencies << ref
       end
 
       if defined?(Pod::UI)
         message = if existing_ref
-                    'Repairing FirebaseCore SPM link on the app target (dependency was already declared but ' \
+                    "Repairing #{product_name} SPM link on the app target (dependency was already declared but " \
                       'never linked) so native code that calls FIRApp/FIROptions APIs directly can resolve ' \
                       'those symbols.'
                   else
-                    'Linking FirebaseCore directly into the app target (SPM) so native code that calls ' \
+                    "Linking #{product_name} directly into the app target (SPM) so native code that calls " \
                       'FIRApp/FIROptions APIs directly can resolve those symbols.'
                   end
         Pod::UI.puts "[react-native-firebase] #{target.name}: ".yellow + message
@@ -914,6 +1142,7 @@ def rnfirebase_add_spm_core_to_app_target(installer)
       # directly (e.g. Expo's generated AppDelegate) -- even though `pod
       # install` itself appears to succeed.
       build_file = project.new(Xcodeproj::Project::Object::PBXBuildFile)
+      rnfirebase_assign_stable_uuid!(project, build_file, "build-file:#{target.name}:#{product_name}")
       build_file.product_ref = ref
       target.frameworks_build_phase.files << build_file
 
@@ -965,11 +1194,17 @@ end
 # 'Firebase'` at compile time, and as duplicate App-Intents-metadata build
 # commands at Archive time.
 def rnfirebase_remove_spm_core_from_app_target(installer)
-  return if RNFirebaseSPM.active?
-
-  pkg_class = Xcodeproj::Project::Object::XCRemoteSwiftPackageReference
+  remote_pkg_class = Xcodeproj::Project::Object::XCRemoteSwiftPackageReference
+  local_pkg_class = Xcodeproj::Project::Object::XCLocalSwiftPackageReference
   ref_class = Xcodeproj::Project::Object::XCSwiftPackageProductDependency
 
+  # When the probe umbrella is active, drop a superseded direct FirebaseCore
+  # remote link. When shipped remote SPM is active, drop a leftover local
+  # RNFBFirebase probe link. When SPM is off, drop both.
+  remove_remote_core = !RNFirebaseSPM.active? || RNFirebaseSPM.umbrella?
+  remove_local_umbrella = !RNFirebaseSPM.active? || !RNFirebaseSPM.umbrella?
+  return unless remove_remote_core || remove_local_umbrella
+
   installer.aggregate_targets.each do |aggregate_target|
     project = aggregate_target.user_project
     project_modified = false
@@ -978,12 +1213,37 @@ def rnfirebase_remove_spm_core_from_app_target(installer)
       next unless target.respond_to?(:package_product_dependencies)
 
       stale_refs = target.package_product_dependencies.select do |dep|
-        dep.instance_of?(ref_class) && dep.product_name == 'FirebaseCore' && dep.package&.repositoryURL == RNFirebaseSPM.url # rubocop:disable Layout/LineLength
+        next false unless dep.instance_of?(ref_class)
+
+        pkg = dep.package
+        next false unless pkg
+
+        if remove_remote_core &&
+           dep.product_name == 'FirebaseCore' &&
+           pkg.respond_to?(:repositoryURL) &&
+           pkg.repositoryURL == RNFirebaseSPM.url
+          next true
+        end
+        if remove_local_umbrella &&
+           dep.product_name == RNFIREBASE_SPM_UMBRELLA_PRODUCT &&
+           pkg.respond_to?(:relative_path) &&
+           pkg.relative_path == RNFirebaseSPM.umbrella_path
+          next true
+        end
+
+        false
       end
       next if stale_refs.empty?
 
       if defined?(Pod::UI)
-        Pod::UI.puts "#{"[react-native-firebase] #{target.name}: ".yellow}SPM disabled -- removing the stale FirebaseCore Swift Package link left on the app target." # rubocop:disable Layout/LineLength
+        reason = if RNFirebaseSPM.umbrella?
+                   'SPM probe umbrella active -- removing the superseded direct FirebaseCore Swift Package link.'
+                 elsif RNFirebaseSPM.active?
+                   'SPM remote active -- removing a leftover RNFBFirebase probe Swift Package link.'
+                 else
+                   'SPM disabled -- removing the stale Firebase SPM link left on the app target.'
+                 end
+        Pod::UI.puts "[react-native-firebase] #{target.name}: ".yellow + reason
       end
 
       stale_refs.each do |ref|
@@ -998,15 +1258,27 @@ def rnfirebase_remove_spm_core_from_app_target(installer)
       project_modified = true
     end
 
-    project.root_object.package_references
-           .select { |pkg| pkg.instance_of?(pkg_class) && pkg.repositoryURL == RNFirebaseSPM.url }
-           .each do |pkg|
-             next if pkg.referrers.any?(ref_class)
+    stale_packages = project.root_object.package_references.select do |pkg|
+      if remove_remote_core &&
+         pkg.instance_of?(remote_pkg_class) &&
+         pkg.repositoryURL == RNFirebaseSPM.url
+        next true
+      end
+      if remove_local_umbrella &&
+         pkg.instance_of?(local_pkg_class) &&
+         pkg.relative_path == RNFirebaseSPM.umbrella_path
+        next true
+      end
 
-             project.root_object.package_references.delete(pkg)
-             pkg.remove_from_project
-             project_modified = true
-           end
+      false
+    end
+    stale_packages.each do |pkg|
+      next if pkg.referrers.any?(ref_class)
+
+      project.root_object.package_references.delete(pkg)
+      pkg.remove_from_project
+      project_modified = true
+    end
 
     project.save if project_modified
   end
@@ -1086,17 +1358,18 @@ end
 # `rnfirebase_hook_cocoapods_post_install!` above -- so you normally never
 # need to call this yourself.
 #
-# 1. `-ObjC` in `OTHER_LDFLAGS` (app target, every configuration): under SPM
-#    + dynamic linkage, dead-code stripping can drop Objective-C
-#    classes/categories that are only ever discovered via runtime reflection
-#    rather than a direct static reference -- e.g. Firebase's
-#    FIRLibrary/FIRComponent registration used by RNFBCrashlyticsInitProvider
-#    -- which otherwise crashes the app at launch, but only in Release/
-#    Archive builds (a TestFlight-only failure that's hard to reproduce from
-#    a local Debug build). `-ObjC` forces the linker to keep any object file
-#    that defines an ObjC class/category, without disabling dead-code
-#    stripping or optimizations for anything else, so it doesn't meaningfully
-#    grow the binary or slow down Release builds.
+# 1. `-ObjC` in `OTHER_LDFLAGS` (app target *and* every RNFB pod target,
+#    every configuration): under SPM + dynamic linkage, dead-code stripping
+#    can drop Objective-C classes/categories that are only ever discovered
+#    via runtime reflection rather than a direct static reference -- e.g.
+#    Firebase's FIRLibrary/FIRComponent registration used by
+#    RNFBCrashlyticsInitProvider, and GoogleAppMeasurement categories
+#    statically absorbed into RNFBAnalytics. App-target `-ObjC` does not
+#    keep categories linked into a pod. Without pod-level `-ObjC` those
+#    categories can vanish and Measurement/Remote Config can explode or
+#    hang. `-ObjC` forces the linker to keep any object file that defines
+#    an ObjC class/category, without disabling dead-code stripping or
+#    optimizations for anything else.
 #
 # 2. `SWIFT_ENABLE_EXPLICIT_MODULES = 'NO'` and `CLANG_ENABLE_EXPLICIT_MODULES
 #    = 'NO'` (app target and Pods project, every configuration): Xcode 26
@@ -1138,6 +1411,88 @@ end
 # build module 'glog'"/`'cxxreact'`. Confirmed via a real `xcodebuild
 # archive`: with this flag, the build fails on React Native's own C++ pods;
 # without it, `@import` is never reached and the archive succeeds cleanly.
+# Schedules the local facade product before RNFBApp Swift compiles, without
+# listing that product in RNFBApp's packageProductDependencies. A product
+# dependency on the pod itself makes Xcode inject FirebaseCore and
+# FirebaseInstallations module maps into RNFBApp's swiftc invocation.
+#
+# The aggregate holds only a PBXTargetDependency productRef. RNFBApp depends
+# on the aggregate target. Shipped installs never call this.
+def rnfirebase_ensure_probe_facade_build_order!(project, app_target)
+  changed = false
+  root = project.root_object
+  pkg_class = Xcodeproj::Project::Object::XCLocalSwiftPackageReference
+  pkg = root.package_references.find do |candidate|
+    candidate.instance_of?(pkg_class) && candidate.relative_path == RNFirebaseSPM.umbrella_path
+  end
+  unless pkg
+    pkg = project.new(pkg_class)
+    pkg.relative_path = RNFirebaseSPM.umbrella_path
+    root.package_references << pkg
+    changed = true
+  end
+
+  order_target = project.targets.find { |candidate| candidate.name == RNFIREBASE_SPM_PROBE_ORDER_TARGET }
+  unless order_target
+    order_target = project.new_aggregate_target(RNFIREBASE_SPM_PROBE_ORDER_TARGET)
+    changed = true
+  end
+
+  product_ready = order_target.dependencies.any? do |dep|
+    dep.respond_to?(:product_ref) && dep.product_ref&.product_name == RNFIREBASE_SPM_UMBRELLA_PRODUCT
+  end
+  unless product_ready
+    product = project.new(Xcodeproj::Project::Object::XCSwiftPackageProductDependency)
+    product.package = pkg
+    product.product_name = RNFIREBASE_SPM_UMBRELLA_PRODUCT
+    dependency = project.new(Xcodeproj::Project::Object::PBXTargetDependency)
+    dependency.product_ref = product
+    order_target.dependencies << dependency
+    changed = true
+  end
+
+  already_ordered = app_target.dependencies.any? do |dep|
+    dep.respond_to?(:target) && dep.target == order_target
+  end
+  unless already_ordered
+    app_target.add_dependency(order_target)
+    changed = true
+  end
+
+  changed
+end
+
+# Sets `RNFB_DYNAMIC_FIREBASE_PROBE` in `SWIFT_ACTIVE_COMPILATION_CONDITIONS`
+# on the app's own native targets while the dynamic probe is active, so app
+# code such as test-rn-bare's AppDelegate.swift selects the `import RNFBFirebase`
+# path. Pods settings never reach the app target, and the user project is
+# checked in, so the condition is also removed again whenever the probe is off
+# (flag unset, remote SPM, or SPM disabled). Runs regardless of whether SPM is
+# active so a probe condition left in the app project cannot leak into a
+# shipped-path build.
+def rnfirebase_sync_probe_swift_condition_on_app_targets(installer)
+  # `umbrella?` is only ever set by `firebase_dependency` while the probe env
+  # var is `1`, so it alone is the probe condition.
+  enabled = RNFirebaseSPM.umbrella?
+
+  installer.aggregate_targets.each do |aggregate_target|
+    project = aggregate_target.user_project
+    # `integrate_targets: false` has no user project: nothing to sync.
+    next if project.nil?
+
+    project_modified = false
+
+    project.native_targets.each do |target|
+      target.build_configurations.each do |config|
+        changed = rnfirebase_set_probe_swift_condition(config.build_settings, enabled)
+        project_modified ||= changed
+      end
+    end
+
+    project.save if project_modified
+  end
+end
+
 def rnfirebase_apply_spm_build_settings(installer)
   return unless RNFirebaseSPM.active?
 
@@ -1184,9 +1539,102 @@ def rnfirebase_apply_spm_build_settings(installer)
   pods_project = installer.pods_project
   return unless pods_project
 
+  # `project.new` for the probe order target runs after CocoaPods has already
+  # handed the Pods UUID counter to React Native's SPM hook. Raise it again
+  # so the aggregate and productRef objects cannot overwrite PBXProject.
+  rnfirebase_ensure_pods_uuid_counter_safe!(installer) if rnfirebase_probe_dynamic_firebase?
+
   pods_modified = false
   pods_project.targets.each do |target|
     target.build_configurations.each do |config|
+      # Analytics/Measurement ObjC categories live on the pod that
+      # statically absorbs those SPM products. App-target `-ObjC` does
+      # not keep them. Apply to every RNFB pod target (not only
+      # RNFBAnalytics) so each static absorption site retains categories.
+      if rnfirebase_rnfb_pod_target?(target)
+        ldflags_changed = add_flag.call(config.build_settings, 'OTHER_LDFLAGS', '-ObjC')
+        pods_modified ||= ldflags_changed
+      end
+
+      # `RNFB_DYNAMIC_FIREBASE_PROBE` turns on the RNFBAppModule.mm assertions.
+      # Those fail the compile when FirebaseCore or FirebaseInstallations
+      # headers are visible, or when C++ modules are enabled. They do not
+      # ask for either. `CLANG_ENABLE_MODULES = YES` keeps React Native's
+      # prebuilt Core module map resolving; it does not enable
+      # `__has_feature(cxx_modules)`. The macro stays on RNFBApp, and only
+      # while the probe is on, so shipped builds are unaffected.
+      if rnfirebase_probe_dynamic_firebase? && target.name == 'RNFBApp'
+        probe_define_changed = add_flag.call(
+          config.build_settings,
+          'GCC_PREPROCESSOR_DEFINITIONS',
+          'RNFB_DYNAMIC_FIREBASE_PROBE=1'
+        )
+        pods_modified ||= probe_define_changed
+        # Swift twin of the define above: RNFBApp's `.swift` files pick the
+        # `import RNFBFirebase` path with `#if RNFB_DYNAMIC_FIREBASE_PROBE`.
+        probe_swift_changed = rnfirebase_set_probe_swift_condition(config.build_settings, true)
+        pods_modified ||= probe_swift_changed
+        # RN prebuilt Core requires its Clang module map. `YES` enables normal
+        # Objective-C modules but does not enable the separate
+        # `__has_feature(cxx_modules)` capability asserted by the probe TU.
+        unless config.build_settings['CLANG_ENABLE_MODULES'] == 'YES'
+          config.build_settings['CLANG_ENABLE_MODULES'] = 'YES'
+          pods_modified = true
+        end
+
+        # The probe package is deliberately owned by the app target rather
+        # than attached to RNFBApp through React Native's `spm_dependency`.
+        # A direct package-product dependency makes Xcode inject every
+        # transitive Firebase target's -I/module-map flags into this pod,
+        # exposing FirebaseCore/FirebaseInstallations to Objective-C++.
+        # Link the already app-owned dynamic framework by name instead: Swift
+        # can import RNFBFirebase, while the underlying product headers remain
+        # outside RNFBApp's compile search paths. Build order is a separate
+        # aggregate productRef (`rnfirebase_ensure_probe_facade_build_order!`);
+        # search paths alone do not wait for that product on an empty DerivedData.
+        #
+        # Do not derive these from BUILT_PRODUCTS_DIR. For a CocoaPods
+        # framework target that setting is target-scoped (for example
+        # .../Release-iphonesimulator/RNFBApp), while Xcode emits package
+        # Swift modules and frameworks into the shared configuration products
+        # directory beside it:
+        #   <configuration-products>/RNFBFirebase.swiftmodule
+        #   <configuration-products>/PackageFrameworks/RNFBFirebase.framework
+        # BUILD_DIR + CONFIGURATION + EFFECTIVE_PLATFORM_NAME addresses that
+        # shared directory for Debug/Release, simulator/device, and Archive.
+        # Xcode realpaths `swiftmodule/..` back to that directory, so the
+        # swiftc line would not name the facade. Also list the emitted
+        # `.swiftmodule` bundle. Swift still imports from the products
+        # directory; the bundle path keeps `RNFBFirebase` on the invocation
+        # without adding FirebaseCore's module map.
+        package_products_path = '${BUILD_DIR}/${CONFIGURATION}${EFFECTIVE_PLATFORM_NAME}'
+        facade_module_include = "#{package_products_path}/#{RNFIREBASE_SPM_UMBRELLA_PRODUCT}.swiftmodule"
+        swift_include_paths = rnfirebase_build_setting_list(config.build_settings['SWIFT_INCLUDE_PATHS'])
+        [package_products_path, facade_module_include].each do |include_path|
+          next if swift_include_paths.include?(include_path)
+
+          swift_include_paths << include_path
+          pods_modified = true
+        end
+        config.build_settings['SWIFT_INCLUDE_PATHS'] = swift_include_paths.join(' ')
+
+        framework_paths = rnfirebase_build_setting_list(config.build_settings['FRAMEWORK_SEARCH_PATHS'])
+        package_frameworks_path = "#{package_products_path}/PackageFrameworks"
+        unless framework_paths.include?(package_frameworks_path)
+          config.build_settings['FRAMEWORK_SEARCH_PATHS'] = (framework_paths << package_frameworks_path).join(' ')
+          pods_modified = true
+        end
+
+        probe_ldflags = rnfirebase_build_setting_list(config.build_settings['OTHER_LDFLAGS'])
+        unless probe_ldflags.include?(RNFIREBASE_SPM_UMBRELLA_PRODUCT)
+          config.build_settings['OTHER_LDFLAGS'] =
+            (probe_ldflags + ['-framework', RNFIREBASE_SPM_UMBRELLA_PRODUCT]).join(' ')
+          pods_modified = true
+        end
+
+        pods_modified = true if rnfirebase_ensure_probe_facade_build_order!(pods_project, target)
+      end
+
       explicit_modules_settings.each do |setting|
         unless config.build_settings[setting] == 'NO'
           config.build_settings[setting] = 'NO'
@@ -1201,36 +1649,44 @@ end
 rnfirebase_hook_cocoapods_post_install!
 
 # @param spec [Pod::Specification] The podspec object (the `s` in podspec DSL)
-# @param version [String] Firebase SDK version (e.g., '12.10.0')
+# @param version [String] Firebase SDK version (e.g., '13.0.0')
 # @param spm_products [Array<String>] SPM product names (e.g., ['FirebaseAuth'])
-# @param pods [Array<String>, String] CocoaPods dependency names with optional version
-#   Can be a single string like 'Firebase/Auth' or an array like ['Firebase/Messaging', 'FirebaseCoreExtension']
-def firebase_dependency(spec, version, spm_products, pods)
-  if defined?(spm_dependency) && !rnfirebase_spm_disabled?
-    # Tracked ourselves (rather than inspecting RN's internal `SPM` object's
-    # dependency list) so `rnfirebase_add_spm_embed_phase` doesn't depend on
-    # any RN-internal state shape -- only on whether *we* ever took this path.
-    RNFirebaseSPM.activate!(version)
+# @param pods [Array<String>, String] Legacy CocoaPods names (ignored — Firebase 13+ is SPM-only)
+#   Kept for call-site compatibility with existing podspecs.
+def firebase_dependency(spec, version, spm_products, _pods)
+  rnfirebase_fail_cocoapods_firebase!('$RNFirebaseDisableSPM = true') if rnfirebase_spm_disabled?
+  unless defined?(spm_dependency)
+    rnfirebase_fail_cocoapods_firebase!('React Native < 0.75 — `spm_dependency` is unavailable')
+  end
+
+  # Tracked ourselves (rather than inspecting RN's internal `SPM` object's
+  # dependency list) so `rnfirebase_add_spm_embed_phase` doesn't depend on
+  # any RN-internal state shape -- only on whether *we* ever took this path.
+  if rnfirebase_probe_dynamic_firebase?
+    RNFirebaseSPM.activate!(version, mode: :umbrella)
+    if defined?(Pod::UI)
+      Pod::UI.puts "[react-native-firebase] #{spec.name}: ".yellow +
+                   "Using local #{RNFIREBASE_SPM_UMBRELLA_PRODUCT} SPM probe " \
+                   '(RNFB_TEST_RN_BARE_DYNAMIC_FIREBASE=1)'
+    end
+    # Do not attach the package product to the pod target. Xcode propagates
+    # a direct Swift-package dependency's transitive Clang include/module
+    # paths into that target, which makes FirebaseCore and
+    # FirebaseInstallations headers visible to RNFBApp Objective-C++.
+    # rnfirebase_add_spm_core_to_app_target owns the package product.
+    # rnfirebase_apply_spm_build_settings links the dynamic framework and,
+    # for this probe only, orders it ahead of RNFBApp via an aggregate
+    # productRef that is not RNFBApp's packageProductDependencies entry.
+  else
+    RNFirebaseSPM.activate!(version, mode: :remote)
     if defined?(Pod::UI)
       Pod::UI.puts "[react-native-firebase] #{spec.name}: ".yellow +
                    "Using SPM for Firebase dependency resolution (products: #{spm_products.join(', ')})"
     end
     spm_dependency(spec,
                    url: RNFirebaseSPM.url,
-                   requirement: { kind: 'upToNextMajorVersion', minimumVersion: version },
+                   requirement: rnfirebase_spm_package_requirement(version),
                    products: spm_products)
-  else
-    if defined?(Pod::UI)
-      if rnfirebase_spm_disabled?
-        Pod::UI.puts "#{"[react-native-firebase] #{spec.name}: ".yellow}SPM disabled ($RNFirebaseDisableSPM = true), using CocoaPods for Firebase dependencies" # rubocop:disable Layout/LineLength
-      elsif !defined?(spm_dependency)
-        Pod::UI.puts "#{"[react-native-firebase] #{spec.name}: ".yellow}SPM not available (React Native < 0.75), using CocoaPods for Firebase dependencies" # rubocop:disable Layout/LineLength
-      end
-    end
-    pods = [pods] unless pods.is_a?(Array)
-    pods.each do |pod|
-      spec.dependency pod, version
-    end
   end
 end