@scalebun-release/react-native 2.5.0

package/ios/Capture/ScreenshotCaptureManager.swift

@@ -0,0 +1,398 @@
+import UIKit
+import ImageIO
+import UniformTypeIdentifiers // P2-2: UTType.avif for AVIF encode (iOS 16+)
+
+/// iOS Screenshot Capture Manager
+///
+/// Captures screenshots from the key window using UIGraphicsImageRenderer.
+/// Supports quality presets, scaling, grayscale, and JPEG compression.
+///
+/// Thread safety: capture runs on the main thread (UIKit requirement),
+/// compression runs on a background queue.
+class ScreenshotCaptureManager {
+    private var config: ReplayConfig
+    private var sequenceNumber: Int = 0
+    private var lastCaptureTime: TimeInterval = 0
+    private let minCaptureInterval: TimeInterval = 0.2 // 200ms hard floor
+    private let compressionQueue = DispatchQueue(label: "com.scalebun.replaysdk.compression", qos: .utility)
+
+    init(config: ReplayConfig) {
+        self.config = config
+    }
+
+    func updateConfig(_ config: ReplayConfig) {
+        self.config = config
+    }
+
+    func reset() {
+        sequenceNumber = 0
+        lastCaptureTime = 0
+    }
+
+    /// Capture a screenshot from the key window.
+    /// - Parameters:
+    ///   - sessionId: Current session ID
+    ///   - screenName: Current screen name
+    ///   - trigger: What triggered this capture
+    ///   - completion: Called with frame data or nil on failure
+    func capture(
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        completion: @escaping ([String: Any]?) -> Void
+    ) {
+        // Throttle
+        let now = Date().timeIntervalSince1970
+        if now - lastCaptureTime < minCaptureInterval {
+            ReplayLogger.debug("Capture throttled")
+            completion(nil)
+            return
+        }
+        lastCaptureTime = now
+
+        // Must access UIKit on main thread
+        DispatchQueue.main.async { [self] in
+            // P2-6 hardening (suspected iOS "empty session" cause): the key window can
+            // be transiently nil during scene-lifecycle transitions (connecting scene,
+            // backgrounded scene, no foregroundActive scene yet). Instead of dropping
+            // the frame on the first nil, fall back to ANY visible window before giving
+            // up, and log enough context to diagnose. PENDING REAL-DEVICE CONFIRMATION —
+            // cannot be runtime-verified without an iOS device/simulator.
+            let resolvedWindow = Self.getKeyWindow() ?? WindowResolver.allVisibleWindows().first
+            guard let window = resolvedWindow else {
+                let sceneCount = UIApplication.shared.connectedScenes.count
+                ReplayLogger.warn("No key window available (no usable window; connectedScenes=\(sceneCount)) — frame skipped")
+                completion(nil)
+                return
+            }
+
+            guard window.bounds.width > 0 && window.bounds.height > 0 else {
+                ReplayLogger.debug("Window has zero dimensions")
+                completion(nil)
+                return
+            }
+
+            // Composite EVERY on-screen window into the base window's coordinate
+            // space, back-to-front by window level. A native UIAlertController lives
+            // in its own `.alert`-level UIWindow, so rendering only the key window
+            // (the previous behavior) dropped alerts/action-sheets from the frame.
+            // Each extra window is translated by its origin delta vs. the base
+            // window so off-origin overlays land in the right place; full-screen
+            // alert windows share the base origin and overlay 1:1.
+            // Scroll containers read on main, from the captured window, immediately before
+            // its pixels are rendered — so the offsets describe this frame.
+            let scrollState = Self.visibleScrollState(in: window)
+
+            let bounds = window.bounds
+            var windows = WindowResolver.allVisibleWindows()
+            if windows.isEmpty { windows = [window] }
+            if windows.count > 1 {
+                ReplayLogger.debug("Compositing \(windows.count) windows (alert/overlay present)")
+            }
+            let baseOrigin = window.frame.origin
+            let renderer = UIGraphicsImageRenderer(bounds: bounds)
+            let rawImage = renderer.image { context in
+                for w in windows {
+                    let dx = w.frame.origin.x - baseOrigin.x
+                    let dy = w.frame.origin.y - baseOrigin.y
+                    context.cgContext.saveGState()
+                    context.cgContext.translateBy(x: dx, y: dy)
+                    w.drawHierarchy(in: w.bounds, afterScreenUpdates: false)
+                    context.cgContext.restoreGState()
+                }
+            }
+
+            // Apply privacy masking while we still have access to the view hierarchy.
+            // This must run on the main thread (UIView hierarchy walking).
+            let image = PrivacyMaskProcessor.applyMasking(
+                image: rawImage,
+                rootView: window,
+                config: self.config
+            )
+
+            // Scale and compress on background thread
+            self.compressionQueue.async { [self] in
+                self.processImage(
+                    image,
+                    sessionId: sessionId,
+                    screenName: screenName,
+                    trigger: trigger,
+                    scrollState: scrollState,
+                    completion: completion
+                )
+            }
+        }
+    }
+
+    /// Capture to raw encoded bytes (NO base64) for the native file outbox path.
+    /// Hands back (frame metadata, image Data) — bytes never cross the JS bridge.
+    func captureToData(
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        completion: @escaping ([String: Any]?, Data?) -> Void
+    ) {
+        DispatchQueue.main.async { [self] in
+            let resolvedWindow = Self.getKeyWindow() ?? WindowResolver.allVisibleWindows().first
+            guard let window = resolvedWindow,
+                  window.bounds.width > 0, window.bounds.height > 0 else {
+                completion(nil, nil)
+                return
+            }
+            // Scroll containers read on main, from the captured window, immediately before
+            // its pixels are rendered — so the offsets describe this frame.
+            let scrollState = Self.visibleScrollState(in: window)
+            let bounds = window.bounds
+            var windows = WindowResolver.allVisibleWindows()
+            if windows.isEmpty { windows = [window] }
+            let baseOrigin = window.frame.origin
+            let renderer = UIGraphicsImageRenderer(bounds: bounds)
+            let rawImage = renderer.image { context in
+                for w in windows {
+                    let dx = w.frame.origin.x - baseOrigin.x
+                    let dy = w.frame.origin.y - baseOrigin.y
+                    context.cgContext.saveGState()
+                    context.cgContext.translateBy(x: dx, y: dy)
+                    w.drawHierarchy(in: w.bounds, afterScreenUpdates: false)
+                    context.cgContext.restoreGState()
+                }
+            }
+            let image = PrivacyMaskProcessor.applyMasking(image: rawImage, rootView: window, config: self.config)
+            self.compressionQueue.async { [self] in
+                self.processToData(image, sessionId: sessionId, screenName: screenName,
+                                   trigger: trigger, scrollState: scrollState, completion: completion)
+            }
+        }
+    }
+
+    private func processToData(
+        _ image: UIImage,
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        scrollState: [[String: Any]],
+        completion: @escaping ([String: Any]?, Data?) -> Void
+    ) {
+        let sizes = frameSizes(for: image)
+        var resized = resize(image, to: sizes.pixels)
+        if config.screenshotQuality == .grayscale { resized = applyGrayscale(resized) ?? resized }
+
+        let quality = CGFloat(config.jpegQuality) / 100.0
+        var data: Data?
+        var actualFormat = "jpeg"
+        if config.format == "avif", #available(iOS 16.0, *),
+           let avif = Self.encodeAVIF(resized, quality: quality) {
+            data = avif; actualFormat = "avif"
+        }
+        if data == nil { data = resized.jpegData(compressionQuality: quality); actualFormat = "jpeg" }
+        guard let data = data else { completion(nil, nil); return }
+
+        sequenceNumber += 1
+        let masked = config.maskTextInputs || config.maskImages || !config.maskedElementIds.isEmpty
+        let frame: [String: Any] = [
+            "frameId": SessionIdGenerator.frameId(),
+            "sessionId": sessionId,
+            "timestamp": Int(Date().timeIntervalSince1970 * 1000),
+            "sequenceNumber": sequenceNumber,
+            "screenName": screenName,
+            "trigger": trigger,
+            "format": actualFormat,
+            "contentType": "image/\(actualFormat)",
+            "sizeBytes": data.count,
+            "width": Int(sizes.reported.width),
+            "height": Int(sizes.reported.height),
+            "quality": config.screenshotQuality.rawValue,
+            "masked": masked,
+            "scrollState": scrollState,
+        ]
+        DispatchQueue.main.async { completion(frame, data) }
+    }
+
+    private func processImage(
+        _ image: UIImage,
+        sessionId: String,
+        screenName: String,
+        trigger: String,
+        scrollState: [[String: Any]],
+        completion: @escaping ([String: Any]?) -> Void
+    ) {
+        // Cap at maxWidth PIXELS (never upscale); see frameSizes.
+        let sizes = frameSizes(for: image)
+        var resized = resize(image, to: sizes.pixels)
+
+        // Grayscale
+        if config.screenshotQuality == .grayscale {
+            resized = applyGrayscale(resized) ?? resized
+        }
+
+        // P2-2 encode fallback chain (iOS): AVIF -> JPEG. iOS has no native WebP
+        // encoder, so the contract's AVIF->WebP->JPEG collapses to AVIF->JPEG here.
+        // AVIF encode via ImageIO is only available iOS 16+; below that (or on
+        // failure) we TRUTHFULLY fall back to JPEG and report the format we made.
+        let quality = CGFloat(config.jpegQuality) / 100.0
+        var data: Data?
+        var actualFormat = "jpeg"
+        if config.format == "avif", #available(iOS 16.0, *),
+           let avif = Self.encodeAVIF(resized, quality: quality) {
+            data = avif
+            actualFormat = "avif"
+        }
+        if data == nil {
+            data = resized.jpegData(compressionQuality: quality)
+            actualFormat = "jpeg"
+        }
+        guard let data = data else {
+            ReplayLogger.error("Image compression failed (avif+jpeg)")
+            completion(nil)
+            return
+        }
+
+        let base64 = data.base64EncodedString()
+        sequenceNumber += 1
+
+        let frame: [String: Any] = [
+            "frameId": SessionIdGenerator.frameId(),
+            "sessionId": sessionId,
+            "timestamp": Int(Date().timeIntervalSince1970 * 1000),
+            "sequenceNumber": sequenceNumber,
+            "screenName": screenName,
+            "trigger": trigger,
+            "format": actualFormat,
+            "sizeBytes": data.count,
+            "width": Int(sizes.reported.width),
+            "height": Int(sizes.reported.height),
+            "quality": config.screenshotQuality.rawValue,
+            "masked": config.maskTextInputs || config.maskImages,
+            "base64": base64,
+            "scrollState": scrollState
+        ]
+
+        DispatchQueue.main.async {
+            completion(frame)
+        }
+    }
+
+    // ─── Image Processing Helpers ──────────────────────────────────
+
+    /// Encoded pixel size and reported size for one frame.
+    ///
+    /// `maxWidth` is a PIXEL budget — Android encodes 720 px wide. It used to be compared against the
+    /// image's POINT width and the downscale rendered at the screen scale, so a 390-pt iPhone passed
+    /// the cap untouched and every frame encoded at 1170×2532: measured on prod 2026-09-23 at
+    /// 170–300 KB per iOS frame against ~25 KB on Android, ~89% of all mobile frame bytes.
+    ///
+    /// `reported` is deliberately unchanged — points, capped at maxWidth, exactly what iOS has always
+    /// sent. Tap placement and the viewport plausibility check read those numbers; only the encoded
+    /// pixels shrink.
+    private func frameSizes(for image: UIImage) -> (pixels: CGSize, reported: CGSize) {
+        let aspect = image.size.width > 0 ? image.size.height / image.size.width : 1
+        let reportedWidth = min(CGFloat(config.maxWidth), image.size.width)
+        let pixelWidth = min(CGFloat(config.maxWidth), image.size.width * image.scale).rounded()
+        return (
+            pixels: CGSize(width: pixelWidth, height: (pixelWidth * aspect).rounded()),
+            reported: CGSize(width: reportedWidth, height: reportedWidth * aspect)
+        )
+    }
+
+    /// Renders at scale 1, so `size` is the bitmap's pixel size. The default format uses the screen
+    /// scale, which multiplied every frame by 3× on current iPhones.
+    private func resize(_ image: UIImage, to size: CGSize) -> UIImage {
+        let format = UIGraphicsImageRendererFormat.default()
+        format.scale = 1
+        let renderer = UIGraphicsImageRenderer(size: size, format: format)
+        return renderer.image { _ in
+            image.draw(in: CGRect(origin: .zero, size: size))
+        }
+    }
+
+    private func applyGrayscale(_ image: UIImage) -> UIImage? {
+        guard let cgImage = image.cgImage else { return nil }
+        let context = CIContext()
+        let ciImage = CIImage(cgImage: cgImage)
+        guard let filter = CIFilter(name: "CIColorControls") else { return nil }
+        filter.setValue(ciImage, forKey: kCIInputImageKey)
+        filter.setValue(0.0, forKey: kCIInputSaturationKey)
+        guard let output = filter.outputImage,
+              let cgOutput = context.createCGImage(output, from: output.extent) else { return nil }
+        return UIImage(cgImage: cgOutput)
+    }
+
+    // ─── Scroll State ──────────────────────────────────────────────
+
+    /// EVERY visible UIScrollView in `window`, read at capture time. MUST run on the main thread.
+    ///
+    /// A frame carrying only width/height cannot say whether a tap belongs on it: a tap inside a
+    /// list scrolled 900pt lands on different content than the same point on a frame taken at 0.
+    /// With this beside the pixels, a tap is compatible with a frame when its container reports
+    /// the same offset in both. Same keys and same classification as
+    /// `InteractionTracker.scrollChain(from:)` (a tap's scroll context), in points.
+    ///
+    /// Bounded because it runs inside every capture: depth <= 64, at most 2000 views visited,
+    /// hidden/transparent subtrees skipped whole. Largest on-screen visible area first, at most 4.
+    /// Never fails: an empty array is always an acceptable answer.
+    static func visibleScrollState(in window: UIWindow) -> [[String: Any]] {
+        let windowBounds = window.bounds
+        guard windowBounds.width > 0, windowBounds.height > 0 else { return [] }
+        var found: [(entry: [String: Any], area: CGFloat)] = []
+        var stack: [(view: UIView, depth: Int)] = [(window, 0)]
+        var visited = 0
+        let tagSelector = NSSelectorFromString("reactTag")
+        while visited < 2000, let item = stack.popLast() {
+            let view = item.view
+            let depth = item.depth
+            visited += 1
+            if view.isHidden || view.alpha < 0.01 { continue }
+            if let sv = view as? UIScrollView {
+                let visible = sv.convert(sv.bounds, to: window).intersection(windowBounds)
+                let area = visible.isNull ? 0 : visible.width * visible.height
+                if area > 0, area.isFinite {
+                    var entry: [String: Any] = [
+                        "kind": "scroll",
+                        "horizontal": sv.contentSize.width > sv.bounds.width + 1,
+                        "offsetX": Double(sv.contentOffset.x),
+                        "offsetY": Double(sv.contentOffset.y),
+                        "contentWidth": Double(sv.contentSize.width),
+                        "contentHeight": Double(sv.contentSize.height),
+                        "viewportWidth": Double(sv.bounds.width),
+                        "viewportHeight": Double(sv.bounds.height)
+                    ]
+                    if sv.responds(to: tagSelector), let tag = sv.value(forKey: "reactTag") as? NSNumber {
+                        entry["containerTag"] = tag.intValue
+                    }
+                    found.append((entry: entry, area: area))
+                }
+            }
+            if depth < 64 {
+                // Reverse push so subviews[0] is visited first: depth-first, document order.
+                for child in view.subviews.reversed() {
+                    stack.append((view: child, depth: depth + 1))
+                }
+            }
+        }
+        found.sort { $0.area > $1.area }
+        return found.prefix(4).map { $0.entry }
+    }
+
+    // ─── Key Window Helper ──────────────────────────────────────────
+
+    private static func getKeyWindow() -> UIWindow? {
+        return WindowResolver.keyWindow()
+    }
+
+    // P2-2: encode a UIImage to AVIF via ImageIO (iOS 16+). Returns nil if the
+    // platform can't encode AVIF (caller falls back to JPEG). Quality 0..1.
+    @available(iOS 16.0, *)
+    private static func encodeAVIF(_ image: UIImage, quality: CGFloat) -> Data? {
+        guard let cg = image.cgImage else { return nil }
+        let out = NSMutableData()
+        // Resolve the AVIF UTI by identifier at runtime: `UTType.avif` is not a
+        // static member on any current SDK, so referencing it fails to compile.
+        // `UTType("public.avif")` resolves at runtime; nil → caller falls back to JPEG.
+        guard let avifType = UTType("public.avif")?.identifier as CFString? else { return nil }
+        guard let dest = CGImageDestinationCreateWithData(out, avifType, 1, nil) else { return nil }
+        let opts: [CFString: Any] = [kCGImageDestinationLossyCompressionQuality: quality]
+        CGImageDestinationAddImage(dest, cg, opts as CFDictionary)
+        guard CGImageDestinationFinalize(dest) else { return nil }
+        return out as Data
+    }
+}

