not-react-native-macos 0.83.0-rc.1 → 0.87.1-rc.2

package/scripts/cocoapods/autolinking.rb

@@ -38,7 +38,16 @@ def list_native_modules!(config_command)
   config = JSON.parse(json)
 
   packages = config["dependencies"]
-  ios_project_root = Pathname.new(config["project"]["ios"]["sourceDir"])
+
+  # [macOS] The autolinking JSON is keyed by platform, and a macOS build asks the
+  # CLI for `--platform macos`, so the only key present is "macos" -- indexing
+  # "ios" unconditionally crashes with `undefined method '[]' for nil`. Take the
+  # key from the target's own platform, and fall back to "ios" so nothing changes
+  # for an iOS build. macOS]
+  autolinking_platform = current_target_definition&.platform&.name == :osx ? "macos" : "ios"
+
+  project_config = config["project"][autolinking_platform] || config["project"]["ios"]
+  ios_project_root = Pathname.new(project_config["sourceDir"])
   react_native_path = Pathname.new(config["reactNativePath"])
   codegen_output_path = ios_project_root.join("build/generated/autolinking/autolinking.json")
 
@@ -49,7 +58,7 @@ def list_native_modules!(config_command)
   found_pods = []
 
   packages.each do |package_name, package|
-    next unless package_config = package["platforms"]["ios"]
+    next unless package_config = package["platforms"][autolinking_platform] # [macOS] was hardcoded "ios"
 
     name = package["name"]
     podspec_path = package_config["podspecPath"]

package/scripts/cocoapods/codegen.rb

@@ -34,7 +34,9 @@ def run_codegen!(
     :config_file_dir => config_file_dir,
     :codegen_output_dir => codegen_output_dir,
     :config_key => config_key,
-    :folly_version => folly_version
+    :folly_version => folly_version,
+    # [macOS] see CodegenUtils#use_react_native_codegen_discovery!
+    :target_platform => (current_target_definition&.platform&.name == :osx ? "macos" : "ios")
   )
 end
 

package/scripts/cocoapods/codegen_utils.rb

@@ -35,7 +35,12 @@ class CodegenUtils
       folly_version: Helpers::Constants.folly_config[:version],
       codegen_utils: CodegenUtils.new(),
       file_manager: File,
-      logger: CodegenUtils::UI
+      logger: CodegenUtils::UI,
+      # [macOS] The generated providers are platform-specific: they map names to
+      # classes that only exist if the owning library was built for this
+      # platform. Upstream hardcodes "ios" because every library supports iOS.
+      # macOS]
+      target_platform: "ios"
       )
       return if codegen_disabled
 
@@ -58,7 +63,7 @@ class CodegenUtils
           "#{relative_installation_root}/#{react_native_path}/scripts/generate-codegen-artifacts.js",
           "-p", "#{app_path}",
           "-o", Pod::Config.instance.installation_root,
-          "-t", "ios",
+          "-t", target_platform, # [macOS] was hardcoded "ios"
         ])
       Pod::UI.puts out;
 

package/scripts/cocoapods/fabric.rb

@@ -11,7 +11,7 @@ def setup_fabric!(react_native_path: "../node_modules/react-native")
     pod 'React-Fabric', :path => "#{react_native_path}/ReactCommon"
     pod 'React-FabricComponents', :path => "#{react_native_path}/ReactCommon"
     pod 'React-graphics', :path => "#{react_native_path}/ReactCommon/react/renderer/graphics"
-    pod 'React-RCTFabric', :path => "#{react_native_path}/React", :modular_headers => true
+    rncore_pod 'React-RCTFabric', :path => "#{react_native_path}/React", :modular_headers => true
     pod 'React-ImageManager', :path => "#{react_native_path}/ReactCommon/react/renderer/imagemanager/platform/ios"
     pod 'React-FabricImage', :path => "#{react_native_path}/ReactCommon"
 end

package/scripts/cocoapods/helpers.rb

@@ -83,16 +83,37 @@ module Helpers
         def self.min_ios_version_supported
             return '15.1'
         end
+
         # [macOS
+        # Matches the minos of the macOS hermesvm.framework that upstream
+        # already publishes in every release tarball.
         def self.min_macos_version_supported
