From 0344a384d8ce9198ae2b38b4afefafb852fec005 Mon Sep 17 00:00:00 2001
From: Jakub Piasecki <piaseckijakub@meta.com>
Date: Thu, 27 Aug 2026 06:54:38 -0700
Subject: [PATCH] Cover react/runtime with Stable API guards

Summary:
Classifies `react/runtime:runtime` and `react/runtime:runtime-platform` as "for frameworks" targets under the three-tier C++ stable API visibility model. Consumers that opt into `RN_STRICT_API` now get a warning if they include their headers directly, which they can acknowledge with `RN_ALLOW_FRAMEWORKS`; without that flag the guards are inert, so no existing build changes behaviour.

The Apple platform layer is covered alongside the core runtime, so `RCTHost.h` and `RCTInstance.h` are in scope. `React-RuntimeCore` already depended on `React-cxxstableapi` from an earlier migration in the same pod; `React-RuntimeApple` gains the dependency here.

Changelog: [Internal]

Differential Revision: D117690303
---
 .../react-native/ReactCommon/react/runtime/BindingsInstaller.h  | 2 ++
 .../react/runtime/BridgelessNativeMethodCallInvoker.h           | 2 ++
 .../ReactCommon/react/runtime/BufferedRuntimeExecutor.h         | 2 ++
 packages/react-native/ReactCommon/react/runtime/CMakeLists.txt  | 1 +
 .../ReactCommon/react/runtime/PlatformTimerRegistry.h           | 2 ++
 packages/react-native/ReactCommon/react/runtime/ReactInstance.h | 2 ++
 packages/react-native/ReactCommon/react/runtime/TimerManager.h  | 2 ++
 .../react/runtime/platform/ios/React-RuntimeApple.podspec       | 1 +
 .../react/runtime/platform/ios/ReactCommon/ObjCTimerRegistry.h  | 2 ++
 .../platform/ios/ReactCommon/RCTContextContainerHandling.h      | 2 ++
 .../react/runtime/platform/ios/ReactCommon/RCTHermesInstance.h  | 2 ++
 .../react/runtime/platform/ios/ReactCommon/RCTHost+Internal.h   | 2 ++
 .../react/runtime/platform/ios/ReactCommon/RCTHost.h            | 2 ++
 .../react/runtime/platform/ios/ReactCommon/RCTInstance.h        | 2 ++
 .../react/runtime/platform/ios/ReactCommon/RCTJSThreadManager.h | 2 ++
 .../react/runtime/platform/ios/ReactCommon/RCTJscInstance.h     | 2 ++
 .../ios/ReactCommon/RCTLegacyUIManagerConstantsProvider.h       | 2 ++
 .../platform/ios/ReactCommon/RCTPerformanceLoggerUtils.h        | 2 ++
 18 files changed, 34 insertions(+)

