@akhilpulse/samadhaan-session-replay 0.2.9 → 0.3.1

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,281 @@
+package com.akhilpulse.sessionreplay
+
+import android.app.Activity
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.PorterDuff
+import android.os.Build
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Base64
+import android.view.PixelCopy
+import android.view.View
+import android.view.ViewGroup
+import android.view.Window
+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
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * Captures the full visible screen by enumerating EVERY active Window the
+ * app currently has on screen (the Activity window plus any Dialog windows
+ * — react-native `Modal`, react-native-modal, react-native-paper Dialog,
+ * many bottom-sheet libraries, etc. all render into separate Dialog
+ * windows on Android), running a PixelCopy on each, and compositing them
+ * onto a single bitmap in the same z-order they're drawn.
+ *
+ * PixelCopy reads the actual on-screen pixels, so hardware-accelerated
+ * layers (views with `elevation` / `zIndex`, native SurfaceViews like
+ * react-native-maps, FABs with shadows) are all included.
+ *
+ * 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 activityWindow = activity.window
+        val activityDecor = activityWindow.decorView
+        val srcW = activityDecor.width
+        val srcH = activityDecor.height
+        if (srcW <= 0 || srcH <= 0) {
+          promise.reject("E_NO_SIZE", "Decor view has zero size")
+          return@runOnUiThread
+        }
+
+        // Discover every active Window via WindowManagerGlobal reflection.
+        // The list is returned in the order Android added them, which is
+        // bottom-to-top z-order (Activity window first, then Dialogs / Toasts
+        // on top), so we composite in that same order.
+        val windows = collectWindows(activityWindow)
+
+        val composite = Bitmap.createBitmap(srcW, srcH, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(composite)
+        // Pre-fill black so any sub-window that fails capture doesn't show
+        // garbage memory.
+        canvas.drawColor(0xFF000000.toInt())
+
+        val handlerThread = HandlerThread("SessionReplayPixelCopy")
+        handlerThread.start()
+        val handler = Handler(handlerThread.looper)
+
+        val remaining = AtomicInteger(windows.size)
+        val results = arrayOfNulls<Bitmap>(windows.size)
+        val locations = Array(windows.size) { intArrayOf(0, 0) }
+
+        if (windows.isEmpty()) {
+          // Should never happen — at least the Activity window exists — but
+          // bail safely instead of hanging.
+          finish(composite, srcW, srcH, targetWidth, quality, promise, handlerThread)
+          return@runOnUiThread
+        }
+
+        for ((index, win) in windows.withIndex()) {
+          val decor: View = win.decorView
+          val w = decor.width
+          val h = decor.height
+          if (w <= 0 || h <= 0) {
+            // Skip zero-size windows (e.g. just-dismissed dialogs).
+            results[index] = null
+            if (remaining.decrementAndGet() == 0) {
+              compositeAll(canvas, windows, results, locations)
+              finish(composite, srcW, srcH, targetWidth, quality, promise, handlerThread)
+            }
+            continue
+          }
+          // Capture this window's screen-space origin so we can position it
+          // correctly on the composite (Dialog windows are usually centered
+          // or anchored, not at 0,0).
+          decor.getLocationOnScreen(locations[index])
+
+          val sub = Bitmap.createBitmap(w, h, Bitmap.Config.ARGB_8888)
+          try {
+            PixelCopy.request(
+                win,
+                sub,
+                { result ->
+                  if (result == PixelCopy.SUCCESS) {
+                    results[index] = sub
+                  } else {
+                    sub.recycle()
+                    results[index] = null
+                  }
+                  if (remaining.decrementAndGet() == 0) {
+                    compositeAll(canvas, windows, results, locations)
+                    finish(composite, srcW, srcH, targetWidth, quality, promise, handlerThread)
+                  }
+                },
+                handler
+            )
+          } catch (e: Throwable) {
+            // Some windows (e.g. SurfaceView-only windows, secure windows)
+            // may reject PixelCopy synchronously. Skip them.
+            sub.recycle()
+            results[index] = null
+            if (remaining.decrementAndGet() == 0) {
+              compositeAll(canvas, windows, results, locations)
+              finish(composite, srcW, srcH, targetWidth, quality, promise, handlerThread)
+            }
+          }
+        }
+      } catch (e: Throwable) {
+        promise.reject("E_OUTER", e)
+      }
+    }
+  }
+
+  /**
+   * Reflects into android.view.WindowManagerGlobal to obtain every Window
+   * the app currently has attached. Falls back to just the Activity window
+   * if reflection fails (newer Android versions or vendor-modified ROMs).
+   */
+  private fun collectWindows(activityWindow: Window): List<Window> {
+    val list = mutableListOf<Window>()
+    try {
+      val wmgClass = Class.forName("android.view.WindowManagerGlobal")
+      val getInstance = wmgClass.getMethod("getInstance")
+      val wmg = getInstance.invoke(null)
+
+      // mViews: ArrayList<View>  (the decor view of each window, in z-order)
+      val viewsField = wmgClass.getDeclaredField("mViews").apply { isAccessible = true }
+      @Suppress("UNCHECKED_CAST")
+      val views = viewsField.get(wmg) as List<View>
+
+      // mParams: ArrayList<WindowManager.LayoutParams> — same length as mViews.
+      // (Reserved for future filtering by window type if needed.)
+
+      for (v in views) {
+        // Skip views that aren't currently attached / visible.
+        if (!v.isAttachedToWindow) continue
+        if (v.visibility != View.VISIBLE) continue
+        // Skip system overlays from other packages (shouldn't happen since
+        // mViews is per-process, but guard anyway).
+        val ctx = v.context ?: continue
+        if (ctx.packageName != activityWindow.context.packageName) continue
+
+        // The Window object itself isn't directly on the View, but PixelCopy
+        // accepts a Window — and we can synthesize a wrapper from the
+        // ViewRootImpl's Surface using the alternative PixelCopy.request
+        // overload. Easier path: walk up the view tree to find the
+        // associated Window via the context (Activity / Dialog).
+        val win = findWindowForView(v, activityWindow)
+        if (win != null && !list.contains(win)) {
+          list.add(win)
+        }
+      }
+    } catch (_: Throwable) {
+      // Reflection failed — at minimum capture the activity window.
+    }
+    if (list.isEmpty()) list.add(activityWindow)
+    return list
+  }
+
+  /**
+   * Tries to resolve the Window that owns a given decor view. Activity
+   * windows are easy (context is the Activity). Dialog windows store their
+   * Window via the view's parent context chain.
+   */
+  private fun findWindowForView(view: View, activityWindow: Window): Window? {
+    // If this view IS the activity's decor, return that window.
+    if (view === activityWindow.decorView) return activityWindow
+
+    // Try unwrapping the context chain to find a Dialog or Activity.
+    var ctx = view.context
+    var depth = 0
+    while (ctx != null && depth < 10) {
+      when (ctx) {
+        is Activity -> return ctx.window
+        else -> {
+          // android.view.ContextThemeWrapper / Dialog's inner context: try
+          // reflection to get a `getWindow()` if present.
+          try {
+            val m = ctx.javaClass.getMethod("getWindow")
+            val w = m.invoke(ctx)
+            if (w is Window) return w
+          } catch (_: Throwable) {
+            // Walk to the base context.
+          }
+          val baseField = try { ctx.javaClass.getMethod("getBaseContext") } catch (_: Throwable) { null }
+          ctx = try { baseField?.invoke(ctx) as? android.content.Context } catch (_: Throwable) { null }
+        }
+      }
+      depth++
+    }
+    return null
+  }
+
+  private fun compositeAll(
+      canvas: Canvas,
+      windows: List<Window>,
+      results: Array<Bitmap?>,
+      locations: Array<IntArray>
+  ) {
+    val activityOrigin = intArrayOf(0, 0)
+    if (windows.isNotEmpty()) {
+      windows[0].decorView.getLocationOnScreen(activityOrigin)
+    }
+    for (i in results.indices) {
+      val bmp = results[i] ?: continue
+      // Translate window screen-space origin into composite-space (relative
+      // to the activity decor's top-left).
+      val left = (locations[i][0] - activityOrigin[0]).toFloat()
+      val top = (locations[i][1] - activityOrigin[1]).toFloat()
+      canvas.drawBitmap(bmp, left, top, null)
+      bmp.recycle()
+    }
+  }
+
+  private fun finish(
+      composite: Bitmap,
+      srcW: Int,
+      srcH: Int,
+      targetWidth: Double,
+      quality: Double,
+      promise: Promise,
+      handlerThread: HandlerThread
+  ) {
+    try {
+      val tw = targetWidth.toInt().coerceAtLeast(1)
+      val scaled = if (tw < srcW) {
+        val th = (srcH.toDouble() / srcW.toDouble() * tw).toInt().coerceAtLeast(1)
+        Bitmap.createScaledBitmap(composite, tw, th, true)
+      } else composite
+
+      val q = (quality * 100).toInt().coerceIn(1, 100)
+      val baos = ByteArrayOutputStream()
+      scaled.compress(Bitmap.CompressFormat.JPEG, q, baos)
+      if (scaled !== composite) scaled.recycle()
+      composite.recycle()
+
+      val b64 = Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP)
+      promise.resolve(b64)
+    } catch (e: Throwable) {
+      promise.reject("E_FINISH", e)
+    } finally {
+      handlerThread.quitSafely()
+    }
+  }
+}

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.1",
   "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) {