-            return '14.0'
+            return '11.0'
+        end
+
+        # Path prefixes the macOS build does not ship, read from the single
+        # list in macos/UIKitCompat/macos-excludes.txt so the podspecs and
+        # macos/scripts/syntax-check.sh can never disagree.
+        #
+        # Returns glob patterns relative to packages/react-native, suitable for
+        # a podspec's `osx.exclude_files`.
+        def self.macos_excluded_files
+            # Two layouts: the repo, where macos/ sits beside packages/, and an
+            # npm tarball, where macos/scripts/publish.sh has vendored macos/
+            # into the package. Try the package-relative path first.
+            list = [
+                File.join(__dir__, '..', '..', 'macos', 'UIKitCompat', 'macos-excludes.txt'),
+                File.join(__dir__, '..', '..', '..', '..', 'macos', 'UIKitCompat', 'macos-excludes.txt'),
+            ].find { |path| File.exist?(path) }
+            return [] if list.nil?
+            # No filter_map: CocoaPods still runs on Ruby 2.6 on stock macOS.
+            File.readlines(list).map do |line|
+                prefix = line.strip
+                next nil if prefix.empty? || prefix.start_with?('#')
+                prefix.end_with?('/') ? "#{prefix}**/*" : "#{prefix}*"
+            end.compact
         end
         # macOS]
-        # [visionOS
-        def self.min_visionos_version_supported
-            return '1.0'
-        end
-        # visionOS]
 
         def self.min_xcode_version_supported
             return '16.1'

package/scripts/cocoapods/jsengine.rb

@@ -13,7 +13,7 @@ def setup_hermes!(react_native_path: "../node_modules/react-native")
     react_native_dir = Pod::Config.instance.installation_root.join(react_native_path)
     # This `:tag => hermestag` below is only to tell CocoaPods to update hermes-engine when React Native version changes.
     # We have custom logic to compute the source for hermes-engine. See sdks/hermes-engine/*
-    hermestag_file_name = ENV['RCT_HERMES_V1_ENABLED'] == "1" ? ".hermesv1version" : ".hermesversion"
+    hermestag_file_name = ".hermesv1version"
     hermestag_file = File.join(react_native_dir, "sdks", hermestag_file_name)
     hermestag = File.exist?(hermestag_file) ? File.read(hermestag_file).strip : ''
     pod 'hermes-engine', :podspec => "#{react_native_path}/sdks/hermes-engine/hermes-engine.podspec", :tag => hermestag

package/scripts/cocoapods/new_architecture.rb

@@ -8,6 +8,8 @@ require 'json'
 require_relative "./utils.rb"
 require_relative "./helpers.rb"
 require_relative "./jsengine.rb"
+require_relative "./rndependencies.rb"
+require_relative "./rncore.rb"
 
 
 class NewArchitectureHelper
@@ -117,7 +119,7 @@ class NewArchitectureHelper
 
         spec.dependency "RCTRequired"
         spec.dependency "RCTTypeSafety"
-        spec.dependency "ReactCommon/turbomodule/bridging"
+        spec.dependency "React-bridging"
         spec.dependency "ReactCommon/turbomodule/core"
         spec.dependency "React-NativeModulesApple"
         spec.dependency "Yoga"
@@ -133,9 +135,13 @@ class NewArchitectureHelper
 
         depend_on_js_engine(spec)
         add_rn_third_party_dependencies(spec)
-        add_rncore_dependency(spec)
 
         spec.pod_target_xcconfig = current_config
+
+        # add_rncore_dependency must be called after setting pod_target_xcconfig
+        # because it reads and modifies the xcconfig. If called before, its changes
+        # would be overwritten by the assignment above.
+        add_rncore_dependency(spec)
     end
 
     def self.extract_react_native_version(react_native_path, file_manager: File, json_parser: JSON)

package/scripts/cocoapods/rncore.rb

@@ -11,13 +11,16 @@ require_relative './utils.rb'
 
 ### Adds ReactNativeCore-prebuilt as a dependency to the given podspec if we're not
 ### building ReactNativeCore from source (then this function does nothing).
+###
+### `<React/...>` resolves through the vendored React.framework; every other namespace
+### (`<react/...>`, `<yoga/...>`, `<hermes/...>`, ...) resolves through the flattened
+### ReactNativeHeaders headers that React-Core-prebuilt exposes. The header search path
+### and the ReactNativeHeaders module-map activation are NOT added here: they are applied
+### post-install by configure_aggregate_xcconfig, which covers aggregate, third-party AND
+### these pods from a single injection site. No clang VFS overlay.
 def add_rncore_dependency(s)
     if !ReactNativeCoreUtils.build_rncore_from_source()