package/ios/Capture/WindowResolver.swift

@@ -0,0 +1,63 @@
+import UIKit
+
+/// Resolves a usable UIWindow for screenshot capture and touch tracking.
+///
+/// `isKeyWindow` is frequently false in real apps (during transitions, when a
+/// system overlay is key, or before the app finishes activating), which made the
+/// previous `first { $0.isKeyWindow }` lookup return nil and silently abort frame
+/// capture. This resolver falls back through progressively looser criteria so a
+/// window is found whenever the app actually has one on screen.
+enum WindowResolver {
+    static func keyWindow() -> UIWindow? {
+        if #available(iOS 15.0, *) {
+            let scenes = UIApplication.shared.connectedScenes
+                .compactMap { $0 as? UIWindowScene }
+
+            // Prefer the foreground-active scene's key window, then any of its windows.
+            let activeScenes = scenes.filter { $0.activationState == .foregroundActive }
+            if let w = firstUsable(in: activeScenes) { return w }
+
+            // Fall back to any connected scene.
+            if let w = firstUsable(in: scenes) { return w }
+            return nil
+        } else {
+            let windows = UIApplication.shared.windows
+            return windows.first { $0.isKeyWindow }
+                ?? windows.first { !$0.isHidden && $0.bounds.width > 0 }
+                ?? windows.first
+        }
+    }
+
+    @available(iOS 15.0, *)
+    private static func firstUsable(in scenes: [UIWindowScene]) -> UIWindow? {
+        let windows = scenes.flatMap { $0.windows }
+        return windows.first { $0.isKeyWindow }
+            ?? windows.first { !$0.isHidden && $0.bounds.width > 0 }
+            ?? windows.first
+    }
+
+    /// All on-screen windows for the active scene, ordered back-to-front by
+    /// `windowLevel`. UIKit renders a `UIAlertController` (and action sheets,
+    /// system text-edit menus, etc.) in a SEPARATE UIWindow at `.alert` level —
+    /// higher than the app's normal window — so a single-window screenshot misses
+    /// it entirely. Compositing these in level order reproduces what the user sees.
+    ///
+    /// Returns an empty array when no usable window exists, in which case callers
+    /// should fall back to `keyWindow()`.
+    static func allVisibleWindows() -> [UIWindow] {
+        let candidates: [UIWindow]
+        if #available(iOS 15.0, *) {
+            let scenes = UIApplication.shared.connectedScenes
+                .compactMap { $0 as? UIWindowScene }
+            let activeScenes = scenes.filter { $0.activationState == .foregroundActive }
+            let chosen = activeScenes.isEmpty ? scenes : activeScenes
+            candidates = chosen.flatMap { $0.windows }
+        } else {
+            candidates = UIApplication.shared.windows
+        }
+
+        return candidates
+            .filter { !$0.isHidden && $0.alpha > 0.01 && $0.bounds.width > 0 && $0.bounds.height > 0 }
+            .sorted { $0.windowLevel < $1.windowLevel }
+    }
+}

