@scalebun-release/react-native 2.5.0

package/android/src/main/java/com/scalebun/replaysdk/tracking/InteractionTracker.kt

@@ -0,0 +1,470 @@
+package com.scalebun.replaysdk.tracking
+
+import android.app.Activity
+import android.os.Handler
+import android.os.Looper
+import android.view.MotionEvent
+import android.view.View
+import android.view.Window
+import android.view.WindowManager
+import java.lang.ref.WeakReference
+import java.util.WeakHashMap
+import java.util.UUID
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.scalebun.replaysdk.core.ReplayLogger
+
+/**
+ * Native interaction tracker.
+ *
+ * Intercepts MotionEvents at the Window.Callback level (highest safe intercept point).
+ * Captures touch start/end in the SAME coordinate space as FrameCaptureManager screenshots
+ * (android.R.id.content view), so normalizedX/Y map exactly to screenshot pixels.
+ *
+ * Emits ScaleBunNativeInteraction events to JS with confidence:"high".
+ */
+class InteractionTracker(private val reactContext: ReactApplicationContext) {
+
+    private var nativeInterceptor: NativeTouchInterceptor? = null
+    private var attachedWindow: android.view.Window? = null
+    private var dialogObserver: DialogTouchObserver? = null
+    var isNativeActive = false
+        private set
+
+    private var touchDownX = 0f
+    private var touchDownY = 0f
+    private var touchDownTs = 0L
+    private var touchDownOccurredAt = 0L
+    private var touchInteractionId = ""
+    /** Scroll containers under the finger at ACTION_DOWN, innermost first. See ScrollContextProbe. */
+    private var touchDownScroll: List<ScrollContextProbe.Entry> = emptyList()
+    private var lastEmittedInteractionId = ""
+    private val processInteractionNonce = UUID.randomUUID().toString().take(8)
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    fun attach(activity: Activity) {
+        if (isNativeActive) return
+        mainHandler.post {
+            try {
+                val window = activity.window ?: return@post
+                val original = window.callback ?: return@post
+
+                // CRITICAL: We do NOT cache contentView at attach time.
+                // R.id.content may be zero-sized during attach (pre-layout). Caching the
+                // decorView fallback at attach used to silently keep normalizing against
+                // decorView dims while FrameCaptureManager captured the smaller content
+                // view — producing markers offset toward the top by ~status-bar fraction.
+                // We resolve the capture view fresh per touch, identically to
+                // FrameCaptureManager.capture(), so denominators always match the screenshot.
+                val interceptor = NativeTouchInterceptor(
+                    original = original,
+                    onDown = { rawX, rawY, ts ->
+                        touchDownX = rawX
+                        touchDownY = rawY
+                        touchDownTs = ts
+                        val id = "ixn-a-$processInteractionNonce-$ts"
+                        if (id != touchInteractionId) touchDownOccurredAt = System.currentTimeMillis()
+                        touchInteractionId = id
+                        touchDownScroll = ScrollContextProbe.probe(resolveCaptureView(window), rawX, rawY)
+                    },
+                    onUp = { rawX, rawY, ts ->
+                        handleTouchUp(rawX, rawY, ts, resolveCaptureView(window))
+                    }
+                )
+                window.callback = interceptor
+                nativeInterceptor = interceptor
+                attachedWindow = window
+                isNativeActive = true
+                ReplayLogger.info("Native touch tracking attached (per-touch view resolution)")
+
+                // Also observe extra dialog windows (Alert.alert → native AlertDialog
+                // lives in a separate Window not covered by the activity-window callback).
+                // Dialog taps reuse the SAME onDown/onUp → handleTouchUp path so they
+                // normalize against the main activity's R.id.content, identical to the
+                // screenshot compositing base.
+                dialogObserver = DialogTouchObserver(
+                    mainHandler = mainHandler,
+                    getMainRootView = { attachedWindow?.decorView?.rootView },
+                    onDown = { rawX, rawY, ts ->
+                        touchDownX = rawX
+                        touchDownY = rawY
+                        touchDownTs = ts
+                        val id = "ixn-a-$processInteractionNonce-$ts"
+                        if (id != touchInteractionId) touchDownOccurredAt = System.currentTimeMillis()
+                        touchInteractionId = id
+                        touchDownScroll = emptyList()
+                    },
+                    onUp = { rawX, rawY, ts ->
+                        val main = attachedWindow ?: return@DialogTouchObserver
+                        handleTouchUp(rawX, rawY, ts, resolveCaptureView(main), onDialogWindow = true)
+                    }
+                ).also { it.start() }
+            } catch (e: Exception) {
+                ReplayLogger.error("Failed to attach native touch tracker: ${e.message}")
+            }
+        }
+    }
+
+    /**
+     * Resolve the capture view fresh — matches FrameCaptureManager.capture() exactly.
+     * Returns R.id.content ONLY. Never falls back to decorView — decorView includes
+     * status bar / navigation bar area, so normalizing against it produces a larger
+     * denominator than the PixelCopy screenshot, shifting markers upward by the
+     * status-bar fraction. Returns null if R.id.content is unusable, causing the
+     * event to be dropped rather than emitted with wrong coordinates.
+     */
+    private fun resolveCaptureView(window: android.view.Window): View? {
+        return try {
+            val decorView = window.decorView ?: return null
+            decorView.rootView
+                ?.findViewById<View>(android.R.id.content)
+                ?.takeIf { it.width > 0 && it.height > 0 }
+        } catch (e: Exception) {
+            null
+        }
+    }
+
+    fun detach(activity: Activity) {
+        val interceptor = nativeInterceptor ?: return
+        try {
+            dialogObserver?.stop()
+            dialogObserver = null
+            activity.window?.callback = interceptor.original
+            nativeInterceptor = null
+            attachedWindow = null
+            isNativeActive = false
+            ReplayLogger.info("Native touch tracking detached")
+        } catch (e: Exception) {
+            ReplayLogger.error("Failed to detach native touch tracker: ${e.message}")
+        }
+    }
+
+    private fun handleTouchUp(rawX: Float, rawY: Float, ts: Long, captureView: View?, onDialogWindow: Boolean = false) {
+        if (captureView == null) {
+            ReplayLogger.debug("Native touch up dropped: no usable capture view")
+            return
+        }
+        // Window/dialog hooks can re-deliver one physical touch. The ACTION_DOWN identity is stable
+        // across those deliveries, unlike coordinates: two legitimate rapid taps may land on the
+        // exact same pixel and must both survive.
+        if (touchInteractionId.isNotEmpty() && touchInteractionId == lastEmittedInteractionId) return
+        lastEmittedInteractionId = touchInteractionId
+
+        val durationMs = ts - touchDownTs
+        val dx = rawX - touchDownX
+        val dy = rawY - touchDownY
+        val dist = Math.sqrt((dx * dx + dy * dy).toDouble())
+
+        val gestureType = when {
+            dist > 40.0 -> if (Math.abs(dy) > Math.abs(dx)) "scroll" else "swipe"
+            durationMs > 500L -> "long_press"
+            else -> "tap"
+        }
+
+        val viewW = captureView.width.toFloat()
+        val viewH = captureView.height.toFloat()
+        if (viewW <= 0 || viewH <= 0) return
+
+        // Convert raw screen coordinates to captureView-local coordinates.
+        // Use getLocationInWindow() — the SAME coordinate system FrameCaptureManager
+        // uses for the PixelCopy srcRect. This eliminates any mismatch between
+        // screen-space and window-space that can occur on devices with non-zero
+        // window origin (edge-to-edge, multi-window, display cutout modes).
+        //
+        // To convert screen-space rawX/rawY to window-space, we subtract the
+        // window's own screen position first, then subtract the view's window
+        // position — equivalent to getLocationOnScreen but using the same
+        // coordinate system as PixelCopy.
+        val windowLoc = IntArray(2)
+        val screenLoc = IntArray(2)
+        try {
+            captureView.getLocationInWindow(windowLoc)
+            captureView.getLocationOnScreen(screenLoc)
+        } catch (e: Exception) {
+            ReplayLogger.error("getLocation failed: ${e.message}")
+            return
+        }
+        // Window's screen offset = screenLoc - windowLoc
+        val windowOffsetX = screenLoc[0] - windowLoc[0]
+        val windowOffsetY = screenLoc[1] - windowLoc[1]
+        // Convert rawX/rawY (screen-space) → window-space → view-local
+        val viewLeft = windowLoc[0].toFloat()
+        val viewTop = windowLoc[1].toFloat()
+
+        val localDownX = (touchDownX - windowOffsetX) - viewLeft
+        val localDownY = (touchDownY - windowOffsetY) - viewTop
+        val localUpX = (rawX - windowOffsetX) - viewLeft
+        val localUpY = (rawY - windowOffsetY) - viewTop
+
+        val normalizedX = (localDownX / viewW).coerceIn(0f, 1f)
+        val normalizedY = (localDownY / viewH).coerceIn(0f, 1f)
+        val normalizedEndX = (localUpX / viewW).coerceIn(0f, 1f)
+        val normalizedEndY = (localUpY / viewH).coerceIn(0f, 1f)
+
+        emitNativeInteraction(
+            gestureType = gestureType,
+            rawX = localDownX,
+            rawY = localDownY,
+            normalizedX = normalizedX,
+            normalizedY = normalizedY,
+            normalizedEndX = normalizedEndX,
+            normalizedEndY = normalizedEndY,
+            rawEndX = localUpX,
+            rawEndY = localUpY,
+            scroll = touchDownScroll,
+            density = captureView.resources?.displayMetrics?.density ?: 0f,
+            screenshotW = viewW,
+            screenshotH = viewH,
+            durationMs = durationMs,
+            interactionId = touchInteractionId,
+            occurredAt = touchDownOccurredAt,
+            onDialogWindow = onDialogWindow
+        )
+    }
+
+    private fun emitNativeInteraction(
+        gestureType: String,
+        rawX: Float, rawY: Float,
+        normalizedX: Float, normalizedY: Float,
+        normalizedEndX: Float, normalizedEndY: Float,
+        rawEndX: Float, rawEndY: Float,
+        scroll: List<ScrollContextProbe.Entry>,
+        density: Float,
+        screenshotW: Float, screenshotH: Float,
+        durationMs: Long,
+        interactionId: String,
+        occurredAt: Long,
+        onDialogWindow: Boolean = false
+    ) {
+        try {
+            val params = Arguments.createMap().apply {
+                putString("gestureType", gestureType)
+                putString("interactionId", interactionId)
+                putInt("interactionProtocol", 1)
+                putDouble("occurredAt", occurredAt.toDouble())
+                putDouble("rawX", rawX.toDouble())
+                putDouble("rawY", rawY.toDouble())
+                putDouble("normalizedX", normalizedX.toDouble())
+                putDouble("normalizedY", normalizedY.toDouble())
+                putDouble("normalizedEndX", normalizedEndX.toDouble())
+                putDouble("normalizedEndY", normalizedEndY.toDouble())
+                /* The swipe END in the same local space as rawX/rawY. JS read rawEndX and fell back to
+                   rawX because neither platform sent it, so every swipe's end equalled its start. */
+                putDouble("rawEndX", rawEndX.toDouble())
+                putDouble("rawEndY", rawEndY.toDouble())
+                if (density > 0f) putDouble("pixelDensity", density.toDouble())
+                /* Scroll containers under the finger at DOWN, innermost first, capture-view pixels. */
+                val sc = Arguments.createArray()
+                for (e in scroll) {
+                    sc.pushMap(Arguments.createMap().apply {
+                        putInt("containerTag", e.containerTag)
+                        putString("kind", e.kind)
+                        putBoolean("horizontal", e.horizontal)
+                        putInt("offsetX", e.offsetX)
+                        putInt("offsetY", e.offsetY)
+                        putInt("contentWidth", e.contentWidth)
+                        putInt("contentHeight", e.contentHeight)
+                        putInt("viewportWidth", e.viewportWidth)
+                        putInt("viewportHeight", e.viewportHeight)
+                    })
+                }
+                putArray("scrollContext", sc)
+                putDouble("screenshotWidthPx", screenshotW.toDouble())
+                putDouble("screenshotHeightPx", screenshotH.toDouble())
+                putString("coordinateSpace", "android-content-view-px")
+                putDouble("timestamp", System.currentTimeMillis().toDouble())
+                putString("confidence", "high")
+                putString("source", "native-interaction-tracker")
+                putDouble("durationMs", durationMs.toDouble())
+                putString("platform", "android")
+                putBoolean("onDialogWindow", onDialogWindow)
+            }
+            reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+                .emit("ScaleBunNativeInteraction", params)
+            ReplayLogger.debug(
+                "[TapAccuracy] platform=android type=$gestureType " +
+                "rawLocalPx=($rawX,$rawY) normalized=($normalizedX,$normalizedY) " +
+                "captureViewPx=(${screenshotW}x${screenshotH}) space=android-content-view-px"
+            )
+        } catch (e: Exception) {
+            ReplayLogger.error("Native interaction emit failed: ${e.message}")
+        }
+    }
+
+    // ── JS-reported fallback (backward compat when native tracker unavailable) ──
+
+    private var lastInteractionMs: Long = 0
+    private val debounceMs: Long = 300
+
+    fun reportInteraction(type: String, x: Int, y: Int, timestamp: Long): Boolean {
+        if (isNativeActive) return false
+        val now = System.currentTimeMillis()
+        if (now - lastInteractionMs < debounceMs) return false
+        lastInteractionMs = now
+        ReplayLogger.debug("JS interaction: $type at ($x, $y)")
+        return true
+    }
+
+    fun reset() {
+        lastInteractionMs = 0
+        touchInteractionId = ""
+        lastEmittedInteractionId = ""
+        touchDownTs = 0
+    }
+}
+
+/**
+ * Window.Callback delegate that intercepts touch events without consuming them.
+ * Only observes ACTION_DOWN and ACTION_UP — all other events pass through unchanged.
+ */
+class NativeTouchInterceptor(
+    val original: Window.Callback,
+    private val onDown: (rawX: Float, rawY: Float, ts: Long) -> Unit,
+    private val onUp: (rawX: Float, rawY: Float, ts: Long) -> Unit
+) : Window.Callback by original {
+
+    override fun dispatchTouchEvent(event: MotionEvent?): Boolean {
+        event?.let { e ->
+            when (e.actionMasked) {
+                MotionEvent.ACTION_DOWN -> onDown(e.rawX, e.rawY, e.eventTime)
+                MotionEvent.ACTION_UP -> onUp(e.rawX, e.rawY, e.eventTime)
+            }
+        }
+        return original.dispatchTouchEvent(event)
+    }
+}
+
+/**
+ * Observes touches on extra dialog windows (e.g. RN Alert.alert → native AlertDialog),
+ * which live in their own Window and are NOT covered by the activity-window callback.
+ *
+ * Discovery mirrors FrameCaptureManager.compositeExtraWindows EXACTLY: reflect on
+ * android.view.WindowManagerGlobal.mViews and apply the same filtering (skip the main
+ * activity root, non-visible / detached / zero-size, and FLAG_SECURE windows). This keeps
+ * the set of observed windows identical to the set composited into the screenshot.
+ *
+ * Each qualifying dialog window has its Window.callback wrapped with a non-consuming
+ * NativeTouchInterceptor (returns the original dispatchTouchEvent result, never swallows
+ * the touch). Coordinates use MotionEvent.rawX/rawY (screen-space), so the shared onUp
+ * handler can normalize them against the MAIN activity's R.id.content — the same base the
+ * screenshot uses — without any per-window math.
+ *
+ * All reflection is wrapped in try/catch and silently no-ops on failure. Dialogs that
+ * appear after tracking starts are caught by a periodic rescan posted on the main handler
+ * (not a busy loop). Hooked windows are tracked weakly to avoid leaking dismissed dialogs.
+ */
+class DialogTouchObserver(
+    private val mainHandler: Handler,
+    private val getMainRootView: () -> View?,
+    private val onDown: (rawX: Float, rawY: Float, ts: Long) -> Unit,
+    private val onUp: (rawX: Float, rawY: Float, ts: Long) -> Unit
+) {
+    private val hookedWindows = WeakHashMap<Window, WeakReference<NativeTouchInterceptor>>()
+    private var rescanRunnable: Runnable? = null
+    private val RESCAN_MS = 400L
+
+    fun start() {
+        stop()
+        val runnable = object : Runnable {
+            override fun run() {
+                rescan()
+                mainHandler.postDelayed(this, RESCAN_MS)
+            }
+        }
+        rescanRunnable = runnable
+        mainHandler.postDelayed(runnable, RESCAN_MS)
+    }
+
+    fun stop() {
+        rescanRunnable?.let { mainHandler.removeCallbacks(it) }
+        rescanRunnable = null
+        unhookAll()
+    }
+
+    private fun rescan() {
+        try {
+            val mainRoot = getMainRootView()
+            val wmgClass = Class.forName("android.view.WindowManagerGlobal")
+            val wmgInstance = wmgClass.getMethod("getInstance").invoke(null)
+            val viewsField = wmgClass.getDeclaredField("mViews")
+            viewsField.isAccessible = true
+
+            @Suppress("UNCHECKED_CAST")
+            val views = viewsField.get(wmgInstance) as? java.util.ArrayList<View> ?: return
+
+            // Snapshot copy — mViews can mutate while we iterate (dialogs added/removed).
+            for (view in ArrayList(views)) {
+                if (view === mainRoot) continue
+                if (view.visibility != View.VISIBLE || view.windowToken == null ||
+                    view.width <= 0 || view.height <= 0
+                ) continue
+
+                val lp = view.layoutParams as? WindowManager.LayoutParams
+                if (lp != null && (lp.flags and WindowManager.LayoutParams.FLAG_SECURE) != 0) {
+                    continue
+                }
+
+                val window = resolveWindow(view) ?: continue
+                if (hookedWindows.containsKey(window)) continue
+                hookWindow(window)
+            }
+        } catch (e: Exception) {
+            ReplayLogger.debug("Dialog window rescan failed: ${e.message}")
+        }
+    }
+
+    private fun hookWindow(window: Window) {
+        try {
+            val original = window.callback ?: return
+            // Never double-wrap our own interceptor.
+            if (original is NativeTouchInterceptor) {
+                hookedWindows[window] = WeakReference(original)
+                return
+            }
+            val interceptor = NativeTouchInterceptor(original, onDown, onUp)
+            window.callback = interceptor
+            hookedWindows[window] = WeakReference(interceptor)
+            ReplayLogger.debug("Hooked dialog window touch callback")
+        } catch (e: Exception) {
+            ReplayLogger.debug("Hook dialog window failed: ${e.message}")
+        }
+    }
+
+    private fun unhookAll() {
+        try {
+            for ((window, ref) in hookedWindows) {
+                try {
+                    val interceptor = ref.get() ?: continue
+                    if (window.callback === interceptor) {
+                        window.callback = interceptor.original
+                    }
+                } catch (_: Exception) { /* window may already be torn down */ }
+            }
+        } catch (_: Exception) { /* no-throw */ }
+        hookedWindows.clear()
+    }
+
+    /**
+     * Resolve the Window backing a top-level (decor) view via reflection.
+     * DecorView holds its PhoneWindow in a field of type android.view.Window.
+     * Returns null (causing the window to be skipped) if not reachable.
+     */
+    private fun resolveWindow(decorView: View): Window? {
+        var clazz: Class<*>? = decorView.javaClass
+        while (clazz != null) {
+            for (f in clazz.declaredFields) {
+                if (Window::class.java.isAssignableFrom(f.type)) {
+                    return try {
+                        f.isAccessible = true
+                        f.get(decorView) as? Window
+                    } catch (_: Exception) {
+                        null
+                    }
+                }
+            }
+            clazz = clazz.superclass
+        }
+        return null
+    }
+}