-        current_pod_target_xcconfig = s.to_hash["pod_target_xcconfig"] || {}
-        current_pod_target_xcconfig = current_pod_target_xcconfig.to_h unless current_pod_target_xcconfig.is_a?(Hash)
         s.dependency "React-Core-prebuilt"
-        current_pod_target_xcconfig["HEADER_SEARCH_PATHS"] ||= [] << "$(PODS_ROOT)/React-Core-prebuilt/React.xcframework/Headers"
-        s.pod_target_xcconfig = current_pod_target_xcconfig
     end
 end
 
@@ -86,7 +89,7 @@ class ReactNativeCoreUtils
         if ENV["RCT_TESTONLY_RNCORE_TARBALL_PATH"]
             abort_if_use_local_rncore_with_no_file()
             rncore_log("Using local xcframework at #{ENV["RCT_TESTONLY_RNCORE_TARBALL_PATH"]}")
-            return {:http => "file://#{ENV["RCT_TESTONLY_RNCORE_TARBALL_PATH"]}" }
+            return {:http => ReactNativePodsUtils.local_file_uri(ENV["RCT_TESTONLY_RNCORE_TARBALL_PATH"]) }
         end
 
         if ENV["RCT_USE_PREBUILT_RNCORE"] == "1"
@@ -143,7 +146,8 @@ class ReactNativeCoreUtils
         rncore_log("  #{Pathname.new(destinationDebug).relative_path_from(Pathname.pwd).to_s}")
         rncore_log("  #{Pathname.new(destinationRelease).relative_path_from(Pathname.pwd).to_s}")
 
-        return {:http => URI::File.build(path: destinationDebug).to_s }
+        return {:http => stable_tarball_url(@@react_native_version, :debug) } unless @@download_dsyms
+        return {:http => ReactNativePodsUtils.local_file_uri(destinationDebug) }
     end
 
     def self.podspec_source_download_prebuilt_nightly_tarball()
@@ -179,7 +183,8 @@ class ReactNativeCoreUtils
         rncore_log("Resolved nightly ReactNativeCore-prebuilt version:")
         rncore_log("  #{Pathname.new(destinationDebug).relative_path_from(Pathname.pwd).to_s}")
         rncore_log("  #{Pathname.new(destinationRelease).relative_path_from(Pathname.pwd).to_s}")
-        return {:http => URI::File.build(path: destinationDebug).to_s }
+        return {:http => nightly_tarball_url(@@react_native_version, :debug) } unless @@download_dsyms
+        return {:http => ReactNativePodsUtils.local_file_uri(destinationDebug) }
     end
 
     def self.process_dsyms(frameworkTarball, dSymsTarball)
@@ -233,7 +238,16 @@ class ReactNativeCoreUtils
 
             # Add the dSYMs folder to the framework folder
             rncore_log("  Adding dSYMs to framework tarball")
-            `(cd "$(dirname "#{dsyms_tmp_dir}")" && mkdir -p React.xcframework && cp -r "$(basename "#{dsyms_tmp_dir}")" React.xcframework/dSYMs && tar -rf "#{frameworkTarPath}" React.xcframework/dSYMs && rm -rf React.xcframework)`
+
+            # Move symbol bundles into each of the slices in the xcframework
+            # Example:
+            # move dSYMs/ios-arm64/. into React.xcframework/ios-arm64/React.framework/dSYMs/.
+            Dir.glob(File.join(dsyms_tmp_dir, "*")).each do |dsym_path|
+                slice_name = File.basename(dsym_path)
+                slice_dsym_dest = File.join("React.xcframework", slice_name, "React.framework", "dSYMs")
+                rncore_log("    Adding dSYM slice #{slice_name} into tarball at #{slice_dsym_dest}")
+                `(cd "#{File.dirname(frameworkTarPath)}" && mkdir -p "#{slice_dsym_dest}" && cp -R "#{dsym_path}/." "#{slice_dsym_dest}" && tar -rf "#{frameworkTarPath}" "#{slice_dsym_dest}")`
+            end
 
             # Now gzip the framework tarball again - remember to use the .tar file and not the .gz file
             rncore_log("  Packing #{Pathname.new(frameworkTarPath).relative_path_from(Pathname.pwd).to_s}")
@@ -246,6 +260,10 @@ class ReactNativeCoreUtils
             # Remove backup of original tarballs
             FileUtils.rm_f("#{frameworkTarball}.orig")
 
