@akhilpulse/samadhaan-session-replay 0.2.9 → 0.3.0

package/README.md

@@ -86,7 +86,7 @@ const { pause, resume, sessionId, status } = useSessionReplay();
 3. The guided-tour overlay must NOT cover the screen center. Use 4 thin edge strips with `pointerEvents: "none"`.
 4. Pause screenshot capture while the iOS keyboard is visible.
 5. Auto-mount the guided-tour overlay inside the provider, and singleton-guard it.
-6. **Android elevation/zIndex break screenshot capture.** `react-native-view-shot` (both `captureRef` and `captureScreen`) uses a software canvas draw on Android (`view.draw(canvas)`) that **silently skips any view promoted to a hardware compositor layer** — i.e. anything with `elevation: > 0` or `zIndex: > 0` (RN implements `zIndex` via `setElevation` on Android). The base view tree (including native `SurfaceView`s like `react-native-maps`) is captured fine, but FABs, modals, cards-with-shadow, and any RN overlay with elevation/zIndex will be invisible in screenshots and the live-streamed frames. **Fix in your app:** rely on tree order to control layering on Android (later siblings paint on top), and remove `elevation`/`zIndex` from anything that must appear in captures. Keep `shadowColor`/`shadowOpacity`/`shadowRadius` — those are iOS-only and don't trigger Android hardware layers. The SDK's own overlays (red pointer dot, end-tour pill, edge halos, consent card) follow this rule.
+6. **Android elevated views & screenshots.** `react-native-view-shot` uses a software canvas draw on Android (`view.draw(canvas)`) which silently skips any view promoted to a hardware compositor layer (anything with `elevation > 0` or `zIndex > 0` — RN implements `zIndex` via `setElevation` on Android). To work around this, **starting in 0.3.0 the SDK ships its own native module that captures via Android's `PixelCopy` API** (real on-screen pixels, including hardware layers, modals, FABs, and native `SurfaceView`s like `react-native-maps`). This module is autolinked — **after upgrading the SDK on Android you must rebuild the app** (`cd android && ./gradlew clean && cd .. && npx react-native run-android`) for the new screenshot path to activate. If the native module isn't present at runtime (older build, Expo Go), the SDK transparently falls back to `captureScreen` and the elevation limitation re-applies. Requires Android 7.0+ (API 24).
 
 ## Publishing
 

package/android/build.gradle

@@ -0,0 +1,42 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  namespace "com.akhilpulse.sessionreplay"
+  compileSdkVersion safeExtGet('compileSdkVersion', 34)
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 24)
+    targetSdkVersion safeExtGet('targetSdkVersion', 34)
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  sourceSets {
+    main {
+      java.srcDirs = ['src/main/java']
+      manifest.srcFile 'src/main/AndroidManifest.xml'
+    }
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:${safeExtGet('kotlinVersion', '1.9.24')}"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/akhilpulse/sessionreplay/SessionReplayPixelCopyModule.kt

@@ -0,0 +1,97 @@
+package com.akhilpulse.sessionreplay
+
+import android.app.Activity
+import android.graphics.Bitmap
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Base64
+import android.view.PixelCopy
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import java.io.ByteArrayOutputStream
+
+/**
+ * Captures the Activity's window via Android PixelCopy, which reads the
+ * actual on-screen pixels (including hardware-accelerated layers like views
+ * with `elevation` / `zIndex`, modals, FABs, native SurfaceViews/MapViews).
+ *
+ * Returns a base64-encoded JPEG (no `data:` prefix) — same shape as
+ * react-native-view-shot's `result: "base64"` so the JS side can use it
+ * interchangeably.
+ *
+ * Requires API 24 (Android 7.0). Falls back to view-shot in JS otherwise.
+ */
+class SessionReplayPixelCopyModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+  override fun getName(): String = "SessionReplayPixelCopy"
+
+  @ReactMethod
+  fun capture(targetWidth: Double, quality: Double, promise: Promise) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.N) {
+      promise.reject("E_API", "PixelCopy requires Android 7.0+ (API 24)")
+      return
+    }
+    val activity: Activity? = currentActivity
+    if (activity == null) {
+      promise.reject("E_NO_ACTIVITY", "No current activity")
+      return
+    }
+
+    activity.runOnUiThread {
+      try {
+        val window = activity.window
+        val decor = window.decorView
+        val srcW = decor.width
+        val srcH = decor.height
+        if (srcW <= 0 || srcH <= 0) {
+          promise.reject("E_NO_SIZE", "Decor view has zero size")
+          return@runOnUiThread
+        }
+        val bitmap = Bitmap.createBitmap(srcW, srcH, Bitmap.Config.ARGB_8888)
+
+        val handlerThread = HandlerThread("SessionReplayPixelCopy")
+        handlerThread.start()
+        val handler = Handler(handlerThread.looper)
+
+        PixelCopy.request(
+            window,
+            bitmap,
+            { result ->
+              try {
+                if (result == PixelCopy.SUCCESS) {
+                  val tw = targetWidth.toInt().coerceAtLeast(1)
+                  val scaled = if (tw < srcW) {
+                    val th = (srcH.toDouble() / srcW.toDouble() * tw).toInt().coerceAtLeast(1)
+                    Bitmap.createScaledBitmap(bitmap, tw, th, true)
+                  } else bitmap
+
+                  val q = (quality * 100).toInt().coerceIn(1, 100)
+                  val baos = ByteArrayOutputStream()
+                  scaled.compress(Bitmap.CompressFormat.JPEG, q, baos)
+                  if (scaled !== bitmap) scaled.recycle()
+                  bitmap.recycle()
+
+                  val b64 = Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP)
+                  promise.resolve(b64)
+                } else {
+                  bitmap.recycle()
+                  promise.reject("E_PIXELCOPY", "PixelCopy failed: $result")
+                }
+              } catch (e: Throwable) {
+                promise.reject("E_INNER", e)
+              } finally {
+                handlerThread.quitSafely()
+              }
+            },
+            handler
+        )
+      } catch (e: Throwable) {
+        promise.reject("E_OUTER", e)
+      }
+    }
+  }
+}