package/ios/Core/DeviceIdentity.swift

@@ -0,0 +1,50 @@
+import Foundation
+
+/**
+ * The ONE place that answers "which iPhone is this?".
+ *
+ * iOS ships no API for the name a person would recognise. `UIDevice.current.model` returns the
+ * FAMILY — the literal string "iPhone" or "iPad" — which is identical on an iPhone 6 and an
+ * iPhone 17 Pro, so a dashboard grouping by it sees one bucket holding every iOS device ever.
+ * `ReplaySdk.getDeviceInfo` sent exactly that, which is why the replay lane could never tell two
+ * iPhones apart.
+ *
+ * The hardware identifier from `uname()` — "iPhone16,2" — is the only thing the OS will tell us,
+ * and it is unique per model. It is not the marketing name and this module does not pretend
+ * otherwise: turning "iPhone16,2" into "iPhone 15 Pro Max" needs a lookup table, and that table
+ * belongs on the server, where a device released after this binary shipped can be named without
+ * waiting for every app to adopt a new SDK and ship to the App Store.
+ *
+ * `ScaleBunProfilerModule` already had this function privately; both lanes now share it so they
+ * cannot drift into reporting two different models for one device.
+ */
+@objc(ScaleBunDeviceIdentity)
+public final class ScaleBunDeviceIdentity: NSObject {
+
+    /**
+     * The hardware identifier, e.g. "iPhone16,2" / "iPad14,3".
+     *
+     * On the simulator `uname` reports the HOST architecture ("x86_64", "arm64"), so the
+     * simulator's own hint is preferred when present — otherwise every developer's simulator
+     * session lands in the dashboard as a device model named after a CPU.
+     */
+    @objc public static func modelIdentifier() -> String {
+        if let simulator = ProcessInfo.processInfo
+            .environment["SIMULATOR_MODEL_IDENTIFIER"], !simulator.isEmpty {
+            return simulator
+        }
+        var systemInfo = utsname()
+        uname(&systemInfo)
+        let identifier = withUnsafePointer(to: &systemInfo.machine) {
+            $0.withMemoryRebound(to: CChar.self, capacity: 1) {
+                String(validatingUTF8: $0) ?? ""
+            }
+        }
+        // Empty rather than "Unknown": an absent measurement must not arrive looking like a value.
+        return identifier
+    }
+
+    // No manufacturer constant here on purpose. iOS's manufacturer is answerable without the
+    // bridge — the platform being iOS entails it — so staticDeviceContext() sets it on the FIRST
+    // event rather than waiting for a native round-trip that may never come back.
+}