+            # Remove temp dSYMs folder and the temp Framework folder
+            FileUtils.rm_rf(dsyms_tmp_dir)
+            FileUtils.rm_rf(File.join(artifacts_dir, "React.xcframework"))
+
         rescue => e
             rncore_log("Failed to process dSYMs: #{e.message}", :error)
             # Restore the original tarballs
@@ -271,9 +289,10 @@ class ReactNativeCoreUtils
         return if dsym_bundles.empty?
 
         # Define source path mappings - from absolute build paths to relative framework paths
+        # Expand the path relative to the installation root (project root, parent of ios/)
+        react_native_absolute_path = File.expand_path(@@react_native_path, Pod::Config.instance.installation_root)
         mappings = [
-            # Make sure to make react_native_path absolute
-            ["/Users/runner/work/react-native/react-native/packages/react-native", "#{File.expand_path(@@react_native_path)}"],
+            ["/Users/runner/work/react-native/react-native/packages/react-native", react_native_absolute_path],
         ]
 
         dsym_bundles.each do |dsym_path| begin
@@ -373,17 +392,69 @@ class ReactNativeCoreUtils
     end
 
     def self.download_rncore_tarball(react_native_path, tarball_url, version, configuration, dsyms = false)
-        destination_path = configuration == nil ?
-            "#{artifacts_dir()}/reactnative-core-#{version}#{dsyms ? "-dSYM" : ""}.tar.gz" :
-            "#{artifacts_dir()}/reactnative-core-#{version}#{dsyms ? "-dSYM" : ""}-#{configuration}.tar.gz"
+        filename = configuration == nil ?
+            "reactnative-core-#{version}#{dsyms ? "-dSYM" : ""}.tar.gz" :
+            "reactnative-core-#{version}#{dsyms ? "-dSYM" : ""}-#{configuration}.tar.gz"
+        destination_path = "#{artifacts_dir()}/#{filename}"
+
+        if File.exist?(destination_path)
+          rncore_log("Tarball #{filename} already exists in Pods. Skipping download.")
+          return destination_path
+        end
 
-        unless File.exist?(destination_path)
-          # Download to a temporary file first so we don't cache incomplete downloads.
-          rncore_log("Downloading ReactNativeCore-prebuilt #{dsyms ? "dSYMs " : ""}#{configuration ? configuration.to_s : ""} tarball from #{tarball_url} to #{Pathname.new(destination_path).relative_path_from(Pathname.pwd).to_s}")
+        `mkdir -p "#{artifacts_dir()}"`
+
+        if ReactNativePodsUtils.skip_caches?
+          rncore_log("RCT_SKIP_CACHES is set. Downloading #{filename} directly (bypassing shared cache).")
           tmp_file = "#{artifacts_dir()}/reactnative-core.download"
-          `mkdir -p "#{artifacts_dir()}" && curl "#{tarball_url}" -Lo "#{tmp_file}" && mv "#{tmp_file}" "#{destination_path}"`
+          `curl -A "react-native-#{version}" "#{tarball_url}" -Lo "#{tmp_file}" && mv "#{tmp_file}" "#{destination_path}"`
+          unless File.exist?(destination_path)
+            abort("[ReactNativeCore] Failed to download #{filename} from #{tarball_url}. Aborting.")
+          end
+          return destination_path
+        end
+
+        cached_path = File.join(ReactNativePodsUtils.shared_cache_dir(), filename)
+        if File.exist?(cached_path)
+          rncore_log("Verifying checksum for cached #{filename}...")
+          if ReactNativePodsUtils.validate_tarball(cached_path, tarball_url)
+            rncore_log("Cache hit: copying #{filename} from shared cache (#{ReactNativePodsUtils.shared_cache_dir()})")
+            FileUtils.cp(cached_path, destination_path)
+          else
+            rncore_log("Shared cache file #{filename} failed SHA verification. Re-downloading.")
+            File.delete(cached_path)
+            tmp_file = "#{artifacts_dir()}/reactnative-core.download"
+            `curl -A "react-native-#{version}" "#{tarball_url}" -Lo "#{tmp_file}" && mv "#{tmp_file}" "#{destination_path}"`
+            unless File.exist?(destination_path)
+              abort("[ReactNativeCore] Failed to download #{filename} from #{tarball_url}. Aborting.")
+            end
+            rncore_log("Verifying checksum for downloaded #{filename}...")
+            if ReactNativePodsUtils.validate_tarball(destination_path, tarball_url)
+              FileUtils.cp(destination_path, cached_path)
+              rncore_log("Saved #{filename} to shared cache (#{ReactNativePodsUtils.shared_cache_dir()})")
+            else
+              File.delete(destination_path) if File.exist?(destination_path)
+              abort("[ReactNativeCore] Downloaded file #{filename} failed SHA verification. Aborting.")
+            end
+          end
         else
