Add stable public CallInvoker C++ entry point (#58159)

Summary:
Pull Request resolved: #58159

Pull Request resolved: #58049

Add `<React/CallInvoker.h>` as the canonical public C++ entry point for `CallInvoker`, `NativeMethodCallInvoker`, and `SchedulerPriority`. Guard direct leaf-header inclusion for strict API consumers while preserving existing React Native builds and legacy include paths.

Export and stage the umbrella consistently through Buck, CMake, Android Prefab, CocoaPods, and the Apple prebuilt-header inventory. SwiftPM needs no change, since its header mapping for this module already preserves the directory structure.

The `ios-prebuild` header configuration needs an explicit entry here: the generic podspec parser only reads the first `header_dir`, so it would have flattened the umbrella into `ReactCommon/` and collided with the existing leaf header of the same basename.

Changelog:
[Internal]

Reviewed By: cipolleschi

Differential Revision: D116921026

fbshipit-source-id: 1838a18632f4493f22397bfebe44f38895cbfc7d

Author: j-piasecki

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

@@ -233,6 +233,7 @@ val preparePrefab by
                       Pair(File(buildDir, "third-party-ndk/folly/").absolutePath, ""),
                       Pair(File(buildDir, "third-party-ndk/glog/exported/").absolutePath, ""),
                       Pair("../ReactCommon/callinvoker/", ""),
+                      Pair("../ReactCommon/callinvoker/React/", "React/"),
                       Pair("../ReactCommon/cxxreact/", "cxxreact/"),
                       // Exported because the public cxxreact/ErrorUtils.h includes it
                       Pair("../ReactCommon/jserrorhandler/", "jserrorhandler/"),

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

@@ -11,5 +11,6 @@ include(${REACT_COMMON_DIR}/cmake-utils/react-native-flags.cmake)
 add_library(callinvoker INTERFACE)
 
 target_include_directories(callinvoker INTERFACE .)
+target_link_libraries(callinvoker INTERFACE react_cxxstableapi)
 target_compile_reactnative_options(callinvoker INTERFACE)
 target_compile_options(callinvoker INTERFACE -Wpedantic)

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

@@ -16,6 +16,12 @@ else
   source[:tag] = "v#{version}"
 end
 
+header_search_paths = []
+
+if ENV['USE_FRAMEWORKS']
+  header_search_paths << "\"$(PODS_TARGET_SRCROOT)/..\"" # ReactCommon, for <react/cxxstableapi/...>
+end
+
 Pod::Spec.new do |s|
   s.name                   = "React-callinvoker"
   s.version                = version
@@ -26,7 +32,17 @@ Pod::Spec.new do |s|
   s.platforms              = min_supported_versions
   s.source                 = source
   s.source_files           = podspec_sources("**/*.{cpp,h}", "**/*.h")
+  s.exclude_files          = "React"
+  s.pod_target_xcconfig    = { "HEADER_SEARCH_PATHS" => header_search_paths.join(' ') }
   s.header_dir             = "ReactCommon"
 
+  s.subspec "CallInvokerUmbrella" do |ss|
+    ss.source_files        = "React/*.h"
+    ss.header_dir          = "React"
+    ss.header_mappings_dir = "React"
+  end
+
+  s.dependency "React-cxxstableapi"
+
   mark_as_react_native_build(s)
 end

packages/react-native/ReactCommon/callinvoker/React/CallInvoker.h

@@ -0,0 +1,27 @@
+/*
+ * 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 `callinvoker` module - public entry point.
+//
+//   #include <React/CallInvoker.h>
+//
+// Re-exports the module's public interface headers. React Native's own code
+// should keep using the fine-grained `<ReactCommon/...>` 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.
+#define RN_UMBRELLA_CONTEXT
+
+#include <ReactCommon/CallInvoker.h>
+#include <ReactCommon/SchedulerPriority.h>
+
+#undef RN_UMBRELLA_CONTEXT

packages/react-native/ReactCommon/callinvoker/ReactCommon/CallInvoker.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include "SchedulerPriority.h"
 
 #include <functional>

packages/react-native/ReactCommon/callinvoker/ReactCommon/SchedulerPriority.h

@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 namespace facebook::react {
 
 enum class SchedulerPriority : int {

packages/react-native/scripts/ios-prebuild/headers-config.js

@@ -513,6 +513,19 @@ const PodspecExceptions /*: {[key: string]: PodSpecConfiguration} */ = {
       },
     ],
   },
+  'ReactCommon/callinvoker/React-callinvoker.podspec': {
+    name: 'React-callinvoker',
+    headerPatterns: ['**/*.h'],
+    excludePatterns: ['React/**'],
+    headerDir: 'ReactCommon',
+    subSpecs: [
+      {
+        name: 'CallInvokerUmbrella',
+        headerPatterns: ['React/*.h'],
+        headerDir: 'React',
+      },
+    ],
+  },
   'React-Core.podspec': {
     name: 'React-Core',
     headerPatterns: [],