package/ios/Core/ReplayConfig.swift

@@ -0,0 +1,100 @@
+import Foundation
+
+/// Replay SDK Configuration — mirrors TypeScript ReplayConfig
+struct ReplayConfig {
+    var enabled: Bool = true
+    var apiKey: String = ""
+    var endpoint: String = ""
+    var captureMode: CaptureMode = .interactions
+    var screenshotQuality: ScreenshotQuality = .normal
+    var screenshotCaptureIntervalMs: Int = 1500
+    var userStepsEnabled: Bool = true
+    var networkLogsEnabled: Bool = true
+    var sdkLogsEnabled: Bool = true
+    var autoStart: Bool = true
+    var maxSessionDurationMs: Int = 300_000
+    var maxFramesPerSession: Int = 500
+    var maxEventsPerSession: Int = 5000
+    var maxStorageSizeBytes: Int = 100 * 1024 * 1024
+    var uploadBatchSize: Int = 10
+    var maxRetryAttempts: Int = 3
+    var verboseLogging: Bool = false
+    var maxWidth: Int = 720
+    var jpegQuality: Int = 70
+    var format: String = "jpeg"
+    var maskTextInputs: Bool = true
+    var maskImages: Bool = false
+    var disableScreenshots: Bool = false
+    var ignoredScreens: [String] = []
+    var maskedElementIds: [String] = []
+    // ─── Native file-based outbox (durable; survives restart). Default-safe OFF. ───
+    // SaaS uploads use `apiBaseUrl` + `clientKey` (header x-scalebun-client-key) against the
+    // /ingestion routes — NOT the legacy `endpoint`/`apiKey` pair.
+    var clientKey: String = ""
+    var apiBaseUrl: String = ""
+    var enableNativeFileOutbox: Bool = false
+    var nativeOutboxUploadEnabled: Bool = false
+    var useObjectStorageForFrames: Bool = false
+    var outboxMaxBytes: Int = 100 * 1024 * 1024
+    var outboxMaxAgeMs: Int = 7 * 24 * 60 * 60 * 1000
+    var outboxMaxUploadAttempts: Int = 30
+    // Network-aware retry knobs (section 6/7). Spec defaults.
+    var outboxRetryIntervalMs: Int = 3000
+    var outboxPoisonMaxAttempts: Int = 2
+    var outboxRespectRetryAfter: Bool = true
+    var outboxStrictThreeSecondRetry: Bool = false
+    var outboxNetworkFailuresCountTowardDead: Bool = false
+
+    init(from dict: [String: Any]) {
+        enabled = dict["enabled"] as? Bool ?? true
+        apiKey = dict["apiKey"] as? String ?? ""
+        endpoint = dict["endpoint"] as? String ?? ""
+        if let mode = dict["captureMode"] as? String { captureMode = CaptureMode(rawValue: mode) ?? .interactions }
+        if let q = dict["screenshotQuality"] as? String { screenshotQuality = ScreenshotQuality(rawValue: q) ?? .normal }
+        screenshotCaptureIntervalMs = dict["screenshotCaptureIntervalMs"] as? Int ?? 1500
+        userStepsEnabled = dict["userStepsEnabled"] as? Bool ?? true
+        networkLogsEnabled = dict["networkLogsEnabled"] as? Bool ?? true
+        sdkLogsEnabled = dict["sdkLogsEnabled"] as? Bool ?? true
+        autoStart = dict["autoStart"] as? Bool ?? true
+        maxSessionDurationMs = dict["maxSessionDurationMs"] as? Int ?? 300_000
+        maxFramesPerSession = dict["maxFramesPerSession"] as? Int ?? 500
+        maxEventsPerSession = dict["maxEventsPerSession"] as? Int ?? 5000
+        maxStorageSizeBytes = dict["maxStorageSizeBytes"] as? Int ?? (100 * 1024 * 1024)
+        uploadBatchSize = dict["uploadBatchSize"] as? Int ?? 10
+        maxRetryAttempts = dict["maxRetryAttempts"] as? Int ?? 3
+        verboseLogging = dict["verboseLogging"] as? Bool ?? false
+        maxWidth = dict["maxWidth"] as? Int ?? 720
+        jpegQuality = dict["jpegQuality"] as? Int ?? 70
+        format = dict["format"] as? String ?? "jpeg"
+        maskTextInputs = dict["maskTextInputs"] as? Bool ?? true
+        maskImages = dict["maskImages"] as? Bool ?? false
+        disableScreenshots = dict["disableScreenshots"] as? Bool ?? false
+        ignoredScreens = dict["ignoredScreens"] as? [String] ?? []
+        maskedElementIds = dict["maskedElementIds"] as? [String] ?? []
+        clientKey = dict["clientKey"] as? String ?? ""
+        apiBaseUrl = dict["apiBaseUrl"] as? String ?? ""
+        enableNativeFileOutbox = dict["enableNativeFileOutbox"] as? Bool ?? false
+        nativeOutboxUploadEnabled = dict["nativeOutboxUploadEnabled"] as? Bool ?? false
+        useObjectStorageForFrames = dict["useObjectStorageForFrames"] as? Bool ?? false
+        outboxMaxBytes = dict["outboxMaxBytes"] as? Int ?? (100 * 1024 * 1024)
+        outboxMaxAgeMs = dict["outboxMaxAgeMs"] as? Int ?? (7 * 24 * 60 * 60 * 1000)
+        outboxMaxUploadAttempts = dict["outboxMaxUploadAttempts"] as? Int ?? 30
+        outboxRetryIntervalMs = dict["nativeOutboxRetryIntervalMs"] as? Int ?? dict["outboxRetryIntervalMs"] as? Int ?? 3000
+        outboxPoisonMaxAttempts = dict["nativeOutboxPoisonMaxAttempts"] as? Int ?? dict["outboxPoisonMaxAttempts"] as? Int ?? 2
+        outboxRespectRetryAfter = dict["nativeOutboxRespectRetryAfter"] as? Bool ?? dict["outboxRespectRetryAfter"] as? Bool ?? true
+        outboxStrictThreeSecondRetry = dict["nativeOutboxStrictThreeSecondRetry"] as? Bool ?? dict["outboxStrictThreeSecondRetry"] as? Bool ?? false
+        outboxNetworkFailuresCountTowardDead = dict["nativeOutboxNetworkFailuresCountTowardDead"] as? Bool ?? dict["outboxNetworkFailuresCountTowardDead"] as? Bool ?? false
+    }
+}
+
+enum CaptureMode: String {
+    case navigation, interactions, frequency
+}
+
+enum ScreenshotQuality: String {
+    case high, normal, low, grayscale
+}
+
+enum SessionState: String {
+    case idle, recording, paused, finalizing, uploading, completed, failed
+}

