@obsrviq/react-native 0.3.1

package/android/src/main/java/app/lumera/replay/LumeraReplayModule.kt

@@ -0,0 +1,530 @@
+package app.lumera.replay
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Paint
+import android.graphics.Rect
+import android.os.Build
+import android.app.Activity
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Base64
+import android.view.MotionEvent
+import android.view.PixelCopy
+import android.view.View
+import android.view.ViewGroup
+import android.view.ViewTreeObserver
+import android.view.Window
+import android.widget.EditText
+import android.widget.ImageView
+import android.widget.TextView
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.OutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+import java.util.UUID
+import java.util.concurrent.atomic.AtomicBoolean
+
+/**
+ * Lumera native screenshot-replay capture engine (Android).
+ *
+ * THREADING CONTRACT:
+ *   • UI thread → only schedules a PixelCopy (which is async) + a cheap mask-rect walk.
+ *   • bg thread → PixelCopy callback lands here (its Handler), then mask + JPEG + UPLOAD.
+ *   • change-driven via ViewTreeObserver.OnDrawListener, throttled to `fps`, overlapping DROPPED.
+ *
+ * Uses PixelCopy (API 26+, async, captures GPU/SurfaceView) — NOT View.draw(Canvas),
+ * which misses hardware-accelerated content. One reused RGB_565 bitmap. No pixels
+ * cross the RN bridge: this engine uploads frames itself to `${endpoint}/v1/batch`.
+ *
+ * NOTE: extends the codegen'd `NativeLumeraReplaySpec` (New Arch). The
+ * `LumeraReplayPackage` registers it as the TurboModule named "LumeraReplay".
+ */
+class LumeraReplayModule(private val reactCtx: ReactApplicationContext) :
+  NativeLumeraReplaySpec(reactCtx) {
+
+  // Dedicated background thread for ALL post-capture work (PixelCopy callback + encode + upload).
+  private val bgThread = HandlerThread("lumera-replay").apply { start() }
+  private val bg = Handler(bgThread.looper)
+
+  private var opts: ReadableStartOptions? = null
+  private val inFlight = AtomicBoolean(false)   // drop overlapping captures
+  private var reuseBitmap: Bitmap? = null
+  // Buffered, fully-built `screen` event JSON objects awaiting the next flush.
+  private val pending = ArrayList<JSONObject>()
+  private var drawListener: ViewTreeObserver.OnDrawListener? = null
+  private var lastCaptureAt = 0L
+
+  // Touch capture: buffered `touch` events + the original Window.Callback we wrap (non-consuming).
+  private val pendingTouch = ArrayList<JSONObject>()
+  private var origCallback: Window.Callback? = null
+  private var lastTouchMoveAt = 0L
+
+  // Native's OWN monotonic batch counter (independent of the JS structured-event stream).
+  // Starts at 0, ++ only on a successful flush, so the worker can order screen chunks.
+  private var seq = 0
+
+  // Reused gray fill for redaction blocks (composited on `bg`).
+  private val maskPaint = Paint().apply {
+    color = Color.rgb(0x9E, 0x9E, 0x9E) // neutral material gray
+    style = Paint.Style.FILL
+    isAntiAlias = true
+  }
+
+  // Diagnostics
+  private var framesCaptured = 0
+  private var framesSent = 0
+  private var framesDropped = 0
+  private var bytesSent = 0L
+
+  override fun getName() = "LumeraReplay"
+
+  // MARK: - Lifecycle
+
+  override fun start(options: com.facebook.react.bridge.ReadableMap) {
+    opts = ReadableStartOptions(options)
+    // The Activity may not be attached yet at init() time — the async JS bootstrap can
+    // call start() before onResume. Retry briefly instead of bailing forever.
+    attachWhenReady(0)
+    scheduleFlush()
+  }
+
+  private fun attachWhenReady(attempt: Int) {
+    val activity = reactCtx.currentActivity
+    if (activity == null) {
+      if (attempt < 20) bg.postDelayed({ attachWhenReady(attempt + 1) }, 250)
+      return
+    }
+    activity.runOnUiThread {
+      if (drawListener != null) return@runOnUiThread
+      val decor = activity.window?.decorView ?: return@runOnUiThread
+      // Change-driven: OnDrawListener fires only when the UI actually draws; throttled to fps.
+      val l = ViewTreeObserver.OnDrawListener { maybeCapture() }
+      decor.viewTreeObserver.addOnDrawListener(l)
+      drawListener = l
+      if (opts?.captureTouches == true) installTouchCallback(activity)
+    }
+  }
+
+  /**
+   * Observe taps/swipes WITHOUT consuming them: wrap the window's Callback and intercept
+   * `dispatchTouchEvent` (the single chokepoint every touch flows through before the view
+   * tree sees it), record the gesture, then delegate to the original so the app behaves
+   * normally. Kotlin interface-delegation (`by base`) forwards every other Callback method.
+   * Runs on the UI thread; recordTouch only builds a small JSON object, no raster.
+   */
+  private fun installTouchCallback(activity: Activity) {
+    if (origCallback != null) return
+    val window = activity.window ?: return
+    val base = window.callback ?: return
+    origCallback = base
+    val density = activity.resources.displayMetrics.density
+    window.callback = TouchCallback(base) { ev -> recordTouch(ev, density) }
+  }
+
+  private fun removeTouchCallback(activity: Activity?) {
+    val window = activity?.window ?: return
+    val orig = origCallback ?: return
+    // Only restore if our wrapper is still the active callback (don't clobber a later wrapper).
+    if (window.callback is TouchCallback) window.callback = orig
+    origCallback = null
+  }
+
+  /** Map a MotionEvent into a buffered `touch` event in logical dp coords (move throttled to 50ms). */
+  private fun recordTouch(e: MotionEvent, density: Float) {
+    val o = opts ?: return
+    if (!o.captureTouches) return
+    val phase = when (e.actionMasked) {
+      MotionEvent.ACTION_DOWN, MotionEvent.ACTION_POINTER_DOWN -> "start"
+      MotionEvent.ACTION_MOVE -> "move"
+      MotionEvent.ACTION_UP, MotionEvent.ACTION_POINTER_UP -> "end"
+      MotionEvent.ACTION_CANCEL -> "cancel"
+      else -> return
+    }
+    val now = System.currentTimeMillis()
+    if (phase == "move") {
+      if (now - lastTouchMoveAt < 50) return
+      lastTouchMoveAt = now
+    }
+    val d = if (density > 0f) density else 1f
+    val points = JSONArray()
+    for (i in 0 until e.pointerCount) {
+      points.put(JSONObject().apply {
+        put("x", Math.round(e.getX(i) / d))
+        put("y", Math.round(e.getY(i) / d))
+      })
+    }
+    val ev = JSONObject().apply {
+      put("id", UUID.randomUUID().toString())
+      put("sessionId", o.sessionId)
+      put("type", "touch")
+      put("t", (now - o.startedAtMs).toInt())
+      put("ts", now)
+      put("phase", phase)
+      put("points", points)
+    }
+    synchronized(pendingTouch) {
+      pendingTouch.add(ev)
+      if (pendingTouch.size > 600) pendingTouch.removeAt(0) // bound memory if upload stalls
+    }
+  }
+
+  override fun stop() {
+    val activity = reactCtx.currentActivity
+    activity?.runOnUiThread {
+      drawListener?.let { activity.window?.decorView?.viewTreeObserver?.removeOnDrawListener(it) }
+      drawListener = null
+      removeTouchCallback(activity)
+    }
+    bg.post { flush() }
+  }
+
+  override fun configure(options: com.facebook.react.bridge.ReadableMap) {
+    opts?.merge(options)
+  }
+
+  override fun setViewMasked(reactTag: Double, masked: Boolean) {
+    if (masked) maskTag(reactTag.toInt()) else unmaskTag(reactTag.toInt())
+  }
+
+  override fun getDiagnostics(promise: Promise) {
+    val map = com.facebook.react.bridge.Arguments.createMap()
+    map.putInt("framesCaptured", framesCaptured)
+    map.putInt("framesSent", framesSent)
+    map.putInt("framesDropped", framesDropped)
+    map.putDouble("bytesSent", bytesSent.toDouble())
+    promise.resolve(map)
+  }
+
+  // MARK: - Capture (UI thread schedules; PixelCopy is async → bg)
+
+  private fun maybeCapture() {
+    val o = opts ?: return
+    val now = System.currentTimeMillis()
+    val minIntervalMs = (1000.0 / o.fps).toLong()
+    if (now - lastCaptureAt < minIntervalMs) return            // throttle to fps
+    if (!inFlight.compareAndSet(false, true)) { framesDropped++; return } // drop overlapping
+
+    val activity = reactCtx.currentActivity
+    val window = activity?.window
+    val decor = window?.decorView
+    if (window == null || decor == null || Build.VERSION.SDK_INT < 26) { inFlight.set(false); return }
+
+    // Change-driven already: OnDrawListener only fires when the UI actually draws, and
+    // we throttle to `fps` above. (No content token — decorView identity + size are
+    // constant for the session, so any such token would freeze capture after frame 1.)
+    lastCaptureAt = now
+
+    // Collect redaction rects on the UI thread (geometry needs the UI thread; no raster here).
+    val masks = collectMaskRects(decor, o)
+
+    val w = decor.width; val h = decor.height
+    if (w <= 0 || h <= 0) { inFlight.set(false); return }
+    val bmp = reuseBitmap?.takeIf { it.width == w && it.height == h }
+      ?: Bitmap.createBitmap(w, h, Bitmap.Config.RGB_565).also { reuseBitmap = it }
+
+    // Logical (dp) screen size — independent of the captured pixel raster.
+    val density = decor.resources.displayMetrics.density
+    val scale = if (density > 0f) Math.round(density) else 1
+    val screenW = if (scale > 0) Math.round(w / density) else w
+    val screenH = if (scale > 0) Math.round(h / density) else h
+
+    val ts = now
+    val tRel = (now - o.startedAtMs).toInt()
+    // PixelCopy is async; its callback fires on `bg` — UI thread is now free.
+    PixelCopy.request(window, bmp, { result ->
+      if (result == PixelCopy.SUCCESS) {
+        framesCaptured++
+        process(bmp, masks, w, h, screenW, screenH, scale, tRel, ts, o)
+      }
+      inFlight.set(false)
+    }, bg)
+  }
+
+  // MARK: - Post-capture pipeline (bg thread)
+
+  private fun process(
+    bmp: Bitmap,
+    masks: List<Rect>,
+    w: Int,
+    h: Int,
+    screenW: Int,
+    screenH: Int,
+    scale: Int,
+    tRel: Int,
+    ts: Long,
+    o: ReadableStartOptions,
+  ) {
+    // ① Mask compositing onto the captured bitmap (never a second capture).
+    //    Rounded gray blocks over each redaction rect — drawn on `bg`, not the UI thread.
+    if (masks.isNotEmpty()) {
+      val canvas = Canvas(bmp)
+      val radius = 8f * (if (scale > 0) scale else 1)
+      for (r in masks) {
+        if (r.width() <= 0 || r.height() <= 0) continue
+        canvas.drawRoundRect(
+          r.left.toFloat(), r.top.toFloat(), r.right.toFloat(), r.bottom.toFloat(),
+          radius, radius, maskPaint,
+        )
+      }
+    }
+
+    // ② Downscale (THE storage/bandwidth lever) — cap the longer edge at maxCaptureDim.
+    //    Full native res (~1080×2400) is ~4× the bytes for no replay benefit. Masks were
+    //    composited above at full res, so they scale down cleanly with the frame. Bilinear
+    //    (filter=true). At ~1fps the per-frame alloc is negligible; recycle the temp after.
+    val longEdge = maxOf(w, h)
+    val downscale = o.maxCaptureDim > 0 && longEdge > o.maxCaptureDim
+    val outBmp: Bitmap
+    val outW: Int
+    val outH: Int
+    if (downscale) {
+      val s = o.maxCaptureDim.toDouble() / longEdge
+      outW = Math.max(1, Math.round(w * s).toInt())
+      outH = Math.max(1, Math.round(h * s).toInt())
+      outBmp = Bitmap.createScaledBitmap(bmp, outW, outH, true)
+    } else {
+      outW = w; outH = h; outBmp = bmp
+    }
+    // Effective pixel/logical ratio after downscale (player maps by screenW/H; this is metadata).
+    val effScale = if (screenW > 0) outW.toDouble() / screenW else scale.toDouble()
+
+    // ③ JPEG compress off the UI thread.
+    val out = java.io.ByteArrayOutputStream()
+    outBmp.compress(Bitmap.CompressFormat.JPEG, (o.jpegQuality * 100).toInt(), out)
+    if (downscale) outBmp.recycle() // temp scaled bitmap; the reused full-res bmp lives on
+    val jpeg = out.toByteArray()
+    val img = Base64.encodeToString(jpeg, Base64.NO_WRAP)
+
+    // ④ Build the `screen` event (BaseEvent + MobileScreenEvent) and buffer for flush.
+    val event = JSONObject().apply {
+      put("id", UUID.randomUUID().toString())
+      put("sessionId", o.sessionId)
+      put("type", "screen")
+      put("t", tRel)
+      put("ts", ts)
+      put("img", img)
+      put("format", "jpeg")
+      put("w", outW)        // encoded (possibly downscaled) pixel size
+      put("h", outH)
+      put("screenW", screenW)  // logical dp — unchanged by downscale
+      put("screenH", screenH)
+      put("scale", effScale)
+      put("full", true)
+    }
+    synchronized(pending) { pending.add(event) }
+  }
+
+  /**
+   * Walk the decorView on the UI thread → redaction rects (in captured-pixel space) for
+   * masked nodes: TextView/EditText when [ReadableStartOptions.maskAllText], ImageView when
+   * [ReadableStartOptions.maskAllImages]. A view whose id (RN reactTag) is in [maskedTags]
+   * — set via `setViewMasked(tag, true)` or `<LumeraMask>` — is force-masked along with its
+   * whole subtree (one block), regardless of mask-all. Rect = getLocationInWindow + width/height.
+   *
+   * Honoring per-view UN-masking under mask-all (force-unmask) would need a second, explicit
+   * "unmasked" set since Android can't distinguish that from "no override"; not implemented.
+   */
+  private fun collectMaskRects(root: View, o: ReadableStartOptions): List<Rect> {
+    val rects = ArrayList<Rect>()
+    val loc = IntArray(2)
+    // decorView's own window offset — subtract so rects are relative to the captured bitmap.
+    root.getLocationInWindow(loc)
+    val originX = loc[0]
+    val originY = loc[1]
+
+    fun rectFor(v: View): Rect {
+      v.getLocationInWindow(loc)
+      val left = loc[0] - originX
+      val top = loc[1] - originY
+      return Rect(left, top, left + v.width, top + v.height)
+    }
+
+    fun explicitState(v: View): Boolean? {
+      // null = no explicit override; true = force-masked.
+      // RN reactTags are surfaced as the host View.id on Android. We can only test for
+      // presence in the masked set; an absent tag means "no explicit MASK override".
+      return if (maskedTags.contains(v.id)) true else null
+    }
+
+    fun walk(v: View, ancestorMasked: Boolean) {
+      if (v.visibility != View.VISIBLE) return
+      if (v.width <= 0 || v.height <= 0) return
+
+      val explicit = explicitState(v)
+      val masked = explicit ?: ancestorMasked
+
+      // Leaf redaction by class heuristic (only when not already covered by an ancestor mask).
+      if (!ancestorMasked && explicit == null) {
+        val byClass = when {
+          o.maskAllText && (v is TextView || v is EditText) -> true
+          o.maskAllImages && v is ImageView -> true
+          else -> false
+        }
+        if (byClass) {
+          rects.add(rectFor(v))
+          return // children of a masked text/image node need no further rects
+        }
+      }
+
+      if (masked && explicit == true) {
+        // An explicit container mask: one block covering the whole subtree.
+        rects.add(rectFor(v))
+        return
+      }
+
+      if (v is ViewGroup) {
+        for (i in 0 until v.childCount) walk(v.getChildAt(i), masked)
+      }
+    }
+
+    walk(root, ancestorMasked = false)
+    return rects
+  }
+
+  // MARK: - Flush / upload (bg thread)
+
+  private fun scheduleFlush() {
+    val o = opts ?: return
+    bg.postDelayed({
+      if (opts != null) { flush(); scheduleFlush() }
+    }, o.flushIntervalMs.toLong())
+  }
+
+  /**
+   * Assemble ONE `IngestBatch` from buffered `screen` events and POST it to
+   * `${endpoint}/v1/batch` (HttpURLConnection on `bg`, x-lumera-key header, plain JSON).
+   * On HTTP 2xx: bump counters + ++seq. On failure: re-queue (prepend so order holds).
+   */
+  private fun flush() {
+    val o = opts ?: return
+    val frames = synchronized(pending) { ArrayList(pending).also { pending.clear() } }
+    val touches = synchronized(pendingTouch) { ArrayList(pendingTouch).also { pendingTouch.clear() } }
+    if (frames.isEmpty() && touches.isEmpty()) return
+
+    val events = JSONArray()
+    for (e in frames) events.put(e)
+    for (e in touches) events.put(e)
+
+    // Use the first frame's logical size for the meta viewport (all frames share one window).
+    // A touch-only batch (no screen this interval) carries 0 — the server keeps the session's
+    // established viewport from earlier frame batches.
+    val first = frames.firstOrNull()
+    val viewport = JSONObject().apply {
+      put("w", first?.optInt("screenW") ?: 0)
+      put("h", first?.optInt("screenH") ?: 0)
+    }
+    val device = JSONObject().apply {
+      put("type", "mobile")
+      put("os", "Android")
+      put("viewport", viewport)
+    }
+    val meta = JSONObject().apply {
+      put("startedAt", o.startedAtMs.toLong())
+      put("entryUrl", "")
+      put("device", device)
+    }
+    val body = JSONObject().apply {
+      put("siteKey", o.siteKey)
+      put("sessionId", o.sessionId)
+      put("seq", seq)
+      put("meta", meta)
+      put("events", events)
+    }
+
+    val payload = body.toString().toByteArray(Charsets.UTF_8)
+    val ok = post(o, payload)
+    if (ok) {
+      framesSent += frames.size
+      bytesSent += payload.size.toLong()
+      seq++
+    } else {
+      // Re-queue at the front so ordering is preserved for the next attempt.
+      synchronized(pending) { pending.addAll(0, frames) }
+      synchronized(pendingTouch) { pendingTouch.addAll(0, touches) }
+    }
+  }
+
+  /** Blocking POST of one batch on the `bg` thread. Returns true on HTTP 2xx. */
+  private fun post(o: ReadableStartOptions, payload: ByteArray): Boolean {
+    val url = "${o.endpoint.trimEnd('/')}/v1/batch"
+    var conn: HttpURLConnection? = null
+    return try {
+      conn = (URL(url).openConnection() as HttpURLConnection).apply {
+        requestMethod = "POST"
+        doOutput = true
+        connectTimeout = 10_000
+        readTimeout = 15_000
+        // 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.
+        setRequestProperty("content-type", "application/octet-stream")
+        setRequestProperty("x-lumera-key", o.siteKey)
+        setFixedLengthStreamingMode(payload.size)
+      }
+      conn.outputStream.use { os: OutputStream -> os.write(payload) }
+      val code = conn.responseCode
+      // Drain so the socket can be reused by the connection pool.
+      (if (code in 200..299) conn.inputStream else conn.errorStream)?.use { it.readBytes() }
+      code in 200..299
+    } catch (_: Exception) {
+      false
+    } finally {
+      conn?.disconnect()
+    }
+  }
+
+  /** Typed view over the JS start() options map. */
+  private class ReadableStartOptions(map: com.facebook.react.bridge.ReadableMap) {
+    var endpoint = map.getString("endpoint") ?: ""
+    var siteKey = map.getString("siteKey") ?: ""
+    var sessionId = map.getString("sessionId") ?: ""
+    var startedAtMs = map.getDouble("startedAtMs")
+    var fps = if (map.hasKey("fps")) map.getDouble("fps") else 1.0
+    var jpegQuality = if (map.hasKey("jpegQuality")) map.getDouble("jpegQuality") else 0.4
+    var maxCaptureDim = if (map.hasKey("maxCaptureDim")) map.getDouble("maxCaptureDim").toInt() else 1200
+    var maskAllText = !map.hasKey("maskAllText") || map.getBoolean("maskAllText")
+    var maskAllImages = !map.hasKey("maskAllImages") || map.getBoolean("maskAllImages")
+    var captureTouches = !map.hasKey("captureTouches") || map.getBoolean("captureTouches")
+    var flushIntervalMs = if (map.hasKey("flushIntervalMs")) map.getDouble("flushIntervalMs") else 5000.0
+    fun merge(m: com.facebook.react.bridge.ReadableMap) {
+      if (m.hasKey("fps")) fps = m.getDouble("fps")
+      if (m.hasKey("jpegQuality")) jpegQuality = m.getDouble("jpegQuality")
+      if (m.hasKey("maskAllText")) maskAllText = m.getBoolean("maskAllText")
+      if (m.hasKey("maskAllImages")) maskAllImages = m.getBoolean("maskAllImages")
+    }
+  }
+
+  /**
+   * Non-consuming Window.Callback wrapper. Delegates EVERY method to [base] via Kotlin
+   * interface delegation; only [dispatchTouchEvent] is overridden to peek at the gesture
+   * (synchronously — no MotionEvent is retained past the call) before delegating, so the
+   * app's own touch handling is completely unaffected.
+   */
+  private class TouchCallback(
+    private val base: Window.Callback,
+    private val onTouch: (MotionEvent) -> Unit,
+  ) : Window.Callback by base {
+    override fun dispatchTouchEvent(event: MotionEvent): Boolean {
+      try { onTouch(event) } catch (_: Throwable) { /* never let capture break input */ }
+      return base.dispatchTouchEvent(event)
+    }
+  }
+
+  companion object {
+    /**
+     * Process-wide set of explicitly-masked View ids (RN reactTags). Shared so both the
+     * TurboModule (`setViewMasked`) and the `<LumeraMask>` view manager
+     * ([LumeraMaskViewManager]) feed the same registry the capture walk reads. A
+     * ConcurrentHashMap-backed set: written from the UI thread, read on `bg`.
+     */
+    private val maskedTags: MutableSet<Int> =
+      java.util.Collections.newSetFromMap(java.util.concurrent.ConcurrentHashMap<Int, Boolean>())
+
+    fun maskTag(tag: Int) { maskedTags.add(tag) }
+    fun unmaskTag(tag: Int) { maskedTags.remove(tag) }
+  }
+}