-          rncore_log("Using downloaded ReactNativeCore-prebuilt #{dsyms ? "dSYMs " : ""}#{configuration ? configuration.to_s : ""} tarball at #{Pathname.new(destination_path).relative_path_from(Pathname.pwd).to_s}")
+          rncore_log("Cache miss: downloading #{filename} from #{tarball_url}")
+          # Download to a temporary file first so we don't cache incomplete downloads.
+          tmp_file = "#{artifacts_dir()}/reactnative-core.download"
+          `curl -A "react-native-#{version}" "#{tarball_url}" -Lo "#{tmp_file}" && mv "#{tmp_file}" "#{destination_path}"`
+          unless File.exist?(destination_path)
+            abort("[ReactNativeCore] Failed to download #{filename} from #{tarball_url}. Aborting.")
+          end
+          rncore_log("Verifying checksum for downloaded #{filename}...")
+          if ReactNativePodsUtils.validate_tarball(destination_path, tarball_url)
+            # Save to shared cache for future use
+            `mkdir -p "#{ReactNativePodsUtils.shared_cache_dir()}"`
+            FileUtils.cp(destination_path, cached_path)
+            rncore_log("Saved #{filename} to shared cache (#{ReactNativePodsUtils.shared_cache_dir()})")
+          else
+            File.delete(destination_path) if File.exist?(destination_path)
+            abort("[ReactNativeCore] Downloaded file #{filename} failed SHA verification. Aborting.")
+          end
         end
 
         return destination_path
@@ -436,4 +507,68 @@ class ReactNativeCoreUtils
         return latest_nightly
     end
 
+    # Single post-install injection site for the prebuilt header resolution. Adds the
+    # ReactNativeHeaders search path + module-map activation to the aggregate (main app)
+    # target AND every pod target — RN core pods, third-party pods alike. (add_rncore_dependency
+    # only declares the React-Core-prebuilt dependency; it no longer touches xcconfigs.)
+    #
+    # `<React/...>` resolves through the vendored React.framework; this adds the search
+    # path to the flattened ReactNativeHeaders headers (every other RN namespace —
+    # the third-party deps namespaces are served by the ReactNativeDependencies pod,
+    # see ReactNativeDependenciesUtils.configure_aggregate_xcconfig). There is
+    # no clang VFS overlay.
+    #
+    # Parameters:
+    # - installer: The CocoaPods installer object
+    def self.configure_aggregate_xcconfig(installer)
+        return if @@build_from_source
+
+        rncore_log("Configuring xcconfig for prebuilt React Native Core...")
+
+        headers_search_path = " \"$(PODS_ROOT)/React-Core-prebuilt/Headers\""
+
+        # Add the header search path to aggregate target xcconfigs (used by the main app target)
+        installer.aggregate_targets.each do |aggregate_target|
+            aggregate_target.xcconfigs.each do |config_name, config_file|
+                add_prebuilt_header_search_paths(config_file.attributes, headers_search_path)
+                xcconfig_path = aggregate_target.xcconfig_path(config_name)
+                config_file.save_as(xcconfig_path)
+            end
+        end
+
+        # Add the header search path to ALL pod targets (for third-party pods that don't call add_rncore_dependency)
+        installer.pod_targets.each do |pod_target|
+            pod_target.build_settings.each do |config_name, build_settings|
+                xcconfig_path = pod_target.xcconfig_path(config_name)
+                next unless File.exist?(xcconfig_path)
+
+                xcconfig = Xcodeproj::Config.new(xcconfig_path)
+
+                # Skip if the prebuilt header search path is already present
+                header_search_paths = xcconfig.attributes["HEADER_SEARCH_PATHS"] || ""
+                next if header_search_paths.include?("React-Core-prebuilt/Headers")
+
+                add_prebuilt_header_search_paths(xcconfig.attributes, headers_search_path)
+                xcconfig.save_as(xcconfig_path)
+            end
+        end
+
+        rncore_log("Prebuilt xcconfig configuration complete")
+    end
+
+    # Helper method to add the prebuilt ReactNativeHeaders header search path to an xcconfig attributes map
+    def self.add_prebuilt_header_search_paths(attributes, headers_search_path)
+        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "HEADER_SEARCH_PATHS", headers_search_path)
+        # Suppress incomplete umbrella warnings for the prebuilt frameworks (it is expected, as our umbrella headers do not include all headers)
+        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_SWIFT_FLAGS", " -Xcc -Wno-incomplete-umbrella")
+        # Activate the ReactNativeHeaders module map so the relocated namespaces
+        # (`yoga`, `RCTDeprecation`, `ReactNativeHeaders_react`, ...) are modular —
+        # otherwise the React framework's clang explicit-module precompile trips
+        # -Wnon-modular-include-in-framework-module on `<yoga/...>` / `<react/...>`.
+        # Quoted so a $(PODS_ROOT) containing spaces stays a single clang argument.
+        module_map_flag = " \"-fmodule-map-file=$(PODS_ROOT)/React-Core-prebuilt/Headers/module.modulemap\""
+        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_CFLAGS", module_map_flag)
+        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_CPLUSPLUSFLAGS", module_map_flag)
+        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_SWIFT_FLAGS", " -Xcc" + module_map_flag)
+    end
 end

