@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,1117 @@
+package com.scalebun.replaysdk
+
+import android.app.Application
+import android.os.Build
+import com.facebook.react.bridge.*
+import com.facebook.react.bridge.LifecycleEventListener
+import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.scalebun.replaysdk.core.*
+import com.scalebun.replaysdk.session.SessionManager
+import com.scalebun.replaysdk.tracking.InteractionTracker
+import com.scalebun.replaysdk.transport.ReplayTransport
+import com.scalebun.replaysdk.outbox.NativeOutbox
+import com.scalebun.replaysdk.outbox.OutboxUploader
+import org.json.JSONObject
+
+/**
+ * React Native Bridge Module for Session Replay SDK.
+ *
+ * Every method here corresponds to a TypeScript method in nativeModule.ts.
+ * All methods are safe — they catch exceptions and reject the promise.
+ */
+class ReplaySdkModule(reactContext: ReactApplicationContext) : ReplaySdkSpec(reactContext), LifecycleEventListener {
+
+    companion object {
+        const val NAME = "ReplaySdk"
+    }
+
+    override fun getName(): String = NAME
+
+    private var sessionManager: SessionManager? = null
+    private var transport: ReplayTransport? = null
+    private val interactionTracker = InteractionTracker(reactContext)
+
+    // Native file-based outbox (only constructed when enableNativeFileOutbox is on).
+    private var nativeOutbox: NativeOutbox? = null
+    private var outboxUploader: OutboxUploader? = null
+    private var outboxConfig: ReplayConfig? = null
+    private var connectivityCallback: android.net.ConnectivityManager.NetworkCallback? = null
+    /**
+     * Outbox lanes parked by a per-feature quota block (shared contract v1). Kept on the module so a
+     * block set before the outbox/uploader exists is applied when they are built. Concurrent set,
+     * written by setOutboxLaneQuota (bridge thread, under quotaLock) and by the uploader's
+     * onLaneParked callback (upload executor) when it parks a lane itself after a 402 / partial grant.
+     */
+    private val quotaBlockedLanes: MutableSet<String> = java.util.concurrent.ConcurrentHashMap.newKeySet()
+    /** Serializes setOutboxLaneQuota against attachQuota so a park racing an uploader build is never lost. */
+    private val quotaLock = Any()
+
+    init {
+        reactContext.addLifecycleEventListener(this)
+    }
+
+    /** Build the uploader from full config, wiring all network-aware retry knobs. */
+    private fun buildUploader(ob: NativeOutbox, config: ReplayConfig): OutboxUploader {
+        val uploader = OutboxUploader(
+            ob, config.apiBaseUrl, config.clientKey,
+            config.useObjectStorageForFrames,
+            maxUploadAttempts = config.outboxMaxUploadAttempts,
+            retryIntervalMs = config.outboxRetryIntervalMs,
+            poisonMaxAttempts = config.outboxPoisonMaxAttempts,
+            respectRetryAfter = config.outboxRespectRetryAfter,
+            strictThreeSecondRetry = config.outboxStrictThreeSecondRetry,
+        )
+        attachQuota(uploader)
+        return uploader
+    }
+
+    // ─── Per-feature quota (shared contract v1) ─────────────────────────
+
+    /** Apply the module's parked lanes to a freshly built uploader and route its 402s back to JS. */
+    private fun attachQuota(uploader: OutboxUploader) {
+        // The uploader has already parked/purged natively. JS records the refusal from the body
+        // (which names the feature), drops a refused session by id, and re-syncs every lane.
+        uploader.onQuotaExceeded = { status, body, retryAfterMs, sessionId ->
+            val params = Arguments.createMap().apply {
+                putInt("status", status)
+                putString("body", body)
+                putDouble("retryAfterMs", retryAfterMs.toDouble())
+                putString("sessionId", sessionId)
+            }
+            emit("ReplaySdk_OutboxQuotaExceeded", params)
+        }
+        // A lane the uploader parks itself is mirrored into the module set at once, so enqueue /
+        // commit / capture-to-file gating does not wait for JS to sync.
+        uploader.onLaneParked = { lane -> quotaBlockedLanes.add(lane) }
+        // Publish the uploader and apply the parked set UNDER quotaLock — the lock setOutboxLaneQuota
+        // holds while it reads `outboxUploader` — so a racing park/un-park is either in the set read
+        // here or sees this uploader and applies itself. (Callers assign the same instance again.)
+        synchronized(quotaLock) {
+            outboxUploader = uploader
+            for (lane in quotaBlockedLanes.toList()) uploader.setLaneQuotaBlocked(lane, true)
+        }
+    }
+
+    /**
+     * Park + purge (blocked) or un-park a lane. Resolves the number of files purged (0 on un-park,
+     * or when the purge is delegated to the uploader's executor, or when no outbox exists yet — the
+     * block is still remembered and applied when it is built).
+     */
+    @ReactMethod
+    override fun setOutboxLaneQuota(lane: String, blocked: Boolean, promise: Promise) {
+        try {
+            // Only the lanes of LIMITED features can be parked; errors/logs/performance never.
+            if (lane !in OutboxUploader.QUOTA_FEATURE_LANES.values) { promise.resolve(0); return }
+            var removed = 0
+            synchronized(quotaLock) {
+                if (blocked) quotaBlockedLanes.add(lane) else quotaBlockedLanes.remove(lane)
+                val uploader = outboxUploader
+                if (uploader != null) {
+                    uploader.setLaneQuotaBlocked(lane, blocked)
+                } else if (blocked) {
+                    removed = nativeOutbox?.purgeLane(lane) ?: 0
+                }
+            }
+            promise.resolve(removed)
+        } catch (e: Exception) {
+            promise.reject("OUTBOX_QUOTA_ERROR", e.message, e)
+        }
+    }
+
+    /** Whether the active masking policy requires masking (drives recover() orphan sweep). */
+    private fun maskRequired(config: ReplayConfig): Boolean =
+        config.maskTextInputs || config.maskImages || config.maskedElementIds.isNotEmpty()
+
+    /**
+     * Register a ConnectivityManager.NetworkCallback so the uploader wakes immediately
+     * when the network is restored and parks (cancels its retry timer) when it drops
+     * (section 6/7). Idempotent; best-effort if the manager is unavailable.
+     */
+    private fun registerConnectivity() {
+        if (connectivityCallback != null) return
+        try {
+            val cm = reactApplicationContext.getSystemService(android.content.Context.CONNECTIVITY_SERVICE)
+                as? android.net.ConnectivityManager ?: return
+            val cb = object : android.net.ConnectivityManager.NetworkCallback() {
+                override fun onAvailable(network: android.net.Network) { outboxUploader?.setNetworkAvailable(true) }
+                override fun onLost(network: android.net.Network) {
+                    val active = cm.activeNetwork != null
+                    outboxUploader?.setNetworkAvailable(active)
+                }
+            }
+            cm.registerDefaultNetworkCallback(cb)
+            connectivityCallback = cb
+            // Seed initial state.
+            outboxUploader?.setNetworkAvailable(cm.activeNetwork != null)
+        } catch (e: Exception) {
+            ReplayLogger.warn("outbox connectivity listener unavailable: ${e.message}")
+        }
+    }
+
+    override fun onHostResume() {
+        getCurrentActivity()?.let { interactionTracker.attach(it) }
+    }
+
+    override fun onHostPause() {
+        getCurrentActivity()?.let { interactionTracker.detach(it) }
+    }
+
+    override fun onHostDestroy() {
+        getCurrentActivity()?.let { interactionTracker.detach(it) }
+    }
+
+    private fun emit(eventName: String, params: WritableMap) {
+        try {
+            reactApplicationContext
+                .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+                .emit(eventName, params)
+        } catch (e: Exception) {
+            ReplayLogger.error("Event emit failed: ${e.message}")
+        }
+    }
+
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun initialize(configMap: ReadableMap, promise: Promise) {
+        try {
+            val app = reactApplicationContext.applicationContext as? Application
+            if (app == null) {
+                promise.reject("INIT_ERROR", "Application context not available")
+                return
+            }
+
+            val config = ReplayConfig.fromMap(configMap.toHashMap().mapValues { it.value })
+            ReplayLogger.verbose = config.verboseLogging
+
+            sessionManager = SessionManager(app, config).apply {
+                onStateChanged = { prev, next, sessionId ->
+                    val params = Arguments.createMap().apply {
+                        putString("sessionId", sessionId)
+                        putString("previousState", prev)
+                        putString("newState", next)
+                        putDouble("timestamp", System.currentTimeMillis().toDouble())
+                    }
+                    emit("ReplaySdk_SessionStateChanged", params)
+                }
+
+                onFrameCaptured = { frameId, sessionId, seq, screenName, trigger, sizeBytes ->
+                    val params = Arguments.createMap().apply {
+                        putString("frameId", frameId)
+                        putString("sessionId", sessionId)
+                        putDouble("timestamp", System.currentTimeMillis().toDouble())
+                        putInt("sequenceNumber", seq)
+                        putString("screenName", screenName)
+                        putString("trigger", trigger)
+                        putInt("sizeBytes", sizeBytes)
+                    }
+                    emit("ReplaySdk_FrameCaptured", params)
+                }
+
+                onLimitReached = { limitType, current, max, sessionId ->
+                    val params = Arguments.createMap().apply {
+                        putString("sessionId", sessionId)
+                        putString("limitType", limitType)
+                        putInt("currentValue", current)
+                        putInt("maxValue", max)
+                    }
+                    emit("ReplaySdk_SessionLimitReached", params)
+                }
+
+                onScreenChanged = { screenName ->
+                    val params = Arguments.createMap().apply {
+                        putString("screenName", screenName)
+                        putDouble("timestamp", System.currentTimeMillis().toDouble())
+                    }
+                    emit("ReplaySdk_ScreenChanged", params)
+                }
+            }
+
+            transport = ReplayTransport(config.endpoint, config.apiKey, config.maxRetryAttempts)
+
+            // Native file-based outbox (default-safe: only when explicitly enabled).
+            outboxConfig = config
+            if (config.enableNativeFileOutbox) {
+                val ob = NativeOutbox(app, config.outboxMaxBytes, config.outboxMaxAgeMs)
+                nativeOutbox = ob
+                // Startup recovery: requeue interrupted uploads, sweep orphans, and drop
+                // any committed frame that violates the mask policy (masked=false).
+                ob.recover(maskRequired(config))
+                if (config.nativeOutboxUploadEnabled) {
+                    outboxUploader = buildUploader(ob, config)
+                    registerConnectivity()
+                    // Drain anything left over from a previous run.
+                    outboxUploader?.flush()
+                }
+                ReplayLogger.info("Native file outbox enabled (upload=${config.nativeOutboxUploadEnabled})")
+            }
+
+            ReplayLogger.info("Native module initialized")
+            promise.resolve(true)
+
+        } catch (e: Exception) {
+            ReplayLogger.error("Initialize failed: ${e.message}", e)
+            promise.reject("INIT_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun startSession(promise: Promise) {
+        try {
+            val sessionId = sessionManager?.startSession()
+            if (sessionId != null) {
+                promise.resolve(sessionId)
+            } else {
+                promise.reject("SESSION_ERROR", "Failed to start session")
+            }
+        } catch (e: Exception) {
+            promise.reject("SESSION_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun stopSession(promise: Promise) {
+        try {
+            val result = sessionManager?.stopSession() ?: false
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("SESSION_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun pauseSession(promise: Promise) {
+        try {
+            val result = sessionManager?.pauseSession() ?: false
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("SESSION_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun resumeSession(promise: Promise) {
+        try {
+            val result = sessionManager?.resumeSession() ?: false
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("SESSION_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Capture ────────────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun captureFrame(reason: String, promise: Promise) {
+        try {
+            val activity = getCurrentActivity()
+            if (activity == null) {
+                promise.resolve(null)
+                return
+            }
+            sessionManager?.captureFrame(activity, reason) { frame ->
+                if (frame != null) {
+                    val result = Arguments.createMap().apply {
+                        putString("base64", frame["base64"] as? String ?: "")
+                        putInt("width", frame["width"] as? Int ?: 0)
+                        putInt("height", frame["height"] as? Int ?: 0)
+                        putInt("sizeBytes", frame["sizeBytes"] as? Int ?: 0)
+                        putString("format", frame["format"] as? String ?: "jpeg")
+                        putDouble("timestamp", (frame["timestamp"] as? Long ?: 0L).toDouble())
+                        putScrollState(this, frame["scrollState"])
+                    }
+                    promise.resolve(result)
+                } else {
+                    promise.resolve(null)
+                }
+            } ?: promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CAPTURE_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun captureManualFrame(promise: Promise) {
+        try {
+            sessionManager?.captureManualFrame { frame ->
+                if (frame != null) {
+                    val result = Arguments.createMap().apply {
+                        putString("base64", frame["base64"] as? String ?: "")
+                        putInt("width", frame["width"] as? Int ?: 0)
+                        putInt("height", frame["height"] as? Int ?: 0)
+                        putInt("sizeBytes", frame["sizeBytes"] as? Int ?: 0)
+                        putString("format", frame["format"] as? String ?: "jpeg")
+                        putDouble("timestamp", (frame["timestamp"] as? Long ?: 0L).toDouble())
+                        putScrollState(this, frame["scrollState"])
+                    }
+                    promise.resolve(result)
+                } else {
+                    promise.resolve(null)
+                }
+            } ?: promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CAPTURE_ERROR", e.message, e)
+        }
+    }
+
+    /**
+     * Standalone screenshot capture — works without session initialization.
+     * Uses PixelCopy (API 26+) with Canvas fallback.
+     * Called by scalebun-sdk's bootstrap.ts for session replay frames.
+     */
+    @ReactMethod
+    override fun captureScreenshot(reason: String, promise: Promise) {
+        try {
+            val activity = reactApplicationContext.currentActivity
+            if (activity == null || activity.isFinishing || activity.isDestroyed) {
+                promise.resolve(null)
+                return
+            }
+
+            // Honor the host's privacy config when the SDK stored one (native
+            // initialize()/initOutbox()). Falling back to a fresh ReplayConfig() — as
+            // before — still masks text inputs, since maskTextInputs defaults to true;
+            // this additionally honors maskImages / maskedElementIds and an explicit opt-out.
+            val config = outboxConfig ?: ReplayConfig()
+            val captureManager = com.scalebun.replaysdk.capture.FrameCaptureManager(config)
+            captureManager.capture(activity, "standalone", "unknown", reason, config) { frame ->
+                captureManager.destroy()
+                if (frame != null) {
+                    val result = Arguments.createMap().apply {
+                        putString("base64", frame.base64)
+                        putInt("width", frame.width)
+                        putInt("height", frame.height)
+                        putInt("sizeBytes", frame.sizeBytes)
+                        putString("format", frame.format)
+                        putDouble("timestamp", frame.timestamp.toDouble())
+                        putScrollState(this, frame.scrollState)
+                    }
+                    promise.resolve(result)
+                } else {
+                    promise.resolve(null)
+                }
+            }
+        } catch (e: Exception) {
+            promise.reject("CAPTURE_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Native file outbox ─────────────────────────────────────────────
+
+    /**
+     * Lightweight outbox bootstrap for the SaaS path where the full native
+     * `initialize()` (which builds a SessionManager) is never called. Constructs
+     * ONLY the durable NativeOutbox + OutboxUploader from a minimal config map
+     * (clientKey, apiBaseUrl, flags). Idempotent: a no-op once the outbox exists.
+     * Resolves false when the flag is off or already initialized.
+     */
+    @ReactMethod
+    override fun initOutbox(configMap: ReadableMap, promise: Promise) {
+        try {
+            if (nativeOutbox != null) { promise.resolve(true); return }
+            val app = reactApplicationContext.applicationContext as? Application
+                ?: run { promise.reject("OUTBOX_INIT", "Application context unavailable"); return }
+            val config = ReplayConfig.fromMap(configMap.toHashMap().mapValues { it.value })
+            if (!config.enableNativeFileOutbox) { promise.resolve(false); return }
+            outboxConfig = config
+            val ob = NativeOutbox(app, config.outboxMaxBytes, config.outboxMaxAgeMs)
+            nativeOutbox = ob
+            ob.recover(maskRequired(config))
+            if (config.nativeOutboxUploadEnabled) {
+                outboxUploader = buildUploader(ob, config)
+                registerConnectivity()
+                outboxUploader?.flush()
+            }
+            ReplayLogger.info("Native file outbox bootstrapped (upload=${config.nativeOutboxUploadEnabled})")
+            promise.resolve(true)
+        } catch (e: Exception) {
+            promise.reject("OUTBOX_INIT_ERROR", e.message, e)
+        }
+    }
+
+    /**
+     * Capture a screenshot natively, mask it, encode to image bytes, and write the
+     * frame (image + metadata json) to the durable native outbox. Returns metadata
+     * ONLY — no base64 crosses the bridge. Resolves null if capture/store fails or the
+     * outbox is disabled.
+     */
+    @ReactMethod
+    override fun captureScreenshotToFile(input: ReadableMap, promise: Promise) {
+        try {
+            val ob = nativeOutbox
+            if (ob == null) { promise.reject("OUTBOX_DISABLED", "enableNativeFileOutbox is off"); return }
+            // frames quota exhausted: don't spend CPU/disk capturing a frame that can never upload.
+            if (NativeOutbox.FRAMES in quotaBlockedLanes) { promise.resolve(null); return }
+            val activity = currentActivity
+            if (activity == null || activity.isFinishing || activity.isDestroyed) { promise.resolve(null); return }
+            val sessionId = input.getString("sessionId")
+            if (sessionId.isNullOrEmpty()) { promise.reject("OUTBOX_ARG", "sessionId required"); return }
+            val screenName = input.getString("screenName") ?: "unknown"
+            val trigger = input.getString("trigger") ?: "manual"
+            val cfg = outboxConfig ?: ReplayConfig()
+
+            ob.initSession(sessionId, screenName)
+            val cm = sessionManager?.captureManager
+                ?: com.scalebun.replaysdk.capture.FrameCaptureManager(cfg)
+
+            cm.captureToFile(activity, sessionId, screenName, trigger, cfg) { frame, bytes ->
+                if (frame == null || bytes == null) { promise.resolve(null); return@captureToFile }
+                // Stage IMAGE ONLY — JS (ReplayCaptureManager) decides keyframe/delta +
+                // change-detection, then calls commitOutboxFrame (writes meta) or
+                // discardOutboxFrame (suppressed). No metadata json is written here.
+                val localFile = ob.writeFrameImage(frame.sessionId, frame.frameId, frame.format, bytes)
+                if (localFile == null) { promise.resolve(null); return@captureToFile }
+                val result = Arguments.createMap().apply {
+                    putString("frameId", frame.frameId)
+                    putString("sessionId", frame.sessionId)
+                    putString("localPath", localFile)
+                    putInt("width", frame.width)
+                    putInt("height", frame.height)
+                    putInt("sizeBytes", frame.sizeBytes)
+                    putString("format", frame.format)
+                    putString("contentType", "image/${frame.format}")
+                    putDouble("timestamp", frame.timestamp.toDouble())
+                    putString("screenName", frame.screenName)
+                    putString("trigger", frame.trigger)
+                    putBoolean("masked", frame.masked)
+                    // Cheap content hash so the JS change-detector works without base64.
+                    putString("frameHash", fnv1a(bytes))
+                    putScrollState(this, frame.scrollState)
+                }
+                promise.resolve(result)
+            }
+        } catch (e: Exception) {
+            promise.reject("CAPTURE_FILE_ERROR", e.message, e)
+        }
+    }
+
+    /**
+     * Commit a staged frame: write the metadata json (upload marker) carrying the
+     * JS-authoritative sequenceNumber/frameType/baseFrameId. Makes the frame
+     * uploadable. Resolves the meta path, or null if the staged image is gone /
+     * outbox disabled.
+     */
+    @ReactMethod
+    override fun commitOutboxFrame(input: ReadableMap, promise: Promise) {
+        try {
+            val ob = nativeOutbox ?: run { promise.resolve(null); return }
+            val map = input.toHashMap()
+            val meta = JSONObject(map as Map<*, *>)
+            if (NativeOutbox.FRAMES in quotaBlockedLanes) {
+                // frames quota exhausted: the staged image is discarded, never made uploadable.
+                val sid = meta.optString("sessionId", "")
+                val fid = meta.optString("frameId", "")
+                if (sid.isNotEmpty() && fid.isNotEmpty()) ob.discardFrame(sid, fid)
+                promise.resolve(null)
+                return
+            }
+            val path = ob.commitFrame(meta)
+            if (path == null) { promise.resolve(null); return }
+            outboxUploader?.flush()
+            promise.resolve(path)
+        } catch (e: Exception) {
+            promise.reject("OUTBOX_COMMIT_ERROR", e.message, e)
+        }
+    }
+
+    /** Discard a staged frame the JS orchestrator suppressed (no upload). */
+    @ReactMethod
+    override fun discardOutboxFrame(sessionId: String, frameId: String, promise: Promise) {
+        try {
+            nativeOutbox?.discardFrame(sessionId, frameId)
+            promise.resolve(true)
+        } catch (e: Exception) {
+            promise.reject("OUTBOX_DISCARD_ERROR", e.message, e)
+        }
+    }
+
+    /**
+     * Append non-frame telemetry records (events|logs|network|errors|performance) to
+     * the session's JSONL segment outbox. JS hands over already-batched records; native
+     * owns durability + upload. Returns false if the outbox is disabled (JS falls back).
+     */
+    @ReactMethod
+    override fun enqueueOutboxRecords(lane: String, sessionId: String, records: ReadableArray, promise: Promise) {
+        try {
+            val ob = nativeOutbox ?: run { promise.resolve(false); return }
+            if (sessionId.isEmpty()) { promise.resolve(false); return }
+            // Quota-parked lane: accept-and-discard (true), so JS does not fall back to posting
+            // records the server would refuse.
+            if (lane in quotaBlockedLanes) { promise.resolve(true); return }
+            ob.initSession(sessionId, "unknown")
+            val list = ArrayList<JSONObject>(records.size())
+            for (i in 0 until records.size()) {
+                val m = records.getMap(i) ?: continue
+                list.add(JSONObject(m.toHashMap() as Map<*, *>))
+            }
+            ob.appendTelemetry(sessionId, lane, list, laneFlushCount(lane), 256L * 1024)
+            outboxUploader?.flush()
+            promise.resolve(true)
+        } catch (e: Exception) {
+            promise.reject("OUTBOX_ENQUEUE_ERROR", e.message, e)
+        }
+    }
+
+    /** Close all open segments across sessions and trigger an upload drain. */
+    @ReactMethod
+    override fun flushNativeOutbox(promise: Promise) {
+        try {
+            val ob = nativeOutbox ?: run { promise.resolve(false); return }
+            for (sid in ob.listSessionIds()) ob.closeAllOpenSegments(sid)
+            outboxUploader?.flush()
+            promise.resolve(true)
+        } catch (e: Exception) {
+            promise.reject("OUTBOX_FLUSH_ERROR", e.message, e)
+        }
+    }
+
+    /** Re-run startup recovery on demand (e.g. JS app-startup trigger). */
+    @ReactMethod
+    override fun recoverNativeOutbox(promise: Promise) {
+        try {
+            nativeOutbox?.recover()
+            promise.resolve(true)
+        } catch (e: Exception) {
+            promise.reject("OUTBOX_RECOVER_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun getOutboxStats(promise: Promise) {
+        try {
+            val ob = nativeOutbox ?: run { promise.resolve(null); return }
+            val result = Arguments.createMap().apply {
+                putBoolean("enabled", true)
+                putBoolean("uploadEnabled", outboxUploader != null)
+                putDouble("totalBytes", ob.totalBytes().toDouble())
+                putInt("sessionCount", ob.listSessionIds().size)
+            }
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("OUTBOX_STATS_ERROR", e.message, e)
+        }
+    }
+
+    private fun laneFlushCount(lane: String): Int = when (lane) {
+        "events" -> 30
+        "logs" -> 50
+        "network" -> 50
+        "errors" -> 20
+        "performance" -> 50
+        else -> 30
+    }
+
+    /**
+     * A frame's visible scroll containers at capture time (ScrollContextProbe.snapshot), in
+     * capture-view pixels. Absent when not measured; an empty array means none on screen.
+     */
+    private fun putScrollState(target: WritableMap, state: Any?) {
+        val list = state as? List<*> ?: return
+        val arr = Arguments.createArray()
+        for (item in list) {
+            val m = item as? Map<*, *> ?: continue
+            val entry = Arguments.createMap()
+            for ((k, v) in m) {
+                val key = k as? String ?: continue
+                when (v) {
+                    is Boolean -> entry.putBoolean(key, v)
+                    is Int -> entry.putInt(key, v)
+                    is Number -> entry.putDouble(key, v.toDouble())
+                    is String -> entry.putString(key, v)
+                }
+            }
+            arr.pushMap(entry)
+        }
+        target.putArray("scrollState", arr)
+    }
+
+    /**
+     * FNV-1a (32-bit) over sampled bytes — cheap content hash for JS change
+     * detection. Samples large frames so cost stays O(1)-ish; folds in length.
+     */
+    private fun fnv1a(bytes: ByteArray): String {
+        var h = 0x811c9dc5.toInt()
+        val len = bytes.size
+        val step = if (len > 4096) len / 4096 + 1 else 1
+        var i = 0
+        while (i < len) {
+            h = h xor (bytes[i].toInt() and 0xff)
+            h *= 0x01000193
+            i += step
+        }
+        return (h.toLong() and 0xffffffffL).toString(36) + "-" + len.toString(36)
+    }
+
+    // ─── Configuration ──────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun setEnabled(enabled: Boolean, promise: Promise) {
+        try {
+            // If disabling and recording, stop session
+            if (!enabled && sessionManager?.isRecording() == true) {
+                sessionManager?.stopSession()
+            }
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CONFIG_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun setCapturingMode(mode: String, promise: Promise) {
+        try {
+            sessionManager?.updateConfig(
+                sessionManager?.let { sm ->
+                    ReplayConfig(captureMode = CaptureMode.fromString(mode))
+                } ?: ReplayConfig()
+            )
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CONFIG_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun setScreenshotQuality(quality: String, promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CONFIG_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun setScreenshotCaptureInterval(intervalMs: Double, promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CONFIG_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun setUserStepsEnabled(enabled: Boolean, promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CONFIG_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun setNetworkLogsEnabled(enabled: Boolean, promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CONFIG_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun setSdkLogsEnabled(enabled: Boolean, promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("CONFIG_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Privacy ────────────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun setPrivacyOptions(options: ReadableMap, promise: Promise) {
+        try {
+            // Was a no-op stub: the promise resolved but nothing propagated, so
+            // `setPrivacy({ disableScreenshots })` did nothing at runtime on Android and only a
+            // restart (which re-reads the init config) honoured it. Now each supplied field is
+            // merged onto the running config via SessionManager.updatePrivacy, which routes through
+            // updateConfig → the capture manager, so the next frame respects it. Absent keys are
+            // left null → unchanged (a partial setPrivacy call must not reset the others).
+            sessionManager?.updatePrivacy(
+                disableScreenshots = if (options.hasKey("disableScreenshots")) options.getBoolean("disableScreenshots") else null,
+                maskTextInputs = if (options.hasKey("maskTextInputs")) options.getBoolean("maskTextInputs") else null,
+                maskImages = if (options.hasKey("maskImages")) options.getBoolean("maskImages") else null,
+                ignoredScreens = if (options.hasKey("ignoredScreens")) readStringList(options.getArray("ignoredScreens")) else null,
+                maskedElementIds = if (options.hasKey("maskedElementIds")) readStringList(options.getArray("maskedElementIds")) else null,
+            )
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("PRIVACY_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun maskElement(elementId: String, promise: Promise) {
+        try {
+            sessionManager?.addMaskedElement(elementId)
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("PRIVACY_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun unmaskElement(elementId: String, promise: Promise) {
+        try {
+            sessionManager?.removeMaskedElement(elementId)
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("PRIVACY_ERROR", e.message, e)
+        }
+    }
+
+    /** ReadableArray → List<String>, nulls and non-strings dropped. */
+    private fun readStringList(arr: ReadableArray?): List<String> {
+        if (arr == null) return emptyList()
+        val out = ArrayList<String>(arr.size())
+        for (i in 0 until arr.size()) {
+            arr.getString(i)?.let { out.add(it) }
+        }
+        return out
+    }
+
+    // ─── User ───────────────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun setUser(user: ReadableMap, promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("USER_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun clearUser(promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("USER_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Breadcrumbs ────────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun addBreadcrumb(breadcrumb: ReadableMap, promise: Promise) {
+        try {
+            val sm = sessionManager ?: run { promise.resolve(null); return }
+            val sessionId = sm.getCurrentSessionId() ?: run { promise.resolve(null); return }
+
+            sm.timelineCollector.addEvent(
+                com.scalebun.replaysdk.models.TimelineEvent(
+                    eventId = SessionIdGenerator.eventId(),
+                    sessionId = sessionId,
+                    type = "custom_breadcrumb",
+                    timestamp = (breadcrumb.getDouble("timestamp")).toLong(),
+                    screenName = sm.screenTracker.currentScreen,
+                    label = breadcrumb.getString("message") ?: "",
+                    data = breadcrumb.toHashMap().mapValues { it.value }
+                )
+            )
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("BREADCRUMB_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun addNetworkBreadcrumb(request: ReadableMap, promise: Promise) {
+        try {
+            val sm = sessionManager ?: run { promise.resolve(null); return }
+            val sessionId = sm.getCurrentSessionId() ?: run { promise.resolve(null); return }
+
+            sm.timelineCollector.addEvent(
+                com.scalebun.replaysdk.models.TimelineEvent(
+                    eventId = SessionIdGenerator.eventId(),
+                    sessionId = sessionId,
+                    type = "network_request",
+                    timestamp = System.currentTimeMillis(),
+                    screenName = sm.screenTracker.currentScreen,
+                    label = "${request.getString("method")} ${request.getString("url")} → ${request.getInt("statusCode")}",
+                    data = request.toHashMap().mapValues { it.value }
+                )
+            )
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("NETWORK_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Screen Tracking ────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun setCurrentScreen(screenName: String, promise: Promise) {
+        try {
+            sessionManager?.setCurrentScreen(screenName)
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("SCREEN_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Interaction Tracking ───────────────────────────────────────────
+
+    @ReactMethod
+    override fun reportInteraction(interaction: ReadableMap, promise: Promise) {
+        try {
+            val type = interaction.getString("type") ?: "tap"
+            val x = (interaction.getDouble("x")).toInt()
+            val y = (interaction.getDouble("y")).toInt()
+            val timestamp = (interaction.getDouble("timestamp")).toLong()
+
+            val shouldCapture = interactionTracker.reportInteraction(type, x, y, timestamp)
+            if (shouldCapture && sessionManager?.isRecording() == true) {
+                val activity = getCurrentActivity()
+                if (activity != null) {
+                    sessionManager?.captureFrame(activity, "interaction")
+                }
+            }
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("INTERACTION_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Query ──────────────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun getSessionInfo(promise: Promise) {
+        try {
+            val info = sessionManager?.getSessionInfo()
+            if (info != null) {
+                val result = Arguments.createMap().apply {
+                    putString("sessionId", info["sessionId"] as? String ?: "")
+                    putString("state", info["state"] as? String ?: "idle")
+                    putDouble("startedAt", (info["startedAt"] as? Long ?: 0L).toDouble())
+                    putDouble("endedAt", (info["endedAt"] as? Long ?: 0L).toDouble())
+                    putInt("frameCount", info["frameCount"] as? Int ?: 0)
+                    putInt("eventCount", info["eventCount"] as? Int ?: 0)
+                    putString("currentScreen", info["currentScreen"] as? String ?: "unknown")
+                }
+                promise.resolve(result)
+            } else {
+                promise.resolve(null)
+            }
+        } catch (e: Exception) {
+            promise.reject("QUERY_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun getDeviceInfo(promise: Promise) {
+        try {
+            val ctx = reactApplicationContext
+            val pm = ctx.packageManager
+            val pi = pm.getPackageInfo(ctx.packageName, 0)
+            val dm = ctx.resources.displayMetrics
+
+            val result = Arguments.createMap().apply {
+                putString("platform", "android")
+                putString("osVersion", Build.VERSION.RELEASE)
+                putString("deviceModel", "${Build.MANUFACTURER} ${Build.MODEL}")
+                putInt("screenWidth", dm.widthPixels)
+                putInt("screenHeight", dm.heightPixels)
+                putDouble("pixelDensity", dm.density.toDouble())
+                putString("appName", pi.applicationInfo?.loadLabel(pm)?.toString() ?: "")
+                putString("appVersion", pi.versionName ?: "0.0.0")
+                putString("bundleId", ctx.packageName)
+                putString("locale", java.util.Locale.getDefault().toString())
+            }
+            promise.resolve(result)
+        } catch (e: Exception) {
+            promise.reject("DEVICE_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun getSessionReplayLink(promise: Promise) {
+        try {
+            val sessionId = sessionManager?.getCurrentSessionId()
+            if (sessionId != null) {
+                val result = Arguments.createMap().apply {
+                    putString("url", "")
+                    putString("sessionId", sessionId)
+                    putBoolean("uploaded", false)
+                }
+                promise.resolve(result)
+            } else {
+                promise.resolve(null)
+            }
+        } catch (e: Exception) {
+            promise.reject("LINK_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Upload ─────────────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun flushUpload(promise: Promise) {
+        try {
+            // Trigger upload of pending data
+            promise.resolve(true)
+        } catch (e: Exception) {
+            promise.reject("UPLOAD_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun cancelUpload(promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("UPLOAD_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Cleanup ────────────────────────────────────────────────────────
+
+    @ReactMethod
+    override fun destroy(promise: Promise) {
+        try {
+            sessionManager?.destroy()
+            transport?.destroy()
+            outboxUploader?.destroy()
+            sessionManager = null
+            transport = null
+            outboxUploader = null
+            nativeOutbox = null
+            ReplayLogger.info("Native module destroyed")
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("DESTROY_ERROR", e.message, e)
+        }
+    }
+
+    // ─── Voice notes (Slice D) ──────────────────────────────────────────
+
+    private var voiceRecorder: com.scalebun.replaysdk.voice.VoiceRecorder? = null
+    private var voiceTranscriber: com.scalebun.replaysdk.voice.VoiceTranscriber? = null
+
+    /**
+     * Start recording a feedback voice note (AAC/.m4a). Requests RECORD_AUDIO at
+     * runtime if needed. A live on-device SpeechRecognizer runs alongside for a
+     * best-effort transcript prefill (the user edits + approves before send).
+     */
+    @ReactMethod
+    override fun startVoiceRecording(promise: Promise) {
+        val ctx = reactApplicationContext
+        val recorder = com.scalebun.replaysdk.voice.VoiceRecorder(ctx)
+        if (recorder.hasMicPermission()) {
+            beginVoiceRecording(recorder, promise)
+            return
+        }
+        val activity = currentActivity
+        if (activity !is com.facebook.react.modules.core.PermissionAwareActivity) {
+            promise.reject("VOICE_PERMISSION", "RECORD_AUDIO not granted")
+            return
+        }
+        val requestCode = 7421
+        activity.requestPermissions(
+            arrayOf(android.Manifest.permission.RECORD_AUDIO),
+            requestCode,
+        ) { code, _, grantResults ->
+            val granted = code == requestCode &&
+                grantResults.isNotEmpty() &&
+                grantResults[0] == android.content.pm.PackageManager.PERMISSION_GRANTED
+            if (granted) {
+                beginVoiceRecording(recorder, promise)
+            } else {
+                promise.reject("VOICE_PERMISSION", "RECORD_AUDIO denied")
+            }
+            true
+        }
+    }
+
+    private fun beginVoiceRecording(
+        recorder: com.scalebun.replaysdk.voice.VoiceRecorder,
+        promise: Promise,
+    ) {
+        try {
+            val transcriber = com.scalebun.replaysdk.voice.VoiceTranscriber(reactApplicationContext)
+            transcriber.start()
+            recorder.start()
+            voiceRecorder = recorder
+            voiceTranscriber = transcriber
+            promise.resolve(null)
+        } catch (e: Exception) {
+            voiceRecorder = null
+            voiceTranscriber = null
+            promise.reject("VOICE_START", e.message, e)
+        }
+    }
+
+    /**
+     * Stop recording. Resolves the clip bytes + real durationMs + best-effort
+     * transcript. Resolves null if nothing was captured.
+     */
+    @ReactMethod
+    override fun stopVoiceRecording(promise: Promise) {
+        try {
+            // Order matters twice here:
+            //  1. The recorder stops FIRST — it owns the mic while running, and on
+            //     most devices a concurrent capture silences the recognition engine
+            //     (the transcript arrives empty). Releasing the mic before asking
+            //     the engine to finalize gives its last buffer a chance to flush.
+            //  2. The transcript is read via the ASYNC stop: stopListening() →
+            //     onResults is not synchronous, and the old sync read raced it —
+            //     returning partials or nothing even when the engine had a result.
+            val clip = voiceRecorder?.stop()
+            val transcriber = voiceTranscriber
+            voiceRecorder = null
+            voiceTranscriber = null
+            if (clip == null) {
+                transcriber?.stop()
+                promise.resolve(null)
+                return
+            }
+            // Bytes are read into base64 by the recorder; drop the temp file now.
+            java.io.File(clip.filePath).delete()
+            val resolveWith = { transcript: com.scalebun.replaysdk.voice.VoiceTranscriber.TranscriptResult? ->
+                val result = Arguments.createMap().apply {
+                    putString("base64", clip.base64)
+                    putString("mime", "audio/mp4")
+                    putInt("durationMs", clip.durationMs)
+                    putInt("byteSize", clip.byteSize)
+                    putString("transcript", transcript?.text ?: "")
+                    putBoolean("transcriptAvailable", transcript?.available ?: false)
+                }
+                promise.resolve(result)
+            }
+            if (transcriber == null) {
+                resolveWith(null)
+            } else {
+                transcriber.stop { transcript -> resolveWith(transcript) }
+            }
+        } catch (e: Exception) {
+            voiceRecorder = null
+            voiceTranscriber = null
+            promise.reject("VOICE_STOP", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun cancelVoiceRecording(promise: Promise) {
+        try {
+            voiceTranscriber?.stop()
+            voiceRecorder?.cancel()
+        } catch (_: Exception) {
+        } finally {
+            voiceRecorder = null
+            voiceTranscriber = null
+            promise.resolve(null)
+        }
+    }
+
+    // ─── Event Emitter Support ──────────────────────────────────────────
+
+    @ReactMethod
+    override fun addListener(eventName: String) {
+        // Required for RN NativeEventEmitter
+    }
+
+    @ReactMethod
+    override fun removeListeners(count: Double) {
+        // Required for RN NativeEventEmitter
+    }
+}