package/android/src/main/java/app/lumera/replay/LumeraReplayPackage.kt

@@ -0,0 +1,50 @@
+package app.lumera.replay
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * TurboModule package for the Lumera native capture engine.
+ *
+ * Registered by the host app (autolinking via react-native.config.js, or manually in
+ * MainApplication's `getPackages()`). Exposes the New-Architecture TurboModule named
+ * "LumeraReplay" plus the optional <LumeraMask> view manager.
+ *
+ * Uses [BaseReactPackage] (RN 0.76+) — `getModule(name, ctx)` is resolved lazily by the
+ * TurboModule infrastructure, and [getReactModuleInfoProvider] marks the module
+ * `isTurboModule = true` so it is loaded over JSI (never the legacy bridge).
+ */
+class LumeraReplayPackage : BaseReactPackage() {
+
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+    when (name) {
+      LumeraReplayModuleName -> LumeraReplayModule(reactContext)
+      else -> null
+    }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider =
+    ReactModuleInfoProvider {
+      mapOf(
+        LumeraReplayModuleName to ReactModuleInfo(
+          /* name = */ LumeraReplayModuleName,
+          /* className = */ LumeraReplayModule::class.java.name,
+          /* canOverrideExistingModule = */ false,
+          /* needsEagerInit = */ false,
+          /* isCxxModule = */ false,
+          /* isTurboModule = */ true,
+        ),
+      )
+    }
+
+  // View managers are not TurboModules; supply the optional <LumeraMask> manager directly.
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
+    listOf(LumeraMaskViewManager())
+
+  private companion object {
+    const val LumeraReplayModuleName = "LumeraReplay"
+  }
+}

package/ios/LumeraMaskView.h

@@ -0,0 +1,19 @@
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Backing native view for the <LumeraMask> RN component. It is a plain pass-through
+ * container (children render normally); its only job is to register/unregister its RN
+ * `reactTag` with the capture engine so the region it occupies is masked (or, with
+ * `masked={false}`, explicitly UN-masked — overriding the global maskAll* defaults).
+ *
+ * The mask itself is composited natively off the UI thread during capture — this view
+ * adds no per-frame cost and never rasterizes anything.
+ */
+@interface LumeraMaskView : UIView
+/** YES → mask this subtree; NO → force-unmask it. Default YES. */
+@property (nonatomic, assign) BOOL masked;
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/LumeraMaskView.m

@@ -0,0 +1,79 @@
+#import "LumeraMaskView.h"
+#import <React/RCTComponent.h>
+
+// The capture engine's @objc surface (see LumeraReplay.swift). Mirrors the umbrella-
+// header resolution in LumeraReplayModule.mm; we only need `shared` + setViewMasked here.
+#if __has_include(<lumera_react_native/lumera_react_native-Swift.h>)
+#import <lumera_react_native/lumera_react_native-Swift.h>
+#elif __has_include("lumera_react_native-Swift.h")
+#import "lumera_react_native-Swift.h"
+#elif __has_include("LumeraReactNative-Swift.h")
+#import "LumeraReactNative-Swift.h"
+#else
+@interface LumeraReplay : NSObject
+@property (class, nonatomic, readonly, strong) LumeraReplay *shared;
+- (void)setViewMasked:(NSNumber *)reactTag masked:(NSNumber *)masked;
+@end
+#endif
+
+@implementation LumeraMaskView
+
+- (instancetype)init
+{
+  if ((self = [super init])) {
+    _masked = YES;
+    // Transparent container — the wrapped children own all visuals.
+    self.backgroundColor = [UIColor clearColor];
+    self.opaque = NO;
+  }
+  return self;
+}
+
+// `reactTag` is assigned by RN before the view is mounted into the tree, so by the time
+// we have a superview the tag is valid — register the redaction here.
+- (void)didMoveToSuperview
+{
+  [super didMoveToSuperview];
+  if (self.superview) {
+    [self applyMask:YES];
+  }
+}
+
+// Unregister as the view leaves the tree (covers unmount + reparenting to nil).
+- (void)willMoveToSuperview:(UIView *)newSuperview
+{
+  [super willMoveToSuperview:newSuperview];
+  if (newSuperview == nil) {
+    [self applyMask:NO];
+  }
+}
+
+// Re-apply if the `masked` prop flips while mounted.
+- (void)setMasked:(BOOL)masked
+{
+  if (_masked == masked) { return; }
+  _masked = masked;
+  if (self.superview) { [self applyMask:YES]; }
+}
+
+- (void)applyMask:(BOOL)registering
+{
+  NSNumber *tag = self.reactTag;
+  if (tag == nil) { return; }
+  // registering → honor the `masked` prop (YES = mask, NO = force-unmask).
+  // !registering (leaving the tree) → clear the entry by unmasking.
+  BOOL value = registering ? self.masked : NO;
+  [LumeraReplay.shared setViewMasked:tag masked:@(value)];
+}
+
+- (void)dealloc
+{
+  // Belt-and-suspenders: drop any lingering registration if the view is torn down
+  // without a willMoveToSuperview:nil (shouldn't happen, but tags must not leak).
+  NSNumber *tag = self.reactTag;
+  if (tag != nil) {
+    [LumeraReplay.shared setViewMasked:tag masked:@(NO)];
+  }
+}
+
+@end