package/scripts/cocoapods/rncore_facades.rb

@@ -0,0 +1,232 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+require 'json'
+require 'fileutils'
+
+# Facade podspecs for the prebuilt React Native Core path.
+#
+# In prebuilt mode the compiled code AND headers for the React core pods live
+# entirely inside React.xcframework + React-Core-prebuilt (which flattens the
+# ReactNativeHeaders namespaces into its Headers/). Re-installing the SOURCE
+# podspecs in that mode is what makes them ship duplicate headers that shadow the
+# prebuilt artifact (via HEADER_SEARCH_PATHS, CocoaPods .hmap header maps, and
+# the all-product-headers VFS overlay) and break the React framework's clang
+# explicit-module precompile.
+#
+# Instead we install dependency-only FACADE podspecs for those names: they ship
+# no source files and (with one narrow exception, see FACADE_REEXPOSED_HEADERS)
+# no headers, so CocoaPods makes them PBXAggregateTarget
+# placeholders (should_build? == false) and nothing is laid down to shadow. Each
+# facade depends on React-Core-prebuilt so its consumers transitively pick up the
+# prebuilt framework + headers. The pod NAMES still resolve, so ReactCodegen,
+# third-party modules, and RN's own podspec graph keep resolving `React-Core`,
+# `Yoga`, `React-Core/Default`, etc.
+#
+# MAINTENANCE MODEL: the set of facaded pods is explicit (FACADE_PODS) so the
+# prebuilt rollout can be staged, but each facade's VERSION and SUBSPECS are
+# DERIVED from the real podspec at `pod install` time (Pod::Specification.from_file).
+# That removes the drift risk that would otherwise bite third-party libraries:
+# if React adds/renames `React-Core/<Subspec>`, the facade exposes it
+# automatically — nobody has to hand-maintain a parallel subspec list.
+#
+# This is staged: phase 1 facades a small set and KEEPS the existing
+# podspec_sources / add_rncore_dependency / configure_aggregate_xcconfig /
+# -fmodule-map-file machinery. The set is expanded until the cold prebuilt
+# build passes; the distributed prebuilt helpers are only deleted afterwards.
+module RNCoreFacades
+    # pod name => podspec path (relative to the react-native package root).
+    # These are the React-core pods whose code + headers are fully provided by
+    # the prebuilt React.xcframework / React-Core-prebuilt. Start small; expand as
+    # the cold build surfaces more shadowing pods. (NOTE: not every caller of
+    # add_rncore_dependency belongs here — e.g. ReactCodegen depends on the
+    # prebuilt but still builds its own generated sources, so it is NOT a facade.)
+    FACADE_PODS = {
+        "React-Core"       => "React-Core.podspec",
+        "React-RCTFabric"  => "React/React-RCTFabric.podspec",
+        "React-RCTRuntime" => "React/Runtime/React-RCTRuntime.podspec",
+        "Yoga"             => "ReactCommon/yoga/Yoga.podspec",
+        "RCTDeprecation"   => "ReactApple/Libraries/RCTFoundation/RCTDeprecation/RCTDeprecation.podspec",
+        "FBLazyVector"     => "Libraries/FBLazyVector/FBLazyVector.podspec",
+        "RCTRequired"      => "Libraries/Required/RCTRequired.podspec",
+    }
+
+    # A facade ships NO headers by default — the prebuilt React.framework /
+    # React-Core-prebuilt own them. NARROW EXCEPTION: a few headers live ONLY
+    # inside React.framework/Headers (served angle-only as <React/...>, e.g.
+    # because they reach unguarded C++ and are excluded from the framework module
+    # map) and are NOT in the flattened React-Core-prebuilt/Headers. A quoted
+    # `#import "<name>.h"` therefore has no resolution target in prebuilt mode.
+    #
+    # Community Fabric modules quote-import RCTFabricComponentsPlugins.h (47x in a
+    # full app: slider, maps, pager-view, keyboard-controller, ...). In source it
+    # was vended by React-RCTFabric at header_dir "React", which put it in
+    # dependents' CocoaPods header maps so the bare quoted name resolved. The
+    # facade dropped it. We re-vend JUST that header here so dependents' header
+    # maps carry it again, exactly as the source pod did.
+    #
+    # Re-exposing a SINGLE header (not the whole React/ namespace) does not put
+    # <react/...>/<yoga/...> on -I, so it does NOT reintroduce the
+    # -Wnon-modular-include-in-framework-module shadowing the modular prebuilt
+    # layout exists to eliminate. The header is core-only (matches source: it
+    # only ever declared RN's built-in components; third-party Fabric components
+    # register via the codegen RCTThirdPartyComponentsProvider, shipped by the
+    # non-facaded ReactCodegen pod).
+    #
+    # pod name => { "header_dir" => <dir>, "globs" => [<glob rel. to its podspec dir>] }
+    FACADE_REEXPOSED_HEADERS = {
+        "React-RCTFabric" => {
+            "header_dir" => "React",
+            "globs" => ["Fabric/Mounting/ComponentViews/RCTFabricComponentsPlugins.h"],
+        },
+    }
+
+    # Sub-directory (relative to the install root) that holds the generated facades.
+    FACADE_RELDIR = File.join("build", "rncore-facades")
+
+    @@install_root = nil
+
+    # True when `name` should be installed as a facade instead of its source podspec.
+    def self.facade?(name)
+        FACADE_PODS.key?(name)
+    end
+
+    # Generates the facade podspecs and returns the base directory holding them.
+    # Each facade gets its OWN sub-directory containing a single
+    # `<Name>.podspec.json`, so it can be installed as a LOCAL pod via
+    # `:path => <dir>`. `:path` (PathSource) uses the spec in place and never
+    # downloads `spec.source` — unlike `:podspec` (PodspecSource), which is an
+    # *external* source whose `root_spec.source` CocoaPods would actually fetch
+    # (i.e. git-clone react-native for every empty facade). Idempotent; safe to
+    # call once per `pod install`.
+    #
+    # `react_native_path` locates the real podspecs we mirror. version + subspecs +
+    # default_subspecs are DERIVED from the real spec so the facade stays
+    # graph-equivalent to the source pod (resources are NOT carried — they live in
+    # the prebuilt artifact; see the note in the loop). A facaded pod whose real
+    # podspec can't be read is a hard error (see load_real_spec) — silently shipping
+    # an empty facade would hide exactly the drift this guards against.
+    def self.generate(react_native_path, install_root, version, ios_version)
+        @@install_root = install_root.to_s
+        abs_base = File.join(@@install_root, FACADE_RELDIR)
+        FileUtils.mkdir_p(abs_base)
+        FACADE_PODS.each do |name, podspec_rel_path|
+            podspec_path = File.join(react_native_path.to_s, podspec_rel_path)
+            podspec_dir = File.dirname(podspec_path)
+            real = load_real_spec(podspec_path, name)
+            dir = File.join(abs_base, name)
+            FileUtils.mkdir_p(dir)
+
+            spec = {
+                "name" => name,
+                "version" => real.version.to_s,
+                "summary" => "Prebuilt facade for #{name} (code + headers live in React-Core-prebuilt).",
+                "homepage" => "https://reactnative.dev/",
+                "license" => "MIT",
+                "authors" => "Meta Platforms, Inc. and its affiliates",
+                "platforms" => { "ios" => ios_version },
+                # Required podspec attribute, but never fetched: the pod is installed
+                # as a LOCAL pod (`:path => <dir>`), which uses this spec in place and
+                # ships no source_files. Placeholder only.
+                "source" => { "git" => "https://github.com/facebook/react-native.git" },
+                "dependencies" => { "React-Core-prebuilt" => [] },
+            }
+
+            # NOTE: the facade carries NO resources. The pods' non-code resources
+            # (e.g. the privacy manifest) are embedded directly in the prebuilt
+            # React.xcframework by the ios-prebuild compose (see ios-prebuild/framework-resources.js),
+            # so they reach both CocoaPods-prebuilt and SwiftPM from the artifact —
+            # the facade only needs to declare the React-Core-prebuilt dependency.
+
+            # Re-vend the narrow set of angle-only framework headers that community
+            # modules quote-import (see FACADE_REEXPOSED_HEADERS). The header is
+            # COPIED into the facade dir (a self-contained snapshot — robust, no
+            # `..` globs reaching out of the pod) and exposed as a public header.
+            # It's header-only (a `.h` has nothing to compile, so the facade stays
+            # a placeholder), but CocoaPods lays it into
+            # Pods/Headers/Public/<Name>/<header_dir>/ and dependents' .hmap,
+            # restoring quoted resolution exactly as the source pod did.
+            reexposed = FACADE_REEXPOSED_HEADERS[name]
+            if reexposed
+                copied = copy_reexposed_headers(reexposed["globs"], podspec_dir, dir, name)
+                unless copied.empty?
+                    spec["source_files"] = copied
+                    spec["public_header_files"] = copied
+                    spec["header_dir"] = reexposed["header_dir"] if reexposed["header_dir"]
+                end
+            end
+
+            # Preserve default_subspec so a bare `pod '<Name>'` resolves to the SAME
+            # subspec graph as the source pod (without it CocoaPods pulls every
+            # subspec, which is not graph-equivalent).
+            defaults = Array(real.default_subspecs)
+            spec["default_subspecs"] = defaults unless defaults.empty?
+
+            subspecs = derive_subspecs(real)
+            unless subspecs.empty?
+                spec["subspecs"] = subspecs.map do |ss|
+                    { "name" => ss, "dependencies" => { "React-Core-prebuilt" => [] } }
+                end
+            end
+
+            File.write(File.join(dir, "#{name}.podspec.json"), JSON.pretty_generate(spec))
+        end
+        abs_base
+    end
+
+    # Facade dir for `<name>`, RELATIVE to the install root — pass to `pod :path =>`.
+    # Relative (not absolute) so the path CocoaPods records in Podfile.lock is
+    # portable rather than machine-specific.
+    def self.facade_path(name)
+        File.join(FACADE_RELDIR, name)
+    end
+
+    # Loads the real podspec so we can mirror its structure. A facaded pod MUST have
+    # a readable real podspec — if it's missing or unparseable we raise rather than
+    # ship an empty facade, since that would silently drop subspecs (the very drift
+    # this mechanism exists to prevent).
+    def self.load_real_spec(path, name)
+        unless File.exist?(path)
+            raise "[RNCoreFacades] Real podspec for facaded pod '#{name}' not found at #{path}. " \
+                  "Update FACADE_PODS in rncore_facades.rb if the podspec moved."
+        end
+        Pod::Specification.from_file(path)
+    rescue => e
+        raise "[RNCoreFacades] Failed to read real podspec for facaded pod '#{name}' at #{path}: #{e.message}"
+    end
+    private_class_method :load_real_spec
+
+    # Library (non-test, non-app) subspec names of the real spec, so third-party
+    # libs depending on `<pod>/<subspec>` keep resolving. Derived, never hand-listed.
+    def self.derive_subspecs(real)
+        real.subspecs
+            .reject { |ss| ss.test_specification? || (ss.respond_to?(:app_specification?) && ss.app_specification?) }
+            .map(&:base_name)
+    end
+    private_class_method :derive_subspecs
+
+    # Copy the re-exposed header(s) into the facade dir (flat) and return the
+    # facade-relative source_files entries. `globs` are resolved against the real
+    # podspec dir. A glob that matches nothing is a hard error: the whole point is
+    # to keep a quoted-import header resolvable, so silently shipping a facade
+    # without it would reintroduce the exact "file not found" we're fixing.
+    def self.copy_reexposed_headers(globs, podspec_dir, facade_dir, name)
+        copied = []
+        Array(globs).each do |g|
+            matches = Dir.glob(File.expand_path(g, podspec_dir))
+            if matches.empty?
+                raise "[RNCoreFacades] Re-exposed header glob '#{g}' for facade '#{name}' " \
+                      "matched no files under #{podspec_dir}. Update FACADE_REEXPOSED_HEADERS."
+            end
+            matches.each do |src|
+                base = File.basename(src)
+                FileUtils.cp(src, File.join(facade_dir, base))
+                copied << base
+            end
+        end
+        copied.uniq
+    end
+    private_class_method :copy_reexposed_headers
+end