@obsrviq/react-native 0.3.1

package/ios/LumeraReplay.swift

@@ -0,0 +1,703 @@
+import Foundation
+import UIKit
+import UIKit.UIGestureRecognizerSubclass   // touchesBegan/Moved/Ended overrides
+
+/**
+ * Lumera native screenshot-replay capture engine (iOS).
+ *
+ * THREADING CONTRACT (the whole point):
+ *   • UI thread  → TWO things only: the `view.drawHierarchy(in:afterScreenUpdates:false)`
+ *                  raster into a raw CGContext at native scale, and the cheap mask-rect
+ *                  view-tree walk (geometry needs the main thread). Nothing else.
+ *   • bg queue   → mask compositing, JPEG encode, JSON assembly, and the HTTP UPLOAD.
+ *   • change-driven, throttled to `fps`, overlapping captures DROPPED.
+ *
+ * No pixels ever cross the RN bridge — this engine uploads frames itself to
+ * `${endpoint}/v1/batch` as `type:"screen"` events, with its OWN monotonic `seq`
+ * (independent of the JS structured-event stream's seq; the worker keys frames by
+ * event id, not seq, so the two streams never collide).
+ *
+ * Reached from the ObjC++ TurboModule bridge (LumeraReplayModule.mm) via the `@objc`
+ * wrappers at the bottom of this file.
+ */
+@objc(LumeraReplay)
+final class LumeraReplay: NSObject {
+
+  struct Options {
+    var endpoint: String
+    var siteKey: String
+    var sessionId: String
+    var startedAtMs: Double
+    var fps: Double
+    var jpegQuality: Double
+    var maxCaptureDim: Int
+    var maskAllText: Bool
+    var maskAllImages: Bool
+    var captureTouches: Bool
+    var flushIntervalMs: Double
+  }
+
+  /// One process-wide instance — the bridge forwards every call here so the JS
+  /// surface (start/stop/configure/mask/diagnostics) talks to a single engine.
+  @objc static let shared = LumeraReplay()
+
+  // Serial background queue: ALL post-capture work (mask/encode/JSON/upload) lands here.
+  private let work = DispatchQueue(label: "app.lumera.replay.work", qos: .utility)
+  // URLSession on the background queue — uploads never touch the JS bridge or main thread.
+  private let session: URLSession = {
+    let cfg = URLSessionConfiguration.default
+    cfg.timeoutIntervalForRequest = 20
+    cfg.waitsForConnectivity = true
+    cfg.httpShouldUsePipelining = true
+    return URLSession(configuration: cfg)
+  }()
+
+  // `state` guards everything touched from more than one thread (options, the masked-tag
+  // sets, inFlight, the change token, and the diagnostics counters). Held only for cheap
+  // reads/writes — never across a raster, encode, or upload.
+  private let lock = NSLock()
+  private var options: Options?
+  private var displayLink: CADisplayLink?
+  private var touchRecognizer: UIGestureRecognizer?   // passive (non-consuming) touch observer
+  private var inFlight = false              // drop overlapping captures
+  private var lastCaptureHost: Int = 0      // change-detection token
+  private var maskedTags = Set<Int>()       // explicit per-view mask opt-in
+  private var unmaskedTags = Set<Int>()     // explicit per-view unmask (wins over maskAll*)
+
+  // `pending` and `seq` are confined to the `work` queue — only ever touched there.
+  private var pending: [ScreenEvent] = []   // buffered frames awaiting flush
+  private var pendingTouch: [TouchEvent] = [] // buffered taps/swipes awaiting flush (work-confined)
+  private var lastTouchMoveTs: Int = 0       // move-event throttle (work-confined)
+  private var seq: Int = 0                   // our OWN monotonic batch counter (starts at 0)
+  private var flushScheduled = false
+  // Backpressure: a prolonged network outage must not grow memory without bound. When the
+  // buffer exceeds this, the OLDEST frames are dropped (and counted) — the same drop-rather-
+  // than-snowball philosophy as the in-flight guard. ~5 min of headroom at 1 fps.
+  private let maxPending = 300
+
+  // Diagnostics (read via getDiagnostics; mutated under `lock`).
+  private var framesCaptured = 0
+  private var framesSent = 0
+  private var framesDropped = 0
+  private var bytesSent = 0
+
+  override init() { super.init() }
+
+  // MARK: - Lifecycle (called from the TurboModule bridge)
+
+  func start(_ opts: Options) {
+    lock.lock()
+    options = opts
+    lock.unlock()
+
+    DispatchQueue.main.async { [weak self] in
+      guard let self else { return }
+      self.displayLink?.invalidate()
+      // A CADisplayLink gated to ~`fps` drives change-driven capture cheaply.
+      let link = CADisplayLink(target: self, selector: #selector(self.tick))
+      link.preferredFramesPerSecond = max(1, Int(opts.fps.rounded()))
+      link.add(to: .main, forMode: .common)
+      self.displayLink = link
+
+      // Passive touch observer: a non-consuming gesture recognizer on the key window
+      // records taps + swipes without interfering with the app's own gestures.
+      if opts.captureTouches, self.touchRecognizer == nil, let window = self.keyWindow() {
+        let r = LumeraTouchRecognizer(target: self, action: #selector(self.touchNoop))
+        r.sink = self
+        window.addGestureRecognizer(r)
+        self.touchRecognizer = r
+      }
+    }
+    // Periodic flush of buffered frames, off-main.
+    work.async { [weak self] in self?.scheduleFlush() }
+  }
+
+  func stop() {
+    DispatchQueue.main.async { [weak self] in
+      self?.displayLink?.invalidate()
+      self?.displayLink = nil
+      if let r = self?.touchRecognizer {
+        r.view?.removeGestureRecognizer(r)
+        self?.touchRecognizer = nil
+      }
+    }
+    lock.lock()
+    options = nil          // stops the flush loop + makes tick() a no-op
+    lock.unlock()
+    // Final flush of anything still buffered.
+    work.async { [weak self] in self?.flush() }
+  }
+
+  func configure(fps: Double?, jpegQuality: Double?, maskAllText: Bool?, maskAllImages: Bool?) {
+    lock.lock()
+    guard var o = options else { lock.unlock(); return }
+    if let v = fps { o.fps = v }
+    if let v = jpegQuality { o.jpegQuality = v }
+    if let v = maskAllText { o.maskAllText = v }
+    if let v = maskAllImages { o.maskAllImages = v }
+    options = o
+    lock.unlock()
+    if let v = fps {
+      DispatchQueue.main.async { [weak self] in
+        self?.displayLink?.preferredFramesPerSecond = max(1, Int(v.rounded()))
+      }
+    }
+  }
+
+  /// Explicitly mask (true) or unmask (false) a view by its RN reactTag. An explicit
+  /// unmask wins over maskAllText/maskAllImages; an explicit mask forces redaction even
+  /// when the global maskAll* flags are off.
+  func setViewMasked(_ reactTag: Int, _ masked: Bool) {
+    lock.lock()
+    if masked { maskedTags.insert(reactTag); unmaskedTags.remove(reactTag) }
+    else { unmaskedTags.insert(reactTag); maskedTags.remove(reactTag) }
+    lock.unlock()
+  }
+
+  /// Snapshot the diagnostics counters (cheap; called off the capture path).
+  func diagnostics() -> [String: Any] {
+    lock.lock(); defer { lock.unlock() }
+    return [
+      "framesCaptured": framesCaptured,
+      "framesSent": framesSent,
+      "framesDropped": framesDropped,
+      "bytesSent": bytesSent,
+    ]
+  }
+
+  // MARK: - Capture (UI thread — keep this minimal)
+
+  @objc private func tick() {
+    // Read shared state once, under the lock.
+    lock.lock()
+    guard let opts = options, !inFlight else { lock.unlock(); return }
+    lock.unlock()
+
+    guard let window = keyWindow() else { return }
+
+    // Cheap change-detection: skip if nothing visibly changed since last frame.
+    let host = changeToken(window)
+    lock.lock()
+    if host == lastCaptureHost { lock.unlock(); return }
+    // Re-check inFlight (a previous tick this run-loop may have claimed it) then claim.
+    if inFlight { lock.unlock(); return }
+    lastCaptureHost = host
+    inFlight = true
+    framesCaptured += 1
+    let snapMasked = maskedTags
+    let snapUnmasked = unmaskedTags
+    lock.unlock()
+
+    // Collect redaction rects during a cheap traversal (still on the UI thread —
+    // we need view geometry — but no rasterization here).
+    let masks = collectMaskRects(window, opts: opts, masked: snapMasked, unmasked: snapUnmasked)
+
+    let scale = window.screen.scale
+    let bounds = window.bounds
+    let pxW = Int((bounds.width * scale).rounded())
+    let pxH = Int((bounds.height * scale).rounded())
+
+    // THE ONE EXPENSIVE UI-THREAD CALL — raw CGContext, native scale, afterScreenUpdates:false.
+    // (Not UIGraphicsImageRenderer; not afterScreenUpdates:true; not CALayer.render.)
+    guard pxW > 0, pxH > 0, let ctx = CGContext(
+      data: nil,
+      width: pxW, height: pxH,
+      bitsPerComponent: 8, bytesPerRow: 0,
+      space: CGColorSpaceCreateDeviceRGB(),
+      bitmapInfo: CGImageAlphaInfo.premultipliedFirst.rawValue | CGBitmapInfo.byteOrder32Little.rawValue
+    ) else {
+      releaseInFlight()
+      return
+    }
+
+    // Flip + scale so UIKit draws right-side-up at native pixel density.
+    ctx.translateBy(x: 0, y: CGFloat(pxH))
+    ctx.scaleBy(x: scale, y: -scale)
+    UIGraphicsPushContext(ctx)
+    window.drawHierarchy(in: bounds, afterScreenUpdates: false)
+    UIGraphicsPopContext()
+
+    guard let cgImage = ctx.makeImage() else { releaseInFlight(); return }
+
+    let ts = Int(Date().timeIntervalSince1970 * 1000)
+    let tRel = max(0, ts - Int(opts.startedAtMs))
+    let logical = bounds.size
+
+    // Hand off to the background queue — UI thread is done.
+    work.async { [weak self] in
+      self?.process(cgImage, masks: masks, scale: scale, logical: logical, tRel: tRel, ts: ts, opts: opts)
+    }
+  }
+
+  private func releaseInFlight() {
+    lock.lock(); inFlight = false; lock.unlock()
+  }
+
+  // MARK: - Post-capture pipeline (background queue)
+
+  private func process(_ cgImage: CGImage, masks: [CGRect], scale: CGFloat, logical: CGSize, tRel: Int, ts: Int, opts: Options) {
+    defer { releaseInFlight() }
+
+    // ① Mask compositing onto the already-captured bitmap (NEVER a second screenshot).
+    let masked = composite(cgImage, rects: masks)
+
+    // ② Downscale (THE storage/bandwidth lever) — cap the longer edge at maxCaptureDim.
+    //    Full native res is ~4× the bytes for no replay benefit; masks were composited at
+    //    full res above so they scale cleanly. No-op when already within the cap.
+    let out = Self.downscale(masked, maxDim: opts.maxCaptureDim)
+
+    // ③ JPEG encode (hardware-accelerated; off-main is safe for CGImage/Core Graphics).
+    guard let jpeg = UIImage(cgImage: out).jpegData(compressionQuality: CGFloat(opts.jpegQuality)) else { return }
+
+    // ④ Wrap into a fully-formed `screen` event + buffer for the next flush.
+    let effScale = logical.width > 0 ? Double(out.width) / Double(logical.width) : Double(scale)
+    let event = ScreenEvent(
+      id: Self.uuidv4(),
+      sessionId: opts.sessionId,
+      type: "screen",
+      t: tRel,
+      ts: ts,
+      img: jpeg.base64EncodedString(),
+      format: "jpeg",
+      w: out.width,        // encoded (possibly downscaled) pixel size
+      h: out.height,
+      screenW: Int(logical.width.rounded()),  // logical pt — unchanged by downscale
+      screenH: Int(logical.height.rounded()),
+      scale: effScale,
+      full: true
+    )
+    pending.append(event)   // `work`-confined — no lock needed
+    trimPending()
+  }
+
+  /// Cap the (work-confined) buffer; drop the OLDEST overflow and count it. Cheap — runs
+  /// only when the buffer is already over the cap (i.e. a sustained upload failure).
+  private func trimPending() {
+    guard pending.count > maxPending else { return }
+    let overflow = pending.count - maxPending
+    pending.removeFirst(overflow)
+    lock.lock(); framesDropped += overflow; lock.unlock()
+  }
+
+  // MARK: - Helpers
+
+  private func keyWindow() -> UIWindow? {
+    // Prefer foreground-active scenes so we never raster a backgrounded scene's window.
+    let scenes = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
+    let active = scenes.filter { $0.activationState == .foregroundActive }
+    let ordered = active.isEmpty ? scenes : active
+    if let key = ordered.flatMap({ $0.windows }).first(where: { $0.isKeyWindow }) { return key }
+    if #available(iOS 15.0, *), let key = ordered.compactMap({ $0.keyWindow }).first { return key }
+    return ordered.flatMap { $0.windows }.first { !$0.isHidden }
+  }
+
+  /// Cheap "did anything change" token. A layout/scroll/text edit shifts at least one
+  /// subview frame, which moves this hash; an idle screen keeps it stable (→ no capture).
+  private func changeToken(_ window: UIWindow) -> Int {
+    var h = Hasher()
+    h.combine(window.bounds.size.width)
+    h.combine(window.bounds.size.height)
+    var stack: [UIView] = [window]
+    var seen = 0
+    while let v = stack.popLast(), seen < 400 {       // bounded so deep trees stay cheap
+      if v.isHidden || v.alpha == 0 { continue }
+      let f = v.frame
+      h.combine(Int(f.origin.x)); h.combine(Int(f.origin.y))
+      h.combine(Int(f.size.width)); h.combine(Int(f.size.height))
+      // Text changes that don't move a frame still need to redraw a frame.
+      if let lbl = v as? UILabel { h.combine(lbl.text?.hashValue ?? 0) }
+      else if let tf = v as? UITextField { h.combine(tf.text?.hashValue ?? 0) }
+      seen += 1
+      stack.append(contentsOf: v.subviews)
+    }
+    return h.finalize()
+  }
+
+  /// Walk the view tree on the MAIN thread, emitting redaction rects (in captured-pixel
+  /// space) for masked nodes. Honors maskAllText/maskAllImages and the per-view
+  /// mask/unmask opt-in/out (matched by RN reactTag where available). Geometry-only —
+  /// no rasterization here.
+  private func collectMaskRects(_ window: UIWindow, opts: Options, masked: Set<Int>, unmasked: Set<Int>) -> [CGRect] {
+    var rects: [CGRect] = []
+    let scale = window.screen.scale
+    var stack: [UIView] = Array(window.subviews.reversed())
+
+    while let view = stack.popLast() {
+      if view.isHidden || view.alpha == 0 { continue }
+
+      let tag = reactTag(of: view)
+      let explicitlyUnmasked = tag != nil && unmasked.contains(tag!)
+      let explicitlyMasked = tag != nil && masked.contains(tag!)
+
+      // Class heuristics for the global maskAll* flags.
+      let isText = view is UILabel || view is UITextField || view is UITextView
+      let isImage = view is UIImageView
+      let shouldMaskByClass = (isText && opts.maskAllText) || (isImage && opts.maskAllImages)
+
+      if !explicitlyUnmasked && (explicitlyMasked || shouldMaskByClass) {
+        // Convert the view's bounds → window coords → captured-pixel space.
+        let inWindow = view.convert(view.bounds, to: window)
+        let pixelRect = inWindow.applying(CGAffineTransform(scaleX: scale, y: scale)).integral
+        if pixelRect.width >= 1, pixelRect.height >= 1 { rects.append(pixelRect) }
+        // An explicit-mask subtree is fully covered by this rect; no need to descend.
+        if explicitlyMasked { continue }
+      }
+
+      stack.append(contentsOf: view.subviews)
+    }
+    return rects
+  }
+
+  /// Best-effort RN reactTag for a view. RN host views expose a `reactTag` property
+  /// (Paper directly; Fabric via the RCTComponentViewProtocol category). We MUST gate on
+  /// `responds(to:)` first: a plain UIKit view has no such key and `value(forKey:)` would
+  /// raise an uncatchable NSUnknownKeyException. Returns nil for non-RN / untagged views.
+  private static let reactTagSelector = Selector(("reactTag"))
+  private func reactTag(of view: UIView) -> Int? {
+    guard view.responds(to: Self.reactTagSelector),
+          let n = view.value(forKey: "reactTag") as? NSNumber else { return nil }
+    let tag = n.intValue
+    return tag != 0 ? tag : nil   // 0 == unset
+  }
+
+  /// Fill redaction rects with a neutral rounded block. Core Graphics is background-safe,
+  /// so this runs on `work`. We draw onto a fresh context seeded with the captured image
+  /// (never a second screenshot) and return the masked CGImage.
+  private func composite(_ image: CGImage, rects: [CGRect]) -> CGImage {
+    guard !rects.isEmpty else { return image }
+    let w = image.width, h = image.height
+    guard let ctx = CGContext(
+      data: nil, width: w, height: h,
+      bitsPerComponent: 8, bytesPerRow: 0,
+      space: CGColorSpaceCreateDeviceRGB(),
+      bitmapInfo: CGImageAlphaInfo.premultipliedFirst.rawValue | CGBitmapInfo.byteOrder32Little.rawValue
+    ) else { return image }
+
+    // Flip the CTM to a UIKit-style top-left / y-down space ONCE, so both the captured
+    // image and the redaction rects share one coordinate system. `image` was produced
+    // top-origin (the capture context was flipped before drawHierarchy); flipping here
+    // too makes `draw` reproduce it unrotated, and lets the rects (already in top-left
+    // pixel space) be filled directly — no per-rect Y math, no double-flip.
+    ctx.translateBy(x: 0, y: CGFloat(h))
+    ctx.scaleBy(x: 1, y: -1)
+
+    let full = CGRect(x: 0, y: 0, width: w, height: h)
+    ctx.draw(image, in: full)
+    ctx.setFillColor(UIColor.systemGray.cgColor)
+    for rect in rects {
+      let clamped = rect.intersection(full)
+      guard !clamped.isNull, clamped.width >= 1, clamped.height >= 1 else { continue }
+      let radius = min(8, min(clamped.width, clamped.height) / 4)
+      let path = CGPath(roundedRect: clamped, cornerWidth: radius, cornerHeight: radius, transform: nil)
+      ctx.addPath(path)
+      ctx.fillPath()
+    }
+    return ctx.makeImage() ?? image
+  }
+
+  /// Downscale so the longer edge is ≤ maxDim (storage/bandwidth lever). No-op when the
+  /// image is already within the cap or maxDim ≤ 0. Core Graphics → background-safe.
+  private static func downscale(_ image: CGImage, maxDim: Int) -> CGImage {
+    guard maxDim > 0 else { return image }
+    let longEdge = max(image.width, image.height)
+    guard longEdge > maxDim else { return image }
+    let s = Double(maxDim) / Double(longEdge)
+    let tw = max(1, Int((Double(image.width) * s).rounded()))
+    let th = max(1, Int((Double(image.height) * s).rounded()))
+    guard let ctx = CGContext(
+      data: nil, width: tw, height: th,
+      bitsPerComponent: 8, bytesPerRow: 0,
+      space: CGColorSpaceCreateDeviceRGB(),
+      bitmapInfo: CGImageAlphaInfo.premultipliedFirst.rawValue | CGBitmapInfo.byteOrder32Little.rawValue
+    ) else { return image }
+    ctx.interpolationQuality = .medium
+    ctx.draw(image, in: CGRect(x: 0, y: 0, width: tw, height: th))
+    return ctx.makeImage() ?? image
+  }
+
+  // MARK: - Flush / upload (background queue)
+
+  /// Kick off the periodic-flush loop. Idempotent: a second start() while a loop is
+  /// already armed is a no-op (no double-flushing). Runs on `work`, so `flushScheduled`
+  /// is work-confined and needs no lock.
+  private func scheduleFlush() {
+    guard !flushScheduled else { return }
+    flushScheduled = true
+    armNextFlush()
+  }
+
+  private func armNextFlush() {
+    lock.lock()
+    let ms = options?.flushIntervalMs
+    lock.unlock()
+    // Recording stopped → let the loop die (a final flush already ran in stop()).
+    guard let ms else { flushScheduled = false; return }
+    work.asyncAfter(deadline: .now() + .milliseconds(Int(ms))) { [weak self] in
+      guard let self else { return }
+      self.flush()
+      self.armNextFlush()
+    }
+  }
+
+  /// Assemble ONE IngestBatch from ALL buffered frames, serialize to plain JSON, and POST
+  /// it to `${endpoint}/v1/batch` on `work` via URLSession. On HTTP 2xx bump
+  /// framesSent/bytesSent and increment our OWN seq; on failure re-queue the frames (their
+  /// ids are stable, so a retry is idempotent server-side).
+  private func flush() {
+    guard !pending.isEmpty || !pendingTouch.isEmpty else { return }
+    lock.lock()
+    let opts = options
+    let currentSeq = seq
+    lock.unlock()
+    guard let opts else { return }
+
+    // Drain both buffers; build the batch from frames + touches together.
+    let frames = pending
+    let touches = pendingTouch
+    pending.removeAll(keepingCapacity: true)
+    pendingTouch.removeAll(keepingCapacity: true)
+    let events: [WireEvent] = frames.map { .screen($0) } + touches.map { .touch($0) }
+
+    let logical = frames.first.map { CGSize(width: $0.screenW, height: $0.screenH) } ?? .zero
+    let batch = IngestBatch(
+      siteKey: opts.siteKey,
+      sessionId: opts.sessionId,
+      seq: currentSeq,
+      meta: BatchMeta(
+        startedAt: Int(opts.startedAtMs),
+        entryUrl: "",
+        device: DeviceMeta(
+          type: "mobile",
+          os: "iOS",
+          viewport: Viewport(w: Int(logical.width), h: Int(logical.height))
+        )
+      ),
+      events: events
+    )
+
+    guard let body = try? JSONEncoder().encode(batch),
+          let url = URL(string: batchURL(opts.endpoint)) else {
+      // Couldn't even serialize — re-queue so we don't silently drop anything.
+      pending.insert(contentsOf: frames, at: 0)
+      pendingTouch.insert(contentsOf: touches, at: 0)
+      return
+    }
+
+    var req = URLRequest(url: url)
+    req.httpMethod = "POST"
+    req.setValue(opts.siteKey, forHTTPHeaderField: "x-lumera-key")
+    // octet-stream, NOT application/json — the ingest reads the raw body buffer and
+    // sniffs gzip itself; application/json hits Fastify's JSON parser → 400 empty_body.
+    req.setValue("application/octet-stream", forHTTPHeaderField: "content-type")
+    req.httpBody = body
+
+    // Block this serial-queue slot on the upload so flushes can't interleave or stampede.
+    let sem = DispatchSemaphore(value: 0)
+    var ok = false
+    let task = session.dataTask(with: req) { _, response, _ in
+      if let http = response as? HTTPURLResponse, (200...299).contains(http.statusCode) { ok = true }
+      sem.signal()
+    }
+    task.resume()
+    sem.wait()
+
+    if ok {
+      lock.lock()
+      framesSent += frames.count
+      bytesSent += body.count
+      seq = currentSeq + 1     // bump our OWN monotonic counter per successful flush
+      lock.unlock()
+    } else {
+      // Re-queue at the FRONT so order is preserved + the next flush retries them.
+      // Not counted as dropped — the events are kept; their stable ids make the retry
+      // idempotent server-side (mobile_frames is ON CONFLICT (session_id, id) DO NOTHING).
+      // Trim from the FRONT (oldest) if a long outage pushed us past the cap.
+      pending.insert(contentsOf: frames, at: 0)
+      pendingTouch.insert(contentsOf: touches, at: 0)
+      trimPending()
+    }
+  }
+
+  private func batchURL(_ endpoint: String) -> String {
+    var base = endpoint
+    while base.hasSuffix("/") { base.removeLast() }
+    return base + "/v1/batch"
+  }
+
+  // MARK: - JSON wire model (matches @obsrviq/types IngestBatch / MobileScreenEvent exactly)
+
+  /// One `type:"screen"` event. Field order/names are the wire contract the worker parses.
+  private struct ScreenEvent: Encodable {
+    let id: String
+    let sessionId: String
+    let type: String        // "screen"
+    let t: Int              // ms since startedAtMs
+    let ts: Int             // epoch ms
+    let img: String         // base64 JPEG
+    let format: String      // "jpeg"
+    let w: Int              // encoded px
+    let h: Int
+    let screenW: Int        // logical points
+    let screenH: Int
+    let scale: Double       // effective px/pt ratio after downscale
+    let full: Bool          // keyframe marker
+  }
+
+  /// One `type:"touch"` event — a tap or a (throttled) swipe sample, in LOGICAL
+  /// screen points so the player maps it by screenW/screenH (matches @obsrviq/types
+  /// MobileTouchEvent). Rides the same batch upload as screen frames.
+  struct TouchEvent: Encodable {
+    let id: String
+    let sessionId: String
+    let type: String        // "touch"
+    let t: Int              // ms since startedAtMs
+    let ts: Int             // epoch ms
+    let phase: String       // "start" | "move" | "end" | "cancel"
+    let points: [Point]
+  }
+  struct Point: Encodable { let x: Int; let y: Int }
+
+  /// A batch carries a mix of screen + touch events; this type-erases the two so
+  /// they serialize into one heterogeneous `events` array.
+  private enum WireEvent: Encodable {
+    case screen(ScreenEvent)
+    case touch(TouchEvent)
+    func encode(to encoder: Encoder) throws {
+      switch self {
+      case .screen(let s): try s.encode(to: encoder)
+      case .touch(let t): try t.encode(to: encoder)
+      }
+    }
+  }
+
+  private struct Viewport: Encodable { let w: Int; let h: Int }
+  private struct DeviceMeta: Encodable { let type: String; let os: String; let viewport: Viewport }
+  private struct BatchMeta: Encodable { let startedAt: Int; let entryUrl: String; let device: DeviceMeta }
+  private struct IngestBatch: Encodable {
+    let siteKey: String
+    let sessionId: String
+    let seq: Int
+    let meta: BatchMeta
+    let events: [WireEvent]
+  }
+
+  // MARK: - Touch capture (called from the passive recognizer on the main thread)
+
+  /// No-op action target the recognizer is constructed with (recording happens in
+  /// its touchesBegan/Moved/Ended overrides, not via the action).
+  @objc func touchNoop() {}
+
+  /// Buffer a tap/swipe sample. Called on the MAIN thread from the recognizer; reads
+  /// options under the lock then hands off to the `work` queue for buffering. Moves
+  /// are throttled to ~50ms so a swipe doesn't flood the buffer.
+  func recordTouch(_ phase: String, _ pts: [CGPoint]) {
+    guard !pts.isEmpty else { return }
+    lock.lock(); let opts = options; lock.unlock()
+    guard let opts, opts.captureTouches else { return }
+    let ts = Int(Date().timeIntervalSince1970 * 1000)
+    let tRel = max(0, ts - Int(opts.startedAtMs))
+    let points = pts.map { Point(x: Int($0.x.rounded()), y: Int($0.y.rounded())) }
+    work.async { [weak self] in
+      guard let self else { return }
+      if phase == "move" {
+        if ts - self.lastTouchMoveTs < 50 { return }
+        self.lastTouchMoveTs = ts
+      }
+      self.pendingTouch.append(TouchEvent(
+        id: Self.uuidv4(), sessionId: opts.sessionId, type: "touch",
+        t: tRel, ts: ts, phase: phase, points: points))
+      if self.pendingTouch.count > self.maxPending {
+        self.pendingTouch.removeFirst(self.pendingTouch.count - self.maxPending)
+      }
+    }
+  }
+
+  /// RFC 4122 v4 UUID for frame ids (the worker keys frame blobs by this — must be unique).
+  private static func uuidv4() -> String { UUID().uuidString.lowercased() }
+
+  // MARK: - @objc bridge surface (called from LumeraReplayModule.mm)
+  //
+  // The ObjC++ TurboModule passes NSDictionary option maps straight through; these
+  // wrappers unbox them into the Swift `Options` struct and forward to the real methods.
+
+  @objc(startWithOptions:)
+  func startObjc(_ options: NSDictionary) {
+    start(Self.options(from: options))
+  }
+
+  @objc func stopObjc() { stop() }
+
+  @objc(configureWithOptions:)
+  func configureObjc(_ options: NSDictionary) {
+    configure(
+      fps: (options["fps"] as? NSNumber)?.doubleValue,
+      jpegQuality: (options["jpegQuality"] as? NSNumber)?.doubleValue,
+      maskAllText: (options["maskAllText"] as? NSNumber)?.boolValue,
+      maskAllImages: (options["maskAllImages"] as? NSNumber)?.boolValue
+    )
+  }
+
+  @objc(setViewMasked:masked:)
+  func setViewMaskedObjc(_ reactTag: NSNumber, masked: NSNumber) {
+    setViewMasked(reactTag.intValue, masked.boolValue)
+  }
+
+  @objc func getDiagnosticsObjc() -> NSDictionary {
+    diagnostics() as NSDictionary
+  }
+
+  /// Unbox the JS StartOptions map into Options, applying the same defaults the JS config
+  /// layer uses (so a partial map never produces a 0-fps / quality-0 capture).
+  private static func options(from map: NSDictionary) -> Options {
+    func num(_ key: String, _ fallback: Double) -> Double { (map[key] as? NSNumber)?.doubleValue ?? fallback }
+    func str(_ key: String) -> String { (map[key] as? String) ?? "" }
+    func bool(_ key: String, _ fallback: Bool) -> Bool { (map[key] as? NSNumber)?.boolValue ?? fallback }
+    return Options(
+      endpoint: str("endpoint"),
+      siteKey: str("siteKey"),
+      sessionId: str("sessionId"),
+      startedAtMs: num("startedAtMs", Date().timeIntervalSince1970 * 1000),
+      fps: num("fps", 1),
+      jpegQuality: num("jpegQuality", 0.4),
+      maxCaptureDim: Int(num("maxCaptureDim", 1200)),
+      maskAllText: bool("maskAllText", true),
+      maskAllImages: bool("maskAllImages", true),
+      captureTouches: bool("captureTouches", true),
+      flushIntervalMs: num("flushIntervalMs", 5000)
+    )
+  }
+}
+
+/// A passive (non-consuming) touch observer added to the key window. Records taps +
+/// swipe samples and forwards them to the engine without interfering with the app's
+/// own gesture handling (cancelsTouchesInView = false; it never claims a gesture).
+final class LumeraTouchRecognizer: UIGestureRecognizer {
+  weak var sink: LumeraReplay?
+
+  override init(target: Any?, action: Selector?) {
+    super.init(target: target, action: action)
+    cancelsTouchesInView = false
+    delaysTouchesBegan = false
+    delaysTouchesEnded = false
+  }
+
+  private func pts(_ touches: Set<UITouch>) -> [CGPoint] {
+    guard let v = view else { return [] }
+    return touches.map { $0.location(in: v) }   // logical points in window space
+  }
+
+  override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent) {
+    sink?.recordTouch("start", pts(touches))
+  }
+  override func touchesMoved(_ touches: Set<UITouch>, with event: UIEvent) {
+    sink?.recordTouch("move", pts(touches))
+  }
+  override func touchesEnded(_ touches: Set<UITouch>, with event: UIEvent) {
+    sink?.recordTouch("end", pts(touches))
+    state = .failed   // reset for the next gesture; never consume the touch
+  }
+  override func touchesCancelled(_ touches: Set<UITouch>, with event: UIEvent) {
+    sink?.recordTouch("cancel", pts(touches))
+    state = .failed
+  }
+}