@goliapkg/sentori-react-native 1.0.0-rc.1 → 1.0.0-rc.3

package/android/src/main/java/com/sentori/SentoriForegroundActivity.kt

@@ -0,0 +1,145 @@
+package com.sentori
+
+import android.app.Activity
+import android.app.Application
+import android.os.Bundle
+import java.lang.ref.WeakReference
+
+/**
+ * v1.0.0-rc.2 — process-wide foreground-Activity tracker.
+ *
+ * Both [SentoriScreenshotCapture] and [SentoriReplayCapture] need a
+ * pointer to the currently-foregrounded Activity to drive their
+ * native captures. The previous implementation registered each
+ * helper's own `ActivityLifecycleCallbacks` inside
+ * [SentoriCrashHandler.register], which runs from the Expo module's
+ * `OnCreate` lifecycle — **after** the MainActivity has already been
+ * resumed in the typical Insight / Expo dev-launcher topology.
+ * `ActivityLifecycleCallbacks` does not back-fill the current state,
+ * it only forwards future events, so `lastActivity` would stay null
+ * for the entire session if the user never backgrounded the app.
+ *
+ * Fix mirrors the iOS keyWindow 4-layer fallback:
+ *
+ *   1. Lifecycle callbacks track resumed/started activities going
+ *      forward (the same approach as before, kept).
+ *   2. **On first install** we also probe `ActivityThread` reflection
+ *      to back-fill whatever Activity is currently foreground, so the
+ *      already-resumed window is seen by the SDK from boot.
+ *   3. If reflection fails (e.g. on a future Android release that
+ *      removes `ActivityThread` access), the lifecycle callbacks
+ *      still catch the next foreground transition.
+ *
+ * `lastPath` carries the diagnostic provenance for `probeWireframe` /
+ * `probeScreenshot`, so the JS side (and Insight) can tell whether
+ * the SDK was working off a live lifecycle event or fell back to
+ * reflection.
+ */
+object SentoriForegroundActivity {
+
+    @Volatile private var lastActivity: WeakReference<Activity>? = null
+    @Volatile var lastPath: String = "none(not-yet-resolved)"
+        private set
+
+    /** Idempotent. Call from [SentoriCrashHandler.register]; subsequent
+     *  calls are no-ops because the same callbacks object would be
+     *  registered twice otherwise. */
+    @Volatile private var registered = false
+
+    @Synchronized
+    fun install(application: Application) {
+        if (registered) {
+            // Even on second install attempt, try the reflection
+            // back-fill again — process state may have advanced.
+            backfillFromActivityThread()
+            return
+        }
+        registered = true
+        application.registerActivityLifecycleCallbacks(object :
+            Application.ActivityLifecycleCallbacks {
+            override fun onActivityCreated(a: Activity, b: Bundle?) {
+                set(a, "lifecycle.created")
+            }
+            override fun onActivityStarted(a: Activity) {
+                set(a, "lifecycle.started")
+            }
+            override fun onActivityResumed(a: Activity) {
+                set(a, "lifecycle.resumed")
+            }
+            override fun onActivityPaused(a: Activity) {}
+            override fun onActivityStopped(a: Activity) {}
+            override fun onActivitySaveInstanceState(a: Activity, b: Bundle) {}
+            override fun onActivityDestroyed(a: Activity) {}
+        })
+        // Back-fill in case the Activity was already resumed before
+        // we got installed (the dev-launcher → MainActivity transition
+        // happens before the Expo module's OnCreate fires).
+        backfillFromActivityThread()
+    }
+
+    /** Public for tests + the helpers' own explicit `setActivity`
+     *  paths (kept for backwards-compat). */
+    fun set(activity: Activity, source: String) {
+        lastActivity = WeakReference(activity)
+        lastPath = source
+    }
+
+    fun current(): Activity? {
+        val live = lastActivity?.get()
+        if (live != null) return live
+        // Last-ditch: try reflection again in case install() ran before
+        // any Activity existed. Cheap if it fails.
+        backfillFromActivityThread()
+        return lastActivity?.get()
+    }
+
+    /**
+     * Best-effort foreground-Activity lookup using non-SDK reflection.
+     * Walks `ActivityThread.sCurrentActivityThread.mActivities` (an
+     * `ArrayMap<IBinder, ActivityClientRecord>`) and finds the record
+     * whose `paused` field is false. This is what Stetho / LeakCanary
+     * / Firebase Performance do, with the same caveat that future
+     * Android versions may break it — failures are silent and the
+     * lifecycle-callbacks path still wins.
+     *
+     * Tagged via `lastPath = "reflection.activityThread"` so the JS
+     * probe can see when reflection had to step in.
+     */
+    @Suppress("PrivateApi", "UNCHECKED_CAST")
+    private fun backfillFromActivityThread() {
+        try {
+            val activityThreadClass = Class.forName("android.app.ActivityThread")
+            val currentActivityThread = activityThreadClass
+                .getDeclaredMethod("currentActivityThread")
+                .also { it.isAccessible = true }
+                .invoke(null) ?: return
+            val activitiesField = activityThreadClass
+                .getDeclaredField("mActivities")
+                .also { it.isAccessible = true }
+            val activities = activitiesField.get(currentActivityThread) ?: return
+
+            // ArrayMap<IBinder, ActivityClientRecord> — iterate via reflection
+            // so we don't have to depend on the (also private) ArrayMap shape.
+            val valuesIter = (activities as? Map<*, *>)?.values?.iterator() ?: return
+            while (valuesIter.hasNext()) {
+                val record = valuesIter.next() ?: continue
+                val recordClass = record.javaClass
+                val pausedField = try {
+                    recordClass.getDeclaredField("paused").also { it.isAccessible = true }
+                } catch (_: NoSuchFieldException) { null }
+                val activityField = try {
+                    recordClass.getDeclaredField("activity").also { it.isAccessible = true }
+                } catch (_: NoSuchFieldException) { null } ?: continue
+                val paused = pausedField?.getBoolean(record) ?: false
+                val candidate = activityField.get(record) as? Activity ?: continue
+                if (!paused && !candidate.isFinishing && !candidate.isDestroyed) {
+                    set(candidate, "reflection.activityThread")
+                    return
+                }
+            }
+        } catch (_: Throwable) {
+            // Reflection unavailable; the lifecycle-callbacks path
+            // will still catch the next foreground transition.
+        }
+    }
+}

