refactor(ios): remove clang VFS overlay, resolve headers via new ReactNativeHeaders framework (#57285)

Summary:
The prebuilt `React.xcframework` previously relied on a Clang VFS overlay (`React-VFS.yaml`) to make headers importable, because the headers were laid out in CocoaPods-style namespaced folders rather than standard framework conventions. The overlay had to be generated at build time, re-resolved at pod-install time per slice, and injected as `-ivfsoverlay` flags into every Obj-C, C++, and Swift compile (including aggregate and third-party pod targets).

This is fragile, hard to reason about, and incompatible with SwiftPM consumption.

This PR removes the VFS overlay entirely and resolves headers through standard framework/header-search-path mechanics instead.

**Headers are now emitted into the artifact according to an explicit, executable spec:**

- **`React.xcframework`** — each slice's `React.framework` carries every `<React/...>` header plus a framework module map, so `#import <React/...>` and `import React` resolve through `FRAMEWORK_SEARCH_PATHS` automatically.
- **`ReactNativeHeaders.xcframework`** (new, headers-only) — carries every other namespace (`<react/...>`, `<yoga/...>`, `folly`, `glog`, …), shipped alongside in the prebuilt tarball and exposed via a single header search path.
- This makes `ReactNativeDependencies` binary-only.

No clang VFS overlay, no per-target `-ivfsoverlay` flags. The layout is driven by a single source of truth (`headers-spec.js`, rules R1–R11) that both the prebuild compose step and downstream SwiftPM tooling derive from, so the shipped header set cannot drift from the spec.

Source headers are byte-identical to the repo — the only consumer-facing change needed is bare-form angle includes (`#import <RCTAppDelegate.h>` → `#import <React/RCTAppDelegate.h>`).

**Consumer surfaces the flattened layout initially dropped are restored** (validated against Expo and community Fabric modules):

- Private headers (`RCTBridge+Private.h` + the Fabric `RCTComponentView*` family) are exposed in the `React` module map — modular where safe, `textual` where they reach C++ — so frameworks like Expo compile unchanged, incl. Swift access to `RCTBridge.moduleRegistry`.
- `React_RCTAppDelegate-umbrella.h` is re-emitted (derived from the live header set) for consumers probing it via `__has_include`.
- Sources shipping under multiple include spellings (`React/X.h` + legacy `CoreModules/…`, `RCTImage/…`, bare aliases — 116 today) keep content at ONE module-owned spelling; other spellings become generated redirect shims, so `-fmodules` consumers cannot hit duplicate declarations.
- The `React-RCTFabric` facade re-vends `RCTFabricComponentsPlugins.h` at `header_dir "React"`, keeping community Fabric modules' quoted `#import "RCTFabricComponentsPlugins.h"` working as with source pods.

**The layout is verified at generator time** (`headers-verify.js`, runs in the prebuild compose CI job): unresolvable includes ratchet against a committed baseline, composed module maps/umbrellas must byte-match the spec render, and consumer-shaped compile smokes must pass (the `React` module, every namespace module, an Expo-shaped ObjC++ fixture, and a Swift `moduleRegistry` fixture). Fail-closed guards cover header collisions, allowlist drift, and missing OR undeclared third-party deps namespaces (the latter surfaced `SocketRocket`, which is deliberately NOT relocated — the real pod vends it, and textual copies collide under `use_frameworks`; the gate asserts its absence).

**Key changes**

- **New**: `headers-spec.js` (the executable layout contract, R1–R11), `headers-compose.js` (emitter for both xcframeworks), `headers-inventory.js` (podspec-driven header classifier feeding the spec + a diagnostic manifest), `headers-verify.js` (generator-time gate + CI step), `__docs__/headers-rules.md` (rules + rationale).
- **Removed**: `vfs.js`, VFS types in `types.js`, and the VFS processing/flag-injection paths in `rncore.rb` and `xcframework.js`.
- **Updated**: `React-Core-prebuilt.podspec` (vends both xcframeworks, flattens `ReactNativeHeaders` headers into `Headers/` via `prepare_command`, fails closed on incomplete tarballs), `rncore.rb` / `react_native_pods.rb` (header search path instead of overlay flags), `prebuild-ios-core.yml` (core tarball ships both xcframeworks; compose job verifies the composed headers), README (VFS docs replaced with the new model).
- Added facades to the Podspecs that shouldn't be in use when running using precompiled frameworks to satisfy dependencies as empty pod-specs (with the single `RCTFabricComponentsPlugins.h` re-vend exception noted above).

## Changelog:

[IOS] [CHANGED] - Remove the Clang VFS overlay from prebuilt React Native Core; resolve headers via React.xcframework + a new headers-only ReactNativeHeaders.xcframework

Pull Request resolved: #57285

Test Plan:
- [x] rn-tester builds against the prebuilt `React-Core-prebuilt` pod (Debug + Release) with no `-ivfsoverlay` flags present in the generated xcconfigs.
- [x] rn-tester builds against React native source code (without any prebuilt artifacts)
- [x] `#import <React/...>`, `import React;`, and the relocated namespaces (`<react/...>`, `<yoga/...>`, `folly`/`glog`) all resolve.
- [x] Prebuilt tarball contains both `React.xcframework` and `ReactNativeHeaders.xcframework`; pod install flattens headers into `React-Core-prebuilt/Headers`.
- [x] Switch RN-tester between Debug/Release and verify that both `React.xcframework` and `ReactNativeHeaders.xcframework` are changed between debug and release correctly.
- [x] `headers-verify.js` gate green on Debug and Release composes (`-Werror=non-modular-include-in-framework-module` never trips in consumer builds).
- [x] `private/helloworld` builds against the prebuilt core (CocoaPods path).
- [x] Expo SDK compiles against the prebuilt artifacts (private headers, `React_RCTAppDelegate` umbrella probe, Fabric quoted imports).

Reviewed By: fabriziocucci

Differential Revision: D111448598

Pulled By: cipolleschi

fbshipit-source-id: 72bc2f37765ad425722161a038e410ba976858a5

Author: chrfalch

.github/workflows/prebuild-ios-core.yml

@@ -157,6 +157,22 @@ jobs:
           pattern: prebuild-ios-core-headers-${{ matrix.flavor }}-*
           path: packages/react-native/.build/headers
           merge-multiple: true
+      - name: Download ReactNativeDependencies
+        if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
+        uses: actions/download-artifact@v7
+        with:
+          name: ReactNativeDependencies${{ matrix.flavor }}.xcframework.tar.gz
+          path: /tmp/third-party/
+      - name: Extract ReactNativeDependencies
+        if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
+        shell: bash
+        run: |
+          # ReactNativeHeaders.xcframework (built by the compose step) folds in
+          # the third-party deps namespaces (folly/glog/boost/...), so the deps
+          # headers must be staged here too — not just in build-slices.
+          tar -xzf /tmp/third-party/ReactNativeDependencies${{ matrix.flavor }}.xcframework.tar.gz -C /tmp/third-party/
+          mkdir -p packages/react-native/third-party/
+          mv /tmp/third-party/packages/react-native/third-party/ReactNativeDependencies.xcframework packages/react-native/third-party/ReactNativeDependencies.xcframework
       - name: Setup Keychain
         if: ${{ steps.restore-ios-xcframework.outputs.cache-hit != 'true' && env.REACT_ORG_CODE_SIGNING_P12_CERT != '' }}
         uses: apple-actions/import-codesign-certs@v3 # https://github.com/marketplace/actions/import-code-signing-certificates
@@ -173,11 +189,24 @@ jobs:
         run: |
           cd packages/react-native
           node scripts/ios-prebuild -c -f "${{ matrix.flavor }}" -i "React Org"
+      - name: Verify composed headers
+        if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
+        run: |
+          # Generator-time header gate: include-health ratchet, structural
+          # byte-compare of module maps/umbrellas against the spec render, and
+          # compile smokes (React module + every namespace module + the
+          # privileged-consumer/Expo fixtures). Catches consumer-facing header
+          # regressions here instead of in downstream builds.
+          cd packages/react-native
+          node scripts/ios-prebuild/headers-verify.js --flavor "${{ matrix.flavor }}"
       - name: Compress and Rename XCFramework
         if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
         run: |
           cd packages/react-native/.build/output/xcframeworks/${{matrix.flavor}}
-          tar -cz -f ../ReactCore${{matrix.flavor}}.xcframework.tar.gz React.xcframework
+          # Ship BOTH xcframeworks: React-Core-prebuilt's prepare_command flattens
+          # ReactNativeHeaders.xcframework's Headers (incl. module.modulemap) into the
+          # pod. Omitting it leaves consumers without React-Core-prebuilt/Headers/module.modulemap.
+          tar -cz -f ../ReactCore${{matrix.flavor}}.xcframework.tar.gz React.xcframework ReactNativeHeaders.xcframework
       - name: Compress and Rename dSYM
         if: steps.restore-ios-xcframework.outputs.cache-hit != 'true'
         run: |

packages/react-native/React-Core-prebuilt.podspec

@@ -17,36 +17,60 @@ Pod::Spec.new do |s|
   s.author                 = "Meta Platforms, Inc. and its affiliates"
   s.platforms              = min_supported_versions
   s.source                 = source
+
+  # We vend two xcframeworks that ship together in the prebuilt tarball:
+  #  - React.xcframework: the compiled core. Its per-slice React.framework carries
+  #    every <React/...> header + the framework module map, so `#import <React/...>`
+  #    and `@import React;` resolve through FRAMEWORK_SEARCH_PATHS automatically.
+  #  - ReactNativeHeaders.xcframework: headers-only. Carries every other namespace
+  #    (<react/...>, <yoga/...>, folly, glog, ...). Its headers are flattened into a
+  #    top-level Headers/ (see prepare_command) and exposed via the standard pod
+  #    header search path. (<hermes/...> is supplied by the hermes-engine pod here;
+  #    it is folded into ReactNativeHeaders only on the SwiftPM consumer side.)
+  # There is no clang VFS overlay.
   s.vendored_frameworks    = "React.xcframework"
 
   s.preserve_paths       = '**/*.*'
-  s.header_mappings_dir  = 'React.xcframework/Headers'
-  s.source_files         = 'React.xcframework/Headers/**/*.{h,hpp}'
-
-  s.module_name          = 'React'
-  s.module_map           = 'React.xcframework/Modules/module.modulemap'
-  s.public_header_files  = 'React.xcframework/Headers/**/*.h'
+  s.header_mappings_dir  = 'Headers'
+  s.source_files         = 'Headers/**/*.{h,hpp}'
+  s.public_header_files  = 'Headers/**/*.h'
 
   add_rn_third_party_dependencies(s)
 
-  # We need to make sure that the React.xcframework is copied correctly - in the downloaded tarball
-  # the root directory is the framework, but when using it we need to have it in a subdirectory
-  # called React.xcframework, so we need to move the contents of the tarball into that directory.
-  # This is done in the prepare_command.
-  # We need to make sure that the headers are copied to the right place - local tar.gz has a different structure
-  # than the one from the maven repo
+  # The downloaded tarball ships React.xcframework and ReactNativeHeaders.xcframework
+  # at its root. We make sure React.xcframework is in its own subdirectory (the Maven
+  # tarball lays the framework contents at the root; the local tar.gz has a different
+  # structure) and flatten ReactNativeHeaders' headers into a top-level Headers/ dir
+  # so CocoaPods exposes them on the header search path.
   s.prepare_command = <<~'CMD'
     CURRENT_PATH=$(pwd)
     XCFRAMEWORK_PATH="${CURRENT_PATH}/React.xcframework"
 
-    # Check if XCFRAMEWORK_PATH is empty
-    if [ -z "$XCFRAMEWORK_PATH" ]; then
-      echo "ERROR: XCFRAMEWORK_PATH is empty."
-      exit 0
+    # Flatten ReactNativeHeaders' headers (identical across slices) into Headers/
+    # BEFORE we sweep stray root entries into React.xcframework. Fail closed:
+    # a tarball without ReactNativeHeaders.xcframework (an artifact published
+    # before the headers-spec layout, or a truncated download) would otherwise
+    # yield a green install with an empty Headers/ and every <react/...> or
+    # <yoga/...> include failing much later, far from the cause.
+    mkdir -p Headers
+    RNH_XCFRAMEWORK_PATH=$(find "$CURRENT_PATH" -type d -name "ReactNativeHeaders.xcframework" | head -n 1)
+    if [ -z "$RNH_XCFRAMEWORK_PATH" ]; then
+      echo "[React-Core-prebuilt] ERROR: ReactNativeHeaders.xcframework not found in the prebuilt tarball." >&2
+      echo "The artifact predates the headers-spec layout or is incomplete; use a matching react-native version." >&2
+      exit 1
+    fi
+    RNH_HEADERS_PATH=$(find "$RNH_XCFRAMEWORK_PATH" -type d -name "Headers" | head -n 1)
+    if [ -z "$RNH_HEADERS_PATH" ]; then
+      echo "[React-Core-prebuilt] ERROR: no Headers directory inside $RNH_XCFRAMEWORK_PATH." >&2
+      exit 1
     fi
+    cp -R "$RNH_HEADERS_PATH/." Headers
+    rm -rf "$RNH_XCFRAMEWORK_PATH"
 
     mkdir -p "${XCFRAMEWORK_PATH}"
-    find "$CURRENT_PATH" -mindepth 1 -maxdepth 1 ! -name "$(basename "$XCFRAMEWORK_PATH")" -exec mv {} "$XCFRAMEWORK_PATH" \;
+    find "$CURRENT_PATH" -mindepth 1 -maxdepth 1 \
+      ! -name "$(basename "$XCFRAMEWORK_PATH")" ! -name "Headers" \
+      -exec mv {} "$XCFRAMEWORK_PATH" \;
   CMD
 
   # If we are passing a local tarball, we don't want to switch between Debug and Release

packages/react-native/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

packages/react-native/scripts/cocoapods/rncore.rb

@@ -11,30 +11,16 @@
 
 ### 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()
-        # Add the dependency
         s.dependency "React-Core-prebuilt"
-
-        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)
-
-        # Add VFS overlay flags for both Objective-C and Swift
-        # The VFS overlay file is pre-resolved at pod install time for each platform slice.
-        # We reference it directly in the xcframework using the React-VFS.yaml file that
-        # is written to the React-Core-prebuilt folder during setup_vfs_overlay.
-        # See scripts/ios-prebuild/__docs__/README.md for more details on VFS overlays.
-        vfs_overlay_flag = "-ivfsoverlay $(PODS_ROOT)/React-Core-prebuilt/React-VFS.yaml"
-        current_pod_target_xcconfig["OTHER_CFLAGS"] ||= "$(inherited)"
-        current_pod_target_xcconfig["OTHER_CFLAGS"] += " #{vfs_overlay_flag}"
-        current_pod_target_xcconfig["OTHER_CPLUSPLUSFLAGS"] ||= "$(inherited)"
-        current_pod_target_xcconfig["OTHER_CPLUSPLUSFLAGS"] += " #{vfs_overlay_flag}"
-        # For Swift, we need to use -Xcc to pass flags to the underlying Clang compiler
-        # Both the flag and its argument need separate -Xcc prefixes
-        current_pod_target_xcconfig["OTHER_SWIFT_FLAGS"] ||= "$(inherited)"
-        current_pod_target_xcconfig["OTHER_SWIFT_FLAGS"] += " -Xcc -ivfsoverlay -Xcc $(PODS_ROOT)/React-Core-prebuilt/React-VFS.yaml"
-
-        s.pod_target_xcconfig = current_pod_target_xcconfig
     end
 end
 
