feat(ios-prebuild)!: make ReactNativeHeaders pure-RN

Every namespace now has exactly ONE physical home: RN namespaces in
ReactNativeHeaders, third-party deps namespaces in the
ReactNativeDependenciesHeaders sidecar / the ReactNativeDependencies
pod. Relocated deps copies are what made the 2026-07-03 SocketRocket
regression possible (duplicate @interface + poisoned module graph under
use_frameworks when a real pod coexisted with relocated copies) - that
bug class is now structurally impossible, and the SocketRocket
exclusion list is deleted rather than maintained.

- headers-spec.js: R2 rewritten; DEPS_NAMESPACES now includes
  SocketRocket (= the sidecar contents = the artifact's Headers/ dirs,
  set-equality enforced); DEPS_NAMESPACES_NOT_RELOCATED deleted.
- headers-compose.js: RNH stages RN headers only; ensureHeadersLayout
  also builds the sidecar from the cache slot's deps headers and
  returns it, so SwiftPM consumers need no published sidecar.
- headers-verify.js: structural gate flipped - deps namespaces must be
  ABSENT from RNH; compile gates take the deps artifact's Headers on
  the include path (exactly how consumers resolve them).
- CocoaPods: NEW ReactNativeDependenciesUtils.configure_aggregate_xcconfig
  injects $(PODS_ROOT)/ReactNativeDependencies/Headers into the
  aggregate and every pod target in prebuilt-deps mode, mirroring the
  rncore injection. Pods previously resolved folly/glog through the
  globally-injected React-Core-prebuilt/Headers flatten of RNH; after
  the flip the deps pod is the single global home, so the mirror
  injection is what keeps arbitrary pods compiling.

Verified: headers gate green (include-health, structural, compile
smokes vs the deps include path); rn-tester prebuilt static + dynamic
(the regression config), helloworld static, source-core+prebuilt-deps
(React compiled from source resolves folly via the deps pod), and a
source-mode control with an unchanged dependency graph.

BREAKING (prebuilt artifacts only): ReactNativeHeaders.xcframework no
longer contains folly/glog/boost/fmt/double-conversion/fast_float;
consumers reaching them through React-Core-prebuilt/Headers must use
the ReactNativeDependencies pod / ReactNativeDependenciesHeaders
sidecar paths instead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: chrfalch

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

@@ -167,9 +167,11 @@ jobs:
         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.
+          # ReactNativeHeaders.xcframework is pure-RN (the deps namespaces ship
+          # in the ReactNativeDependenciesHeaders sidecar built by the deps
+          # prebuild), but the headers-verify compile gates still need the deps
+          # headers on their include path (folly/glog/... reached from RN's
+          # public headers), so the deps artifact is staged here too.
           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

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

@@ -22,11 +22,15 @@ Pod::Spec.new do |s|
   #  - 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.)
+  #  - ReactNativeHeaders.xcframework: headers-only, PURE-RN. Carries every other
+  #    RN namespace (<react/...>, <yoga/...>, ...). Its headers are flattened into
+  #    a top-level Headers/ (see prepare_command) and exposed via the standard pod
+  #    header search path. The third-party deps namespaces (folly/glog/boost/...)
+  #    are NOT here — the ReactNativeDependencies pod serves them from its own
+  #    artifact (see scripts/cocoapods/__docs__/prebuilt-deps.md), wired through
+  #    add_rn_third_party_dependencies below. (<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"
 

packages/react-native/scripts/cocoapods/__docs__/prebuilt-deps.md

@@ -13,17 +13,21 @@ xcframework binary, and the artifact's own
 `Headers/{folly,glog,boost,fmt,double-conversion,fast_float, SocketRocket}` are
 flattened into the pod's `Headers/` by the podspec's `prepare_command`.
 Consumers resolve bare `<folly/...>` / `<SocketRocket/...>` via CocoaPods
-public-header linkage from `s.dependency "ReactNativeDependencies"`, plus an
-explicit `HEADER_SEARCH_PATHS` entry
-(`$(PODS_ROOT)/ReactNativeDependencies/Headers`). The real source pods are
-neither depended on nor searched.
+public-header linkage from `s.dependency "ReactNativeDependencies"`, plus
+`HEADER_SEARCH_PATHS` entries pointing at
+`$(PODS_ROOT)/ReactNativeDependencies/Headers`: per-podspec via
+`add_rn_third_party_dependencies`, and globally (aggregate + every pod target)
+via `ReactNativeDependenciesUtils.configure_aggregate_xcconfig` at post-install
+— ReactNativeHeaders is pure-RN, so this is the only global home of the deps
+namespaces. The real source pods are neither depended on nor searched.
 