package/android/src/main/java/com/sentori/SentoriModule.kt

@@ -39,6 +39,14 @@ class SentoriModule : Module() {
             SentoriReplayCapture.probe()
         }
 
+        // v1.0.0-rc.2 — diagnostic readout for screenshot. Surfaces
+        // foreground-Activity provenance, decor-view state, and the
+        // last failure reason so the JS side can ship raw state back
+        // when screenshot returns null.
+        Function("probeScreenshot") {
+            SentoriScreenshotCapture.probe()
+        }
+
         // v0.9.4 #1 — Mobile Vitals exposure.
         Function("markJsBridgeReady") {
             SentoriMobileVitals.markJsBridgeReady()

package/android/src/main/java/com/sentori/SentoriReplayCapture.kt

@@ -1,7 +1,6 @@
 package com.sentori
 
 import android.app.Activity
-import android.graphics.Rect
 import android.view.View
 import android.view.ViewGroup
 import android.widget.EditText
@@ -9,7 +8,6 @@ import android.widget.ImageView
 import android.widget.TextView
 import org.json.JSONArray
 import org.json.JSONObject
-import java.lang.ref.WeakReference
 
 /**
  * v0.9.6 #2 — wireframe session replay (Android side).
@@ -26,71 +24,88 @@ import java.lang.ref.WeakReference
 object SentoriReplayCapture {
 
     private const val MAX_NODES = 800
-
-    @Volatile private var lastActivity: WeakReference<Activity>? = null
-
-    // v0.9.12 — diagnostic readout so the JS side can ask "why is the
-    // ring empty?" without parsing logcat. Mirrors the iOS side.
+    private const val MAX_DEPTH = 60
+
+    // Diagnostic readouts. Mirrors the iOS side. Surfaced via
+    // `probe()` so JS can answer "why is the ring shallow?" without
+    // parsing logcat.
+    //
+    // v0.9.12: lastPath + lastNodes
+    // v1.0.0-rc.3:
+    //   * lastDepthMax — deepest descendant the walker reached. If
+    //     this stays at 2 or 3 we know the recursion bailed early
+    //     (the rc.2 zero-size-bails-subtree bug).
+    //   * lastSizeBytes — byte length of the serialised payload. ~50
+    //     bytes per node is typical; a 1 KB result with 800 nodes
+    //     would be a red flag.
+    //   * totalTicks / lastEmptyResultTicks — lifetime counters for
+    //     ring health, so a thin-but-non-null capture doesn't slip
+    //     through unnoticed.
     @Volatile private var lastDiagPath: String = "none(not-yet-called)"
     @Volatile private var lastDiagNodes: Int = 0
+    @Volatile private var lastDiagDepthMax: Int = 0
+    @Volatile private var lastDiagSizeBytes: Int = 0
+    @Volatile private var totalTicks: Long = 0
+    @Volatile private var totalEmptyResultTicks: Long = 0
 
     @JvmStatic
     fun probe(): Map<String, Any> {
-        val activity = lastActivity?.get()
+        val activity = SentoriForegroundActivity.current()
         return mapOf(
             "lastPath" to lastDiagPath,
             "lastNodes" to lastDiagNodes,
-            "sceneCount" to if (activity != null) 1 else 0,
-            "windowCount" to (activity?.window?.let { 1 } ?: 0),
+            "lastDepthMax" to lastDiagDepthMax,
+            "lastSizeBytes" to lastDiagSizeBytes,
+            "totalTicks" to totalTicks,
+            "totalEmptyResultTicks" to totalEmptyResultTicks,
+            "trackedSource" to SentoriForegroundActivity.lastPath,
+            "trackedActivity" to (activity?.javaClass?.name ?: "null"),
+            "decorViewFound" to (activity?.window?.decorView != null),
         )
     }
 
+    /** Backwards compat — pre-rc.2 callers that hand-fed an Activity
+     *  through `setActivity` still work; we forward to the shared
+     *  tracker so screenshot + replay both see it. */
     @JvmStatic
     fun setActivity(activity: Activity?) {
-        lastActivity = activity?.let { WeakReference(it) }
+        if (activity != null) SentoriForegroundActivity.set(activity, "manual.setActivity")
     }
 
-    /** Attach an ActivityLifecycleCallbacks so future
-     *  `captureWireframe()` calls know which Activity to walk. */
+    /** Idempotent. Wires the replay helper into the shared tracker;
+     *  kept as a public entrypoint for backwards compat with existing
+     *  call sites. */
     @JvmStatic
     fun register(application: android.app.Application) {
-        application.registerActivityLifecycleCallbacks(object :
-            android.app.Application.ActivityLifecycleCallbacks {
-            override fun onActivityCreated(a: Activity, b: android.os.Bundle?) { setActivity(a) }
-            override fun onActivityStarted(a: Activity) { setActivity(a) }
-            override fun onActivityResumed(a: Activity) { setActivity(a) }
-            override fun onActivityPaused(a: Activity) {}
-            override fun onActivityStopped(a: Activity) {}
-            override fun onActivitySaveInstanceState(a: Activity, b: android.os.Bundle) {}
-            override fun onActivityDestroyed(a: Activity) {}
-        })
+        SentoriForegroundActivity.install(application)
     }
 
     @JvmStatic
     fun captureWireframe(maskedIds: List<String>): String? {
-        val activity = lastActivity?.get()
+        totalTicks++
+        val activity = SentoriForegroundActivity.current()
         if (activity == null) {
             lastDiagPath = "activity.null"
+            totalEmptyResultTicks++
             return null
         }
         val root = activity.window?.decorView
         if (root == null) {
             lastDiagPath = "decorView.null"
+            totalEmptyResultTicks++
             return null
         }
         if (root.width <= 0 || root.height <= 0) {
             lastDiagPath = "root.zero-size"
+            totalEmptyResultTicks++
             return null
         }
 
         val maskedSet = maskedIds.toHashSet()
         val nodes = JSONArray()
-        val rect = Rect()
         val rootLoc = IntArray(2).also { root.getLocationInWindow(it) }
-        walk(root, false, maskedSet, rootLoc, rect, nodes)
-
-        lastDiagPath = "activity.resumed"
-        lastDiagNodes = nodes.length()
+        val ctx = WalkContext(rootLoc = rootLoc, maskedSet = maskedSet)
+        walk(root, depth = 0, parentMasked = false, ctx = ctx, nodes = nodes)
 
         val payload = JSONObject().apply {
             put("ts", System.currentTimeMillis())
@@ -98,77 +113,123 @@ object SentoriReplayCapture {
             put("height", root.height)
             put("nodes", nodes)
         }
-        return payload.toString()
+        val serialised = payload.toString()
+
+        lastDiagPath = "ok(${SentoriForegroundActivity.lastPath})"
+        lastDiagNodes = nodes.length()
+        lastDiagDepthMax = ctx.depthMax
+        lastDiagSizeBytes = serialised.length
+
+        if (nodes.length() == 0) totalEmptyResultTicks++
+
+        return serialised
     }
 
+    /** Per-walk scratch: tracks the deepest descendant reached so
+     *  the probe can surface whether the recursion ran or bailed.
+     *  Bundled into one object to keep the recursive signature
+     *  manageable. */
+    private class WalkContext(
+        val rootLoc: IntArray,
+        val maskedSet: Set<String>,
+        var depthMax: Int = 0,
+    )
+
+    /**
+     * Recursive walker.
+     *
+     * v1.0.0-rc.3 fix: previously this function returned ENTIRELY
+     * when the view itself had `width <= 0 || height <= 0`. That
+     * meant any ViewGroup wrapper that happened to measure to zero
+     * size during the tick (common on Fabric / RN's intermediate
+     * shadow-tree wrappers, and on lazy-layout phases) skipped the
+     * whole descendant subtree — Insight 2026-05-17 verify event
+     * saw 800-node frames whose subtree was actually thousands of
+     * Views deep but only the root + 2-3 wrappers made it into the
+     * JSON.
+     *
+     * Now we separate "emit a node for this view" from "recurse into
+     * its children". A zero-size view doesn't get an emitted node
+     * (no visual contribution) but its descendants still get walked
+     * — they may have real frames.
+     */
     private fun walk(
         view: View,
+        depth: Int,
         parentMasked: Boolean,
-        maskedSet: Set<String>,
-        rootLoc: IntArray,
-        scratch: Rect,
+        ctx: WalkContext,
         nodes: JSONArray,
     ) {
         if (nodes.length() >= MAX_NODES) return
+        if (depth >= MAX_DEPTH) return
         if (view.visibility != View.VISIBLE || view.alpha < 0.01) return
 
+        if (depth > ctx.depthMax) ctx.depthMax = depth
+
         val viewTag = view.tag as? String
-        val isThisMasked = viewTag != null && maskedSet.contains(viewTag)
+        val isThisMasked = viewTag != null && ctx.maskedSet.contains(viewTag)
         val masked = parentMasked || isThisMasked
 
-        val loc = IntArray(2)
-        view.getLocationInWindow(loc)
-        val x = loc[0] - rootLoc[0]
-        val y = loc[1] - rootLoc[1]
         val w = view.width
         val h = view.height
-        if (w <= 0 || h <= 0) return
 
-        val node = JSONObject().apply {
-            put("x", x)
-            put("y", y)
-            put("w", w)
-            put("h", h)
-        }
-
-        var kindEmitted = false
-        when {
-            masked -> {
-                node.put("kind", "mask")
-                kindEmitted = true
-            }
-            view is TextView && !view.text.isNullOrEmpty() -> {
-                node.put("kind", "text")
-                val text = view.text.toString().let { if (it.length > 200) it.substring(0, 200) else it }
-                node.put("text", text)
-                node.put("color", colorToHex(view.currentTextColor))
-                kindEmitted = true
-            }
-            view is EditText -> {
-                node.put("kind", "text")
-                val text = (view.text ?: "").toString().let { if (it.length > 200) it.substring(0, 200) else it }
-                node.put("text", text)
-                kindEmitted = true
+        // Emit a node ONLY when the view has visual extent. A zero-
+        // size view contributes nothing to render but its subtree
+        // might; recurse below regardless.
+        if (w > 0 && h > 0) {
+            val loc = IntArray(2)
+            view.getLocationInWindow(loc)
+            val x = loc[0] - ctx.rootLoc[0]
+            val y = loc[1] - ctx.rootLoc[1]
+
+            val node = JSONObject().apply {
+                put("x", x)
+                put("y", y)
+                put("w", w)
+                put("h", h)
             }
-            view is ImageView -> {
-                node.put("kind", "image")
-                kindEmitted = true
-            }
-            view.background != null -> {
-                node.put("kind", "rect")
-                // Background drawables don't always expose color directly.
-                // Skip color for non-ColorDrawable; renderer falls back to neutral.
-                kindEmitted = true
+
+            var kindEmitted = false
+            when {
+                masked -> {
+                    node.put("kind", "mask")
+                    kindEmitted = true
+                }
+                view is TextView && !view.text.isNullOrEmpty() -> {
+                    node.put("kind", "text")
+                    val text = view.text.toString().let { if (it.length > 200) it.substring(0, 200) else it }
+                    node.put("text", text)
+                    node.put("color", colorToHex(view.currentTextColor))
+                    kindEmitted = true
+                }
+                view is EditText -> {
+                    node.put("kind", "text")
+                    val text = (view.text ?: "").toString().let { if (it.length > 200) it.substring(0, 200) else it }
+                    node.put("text", text)
+                    kindEmitted = true
+                }
+                view is ImageView -> {
+                    node.put("kind", "image")
+                    kindEmitted = true
+                }
+                view.background != null -> {
+                    node.put("kind", "rect")
+                    // Background drawables don't always expose color directly.
+                    // Skip color for non-ColorDrawable; renderer falls back to neutral.
+                    kindEmitted = true
+                }
             }
-        }
 
-        if (kindEmitted) {
-            nodes.put(node)
+            if (kindEmitted) {
+                nodes.put(node)
+            }
         }
 
+        // Always recurse — even zero-size wrappers can host real
+        // descendants (the rc.3 fix).
         if (!masked && view is ViewGroup) {
             for (i in 0 until view.childCount) {
-                walk(view.getChildAt(i), masked, maskedSet, rootLoc, scratch, nodes)
+                walk(view.getChildAt(i), depth + 1, masked, ctx, nodes)
             }
         }
     }

package/android/src/main/java/com/sentori/SentoriScreenshotCapture.kt

@@ -1,13 +1,11 @@
 package com.sentori
 
-import android.app.Activity
 import android.app.Application
 import android.graphics.Bitmap
 import android.graphics.Canvas
 import android.graphics.Color
 import android.graphics.Paint
 import android.os.Build
-import android.os.Bundle
 import android.os.Handler
 import android.os.HandlerThread
 import android.util.Base64
@@ -16,7 +14,6 @@ import android.view.View
 import android.view.ViewGroup
 import android.view.Window
 import java.io.ByteArrayOutputStream
-import java.lang.ref.WeakReference
 import java.util.concurrent.CountDownLatch
 import java.util.concurrent.TimeUnit
 import org.json.JSONArray
@@ -60,36 +57,44 @@ object SentoriScreenshotCapture {
     private const val MAX_NODES = 1500
     private const val PIXEL_COPY_TIMEOUT_MS = 200L
 
-    /// Latest activity we've seen via `ActivityLifecycleCallbacks` —
-    /// used to find the window to screenshot when neither the JS
-    /// side (which knows of `Activity.this` via React Native) nor
-    /// the crash handler hands one to us.
-    @Volatile private var lastActivity: WeakReference<Activity>? = null
+    // v1.0.0-rc.2 — diagnostic readout so the JS side can ask
+    // "why did screenshot return null" without parsing logcat. Mirrors
+    // SentoriReplayCapture.probe() and the iOS Swift probe.
+    @Volatile private var lastDiagPath: String = "none(not-yet-called)"
+    @Volatile private var lastDiagW: Int = 0
+    @Volatile private var lastDiagH: Int = 0
 
     /**
-     * Attach an `ActivityLifecycleCallbacks` so subsequent
-     * `captureScreen()` calls know which Activity (and therefore
-     * Window) to target. Idempotent; call from
-     * `SentoriCrashHandler.register(context)`.
+     * Snapshot of the most recent capture attempt — what code path
+     * resolved an Activity, what the decor view's dimensions were,
+     * and what call source the foreground tracker last saw the
+     * Activity from. Used by `probeNativeScreenshot()` on the JS
+     * side so Insight can ship raw diagnostic state back without
+     * needing logcat access.
+     */
+    @JvmStatic
+    fun probe(): Map<String, Any> {
+        val tracked = SentoriForegroundActivity.current()
+        return mapOf(
+            "lastPath" to lastDiagPath,
+            "lastWidth" to lastDiagW,
+            "lastHeight" to lastDiagH,
+            "trackedSource" to SentoriForegroundActivity.lastPath,
+            "trackedActivity" to (tracked?.javaClass?.name ?: "null"),
+            "decorViewFound" to (tracked?.window?.decorView != null),
+        )
+    }
+
+    /**
+     * Idempotent. Wires the screenshot helper into the shared
+     * foreground-activity tracker; kept as a public entrypoint for
+     * backwards compat with existing call sites (the crash handler
+     * still calls this), but the actual lifecycle subscription lives
+     * in [SentoriForegroundActivity].
      */
     @JvmStatic
     fun register(application: Application) {
-        application.registerActivityLifecycleCallbacks(object :
-            Application.ActivityLifecycleCallbacks {
-            override fun onActivityCreated(a: Activity, b: Bundle?) {
-                lastActivity = WeakReference(a)
-            }
-            override fun onActivityStarted(a: Activity) {
-                lastActivity = WeakReference(a)
-            }
-            override fun onActivityResumed(a: Activity) {
-                lastActivity = WeakReference(a)
-            }
-            override fun onActivityPaused(a: Activity) {}
-            override fun onActivityStopped(a: Activity) {}
-            override fun onActivitySaveInstanceState(a: Activity, b: Bundle) {}
-            override fun onActivityDestroyed(a: Activity) {}
-        })
+        SentoriForegroundActivity.install(application)
     }
 
     /**
@@ -102,8 +107,16 @@ object SentoriScreenshotCapture {
      */
     @JvmStatic
     fun captureKeyWindow(): Map<String, Any>? {
-        val activity = lastActivity?.get() ?: return null
-        val window = activity.window ?: return null
+        val activity = SentoriForegroundActivity.current()
+        if (activity == null) {
+            lastDiagPath = "activity.null"
+            return null
+        }
+        val window = activity.window
+        if (window == null) {
+            lastDiagPath = "window.null"
+            return null
+        }
         val out = mutableMapOf<String, Any>()
         captureScreen(window, emptySet())?.let { (base64, mediaType) ->
             out["screenshot"] = mapOf("base64" to base64, "mediaType" to mediaType)
@@ -120,8 +133,16 @@ object SentoriScreenshotCapture {
     /// masked subview's frame on the captured bitmap.
     @JvmStatic
     fun captureScreenshotWithMask(maskedIds: List<String>): Map<String, String>? {
-        val activity = lastActivity?.get() ?: return null
-        val window = activity.window ?: return null
+        val activity = SentoriForegroundActivity.current()
+        if (activity == null) {
+            lastDiagPath = "activity.null"
+            return null
+        }
+        val window = activity.window
+        if (window == null) {
+            lastDiagPath = "window.null"
+            return null
+        }
         val (base64, mediaType) = captureScreen(window, maskedIds.toHashSet()) ?: return null
         return mapOf("base64" to base64, "mediaType" to mediaType)
     }
@@ -135,12 +156,22 @@ object SentoriScreenshotCapture {
             // requires the activity not to be torn down. Skip for
             // now; v0.6.1 SDK can add the fallback if real-world
             // data shows we have users below API 24.
+            lastDiagPath = "api.unsupported"
+            return null
+        }
+        val decor = window.decorView
+        if (decor == null) {
+            lastDiagPath = "decorView.null"
             return null
         }
-        val decor = window.decorView ?: return null
         val w = decor.width
         val h = decor.height
-        if (w <= 0 || h <= 0) return null
+        lastDiagW = w
+        lastDiagH = h
+        if (w <= 0 || h <= 0) {
+            lastDiagPath = "decorView.zero-size"
+            return null
+        }
 
         // Long-edge scale.
         val longEdge = maxOf(w, h).toFloat()
@@ -175,12 +206,17 @@ object SentoriScreenshotCapture {
                 )
             }
             latch.await(PIXEL_COPY_TIMEOUT_MS, TimeUnit.MILLISECONDS)
-        } catch (_: Throwable) {
+        } catch (t: Throwable) {
+            lastDiagPath = "pixelCopy.threw:${t.javaClass.simpleName}"
             return null
         } finally {
             handlerThread.quitSafely()
         }
-        if (!success) return null
+        if (!success) {
+            lastDiagPath = "pixelCopy.notSuccess"
+            return null
+        }
+        lastDiagPath = "ok"
 
         // v0.7.3 — paint black rectangles over masked subviews on the
         // already-captured bitmap. We get window-relative coordinates

package/ios/SentoriModule.swift

@@ -38,6 +38,13 @@ public class SentoriModule: Module {
             return SentoriReplayCapture.probe()
         }
 
+        // v1.0.0-rc.2 — diagnostic readout for screenshot. Same shape
+        // as Android side; lets Insight ship raw state back when the
+        // captureScreenshot path returns null.
+        Function("probeScreenshot") { () -> [String: Any] in
+            return SentoriScreenshotCapture.probe()
+        }
+
         // v0.9.4 #1 — Mobile Vitals exposure.
         Function("markJsBridgeReady") {
             SentoriMobileVitals.markJsBridgeReady()