@@ -521,96 +507,65 @@ def self.get_nightly_npm_version()
         return latest_nightly
     end
 
-    # Processes the VFS overlay file from the React.xcframework to resolve the ${ROOT_PATH} placeholder.
-    # This method should be called from react_native_post_install after pod install completes.
+    # 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.)
     #
-    # The VFS overlay file maps header import paths to their actual locations within the xcframework.
-    # Since the xcframework contains platform-specific slices, we generate a resolved VFS file for each
-    # slice and also create a default VFS file that can be used immediately (before script phases run).
-    def self.process_vfs_overlay()
-        return if @@build_from_source
-
-        prebuilt_path = File.join(Pod::Config.instance.project_pods_root, "React-Core-prebuilt")
-        xcframework_path = File.join(prebuilt_path, "React.xcframework")
-        vfs_template_path = File.join(xcframework_path, "React-VFS-template.yaml")
-
-        unless File.exist?(vfs_template_path)
-            rncore_log("VFS overlay template not found at #{vfs_template_path}", :error)
-            exit 1
-        end
-
-        rncore_log("Processing VFS overlay file...")
-
-        # Read the template content
-        vfs_template_content = File.read(vfs_template_path)
-
-        # Write the VFS file - use the top-level xcframework path
-        # so that ${ROOT_PATH}/Headers points to the xcframework's Headers folder
-        resolved_vfs_content = vfs_template_content.gsub('${ROOT_PATH}', xcframework_path)
-        resolved_vfs_path = File.join(prebuilt_path, "React-VFS.yaml")
-        File.write(resolved_vfs_path, resolved_vfs_content)
-        rncore_log("  Created VFS overlay at #{resolved_vfs_path}")
-
-        rncore_log("VFS overlay setup complete")
-    end
-
-    # Configures the xcconfig files for aggregate (main app) targets to enable VFS overlay for React Native Core.
-    # This is needed because the main app target does not go through podspec processing,
-    # so it won't get the VFS overlay flags from add_rncore_dependency.
+    # `<React/...>` resolves through the vendored React.framework; this adds the search
+    # path to the flattened ReactNativeHeaders headers (every other namespace). There is
+    # no clang VFS overlay.
     #
     # Parameters:
     # - installer: The CocoaPods installer object
     def self.configure_aggregate_xcconfig(installer)
         return if @@build_from_source
 
