react-native-tvos 0.86.0-2 → 0.87.0-0

package/ReactCommon/cxxreact/ReactNativeVersion.h

@@ -13,16 +13,16 @@
 #include <string_view>
 
 #define REACT_NATIVE_VERSION_MAJOR 0
-#define REACT_NATIVE_VERSION_MINOR 86
+#define REACT_NATIVE_VERSION_MINOR 87
 #define REACT_NATIVE_VERSION_PATCH 0
 
 namespace facebook::react {
 
 struct ReactNativeVersionType {
   int32_t Major = 0;
-  int32_t Minor = 86;
+  int32_t Minor = 87;
   int32_t Patch = 0;
-  std::string_view Prerelease = "2";
+  std::string_view Prerelease = "0";
 };
 
 constexpr ReactNativeVersionType ReactNativeVersion;

package/ReactCommon/cxxreact/TraceSection.h

@@ -110,7 +110,7 @@ using TraceSectionUnwrapped = DummyTraceSection;
  * In the case of WITH_LOOM_TRACE we don't use the signposts APIs because of the
  * templated type for TraceSection.
  */
-#if defined(__APPLE__) && OS_LOG_TARGET_HAS_10_15_FEATURES && !defined(WITH_LOOM_TRACE)
+#if defined(__APPLE__) && OS_LOG_TARGET_HAS_10_15_FEATURES && !defined(WITH_LOOM_TRACE) && !defined(WITH_PERFETTO)
 
 namespace systrace {
 

package/ReactCommon/cxxreact/tests/methodcall.cpp

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+#ifndef RCT_REMOVE_LEGACY_ARCH
+
 #include <cxxreact/MethodCall.h>
 
 #include <folly/json.h>
@@ -152,3 +154,5 @@ TEST(parseMethodCalls, ParseTwoCalls) {
   auto returnedCalls = parseMethodCalls(folly::parseJson(jsText));
   EXPECT_EQ(2, returnedCalls.size());
 }
+
+#endif // RCT_REMOVE_LEGACY_ARCH

package/ReactCommon/hermes/executor/HermesExecutorFactory.cpp

@@ -17,11 +17,6 @@
 
 #include <hermes/inspector-modern/chrome/HermesRuntimeTargetDelegate.h>
 
-#if defined(HERMES_ENABLE_DEBUGGER) && !defined(HERMES_V1_ENABLED)
-#include <hermes/inspector-modern/chrome/Registration.h>
-#include <hermes/inspector/RuntimeAdapter.h>
-#endif
-
 using namespace facebook::hermes;
 using namespace facebook::jsi;
 
@@ -29,43 +24,6 @@ namespace facebook::react {
 
 namespace {
 
-#if defined(HERMES_ENABLE_DEBUGGER) && !defined(HERMES_V1_ENABLED)
-
-class HermesExecutorRuntimeAdapter
-    : public facebook::hermes::inspector_modern::RuntimeAdapter {
- public:
-  HermesExecutorRuntimeAdapter(
-      std::shared_ptr<HermesRuntime> runtime,
-      std::shared_ptr<MessageQueueThread> thread)
-      : runtime_(runtime), thread_(std::move(thread)) {}
-
-  virtual ~HermesExecutorRuntimeAdapter() = default;
-
-  HermesRuntime& getRuntime() override {
-    return *runtime_;
-  }
-
-  void tickleJs() override {
-    thread_->runOnQueue(
-        [weakRuntime = std::weak_ptr<HermesRuntime>(runtime_)]() {
-          auto runtime = weakRuntime.lock();
-          if (!runtime) {
-            return;
-          }
-          jsi::Function func =
-              runtime->global().getPropertyAsFunction(*runtime, "__tickleJs");
-          func.call(*runtime);
-        });
-  }
-
- private:
-  std::shared_ptr<HermesRuntime> runtime_;
-
-  std::shared_ptr<MessageQueueThread> thread_;
-};
-
-#endif // defined(HERMES_ENABLE_DEBUGGER) && !defined(HERMES_V1_ENABLED)
-
 struct ReentrancyCheck {
 // This is effectively a very subtle and complex assert, so only
 // include it in builds which would include asserts.
@@ -133,14 +91,11 @@ struct ReentrancyCheck {
 #endif
 };
 
-// This adds ReentrancyCheck and debugger enable/teardown to the given
-// Runtime.
+// This adds ReentrancyCheck to the given Runtime.
 class DecoratedRuntime : public jsi::WithRuntimeDecorator<ReentrancyCheck> {
  public:
   // The first argument may be another decorater which itself
   // decorates the real HermesRuntime, depending on the build config.
-  // The second argument is the real HermesRuntime as well to
-  // manage the debugger registration.
   DecoratedRuntime(
       std::unique_ptr<Runtime> runtime,
       HermesRuntime& hermesRuntime,
@@ -149,42 +104,17 @@ class DecoratedRuntime : public jsi::WithRuntimeDecorator<ReentrancyCheck> {
       const std::string& debuggerName)
       : jsi::WithRuntimeDecorator<ReentrancyCheck>(*runtime, reentrancyCheck_),
         runtime_(std::move(runtime)) {
-#if defined(HERMES_ENABLE_DEBUGGER) && !defined(HERMES_V1_ENABLED)
-    enableDebugger_ = enableDebugger;
-    if (enableDebugger_) {
-      std::shared_ptr<HermesRuntime> rt(runtime_, &hermesRuntime);
-      auto adapter =
-          std::make_unique<HermesExecutorRuntimeAdapter>(rt, jsQueue);
-      debugToken_ = facebook::hermes::inspector_modern::chrome::enableDebugging(
-          std::move(adapter), debuggerName);
-    }
-#else
+    (void)hermesRuntime;
     (void)jsQueue;
-#endif // HERMES_ENABLE_DEBUGGER
+    (void)enableDebugger;
+    (void)debuggerName;
   }
 
-  ~DecoratedRuntime() {
-#if defined(HERMES_ENABLE_DEBUGGER) && !defined(HERMES_V1_ENABLED)
-    if (enableDebugger_) {
-      facebook::hermes::inspector_modern::chrome::disableDebugging(debugToken_);
-    }
-#endif // HERMES_ENABLE_DEBUGGER
-  }
+  ~DecoratedRuntime() {}
 
  private:
-  // runtime_ is a potentially decorated Runtime.
-  // hermesRuntime is a reference to a HermesRuntime managed by runtime_.
-  //
-  // HermesExecutorRuntimeAdapter requirements are kept, because the
-  // dtor will disable debugging on the HermesRuntime before the
-  // member managing it is destroyed.
-
   std::shared_ptr<Runtime> runtime_;
   ReentrancyCheck reentrancyCheck_;
-#if defined(HERMES_ENABLE_DEBUGGER) && !defined(HERMES_V1_ENABLED)
-  bool enableDebugger_;
-  facebook::hermes::inspector_modern::chrome::DebugSessionToken debugToken_;
-#endif // HERMES_ENABLE_DEBUGGER
 };
 
 } // namespace
@@ -221,10 +151,7 @@ std::unique_ptr<JSExecutor> HermesExecutorFactory::createJSExecutor(
   //
   // DecoratedRuntime is held by JSIExecutor.  When it gets used, it
   // will check that it's on the right thread, do any necessary trace
-  // logging, then call the real HermesRuntime.  When it is destroyed,
-  // it will shut down the debugger before the HermesRuntime is.  In
-  // the normal case where debugging is not compiled in,
-  // all that's left is the thread checking.
+  // logging, then call the real HermesRuntime.
 
   // Add js engine information to Error.prototype so in error reporting we
   // can send this information.

package/ReactCommon/jserrorhandler/ErrorUtils.cpp

@@ -0,0 +1,42 @@
+/*
+ * 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.
+ */
+
+#include "ErrorUtils.h"
+
+namespace facebook::react {
+
+void handleJSError(
+    jsi::Runtime& runtime,
+    const jsi::JSError& error,
+    bool isFatal) {
+  auto errorUtils = runtime.global().getProperty(runtime, "ErrorUtils");
+  if (errorUtils.isUndefined() || !errorUtils.isObject() ||
+      !errorUtils.getObject(runtime).hasProperty(runtime, "reportFatalError") ||
+      !errorUtils.getObject(runtime).hasProperty(runtime, "reportError")) {
+    // ErrorUtils was not set up. This probably means the bundle didn't
+    // load properly.
+    throw jsi::JSError(
+        runtime,
+        "ErrorUtils is not set up properly. Something probably went wrong trying to load the JS bundle. Trying to report error " +
+            error.getMessage(),
+        error.getStack());
+  }
+
+  // TODO(janzer): Rewrite this function to return the processed error
+  // instead of just reporting it through the native module
+  if (isFatal) {
+    auto func = errorUtils.asObject(runtime).getPropertyAsFunction(
+        runtime, "reportFatalError");
+    func.call(runtime, error.value());
+  } else {
+    auto func = errorUtils.asObject(runtime).getPropertyAsFunction(
+        runtime, "reportError");
+    func.call(runtime, error.value());
+  }
+}
+
+} // namespace facebook::react

package/{React/CxxLogUtils/RCTDefaultCxxLogFunction.h → ReactCommon/jserrorhandler/ErrorUtils.h}

@@ -7,10 +7,10 @@
 
 #pragma once
 
-#import <logger/react_native_log.h>
+#include <jsi/jsi.h>
 
 namespace facebook::react {
 
-void RCTDefaultCxxLogFunction(ReactNativeLogLevel level, const char *message);
+void handleJSError(jsi::Runtime &runtime, const jsi::JSError &error, bool isFatal);
 
 } // namespace facebook::react

package/ReactCommon/jserrorhandler/JsErrorHandler.cpp

@@ -6,12 +6,12 @@
  */
 
 #include "JsErrorHandler.h"
-#include <cxxreact/ErrorUtils.h>
 #include <glog/logging.h>
 #include <react/bridging/Bridging.h>
 #include <react/featureflags/ReactNativeFeatureFlags.h>
 #include <ostream>
 #include <string>
+#include "ErrorUtils.h"
 #include "StackTraceParser.h"
 
 using namespace facebook;

package/ReactCommon/jserrorhandler/React-jserrorhandler.podspec

@@ -28,7 +28,7 @@ Pod::Spec.new do |s|
   s.platforms              = min_supported_versions
   s.source                 = source
   s.header_dir             = "jserrorhandler"
-  s.source_files           = podspec_sources(["JsErrorHandler.{cpp,h}", "StackTraceParser.{cpp,h}"], ["JsErrorHandler.h", "StackTraceParser.h"])
+  s.source_files           = podspec_sources(["ErrorUtils.{cpp,h}", "JsErrorHandler.{cpp,h}", "StackTraceParser.{cpp,h}"], ["ErrorUtils.h", "JsErrorHandler.h", "StackTraceParser.h"])
   s.pod_target_xcconfig = {
     "USE_HEADERMAP" => "YES",
     "CLANG_CXX_LANGUAGE_STANDARD" => rct_cxx_language_standard()
@@ -37,8 +37,7 @@ Pod::Spec.new do |s|
   resolve_use_frameworks(s, header_mappings_dir: '../', module_name: "React_jserrorhandler")
 
   s.dependency "React-jsi"
-  s.dependency "React-cxxreact"
-  s.dependency "ReactCommon/turbomodule/bridging"
+  s.dependency "React-bridging"
   add_dependency(s, "React-featureflags")
   add_dependency(s, "React-debug")
 

package/ReactCommon/jsi/jsi/hermes-interfaces.h

@@ -26,6 +26,59 @@ namespace debugger {
 class Debugger;
 }
 
+/// IEventLoopControl is defined by the integrator to allow the Runtime to
+/// schedule some task to be run when convenient, and to keep track of "Task
+/// sources". After it is set to a Runtime, the integrator must ensure that the
+/// `IEventLoopControl` instance outlives the Runtime. The IEventLoopControl
+/// methods may be called by the Runtime from any thread, so they must be
+/// thread-safe and cannot perform any VM operations.
+struct IEventLoopControl {
+  /// `scheduleTask` is a function used by the caller (the Runtime) to schedule
+  /// some \p task. The scheduled task may perform VM operations. Thus, the
+  /// integrator must only run the tasks when it had exclusive access to the
+  /// Runtime.
+  virtual void scheduleTask(const std::function<void()>& task) = 0;
+  /// Used by the caller (the Runtime) to register a new source that can
+  /// schedule new work via `scheduleTask`. This method return an uint64
+  /// identifying the source registered. As an example, a WebWorker instance may
+  /// schedule a message-processing task via `scheduleTask`, and thus is
+  /// considered as a "task queue source". The Runtime may register each Worker
+  /// using this method. This is useful for the integrator to keep track of
+  /// active "sources".
+  virtual uint64_t registerTaskQueueSource() = 0;
+  /// Used by the caller to unregister a source when it is not allowed to invoke
+  /// `scheduleTasks` anymore. The source is identified by \p sourceId, which is
+  /// provided when the source was originally register in
+  /// `registerTaskQueueSource`. As an example, after WebWorker instance is
+  /// terminated, it will not schedule more tasks. The Runtime may unregister
+  /// the Worker instance, and the integrator may exit the event-loop if there
+  /// are no more active sources.
+  virtual void unregisterTaskQueueSource(uint64_t sourceId) = 0;
+
+ protected:
+  ~IEventLoopControl() = default;
+};
+
+/// Interface for setting the IEventLoopControl in the Runtime.
+struct JSI_EXPORT ISetEventLoopControl : public jsi::ICast {
+ public:
+  static constexpr jsi::UUID uuid{
+      0x7b6902e6,
+      0xfd38,
+      0x11f0,
+      0x8de9,
+      0x0242ac120002};
+
+  /// Configures the eventloop control mechanism using \p eventLoopControl.
+  virtual void setEventLoopControl(IEventLoopControl* eventLoopControl) = 0;
+  /// Retrieves the IEventLoopControl if it was set previously. Otherwise,
+  /// return nullptr.
+  virtual IEventLoopControl* getEventLoopControl() = 0;
+
+ protected:
+  ~ISetEventLoopControl() = default;
+};
+
 /// Interface for Hermes-specific runtime methods.The actual implementations of
 /// the pure virtual methods are provided by Hermes API.
 class JSI_EXPORT IHermes : public jsi::ICast {

package/ReactCommon/jsiexecutor/React-jsiexecutor.podspec

@@ -26,7 +26,8 @@ Pod::Spec.new do |s|
   s.platforms              = min_supported_versions
   s.source                 = source
   s.source_files           = podspec_sources("jsireact/*.{cpp,h}", "jsireact/*.h")
-  s.pod_target_xcconfig    = { "CLANG_CXX_LANGUAGE_STANDARD" => rct_cxx_language_standard() }
+  s.pod_target_xcconfig    = { "CLANG_CXX_LANGUAGE_STANDARD" => rct_cxx_language_standard(),
+                               "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/..\"" }
   s.header_dir             = "jsireact"
 
   s.dependency "React-cxxreact"

package/ReactCommon/jsiexecutor/jsireact/JSIExecutor.cpp

@@ -7,13 +7,13 @@
 
 #include "jsireact/JSIExecutor.h"
 
-#include <cxxreact/ErrorUtils.h>
 #include <cxxreact/JSBigString.h>
 #include <cxxreact/ModuleRegistry.h>
 #include <cxxreact/ReactMarker.h>
 #include <cxxreact/TraceSection.h>
 #include <folly/json.h>
 #include <glog/logging.h>
+#include <jserrorhandler/ErrorUtils.h>
 #include <jsi/JSIDynamic.h>
 #include <jsi/instrumentation.h>
 #include <reactperflogger/BridgeNativeModulePerfLogger.h>
@@ -144,25 +144,14 @@ void JSIExecutor::initializeRuntime() {
   if (runtimeInstaller_) {
     runtimeInstaller_(*runtime_);
   }
-  bool hasLogger = false;
-  {
-    std::shared_lock lock(ReactMarker::logTaggedMarkerImplMutex);
-    hasLogger = ReactMarker::logTaggedMarkerImpl != nullptr;
-  }
-  if (hasLogger) {
-    ReactMarker::logMarker(ReactMarker::CREATE_REACT_CONTEXT_STOP);
-  }
+  ReactMarker::logMarker(ReactMarker::CREATE_REACT_CONTEXT_STOP);
 }
 
 void JSIExecutor::loadBundle(
     std::unique_ptr<const JSBigString> script,
     std::string sourceURL) {
   TraceSection s("JSIExecutor::loadBundle");
-  bool hasLogger = false;
-  {
-    std::shared_lock lock(ReactMarker::logTaggedMarkerImplMutex);
-    hasLogger = ReactMarker::logTaggedMarkerImpl != nullptr;
-  }
+  bool hasLogger(ReactMarker::logTaggedMarkerImpl);
   std::string scriptName = simpleBasename(sourceURL);
   if (hasLogger) {
     ReactMarker::logTaggedMarker(

package/ReactCommon/jsiexecutor/jsireact/JSINativeModules.cpp

@@ -70,15 +70,8 @@ void JSINativeModules::reset() {
 std::optional<Object> JSINativeModules::createModule(
     Runtime& rt,
     const std::string& name) {
-  bool hasLogger = false;
-  {
-    std::shared_lock lock(ReactMarker::logTaggedMarkerImplMutex);
-    hasLogger = ReactMarker::logTaggedMarkerImpl != nullptr;
-  }
-  if (hasLogger) {
-    ReactMarker::logTaggedMarker(
-        ReactMarker::NATIVE_MODULE_SETUP_START, name.c_str());
-  }
+  ReactMarker::logTaggedMarker(
+      ReactMarker::NATIVE_MODULE_SETUP_START, name.c_str());
 
   auto result = m_moduleRegistry->getConfig(name);
   if (!result.has_value()) {
@@ -101,10 +94,8 @@ std::optional<Object> JSINativeModules::createModule(
   std::optional<Object> module(
       moduleInfo.asObject(rt).getPropertyAsObject(rt, "module"));
 
-  if (hasLogger) {
-    ReactMarker::logTaggedMarker(
-        ReactMarker::NATIVE_MODULE_SETUP_STOP, name.c_str());
-  }
+  ReactMarker::logTaggedMarker(
+      ReactMarker::NATIVE_MODULE_SETUP_STOP, name.c_str());
 
   return module;
 }

package/ReactCommon/jsinspector-modern/HostAgent.cpp

@@ -21,8 +21,10 @@
 #include <folly/json.h>
 #include <jsinspector-modern/cdp/CdpJson.h>
 
+#include <algorithm>
 #include <chrono>
 #include <functional>
+#include <string>
 #include <string_view>
 
 using namespace std::chrono;
@@ -236,6 +238,53 @@ class HostAgent::Impl final {
         };
       }
     }
+    if (req.method == "Page.addScriptToEvaluateOnNewDocument") {
+      // @cdp Page.addScriptToEvaluateOnNewDocument registers a script that
+      // will be evaluated in every new JS runtime created for this Host
+      // (e.g. after a reload), BEFORE the app's main bundle runs. We store
+      // it as session state and let each new RuntimeAgent replay it onto its
+      // runtime, mirroring the handling of @cdp Runtime.addBinding. Per CDP
+      // semantics the script does NOT run in the runtime that is current
+      // when it is registered; the client must reload to apply it.
+      std::string source =
+          req.params.isObject() && (req.params.count("source") != 0u)
+          ? req.params.at("source").asString()
+          : std::string();
+      std::string identifier =
+          std::to_string(sessionState_.nextScriptToEvaluateOnNewDocumentId++);
+      sessionState_.scriptsToEvaluateOnNewDocument.push_back(
+          {.identifier = identifier, .source = std::move(source)});
+
+      frontendChannel_(
+          cdp::jsonResult(
+              req.id, folly::dynamic::object("identifier", identifier)));
+
+      return {
+          .isFinishedHandlingRequest = true,
+          .shouldSendOKResponse = false,
+      };
+    }
+    if (req.method == "Page.removeScriptToEvaluateOnNewDocument") {
+      std::string identifier =
+          req.params.isObject() && (req.params.count("identifier") != 0u)
+          ? req.params.at("identifier").asString()
+          : std::string();
+      auto& scripts = sessionState_.scriptsToEvaluateOnNewDocument;
+      scripts.erase(
+          std::remove_if(
+              scripts.begin(),
+              scripts.end(),
+              [&identifier](
+                  const SessionState::ScriptToEvaluateOnNewDocument& script) {
+                return script.identifier == identifier;
+              }),
+          scripts.end());
+
+      return {
+          .isFinishedHandlingRequest = true,
+          .shouldSendOKResponse = true,
+      };
+    }
     if (req.method == "Overlay.setPausedInDebuggerMessage") {
       auto message =
           req.params.isObject() && (req.params.count("message") != 0u)
@@ -397,6 +446,11 @@ class HostAgent::Impl final {
       return;
     }
 
+    if (requestState.isFinishedHandlingRequest) {
+      // The handler already sent its own response via frontendChannel_.
+      return;
+    }
+
     throw NotImplementedException(req.method);
   }
 

package/ReactCommon/jsinspector-modern/HostTarget.h

@@ -252,13 +252,6 @@ class HostTargetController final {
 
   bool hasInstance() const;
 
-  /**
-   * [Experimental] Install a runtime binding subscribing to new Performance
-   * Issues, which we broadcast to the V2 Perf Monitor overlay via
-   * \ref HostTargetDelegate::unstable_onPerfIssueAdded.
-   */
-  void installPerfIssuesBinding();
-
   /**
    * Increments the target's pause overlay counter. The counter represents the
    * exact number of Agents that have (concurrently) requested the pause

package/ReactCommon/jsinspector-modern/HostTargetTraceRecording.cpp

@@ -64,13 +64,16 @@ tracing::HostTracingProfile HostTargetTraceRecording::stop() {
   auto startTime = *startTime_;
   startTime_.reset();
 
-  return tracing::HostTracingProfile{
-      .processId = oscompat::getCurrentProcessId(),
-      .startTime = startTime,
-      .frameTimings = frameTimings_.pruneExpiredAndExtract(),
-      .instanceTracingProfiles = std::move(state.instanceTracingProfiles),
-      .runtimeSamplingProfiles = std::move(state.runtimeSamplingProfiles),
-  };
+  // Member-wise assignment instead of designated initializers:
+  // HostTracingProfile declares its special members (move-only) and is no
+  // longer an aggregate.
+  tracing::HostTracingProfile profile;
+  profile.processId = oscompat::getCurrentProcessId();
+  profile.startTime = startTime;
+  profile.frameTimings = frameTimings_.pruneExpiredAndExtract();
+  profile.instanceTracingProfiles = std::move(state.instanceTracingProfiles);
+  profile.runtimeSamplingProfiles = std::move(state.runtimeSamplingProfiles);
+  return profile;
 }
 
 void HostTargetTraceRecording::recordFrameTimings(

package/ReactCommon/jsinspector-modern/InspectorPackagerConnection.cpp

@@ -341,9 +341,12 @@ void InspectorPackagerConnection::Impl::connect() {
     webSocket_ = delegate_->connectWebSocket(url_, weak_from_this());
   } catch (const std::exception& e) {
     LOG(ERROR) << "Failed to create WebSocket connection: " << e.what();
-    reconnect();
+    webSocket_.reset();
   } catch (...) {
     LOG(ERROR) << "Failed to create WebSocket connection: unknown error";
+    webSocket_.reset();
+  }
+  if (!webSocket_ && !closed_) {
     reconnect();
   }
 }

package/ReactCommon/jsinspector-modern/RuntimeAgent.cpp

@@ -33,6 +33,13 @@ RuntimeAgent::RuntimeAgent(
     }
   }
 
+  // Replay any scripts registered via @cdp
+  // Page.addScriptToEvaluateOnNewDocument onto this newly created runtime, in
+  // registration order, so they evaluate before the app's main bundle.
+  for (const auto& script : sessionState_.scriptsToEvaluateOnNewDocument) {
+    targetController_.installScriptToEvaluateOnNewDocument(script.source);
+  }
+
   if (sessionState_.isRuntimeDomainEnabled) {
     targetController_.notifyDomainStateChanged(
         RuntimeTargetController::Domain::Runtime, true, *this);

package/ReactCommon/jsinspector-modern/RuntimeTarget.cpp

@@ -130,6 +130,21 @@ void RuntimeTarget::installBindingHandler(const std::string& bindingName) {
   });
 }
 
+void RuntimeTarget::installScriptToEvaluateOnNewDocument(
+    const std::string& source) {
+  jsExecutor_([source](jsi::Runtime& runtime) {
+    try {
+      runtime.evaluateJavaScript(
+          std::make_shared<jsi::StringBuffer>(source),
+          "<addScriptToEvaluateOnNewDocument>");
+    } catch (jsi::JSIException&) {
+      // Swallow exceptions thrown while evaluating the injected script so a
+      // faulty script cannot break the app. This mirrors how
+      // installBindingHandler isolates binding-setup failures.
+    }
+  });
+}
+
 void RuntimeTarget::installFastRefreshHandler() {
   jsExecutor_([selfExecutor = executorFromThis()](jsi::Runtime& runtime) {
     auto globalObj = runtime.global();
@@ -313,6 +328,11 @@ void RuntimeTargetController::installBindingHandler(
   target_.installBindingHandler(bindingName);
 }
 
+void RuntimeTargetController::installScriptToEvaluateOnNewDocument(
+    const std::string& source) {
+  target_.installScriptToEvaluateOnNewDocument(source);
+}
+
 void RuntimeTargetController::enableSamplingProfiler() {
   target_.enableSamplingProfiler();
 }

package/ReactCommon/jsinspector-modern/RuntimeTarget.h

@@ -129,6 +129,14 @@ class RuntimeTargetController {
    */
   void installBindingHandler(const std::string &bindingName);
 
+  /**
+   * Evaluates the given JavaScript source on the runtime's thread before any
+   * user code runs. Used to replay @cdp
+   * Page.addScriptToEvaluateOnNewDocument scripts onto a freshly created
+   * runtime.
+   */
+  void installScriptToEvaluateOnNewDocument(const std::string &source);
+
   /**
    * Notifies the target that an agent has received an enable or disable
    * message for the given domain.
@@ -289,6 +297,14 @@ class JSINSPECTOR_EXPORT RuntimeTarget : public EnableExecutorFromThis<RuntimeTa
    */
   void installBindingHandler(const std::string &bindingName);
 
+  /**
+   * Evaluates the given JavaScript source on the runtime's thread before any
+   * user code runs. Used to replay @cdp
+   * Page.addScriptToEvaluateOnNewDocument scripts onto a freshly created
+   * runtime.
+   */
+  void installScriptToEvaluateOnNewDocument(const std::string &source);
+
   /**
    * Installs any global values we want to expose to framework/user JavaScript
    * code.

package/ReactCommon/jsinspector-modern/SessionState.h

@@ -14,6 +14,7 @@
 #include <string_view>
 #include <unordered_map>
 #include <unordered_set>
+#include <vector>
 
 namespace facebook::react::jsinspector_modern {
 
@@ -43,6 +44,36 @@ struct SessionState {
    */
   std::unordered_map<std::string, ExecutionContextSelectorSet> subscribedBindings;
 
+  /**
+   * A single script registered during this session using @cdp
+   * Page.addScriptToEvaluateOnNewDocument.
+   */
+  struct ScriptToEvaluateOnNewDocument {
+    /** Opaque identifier returned to the frontend, used by @cdp
+     * Page.removeScriptToEvaluateOnNewDocument. */
+    std::string identifier;
+    /** The JavaScript source to evaluate. */
+    std::string source;
+  };
+
+  /**
+   * Scripts registered during this session using @cdp
+   * Page.addScriptToEvaluateOnNewDocument, in registration order.
+   *
+   * Like subscribedBindings, these are treated as session state: each new
+   * RuntimeAgent replays them onto its runtime so they evaluate before any
+   * user code (i.e. before the app's main bundle). Per CDP semantics they do
+   * NOT run in the runtime that is current when they are registered - the
+   * client must trigger a reload (@cdp Page.reload) for them to take effect.
+   */
+  std::vector<ScriptToEvaluateOnNewDocument> scriptsToEvaluateOnNewDocument;
+
+  /**
+   * Monotonic counter for generating the identifiers returned from @cdp
+   * Page.addScriptToEvaluateOnNewDocument.
+   */
+  unsigned int nextScriptToEvaluateOnNewDocumentId{1};
+
   /**
    * Messages logged through the HostAgent::sendConsoleMessage and
    * InstanceAgent::sendConsoleMessage utilities that have not yet been sent to