package/ios/Core/ReplayLogger.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+/// Internal logger for the iOS replay SDK.
+struct ReplayLogger {
+    static var verbose: Bool = false
+
+    static func debug(_ message: String) {
+        if verbose { NSLog("[ReplaySdk] DEBUG: %@", message) }
+    }
+
+    static func info(_ message: String) {
+        NSLog("[ReplaySdk] INFO: %@", message)
+    }
+
+    static func warn(_ message: String) {
+        NSLog("[ReplaySdk] WARN: %@", message)
+    }
+
+    static func error(_ message: String) {
+        NSLog("[ReplaySdk] ERROR: %@", message)
+    }
+}

package/ios/Core/SessionIdGenerator.swift

@@ -0,0 +1,18 @@
+import Foundation
+
+/// ID generators matching the TypeScript/Kotlin convention.
+struct SessionIdGenerator {
+    static func sessionId() -> String { "rs-\(timestampBase36())-\(shortRandom())" }
+    static func eventId() -> String { "re-\(timestampBase36())-\(shortRandom())" }
+    static func frameId() -> String { "rf-\(timestampBase36())-\(shortRandom())" }
+    static func batchId() -> String { "rb-\(timestampBase36())-\(shortRandom())" }
+
+    private static func timestampBase36() -> String {
+        String(Int(Date().timeIntervalSince1970 * 1000), radix: 36)
+    }
+
+    private static func shortRandom() -> String {
+        let chars = "0123456789abcdefghijklmnopqrstuvwxyz"
+        return String((0..<8).map { _ in chars.randomElement()! })
+    }
+}