Cover cxxreact:jsbigstring with Stable API guards

Summary:
Classifies `cxxreact:jsbigstring` as a public target under the C++ stable API three-tier visibility model. Adds `#include <react/cxxstableapi/UmbrellaGuard.h>` to the target's 2 exported C++ headers and introduces the module umbrella `React/JSBigString.h`, wiring the guard dependency into BUCK, CMake and CocoaPods and the umbrella into BUCK, CMake, CocoaPods, the iOS prebuild header config and the Android prefab export.

Consumers that opt into `RN_STRICT_API` now get an error if they include the target's headers directly, and should include `<React/JSBigString.h>` instead; without that flag the guards are inert, so no existing build changes behaviour.

Under `USE_FRAMEWORKS` the pod now maps its headers relative to `ReactCommon`, so they install under `cxxreact/` inside the built framework rather than at its root. Pods that pick up the framework's `Headers` directory through `install_modules_dependencies` are unaffected. `React-RCTFabric`, `ReactCommon` and `React-NativeModulesApple` pin their own search paths instead and are updated here; pods outside the repository that do the same have to make the equivalent change.

Changelog:
[iOS][Breaking] - Install `React-cxxreact` headers under `cxxreact/` inside its framework when `USE_FRAMEWORKS` is enabled. Pods that include `<cxxreact/...>` without calling `install_modules_dependencies` must add `React_cxxreact.framework/Headers` to `HEADER_SEARCH_PATHS`.

Differential Revision: D119144023

Author: j-piasecki

packages/react-native/React/React-RCTFabric.podspec

@@ -66,6 +66,7 @@ Pod::Spec.new do |s|
   s.dependency "RCTSwiftUIWrapper"
 
   add_dependency(s, "React-FabricImage")
