@akhilpulse/samadhaan-session-replay 0.2.7 → 0.3.0

package/README.md

@@ -81,11 +81,12 @@ const { pause, resume, sessionId, status } = useSessionReplay();
 
 ## Critical constraints (don't skip)
 
-1. Never use RN `<Modal>` for transient consent UI — use absolutely-positioned `<View>` with `zIndex: 9999`.
+1. Never use RN `<Modal>` for transient consent UI — use absolutely-positioned `<View>` (no `zIndex` — see #6).
 2. Never animate colors with `useNativeDriver: false` — causes 60fps JS commits that break touch handling on Fabric.
 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 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.7",
+  "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 } from "react-native-view-shot";
+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.6";
+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,12 +243,33 @@ 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.
-          const uri = await captureRef(ref as any, {
-            format: "jpg",
+          // 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,
             quality: 0.25,
-            result: "base64",
+            result: "base64" as const,
             width: 360,
-          });
+          };
+          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) {
@@ -356,6 +388,47 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
   // Captured root-View size (in points) so we can place the agent pointer correctly.
   const viewSizeRef = useRef<{ w: number; h: number }>({ w: 0, h: 0 });
 
+  // ---- Draggable End-tour pill ----
+  // Animated translate offset relative to the pill's anchored position (top-right).
+  const endTourPan = useRef(new Animated.ValueXY({ x: 0, y: 0 })).current;
+  const endTourPanResponder = useMemo(
+    () =>
+      PanResponder.create({
+        // Don't claim taps — let the inner Pressable receive onPress.
+        onStartShouldSetPanResponder: () => false,
+        // Only claim once the user clearly starts dragging (>4px).
+        onMoveShouldSetPanResponder: (_e, g) => Math.abs(g.dx) > 4 || Math.abs(g.dy) > 4,
+        onPanResponderGrant: () => {
+          endTourPan.extractOffset();
+        },
+        onPanResponderMove: Animated.event(
+          [null, { dx: endTourPan.x, dy: endTourPan.y }],
+          { useNativeDriver: false }
+        ),
+        onPanResponderRelease: () => {
+          endTourPan.flattenOffset();
+          // Clamp inside the visible root-view bounds so the pill never escapes off-screen.
+          const { w, h } = viewSizeRef.current;
+          const PILL_W = 110, PILL_H = 36, ANCHOR_TOP = 64, ANCHOR_RIGHT = 12, MARGIN = 8;
+          // Pill sits at top:64, right:12 by default. Translate ranges:
+          //   x: from -(w - ANCHOR_RIGHT - PILL_W - MARGIN)  to 0  (can move left from right edge)
+          //   y: from -(ANCHOR_TOP - MARGIN)  to (h - ANCHOR_TOP - PILL_H - MARGIN)
+          const minX = -(Math.max(0, w - ANCHOR_RIGHT - PILL_W - MARGIN));
+          const maxX = 0;
+          const minY = -(ANCHOR_TOP - MARGIN);
+          const maxY = Math.max(0, h - ANCHOR_TOP - PILL_H - MARGIN);
+          const cx = (endTourPan.x as any)._value;
+          const cy = (endTourPan.y as any)._value;
+          const nx = Math.min(maxX, Math.max(minX, cx));
+          const ny = Math.min(maxY, Math.max(minY, cy));
+          if (nx !== cx || ny !== cy) {
+            Animated.spring(endTourPan, { toValue: { x: nx, y: ny }, useNativeDriver: false, friction: 7 }).start();
+          }
+        },
+      }),
+    [endTourPan]
+  );
+
   function consentTour(accept: boolean) {
     if (accept) {
       setTourState((s) => ({ phase: "active", agentName: s.agentName }));
@@ -447,9 +520,14 @@ export function SessionReplayProvider({ config, children }: { config: Config; ch
             <View pointerEvents="none" style={[styles.edge, { bottom: 0, left: 0, right: 0, height: 4 }]} />
             <View pointerEvents="none" style={[styles.edge, { top: 0, bottom: 0, left: 0, width: 4 }]} />
             <View pointerEvents="none" style={[styles.edge, { top: 0, bottom: 0, right: 0, width: 4 }]} />
-            <Pressable onPress={endTourLocal} style={({ pressed }) => [styles.endTourPill, pressed && styles.btnPressed]} hitSlop={8}>
-              <Text style={styles.endTourText}>End tour</Text>
-            </Pressable>
+            <Animated.View
+              style={[styles.endTourPill, { transform: endTourPan.getTranslateTransform() }]}
+              {...endTourPanResponder.panHandlers}
+            >
+              <Pressable onPress={endTourLocal} style={({ pressed }) => [styles.endTourPressable, pressed && styles.btnPressed]} hitSlop={8}>
+                <Text style={styles.endTourText}>End tour</Text>
+              </Pressable>
+            </Animated.View>
             {pointer && (
               <>
                 <View pointerEvents="none" style={[styles.pointerHalo, { left: pointer.x - 24, top: pointer.y - 24 }]} />
@@ -511,15 +589,20 @@ const styles = StyleSheet.create({
     position: "absolute", width: 40, height: 40, borderRadius: 20,
     backgroundColor: "rgba(34,197,94,0.45)", borderWidth: 2, borderColor: "#22c55e",
   },
+  // NOTE: We intentionally avoid `elevation` and `zIndex` on SDK overlays.
+  // On Android, both push the view into a hardware compositor layer that
+  // `react-native-view-shot`'s software canvas draw cannot capture, so the
+  // overlay would be invisible in screenshots/streamed frames. Tree order
+  // (overlays rendered AFTER children) already keeps them visually on top.
   consentBackdrop: {
     position: "absolute", top: 0, left: 0, right: 0, bottom: 0,
     backgroundColor: "rgba(0,0,0,0.55)", justifyContent: "center", alignItems: "center",
-    paddingHorizontal: 24, zIndex: 9999,
+    paddingHorizontal: 24,
   },
   consentCard: {
     width: "100%", maxWidth: 360, backgroundColor: "#ffffff", borderRadius: 20,
     paddingVertical: 24, paddingHorizontal: 22, alignItems: "center",
-    shadowColor: "#000", shadowOpacity: 0.25, shadowRadius: 24, shadowOffset: { width: 0, height: 12 }, elevation: 12,
+    shadowColor: "#000", shadowOpacity: 0.25, shadowRadius: 24, shadowOffset: { width: 0, height: 12 },
   },
   consentIconWrap: {
     width: 56, height: 56, borderRadius: 28, alignItems: "center", justifyContent: "center",
@@ -545,23 +628,27 @@ const styles = StyleSheet.create({
   btnGhostText: { color: "#475569", fontSize: 15, fontWeight: "600" },
   btnPrimary: { backgroundColor: "#22c55e" },
   btnPrimaryText: { color: "#fff", fontSize: 15, fontWeight: "600" },
-  edge: { position: "absolute", backgroundColor: "rgba(34,197,94,0.7)", zIndex: 9998 },
+  edge: { position: "absolute", backgroundColor: "rgba(34,197,94,0.7)" },
   // End-tour pill: anchored to TOP-RIGHT with safe top inset (~64px) to clear iOS Dynamic Island & status bar.
+  // No `elevation`/`zIndex` — see consentBackdrop note above. Shadow is iOS-only and harmless on Android.
   endTourPill: {
-    position: "absolute", top: 64, right: 12, zIndex: 9999,
-    backgroundColor: "rgba(17,24,39,0.92)", paddingVertical: 8, paddingHorizontal: 14,
-    borderRadius: 999, flexDirection: "row", alignItems: "center",
-    shadowColor: "#000", shadowOpacity: 0.3, shadowRadius: 6, shadowOffset: { width: 0, height: 2 }, elevation: 6,
+    position: "absolute", top: 64, right: 12,
+    backgroundColor: "rgba(17,24,39,0.92)",
+    borderRadius: 999,
+    shadowColor: "#000", shadowOpacity: 0.3, shadowRadius: 6, shadowOffset: { width: 0, height: 2 },
+  },
+  endTourPressable: {
+    paddingVertical: 8, paddingHorizontal: 14,
+    flexDirection: "row", alignItems: "center", borderRadius: 999,
   },
   endTourText: { color: "#fff", fontSize: 13, fontWeight: "600" },
   pointer: {
     position: "absolute", width: 24, height: 24, borderRadius: 12,
     backgroundColor: "rgba(239,68,68,1)", borderWidth: 3, borderColor: "#fff",
     shadowColor: "#ef4444", shadowOpacity: 0.9, shadowRadius: 8,
-    elevation: 12, zIndex: 10000,
   },
   pointerHalo: {
     position: "absolute", width: 48, height: 48, borderRadius: 24,
-    backgroundColor: "rgba(239,68,68,0.25)", zIndex: 9999,
+    backgroundColor: "rgba(239,68,68,0.25)",
   },
 });