Support light/dark mode toggling via Emulation.setEmulatedMedia

Summary:
Implements the `Emulation.setEmulatedMedia` CDP method in `jsinspector-modern`, scoped to `prefers-color-scheme` emulation. This allows CDP clients to toggle the app color scheme for debugging without changing system settings.

**Implementation notes**

Adds a new `EmulationAgent` CDP domain agent that validates the `features` param, rejects unsupported media features/types, and delegates to `HostTargetDelegate::onSetEmulatedMedia`. Platform delegates:

- **Android**: Calls `AppCompatDelegate.setDefaultNightMode()` on the UI thread via JNI through `ReactHostImpl`.
- **iOS**: Sets `overrideUserInterfaceStyle` on the key `UIWindow`.

Both platforms trigger their existing `Appearance` change event propagation to JS automatically.

Changelog:
[General][Added] - **React Native DevTools**: Add support for light/dark mode emulation via `Emulation.setEmulatedMedia`

Differential Revision: D101624433

Author: huntie

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/runtime/ReactHostImpl.kt

@@ -12,6 +12,7 @@ import android.content.Context
 import android.content.Intent
 import android.nfc.NfcAdapter
 import android.os.Bundle
+import androidx.appcompat.app.AppCompatDelegate
 import androidx.core.graphics.createBitmap
 import com.facebook.common.logging.FLog
 import com.facebook.infer.annotation.Assertions
@@ -448,6 +449,19 @@ public class ReactHostImpl(
     InspectorNetworkHelper.loadNetworkResource(url, listener)
   }
 
+  @DoNotStrip
+  private fun setEmulatedMedia(colorScheme: String) {
+    UiThreadUtil.runOnUiThread {
+      val mode =
+          when (colorScheme) {
+            "dark" -> AppCompatDelegate.MODE_NIGHT_YES
+            "light" -> AppCompatDelegate.MODE_NIGHT_NO
+            else -> AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM
+          }
+      AppCompatDelegate.setDefaultNightMode(mode)
+    }
+  }
+
   @DoNotStrip
   private fun captureScreenshot(format: String, quality: Int): String? {
     val activity = currentActivity ?: return null

packages/react-native/ReactAndroid/src/main/jni/react/runtime/jni/JReactHostInspectorTarget.cpp

@@ -159,6 +159,16 @@ std::optional<std::string> JReactHostInspectorTarget::captureScreenshot(
   return std::nullopt;
 }
 
+bool JReactHostInspectorTarget::onSetEmulatedMedia(
+    const jsinspector_modern::HostTargetDelegate::SetEmulatedMediaRequest&
+        request) {
+  if (auto javaReactHostImplStrong = javaReactHostImpl_->get()) {
+    javaReactHostImplStrong->setEmulatedMedia(request.colorScheme);
+    return true;
+  }
+  return false;
+}
+
 HostTarget* JReactHostInspectorTarget::getInspectorTarget() {
   return inspectorTarget_ ? inspectorTarget_.get() : nullptr;
 }

packages/react-native/ReactAndroid/src/main/jni/react/runtime/jni/JReactHostInspectorTarget.h

@@ -152,6 +152,12 @@ struct JReactHostImpl : public jni::JavaClass<JReactHostImpl> {
         "captureScreenshot");
     return method(self(), jni::make_jstring(format), static_cast<jint>(quality));
   }
