@scalebun-release/react-native 2.5.0

package/android/src/main/java/com/scalebun/replaysdk/ReplaySdkPackage.kt

@@ -0,0 +1,24 @@
+package com.scalebun.replaysdk
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+import com.scalebun.rn.performance.PerformanceModule
+
+/**
+ * React Native Package registration for ReplaySdk and Performance modules.
+ */
+class ReplaySdkPackage : ReactPackage {
+
+    override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
+        return listOf(
+            ReplaySdkModule(reactContext),
+            PerformanceModule(reactContext)
+        )
+    }
+
+    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+        return emptyList()
+    }
+}

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

@@ -0,0 +1,47 @@
+package com.scalebun.replaysdk.capture
+
+/**
+ * Describes why a frame capture was requested and how the scheduler should
+ * treat it. Centralizing this here keeps timing policy out of the capture
+ * primitive and the session layer.
+ *
+ * - [priority]      higher wins when multiple requests coalesce into one capture.
+ * - [debounceMs]    how long to wait for further requests before acting. Larger
+ *                   for navigation because route transitions emit a burst.
+ * - [requireStable] gate the capture on a stable draw state (see UiStabilityDetector).
+ * - [quietFrames]   consecutive idle draw frames required before "stable".
+ * - [settleWatch]   after a stable capture, briefly watch for a late content
+ *                   change (skeleton → data, image load) and capture once more.
+ */
+enum class CaptureReason(
+    val raw: String,
+    val priority: Int,
+    val debounceMs: Long,
+    val requireStable: Boolean,
+    val quietFrames: Int,
+    val settleWatch: Boolean
+) {
+    // Route changed. RN fires this at the START of the transition, so we must
+    // wait for the new screen to settle and also watch for late-arriving data.
+    NAVIGATION("navigation", priority = 100, debounceMs = 350, requireStable = true, quietFrames = 2, settleWatch = true),
+
+    // Explicit app/host request — treat as important and stable, no settle watch.
+    MANUAL("manual", priority = 80, debounceMs = 0, requireStable = true, quietFrames = 1, settleWatch = false),
+
+    // User touch/scroll/swipe. Keep responsive: one quiet frame is enough.
+    INTERACTION("interaction", priority = 50, debounceMs = 120, requireStable = true, quietFrames = 1, settleWatch = false),
+
+    // Periodic frequency-mode tick. The screen is assumed already stable; do not
+    // gate or delay, just snapshot.
+    TIMER("timer", priority = 10, debounceMs = 0, requireStable = false, quietFrames = 1, settleWatch = false);
+
+    companion object {
+        // Internal reason used for the late-content follow-up capture.
+        const val NAVIGATION_SETTLE = "navigation.settle"
+
+        fun fromTrigger(trigger: String): CaptureReason = when {
+            trigger == NAVIGATION_SETTLE -> NAVIGATION
+            else -> entries.find { it.raw == trigger } ?: INTERACTION
+        }
+    }
+}

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

@@ -0,0 +1,574 @@
+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 com.scalebun.replaysdk.tracking.ScrollContextProbe
+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)
+
+        // Scroll state is read on main immediately before the bitmap, from the same captureView.
+        withScrollState(captureView, onError = { callback(null) }) { scrollState ->
+            acquireBitmap(
+                activity, captureView,
+                onBitmap = { bmp ->
+                    // Privacy masking on the full-res bitmap BEFORE scaling — identical to
+                    // captureToFile(). Without this, the default base64 path (used whenever
+                    // the native file outbox is off) uploaded text inputs UNMASKED while
+                    // still stamping masked=true. FAIL CLOSED: if masking throws, the frame
+                    // is DISCARDED — never emitted unmasked, never with a falsely-true flag.
+                    val masked = applyMaskSafe(bmp, captureView, cfg)
+                    if (masked == null) {
+                        ReplayLogger.warn("capture: masking failed — frame dropped (fail-closed)")
+                        if (!bmp.isRecycled) bmp.recycle()
+                        callback(null)
+                    } else {
+                        compressAndEmit(masked, targetWidth, targetHeight, sessionId, screenName, trigger, cfg, scrollState, callback)
+                    }
+                },
+                onFail = { callback(null) }
+            )
+        }
+    }
+
+    /**
+     * Read the visible scroll containers of [captureView] on the MAIN thread, immediately before
+     * the bitmap is acquired, then continue with [then] in that same main-thread turn — so the
+     * offsets describe the pixels the frame will hold (see ScrollContextProbe.snapshot).
+     *
+     * Already on main (the scheduler path): synchronous, nothing reordered. Called from another
+     * thread (the bridge's captureScreenshot / captureScreenshotToFile): one hop to main, and the
+     * bitmap acquisition follows there — where view reads belong anyway. An exception from [then]
+     * after the hop can no longer reach the bridge method's try/catch, so it is caught and routed
+     * to [onError] instead of crashing the main thread. A failed snapshot yields a null
+     * scrollState (not measured), never a lost frame.
+     */
+    private fun withScrollState(
+        captureView: View,
+        onError: () -> Unit,
+        then: (List<Map<String, Any>>?) -> Unit
+    ) {
+        fun read(): List<Map<String, Any>>? = try {
+            ScrollContextProbe.toMaps(ScrollContextProbe.snapshot(captureView))
+        } catch (t: Throwable) {
+            null
+        }
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            then(read())
+            return
+        }
+        mainHandler.post {
+            try {
+                then(read())
+            } catch (e: Exception) {
+                ReplayLogger.error("Capture after scroll snapshot failed: ${e.message}", e)
+                onError()
+            }
+        }
+    }
+
+    /**
+     * 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)
+
+        // Scroll state is read on main immediately before the bitmap, from the same captureView.
+        withScrollState(captureView, onError = { sink(null, null) }) { scrollState ->
+            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, scrollState, 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,
+        scrollState: List<Map<String, Any>>?,
+        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()
+                // Truthful masked flag: the bitmap reaching here has already been through
+                // applyMaskSafe() in capture() (fail-closed — an unmasked frame never gets
+                // here), so this reflects what was actually configured. Mirrors
+                // compressToBytes()'s maskApplied, incl. maskedElementIds.
+                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 = base64,
+                    scrollState = scrollState
+                )
+
+                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,
+        scrollState: List<Map<String, Any>>?,
+        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,
+                    scrollState = scrollState
+                )
+                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()
+    }
+}