@scalebun-release/react-native 2.5.0

package/ios/ReplaySdk.swift

@@ -0,0 +1,793 @@
+import Foundation
+import React
+import UIKit
+
+/// Main ReplaySdk native module (RCTEventEmitter subclass).
+/// Method signatures are exported to React Native via RCT_EXTERN_MODULE /
+/// RCT_EXTERN_METHOD in ReplaySdkBridge.m; this class holds the implementations
+/// and emits events to JS through `sendEvent(withName:body:)`.
+@objc(ReplaySdk)
+class ReplaySdk: RCTEventEmitter {
+
+    private var sessionManager: SessionManager?
+    private var transport: ReplayTransport?
+    private let interactionTracker = InteractionTracker()
+    private var nativeOutbox: NativeOutbox?
+    private var outboxUploader: OutboxUploader?
+    private var outboxConfig: ReplayConfig?
+    /// 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. Guarded by
+    /// `quotaLock`. Written by setOutboxLaneQuota (bridge method queue) and by the uploader's
+    /// onLaneParked callback (upload queue) when it parks a lane itself after a 402 / partial grant.
+    /// `outboxUploader` is published under the same lock (see attachQuota).
+    private var quotaBlockedLanes = Set<String>()
+    private let quotaLock = NSLock()
+
+    /// Events this module can emit to JS. Must match the JS NativeEventEmitter
+    /// listener names (ScaleBunNativeInteraction drives high-confidence touch capture).
+    override func supportedEvents() -> [String]! {
+        return [
+            "ReplaySdk_SessionStateChanged", "ReplaySdk_FrameCaptured",
+            "ReplaySdk_UploadProgress", "ReplaySdk_UploadComplete",
+            "ReplaySdk_UploadFailed", "ReplaySdk_Error",
+            "ReplaySdk_SessionLimitReached", "ReplaySdk_ScreenChanged",
+            "ReplaySdk_OutboxQuotaExceeded",
+            "ScaleBunNativeInteraction"
+        ]
+    }
+
+    @objc override static func requiresMainQueueSetup() -> Bool {
+        return false
+    }
+
+    /// Attach native touch tracking to the key window.
+    ///
+    /// RETRIED, AND RE-ATTACHED ON FOREGROUND — because the previous one-shot version is the most
+    /// likely explanation for iOS capturing coordinates on 0.4% of interactions where Android
+    /// manages 15.3%.
+    ///
+    /// It ran exactly once, 500 ms after `initialize()`. If `getKeyWindow()` returned nil at that
+    /// instant it logged a warning and never tried again, so native touch tracking was off for the
+    /// WHOLE app session. A cold start behind a heavy JS bundle, a slow device, or a scene-based
+    /// app whose key window is not the one that existed at +500 ms — any of those and no touch is
+    /// ever tracked. Losing that race once lost it permanently.
+    ///
+    /// Android never had the problem because it attaches from a lifecycle hook
+    /// (`ReplaySdkModule.onHostResume`), so every foreground corrects an attach that was too early.
+    /// This mirrors that: bounded retries for the cold-start race, plus a foreground observer that
+    /// attaches if a previous attempt never succeeded. `attach` is idempotent —
+    /// `guard !isActive else { return }` — so a redundant call costs nothing and cannot install a
+    /// second gesture recognizer.
+    ///
+    /// WHAT THIS DOES NOT FIX, stated because that same guard is why: a key window that CHANGES
+    /// after a successful attach. `attach` returns early on `isActive` without comparing the
+    /// window, so the tracker stays bound to the original one and the foreground observer cannot
+    /// help. That needs a detach-and-rebind inside `InteractionTracker`, which is a larger change
+    /// than the race this addresses. The cold-start race is the dominant cause — it costs the whole
+    /// session every time it is lost — and it is fixed here; the window-change case remains open.
+    private func activateNativeTracking() {
+        scheduleAttach(attemptsRemaining: 10)
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(reattachNativeTracking),
+            name: UIApplication.didBecomeActiveNotification,
+            object: nil
+        )
+    }
+
+    /// Try to attach, and try again shortly if there is no key window yet.
+    ///
+    /// Ten attempts at 500 ms covers about five seconds of startup, which is far longer than a
+    /// window takes to appear and short enough that a genuinely window-less process stops asking.
+    /// The last failure is logged at warn so a host that never gets tracking is told, rather than
+    /// discovering it as an empty heatmap.
+    private func scheduleAttach(attemptsRemaining: Int) {
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in
+            guard let self = self else { return }
+            guard let window = Self.getKeyWindow() else {
+                if attemptsRemaining > 1 {
+                    self.scheduleAttach(attemptsRemaining: attemptsRemaining - 1)
+                } else {
+                    ReplayLogger.warn(
+                        "Native tracking: no key window after repeated attempts — touch capture is off"
+                    )
+                }
+                return
+            }
+            self.interactionTracker.attach(to: window, sendEvent: { [weak self] name, payload in
+                self?.sendEvent(withName: name, body: payload)
+            })
+        }
+    }
+
+    /// Re-attach when the app becomes active, mirroring Android's `onHostResume`.
+    @objc private func reattachNativeTracking() {
+        guard let window = Self.getKeyWindow() else { return }
+        interactionTracker.attach(to: window, sendEvent: { [weak self] name, payload in
+            self?.sendEvent(withName: name, body: payload)
+        })
+    }
+
+    /// Matches what the other two observer-registering modules here do
+    /// (`SessionManager`, `ScaleBunProfilerModule`). A native module usually outlives the app's
+    /// interesting lifetime and selector observers have been zeroing-weak since iOS 9, so this is
+    /// hygiene rather than a crash fix — but being the one file that registers and never removes is
+    /// how a convention quietly stops being one.
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    private static func getKeyWindow() -> UIWindow? {
+        return WindowResolver.keyWindow()
+    }
+
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+
+    @objc func initialize(_ config: NSDictionary,
+                          resolve: @escaping RCTPromiseResolveBlock,
+                          reject: @escaping RCTPromiseRejectBlock) {
+        do {
+            let dict = config as? [String: Any] ?? [:]
+            let replayConfig = ReplayConfig(from: dict)
+            ReplayLogger.verbose = replayConfig.verboseLogging
+
+            sessionManager = SessionManager(config: replayConfig)
+            sessionManager?.onStateChanged = { [weak self] prev, next, sessionId in
+                self?.sendEvent(withName: "ReplaySdk_SessionStateChanged", body: [
+                    "sessionId": sessionId,
+                    "previousState": prev,
+                    "newState": next,
+                    "timestamp": Int(Date().timeIntervalSince1970 * 1000)
+                ])
+            }
+            sessionManager?.onFrameCaptured = { [weak self] frameId, sessionId, seq, screen, trigger, size in
+                self?.sendEvent(withName: "ReplaySdk_FrameCaptured", body: [
+                    "frameId": frameId,
+                    "sessionId": sessionId,
+                    "timestamp": Int(Date().timeIntervalSince1970 * 1000),
+                    "sequenceNumber": seq,
+                    "screenName": screen,
+                    "trigger": trigger,
+                    "sizeBytes": size
+                ])
+            }
+            sessionManager?.onLimitReached = { [weak self] limitType, current, max, sessionId in
+                self?.sendEvent(withName: "ReplaySdk_SessionLimitReached", body: [
+                    "sessionId": sessionId,
+                    "limitType": limitType,
+                    "currentValue": current,
+                    "maxValue": max
+                ])
+            }
+            // Forward screen changes to JS so the backend event stream gets SCREEN_VIEW events
+            sessionManager?.onScreenChanged = { [weak self] screenName in
+                self?.sendEvent(withName: "ReplaySdk_ScreenChanged", body: [
+                    "screenName": screenName,
+                    "timestamp": Int(Date().timeIntervalSince1970 * 1000)
+                ])
+            }
+
+            transport = ReplayTransport(endpoint: replayConfig.endpoint,
+                                        apiKey: replayConfig.apiKey,
+                                        maxRetries: replayConfig.maxRetryAttempts)
+
+            // Native file-based outbox (default-safe: only when explicitly enabled).
+            outboxConfig = replayConfig
+            if replayConfig.enableNativeFileOutbox {
+                let ob = NativeOutbox(maxBytes: Int64(replayConfig.outboxMaxBytes),
+                                      maxAgeMs: Int64(replayConfig.outboxMaxAgeMs))
+                nativeOutbox = ob
+                // startup recovery: requeue interrupted uploads, sweep orphans, drop
+                // committed frames that violate the mask policy (masked=false).
+                ob.recover(maskRequired: ReplaySdk.maskRequired(replayConfig))
+                if replayConfig.nativeOutboxUploadEnabled {
+                    let uploader = OutboxUploader(
+                        outbox: ob,
+                        apiBaseUrl: replayConfig.apiBaseUrl,
+                        clientKey: replayConfig.clientKey,
+                        useObjectStorageForFrames: replayConfig.useObjectStorageForFrames,
+                        maxUploadAttempts: replayConfig.outboxMaxUploadAttempts,
+                        retryIntervalMs: Int64(replayConfig.outboxRetryIntervalMs),
+                        poisonMaxAttempts: replayConfig.outboxPoisonMaxAttempts,
+                        respectRetryAfter: replayConfig.outboxRespectRetryAfter,
+                        strictThreeSecondRetry: replayConfig.outboxStrictThreeSecondRetry)
+                    attachQuota(uploader) // publishes outboxUploader under quotaLock
+                    uploader.flush()
+                }
+                ReplayLogger.info("Native file outbox enabled (upload=\(replayConfig.nativeOutboxUploadEnabled))")
+            }
+
+            ReplayLogger.info("Native module initialized")
+            self.activateNativeTracking()
+            resolve(true)
+        } catch {
+            reject("INIT_ERROR", error.localizedDescription, error)
+        }
+    }
+
+    @objc func startSession(_ resolve: @escaping RCTPromiseResolveBlock,
+                             reject: @escaping RCTPromiseRejectBlock) {
+        if let id = sessionManager?.startSession() {
+            resolve(id)
+        } else {
+            reject("SESSION_ERROR", "Failed to start session", nil)
+        }
+    }
+
+    @objc func stopSession(_ resolve: @escaping RCTPromiseResolveBlock,
+                            reject: @escaping RCTPromiseRejectBlock) {
+        resolve(sessionManager?.stopSession() ?? false)
+    }
+
+    @objc func pauseSession(_ resolve: @escaping RCTPromiseResolveBlock,
+                             reject: @escaping RCTPromiseRejectBlock) {
+        resolve(sessionManager?.pauseSession() ?? false)
+    }
+
+    @objc func resumeSession(_ resolve: @escaping RCTPromiseResolveBlock,
+                              reject: @escaping RCTPromiseRejectBlock) {
+        resolve(sessionManager?.resumeSession() ?? false)
+    }
+
+    // ─── Capture ────────────────────────────────────────────────────────
+
+    @objc func captureFrame(_ reason: String,
+                            resolve: @escaping RCTPromiseResolveBlock,
+                            reject: @escaping RCTPromiseRejectBlock) {
+        sessionManager?.captureFrame(trigger: reason) { frame in
+            if let frame = frame {
+                var result: [String: Any] = [
+                    "base64": frame["base64"] as? String ?? "",
+                    "width": frame["width"] as? Int ?? 0,
+                    "height": frame["height"] as? Int ?? 0,
+                    "sizeBytes": frame["sizeBytes"] as? Int ?? 0,
+                    "format": frame["format"] as? String ?? "jpeg",
+                    "timestamp": frame["timestamp"] as? Int ?? 0
+                ]
+                // Visible scroll containers at capture time (points). Absent = not measured.
+                if let scrollState = frame["scrollState"] as? [[String: Any]] {
+                    result["scrollState"] = scrollState
+                }
+                resolve(result)
+            } else {
+                resolve(NSNull())
+            }
+        } ?? resolve(NSNull())
+    }
+
+    @objc func captureManualFrame(_ resolve: @escaping RCTPromiseResolveBlock,
+                                   reject: @escaping RCTPromiseRejectBlock) {
+        captureFrame("manual", resolve: resolve, reject: reject)
+    }
+
+    /// Standalone screenshot capture — works WITHOUT session initialization.
+    /// Creates a temporary ScreenshotCaptureManager, captures, and destroys.
+    /// Used by scalebun-sdk's perfCaptureScreen command for performance screenshots.
+    @objc func captureScreenshot(_ reason: String,
+                                 resolve: @escaping RCTPromiseResolveBlock,
+                                 reject: @escaping RCTPromiseRejectBlock) {
+        let config = ReplayConfig(from: [:])
+        let captureManager = ScreenshotCaptureManager(config: config)
+        captureManager.capture(
+            sessionId: "standalone",
+            screenName: "unknown",
+            trigger: reason
+        ) { frame in
+            // captureManager is retained by this closure until completion
+            _ = captureManager // prevent premature dealloc
+            if let frame = frame {
+                var result: [String: Any] = [
+                    "base64": frame["base64"] as? String ?? "",
+                    "width": frame["width"] as? Int ?? 0,
+                    "height": frame["height"] as? Int ?? 0,
+                    "sizeBytes": frame["sizeBytes"] as? Int ?? 0,
+                    "format": frame["format"] as? String ?? "jpeg",
+                    "timestamp": frame["timestamp"] as? Int ?? 0
+                ]
+                // Visible scroll containers at capture time (points). Absent = not measured.
+                if let scrollState = frame["scrollState"] as? [[String: Any]] {
+                    result["scrollState"] = scrollState
+                }
+                resolve(result)
+            } else {
+                resolve(NSNull())
+            }
+        }
+    }
+
+    // ─── 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.
+    /// Whether the active masking policy requires masking (drives recover() orphan sweep).
+    static func maskRequired(_ c: ReplayConfig) -> Bool {
+        return c.maskTextInputs || c.maskImages || !c.maskedElementIds.isEmpty
+    }
+
+    /// Idempotent: a no-op once the outbox exists. Resolves false when the flag is
+    /// off or already initialized.
+    @objc func initOutbox(_ config: NSDictionary,
+                          resolve: @escaping RCTPromiseResolveBlock,
+                          reject: @escaping RCTPromiseRejectBlock) {
+        if nativeOutbox != nil { resolve(true); return }
+        let dict = config as? [String: Any] ?? [:]
+        let replayConfig = ReplayConfig(from: dict)
+        if !replayConfig.enableNativeFileOutbox { resolve(false); return }
+        outboxConfig = replayConfig
+        let ob = NativeOutbox(maxBytes: Int64(replayConfig.outboxMaxBytes),
+                              maxAgeMs: Int64(replayConfig.outboxMaxAgeMs))
+        nativeOutbox = ob
+        ob.recover(maskRequired: ReplaySdk.maskRequired(replayConfig))
+        if replayConfig.nativeOutboxUploadEnabled {
+            let uploader = OutboxUploader(
+                outbox: ob,
+                apiBaseUrl: replayConfig.apiBaseUrl,
+                clientKey: replayConfig.clientKey,
+                useObjectStorageForFrames: replayConfig.useObjectStorageForFrames,
+                maxUploadAttempts: replayConfig.outboxMaxUploadAttempts,
+                retryIntervalMs: Int64(replayConfig.outboxRetryIntervalMs),
+                poisonMaxAttempts: replayConfig.outboxPoisonMaxAttempts,
+                respectRetryAfter: replayConfig.outboxRespectRetryAfter,
+                strictThreeSecondRetry: replayConfig.outboxStrictThreeSecondRetry)
+            attachQuota(uploader) // publishes outboxUploader under quotaLock
+            uploader.flush()
+        }
+        ReplayLogger.info("Native file outbox bootstrapped (upload=\(replayConfig.nativeOutboxUploadEnabled))")
+        resolve(true)
+    }
+
+    /// Capture a screenshot to the durable native outbox. Returns metadata ONLY —
+    /// no base64 crosses the bridge. Resolves null on failure / when outbox disabled.
+    @objc func captureScreenshotToFile(_ input: NSDictionary,
+                                       resolve: @escaping RCTPromiseResolveBlock,
+                                       reject: @escaping RCTPromiseRejectBlock) {
+        guard let ob = nativeOutbox else {
+            reject("OUTBOX_DISABLED", "enableNativeFileOutbox is off", nil); return
+        }
+        // frames quota exhausted: don't spend CPU/disk capturing a frame that can never upload.
+        if isLaneQuotaBlocked(NativeOutbox.FRAMES) { resolve(NSNull()); return }
+        let dict = input as? [String: Any] ?? [:]
+        guard let sessionId = dict["sessionId"] as? String, !sessionId.isEmpty else {
+            reject("OUTBOX_ARG", "sessionId required", nil); return
+        }
+        let screenName = dict["screenName"] as? String ?? "unknown"
+        let trigger = dict["trigger"] as? String ?? "manual"
+        let cfg = outboxConfig ?? ReplayConfig(from: [:])
+
+        ob.initSession(sessionId, screenName)
+        let cm = ScreenshotCaptureManager(config: cfg)
+        cm.captureToData(sessionId: sessionId, screenName: screenName, trigger: trigger) { frame, data in
+            _ = cm // retain until completion
+            guard let meta = frame, let bytes = data else { resolve(NSNull()); return }
+            let frameId = meta["frameId"] as? String ?? ""
+            let format = meta["format"] as? String ?? "jpeg"
+            // Stage IMAGE ONLY — JS (ReplayCaptureManager) decides keyframe/delta +
+            // change-detection, then calls commitOutboxFrame (writes meta) or
+            // discardOutboxFrame (suppressed). No metadata json is written here.
+            guard let localFile = ob.writeFrameImage(sessionId, frameId, format, bytes) else {
+                resolve(NSNull()); return
+            }
+            var result: [String: Any] = [
+                "frameId": frameId,
+                "sessionId": sessionId,
+                "localPath": localFile,
+                "width": meta["width"] ?? 0,
+                "height": meta["height"] ?? 0,
+                "sizeBytes": meta["sizeBytes"] ?? 0,
+                "format": format,
+                "contentType": meta["contentType"] ?? "image/jpeg",
+                "timestamp": meta["timestamp"] ?? 0,
+                "screenName": screenName,
+                "trigger": trigger,
+                "masked": meta["masked"] ?? false,
+                // Cheap content hash so the JS change-detector works without base64.
+                "frameHash": ReplaySdk.fnv1a(bytes),
+            ]
+            // Visible scroll containers at capture time (points). Absent = not measured.
+            if let scrollState = meta["scrollState"] as? [[String: Any]] {
+                result["scrollState"] = scrollState
+            }
+            resolve(result)
+        }
+    }
+
+    // ─── Per-feature quota (shared contract v1) ─────────────────────────
+
+    private func isLaneQuotaBlocked(_ lane: String) -> Bool {
+        quotaLock.lock(); defer { quotaLock.unlock() }
+        return quotaBlockedLanes.contains(lane)
+    }
+
+    /// Apply the module's parked lanes to a freshly built uploader and route its 402s back to JS.
+    private func 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 = { [weak self] status, body, retryAfterMs, sessionId in
+            self?.sendEvent(withName: "ReplaySdk_OutboxQuotaExceeded", body: [
+                "status": status,
+                "body": body,
+                "retryAfterMs": retryAfterMs,
+                "sessionId": sessionId,
+            ])
+        }
+        // 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 = { [weak self] lane in
+            guard let self = self else { return }
+            self.quotaLock.lock()
+            self.quotaBlockedLanes.insert(lane)
+            self.quotaLock.unlock()
+        }
+        // Publish the uploader and apply the parked set UNDER quotaLock — the lock setOutboxLaneQuota
+        // holds while it reads `outboxUploader` — so a park/un-park racing this is never lost, without
+        // relying on the bridge's serial method queue: either it is in the set read here, or it sees
+        // the published uploader and applies itself.
+        quotaLock.lock()
+        outboxUploader = uploader
+        for lane in quotaBlockedLanes { uploader.setLaneQuotaBlocked(lane, true) }
+        quotaLock.unlock()
+    }
+
+    /// Park + purge (blocked) or un-park a lane. Resolves the number of files purged (0 on
+    /// un-park, or when the outbox does not exist yet — the block is still remembered and applied
+    /// when it is built).
+    @objc func setOutboxLaneQuota(_ lane: String,
+                                  blocked: Bool,
+                                  resolve: @escaping RCTPromiseResolveBlock,
+                                  reject: @escaping RCTPromiseRejectBlock) {
+        // Only the lanes of LIMITED features can be parked; errors/logs/performance never.
+        guard OutboxUploader.QUOTA_FEATURE_LANES.values.contains(lane) else { resolve(0); return }
+        var removed = 0
+        quotaLock.lock()
+        if blocked { quotaBlockedLanes.insert(lane) } else { quotaBlockedLanes.remove(lane) }
+        if let uploader = outboxUploader {
+            // Purge runs on the uploader's queue, serialized with any in-flight drain.
+            uploader.setLaneQuotaBlocked(lane, blocked)
+        } else if blocked, let ob = nativeOutbox {
+            removed = ob.purgeLane(lane)
+        }
+        quotaLock.unlock()
+        resolve(removed)
+    }
+
+    /// Commit a staged frame: write metadata json carrying JS-authoritative
+    /// sequenceNumber/frameType/baseFrameId. Resolves the meta path or null.
+    @objc func commitOutboxFrame(_ input: NSDictionary,
+                                 resolve: @escaping RCTPromiseResolveBlock,
+                                 reject: @escaping RCTPromiseRejectBlock) {
+        guard let ob = nativeOutbox else { resolve(NSNull()); return }
+        let meta = (input as? [String: Any]) ?? [:]
+        if isLaneQuotaBlocked(NativeOutbox.FRAMES) {
+            // frames quota exhausted: the staged image is discarded, never made uploadable.
+            if let sid = meta["sessionId"] as? String, let fid = meta["frameId"] as? String {
+                ob.discardFrame(sid, fid)
+            }
+            resolve(NSNull()); return
+        }
+        guard let path = ob.commitFrame(meta) else { resolve(NSNull()); return }
+        outboxUploader?.flush()
+        resolve(path)
+    }
+
+    /// Discard a staged frame the JS orchestrator suppressed (no upload).
+    @objc func discardOutboxFrame(_ sessionId: String,
+                                  frameId: String,
+                                  resolve: @escaping RCTPromiseResolveBlock,
+                                  reject: @escaping RCTPromiseRejectBlock) {
+        nativeOutbox?.discardFrame(sessionId, frameId)
+        resolve(true)
+    }
+
+    /// Append non-frame telemetry records to the session's JSONL segment outbox.
+    /// Resolves false if the outbox is disabled (JS falls back to its own path).
+    @objc func enqueueOutboxRecords(_ lane: String,
+                                    sessionId: String,
+                                    records: NSArray,
+                                    resolve: @escaping RCTPromiseResolveBlock,
+                                    reject: @escaping RCTPromiseRejectBlock) {
+        guard let ob = nativeOutbox else { resolve(false); return }
+        if sessionId.isEmpty { resolve(false); return }
+        // Quota-parked lane: accept-and-discard (true), so JS does not fall back to posting records
+        // the server would refuse.
+        if isLaneQuotaBlocked(lane) { resolve(true); return }
+        ob.initSession(sessionId, "unknown")
+        let list = (records as? [[String: Any]]) ?? []
+        ob.appendTelemetry(sessionId, lane, list, laneFlushCount(lane), 256 * 1024)
+        outboxUploader?.flush()
+        resolve(true)
+    }
+
+    @objc func flushNativeOutbox(_ resolve: @escaping RCTPromiseResolveBlock,
+                                 reject: @escaping RCTPromiseRejectBlock) {
+        guard let ob = nativeOutbox else { resolve(false); return }
+        for sid in ob.listSessionIds() { ob.closeAllOpenSegments(sid) }
+        outboxUploader?.flush()
+        resolve(true)
+    }
+
+    @objc func recoverNativeOutbox(_ resolve: @escaping RCTPromiseResolveBlock,
+                                   reject: @escaping RCTPromiseRejectBlock) {
+        nativeOutbox?.recover()
+        resolve(true)
+    }
+
+    @objc func getOutboxStats(_ resolve: @escaping RCTPromiseResolveBlock,
+                              reject: @escaping RCTPromiseRejectBlock) {
+        guard let ob = nativeOutbox else { resolve(NSNull()); return }
+        resolve([
+            "enabled": true,
+            "uploadEnabled": outboxUploader != nil,
+            "totalBytes": ob.totalBytes(),
+            "sessionCount": ob.listSessionIds().count,
+        ])
+    }
+
+    private func laneFlushCount(_ lane: String) -> Int {
+        switch lane {
+        case "events": return 30
+        case "logs": return 50
+        case "network": return 50
+        case "errors": return 20
+        case "performance": return 50
+        default: return 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.
+    static func fnv1a(_ data: Data) -> String {
+        var h: UInt32 = 0x811c9dc5
+        let len = data.count
+        let step = len > 4096 ? (len / 4096 + 1) : 1
+        var i = 0
+        while i < len {
+            h ^= UInt32(data[i])
+            h = h &* 0x01000193
+            i += step
+        }
+        return String(h, radix: 36) + "-" + String(len, radix: 36)
+    }
+
+    // ─── Voice notes (Slice D) ──────────────────────────────────────────
+
+    private static var voiceRecorder: VoiceRecorder?
+
+    @objc func startVoiceRecording(_ resolve: @escaping RCTPromiseResolveBlock,
+                                   reject: @escaping RCTPromiseRejectBlock) {
+        let recorder = VoiceRecorder()
+        Self.voiceRecorder = recorder
+        recorder.start { granted, err in
+            if granted {
+                resolve(NSNull())
+            } else {
+                Self.voiceRecorder = nil
+                reject("VOICE_START", err ?? "could not start recording", nil)
+            }
+        }
+    }
+
+    @objc func stopVoiceRecording(_ resolve: @escaping RCTPromiseResolveBlock,
+                                  reject: @escaping RCTPromiseRejectBlock) {
+        guard let recorder = Self.voiceRecorder else { resolve(NSNull()); return }
+        recorder.stop { clip in
+            Self.voiceRecorder = nil
+            guard let clip = clip else { resolve(NSNull()); return }
+            resolve([
+                "base64": clip.base64,
+                "mime": "audio/mp4",
+                "durationMs": clip.durationMs,
+                "byteSize": clip.byteSize,
+                "transcript": clip.transcript,
+                "transcriptAvailable": clip.transcriptAvailable,
+            ])
+        }
+    }
+
+    @objc func cancelVoiceRecording(_ resolve: @escaping RCTPromiseResolveBlock,
+                                    reject: @escaping RCTPromiseRejectBlock) {
+        Self.voiceRecorder?.cancel()
+        Self.voiceRecorder = nil
+        resolve(NSNull())
+    }
+
+    // ─── Configuration ──────────────────────────────────────────────────
+
+    @objc func setEnabled(_ enabled: Bool,
+                          resolve: @escaping RCTPromiseResolveBlock,
+                          reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    @objc func setCapturingMode(_ mode: String,
+                                resolve: @escaping RCTPromiseResolveBlock,
+                                reject: @escaping RCTPromiseRejectBlock) {
+        // Apply the runtime capture-mode change (e.g. admin-forced 'frequency' via /config, or a
+        // revert to the developer's mode). Dispatched to main so the frequency Timer schedules on
+        // the main run loop. Unknown modes are ignored (leaves the current mode intact).
+        if let m = CaptureMode(rawValue: mode) {
+            DispatchQueue.main.async { [weak self] in
+                self?.sessionManager?.setCaptureMode(m)
+            }
+        }
+        resolve(NSNull())
+    }
+
+    @objc func setScreenshotQuality(_ quality: String,
+                                    resolve: @escaping RCTPromiseResolveBlock,
+                                    reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    @objc func setScreenshotCaptureInterval(_ intervalMs: Double,
+                                            resolve: @escaping RCTPromiseResolveBlock,
+                                            reject: @escaping RCTPromiseRejectBlock) {
+        // Apply the frequency-mode capture interval (paired with setCapturingMode('frequency') by
+        // the admin override). Dispatched to main so the Timer re-arms on the main run loop.
+        DispatchQueue.main.async { [weak self] in
+            self?.sessionManager?.setScreenshotInterval(Int(intervalMs))
+        }
+        resolve(NSNull())
+    }
+
+    @objc func setUserStepsEnabled(_ enabled: Bool,
+                                   resolve: @escaping RCTPromiseResolveBlock,
+                                   reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    @objc func setNetworkLogsEnabled(_ enabled: Bool,
+                                     resolve: @escaping RCTPromiseResolveBlock,
+                                     reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    @objc func setSdkLogsEnabled(_ enabled: Bool,
+                                 resolve: @escaping RCTPromiseResolveBlock,
+                                 reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    // ─── Privacy ────────────────────────────────────────────────────────
+
+    @objc func setPrivacyOptions(_ options: NSDictionary,
+                                 resolve: @escaping RCTPromiseResolveBlock,
+                                 reject: @escaping RCTPromiseRejectBlock) {
+        // Was a no-op stub — the runtime toggle silently did nothing (only a restart, which
+        // re-reads the init config, honoured it). Each supplied key merges onto the running
+        // config via SessionManager.updatePrivacy → the capture manager; absent keys stay nil →
+        // unchanged, so a partial setPrivacy call never resets the other fields.
+        sessionManager?.updatePrivacy(
+            disableScreenshots: options["disableScreenshots"] as? Bool,
+            maskTextInputs: options["maskTextInputs"] as? Bool,
+            maskImages: options["maskImages"] as? Bool,
+            ignoredScreens: options["ignoredScreens"] as? [String],
+            maskedElementIds: options["maskedElementIds"] as? [String]
+        )
+        resolve(NSNull())
+    }
+
+    @objc func maskElement(_ elementId: String,
+                           resolve: @escaping RCTPromiseResolveBlock,
+                           reject: @escaping RCTPromiseRejectBlock) {
+        sessionManager?.addMaskedElement(elementId)
+        resolve(NSNull())
+    }
+
+    @objc func unmaskElement(_ elementId: String,
+                             resolve: @escaping RCTPromiseResolveBlock,
+                             reject: @escaping RCTPromiseRejectBlock) {
+        sessionManager?.removeMaskedElement(elementId)
+        resolve(NSNull())
+    }
+
+    // ─── User ───────────────────────────────────────────────────────────
+
+    @objc func setUser(_ user: NSDictionary,
+                       resolve: @escaping RCTPromiseResolveBlock,
+                       reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    @objc func clearUser(_ resolve: @escaping RCTPromiseResolveBlock,
+                         reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    // ─── Breadcrumbs ────────────────────────────────────────────────────
+
+    @objc func addBreadcrumb(_ breadcrumb: NSDictionary,
+                             resolve: @escaping RCTPromiseResolveBlock,
+                             reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    @objc func addNetworkBreadcrumb(_ request: NSDictionary,
+                                    resolve: @escaping RCTPromiseResolveBlock,
+                                    reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    // ─── Screen / Interaction ─────────────────────────────────────────
+
+    @objc func setCurrentScreen(_ screenName: String,
+                                resolve: @escaping RCTPromiseResolveBlock,
+                                reject: @escaping RCTPromiseRejectBlock) {
+        sessionManager?.setCurrentScreen(screenName)
+        resolve(NSNull())
+    }
+
+    @objc func reportInteraction(_ interaction: NSDictionary,
+                                 resolve: @escaping RCTPromiseResolveBlock,
+                                 reject: @escaping RCTPromiseRejectBlock) {
+        if sessionManager?.state == .recording {
+            let trigger = interaction["type"] as? String ?? "interaction"
+            sessionManager?.captureFrame(trigger: trigger) { _ in }
+        }
+        resolve(NSNull())
+    }
+
+    // ─── Query ──────────────────────────────────────────────────────────
+
+    @objc func getSessionInfo(_ resolve: @escaping RCTPromiseResolveBlock,
+                              reject: @escaping RCTPromiseRejectBlock) {
+        resolve(sessionManager?.getSessionInfo() as Any)
+    }
+
+    @objc func getDeviceInfo(_ resolve: @escaping RCTPromiseResolveBlock,
+                             reject: @escaping RCTPromiseRejectBlock) {
+        let device = UIDevice.current
+        let screen = UIScreen.main
+        let bundle = Bundle.main
+        resolve([
+            "platform": "ios",
+            "osVersion": device.systemVersion,
+            // NOT device.model — that is the family ("iPhone"), identical on every iPhone ever
+            // made. ScaleBunDeviceIdentity reports the hardware identifier, which is unique per model.
+            "deviceModel": ScaleBunDeviceIdentity.modelIdentifier(),
+            "screenWidth": Int(screen.bounds.width * screen.scale),
+            "screenHeight": Int(screen.bounds.height * screen.scale),
+            "pixelDensity": screen.scale,
+            "appName": bundle.object(forInfoDictionaryKey: "CFBundleDisplayName") as? String ?? "",
+            "appVersion": bundle.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "0.0.0",
+            "bundleId": bundle.bundleIdentifier ?? "",
+            "locale": Locale.current.identifier
+        ])
+    }
+
+    @objc func getSessionReplayLink(_ resolve: @escaping RCTPromiseResolveBlock,
+                                    reject: @escaping RCTPromiseRejectBlock) {
+        if let id = sessionManager?.sessionId {
+            resolve(["url": "", "sessionId": id, "uploaded": false])
+        } else {
+            resolve(NSNull())
+        }
+    }
+
+    // ─── Upload ─────────────────────────────────────────────────────────
+
+    @objc func flushUpload(_ resolve: @escaping RCTPromiseResolveBlock,
+                           reject: @escaping RCTPromiseRejectBlock) {
+        resolve(true)
+    }
+
+    @objc func cancelUpload(_ resolve: @escaping RCTPromiseResolveBlock,
+                            reject: @escaping RCTPromiseRejectBlock) {
+        resolve(NSNull())
+    }
+
+    // ─── Cleanup ────────────────────────────────────────────────────────
+
+    @objc func destroy(_ resolve: @escaping RCTPromiseResolveBlock,
+                       reject: @escaping RCTPromiseRejectBlock) {
+        interactionTracker.detach()
+        sessionManager?.destroy()
+        transport?.destroy()
+        sessionManager = nil
+        transport = nil
+        outboxUploader = nil
+        nativeOutbox = nil
+        ReplayLogger.info("Native module destroyed")
+        resolve(NSNull())
+    }
+}