+  add_dependency(s, "React-cxxreact")
   add_dependency(s, "React-Fabric", :additional_framework_paths => [
     "react/renderer/components/scrollview/platform/cxx",
     "react/renderer/components/scrollview/platform/ios",

packages/react-native/ReactAndroid/build.gradle.kts

@@ -113,6 +113,7 @@ val preparePrefab by
                       // reactnativejni
                       Pair("src/main/jni/react/jni", "react/jni/"),
                       Pair("../ReactCommon/cxxreact/", "cxxreact/"),
+                      Pair("../ReactCommon/cxxreact/React/", "React/"),
                       // react_featureflags
                       Pair("../ReactCommon/react/featureflags/", "react/featureflags/"),
                       Pair("../ReactCommon/react/featureflags/React/", "React/"),

packages/react-native/ReactCommon/ReactCommon.podspec

@@ -51,7 +51,7 @@ Pod::Spec.new do |s|
 
     ss.subspec "core" do |sss|
       sss.source_files = podspec_sources("react/nativemodule/core/ReactCommon/**/*.{cpp,h}", "react/nativemodule/core/ReactCommon/**/*.h")
-      sss.pod_target_xcconfig  = { "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/ReactCommon\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-debug/React_debug.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-debug/React_featureflags.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-utils/React_utils.framework/Headers\"" }
+      sss.pod_target_xcconfig  = { "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/ReactCommon\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-debug/React_debug.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-debug/React_featureflags.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-utils/React_utils.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-cxxreact/React_cxxreact.framework/Headers\"" }
       sss.dependency "React-bridging"
       sss.dependency "React-cxxreact", version
       sss.dependency "React-debug", version

packages/react-native/ReactCommon/cxxreact/CMakeLists.txt

@@ -12,6 +12,7 @@ file(GLOB react_cxxreact_SRC CONFIGURE_DEPENDS *.cpp)
 add_library(react_cxxreact OBJECT ${react_cxxreact_SRC})
 
 target_include_directories(react_cxxreact PUBLIC ${REACT_COMMON_DIR})
+target_include_directories(react_cxxreact INTERFACE ${REACT_COMMON_DIR}/cxxreact)
 
 target_link_libraries(react_cxxreact
         boost
@@ -22,6 +23,7 @@ target_link_libraries(react_cxxreact
         jsi
         jsinspector
         logger
+        react_cxxstableapi
         reactperflogger
         runtimeexecutor
         react_debug)

packages/react-native/ReactCommon/cxxreact/JSBigString.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <memory>
 #include <string>
 

packages/react-native/ReactCommon/cxxreact/JSBundleType.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <folly/Portability.h>
 #include <cstdint>
 #include <cstring>

packages/react-native/ReactCommon/cxxreact/React-cxxreact.podspec

@@ -34,6 +34,8 @@ Pod::Spec.new do |s|
   }
   s.header_dir             = "cxxreact"
 
+  resolve_use_frameworks(s, header_mappings_dir: "..", module_name: "React_cxxreact")
+
   add_dependency(s, "React-jsinspector", :framework_name => 'jsinspector_modern')
   add_dependency(s, "React-jsinspectorcdp", :framework_name => 'jsinspector_moderncdp')
   add_dependency(s, "React-jsinspectortracing", :framework_name => 'jsinspector_moderntracing')
@@ -45,6 +47,7 @@ Pod::Spec.new do |s|
   s.dependency "React-logger", version
   s.dependency "React-debug", version
   s.dependency "React-timing", version
+  s.dependency "React-cxxstableapi"
   add_dependency(s, "React-utils", :additional_framework_paths => ["react/utils/platform/ios"])
 
   s.resource_bundles = {'React-cxxreact_privacy' => 'PrivacyInfo.xcprivacy'}
@@ -56,5 +59,11 @@ Pod::Spec.new do |s|
   add_rn_third_party_dependencies(s)
   add_rncore_dependency(s)
 
+  s.subspec "cxxreactUmbrella" do |ss|
+    ss.source_files        = "React/*.h"
+    ss.header_dir          = ""
+    ss.header_mappings_dir = "."
+  end
+
   mark_as_react_native_build(s)
 end

packages/react-native/ReactCommon/cxxreact/React/JSBigString.h

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+
+#pragma once
+
+// =============================================================================
+// Umbrella header for the `cxxreact` module - public entry point.
+//
+//   #include <React/JSBigString.h>
+//
+// Re-exports the module's public interface headers. React Native's own code
+// should keep using the fine-grained `<cxxreact/...>` includes; only outside
+// consumers use this umbrella.
+// =============================================================================
+
+// Marks that the following headers are pulled in through the umbrella, so their
+// shared guard (<react/cxxstableapi/UmbrellaGuard.h>) accepts them. The marker
+// is saved and restored rather than defined and undefined: the scope ends at
+// this block, so later *direct* includes in the same TU are still caught, and
+// it nests inside an enclosing umbrella rather than disarming it.
+#pragma push_macro("RN_UMBRELLA_CONTEXT")
+#undef RN_UMBRELLA_CONTEXT
+#define RN_UMBRELLA_CONTEXT 1
+
+#include <cxxreact/JSBigString.h>
+#include <cxxreact/JSBundleType.h>
+
+#undef RN_UMBRELLA_CONTEXT
+#pragma pop_macro("RN_UMBRELLA_CONTEXT")

packages/react-native/ReactCommon/react/nativemodule/core/platform/ios/React-NativeModulesApple.podspec

@@ -40,7 +40,7 @@ Pod::Spec.new do |s|
     s.dependency "React-bridging"
     s.dependency "React-callinvoker"
     s.dependency "React-Core"
-    s.dependency "React-cxxreact"
+    add_dependency(s, "React-cxxreact")
     s.dependency "React-jsi"
     s.dependency "React-featureflags"
     add_dependency(s, "React-debug")

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

@@ -100,6 +100,7 @@ def self.install_modules_dependencies(spec, new_arch_enabled, folly_version = He
                 .concat(ReactNativePodsUtils.create_header_search_path_for_frameworks("PODS_CONFIGURATION_BUILD_DIR", "React-rendererdebug", "React_rendererdebug", []))
                 .concat(ReactNativePodsUtils.create_header_search_path_for_frameworks("PODS_CONFIGURATION_BUILD_DIR", "React-renderercss", "React_renderercss", []))
                 .concat(ReactNativePodsUtils.create_header_search_path_for_frameworks("PODS_CONFIGURATION_BUILD_DIR", "React-cxxstableapi", "React_cxxstableapi", []))
+                .concat(ReactNativePodsUtils.create_header_search_path_for_frameworks("PODS_CONFIGURATION_BUILD_DIR", "React-cxxreact", "React_cxxreact", []))
                 .each { |search_path|
                     header_search_paths << "\"#{search_path}\""
                 }