package/android/src/main/java/com/akhilpulse/sessionreplay/SessionReplayPixelCopyPackage.kt

@@ -0,0 +1,14 @@
+package com.akhilpulse.sessionreplay
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class SessionReplayPixelCopyPackage : ReactPackage {
+  override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> =
+      listOf(SessionReplayPixelCopyModule(reactContext))
+
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> =
+      emptyList()
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akhilpulse/samadhaan-session-replay",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "React Native SDK for Samadhaan Guided Support — session recording, live remote screen-share, take-control, and guided-tour overlays.",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -9,6 +9,8 @@
   "source": "src/index.ts",
   "files": [
     "src",
+    "android",
+    "react-native.config.js",
     "README.md"
   ],
   "scripts": {

package/react-native.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: './android',
+        packageImportPath: 'import com.akhilpulse.sessionreplay.SessionReplayPixelCopyPackage;',
+        packageInstance: 'new SessionReplayPixelCopyPackage()',
+      },
+      ios: null,
+    },
+  },
+};

package/src/SessionReplayProvider.tsx

@@ -31,12 +31,23 @@ import {
   findNodeHandle,
   StyleSheet,
   Pressable,
+  NativeModules,
 } from "react-native";
 import AsyncStorage from "@react-native-async-storage/async-storage";
 import { captureRef, captureScreen } from "react-native-view-shot";
 
+// Bundled native module (Android only) that uses PixelCopy to capture the
+// real on-screen pixels — including hardware-accelerated layers (views with
+// `elevation`/`zIndex`, modals, FABs, native MapViews). Autolinked via
+// react-native.config.js. Will be `undefined` if the host app hasn't been
+// rebuilt after upgrading the SDK, in which case we fall back to view-shot.
+type PixelCopyNative = { capture: (targetWidth: number, quality: number) => Promise<string> };
+const SessionReplayPixelCopy: PixelCopyNative | undefined =
+  Platform.OS === "android" ? (NativeModules as any).SessionReplayPixelCopy : undefined;
+let pixelCopyDisabled = false; // turned true after a runtime failure to avoid retrying every frame
+
 const STORAGE_KEY = "@akhilpulse/samadhaan-session-replay/sessionId";
-const SDK_VERSION = "0.2.9";
+const SDK_VERSION = "0.3.0";
 
 /** Default Samadhaan production endpoint. Override via `config.serverUrl` for staging. */
 export const DEFAULT_SERVER_URL = "https://samadhaan.pulseenergy.io";
@@ -232,9 +243,10 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
         const ref = rootRef.current;
         if (ref) {
           // Aggressively downscaled + low quality so capture+encode stays under ~50ms on mid devices.
-          // Android: captureRef misses views with `elevation` (they render in a separate
-          // hardware layer). Use captureScreen() which does an OS-level screenshot and
-          // includes elevated views (modals, FABs, cards with shadow, etc.).
+          // Android: native PixelCopy reads the actual on-screen pixels including
+          // hardware-accelerated layers (elevation/zIndex views, modals, FABs,
+          // native MapViews). Falls back to captureScreen if the native module
+          // isn't installed (host app hasn't rebuilt) or if PixelCopy fails.
           // iOS: captureRef on the app root works correctly and stays scoped to the app.
           const captureOpts = {
             format: "jpg" as const,
@@ -242,9 +254,22 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
             result: "base64" as const,
             width: 360,
           };
-          const uri = Platform.OS === "android"
-            ? await captureScreen(captureOpts)
-            : await captureRef(ref as any, captureOpts);
+          let uri: string;
+          if (Platform.OS === "android") {
+            if (SessionReplayPixelCopy && !pixelCopyDisabled) {
+              try {
+                uri = await SessionReplayPixelCopy.capture(360, 0.25);
+              } catch (err) {
+                if (__DEV__) console.warn("[session-replay] PixelCopy failed, falling back to view-shot:", err);
+                pixelCopyDisabled = true;
+                uri = await captureScreen(captureOpts);
+              }
+            } else {
+              uri = await captureScreen(captureOpts);
+            }
+          } else {
+            uri = await captureRef(ref as any, captureOpts);
+          }
           const blob = base64ToUint8Array(uri);
           // Stream binary over WS — no REST upload in the hot path.
           if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {