@obsrviq/react-native 0.3.1

package/README.md

@@ -0,0 +1,108 @@
+# @obsrviq/react-native
+
+Mobile session replay + analytics capture for **React Native (iOS + Android)**, feeding the same Lumera backend as the web tracker. Engineered around one non-negotiable: **zero added latency on the device.**
+
+> **Status: in development.** The pure-JS layer (public API, session/identity, network/error/console capture, transport) is implemented. The native screenshot-capture TurboModule (iOS Swift / Android Kotlin), the backend frame-storage path, and the mobile player renderer are in progress — see [Roadmap](#roadmap).
+
+---
+
+## Why this design (the research)
+
+We surveyed the 2026 mobile-replay landscape (Sentry, PostHog, Datadog, FullStory, Smartlook, UXCam — Sentry/PostHog/Datadog are open source and were read at the source level). Findings:
+
+- Nobody records video on-device for analytics replay — battery/heat/privacy kill it.
+- The two viable strategies are **wireframe** (serialize the view tree → reconstruct) and **periodic screenshots** (1 fps, masked, encoded). Both Sentry & PostHog **force screenshot mode for React Native** because RN's cross-platform rendering can't be reliably rebuilt from the native tree.
+- We chose **screenshot-first** (pixel-perfect replay) and apply the open-source playbook that makes it jank-free.
+
+The measured reason naive screenshot replay janks: rasterizing a screen on the UI thread costs **25–155 ms/frame** (Sentry measured 9–10 dropped frames/sec on their first iOS renderer). The fix is architectural, not incremental.
+
+## The zero-latency architecture
+
+```
+┌───────────────────────── DEVICE ─────────────────────────┐
+│                                                           │
+│  JS thread          Native UI thread     Background thread │
+│  ─────────          ───────────────      ───────────────── │
+│  init / identify    ① one fast raster ──▶ ② mask composite  │
+│  track / tag           (~1 fps, change-     ③ JPEG encode    │
+│  network/error/        driven, drop          ④ gzip          │
+│  console capture       overlapping)          ⑤ UPLOAD ───────┼──▶ POST /v1/batch
+│       │                                                     │     (type:'screen')
+│       └── structured events ──▶ POST /v1/batch (type:custom/network/…)
+│                                                           │
+└───────────────────────────────────────────────────────────┘
+```
+
+**Invariants (every one is a measured jank source if violated):**
+
+1. The **UI thread** does *only* the single screenshot grab. Everything after — masking, JPEG encode, gzip, upload — runs on a background thread.
+2. The **JS thread** is never in the capture loop. It calls `start/stop/configure` once; the native timer reads native views directly (RN renders to real `UIView`/`View`, so no JS hook is needed for pixels).
+3. **No pixel/frame buffer ever crosses the bridge/JSI.** The native module uploads frames itself, using the `siteKey` + `sessionId` the JS layer hands it at `start()`.
+4. Capture is **change-driven, throttled to ~1 fps**, and **overlapping captures are dropped** (an in-flight flag) so a slow frame can't snowball.
+5. **Idle screens cost zero** — unchanged view tree ⇒ no capture.
+
+**Platform specifics** (from the source-level research):
+
+- **iOS:** raster via a raw `CGContext` + `view.drawHierarchy(in:afterScreenUpdates:false)` at native scale — *not* `UIGraphicsImageRenderer` (≈6× slower), *not* `afterScreenUpdates:true` (forces a sync layout+commit), *not* `CALayer.render(in:)` (drops content).
+- **Android:** `PixelCopy.request(window, bitmap, listener, backgroundHandler)` (API 26+, async, captures GPU/`SurfaceView` content) — *not* `View.draw(Canvas)` (misses hardware content → black video/maps). Reuse one `RGB_565` bitmap.
+- **Masking:** privacy-by-default. Redaction rects are collected during the (cheap) traversal and composited onto the already-captured bitmap on the background thread — never a second screenshot.
+
+## Install
+
+```sh
+npm install @obsrviq/react-native @react-native-async-storage/async-storage
+cd ios && pod install   # iOS
+```
+
+Requires React Native ≥ 0.76 (New Architecture). Works under the old architecture via RN's interop shim.
+
+## Quickstart
+
+```ts
+import { LumeraReplay } from '@obsrviq/react-native';
+
+LumeraReplay.init({
+  siteKey: 'pk_live_…',
+  // privacy-by-default: all text + images masked. Opt out per-view with <LumeraMask unmask>.
+});
+
+// later — identical API to the web SDK:
+LumeraReplay.identify('user_123', { plan: 'pro' });
+LumeraReplay.track('checkout_started', { cart: 3 });
+LumeraReplay.conversion('purchase', { value: 49.0 });
+LumeraReplay.tag('vip', 'beta');
+```
+
+## API
+
+Mirrors `@obsrviq/tracker` 1:1 — `init`, `identify`, `setMetadata`, `track`, `conversion`, `tag`, `startTask`/`endTask`, `setConsent`, `reset`, `stop`, `flush`, `getDiagnostics`, `sessionId`. See [`src/config.ts`](src/config.ts) for the full config.
+
+## Privacy / masking
+
+- **Default:** all text and images are masked before any pixel is persisted (masking runs on the capture thread, pre-encode).
+- **Per-view control:** `<LumeraMask>` / `<LumeraMask unmask>` wrappers (call `setViewMasked(reactTag, …)` natively). *(component pending — task #95/#96)*
+- Network header redaction (`authorization`/`cookie`/`set-cookie` by default), bodies off by default.
+
+## Data flow
+
+Two independent uploaders, one session:
+
+| Stream | Owner | Endpoint | Event type | Storage |
+|---|---|---|---|---|
+| Structured (network/error/console/custom) | JS | `POST /v1/batch` | `network`/`error`/`console`/`custom` | Postgres `events` |
+| Screenshot frames | **Native** | `POST /v1/batch` | `screen` | blob + `mobile_frames` index |
+
+Both share `siteKey` + `sessionId`. No `seq` collision: structured events never write replay chunks; `screen` frames get their own frame index. The ingest endpoint already accepts new event types (permissive validation), so **no ingest change is needed** — only a worker routing rule for `type:'screen'`.
+
+## Roadmap
+
+- [x] JS core — public API, session/identity, network/error/console capture, transport (`src/`)
+- [x] Wire format — `MobileScreenEvent` (`type:'screen'`) + `MobileTouchEvent` in `@obsrviq/types`
+- [ ] Native iOS capture (Swift TurboModule) — `ios/` *(task #95)*
+- [ ] Native Android capture (Kotlin TurboModule) — `android/` *(task #96)*
+- [ ] Backend — route `type:'screen'` to blob + `mobile_frames`, migration *(task #97)*
+- [ ] Player — mobile screenshot renderer + device-based routing *(task #98)*
+
+## Building (native)
+
+Native code can't be compiled in the SDK repo — build it inside a real RN app and test on devices (jank only shows on hardware, especially low-end). Codegen runs automatically during the app's iOS/Android build from [`src/spec/NativeLumeraReplay.ts`](src/spec/NativeLumeraReplay.ts).

package/android/build.gradle

@@ -0,0 +1,31 @@
+buildscript {
+  repositories { google(); mavenCentral() }
+  dependencies { classpath "com.android.tools.build:gradle:8.2.1" }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"   // REQUIRED: sources are Kotlin — without this the .kt files are silently skipped
+apply plugin: "com.facebook.react"   // enables New-Arch codegen for the TurboModule
+
+android {
+  namespace "app.lumera.replay"
+  compileSdkVersion safeExtGet("compileSdkVersion", 35)
+
+  defaultConfig {
+    minSdkVersion safeExtGet("minSdkVersion", 24)   // PixelCopy(Surface) = 24; window overload = 26
+    targetSdkVersion safeExtGet("targetSdkVersion", 35)
+  }
+
+  buildFeatures { buildConfig true }
+}
+
+repositories { google(); mavenCentral() }
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"
+}
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

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

@@ -0,0 +1,39 @@
+package app.lumera.replay
+
+import android.view.View
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+
+/**
+ * Backs the optional `<LumeraMask>` JS component. It is a plain pass-through container
+ * (children render normally); its sole job is to tell the capture engine "redact my
+ * subtree". On attach it registers its own View.id in [LumeraReplayModule.maskedTags];
+ * on detach it removes it. This is the geometry [LumeraReplayModule.collectMaskRects]
+ * walks: an explicitly-masked container yields one redaction block over the whole subtree.
+ *
+ * Kept deliberately minimal — no custom props, no shadow node. JS can also drive masking
+ * imperatively via `NativeLumeraReplay.setViewMasked(reactTag, masked)` without this view.
+ */
+@ReactModule(name = LumeraMaskViewManager.REACT_CLASS)
+class LumeraMaskViewManager : SimpleViewManager<View>() {
+
+  override fun getName() = REACT_CLASS
+
+  override fun createViewInstance(reactContext: ThemedReactContext): View =
+    object : View(reactContext) {
+      override fun onAttachedToWindow() {
+        super.onAttachedToWindow()
+        LumeraReplayModule.maskTag(id)
+      }
+
+      override fun onDetachedFromWindow() {
+        LumeraReplayModule.unmaskTag(id)
+        super.onDetachedFromWindow()
+      }
+    }
+
+  companion object {
+    const val REACT_CLASS = "LumeraMask"
+  }
+}