@scalebun/react-native 1.0.2 → 1.0.3

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

@@ -1,966 +1,966 @@
-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
-
-    init {
-        reactContext.addLifecycleEventListener(this)
-    }
-
-    /** Build the uploader from full config, wiring all network-aware retry knobs. */
-    private fun buildUploader(ob: NativeOutbox, config: ReplayConfig): OutboxUploader =
-        OutboxUploader(
-            ob, config.apiBaseUrl, config.clientKey,
-            config.useObjectStorageForFrames,
-            maxUploadAttempts = config.outboxMaxUploadAttempts,
-            retryIntervalMs = config.outboxRetryIntervalMs,
-            poisonMaxAttempts = config.outboxPoisonMaxAttempts,
-            respectRetryAfter = config.outboxRespectRetryAfter,
-            strictThreeSecondRetry = config.outboxStrictThreeSecondRetry,
-        )
-
-    /** 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())
-                    }
-                    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())
-                    }
-                    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
-            }
-
-            val config = 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())
-                    }
-                    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 }
-            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))
-                }
-                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<*, *>)
-            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 }
-            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
-    }
-
-    /**
-     * 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 {
-            promise.resolve(null)
-        } catch (e: Exception) {
-            promise.reject("PRIVACY_ERROR", e.message, e)
-        }
-    }
-
-    @ReactMethod
-    override fun maskElement(elementId: String, promise: Promise) {
-        try {
-            promise.resolve(null)
-        } catch (e: Exception) {
-            promise.reject("PRIVACY_ERROR", e.message, e)
-        }
-    }
-
-    @ReactMethod
-    override fun unmaskElement(elementId: String, promise: Promise) {
-        try {
-            promise.resolve(null)
-        } catch (e: Exception) {
-            promise.reject("PRIVACY_ERROR", e.message, e)
-        }
-    }
-
-    // ─── 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 {
-            val transcript = voiceTranscriber?.stop()
-            val clip = voiceRecorder?.stop()
-            voiceRecorder = null
-            voiceTranscriber = null
-            if (clip == null) {
-                promise.resolve(null)
-                return
-            }
-            // Bytes are read into base64 by the recorder; drop the temp file now.
-            java.io.File(clip.filePath).delete()
-            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)
-        } 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
-    }
-}
+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
+
+    init {
+        reactContext.addLifecycleEventListener(this)
+    }
+
+    /** Build the uploader from full config, wiring all network-aware retry knobs. */
+    private fun buildUploader(ob: NativeOutbox, config: ReplayConfig): OutboxUploader =
+        OutboxUploader(
+            ob, config.apiBaseUrl, config.clientKey,
+            config.useObjectStorageForFrames,
+            maxUploadAttempts = config.outboxMaxUploadAttempts,
+            retryIntervalMs = config.outboxRetryIntervalMs,
+            poisonMaxAttempts = config.outboxPoisonMaxAttempts,
+            respectRetryAfter = config.outboxRespectRetryAfter,
+            strictThreeSecondRetry = config.outboxStrictThreeSecondRetry,
+        )
+
+    /** 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())
+                    }
+                    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())
+                    }
+                    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
+            }
+
+            val config = 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())
+                    }
+                    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 }
+            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))
+                }
+                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<*, *>)
+            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 }
+            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
+    }
+
+    /**
+     * 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 {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("PRIVACY_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun maskElement(elementId: String, promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("PRIVACY_ERROR", e.message, e)
+        }
+    }
+
+    @ReactMethod
+    override fun unmaskElement(elementId: String, promise: Promise) {
+        try {
+            promise.resolve(null)
+        } catch (e: Exception) {
+            promise.reject("PRIVACY_ERROR", e.message, e)
+        }
+    }
+
+    // ─── 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 {
+            val transcript = voiceTranscriber?.stop()
+            val clip = voiceRecorder?.stop()
+            voiceRecorder = null
+            voiceTranscriber = null
+            if (clip == null) {
+                promise.resolve(null)
+                return
+            }
+            // Bytes are read into base64 by the recorder; drop the temp file now.
+            java.io.File(clip.filePath).delete()
+            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)
+        } 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
+    }
+}