Deprecate legacy Android UIManager surface APIs (#59039)

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/bridge/UIManager.kt

@@ -16,14 +16,29 @@ import com.facebook.react.uimanager.events.EventDispatcher
 
 @OptIn(UnstableReactNativeAPI::class)
 public interface UIManager : PerformanceCounter {
-  /** Registers a new root view. @Deprecated call startSurface instead */
+  /**
+   * Registers a new root view.
+   *
+   * @deprecated Use `ReactHost.createSurface(...)` and `ReactSurface.start()` instead.
+   */
   @UiThread
   @ThreadConfined(ThreadConfined.UI)
-  @Deprecated("")
+  @Deprecated(
+      "This legacy surface API will be removed in a future release. " +
+          "Use ReactHost.createSurface(...) and ReactSurface.start() instead."
+  )
   public fun <T : View> addRootView(rootView: T, initialProps: WritableMap?): Int
 
-  /** Registers a new root view with width and height. */
+  /**
+   * Registers a new root view with width and height.
+   *
+   * @deprecated Use `ReactHost.createSurface(...)` and `ReactSurface.start()` instead.
+   */
   @AnyThread
+  @Deprecated(
+      "This legacy surface API will be removed in a future release. " +
+          "Use ReactHost.createSurface(...) and ReactSurface.start() instead."
+  )
   public fun <T : View?> startSurface(
       rootView: T,
       moduleName: String,
@@ -35,8 +50,14 @@ public interface UIManager : PerformanceCounter {
   /**
    * Stop a surface from running in JS and clears up native memory usage. Assumes that the native
    * View hierarchy has already been cleaned up. Fabric-only.
+   *
+   * @deprecated Use `ReactSurface.stop()` instead.
    */
-  @AnyThread public fun stopSurface(surfaceId: Int)
+  @AnyThread
+  @Deprecated(
+      "This legacy surface API will be removed in a future release. Use ReactSurface.stop() instead."
+  )
+  public fun stopSurface(surfaceId: Int)
 
   /**
    * Updates the layout specs of the RootShadowNode based on the Measure specs received by

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/FabricUIManager.java

@@ -262,6 +262,9 @@ public FabricUIManager(
     mReactApplicationContext.registerComponentCallbacks(viewManagerRegistry);
   }
 
+  /**
+   * @deprecated Use {@code ReactHost.createSurface(...)} and {@code ReactSurface.start()} instead.
+   */
   @Override
   @UiThread
   @ThreadConfined(UI)
@@ -271,7 +274,8 @@ public <T extends View> int addRootView(
     ReactSoftExceptionLogger.logSoftException(
         TAG,
         new IllegalViewOperationException(
-            "Do not call addRootView in Fabric; it is unsupported. Call startSurface instead."));
+            "Do not call addRootView in Fabric; it is unsupported. Use ReactHost.createSurface(...)"
+                + " and ReactSurface.start() instead."));
 
     ReactRoot reactRootView = (ReactRoot) rootView;
     final int rootTag = reactRootView.getRootViewTag();
@@ -341,6 +345,10 @@ public <T extends View> int addRootView(
     return mBinding != null ? mBinding.getRelativeAncestorList(rootTag, childTag) : null;
   }
 
+  /**
+   * @deprecated Use {@code ReactHost.createSurface(...)} and {@code ReactSurface.start()} instead.
+   */
+  @Deprecated
   @Override
   @AnyThread
   @ThreadConfined(ANY)
@@ -430,6 +438,10 @@ public void onRequestEventBeat() {
     mEventDispatcher.dispatchAllEvents();
   }
 
+  /**
+   * @deprecated Use {@code ReactSurface.stop()} instead.
+   */
+  @Deprecated
   @AnyThread
   @ThreadConfined(ANY)
   @Override

packages/react-native/ReactAndroid/src/test/java/com/facebook/testutils/fakes/FakeUIManager.kt

@@ -34,6 +34,7 @@ class FakeUIManager : UIManager, UIBlockViewResolver {
     error("Not yet implemented")
   }
 
+  @Deprecated("")
   override fun <T : View?> startSurface(
       rootView: T,
       moduleName: String,
@@ -44,6 +45,7 @@ class FakeUIManager : UIManager, UIBlockViewResolver {
     error("Not yet implemented")
   }
 
+  @Deprecated("")
   override fun stopSurface(surfaceId: Int) {
     error("Not yet implemented")
   }