+
+  void setEmulatedMedia(const std::string &colorScheme)
+  {
+    static auto method = javaClassStatic()->getMethod<void(jni::local_ref<jni::JString>)>("setEmulatedMedia");
+    method(self(), jni::make_jstring(colorScheme));
+  }
 };
 
 /**
@@ -284,6 +290,7 @@ class JReactHostInspectorTarget : public jni::HybridClass<JReactHostInspectorTar
       jsinspector_modern::ScopedExecutor<jsinspector_modern::NetworkRequestListener> executor) override;
   std::optional<std::string> captureScreenshot(
       const jsinspector_modern::HostTargetDelegate::PageCaptureScreenshotRequest &request) override;
+  bool onSetEmulatedMedia(const jsinspector_modern::HostTargetDelegate::SetEmulatedMediaRequest &request) override;
   jsinspector_modern::HostTargetTracingDelegate *getTracingDelegate() override;
 
  private:

packages/react-native/ReactCommon/jsinspector-modern/EmulationAgent.cpp

@@ -0,0 +1,97 @@
+/*
+ * 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 "EmulationAgent.h"
+
+#include <jsinspector-modern/cdp/CdpJson.h>
+
+namespace facebook::react::jsinspector_modern {
+
+EmulationAgent::EmulationAgent(
+    FrontendChannel frontendChannel,
+    HostTargetController& hostTargetController)
+    : frontendChannel_(std::move(frontendChannel)),
+      hostTargetController_(hostTargetController) {}
+
+bool EmulationAgent::handleRequest(const cdp::PreparsedRequest& req) {
+  if (req.method != "Emulation.setEmulatedMedia") {
+    return false;
+  }
+
+  if (req.params.isObject() && req.params.count("media") != 0u &&
+      !req.params.at("media").empty()) {
+    frontendChannel_(
+        cdp::jsonError(
+            req.id,
+            cdp::ErrorCode::MethodNotFound,
+            "Emulation.setEmulatedMedia: media type emulation is not supported"));
+    return true;
+  }
+
+  if (!req.params.isObject() || req.params.count("features") == 0u ||
+      !req.params.at("features").isArray()) {
+    frontendChannel_(cdp::jsonResult(req.id));
+    return true;
+  }
+
+  const auto& features = req.params.at("features");
+
+  std::string colorSchemeValue;
+  bool hasColorScheme = false;
+
+  for (const auto& feature : features) {
+    if (!feature.isObject() || feature.count("name") == 0u) {
+      continue;
+    }
+
+    const auto& name = feature.at("name").asString();
+
+    if (name != "prefers-color-scheme") {
+      frontendChannel_(
+          cdp::jsonError(
+              req.id,
+              cdp::ErrorCode::MethodNotFound,
+              "Emulation.setEmulatedMedia: unsupported media feature '" + name +
+                  "'"));
+      return true;
+    }
+
+    hasColorScheme = true;
+    colorSchemeValue =
+        feature.count("value") != 0u ? feature.at("value").asString() : "";
+  }
+
+  if (hasColorScheme && !colorSchemeValue.empty() &&
+      colorSchemeValue != "light" && colorSchemeValue != "dark") {
+    frontendChannel_(
+        cdp::jsonError(
+            req.id,
+            cdp::ErrorCode::InvalidParams,
+            "Emulation.setEmulatedMedia: invalid value '" + colorSchemeValue +
+                "' for prefers-color-scheme (expected 'light', 'dark', or '')"));
+    return true;
+  }
+
+  if (hasColorScheme) {
+    bool success = hostTargetController_.getDelegate().onSetEmulatedMedia(
+        {.colorScheme = colorSchemeValue});
+
+    if (!success) {
+      frontendChannel_(
+          cdp::jsonError(
+              req.id,
+              cdp::ErrorCode::InternalError,
+              "Emulation.setEmulatedMedia: failed to apply color scheme override"));
+      return true;
+    }
+  }
+
+  frontendChannel_(cdp::jsonResult(req.id));
+  return true;
+}
+
+} // namespace facebook::react::jsinspector_modern

packages/react-native/ReactCommon/jsinspector-modern/EmulationAgent.h

@@ -0,0 +1,45 @@
+/*
+ * 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
+
+#include "HostTarget.h"
+#include "InspectorInterfaces.h"
+
+#include <jsinspector-modern/cdp/CdpJson.h>
+
+namespace facebook::react::jsinspector_modern {
+
+/**
+ * Provides an agent for handling CDP's Emulation domain.
+ * Currently supports Emulation.setEmulatedMedia (prefers-color-scheme only).
+ */
+class EmulationAgent {
+ public:
+  /**
+   * \param frontendChannel A channel used to send responses to the
+   * frontend.
+   * \param hostTargetController An interface to the HostTarget that this agent
+   * is attached to. The caller is responsible for ensuring that the
+   * HostTargetDelegate and underlying HostTarget both outlive the agent.
+   */
+  EmulationAgent(FrontendChannel frontendChannel, HostTargetController &hostTargetController);
+
+  /**
+   * Handle a CDP request. The response will be sent over the provided
+   * \c FrontendChannel synchronously or asynchronously.
+   * \param req The parsed request.
+   * \returns true if the request was handled.
+   */
+  bool handleRequest(const cdp::PreparsedRequest &req);
+
+ private:
+  FrontendChannel frontendChannel_;
+  HostTargetController &hostTargetController_;
+};
+
+} // namespace facebook::react::jsinspector_modern

packages/react-native/ReactCommon/jsinspector-modern/HostAgent.cpp