package/android/src/main/java/com/scalebun/replaysdk/tracking/ScreenTracker.kt

@@ -0,0 +1,20 @@
+package com.scalebun.replaysdk.tracking
+
+/**
+ * Simple screen name tracker.
+ * Updated from JS or from native Activity tracking.
+ */
+class ScreenTracker {
+    @Volatile
+    var currentScreen: String = "unknown"
+        private set
+
+    private var previousScreen: String = "unknown"
+
+    fun setScreen(name: String) {
+        previousScreen = currentScreen
+        currentScreen = name
+    }
+
+    fun getPreviousScreen(): String = previousScreen
+}

package/android/src/main/java/com/scalebun/replaysdk/tracking/ScrollContextProbe.kt

@@ -0,0 +1,188 @@
+package com.scalebun.replaysdk.tracking
+
+import android.graphics.Rect
+import android.view.View
+import android.view.ViewGroup
+import android.widget.HorizontalScrollView
+import android.widget.ScrollView
+
+/**
+ * WHERE IN THE CONTENT a touch landed — read natively, at ACTION_DOWN, with no wrapper.
+ *
+ * The JS scroll context only knew offsets recorded by the SDK's own ScrollView/FlatList wrappers,
+ * and production apps use the stock components: 0 of ~55,000 production taps carried an offset.
+ * Two taps at the same screen point one viewport apart are different controls, so without this a
+ * scrolled list merges into one hotspot at a position where, in content terms, nothing is.
+ *
+ * Read at DOWN, before the gesture moves anything: the offset that matters is the one the finger
+ * landed on. Innermost first, so a carousel inside a scrolling page reports the carousel before
+ * the page. Everything is in the capture view's pixel space — the same space as the screenshot and
+ * the tap's own rawX/rawY — with `pixelDensity` emitted beside it for a dp conversion.
+ *
+ * React Native's ScrollView/FlatList/SectionList render ReactScrollView (a ScrollView) or
+ * ReactHorizontalScrollView (a HorizontalScrollView); NestedScrollView and RecyclerView are
+ * matched by class name so the SDK takes no AndroidX dependency for them.
+ */
+object ScrollContextProbe {
+    data class Entry(
+        val containerTag: Int,
+        val horizontal: Boolean,
+        val offsetX: Int,
+        val offsetY: Int,
+        val contentWidth: Int,
+        val contentHeight: Int,
+        val viewportWidth: Int,
+        val viewportHeight: Int,
+        val kind: String,
+    )
+
+    private const val MAX_DEPTH = 64
+    private const val MAX_ENTRIES = 4
+    private const val MAX_NODES = 2000
+
+    /**
+     * EVERY visible scroll container in the capture view, read at the moment a screenshot is taken.
+     *
+     * A frame carrying only width/height cannot say whether a tap belongs on it: a tap inside a
+     * list scrolled 900px lands on different content than the same point on a frame taken at 0.
+     * With this beside the pixels, a tap is compatible with a frame when its container reports the
+     * same offset in both. Same classification as [probe] (via [entryFor]) and the same space:
+     * capture-view pixels.
+     *
+     * Bounded on purpose — it runs on the main thread inside every capture: depth <= 64, at most
+     * [MAX_NODES] nodes visited, invisible subtrees skipped whole. Largest on-screen visible area
+     * first, at most 4, so the page's own scroller wins over a small carousel when the cap bites.
+     * Never throws: an empty list is always an acceptable answer.
+     */
+    fun snapshot(root: View?): List<Entry> {
+        if (root == null) return emptyList()
+        return try {
+            val rootRect = Rect()
+            if (!root.getGlobalVisibleRect(rootRect)) return emptyList()
+            val found = ArrayList<Pair<Entry, Long>>(4)
+            val stack = ArrayDeque<Pair<View, Int>>()
+            stack.addLast(root to 0)
+            var visited = 0
+            val r = Rect()
+            while (stack.isNotEmpty() && visited < MAX_NODES) {
+                val (v, depth) = stack.removeLast()
+                visited++
+                if (v.visibility != View.VISIBLE) continue
+                val entry = entryFor(v)
+                if (entry != null && v.getGlobalVisibleRect(r) && r.intersect(rootRect)) {
+                    val area = r.width().toLong() * r.height().toLong()
+                    if (area > 0) found.add(entry to area)
+                }
+                if (v is ViewGroup && depth < MAX_DEPTH) {
+                    // Reverse push so child 0 is visited first: depth-first, document order.
+                    for (i in v.childCount - 1 downTo 0) {
+                        val child = v.getChildAt(i) ?: continue
+                        stack.addLast(child to depth + 1)
+                    }
+                }
+            }
+            found.sortedByDescending { it.second }.take(MAX_ENTRIES).map { it.first }
+        } catch (t: Throwable) {
+            // A scroll state is never worth a crash or a dropped frame.
+            emptyList()
+        }
+    }
+
+    /** Wire shape of a frame's `scrollState` — the same keys as a tap's `scrollContext`. */
+    fun toMaps(entries: List<Entry>): List<Map<String, Any>> = entries.map { e ->
+        mapOf(
+            "containerTag" to e.containerTag,
+            "kind" to e.kind,
+            "horizontal" to e.horizontal,
+            "offsetX" to e.offsetX,
+            "offsetY" to e.offsetY,
+            "contentWidth" to e.contentWidth,
+            "contentHeight" to e.contentHeight,
+            "viewportWidth" to e.viewportWidth,
+            "viewportHeight" to e.viewportHeight,
+        )
+    }
+
+    /** The deepest visible view under the screen point, then its scrollable ancestors up to [root]. */
+    fun probe(root: View?, rawX: Float, rawY: Float): List<Entry> {
+        if (root == null) return emptyList()
+        return try {
+            val hit = hitTest(root, rawX.toInt(), rawY.toInt(), 0) ?: return emptyList()
+            val out = ArrayList<Entry>(2)
+            var v: View? = hit
+            while (v != null && out.size < MAX_ENTRIES) {
+                entryFor(v)?.let { out.add(it) }
+                if (v === root) break
+                v = v.parent as? View
+            }
+            out
+        } catch (e: Exception) {
+            // A scroll offset is never worth a crash or a dropped tap.
+            emptyList()
+        }
+    }
+
+    private fun hitTest(view: View, x: Int, y: Int, depth: Int): View? {
+        if (view.visibility != View.VISIBLE || depth > MAX_DEPTH) return null
+        val loc = IntArray(2)
+        view.getLocationOnScreen(loc)
+        if (x < loc[0] || y < loc[1] || x >= loc[0] + view.width || y >= loc[1] + view.height) return null
+        if (view is ViewGroup) {
+            // Topmost child first: the last drawn child is the one on top.
+            for (i in view.childCount - 1 downTo 0) {
+                val child = view.getChildAt(i) ?: continue
+                val found = hitTest(child, x, y, depth + 1)
+                if (found != null) return found
+            }
+        }
+        return view
+    }
+
+    private fun entryFor(v: View): Entry? {
+        val name = v.javaClass.name
+        return when {
+            v is ScrollView -> fromChild(v, horizontal = false, kind = "scroll")
+            v is HorizontalScrollView -> fromChild(v, horizontal = true, kind = "horizontal_scroll")
+            name.endsWith(".NestedScrollView") -> fromChild(v as ViewGroup, horizontal = false, kind = "nested_scroll")
+            name.endsWith(".RecyclerView") -> recycler(v)
+            else -> null
+        }
+    }
+
+    private fun fromChild(v: ViewGroup, horizontal: Boolean, kind: String): Entry {
+        val content = if (v.childCount > 0) v.getChildAt(0) else null
+        return Entry(
+            containerTag = v.id,
+            horizontal = horizontal,
+            offsetX = v.scrollX,
+            offsetY = v.scrollY,
+            contentWidth = content?.width ?: v.width,
+            contentHeight = content?.height ?: v.height,
+            viewportWidth = v.width,
+            viewportHeight = v.height,
+            kind = kind,
+        )
+    }
+
+    /** RecyclerView's offsets are computed, not scrollX/Y — read reflectively, no AndroidX dependency. */
+    private fun recycler(v: View): Entry? {
+        fun call(m: String): Int? = try {
+            (v.javaClass.getMethod(m).invoke(v) as? Int)
+        } catch (e: Exception) {
+            null
+        }
+        val oy = call("computeVerticalScrollOffset") ?: return null
+        val ox = call("computeHorizontalScrollOffset") ?: 0
+        return Entry(
+            containerTag = v.id,
+            horizontal = (call("computeHorizontalScrollRange") ?: 0) > v.width,
+            offsetX = ox,
+            offsetY = oy,
+            contentWidth = call("computeHorizontalScrollRange") ?: v.width,
+            contentHeight = call("computeVerticalScrollRange") ?: v.height,
+            viewportWidth = v.width,
+            viewportHeight = v.height,
+            kind = "recycler",
+        )
+    }
+}