Add unstable_fastRefreshComplete CDP event (#56273)

Summary:
Pull Request resolved: #56273

Adds a new, experimental `ReactNativeApplication.unstable_fastRefreshComplete` CDP event, emitted to subscribed active CDP sessions when a Fast Refresh update completes.

**Notes**

- As with D97486551, we reuse the `changeId` block in `HMRClient.js`, ensuring duplicate updates for the same change are not reported.

Changelog: [Internal]

Reviewed By: GijsWeterings, hoxyq

Differential Revision: D98493216

fbshipit-source-id: b0b81a210fb84873e9358aa5484038062f110103

Author: huntie

packages/react-native/Libraries/Utilities/HMRClient.js

@@ -26,6 +26,7 @@ let hmrUnavailableReason: string | null = null;
 let hmrOrigin: string | null = null;
 let currentCompileErrorMessage: string | null = null;
 let didConnect: boolean = false;
+let lastMarkerChangeId: ?string = null;
 let pendingLogs: Array<[LogLevel, $ReadOnlyArray<mixed>]> = [];
 
 type LogLevel =
@@ -229,10 +230,15 @@ Error: ${e.message}`;
       }
     });
 
-    client.on('update-done', () => {
+    client.on('update-done', body => {
       pendingUpdatesCount--;
       if (pendingUpdatesCount === 0) {
         DevLoadingView.hide();
+        const changeId = body?.changeId;
+        if (changeId != null && changeId !== lastMarkerChangeId) {
+          lastMarkerChangeId = changeId;
+          emitFastRefreshCompleteEvents();
+        }
       }
     });
 
@@ -378,4 +384,25 @@ function showCompileError() {
   throw error;
 }
 
+function emitFastRefreshCompleteEvents() {
+  // Add marker entry in performance timeline
+  performance.mark('Fast Refresh - Update done', {
+    detail: {
+      devtools: {
+        dataType: 'marker',
+        color: 'primary',
+        tooltipText: 'Fast Refresh \u269b',
+      },
+    },
+  });
+
+  // Notify CDP clients via internal binding
+  if (
+    // $FlowFixMe[prop-missing] - Injected by RuntimeTarget
+    typeof globalThis.__notifyFastRefreshComplete === 'function'
+  ) {
+    globalThis.__notifyFastRefreshComplete();
+  }
+}
+
 export default HMRClient;

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

@@ -8,6 +8,10 @@
 #include "RuntimeAgent.h"
 #include "SessionState.h"
 
+#include <folly/dynamic.h>
+#include <jsinspector-modern/cdp/CdpJson.h>
+
+#include <chrono>
 #include <utility>
 
 namespace facebook::react::jsinspector_modern {
@@ -119,6 +123,21 @@ void RuntimeAgent::notifyBindingCalled(
               "name", bindingName)("payload", payload)));
 }
 
+void RuntimeAgent::notifyFastRefreshComplete() {
+  if (!sessionState_.isReactNativeApplicationDomainEnabled) {
+    return;
+  }
+  folly::dynamic params = folly::dynamic::object(
+      "timestamp",
+      std::chrono::duration_cast<std::chrono::milliseconds>(
+          std::chrono::system_clock::now().time_since_epoch())
+          .count());
+  frontendChannel_(
+      cdp::jsonNotification(
+          "ReactNativeApplication.unstable_fastRefreshComplete",
+          std::move(params)));
+}
+
 RuntimeAgent::ExportedState RuntimeAgent::getExportedState() {
   return {
       .delegateState = delegate_ ? delegate_->getExportedState() : nullptr,

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

@@ -72,6 +72,13 @@ class RuntimeAgent final {
 
   void notifyBindingCalled(const std::string &bindingName, const std::string &payload);
 
+  /**
+   * Called by RuntimeTarget when JS calls __notifyFastRefreshComplete().
+   * Emits a ReactNativeApplication.unstable_fastRefreshComplete CDP
+   * notification if the ReactNativeApplication domain is enabled.
+   */
+  void notifyFastRefreshComplete();
+
   struct ExportedState {
     std::unique_ptr<RuntimeAgentDelegate::ExportedState> delegateState;
   };

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

@@ -60,6 +60,8 @@ void RuntimeTarget::installGlobals() {
   // NOTE: RuntimeTarget::installNetworkReporterAPI is in
   // RuntimeTargetNetwork.cpp
   installNetworkReporterAPI();
+
+  installFastRefreshHandler();
 }
 
 std::shared_ptr<RuntimeAgent> RuntimeTarget::createAgent(
@@ -141,6 +143,37 @@ void RuntimeTarget::installBindingHandler(const std::string& bindingName) {
   });
 }
 
+void RuntimeTarget::installFastRefreshHandler() {
+  jsExecutor_([selfExecutor = executorFromThis()](jsi::Runtime& runtime) {
+    auto globalObj = runtime.global();
+    try {
+      auto name =
+          jsi::PropNameID::forUtf8(runtime, "__notifyFastRefreshComplete");
+      globalObj.setProperty(
+          runtime,
+          name,
+          jsi::Function::createFromHostFunction(
+              runtime,
+              name,
+              0,
+              [selfExecutor](
+                  jsi::Runtime& /*rt*/,
+                  const jsi::Value&,
+                  const jsi::Value*,
+                  size_t) -> jsi::Value {
+                selfExecutor([](auto& self) {
+                  self.agents_.forEach(
+                      [](auto& agent) { agent.notifyFastRefreshComplete(); });
+                });
+
+                return jsi::Value::undefined();
+              }));
+    } catch (jsi::JSError&) {
+      // Swallow JavaScript exceptions that occur while setting up the global.
+    }
+  });
+}
+
 void RuntimeTarget::emitDebuggerSessionCreated() {
   jsExecutor_([selfExecutor = executorFromThis()](jsi::Runtime& runtime) {
     try {

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

@@ -289,6 +289,12 @@ class JSINSPECTOR_EXPORT RuntimeTarget : public EnableExecutorFromThis<RuntimeTa
    */
   void installGlobals();
 
+  /**
+   * Installs __notifyFastRefreshComplete on the runtime's global object.
+   * When called from JS, dispatches to all connected RuntimeAgents.
+   */
+  void installFastRefreshHandler();
+
   /**
    * Install the console API handler.
    */