diff --git a/packages/react-native/ReactCommon/react/runtime/BindingsInstaller.h b/packages/react-native/ReactCommon/react/runtime/BindingsInstaller.h
index fb4226f50699..2ac39d75d7eb 100644
--- a/packages/react-native/ReactCommon/react/runtime/BindingsInstaller.h
+++ b/packages/react-native/ReactCommon/react/runtime/BindingsInstaller.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #include <react/runtime/ReactInstance.h>
 
 namespace facebook::react {
diff --git a/packages/react-native/ReactCommon/react/runtime/BridgelessNativeMethodCallInvoker.h b/packages/react-native/ReactCommon/react/runtime/BridgelessNativeMethodCallInvoker.h
index 57dc1999b6f3..19afec86b7b3 100644
--- a/packages/react-native/ReactCommon/react/runtime/BridgelessNativeMethodCallInvoker.h
+++ b/packages/react-native/ReactCommon/react/runtime/BridgelessNativeMethodCallInvoker.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #include <ReactCommon/CallInvoker.h>
 #include <cxxreact/MessageQueueThread.h>
 #include <memory>
diff --git a/packages/react-native/ReactCommon/react/runtime/BufferedRuntimeExecutor.h b/packages/react-native/ReactCommon/react/runtime/BufferedRuntimeExecutor.h
index 274015587fde..54178ba6f986 100644
--- a/packages/react-native/ReactCommon/react/runtime/BufferedRuntimeExecutor.h
+++ b/packages/react-native/ReactCommon/react/runtime/BufferedRuntimeExecutor.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #include <ReactCommon/RuntimeExecutor.h>
 #include <jsi/jsi.h>
 #include <atomic>
diff --git a/packages/react-native/ReactCommon/react/runtime/CMakeLists.txt b/packages/react-native/ReactCommon/react/runtime/CMakeLists.txt
index 0cf910be5bfd..da494a138033 100644
--- a/packages/react-native/ReactCommon/react/runtime/CMakeLists.txt
+++ b/packages/react-native/ReactCommon/react/runtime/CMakeLists.txt
@@ -34,6 +34,7 @@ target_link_libraries(
         jsi
         jsitooling
         jsireact
+        react_cxxstableapi
         react_utils
         jsinspector
         react_featureflags
diff --git a/packages/react-native/ReactCommon/react/runtime/PlatformTimerRegistry.h b/packages/react-native/ReactCommon/react/runtime/PlatformTimerRegistry.h
index c0bb2ce3716a..de6ab5512982 100644
--- a/packages/react-native/ReactCommon/react/runtime/PlatformTimerRegistry.h
+++ b/packages/react-native/ReactCommon/react/runtime/PlatformTimerRegistry.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #include <cstdint>
 #include <memory>
 
diff --git a/packages/react-native/ReactCommon/react/runtime/ReactInstance.h b/packages/react-native/ReactCommon/react/runtime/ReactInstance.h
index b850d0fac316..33b5910baa0c 100644
--- a/packages/react-native/ReactCommon/react/runtime/ReactInstance.h
+++ b/packages/react-native/ReactCommon/react/runtime/ReactInstance.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #include <ReactCommon/RuntimeExecutor.h>
 #include <cxxreact/JSBigString.h>
 #include <cxxreact/MessageQueueThread.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/TimerManager.h b/packages/react-native/ReactCommon/react/runtime/TimerManager.h
index 9da5669d7fc7..7ace46ee81fd 100644
--- a/packages/react-native/ReactCommon/react/runtime/TimerManager.h
+++ b/packages/react-native/ReactCommon/react/runtime/TimerManager.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #include <ReactCommon/RuntimeExecutor.h>
 #include <unordered_map>
 #include <vector>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/React-RuntimeApple.podspec b/packages/react-native/ReactCommon/react/runtime/platform/ios/React-RuntimeApple.podspec
index 947cd5c69d19..175b9968cbca 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/React-RuntimeApple.podspec
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/React-RuntimeApple.podspec
@@ -55,6 +55,7 @@ Pod::Spec.new do |s|
   s.dependency "React-jserrorhandler"
   s.dependency "React-jsinspector"
   s.dependency "React-featureflags"
+  s.dependency "React-cxxstableapi"
   add_dependency(s, "React-jsitooling", :framework_name => "JSITooling")
   add_dependency(s, "React-RCTFBReactNativeSpec")
   add_dependency(s, "React-utils", :additional_framework_paths => ["react/utils/platform/ios"])
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/ObjCTimerRegistry.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/ObjCTimerRegistry.h
index 7d566f513e1e..827f11d98910 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/ObjCTimerRegistry.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/ObjCTimerRegistry.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import <UIKit/UIKit.h>
 
 #import <React/RCTTiming.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTContextContainerHandling.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTContextContainerHandling.h
index 1fc73afe85dd..411b928bc2e8 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTContextContainerHandling.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTContextContainerHandling.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import <Foundation/Foundation.h>
 
 #import <react/utils/ContextContainer.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHermesInstance.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHermesInstance.h
index c7bc46026c5f..ad2cf29bcf68 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHermesInstance.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHermesInstance.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import <hermes/Public/CrashManager.h>
 #import <jsi/jsi.h>
 #import <react/runtime/JSRuntimeFactory.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost+Internal.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost+Internal.h
index d039fa668f04..e7cfe255d022 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost+Internal.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost+Internal.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import "RCTHost.h"
 
 #import "RCTContextContainerHandling.h"
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost.h
index d845c8e46904..cd2f5d546c4f 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import <Foundation/Foundation.h>
 
 #import <React/RCTDefines.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTInstance.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTInstance.h
index 72b7585184e6..b0aaf2dff5f5 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTInstance.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTInstance.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import <UIKit/UIKit.h>
 
 #import <React/RCTDefines.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTJSThreadManager.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTJSThreadManager.h
index ce64c55fdf04..0b98de49f79c 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTJSThreadManager.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTJSThreadManager.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import <Foundation/Foundation.h>
 
 #import <React/RCTMessageThread.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTJscInstance.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTJscInstance.h
index e0da9c1fd6a4..24e507de19b1 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTJscInstance.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTJscInstance.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import <cxxreact/MessageQueueThread.h>
 #import <jsi/jsi.h>
 #import <react/runtime/JSRuntimeFactory.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTLegacyUIManagerConstantsProvider.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTLegacyUIManagerConstantsProvider.h
index 8711745df841..316bdfc81bf3 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTLegacyUIManagerConstantsProvider.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTLegacyUIManagerConstantsProvider.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #ifndef RCT_REMOVE_LEGACY_COMPONENT_INTEROP
 
 #include <jsi/jsi.h>
diff --git a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTPerformanceLoggerUtils.h b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTPerformanceLoggerUtils.h
index 85a86fc07f94..9c080bf1cea8 100644
--- a/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTPerformanceLoggerUtils.h
+++ b/packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTPerformanceLoggerUtils.h
@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#include <react/cxxstableapi/FrameworksGuard.h>
+
 #import <Foundation/Foundation.h>
 
 @class RCTPerformanceLogger;