External inspection support (facebook#55408)

Summary:
Pull Request resolved: facebook#55408

Changelog: [Internal]

Reviewed By: hoxyq

Differential Revision: D91919421

fbshipit-source-id: 7c7bb0ccefa758745600202bcaf216c019eae615

Author: sbuggay

packages/react-native/Libraries/ReactNative/AppContainer-dev.js

@@ -8,12 +8,14 @@
  * @format
  */
 
+import type {TouchedViewDataAtPoint} from '../Renderer/shims/ReactNativeTypes';
 import type {
   ReactDevToolsAgent,
   ReactDevToolsGlobalHook,
 } from '../Types/ReactDevToolsTypes';
 import type {Props} from './AppContainer';
 
+import useExternalInspection from '../../src/private/devsupport/devmenu/elementinspector/useExternalInspection';
 import ReactNativeStyleAttributes from '../Components/View/ReactNativeStyleAttributes';
 import View from '../Components/View/View';
 import DebuggingOverlay from '../Debugging/DebuggingOverlay';
@@ -40,16 +42,25 @@ if (reactDevToolsHook) {
   );
 }
 
+type ExternalInspection = {
+  externalInspectingEnabled: boolean,
+  +reportToExternalInspection: (viewData: TouchedViewDataAtPoint) => void,
+};
+
 type InspectorDeferredProps = {
   inspectedViewRef: InspectedViewRef,
   onInspectedViewRerenderRequest: () => void,
   reactDevToolsAgent?: ReactDevToolsAgent,
+  devMenuInspectorOpen: boolean,
+  externalInspection: ExternalInspection,
 };
 
 const InspectorDeferred = ({
   inspectedViewRef,
   onInspectedViewRerenderRequest,
   reactDevToolsAgent,
+  devMenuInspectorOpen,
+  externalInspection,
 }: InspectorDeferredProps) => {
   // D39382967 adds a require cycle: InitializeCore -> AppContainer -> Inspector -> InspectorPanel -> ScrollView -> InitializeCore
   // We can't remove it yet, fallback to dynamic require for now. This is the only reason why this logic is in a separate function.
@@ -61,6 +72,8 @@ const InspectorDeferred = ({
       inspectedViewRef={inspectedViewRef}
       onRequestRerenderApp={onInspectedViewRerenderRequest}
       reactDevToolsAgent={reactDevToolsAgent}
+      devMenuInspectorOpen={devMenuInspectorOpen}
+      externalInspection={externalInspection}
     />
   );
 };
@@ -108,6 +121,7 @@ const AppContainer = ({
   const [shouldRenderInspector, setShouldRenderInspector] = useState(false);
   const [reactDevToolsAgent, setReactDevToolsAgent] =
     useState<ReactDevToolsAgent | void>(reactDevToolsHook?.reactDevtoolsAgent);
+  const externalInspection = useExternalInspection();
 
   useEffect(() => {
     let inspectorSubscription = null;
@@ -179,11 +193,14 @@ const AppContainer = ({
           />
         )}
 
-        {shouldRenderInspector && (
+        {(shouldRenderInspector ||
+          externalInspection.externalInspectingEnabled) && (
           <InspectorDeferred
             inspectedViewRef={innerViewRef}
             onInspectedViewRerenderRequest={onInspectedViewRerenderRequest}
             reactDevToolsAgent={reactDevToolsAgent}
+            devMenuInspectorOpen={shouldRenderInspector}
+            externalInspection={externalInspection}
           />
         )}
 

packages/react-native/scripts/featureflags/ReactNativeFeatureFlags.config.js

@@ -936,6 +936,17 @@ const definitions: FeatureFlagDefinitions = {
       },
       ossReleaseStage: 'none',
     },
+    externalElementInspectionEnabled: {
+      defaultValue: false,
+      metadata: {
+        dateAdded: '2026-02-04',
+        description:
+          'Enable the external inspection API for DevTools to communicate with the Inspector overlay.',
+        expectedReleaseValue: true,
+        purpose: 'experimentation',
+      },
+      ossReleaseStage: 'none',
+    },
     fixVirtualizeListCollapseWindowSize: {
       defaultValue: false,
       metadata: {

packages/react-native/src/private/devsupport/devmenu/elementinspector/Inspector.js

@@ -47,18 +47,29 @@ export type InspectedElement = Readonly<{
 }>;
 export type ElementsHierarchy = InspectorData['hierarchy'];
 
+type ExternalInspection = {
+  externalInspectingEnabled: boolean,
+  +reportToExternalInspection: (viewData: TouchedViewDataAtPoint) => void,
+};
+
 type Props = {
   inspectedViewRef: InspectedViewRef,
   onRequestRerenderApp: () => void,
   reactDevToolsAgent?: ReactDevToolsAgent,
+  devMenuInspectorOpen: boolean,
+  externalInspection: ExternalInspection,
 };
 
 function Inspector({
   inspectedViewRef,
   onRequestRerenderApp,
   reactDevToolsAgent,
+  devMenuInspectorOpen,
+  externalInspection,
 }: Props): React.Node {
-  const [inspecting, setInspecting] = useState<boolean>(true);
+  const [inspectingEnabled, setInspectingEnabled] = useState<boolean>(true);
+  const {externalInspectingEnabled, reportToExternalInspection} =
+    externalInspection;
 
   const [panelPosition, setPanelPosition] = useState<PanelPosition>('bottom');
   const [inspectedElement, setInspectedElement] =
@@ -67,6 +78,9 @@ function Inspector({
   const [elementsHierarchy, setElementsHierarchy] =
     useState<?ElementsHierarchy>(null);
 
+  // Derive inspecting state: external inspection forces it on, otherwise use local state
+  const isInspecting = externalInspectingEnabled || inspectingEnabled;
+
   const setSelection = (i: number) => {
     const hierarchyItem = elementsHierarchy?.[i];
     if (hierarchyItem == null) {
@@ -99,6 +113,11 @@ function Inspector({
         closestInstance,
       } = viewData;
 
+      // Report to external inspection if in external inspection mode
+      if (externalInspectingEnabled) {
+        reportToExternalInspection(viewData);
+      }
+
       // Sync the touched view with React DevTools.
       // Note: This is Paper only. To support Fabric,
       // DevTools needs to be updated to not rely on view tags.
@@ -138,7 +157,7 @@ function Inspector({
   };
 
   const handleSetInspecting = (enabled: boolean) => {
-    setInspecting(enabled);
+    setInspectingEnabled(enabled);
     setInspectedElement(null);
   };
 
@@ -154,26 +173,29 @@ function Inspector({
 
   return (
     <View style={styles.container} pointerEvents="box-none">
-      {inspecting && (
+      {isInspecting && (
         <InspectorOverlay
           inspected={inspectedElement}
           onTouchPoint={onTouchPoint}
+          externalInspectionActive={externalInspectingEnabled}
         />
       )}
 
-      <SafeAreaView style={[styles.panelContainer, panelContainerStyle]}>
-        <InspectorPanel
-          devtoolsIsOpen={!!reactDevToolsAgent}
-          inspecting={inspecting}
-          setInspecting={handleSetInspecting}
-          inspected={inspectedElement}
-          hierarchy={elementsHierarchy}
-          selection={selectionIndex}
-          setSelection={setSelection}
-          touchTargeting={PressabilityDebug.isEnabled()}
-          setTouchTargeting={setTouchTargeting}
-        />
-      </SafeAreaView>
+      {!externalInspectingEnabled && (
+        <SafeAreaView style={[styles.panelContainer, panelContainerStyle]}>
+          <InspectorPanel
+            devtoolsIsOpen={!!reactDevToolsAgent}
+            inspecting={inspectingEnabled}
+            setInspecting={handleSetInspecting}
+            inspected={inspectedElement}
+            hierarchy={elementsHierarchy}
+            selection={selectionIndex}
+            setSelection={setSelection}
+            touchTargeting={PressabilityDebug.isEnabled()}
+            setTouchTargeting={setTouchTargeting}
+          />
+        </SafeAreaView>
+      )}
     </View>
   );
 }

packages/react-native/src/private/devsupport/devmenu/elementinspector/InspectorOverlay.js

@@ -23,9 +23,14 @@ const ElementBox = require('./ElementBox').default;
 type Props = Readonly<{
   inspected?: ?InspectedElement,
   onTouchPoint: (locationX: number, locationY: number) => void,
+  externalInspectionActive?: boolean,
 }>;
 
-function InspectorOverlay({inspected, onTouchPoint}: Props): React.Node {
+function InspectorOverlay({
+  inspected,
+  onTouchPoint,
+  externalInspectionActive,
+}: Props): React.Node {
   const findViewForTouchEvent = (e: GestureResponderEvent) => {
     const {locationX, locationY} = e.nativeEvent.touches[0];
 
@@ -47,7 +52,10 @@ function InspectorOverlay({inspected, onTouchPoint}: Props): React.Node {
       onStartShouldSetResponder={handleStartShouldSetResponder}
       onResponderMove={findViewForTouchEvent}
       nativeID="inspectorOverlay" /* TODO: T68258846. */
-      style={styles.inspector}>
+      style={[
+        styles.inspector,
+        externalInspectionActive === true && styles.externalInspectionIndicator,
+      ]}>
       {content}
     </View>
   );
@@ -62,6 +70,10 @@ const styles = StyleSheet.create({
     right: 0,
     bottom: 0,
   },
+  externalInspectionIndicator: {
+    borderWidth: 4,
+    borderColor: 'rgba(255, 0, 0, 0.8)',
+  },
 });
 
 export default InspectorOverlay;

packages/react-native/src/private/devsupport/devmenu/elementinspector/useExternalInspection.js

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+import type {TouchedViewDataAtPoint} from '../../../../../Libraries/Renderer/shims/ReactNativeTypes';
+
+import * as ReactNativeFeatureFlags from '../../../../../src/private/featureflags/ReactNativeFeatureFlags';
+import {useCallback, useEffect, useState} from 'react';
+
+type ExternalInspectionAPI = {
+  enable: () => void,
+  disable: () => void,
+};
+
+declare var __EXTERNAL_INSPECTION__: ?ExternalInspectionAPI;
+declare var __EXTERNAL_INSPECTION_SELECT__: ?(payload: string) => void;
+
+type UseExternalInspectionResult = {
+  externalInspectingEnabled: boolean,
+  reportToExternalInspection: (viewData: TouchedViewDataAtPoint) => void,
+};
+
+/**
+ * Initializes the __EXTERNAL_INSPECTION__ API on the device.
+ */
+function ensureExternalInspectionAPI(
+  onEnable: () => void,
+  onDisable: () => void,
+): ExternalInspectionAPI {
+  if (
+    typeof __EXTERNAL_INSPECTION__ === 'undefined' ||
+    __EXTERNAL_INSPECTION__ == null
+  ) {
+    const api: ExternalInspectionAPI = {
+      enable: onEnable,
+      disable: onDisable,
+    };
+    // $FlowFixMe[prop-missing] Initializing global API for DevTools communication
+    (global: $FlowFixMe).__EXTERNAL_INSPECTION__ = api;
+    return api;
+  }
+  __EXTERNAL_INSPECTION__.enable = onEnable;
+  __EXTERNAL_INSPECTION__.disable = onDisable;
+  return __EXTERNAL_INSPECTION__;
+}
+
+export default function useExternalInspection(): UseExternalInspectionResult {
+  const [externalInspectingEnabled, setExternalInspectingEnabled] =
+    useState<boolean>(false);
+
+  useEffect(() => {
+    if (!ReactNativeFeatureFlags.externalElementInspectionEnabled()) {
+      return;
+    }
+
+    const handleEnable = () => {
+      setExternalInspectingEnabled(true);
+    };
+
+    const handleDisable = () => {
+      setExternalInspectingEnabled(false);
+    };
+
+    ensureExternalInspectionAPI(handleEnable, handleDisable);
+  }, []);
+
+  const reportToExternalInspection = useCallback(
+    (viewData: TouchedViewDataAtPoint) => {
+      if (
+        typeof __EXTERNAL_INSPECTION_SELECT__ === 'undefined' ||
+        __EXTERNAL_INSPECTION_SELECT__ === null ||
+        !externalInspectingEnabled
+      ) {
+        return;
+      }
+
+      __EXTERNAL_INSPECTION_SELECT__(
+        JSON.stringify({
+          frame: viewData.frame,
+          hierarchy: viewData.hierarchy.map(item => ({
+            name: item.name,
+          })),
+          touchedViewTag: viewData.touchedViewTag,
+        }),
+      );
+    },
+    [externalInspectingEnabled],
+  );
+
+  return {
+    externalInspectingEnabled,
+    reportToExternalInspection,
+  };
+}

packages/react-native/src/private/featureflags/ReactNativeFeatureFlags.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<8b51e19257e928d50c473288cd1a01df>>
+ * @generated SignedSource<<c3eeb5a098c4f8f0738ee377e81679cb>>
  * @flow strict
  * @noformat
  */
@@ -33,6 +33,7 @@ export type ReactNativeFeatureFlagsJsOnly = $ReadOnly<{
   animatedShouldUseSingleOp: Getter<boolean>,
   deferFlatListFocusChangeRenderUpdate: Getter<boolean>,
   disableMaintainVisibleContentPosition: Getter<boolean>,
+  externalElementInspectionEnabled: Getter<boolean>,
   fixVirtualizeListCollapseWindowSize: Getter<boolean>,
   isLayoutAnimationEnabled: Getter<boolean>,
   shouldUseAnimatedObjectForTransform: Getter<boolean>,
@@ -151,6 +152,11 @@ export const deferFlatListFocusChangeRenderUpdate: Getter<boolean> = createJavaS
  */
 export const disableMaintainVisibleContentPosition: Getter<boolean> = createJavaScriptFlagGetter('disableMaintainVisibleContentPosition', false);
 
+/**
+ * Enable the external inspection API for DevTools to communicate with the Inspector overlay.
+ */
+export const externalElementInspectionEnabled: Getter<boolean> = createJavaScriptFlagGetter('externalElementInspectionEnabled', false);
+
 /**
  * Fixing an edge case where the current window size is not properly calculated with fast scrolling. Window size collapsed to 1 element even if windowSize more than the current amount of elements
  */