-        prebuilt_path = File.join(Pod::Config.instance.project_pods_root, "React-Core-prebuilt")
-        vfs_overlay_path = File.join(prebuilt_path, "React-VFS.yaml")
-
-        unless File.exist?(vfs_overlay_path)
-            rncore_log("VFS overlay not found at #{vfs_overlay_path}, skipping prebuilt xcconfig configuration", :error)
-            exit 1
-        end
-
         rncore_log("Configuring xcconfig for prebuilt React Native Core...")
 
-        vfs_overlay_flag = " -ivfsoverlay \"#{vfs_overlay_path}\""
-        swift_vfs_overlay_flag = " -Xcc -ivfsoverlay -Xcc \"#{vfs_overlay_path}\""
+        headers_search_path = " \"$(PODS_ROOT)/React-Core-prebuilt/Headers\""
 
-        # Add flags to aggregate target xcconfigs (these are used by the main app target)
+        # 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_vfs_overlay_flags(config_file.attributes, vfs_overlay_flag, swift_vfs_overlay_flag)
+                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 flags to ALL pod targets (for third-party pods that don't call add_rncore_dependency)
+        # 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)
 
-                # Check if VFS overlay is already present
-                other_cflags = xcconfig.attributes["OTHER_CFLAGS"] || ""
-                next if other_cflags.include?("ivfsoverlay")
+                # 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_vfs_overlay_flags(xcconfig.attributes, vfs_overlay_flag, swift_vfs_overlay_flag)
+                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 VFS overlay flags to an xcconfig attributes map
-    def self.add_vfs_overlay_flags(attributes, vfs_overlay_flag, swift_vfs_overlay_flag)
-        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_CFLAGS", vfs_overlay_flag)
-        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_CPLUSPLUSFLAGS", vfs_overlay_flag)
-        ReactNativePodsUtils.add_flag_to_map_with_inheritance(attributes, "OTHER_SWIFT_FLAGS", swift_vfs_overlay_flag)
+    # 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_SWIFT_FLAGS", " -Xcc" + module_map_flag)
     end
 end