-NOTE: this is a CocoaPods-level contract. The deps XCFRAMEWORK itself is NOT
-self-serving: it is framework-type without `HeadersPath`, so its root `Headers/`
-is invisible to SPM binaryTargets (verified 2026-07-04 — `HeadersPath` is
-rejected on framework entries). In SPM the six C++ namespaces are served by
-ReactNativeHeaders.xcframework; serving them from the deps side requires the
-phase-2 headers-only library sidecar (see rn-deps-self-serving plan).
+For SPM, the deps XCFRAMEWORK itself cannot serve headers: it is framework-type
+without `HeadersPath`, and its root `Headers/` is invisible to SPM binaryTargets
+(verified 2026-07-04 — `HeadersPath` is rejected on framework entries). The deps
+prebuild therefore emits a headers-only LIBRARY-type sidecar,
+`ReactNativeDependenciesHeaders.xcframework` (same recipe as ReactNativeHeaders:
+stub archives + per-slice `Headers/`), which SPM auto-serves with zero flags.
+The sidecar ships inside the deps tarball and as a standalone artifact.
 
 ## Why SocketRocket is vended here
 

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

@@ -513,7 +513,9 @@ def self.get_nightly_npm_version()
     # 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 namespace). There is
+    # 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:

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

@@ -150,6 +150,52 @@ def self.abort_if_use_local_rndeps_with_no_file()
       end
     end
 
+    # Single post-install injection site for the prebuilt deps header resolution.
+    # Adds the flattened ReactNativeDependencies/Headers search path to the
+    # aggregate (main app) target AND every pod target, mirroring
+    # ReactNativeCoreUtils.configure_aggregate_xcconfig. ReactNativeHeaders is
+    # pure-RN, so this path is the single global home of the third-party
+    # namespaces (folly/glog/boost/fmt/double-conversion/fast_float/
+    # SocketRocket): pods that never call add_rn_third_party_dependencies (nor
+    # depend on a facade) still compile RN headers that textually reach
+    # <folly/...>. No module-map activation needed — the deps headers are
+    # served textually; modules come from the ReactNativeDependencies pod.
+    def self.configure_aggregate_xcconfig(installer)
+        return if @@build_from_source
+
+        rndeps_log("Configuring xcconfig for prebuilt React Native Dependencies...")
+        headers_search_path = " \"$(PODS_ROOT)/ReactNativeDependencies/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|
+                ReactNativePodsUtils.add_flag_to_map_with_inheritance(config_file.attributes, "HEADER_SEARCH_PATHS", 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 pods that don't go
+        # through add_rn_third_party_dependencies)
+        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 deps header search path is already present
+                header_search_paths = xcconfig.attributes["HEADER_SEARCH_PATHS"] || ""
+                next if header_search_paths.include?("ReactNativeDependencies/Headers")
+
+                ReactNativePodsUtils.add_flag_to_map_with_inheritance(xcconfig.attributes, "HEADER_SEARCH_PATHS", headers_search_path)
+                xcconfig.save_as(xcconfig_path)
+            end
+        end
+
+        rndeps_log("Prebuilt deps xcconfig configuration complete")
+    end
+
     def self.podspec_source_download_prebuild_release_tarball()
         # Warn if @@react_native_path is not set
         if @@react_native_path == ""

packages/react-native/scripts/ios-prebuild/__tests__/headers-spec-test.js

@@ -11,6 +11,7 @@
 'use strict';
 
 const {
+  DEPS_NAMESPACES,
   planFromInventory,
   renderNamespaceModuleMap,
   renderReactModuleMap,
@@ -218,6 +219,22 @@ describe('R11 redirect shims for dual-identity headers', () => {
   });
 });
 
+describe('DEPS_NAMESPACES (R2 — the deps sidecar namespace set)', () => {
+  test('includes SocketRocket: one physical home, in the sidecar', () => {
+    // Pre-sidecar, SocketRocket was excluded from relocation because a REAL
+    // pod vended it (the 2026-07-03 dual-copy regression). With the sidecar
+    // being the deps' single header home, it must be declared like every
+    // other deps namespace.
+    expect(DEPS_NAMESPACES).toContain('SocketRocket');
+  });
+
+  test('plan.depsNamespaces mirrors the spec list', () => {
+    expect(planFromInventory(validManifest()).depsNamespaces).toEqual(
+      DEPS_NAMESPACES,
+    );
+  });
+});
+
 describe('headers-verify gate pieces', () => {
   const {
     diffAgainstBaseline,