@@ -9,6 +9,7 @@
 #include "InstanceAgent.h"
 
 #ifdef REACT_NATIVE_DEBUGGER_ENABLED
+#include "EmulationAgent.h"
 #include "InspectorFlags.h"
 #include "InspectorInterfaces.h"
 #include "NetworkIOAgent.h"
@@ -50,7 +51,8 @@ class HostAgent::Impl final {
         sessionState_(sessionState),
         networkIOAgent_(NetworkIOAgent(frontendChannel, std::move(executor))),
         tracingAgent_(
-            TracingAgent(frontendChannel, sessionState, targetController)) {}
+            TracingAgent(frontendChannel, sessionState, targetController)),
+        emulationAgent_(EmulationAgent(frontendChannel, targetController)) {}
 
   ~Impl() {
     if (isPausedInDebuggerOverlayVisible_) {
@@ -380,6 +382,11 @@ class HostAgent::Impl final {
       return;
     }
 
+    if (!requestState.isFinishedHandlingRequest &&
+        emulationAgent_.handleRequest(req)) {
+      return;
+    }
+
     if (!requestState.isFinishedHandlingRequest && instanceAgent_ &&
         instanceAgent_->handleRequest(req)) {
       return;
@@ -509,6 +516,8 @@ class HostAgent::Impl final {
   NetworkIOAgent networkIOAgent_;
 
   TracingAgent tracingAgent_;
+
+  EmulationAgent emulationAgent_;
 };
 
 #else

packages/react-native/ReactCommon/jsinspector-modern/HostTarget.h

@@ -148,6 +148,19 @@ class HostTargetDelegate : public LoadNetworkResourceDelegate {
     std::optional<int> quality;
   };
 
+  struct SetEmulatedMediaRequest {
+    /**
+     * The color scheme to emulate: "light", "dark", or "" (reset to system
+     * default).
+     */
+    std::string colorScheme;
+
+    inline bool operator==(const SetEmulatedMediaRequest &rhs) const
+    {
+      return colorScheme == rhs.colorScheme;
+    }
+  };
+
   virtual ~HostTargetDelegate() override;
 
   /**
@@ -206,6 +219,18 @@ class HostTargetDelegate : public LoadNetworkResourceDelegate {
     return std::nullopt;
   }
 
+  /**
+   * Called when the debugger requests an emulated media override via
+   * @cdp Emulation.setEmulatedMedia. Currently only supports the
+   * prefers-color-scheme media feature.
+   *
+   * \returns true if the override was applied successfully.
+   */
+  virtual bool onSetEmulatedMedia(const SetEmulatedMediaRequest & /*request*/)
+  {
+    return false;
+  }
+
   /**
    * An optional delegate that will be used by HostTarget to notify about tracing-related events.
    */

packages/react-native/ReactCommon/react/runtime/platform/ios/ReactCommon/RCTHost.mm

@@ -141,6 +141,43 @@ void loadNetworkResource(const RCTInspectorLoadNetworkResourceRequest &params, R
     [networkHelper_ loadNetworkResourceWithParams:params executor:executor];
   }
 
+#if TARGET_OS_IPHONE
+  bool onSetEmulatedMedia(const SetEmulatedMediaRequest &request) override
+  {
+    RCTAssertMainQueue();
+    UIWindow *keyWindow = nil;
+    for (UIScene *scene in RCTSharedApplication().connectedScenes) {
+      if (scene.activationState == UISceneActivationStateForegroundActive &&
+          [scene isKindOfClass:[UIWindowScene class]]) {
+        auto *windowScene = (UIWindowScene *)scene;
+        for (UIWindow *win in windowScene.windows) {
+          if (win.isKeyWindow) {
+            keyWindow = win;
+            break;
+          }
+        }
+      }
+      if (keyWindow != nil) {
+        break;
+      }
+    }
+
+    if (keyWindow == nil) {
+      return false;
+    }
+
+    UIUserInterfaceStyle style = UIUserInterfaceStyleUnspecified;
+    if (request.colorScheme == "dark") {
+      style = UIUserInterfaceStyleDark;
+    } else if (request.colorScheme == "light") {
+      style = UIUserInterfaceStyleLight;
+    }
+
+    keyWindow.overrideUserInterfaceStyle = style;
+    return true;
+  }
+#endif
+
 #if TARGET_OS_IPHONE && defined(REACT_NATIVE_DEBUGGER_ENABLED)
   std::optional<std::string> captureScreenshot(const PageCaptureScreenshotRequest &request) override
   {