@buoy-gg/bug-links 0.0.0-stage → 7.0.80

package/android/src/main/java/gg/buoy/buglinks/frames/FrameEngine.kt

@@ -0,0 +1,707 @@
+// Bug Links pictures and video on Android (research/bug-links-2026-10/media/SPEC.md).
+//
+// The way to take a frame won a race on a real Pixel (SPEC section 6, a4):
+// PixelCopy of the window straight into a 1x bitmap, off the main thread.
+//
+// Safety, from the 2026-10-26 compatibility review:
+// - Android 7.0 and 7.1 have no window PixelCopy: no frames, with a reason;
+// - a protected window (FLAG_SECURE) gives no frame;
+// - an RN Modal is its own window: it is copied and walked too, or the frame
+//   is dropped;
+// - boxes are read a tick before, right before and right after the copy (H13);
+// - every job carries a run token and a deadline, so a late or lost copy can't
+//   touch a newer run or keep the lane busy.
+package gg.buoy.buglinks.frames
+
+import android.app.Activity
+import android.app.Dialog
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Paint
+import android.graphics.Rect
+import android.graphics.RectF
+import android.content.pm.ApplicationInfo
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.os.Looper
+import android.os.SystemClock
+import android.util.Base64
+import android.view.Choreographer
+import android.view.MotionEvent
+import android.view.PixelCopy
+import android.view.View
+import android.view.Window
+import android.view.WindowManager
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.LifecycleEventListener
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.common.LifecycleState
+import java.io.ByteArrayOutputStream
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.roundToInt
+
+/** C2: video frames this close to a "Bug here" mark are kept first. */
+private const val NEAR_MARK_MS = 3000.0
+
+/** 0 until n, in an order where every start of the list spans the range (ends, middle, quarters…). */
+internal fun spreadOrder(n: Int): List<Int> {
+  val out = ArrayList<Int>(n)
+  if (n <= 0) return out
+  val used = BooleanArray(n)
+  fun add(i: Int) { if (!used[i]) { used[i] = true; out.add(i) } }
+  add(0); add(n - 1)
+  var parts = 2
+  while (out.size < n) {
+    var k = 1
+    while (k < parts) { add(Math.round((n - 1).toDouble() * k / parts).toInt()); k += 2 }
+    if (parts > n * 2) for (i in 0 until n) add(i)
+    parts *= 2
+  }
+  return out
+}
+
+class Frame(val t: Double, val kind: String, val w: Int, val h: Int, val jpeg: ByteArray, val boxes: Int, val moved: Boolean)
+
+class FrameEngine(private val context: ReactApplicationContext) {
+  private val main = Handler(Looper.getMainLooper())
+  private val thread = HandlerThread("buoy-frames").apply { start() }
+  private val bg = Handler(thread.looper)
+
+  // Settings (S1, M1)
+  private var pictures = true
+  private var customer = false
+  private val masks = MaskSettings()
+  private var videoFps = 2.0
+  private var enabled = false
+
+  // Rings (F2, F3, F4). Main thread only.
+  private val taps = ArrayList<Frame>()
+  private val video = ArrayList<Frame>()
+  private var last: Frame? = null
+  private val marks = ArrayList<Double>()
+  private val dropped = HashMap<String, Int>()
+  private var frozen = false
+  private var lastReason: String? = null
+  // F8: the time of the last frame taken when Buoy's button was touched, and
+  // whether the touch going on now started on Buoy (no tap frame for it).
+  private var buttonLastT: Double? = null
+  private var downOnBuoy = false
+
+  // One job at a time. `run` goes up on every stop, so late jobs are ignored.
+  private var run = 0
+  private var busy = false
+  private var slowInRow = 0
+  private var stoppedReason: String? = null
+
+  // Video
+  private var videoOn = false
+  private var videoAlways = false
+  private var videoUntil = 0L
+  private var nextVideoDue = 0L
+  private val videoClock = object : Choreographer.FrameCallback {
+    override fun doFrame(frameTimeNanos: Long) {
+      if (!videoOn) return
+      videoTick()
+      if (videoOn) Choreographer.getInstance().postFrameCallback(this)
+    }
+  }
+
+  // Taps
+  private var wrapped: Window? = null
+  private var watcher: TapCallback? = null
+  private val tapRunnable = Runnable { take("tap", 1, null) }
+
+  companion object {
+    private const val MAX_LONG_SIDE = 1280f
+    private const val MAX_VIDEO_BYTES = 6 * 1024 * 1024
+    private const val COPY_DEADLINE_MS = 1000L
+    private val BOX = Paint().apply { color = Color.rgb(0x1F, 0x1F, 0x1F); style = Paint.Style.FILL } // H3
+  }
+
+  // MARK: settings
+
+  // A new Activity (the system can rebuild it) has a new window: watch it as soon as the app is back.
+  private val lifecycle = object : LifecycleEventListener {
+    override fun onHostResume() { if (enabled) attachWatcher() }
+    override fun onHostPause() {}
+    override fun onHostDestroy() {}
+  }
+  private var listening = false
+
+  fun configure(o: ReadableMap) {
+    if (!listening) { context.addLifecycleEventListener(lifecycle); listening = true }
+    val wasCustomer = customer
+    val old = Triple(masks.text, masks.images, masks.inputs)
+    pictures = !o.hasKey("pictures") || o.getBoolean("pictures")
+    customer = o.hasKey("mode") && o.getString("mode") == "customer"
+    masks.text = !o.hasKey("maskAllText") || o.getBoolean("maskAllText")
+    masks.images = !o.hasKey("maskAllImages") || o.getBoolean("maskAllImages")
+    masks.inputs = !o.hasKey("maskAllInputs") || o.getBoolean("maskAllInputs")
+    // A hiding setting that turned on (or customer mode): frames already taken hid less, so they go.
+    // Here, not only in JS: a JS reload brings fresh settings to frames an older JS took.
+    if ((!old.first && masks.text) || (!old.second && masks.images) || (!old.third && masks.inputs) || (customer && !wasCustomer)) clear()
+    if (o.hasKey("videoFps")) videoFps = o.getDouble("videoFps").coerceIn(0.5, 10.0)
+    enabled = true
+    attachWatcher()
+    val v = if (o.hasKey("video")) o.getString("video") else null
+    if (v == "always" && !customer) startVideo(true) else if (videoAlways) stopVideo()
+  }
+
+  fun status(): WritableMap = Arguments.createMap().apply {
+    putBoolean("available", Build.VERSION.SDK_INT >= Build.VERSION_CODES.O)
+    putBoolean("enabled", enabled)
+    putString("mode", if (customer) "customer" else "internal")
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) putString("stopped", "pictures need Android 8.0 or newer")
+    else stoppedReason?.let { putString("stopped", it) }
+  }
+
+  // MARK: taps
+
+  private fun attachWatcher() {
+    val window = context.currentActivity?.window ?: return
+    // Other SDKs (Sentry) wrap the callback too, so ours may not be on top:
+    // remember the window instead of checking the callback, or every frame
+    // would wrap it again.
+    if (wrapped === window) return
+    detachWatcher()
+    val base = window.callback ?: return
+    val w = TapCallback(base, ::touchDown, ::tapped, ::activityFocus)
+    window.callback = w
+    wrapped = window
+    watcher = w
+    // A Modal may already be open when pictures start.
+    watchModals()
+  }
+
+  // An RN Modal is its own window, so its taps never reach the Activity's.
+  // The Activity loses focus when one opens: watch the Modal's window then.
+  private val modalWatchers = java.util.WeakHashMap<Window, TapCallback>()
+
+  /** When each Modal window was first seen, so stacked Modals draw in the order they opened. */
+  private val modalOrder = java.util.WeakHashMap<Window, Long>()
+  private var modalSeq = 0L
+
+  private fun activityFocus(hasFocus: Boolean) {
+    if (!hasFocus) main.post { watchModals() }
+  }
+
+  private fun watchModals() {
+    val decor = context.currentActivity?.window?.decorView ?: return
+    val hosts = ArrayList<View>()
+    collectModals(decor, hosts)
+    for (host in hosts) {
+      val w = modalDialog(host)?.window ?: continue
+      if (!modalOrder.containsKey(w)) modalOrder[w] = ++modalSeq
+      if (modalWatchers.containsKey(w)) continue
+      val base = w.callback ?: continue
+      // A touch in a Modal is never on Buoy's floating button. A Modal that
+      // loses focus may have opened another above it; a closed one leaves the map.
+      val cb = TapCallback(base, { _, _ -> downOnBuoy = false }, ::tapped, ::activityFocus, { modalWatchers.remove(w) })
+      w.callback = cb
+      modalWatchers[w] = cb
+    }
+  }
+
+  private fun unwatchModals() {
+    for ((w, cb) in modalWatchers) if (w.callback === cb) w.callback = cb.base else cb.live = false
+    modalWatchers.clear()
+  }
+
+  private fun detachWatcher() {
+    unwatchModals()
+    val w = wrapped ?: return
+    val mine = watcher
+    // If another SDK wrapped ours, it can't come out: turn it off instead.
+    if (mine != null && w.callback === mine) w.callback = mine.base else mine?.live = false
+    wrapped = null
+    watcher = null
+  }
+
+  /** A touch on Buoy's floating button: take the last frame now, before the dial draws (F8). */
+  private fun touchDown(x: Float, y: Float) {
+    val decor = context.currentActivity?.window?.decorView ?: return
+    downOnBuoy = onBuoyButton(decor, x, y)
+    if (!downOnBuoy || !enabled || frozen || busy) return
+    take("last", 1) { ok -> if (ok) buttonLastT = last?.t }
+  }
+
+  private fun onBuoyButton(decor: View, x: Float, y: Float): Boolean {
+    val root = findById(decor, FrameWalker.BUOY_ROOT) ?: return false
+    val loc = IntArray(2)
+    val stack = ArrayList<View>().apply { add(root) }
+    while (stack.isNotEmpty()) {
+      val v = stack.removeAt(stack.size - 1)
+      if (v.visibility != View.VISIBLE) continue
+      if (v !== root) {
+        v.getLocationInWindow(loc)
+        if (x >= loc[0] && x < loc[0] + v.width && y >= loc[1] && y < loc[1] + v.height &&
+          v.width * v.height < decor.width * decor.height / 2) return true
+      }
+      if (v is android.view.ViewGroup) for (i in 0 until v.childCount) v.getChildAt(i)?.let { stack.add(it) }
+    }
+    return false
+  }
+
+  private fun findById(root: View, id: String): View? {
+    val stack = ArrayList<View>().apply { add(root) }
+    while (stack.isNotEmpty()) {
+      val v = stack.removeAt(stack.size - 1)
+      if (FrameWalker.nativeId(v) == id) return v
+      if (v is android.view.ViewGroup) for (i in 0 until v.childCount) v.getChildAt(i)?.let { stack.add(it) }
+    }
+    return null
+  }
+
+  private fun tapped() {
+    // A tap on Buoy's own button would show Buoy's toast or dial, not the app.
+    if (downOnBuoy) { downOnBuoy = false; return }
+    if (!enabled || !pictures || customer || frozen || stoppedReason != null) return
+    main.removeCallbacks(tapRunnable)
+    main.postDelayed(tapRunnable, 300) // F2
+  }
+
+  // MARK: video
+
+  fun startVideo(always: Boolean) {
+    if (!enabled || customer) return
+    videoAlways = always
+    if (!always) { video.clear(); marks.clear() }
+    videoUntil = if (always) Long.MAX_VALUE else SystemClock.uptimeMillis() + 60_000 // F3
+    nextVideoDue = SystemClock.uptimeMillis()
+    if (!videoOn) {
+      videoOn = true
+      Choreographer.getInstance().postFrameCallback(videoClock)
+    }
+  }
+
+  fun stopVideo() {
+    videoOn = false
+    videoAlways = false
+    Choreographer.getInstance().removeFrameCallback(videoClock)
+  }
+
+  fun mark() { if (videoOn) marks.add(System.currentTimeMillis().toDouble()) }
+
+  private fun videoTick() {
+    val now = SystemClock.uptimeMillis()
+    if (now > videoUntil) { stopVideo(); return }
+    if (frozen || stoppedReason != null || now < nextVideoDue) return
+    nextVideoDue = now + (1000 / videoFps).toLong() // from now: never a backlog
+    if (!busy) take("video", 1, null)
+  }
+
+  // MARK: the case
+
+  fun captureLast(done: (Boolean, String?) -> Unit) {
+    // Buoy's toast is up by now, so the frame from the button touch is the
+    // better last frame while it is new.
+    val b = buttonLastT
+    if (b != null && last?.t == b && System.currentTimeMillis() - b < 10_000) { done(true, null); return }
+    take("last", if (customer) 6 else 1) { ok -> done(ok, if (ok) null else lastReason ?: "no frame") }
+  }
+
+  fun takeMedia(): WritableMap {
+    frozen = true // F8
+    // C2's order: the last frame, taps (newest first), video near a "Bug here"
+    // mark (closest first), then the rest of the video spread over the clip.
+    val all = ArrayList<Frame>()
+    last?.let { all.add(it) }
+    all.addAll(taps.asReversed())
+    val gap = { f: Frame -> marks.minOfOrNull { kotlin.math.abs(it - f.t) } ?: Double.MAX_VALUE }
+    val near = video.filter { gap(it) <= NEAR_MARK_MS }.sortedBy(gap)
+    all.addAll(near)
+    // The rest in spread order, so a size cut keeps frames from the whole clip.
+    val rest = video.filter { v -> near.none { it === v } }
+    for (i in spreadOrder(rest.size)) all.add(rest[i])
+    val kept = ArrayList<Frame>()
+    var bytes = 0
+    var cut = 0
+    for (f in all) {
+      if (kept.size >= 150 || bytes + f.jpeg.size > 4 * 1024 * 1024) { cut++; continue } // C2, before base64
+      kept.add(f)
+      bytes += f.jpeg.size
+    }
+    kept.sortBy { it.t }
+    val frames = Arguments.createArray()
+    for (f in kept) frames.pushMap(Arguments.createMap().apply {
+      putDouble("t", f.t); putString("kind", f.kind); putInt("w", f.w); putInt("h", f.h)
+      putInt("boxes", f.boxes); putBoolean("moved", f.moved)
+      putString("jpeg", Base64.encodeToString(f.jpeg, Base64.NO_WRAP))
+    })
+    val reasons = Arguments.createMap().apply { for ((k, v) in dropped) putInt(k, v) }
+    return Arguments.createMap().apply {
+      putArray("frames", frames)
+      putArray("marks", Arguments.createArray().apply { marks.forEach { pushDouble(it) } })
+      putInt("dropped", cut + dropped.values.sum())
+      putMap("reasons", reasons)
+      stoppedReason?.let { putString("stopped", it) }
+      last?.let { putDouble("lastAgeMs", System.currentTimeMillis() - it.t) }
+      putMap("settings", Arguments.createMap().apply {
+        putBoolean("maskAllText", masks.text); putBoolean("maskAllImages", masks.images); putBoolean("maskAllInputs", masks.inputs)
+      })
+    }
+  }
+
+  fun resume() { frozen = false }
+
+  fun clear() {
+    // A frame still being made belongs to the old settings: a new run token drops it.
+    run++
+    busy = false
+    main.removeCallbacks(tapRunnable)
+    taps.clear(); video.clear(); last = null; marks.clear(); dropped.clear(); frozen = false
+  }
+
+  fun stopAll() {
+    run++
+    stopVideo()
+    main.removeCallbacks(tapRunnable)
+    detachWatcher()
+    busy = false
+    enabled = false
+  }
+
+  /** The module is gone (reload or app close): free the thread too. */
+  fun destroy() {
+    stopAll()
+    if (listening) { context.removeLifecycleEventListener(lifecycle); listening = false }
+    thread.quitSafely()
+  }
+
+  // MARK: one frame
+
+  private fun drop(reason: String) {
+    dropped[reason] = (dropped[reason] ?: 0) + 1
+    lastReason = reason
+  }
+
+  private class Target(val window: Window, val root: WalkRoot)
+
+  private class Found(val targets: List<Target>, val frameW: Float, val frameH: Float, val density: Float, val reason: String?)
+
+  /** The app's windows: the Activity, plus any RN Modal on top. */
+  private fun findWindows(activity: Activity): Found {
+    val window = activity.window
+    val decor = window.decorView
+    val density = decor.resources.displayMetrics.density
+    val w = decor.width / density
+    val h = decor.height / density
+    fun no(reason: String) = Found(emptyList(), w, h, density, reason)
+    if (decor.width <= 0 || decor.height <= 0) return no("no app window")
+    if (window.attributes.flags and WindowManager.LayoutParams.FLAG_SECURE != 0) return no("this screen is protected") // H5
+    val targets = arrayListOf(Target(window, WalkRoot(decor, 0f, 0f)))
+    val base = IntArray(2).also { decor.getLocationOnScreen(it) }
+    val dialogs = ArrayList<View>()
+    collectModals(decor, dialogs)
+    for (host in dialogs) {
+      val d = modalDialog(host) ?: return no("a popup is open that Buoy can't read")
+      if (!d.isShowing) continue
+      val dw = d.window ?: return no("a popup is open that Buoy can't read")
+      if (dw.attributes.flags and WindowManager.LayoutParams.FLAG_SECURE != 0) return no("this screen is protected")
+      val dDecor = dw.decorView
+      val loc = IntArray(2).also { dDecor.getLocationOnScreen(it) }
+      if (!modalOrder.containsKey(dw)) modalOrder[dw] = ++modalSeq
+      targets.add(Target(dw, WalkRoot(dDecor, (loc[0] - base[0]).toFloat(), (loc[1] - base[1]).toFloat())))
+    }
+    // Draw Modals in the order they opened, not their order in the JSX, and
+    // the one with focus on top: it's the one in front.
+    if (targets.size > 2) {
+      val modals = targets.subList(1, targets.size).sortedWith(
+        compareBy({ if (it.window.decorView.hasWindowFocus()) 1 else 0 }, { modalOrder[it.window] ?: 0L })
+      )
+      for (i in modals.indices) targets[i + 1] = modals[i]
+    }
+    // Something else on top (a system sheet, another SDK's dialog): the
+    // Activity has lost focus to a window we can't see.
+    // With Modals open too: when none of our windows has focus, something we can't see is in front.
+    if (!decor.hasWindowFocus() && !anyFocused(targets)) return no("another window is on top")
+    return Found(targets, w, h, density, null)
+  }
+
+  private fun anyFocused(t: List<Target>) = t.any { it.window.decorView.hasWindowFocus() }
+
+  private fun collectModals(root: View, out: ArrayList<View>) {
+    val stack = ArrayList<View>().apply { add(root) }
+    while (stack.isNotEmpty()) {
+      val v = stack.removeAt(stack.size - 1)
+      if (v.javaClass.name.contains("ReactModalHostView")) out.add(v)
+      if (v is android.view.ViewGroup) for (i in 0 until v.childCount) v.getChildAt(i)?.let { stack.add(it) }
+    }
+  }
+
+  private fun modalDialog(host: View): Dialog? {
+    var c: Class<*>? = host.javaClass
+    while (c != null) {
+      try {
+        val f = c.getDeclaredField("dialog")
+        f.isAccessible = true
+        return f.get(host) as? Dialog
+      } catch (_: NoSuchFieldException) {
+        c = c.superclass
+      } catch (_: Throwable) {
+        return null
+      }
+    }
+    return null
+  }
+
+  // A debuggable build runs this code about 8 times slower (13 ms vs 1.6 ms on
+  // a Pixel 4 XL), so it gets more time before a frame is dropped.
+  private val walkBudgetMs: Long =
+    if (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE != 0) 160 else 40
+
+  private fun walk(found: Found): Walk =
+    FrameWalker.walk(found.targets.map { it.root }, found.frameW, found.frameH, found.density, masks, walkBudgetMs)
+
+  private fun appInFront(): Boolean = context.lifecycleState == LifecycleState.RESUMED
+
+  /** One frame over two display ticks: boxes a tick before, then right before and right after the copy (H13). */
+  private fun take(kind: String, attempts: Int, done: ((Boolean) -> Unit)?) {
+    if (!enabled) { done?.invoke(false); return }
+    // Customer mode keeps the last frame only (M1); a tap queued before the switch adds nothing.
+    if (kind == "tap" && (customer || !pictures)) { done?.invoke(false); return }
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) { drop("pictures need Android 8.0 or newer"); done?.invoke(false); return }
+    attachWatcher()
+    if (busy) { drop("busy"); done?.invoke(false); return }
+    if (!appInFront()) { drop("app in background"); done?.invoke(false); return } // F7
+    val activity = context.currentActivity ?: run { drop("no app window"); done?.invoke(false); return }
+    busy = true
+    val token = run
+    val foundA = findWindows(activity)
+    val walkA = if (foundA.reason == null) walk(foundA) else null
+    Choreographer.getInstance().postFrameCallback {
+      if (token != run) { done?.invoke(false); return@postFrameCallback }
+      shoot(kind, activity, foundA, walkA, token) { ok, retry ->
+        if (!ok && retry && attempts > 1) {
+          main.postDelayed({
+            if (token == run) take(kind, attempts - 1, done) else done?.invoke(false)
+          }, 100)
+        } else done?.invoke(ok)
+      }
+    }
+  }
+
+  private fun shoot(kind: String, activity: Activity, foundA: Found, walkA: Walk?, token: Int, done: (Boolean, Boolean) -> Unit) {
+    val t0 = SystemClock.uptimeMillis()
+    fun fail(reason: String, retry: Boolean = false) { busy = false; drop(reason); done(false, retry) }
+    if (!appInFront() || context.currentActivity !== activity) return fail("app in background")
+    foundA.reason?.let { return fail(it) }
+    val found = findWindows(activity)
+    found.reason?.let { return fail(it) }
+    if (!sameWindows(foundA, found)) return fail("the window changed")
+    val walkB = walk(found)
+    (walkA?.failed ?: walkB.failed)?.let { return fail(it) }
+    if (walkA?.buoyOpen == true || walkB.buoyOpen) return fail("a Buoy screen was open") // F5
+
+    val scale = min(1f, MAX_LONG_SIDE / max(found.frameW, found.frameH))
+    val outW = max(1, (found.frameW * scale).roundToInt())
+    val outH = max(1, (found.frameH * scale).roundToInt())
+    val copies = arrayOfNulls<Bitmap>(found.targets.size)
+    val mainMs = SystemClock.uptimeMillis() - t0
+
+    // Copy each window in turn on the background thread, with a deadline.
+    var settled = false
+    val deadline = Runnable {
+      if (settled) return@Runnable
+      // A newer run (clear, stop): still answer, so a waiting report never hangs.
+      if (token != run) { settled = true; copies.forEach { it?.recycle() }; done(false, false); return@Runnable }
+      settled = true
+      copies.forEach { it?.recycle() }
+      fail("the copy took too long")
+    }
+    main.postDelayed(deadline, COPY_DEADLINE_MS)
+
+    fun finish(ok: Boolean, why: String?) {
+      main.post {
+        main.removeCallbacks(deadline)
+        if (settled) return@post
+        if (token != run) { settled = true; copies.forEach { it?.recycle() }; done(false, false); return@post }
+        settled = true
+        if (!ok) { copies.forEach { it?.recycle() }; return@post fail(why ?: "the copy failed") }
+        // H11 / H13: read the boxes again now the pixels are in.
+        val tC = SystemClock.uptimeMillis()
+        val foundC = findWindows(activity)
+        if (foundC.reason != null || !sameWindows(found, foundC)) { copies.forEach { it?.recycle() }; return@post fail(foundC.reason ?: "the window changed") }
+        val walkC = walk(foundC)
+        walkC.failed?.let { copies.forEach { b -> b?.recycle() }; return@post fail(it) }
+        if (walkC.buoyOpen) { copies.forEach { it?.recycle() }; return@post fail("a Buoy screen was open") }
+        val boxes = HashMap<View, RectF>(walkA?.parts ?: emptyMap())
+        var moved = walkA == null
+        for (parts in listOf(walkB.parts, walkC.parts)) for ((v, r) in parts) {
+          val old = boxes[v]
+          if (old == null) { boxes[v] = RectF(r); moved = true }
+          else { if (old != r) moved = true; old.union(r) }
+        }
+        if (walkA != null && walkA.parts.keys.any { it !in walkC.parts }) moved = true
+        if (moved && customer) { copies.forEach { it?.recycle() }; return@post fail("the screen was moving", retry = true) }
+        noteSpeed(mainMs + (SystemClock.uptimeMillis() - tC), kind)
+        val rects = merge(boxes.values.toList())
+        val offsets = found.targets.map { Pair(it.root.dx / found.density, it.root.dy / found.density) }
+        val wall = System.currentTimeMillis().toDouble()
+        bg.post {
+          val jpeg = try { compose(copies, offsets, outW, outH, scale, rects) } catch (_: Throwable) { null }
+          copies.forEach { it?.recycle() }
+          main.post {
+            if (token != run) { done(false, false); return@post }
+            busy = false
+            if (jpeg == null) { drop("couldn't make the picture"); done(false, false); return@post }
+            keep(Frame(wall, kind, found.frameW.roundToInt(), found.frameH.roundToInt(), jpeg, rects.size, moved))
+            done(true, false)
+          }
+        }
+      }
+    }
+
+    fun copy(i: Int) {
+      if (i == found.targets.size) { finish(true, null); return }
+      val t = found.targets[i]
+      val d = t.root.view
+      val bw = max(1, (d.width / found.density * scale).roundToInt())
+      val bh = max(1, (d.height / found.density * scale).roundToInt())
+      val bmp = try { Bitmap.createBitmap(bw, bh, Bitmap.Config.ARGB_8888) } catch (_: Throwable) { null }
+        ?: return finish(false, "not enough memory for a picture")
+      copies[i] = bmp
+      try {
+        PixelCopy.request(t.window, bmp, { result ->
+          if (result == PixelCopy.SUCCESS) copy(i + 1)
+          else finish(false, "the copy failed (code $result)")
+        }, bg)
+      } catch (e: Throwable) {
+        finish(false, "the copy failed")
+      }
+    }
+    copy(0)
+  }
+
+  private fun sameWindows(a: Found, b: Found): Boolean =
+    a.targets.size == b.targets.size && a.frameW == b.frameW && a.frameH == b.frameH &&
+      a.targets.indices.all { a.targets[it].window === b.targets[it].window }
+
+  private fun compose(copies: Array<Bitmap?>, offsets: List<Pair<Float, Float>>, w: Int, h: Int, scale: Float, rects: List<RectF>): ByteArray? {
+    val out = Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888)
+    try {
+      val c = Canvas(out)
+      c.drawColor(Color.BLACK)
+      for (i in copies.indices) {
+        val b = copies[i] ?: return null
+        c.drawBitmap(b, offsets[i].first * scale, offsets[i].second * scale, null)
+      }
+      for (r in rects) c.drawRect(r.left * scale, r.top * scale, r.right * scale, r.bottom * scale, BOX)
+      val bytes = ByteArrayOutputStream()
+      if (!out.compress(Bitmap.CompressFormat.JPEG, 60, bytes)) return null // F1
+      return bytes.toByteArray()
+    } finally {
+      out.recycle()
+    }
+  }
+
+  private fun keep(f: Frame) {
+    if (frozen && f.kind != "last") return // F8
+    when (f.kind) {
+      "last" -> last = f
+      "tap" -> { taps.add(f); while (taps.size > 10) taps.removeAt(0) } // F2
+      else -> {
+        video.add(f)
+        val cutoff = f.t - if (videoAlways) 30_000 else 60_000 // F3, F3a
+        video.removeAll { it.t < cutoff }
+        var total = video.sumOf { it.jpeg.size }
+        while (total > MAX_VIDEO_BYTES && video.isNotEmpty()) total -= video.removeAt(0).jpeg.size // F4
+      }
+    }
+  }
+
+  /** F6 and M1: slow phones take fewer frames, then stop. */
+  private fun noteSpeed(ms: Long, kind: String) {
+    if (kind == "last") return
+    when {
+      ms > 250 -> { stoppedReason = "pictures stopped: this phone took $ms ms for one"; stopVideo() }
+      ms > 100 -> { slowInRow++; if (slowInRow >= 2) { videoFps = max(0.5, videoFps / 2); slowInRow = 0 } }
+      else -> slowInRow = 0
+    }
+  }
+
+  private fun merge(rects: List<RectF>): List<RectF> {
+    val sorted = rects.sortedByDescending { it.width() * it.height() }
+    val out = ArrayList<RectF>()
+    for (r in sorted) if (out.none { it.contains(r) }) out.add(r)
+    return out
+  }
+
+  // MARK: test hook
+
+  /** The testID for a boxed view: its own, or the nearest parent's when the box covers most of it. */
+  private fun probeId(v: View): String {
+    FrameWalker.testId(v)?.takeIf { it.isNotEmpty() }?.let { return it }
+    var p = v.parent
+    while (p is View) {
+      val id = FrameWalker.testId(p)
+      if (!id.isNullOrEmpty()) return if (v.width * v.height >= p.width * p.height * 0.8) id else ""
+      p = p.parent
+    }
+    return ""
+  }
+
+  fun probe(done: (WritableMap) -> Unit) {
+    val activity = context.currentActivity ?: return done(Arguments.createMap().apply { putBoolean("ok", false); putString("reason", "no app window") })
+    val found = findWindows(activity)
+    val parts = Arguments.createArray()
+    var failed: String? = found.reason
+    var buoyOpen = false
+    if (found.reason == null) {
+      val w = FrameWalker.walk(found.targets.map { it.root }, found.frameW, found.frameH, found.density, masks, 200)
+      failed = w.failed
+      buoyOpen = w.buoyOpen
+      for ((v, r) in w.parts) parts.pushMap(Arguments.createMap().apply {
+        putString("testID", probeId(v)); putString("cls", v.javaClass.name); putDouble("x", r.left.toDouble()); putDouble("y", r.top.toDouble())
+        putDouble("w", r.width().toDouble()); putDouble("h", r.height().toDouble())
+      })
+    }
+    val wasFrozen = frozen
+    frozen = false
+    take("last", 1) { ok ->
+      frozen = wasFrozen
+      done(Arguments.createMap().apply {
+        putBoolean("ok", ok)
+        if (!ok) putString("reason", lastReason)
+        putArray("parts", parts)
+        failed?.let { putString("failed", it) }
+        putBoolean("buoyOpen", buoyOpen)
+        if (ok) last?.let { putString("jpeg", Base64.encodeToString(it.jpeg, Base64.NO_WRAP)) }
+        putDouble("w", found.frameW.toDouble()); putDouble("h", found.frameH.toDouble())
+      })
+    }
+  }
+
+  /** Watches touches without taking them: every call goes on to the app as before. */
+  private class TapCallback(
+    val base: Window.Callback,
+    val down: (Float, Float) -> Unit,
+    val up: () -> Unit,
+    val focus: ((Boolean) -> Unit)? = null,
+    val detached: (() -> Unit)? = null,
+  ) : Window.Callback by base {
+    var live = true
+    override fun onWindowFocusChanged(hasFocus: Boolean) {
+      base.onWindowFocusChanged(hasFocus)
+      if (live) try { focus?.invoke(hasFocus) } catch (_: Throwable) {}
+    }
+    override fun onDetachedFromWindow() {
+      base.onDetachedFromWindow()
+      try { detached?.invoke() } catch (_: Throwable) {}
+    }
+    override fun dispatchTouchEvent(event: MotionEvent?): Boolean {
+      if (event != null && live) try {
+        when (event.actionMasked) {
+          MotionEvent.ACTION_DOWN -> down(event.x, event.y)
+          MotionEvent.ACTION_UP -> up()
+        }
+      } catch (_: Throwable) {}
+      return base.dispatchTouchEvent(event)
+    }
+  }
+}