@scalebun/react-native 1.0.0 → 1.0.2

package/android/src/main/java/com/scalebun/replaysdk/capture/FrameCaptureManager.kt

@@ -1,508 +1,508 @@
-package com.scalebun.replaysdk.capture
-
-import android.app.Activity
-import android.graphics.Bitmap
-import android.graphics.Canvas
-import android.graphics.Color
-import android.graphics.ColorMatrix
-import android.graphics.ColorMatrixColorFilter
-import android.graphics.Paint
-import android.os.Build
-import android.os.Handler
-import android.os.HandlerThread
-import android.os.Looper
-import android.view.PixelCopy
-import android.view.View
-import com.scalebun.replaysdk.core.*
-import com.scalebun.replaysdk.models.ReplayFrame
-import java.io.ByteArrayOutputStream
-import java.util.concurrent.atomic.AtomicInteger
-import android.util.Base64
-
-/**
- * Android Frame Capture Manager
- *
- * Captures screenshots from the current Activity's decor view.
- * Uses PixelCopy API (API 26+) as primary, Canvas.draw as fallback.
- *
- * Performance considerations:
- * - Captures run on a dedicated background thread
- * - Bitmap allocation is reused where possible
- * - Compression happens off the main thread
- * - Throttling prevents excessive captures
- */
-class FrameCaptureManager(private var config: ReplayConfig) {
-
-    private val sequenceCounter = AtomicInteger(0)
-    private val captureThread = HandlerThread("ReplaySdk-Capture").also { it.start() }
-    private val captureHandler = Handler(captureThread.looper)
-    private val mainHandler = Handler(Looper.getMainLooper())
-
-    // Stability-aware scheduling. capture() remains the low-level primitive;
-    // scheduleCapture() is the stability-gated, debounced, coalesced entry point.
-    private val stabilityDetector = UiStabilityDetector(mainHandler)
-    private val scheduler = FrameCaptureScheduler(
-        stability = stabilityDetector,
-        resolveView = { activity -> resolveCaptureView(activity) },
-        performCapture = { req, cb ->
-            val act = req.activityRef.get()
-            if (act == null) cb(null)
-            else capture(act, req.sessionId, req.screenName, req.trigger, req.cfg, cb)
-        },
-        mainHandler = mainHandler
-    )
-
-    // Frequency timer
-    private var frequencyHandler: Handler? = null
-    private var frequencyRunnable: Runnable? = null
-
-    val frameCount: Int get() = sequenceCounter.get()
-
-    fun reset() {
-        sequenceCounter.set(0)
-        scheduler.reset()
-    }
-
-    /**
-     * Stability-aware capture entry point. Debounces/coalesces requests and waits
-     * for a stable draw state before snapshotting, so navigation/loading frames
-     * are not half-rendered.
-     *
-     * @param onPersist invoked for every produced frame (incl. late-content
-     *                  follow-ups) — persist + timeline + JS event belong here.
-     * @param onFrame   one-shot reply for the originating request (bridge promise).
-     */
-    fun scheduleCapture(
-        activity: Activity,
-        sessionId: String,
-        screenName: String,
-        trigger: String,
-        cfg: ReplayConfig,
-        onPersist: (ReplayFrame) -> Unit,
-        onFrame: (ReplayFrame?) -> Unit
-    ) {
-        val reason = CaptureReason.fromTrigger(trigger)
-        val req = FrameCaptureScheduler.FrameRequest(
-            activityRef = java.lang.ref.WeakReference(activity),
-            sessionId = sessionId,
-            screenName = screenName,
-            reason = reason,
-            trigger = trigger,
-            cfg = cfg,
-            onPersist = onPersist
-        )
-        scheduler.request(req, onFrame)
-    }
-
-    /**
-     * Resolve the capture view (app content area below the status bar). Its
-     * coordinate space matches the InteractionTracker normalization base, so
-     * touch markers map directly to screenshot pixels.
-     */
-    private fun resolveCaptureView(activity: Activity): View? = try {
-        activity.window?.decorView?.rootView
-            ?.findViewById<View>(android.R.id.content)
-            ?.takeIf { it.width > 0 && it.height > 0 }
-    } catch (e: Exception) {
-        ReplayLogger.warn("Cannot access capture view: ${e.message}")
-        null
-    }
-
-    fun updateConfig(newConfig: ReplayConfig) {
-        config = newConfig
-    }
-
-    /**
-     * Capture a screenshot from the given Activity.
-     * Runs processing on background thread, delivers result on main thread.
-     */
-    fun capture(
-        activity: Activity,
-        sessionId: String,
-        screenName: String,
-        trigger: String,
-        cfg: ReplayConfig,
-        callback: (ReplayFrame?) -> Unit
-    ) {
-        // Timing/throttling is owned by FrameCaptureScheduler. capture() is the
-        // unconditional primitive: it snapshots whatever is on screen right now.
-        //
-        // Use R.id.content ONLY — the app content area below the status bar.
-        // Its coordinate space matches the InteractionTracker's normalization base
-        // exactly, so normalizedX/Y maps directly to screenshot pixels.
-        // NEVER fall back to decorView — decorView includes status bar / nav bar
-        // area, producing a screenshot with different dimensions than the touch
-        // normalization base, which shifts markers upward by ~status-bar fraction.
-        val captureView: View = resolveCaptureView(activity) ?: run {
-            ReplayLogger.warn("Cannot access R.id.content — skipping capture")
-            callback(null)
-            return
-        }
-
-        if (captureView.width <= 0 || captureView.height <= 0) {
-            ReplayLogger.debug("Capture view not ready (zero dimensions)")
-            callback(null)
-            return
-        }
-
-        // Calculate scaled dimensions
-        val scale = cfg.maxWidth.toFloat() / captureView.width.toFloat()
-        val targetWidth = cfg.maxWidth.coerceAtMost(captureView.width)
-        val targetHeight = Math.round(captureView.height * scale).coerceAtLeast(1)
-
-        acquireBitmap(
-            activity, captureView,
-            onBitmap = { bmp -> compressAndEmit(bmp, targetWidth, targetHeight, sessionId, screenName, trigger, cfg, callback) },
-            onFail = { callback(null) }
-        )
-    }
-
-    /**
-     * Capture-to-file path for the native outbox. Captures, applies privacy masking on
-     * the full-resolution bitmap, encodes to image bytes, and hands (metadata, bytes)
-     * to the sink. NO base64 is produced — the raw encoded bytes are written straight
-     * to the outbox file by the caller, so image bytes never cross the JS bridge.
-     */
-    fun captureToFile(
-        activity: Activity,
-        sessionId: String,
-        screenName: String,
-        trigger: String,
-        cfg: ReplayConfig,
-        sink: (ReplayFrame?, ByteArray?) -> Unit
-    ) {
-        val captureView: View = resolveCaptureView(activity) ?: run {
-            ReplayLogger.warn("captureToFile: cannot access R.id.content")
-            sink(null, null); return
-        }
-        if (captureView.width <= 0 || captureView.height <= 0) { sink(null, null); return }
-
-        val scale = cfg.maxWidth.toFloat() / captureView.width.toFloat()
-        val targetWidth = cfg.maxWidth.coerceAtMost(captureView.width)
-        val targetHeight = Math.round(captureView.height * scale).coerceAtLeast(1)
-
-        acquireBitmap(
-            activity, captureView,
-            onBitmap = { bmp ->
-                // Mask on the full-res bitmap (rects are computed in that coordinate
-                // space; scaling happens afterwards inside compressToBytes). FAIL CLOSED:
-                // if the masking step throws, the frame is DISCARDED — never persisted
-                // unmasked, never persisted with a falsely-true masked flag (section 3).
-                val masked = applyMaskSafe(bmp, captureView, cfg)
-                if (masked == null) {
-                    com.scalebun.replaysdk.outbox.NativeOutbox.maskFailureDropCount.incrementAndGet()
-                    ReplayLogger.warn("captureToFile: masking failed — frame dropped (fail-closed)")
-                    if (!bmp.isRecycled) bmp.recycle()
-                    sink(null, null); return@acquireBitmap
-                }
-                compressToBytes(masked, targetWidth, targetHeight, sessionId, screenName, trigger, cfg, sink)
-            },
-            onFail = { sink(null, null) }
-        )
-    }
-
-    /** Shared capture dispatch: produce a composited bitmap, deliver on the main thread. */
-    private fun acquireBitmap(
-        activity: Activity,
-        captureView: View,
-        onBitmap: (Bitmap) -> Unit,
-        onFail: () -> Unit
-    ) {
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-            captureWithPixelCopy(activity, captureView, onBitmap, onFail)
-        } else {
-            captureWithCanvas(captureView, onBitmap, onFail)
-        }
-    }
-
-    /**
-     * Apply privacy masking; recycle the input if a masked copy was produced. Returns
-     * null if the masking step throws — the caller MUST discard the frame (fail-closed),
-     * because we cannot prove the on-disk bytes are masked. Never returns the unmasked
-     * input on failure.
-     */
-    private fun applyMaskSafe(bitmap: Bitmap, captureView: View, cfg: ReplayConfig): Bitmap? = try {
-        val out = com.scalebun.replaysdk.privacy.PrivacyMaskProcessor.applyMasking(bitmap, captureView, cfg)
-        if (out !== bitmap) bitmap.recycle()
-        out
-    } catch (e: Exception) {
-        ReplayLogger.warn("Masking threw — dropping frame (fail-closed): ${e.message}")
-        null
-    }
-
-    private fun captureWithPixelCopy(
-        activity: Activity,
-        captureView: View,
-        onBitmap: (Bitmap) -> Unit,
-        onFail: () -> Unit
-    ) {
-        val bitmap = Bitmap.createBitmap(captureView.width, captureView.height, Bitmap.Config.ARGB_8888)
-
-        try {
-            val window = activity.window ?: run {
-                bitmap.recycle()
-                onFail()
-                return
-            }
-
-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-                // PixelCopy captures the full window but we clip to captureView bounds.
-                // Compute captureView's position within the window.
-                val loc = IntArray(2)
-                captureView.getLocationInWindow(loc)
-                val srcRect = android.graphics.Rect(
-                    loc[0], loc[1],
-                    loc[0] + captureView.width,
-                    loc[1] + captureView.height
-                )
-
-                PixelCopy.request(window, srcRect, bitmap, { result ->
-                    if (result == PixelCopy.SUCCESS) {
-                        mainHandler.post {
-                            compositeExtraWindows(bitmap, captureView)
-                            onBitmap(bitmap)
-                        }
-                    } else {
-                        ReplayLogger.warn("PixelCopy failed with code: $result, falling back to Canvas")
-                        bitmap.recycle()
-                        mainHandler.post {
-                            captureWithCanvas(captureView, onBitmap, onFail)
-                        }
-                    }
-                }, captureHandler)
-            }
-        } catch (e: Exception) {
-            ReplayLogger.error("PixelCopy error: ${e.message}", e)
-            bitmap.recycle()
-            onFail()
-        }
-    }
-
-    private fun captureWithCanvas(
-        captureView: View,
-        onBitmap: (Bitmap) -> Unit,
-        onFail: () -> Unit
-    ) {
-        try {
-            val bitmap = Bitmap.createBitmap(captureView.width, captureView.height, Bitmap.Config.ARGB_8888)
-            val canvas = Canvas(bitmap)
-            captureView.draw(canvas)
-            compositeExtraWindows(bitmap, captureView)
-            onBitmap(bitmap)
-        } catch (e: Exception) {
-            ReplayLogger.error("Canvas capture error: ${e.message}", e)
-            onFail()
-        }
-    }
-
-    /**
-     * Draw any extra windows (like Dialogs/Alerts) over the base bitmap.
-     * MUST be called on the main UI thread.
-     */
-    private fun compositeExtraWindows(baseBitmap: Bitmap, captureView: View) {
-        try {
-            val canvas = Canvas(baseBitmap)
-            val contentLoc = IntArray(2)
-            captureView.getLocationOnScreen(contentLoc)
-
-            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
-
-            for (view in views) {
-                if (view === captureView.rootView) continue
-                
-                if (view.visibility != View.VISIBLE || view.windowToken == null || view.width <= 0 || view.height <= 0) continue
-
-                val lp = view.layoutParams as? android.view.WindowManager.LayoutParams
-                if (lp != null && (lp.flags and android.view.WindowManager.LayoutParams.FLAG_SECURE) != 0) {
-                    continue
-                }
-
-                val loc = IntArray(2)
-                view.getLocationOnScreen(loc)
-
-                canvas.save()
-                canvas.translate((loc[0] - contentLoc[0]).toFloat(), (loc[1] - contentLoc[1]).toFloat())
-                view.draw(canvas)
-                canvas.restore()
-            }
-        } catch (e: Exception) {
-            ReplayLogger.warn("Failed to composite extra windows: ${e.message}")
-        }
-    }
-
-    /**
-     * Scale, optionally grayscale, compress, and emit the frame.
-     * Runs on background capture thread.
-     */
-    private fun compressAndEmit(
-        originalBitmap: Bitmap,
-        targetWidth: Int,
-        targetHeight: Int,
-        sessionId: String,
-        screenName: String,
-        trigger: String,
-        cfg: ReplayConfig,
-        callback: (ReplayFrame?) -> Unit
-    ) {
-        captureHandler.post {
-            try {
-                // Scale
-                var bitmap = Bitmap.createScaledBitmap(originalBitmap, targetWidth, targetHeight, true)
-                if (bitmap !== originalBitmap) originalBitmap.recycle()
-
-                // Apply grayscale if needed
-                if (cfg.screenshotQuality == ScreenshotQuality.GRAYSCALE) {
-                    val grayscale = Bitmap.createBitmap(bitmap.width, bitmap.height, Bitmap.Config.ARGB_8888)
-                    val canvas = Canvas(grayscale)
-                    val paint = Paint()
-                    val cm = ColorMatrix()
-                    cm.setSaturation(0f)
-                    paint.colorFilter = ColorMatrixColorFilter(cm)
-                    canvas.drawBitmap(bitmap, 0f, 0f, paint)
-                    bitmap.recycle()
-                    bitmap = grayscale
-                }
-
-                // Compress — P2-2 format fallback chain: AVIF -> WebP -> JPEG.
-                // NOTE: Android's Bitmap.CompressFormat has NO AVIF encoder (only
-                // JPEG/PNG/WEBP*). On-device AVIF encode would need a separate AV1
-                // encoder (MediaCodec/libaom) which is not bundled here. So a request
-                // for "avif" TRUTHFULLY falls back to WebP (API 30+) then JPEG, and we
-                // report the format we ACTUALLY produced — never claim avif we can't make.
-                val outputStream = ByteArrayOutputStream()
-                val wantsModern = cfg.format == "avif" || cfg.format == "webp"
-                val useWebp = wantsModern && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
-                val format = if (useWebp) Bitmap.CompressFormat.WEBP_LOSSY else Bitmap.CompressFormat.JPEG
-                bitmap.compress(format, cfg.jpegQuality, outputStream)
-                val bytes = outputStream.toByteArray()
-                val base64 = Base64.encodeToString(bytes, Base64.NO_WRAP)
-                val actualFormat = if (format == Bitmap.CompressFormat.JPEG) "jpeg" else "webp"
-
-                val seq = sequenceCounter.incrementAndGet()
-                val frame = ReplayFrame(
-                    frameId = SessionIdGenerator.frameId(),
-                    sessionId = sessionId,
-                    timestamp = System.currentTimeMillis(),
-                    sequenceNumber = seq,
-                    screenName = screenName,
-                    trigger = trigger,
-                    format = actualFormat,
-                    sizeBytes = bytes.size,
-                    width = bitmap.width,
-                    height = bitmap.height,
-                    quality = cfg.screenshotQuality.value,
-                    masked = cfg.maskTextInputs || cfg.maskImages,
-                    base64 = base64
-                )
-
-                bitmap.recycle()
-
-                // Deliver on main thread
-                mainHandler.post { callback(frame) }
-
-            } catch (e: Exception) {
-                ReplayLogger.error("Compress/emit error: ${e.message}", e)
-                mainHandler.post { callback(null) }
-            }
-        }
-    }
-
-    /**
-     * Scale, optionally grayscale, compress to image bytes (NO base64) and hand
-     * (frame metadata, bytes) to the sink. Runs on the background capture thread.
-     */
-    private fun compressToBytes(
-        originalBitmap: Bitmap,
-        targetWidth: Int,
-        targetHeight: Int,
-        sessionId: String,
-        screenName: String,
-        trigger: String,
-        cfg: ReplayConfig,
-        sink: (ReplayFrame?, ByteArray?) -> Unit
-    ) {
-        captureHandler.post {
-            try {
-                var bitmap = Bitmap.createScaledBitmap(originalBitmap, targetWidth, targetHeight, true)
-                if (bitmap !== originalBitmap) originalBitmap.recycle()
-
-                if (cfg.screenshotQuality == ScreenshotQuality.GRAYSCALE) {
-                    val grayscale = Bitmap.createBitmap(bitmap.width, bitmap.height, Bitmap.Config.ARGB_8888)
-                    val canvas = Canvas(grayscale)
-                    val paint = Paint()
-                    val cm = ColorMatrix()
-                    cm.setSaturation(0f)
-                    paint.colorFilter = ColorMatrixColorFilter(cm)
-                    canvas.drawBitmap(bitmap, 0f, 0f, paint)
-                    bitmap.recycle()
-                    bitmap = grayscale
-                }
-
-                val outputStream = ByteArrayOutputStream()
-                val wantsModern = cfg.format == "avif" || cfg.format == "webp"
-                val useWebp = wantsModern && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
-                val format = if (useWebp) Bitmap.CompressFormat.WEBP_LOSSY else Bitmap.CompressFormat.JPEG
-                bitmap.compress(format, cfg.jpegQuality, outputStream)
-                val bytes = outputStream.toByteArray()
-                val actualFormat = if (format == Bitmap.CompressFormat.JPEG) "jpeg" else "webp"
-
-                val seq = sequenceCounter.incrementAndGet()
-                val maskApplied = cfg.maskTextInputs || cfg.maskImages || cfg.maskedElementIds.isNotEmpty()
-                val frame = ReplayFrame(
-                    frameId = SessionIdGenerator.frameId(),
-                    sessionId = sessionId,
-                    timestamp = System.currentTimeMillis(),
-                    sequenceNumber = seq,
-                    screenName = screenName,
-                    trigger = trigger,
-                    format = actualFormat,
-                    sizeBytes = bytes.size,
-                    width = bitmap.width,
-                    height = bitmap.height,
-                    quality = cfg.screenshotQuality.value,
-                    masked = maskApplied,
-                    base64 = null
-                )
-                bitmap.recycle()
-                mainHandler.post { sink(frame, bytes) }
-            } catch (e: Exception) {
-                ReplayLogger.error("compressToBytes error: ${e.message}", e)
-                mainHandler.post { sink(null, null) }
-            }
-        }
-    }
-
-    // ─── Frequency Timer ────────────────────────────────────────────────
-
-    fun startFrequencyTimer(intervalMs: Long, capture: (Activity?) -> Unit) {
-        stopFrequencyTimer()
-        frequencyHandler = Handler(Looper.getMainLooper())
-        frequencyRunnable = object : Runnable {
-            override fun run() {
-                capture(null) // Caller must provide current activity
-                frequencyHandler?.postDelayed(this, intervalMs)
-            }
-        }
-        frequencyHandler?.postDelayed(frequencyRunnable!!, intervalMs)
-    }
-
-    fun stopFrequencyTimer() {
-        frequencyRunnable?.let { frequencyHandler?.removeCallbacks(it) }
-        frequencyRunnable = null
-        frequencyHandler = null
-    }
-
-    // ─── Cleanup ────────────────────────────────────────────────────────
-
-    fun destroy() {
-        stopFrequencyTimer()
-        scheduler.reset()
-        captureThread.quitSafely()
-    }
-}
+package com.scalebun.replaysdk.capture
+
+import android.app.Activity
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.ColorMatrix
+import android.graphics.ColorMatrixColorFilter
+import android.graphics.Paint
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.os.Looper
+import android.view.PixelCopy
+import android.view.View
+import com.scalebun.replaysdk.core.*
+import com.scalebun.replaysdk.models.ReplayFrame
+import java.io.ByteArrayOutputStream
+import java.util.concurrent.atomic.AtomicInteger
+import android.util.Base64
+
+/**
+ * Android Frame Capture Manager
+ *
+ * Captures screenshots from the current Activity's decor view.
+ * Uses PixelCopy API (API 26+) as primary, Canvas.draw as fallback.
+ *
+ * Performance considerations:
+ * - Captures run on a dedicated background thread
+ * - Bitmap allocation is reused where possible
+ * - Compression happens off the main thread
+ * - Throttling prevents excessive captures
+ */
+class FrameCaptureManager(private var config: ReplayConfig) {
+
+    private val sequenceCounter = AtomicInteger(0)
+    private val captureThread = HandlerThread("ReplaySdk-Capture").also { it.start() }
+    private val captureHandler = Handler(captureThread.looper)
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    // Stability-aware scheduling. capture() remains the low-level primitive;
+    // scheduleCapture() is the stability-gated, debounced, coalesced entry point.
+    private val stabilityDetector = UiStabilityDetector(mainHandler)
+    private val scheduler = FrameCaptureScheduler(
+        stability = stabilityDetector,
+        resolveView = { activity -> resolveCaptureView(activity) },
+        performCapture = { req, cb ->
+            val act = req.activityRef.get()
+            if (act == null) cb(null)
+            else capture(act, req.sessionId, req.screenName, req.trigger, req.cfg, cb)
+        },
+        mainHandler = mainHandler
+    )
+
+    // Frequency timer
+    private var frequencyHandler: Handler? = null
+    private var frequencyRunnable: Runnable? = null
+
+    val frameCount: Int get() = sequenceCounter.get()
+
+    fun reset() {
+        sequenceCounter.set(0)
+        scheduler.reset()
+    }
+
+    /**
+     * Stability-aware capture entry point. Debounces/coalesces requests and waits
+     * for a stable draw state before snapshotting, so navigation/loading frames
+     * are not half-rendered.
+     *
+     * @param onPersist invoked for every produced frame (incl. late-content
+     *                  follow-ups) — persist + timeline + JS event belong here.
+     * @param onFrame   one-shot reply for the originating request (bridge promise).
+     */
+    fun scheduleCapture(
+        activity: Activity,
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        cfg: ReplayConfig,
+        onPersist: (ReplayFrame) -> Unit,
+        onFrame: (ReplayFrame?) -> Unit
+    ) {
+        val reason = CaptureReason.fromTrigger(trigger)
+        val req = FrameCaptureScheduler.FrameRequest(
+            activityRef = java.lang.ref.WeakReference(activity),
+            sessionId = sessionId,
+            screenName = screenName,
+            reason = reason,
+            trigger = trigger,
+            cfg = cfg,
+            onPersist = onPersist
+        )
+        scheduler.request(req, onFrame)
+    }
+
+    /**
+     * Resolve the capture view (app content area below the status bar). Its
+     * coordinate space matches the InteractionTracker normalization base, so
+     * touch markers map directly to screenshot pixels.
+     */
+    private fun resolveCaptureView(activity: Activity): View? = try {
+        activity.window?.decorView?.rootView
+            ?.findViewById<View>(android.R.id.content)
+            ?.takeIf { it.width > 0 && it.height > 0 }
+    } catch (e: Exception) {
+        ReplayLogger.warn("Cannot access capture view: ${e.message}")
+        null
+    }
+
+    fun updateConfig(newConfig: ReplayConfig) {
+        config = newConfig
+    }
+
+    /**
+     * Capture a screenshot from the given Activity.
+     * Runs processing on background thread, delivers result on main thread.
+     */
+    fun capture(
+        activity: Activity,
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        cfg: ReplayConfig,
+        callback: (ReplayFrame?) -> Unit
+    ) {
+        // Timing/throttling is owned by FrameCaptureScheduler. capture() is the
+        // unconditional primitive: it snapshots whatever is on screen right now.
+        //
+        // Use R.id.content ONLY — the app content area below the status bar.
+        // Its coordinate space matches the InteractionTracker's normalization base
+        // exactly, so normalizedX/Y maps directly to screenshot pixels.
+        // NEVER fall back to decorView — decorView includes status bar / nav bar
+        // area, producing a screenshot with different dimensions than the touch
+        // normalization base, which shifts markers upward by ~status-bar fraction.
+        val captureView: View = resolveCaptureView(activity) ?: run {
+            ReplayLogger.warn("Cannot access R.id.content — skipping capture")
+            callback(null)
+            return
+        }
+
+        if (captureView.width <= 0 || captureView.height <= 0) {
+            ReplayLogger.debug("Capture view not ready (zero dimensions)")
+            callback(null)
+            return
+        }
+
+        // Calculate scaled dimensions
+        val scale = cfg.maxWidth.toFloat() / captureView.width.toFloat()
+        val targetWidth = cfg.maxWidth.coerceAtMost(captureView.width)
+        val targetHeight = Math.round(captureView.height * scale).coerceAtLeast(1)
+
+        acquireBitmap(
+            activity, captureView,
+            onBitmap = { bmp -> compressAndEmit(bmp, targetWidth, targetHeight, sessionId, screenName, trigger, cfg, callback) },
+            onFail = { callback(null) }
+        )
+    }
+
+    /**
+     * Capture-to-file path for the native outbox. Captures, applies privacy masking on
+     * the full-resolution bitmap, encodes to image bytes, and hands (metadata, bytes)
+     * to the sink. NO base64 is produced — the raw encoded bytes are written straight
+     * to the outbox file by the caller, so image bytes never cross the JS bridge.
+     */
+    fun captureToFile(
+        activity: Activity,
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        cfg: ReplayConfig,
+        sink: (ReplayFrame?, ByteArray?) -> Unit
+    ) {
+        val captureView: View = resolveCaptureView(activity) ?: run {
+            ReplayLogger.warn("captureToFile: cannot access R.id.content")
+            sink(null, null); return
+        }
+        if (captureView.width <= 0 || captureView.height <= 0) { sink(null, null); return }
+
+        val scale = cfg.maxWidth.toFloat() / captureView.width.toFloat()
+        val targetWidth = cfg.maxWidth.coerceAtMost(captureView.width)
+        val targetHeight = Math.round(captureView.height * scale).coerceAtLeast(1)
+
+        acquireBitmap(
+            activity, captureView,
+            onBitmap = { bmp ->
+                // Mask on the full-res bitmap (rects are computed in that coordinate
+                // space; scaling happens afterwards inside compressToBytes). FAIL CLOSED:
+                // if the masking step throws, the frame is DISCARDED — never persisted
+                // unmasked, never persisted with a falsely-true masked flag (section 3).
+                val masked = applyMaskSafe(bmp, captureView, cfg)
+                if (masked == null) {
+                    com.scalebun.replaysdk.outbox.NativeOutbox.maskFailureDropCount.incrementAndGet()
+                    ReplayLogger.warn("captureToFile: masking failed — frame dropped (fail-closed)")
+                    if (!bmp.isRecycled) bmp.recycle()
+                    sink(null, null); return@acquireBitmap
+                }
+                compressToBytes(masked, targetWidth, targetHeight, sessionId, screenName, trigger, cfg, sink)
+            },
+            onFail = { sink(null, null) }
+        )
+    }
+
+    /** Shared capture dispatch: produce a composited bitmap, deliver on the main thread. */
+    private fun acquireBitmap(
+        activity: Activity,
+        captureView: View,
+        onBitmap: (Bitmap) -> Unit,
+        onFail: () -> Unit
+    ) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            captureWithPixelCopy(activity, captureView, onBitmap, onFail)
+        } else {
+            captureWithCanvas(captureView, onBitmap, onFail)
+        }
+    }
+
+    /**
+     * Apply privacy masking; recycle the input if a masked copy was produced. Returns
+     * null if the masking step throws — the caller MUST discard the frame (fail-closed),
+     * because we cannot prove the on-disk bytes are masked. Never returns the unmasked
+     * input on failure.
+     */
+    private fun applyMaskSafe(bitmap: Bitmap, captureView: View, cfg: ReplayConfig): Bitmap? = try {
+        val out = com.scalebun.replaysdk.privacy.PrivacyMaskProcessor.applyMasking(bitmap, captureView, cfg)
+        if (out !== bitmap) bitmap.recycle()
+        out
+    } catch (e: Exception) {
+        ReplayLogger.warn("Masking threw — dropping frame (fail-closed): ${e.message}")
+        null
+    }
+
+    private fun captureWithPixelCopy(
+        activity: Activity,
+        captureView: View,
+        onBitmap: (Bitmap) -> Unit,
+        onFail: () -> Unit
+    ) {
+        val bitmap = Bitmap.createBitmap(captureView.width, captureView.height, Bitmap.Config.ARGB_8888)
+
+        try {
+            val window = activity.window ?: run {
+                bitmap.recycle()
+                onFail()
+                return
+            }
+
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                // PixelCopy captures the full window but we clip to captureView bounds.
+                // Compute captureView's position within the window.
+                val loc = IntArray(2)
+                captureView.getLocationInWindow(loc)
+                val srcRect = android.graphics.Rect(
+                    loc[0], loc[1],
+                    loc[0] + captureView.width,
+                    loc[1] + captureView.height
+                )
+
+                PixelCopy.request(window, srcRect, bitmap, { result ->
+                    if (result == PixelCopy.SUCCESS) {
+                        mainHandler.post {
+                            compositeExtraWindows(bitmap, captureView)
+                            onBitmap(bitmap)
+                        }
+                    } else {
+                        ReplayLogger.warn("PixelCopy failed with code: $result, falling back to Canvas")
+                        bitmap.recycle()
+                        mainHandler.post {
+                            captureWithCanvas(captureView, onBitmap, onFail)
+                        }
+                    }
+                }, captureHandler)
+            }
+        } catch (e: Exception) {
+            ReplayLogger.error("PixelCopy error: ${e.message}", e)
+            bitmap.recycle()
+            onFail()
+        }
+    }
+
+    private fun captureWithCanvas(
+        captureView: View,
+        onBitmap: (Bitmap) -> Unit,
+        onFail: () -> Unit
+    ) {
+        try {
+            val bitmap = Bitmap.createBitmap(captureView.width, captureView.height, Bitmap.Config.ARGB_8888)
+            val canvas = Canvas(bitmap)
+            captureView.draw(canvas)
+            compositeExtraWindows(bitmap, captureView)
+            onBitmap(bitmap)
+        } catch (e: Exception) {
+            ReplayLogger.error("Canvas capture error: ${e.message}", e)
+            onFail()
+        }
+    }
+
+    /**
+     * Draw any extra windows (like Dialogs/Alerts) over the base bitmap.
+     * MUST be called on the main UI thread.
+     */
+    private fun compositeExtraWindows(baseBitmap: Bitmap, captureView: View) {
+        try {
+            val canvas = Canvas(baseBitmap)
+            val contentLoc = IntArray(2)
+            captureView.getLocationOnScreen(contentLoc)
+
+            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
+
+            for (view in views) {
+                if (view === captureView.rootView) continue
+                
+                if (view.visibility != View.VISIBLE || view.windowToken == null || view.width <= 0 || view.height <= 0) continue
+
+                val lp = view.layoutParams as? android.view.WindowManager.LayoutParams
+                if (lp != null && (lp.flags and android.view.WindowManager.LayoutParams.FLAG_SECURE) != 0) {
+                    continue
+                }
+
+                val loc = IntArray(2)
+                view.getLocationOnScreen(loc)
+
+                canvas.save()
+                canvas.translate((loc[0] - contentLoc[0]).toFloat(), (loc[1] - contentLoc[1]).toFloat())
+                view.draw(canvas)
+                canvas.restore()
+            }
+        } catch (e: Exception) {
+            ReplayLogger.warn("Failed to composite extra windows: ${e.message}")
+        }
+    }
+
+    /**
+     * Scale, optionally grayscale, compress, and emit the frame.
+     * Runs on background capture thread.
+     */
+    private fun compressAndEmit(
+        originalBitmap: Bitmap,
+        targetWidth: Int,
+        targetHeight: Int,
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        cfg: ReplayConfig,
+        callback: (ReplayFrame?) -> Unit
+    ) {
+        captureHandler.post {
+            try {
+                // Scale
+                var bitmap = Bitmap.createScaledBitmap(originalBitmap, targetWidth, targetHeight, true)
+                if (bitmap !== originalBitmap) originalBitmap.recycle()
+
+                // Apply grayscale if needed
+                if (cfg.screenshotQuality == ScreenshotQuality.GRAYSCALE) {
+                    val grayscale = Bitmap.createBitmap(bitmap.width, bitmap.height, Bitmap.Config.ARGB_8888)
+                    val canvas = Canvas(grayscale)
+                    val paint = Paint()
+                    val cm = ColorMatrix()
+                    cm.setSaturation(0f)
+                    paint.colorFilter = ColorMatrixColorFilter(cm)
+                    canvas.drawBitmap(bitmap, 0f, 0f, paint)
+                    bitmap.recycle()
+                    bitmap = grayscale
+                }
+
+                // Compress — P2-2 format fallback chain: AVIF -> WebP -> JPEG.
+                // NOTE: Android's Bitmap.CompressFormat has NO AVIF encoder (only
+                // JPEG/PNG/WEBP*). On-device AVIF encode would need a separate AV1
+                // encoder (MediaCodec/libaom) which is not bundled here. So a request
+                // for "avif" TRUTHFULLY falls back to WebP (API 30+) then JPEG, and we
+                // report the format we ACTUALLY produced — never claim avif we can't make.
+                val outputStream = ByteArrayOutputStream()
+                val wantsModern = cfg.format == "avif" || cfg.format == "webp"
+                val useWebp = wantsModern && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
+                val format = if (useWebp) Bitmap.CompressFormat.WEBP_LOSSY else Bitmap.CompressFormat.JPEG
+                bitmap.compress(format, cfg.jpegQuality, outputStream)
+                val bytes = outputStream.toByteArray()
+                val base64 = Base64.encodeToString(bytes, Base64.NO_WRAP)
+                val actualFormat = if (format == Bitmap.CompressFormat.JPEG) "jpeg" else "webp"
+
+                val seq = sequenceCounter.incrementAndGet()
+                val frame = ReplayFrame(
+                    frameId = SessionIdGenerator.frameId(),
+                    sessionId = sessionId,
+                    timestamp = System.currentTimeMillis(),
+                    sequenceNumber = seq,
+                    screenName = screenName,
+                    trigger = trigger,
+                    format = actualFormat,
+                    sizeBytes = bytes.size,
+                    width = bitmap.width,
+                    height = bitmap.height,
+                    quality = cfg.screenshotQuality.value,
+                    masked = cfg.maskTextInputs || cfg.maskImages,
+                    base64 = base64
+                )
+
+                bitmap.recycle()
+
+                // Deliver on main thread
+                mainHandler.post { callback(frame) }
+
+            } catch (e: Exception) {
+                ReplayLogger.error("Compress/emit error: ${e.message}", e)
+                mainHandler.post { callback(null) }
+            }
+        }
+    }
+
+    /**
+     * Scale, optionally grayscale, compress to image bytes (NO base64) and hand
+     * (frame metadata, bytes) to the sink. Runs on the background capture thread.
+     */
+    private fun compressToBytes(
+        originalBitmap: Bitmap,
+        targetWidth: Int,
+        targetHeight: Int,
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        cfg: ReplayConfig,
+        sink: (ReplayFrame?, ByteArray?) -> Unit
+    ) {
+        captureHandler.post {
+            try {
+                var bitmap = Bitmap.createScaledBitmap(originalBitmap, targetWidth, targetHeight, true)
+                if (bitmap !== originalBitmap) originalBitmap.recycle()
+
+                if (cfg.screenshotQuality == ScreenshotQuality.GRAYSCALE) {
+                    val grayscale = Bitmap.createBitmap(bitmap.width, bitmap.height, Bitmap.Config.ARGB_8888)
+                    val canvas = Canvas(grayscale)
+                    val paint = Paint()
+                    val cm = ColorMatrix()
+                    cm.setSaturation(0f)
+                    paint.colorFilter = ColorMatrixColorFilter(cm)
+                    canvas.drawBitmap(bitmap, 0f, 0f, paint)
+                    bitmap.recycle()
+                    bitmap = grayscale
+                }
+
+                val outputStream = ByteArrayOutputStream()
+                val wantsModern = cfg.format == "avif" || cfg.format == "webp"
+                val useWebp = wantsModern && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
+                val format = if (useWebp) Bitmap.CompressFormat.WEBP_LOSSY else Bitmap.CompressFormat.JPEG
+                bitmap.compress(format, cfg.jpegQuality, outputStream)
+                val bytes = outputStream.toByteArray()
+                val actualFormat = if (format == Bitmap.CompressFormat.JPEG) "jpeg" else "webp"
+
+                val seq = sequenceCounter.incrementAndGet()
+                val maskApplied = cfg.maskTextInputs || cfg.maskImages || cfg.maskedElementIds.isNotEmpty()
+                val frame = ReplayFrame(
+                    frameId = SessionIdGenerator.frameId(),
+                    sessionId = sessionId,
+                    timestamp = System.currentTimeMillis(),
+                    sequenceNumber = seq,
+                    screenName = screenName,
+                    trigger = trigger,
+                    format = actualFormat,
+                    sizeBytes = bytes.size,
+                    width = bitmap.width,
+                    height = bitmap.height,
+                    quality = cfg.screenshotQuality.value,
+                    masked = maskApplied,
+                    base64 = null
+                )
+                bitmap.recycle()
+                mainHandler.post { sink(frame, bytes) }
+            } catch (e: Exception) {
+                ReplayLogger.error("compressToBytes error: ${e.message}", e)
+                mainHandler.post { sink(null, null) }
+            }
+        }
+    }
+
+    // ─── Frequency Timer ────────────────────────────────────────────────
+
+    fun startFrequencyTimer(intervalMs: Long, capture: (Activity?) -> Unit) {
+        stopFrequencyTimer()
+        frequencyHandler = Handler(Looper.getMainLooper())
+        frequencyRunnable = object : Runnable {
+            override fun run() {
+                capture(null) // Caller must provide current activity
+                frequencyHandler?.postDelayed(this, intervalMs)
+            }
+        }
+        frequencyHandler?.postDelayed(frequencyRunnable!!, intervalMs)
+    }
+
+    fun stopFrequencyTimer() {
+        frequencyRunnable?.let { frequencyHandler?.removeCallbacks(it) }
+        frequencyRunnable = null
+        frequencyHandler = null
+    }
+
+    // ─── Cleanup ────────────────────────────────────────────────────────
+
+    fun destroy() {
+        stopFrequencyTimer()
+        scheduler.reset()
+        captureThread.quitSafely()
+    }
+}