Add dynamic sampling to frame screenshots (facebook#56048)

Summary:

Update Android frame screenshot processing to skip screenshot capture when encoding is already in progress — now limited to a single background thread — while always emitting frame timing events.

**Motivation**

1. Prevents truncated trace data on slower devices (e.g. missing screenshots for the last 1/3 of the trace), with the tradeoff of some intermediate frame visual snapshot loss.
2. Reduces total recording overhead by freeing up device threads - prevents excessive encoding work from blocking or slowing down the UI and other app threads.

NOTE: ⚠️ This still does not yet solve crashes (OkHttp network chunk size overflow) for heavy frame data at a high FPS on fast devices (coming next).

**Dynamic throttling algorithm**

- Use a single `lastFrameBuffer` to store the most recently captured frame (bitmap + metadata)
- Use a serial background thread (single-thread executor) for all encoding work
- Use an atomic `encodingInProgress` flag to track encoding state
- Always capture screenshots to `lastFrameBuffer` on every frame (even during encoding), replacing any previous waiting frame
- When not encoding: start encoding the captured frame
- When encoding finishes: loop back and check if buffer was refilled, encode that frame if present
- Always emit frame timing events immediately (without screenshot)

This ensures we don't queue up excessive encoding work while maintaining continuous frame timing data and guaranteeing the final settled state of animations is captured (tail-capture), minimizing the performance impact of recording on the device.

NOTE: ⚠️ We do still typically lose a small region of pending frames at the end of a trace, but this is now more reasonable. A further fix (likely unnecessary) is to add lifecycle methods to await frame processing before responding to `Tracing.stop`.

Changelog: [Internal]

Differential Revision: D95987488

Author: huntie

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/devsupport/inspector/FrameTimingsObserver.kt

@@ -17,8 +17,13 @@ import android.view.PixelCopy
 import android.view.Window
 import com.facebook.proguard.annotations.DoNotStripAny
 import java.io.ByteArrayOutputStream
+import java.util.concurrent.Executors
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicReference
+import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.asCoroutineDispatcher
 import kotlinx.coroutines.launch
 
 @DoNotStripAny
@@ -29,16 +34,35 @@ internal class FrameTimingsObserver(
   private val isSupported = Build.VERSION.SDK_INT >= Build.VERSION_CODES.N
   private val mainHandler = Handler(Looper.getMainLooper())
 
+  // Serial dispatcher for encoding work (single background thread)
+  private val encodingDispatcher: CoroutineDispatcher =
+      Executors.newSingleThreadExecutor().asCoroutineDispatcher()
+
+  // Stores the most recently captured frame. When previous frame encoding finishes, ensures we
+  // encode the final settled frame even if intermediate frames were skipped.
+  private val lastFrameBuffer = AtomicReference<FrameData?>(null)
+
   private var frameCounter: Int = 0
+  private val encodingInProgress = AtomicBoolean(false)
   @Volatile private var isTracing: Boolean = false
   @Volatile private var currentWindow: Window? = null
 
+  private data class FrameData(
+      val bitmap: Bitmap,
+      val frameId: Int,
+      val threadId: Int,
+      val beginTimestamp: Long,
+      val endTimestamp: Long,
+  )
+
   fun start() {
     if (!isSupported) {
       return
     }
 
     frameCounter = 0
+    encodingInProgress.set(false)
+    lastFrameBuffer.set(null)
     isTracing = true
 
     // Capture initial screenshot to ensure there's always at least one frame
@@ -58,6 +82,7 @@ internal class FrameTimingsObserver(
 
     currentWindow?.removeOnFrameMetricsAvailableListener(frameMetricsListener)
     mainHandler.removeCallbacksAndMessages(null)
+    lastFrameBuffer.getAndSet(null)?.bitmap?.recycle()
   }
 
   fun setCurrentWindow(window: Window?) {
@@ -88,35 +113,67 @@ internal class FrameTimingsObserver(
     val frameId = frameCounter++
     val threadId = Process.myTid()
 
+    // Always emit frame event without screenshot immediately
+    CoroutineScope(Dispatchers.Default).launch {
+      onFrameTimingSequence(
+          FrameTimingSequence(frameId, threadId, beginTimestamp, endTimestamp, null)
+      )
+    }
+
+    // If screenshots enabled, always capture to lastFrameBuffer (even during encoding).
+    // This ensures we capture the settled/end state of animations.
     if (screenshotsEnabled) {
-      // Initiate PixelCopy immediately on the main thread, while still in the current frame,
-      // then process and emit asynchronously once the copy is complete.
-      captureScreenshot { screenshot ->
-        CoroutineScope(Dispatchers.Default).launch {
+      captureScreenshotToBuffer(frameId, threadId, beginTimestamp, endTimestamp) {
+        // If not currently encoding, start encoding the last captured frame
+        if (encodingInProgress.compareAndSet(false, true)) {
+          encodeBufferedFrames()
+        }
+      }
+    }
+  }
+
+  private fun encodeBufferedFrames() {
+    CoroutineScope(encodingDispatcher).launch {
+      // Keep encoding until lastFrameBuffer is empty.
+      // This loop ensures we encode the "last frame" - the settled state of any animation,
+      // even if intermediate frames were captured while we were encoding.
+      while (true) {
+        val frameData = lastFrameBuffer.getAndSet(null) ?: break
+        try {
+          val screenshot = encodeScreenshotFromBuffer(frameData.bitmap)
           onFrameTimingSequence(
-              FrameTimingSequence(frameId, threadId, beginTimestamp, endTimestamp, screenshot)
+              FrameTimingSequence(
+                  frameData.frameId,
+                  frameData.threadId,
+                  frameData.beginTimestamp,
+                  frameData.endTimestamp,
+                  screenshot,
+              )
           )
+        } finally {
+          frameData.bitmap.recycle()
         }
       }
-    } else {
-      CoroutineScope(Dispatchers.Default).launch {
-        onFrameTimingSequence(
-            FrameTimingSequence(frameId, threadId, beginTimestamp, endTimestamp, null)
-        )
-      }
+      encodingInProgress.set(false)
     }
   }
 
   // Must be called from the main thread so that PixelCopy captures the current frame.
-  private fun captureScreenshot(callback: (ByteArray?) -> Unit) {
+  // Stores the captured bitmap and frame metadata in lastFrameBuffer, replacing any previous
+  // frame. This ensures we always have the most recent frame available for encoding.
+  private fun captureScreenshotToBuffer(
+      frameId: Int,
+      threadId: Int,
+      beginTimestamp: Long,
+      endTimestamp: Long,
+      callback: () -> Unit,
+  ) {
     if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
-      callback(null)
       return
     }
 
     val window = currentWindow
     if (window == null) {
-      callback(null)
       return
     }
 
@@ -130,26 +187,27 @@ internal class FrameTimingsObserver(
         bitmap,
         { copyResult ->
           if (copyResult == PixelCopy.SUCCESS) {
-            CoroutineScope(Dispatchers.Default).launch {
-              callback(encodeScreenshot(window, bitmap, width, height))
-            }
+            // Store frame data in lastFrameBuffer, recycling any previous frame's bitmap
+            val oldFrameData =
+                lastFrameBuffer.getAndSet(
+                    FrameData(bitmap, frameId, threadId, beginTimestamp, endTimestamp)
+                )
+            oldFrameData?.bitmap?.recycle()
+            callback()
           } else {
             bitmap.recycle()
-            callback(null)
           }
         },
         mainHandler,
     )
   }
 
-  private fun encodeScreenshot(
-      window: Window,
-      bitmap: Bitmap,
-      width: Int,
-      height: Int,
-  ): ByteArray? {
+  private fun encodeScreenshotFromBuffer(bitmap: Bitmap): ByteArray? {
     var scaledBitmap: Bitmap? = null
     return try {
+      val window = currentWindow ?: return null
+      val width = bitmap.width
+      val height = bitmap.height
       val density = window.context.resources.displayMetrics.density
       val scaledWidth = (width / density * SCREENSHOT_SCALE_FACTOR).toInt()
       val scaledHeight = (height / density * SCREENSHOT_SCALE_FACTOR).toInt()
@@ -167,7 +225,6 @@ internal class FrameTimingsObserver(
       null
     } finally {
       scaledBitmap?.recycle()
-      bitmap.recycle()
     }
   }