@repliqo/sdk-react-native 0.4.1 → 0.5.0

package/INTEGRATION_GUIDE.md

@@ -1382,3 +1382,76 @@ the user naturally scrolls, exactly like the ScrollView variant.
 > `@react-native/metro-config` for RN 0.72+ and in Expo). On older RN
 > versions either install AsyncStorage, pass your own `storage`, or enable
 > that Metro option.
+
+## 21. Privacy: Masking Sensitive Content
+
+Session replay screenshots and heatmap tiles are real pixels from the
+user's screen. Anything visible is captured — including emails, names,
+balances and card numbers. Repliqo redacts sensitive regions **on the
+device, before the image is encoded**, so those pixels never reach the
+network or your storage.
+
+### Automatic
+
+Password inputs are always redacted, no configuration needed:
+
+```tsx
+<TextInput secureTextEntry value={password} onChangeText={setPassword} />
+```
+
+Any field using a password transformation is detected natively and covered
+with an opaque block in every capture.
+
+### Manual
+
+Wrap anything else you don't want captured:
+
+```tsx
+import { RepliqoMask } from '@repliqo/sdk-react-native';
+
+<RepliqoMask>
+  <Text>{user.email}</Text>
+  <Text>{account.balance}</Text>
+</RepliqoMask>
+```
+
+The content renders normally on the device — only the captured image is
+masked. Masking applies to BOTH session replay snapshots and the scroll
+tiles used to build heatmap backgrounds.
+
+Temporarily disable redaction for a subtree (e.g. behind a "show details"
+toggle you deliberately want in the replay):
+
+```tsx
+<RepliqoMask enabled={!hideSensitive}>
+  <OrderSummary />
+</RepliqoMask>
+```
+
+`RepliqoMask` accepts all `View` props, so it can replace a wrapper you
+already have. A `nativeID` you pass is preserved.
+
+### What to mask
+
+At minimum, wrap anything that would be a compliance problem in a
+screenshot: payment fields, government/ID numbers, health information,
+full names and emails, auth tokens shown on screen, and any PII your
+privacy policy commits to protecting.
+
+> Masking covers the region occupied by the wrapped views. If a sensitive
+> value is rendered by a native module that draws outside its own view
+> bounds (rare), verify the result in a real replay before shipping.
+
+### Platform behavior (important)
+
+Redaction is performed by the **native Android capture path**, which paints
+over the sensitive regions before the JPEG is encoded.
+
+When that path is unavailable — on iOS, or on Android if a frame can only be
+produced by the `react-native-view-shot` fallback — the SDK **fails closed**:
+while any `<RepliqoMask>` is mounted, those frames are **skipped entirely**
+rather than captured without redaction. You may see gaps in a replay on
+those platforms; that is deliberate. Losing a frame is preferable to
+uploading content you marked as sensitive.
+
+Heatmap scroll tiles always use the native path, so they are always redacted.

package/android/src/main/java/com/repliqo/screencapture/MaskCollector.java

@@ -0,0 +1,159 @@
+package com.repliqo.screencapture;
+
+import android.graphics.Rect;
+import android.text.method.PasswordTransformationMethod;
+import android.util.Log;
+import android.view.View;
+import android.view.ViewGroup;
+import android.widget.TextView;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Finds the on-screen regions that must be redacted before a capture leaves
+ * the device.
+ *
+ * A region is masked when ANY of these hold:
+ *
+ *   1. The view is tagged with the Repliqo mask marker — set by the
+ *      {@code <RepliqoMask>} JS component through React Native's
+ *      {@code nativeID} prop (and, as a fallback, {@code testID} or the
+ *      accessibility label).
+ *   2. The view is a password field (any TextView/EditText using a
+ *      password transformation). These are masked AUTOMATICALLY: a
+ *      session-replay screenshot must never contain a typed password,
+ *      even if the host app forgot to wrap it.
+ *
+ * All tag lookups are defensive — React Native's internal resource id is
+ * resolved by name at runtime, so this keeps working across RN versions
+ * and degrades to the fallbacks (never throws) if it can't be resolved.
+ */
+final class MaskCollector {
+    private static final String TAG = "RepliqoCapture";
+
+    /** Marker value set by the RepliqoMask component. */
+    static final String MASK_MARKER = "repliqo-mask";
+
+    /** Guard against pathological / cyclic view trees. */
+    private static final int MAX_DEPTH = 60;
+
+    /**
+     * Cached resolution of React Native's `view_tag_native_id` resource id.
+     * 0 = not resolved yet, -1 = resolution failed (don't retry).
+     */
+    private static int nativeIdTagKey = 0;
+
+    private MaskCollector() {}
+
+    /**
+     * Collect the rectangles to redact, in coordinates RELATIVE to
+     * {@code root} (so they can be painted with the same canvas transform
+     * used to draw that root view).
+     */
+    static List<Rect> collect(View root) {
+        List<Rect> rects = new ArrayList<>();
+        try {
+            int[] rootLoc = new int[2];
+            root.getLocationInWindow(rootLoc);
+            walk(root, rootLoc, rects, 0);
+        } catch (Exception e) {
+            // Never let mask collection break a capture — but a failure here
+            // means unredacted output, so it must be visible in logs.
+            Log.w(TAG, "Mask collection failed: " + e.getMessage());
+        }
+        return rects;
+    }
+
+    private static void walk(View view, int[] rootLoc, List<Rect> out, int depth) {
+        if (view == null || depth > MAX_DEPTH) return;
+        if (view.getVisibility() != View.VISIBLE) return;
+        if (view.getWidth() <= 0 || view.getHeight() <= 0) return;
+
+        if (isSensitive(view)) {
+            int[] loc = new int[2];
+            view.getLocationInWindow(loc);
+            int left = loc[0] - rootLoc[0];
+            int top = loc[1] - rootLoc[1];
+            out.add(new Rect(left, top, left + view.getWidth(), top + view.getHeight()));
+            // No need to descend: the whole subtree is covered by this rect.
+            return;
+        }
+
+        if (view instanceof ViewGroup) {
+            ViewGroup group = (ViewGroup) view;
+            int count = group.getChildCount();
+            for (int i = 0; i < count; i++) {
+                walk(group.getChildAt(i), rootLoc, out, depth + 1);
+            }
+        }
+    }
+
+    private static boolean isSensitive(View view) {
+        return isPasswordField(view) || hasMaskMarker(view);
+    }
+
+    /**
+     * Password fields are redacted automatically — no host-app opt-in.
+     */
+    private static boolean isPasswordField(View view) {
+        try {
+            if (!(view instanceof TextView)) return false;
+            TextView tv = (TextView) view;
+            return tv.getTransformationMethod() instanceof PasswordTransformationMethod;
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    private static boolean hasMaskMarker(View view) {
+        // 1. React Native `nativeID` — stored under RN's own tag key.
+        try {
+            int key = resolveNativeIdTagKey(view);
+            if (key > 0) {
+                Object tag = view.getTag(key);
+                if (matches(tag)) return true;
+            }
+        } catch (Exception ignored) {
+            // fall through to the generic fallbacks
+        }
+
+        // 2. Plain view tag (RN `testID` on several versions).
+        try {
+            if (matches(view.getTag())) return true;
+        } catch (Exception ignored) {
+            // fall through
+        }
+
+        // 3. Accessibility label — last-resort marker.
+        try {
+            CharSequence desc = view.getContentDescription();
+            if (desc != null && matches(desc.toString())) return true;
+        } catch (Exception ignored) {
+            // fall through
+        }
+
+        return false;
+    }
+
+    private static boolean matches(Object tag) {
+        return tag instanceof String && ((String) tag).startsWith(MASK_MARKER);
+    }
+
+    /**
+     * Resolve React Native's internal `view_tag_native_id` resource id by
+     * NAME rather than linking against com.facebook.react.R, so this works
+     * regardless of the RN version the host app builds with.
+     */
+    private static int resolveNativeIdTagKey(View view) {
+        if (nativeIdTagKey != 0) return nativeIdTagKey;
+        try {
+            int id = view.getResources().getIdentifier(
+                    "view_tag_native_id", "id", view.getContext().getPackageName());
+            nativeIdTagKey = id > 0 ? id : -1;
+        } catch (Exception e) {
+            nativeIdTagKey = -1;
+        }
+        return nativeIdTagKey;
+    }
+}

package/android/src/main/java/com/repliqo/screencapture/MultiWindowCapture.java

@@ -3,6 +3,8 @@ package com.repliqo.screencapture;
 import android.app.Activity;
 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.util.Base64;
@@ -37,6 +39,25 @@ public class MultiWindowCapture {
     private static final int TARGET_WIDTH = 390;
     private static final int JPEG_QUALITY = 40;
 
+    /**
+     * Redaction blocks. Opaque fill so nothing shows through JPEG
+     * compression, plus a visible outline so a reviewer can tell the area
+     * was intentionally masked rather than blank/broken.
+     */
+    private static final Paint MASK_FILL_PAINT = new Paint();
+    private static final Paint MASK_STROKE_PAINT = new Paint();
+
+    static {
+        MASK_FILL_PAINT.setColor(Color.rgb(30, 34, 60));
+        MASK_FILL_PAINT.setStyle(Paint.Style.FILL);
+        MASK_FILL_PAINT.setAntiAlias(false);
+
+        MASK_STROKE_PAINT.setColor(Color.rgb(99, 102, 241));
+        MASK_STROKE_PAINT.setStyle(Paint.Style.STROKE);
+        MASK_STROKE_PAINT.setStrokeWidth(2f);
+        MASK_STROKE_PAINT.setAntiAlias(false);
+    }
+
     /**
      * Capture all visible windows composited into a single JPEG.
      *
@@ -105,6 +126,11 @@ public class MultiWindowCapture {
                         Log.w(TAG, "Failed to draw view: " + e.getMessage());
                     }
 
+                    // Redact sensitive regions IN THE SAME transform, right
+                    // after drawing this window — password fields and views
+                    // wrapped in <RepliqoMask> must never reach the network.
+                    drawMasks(canvas, info.view);
+
                     canvas.restore();
                 }
 
@@ -123,6 +149,25 @@ public class MultiWindowCapture {
         }
     }
 
+    /**
+     * Paint opaque blocks over every region that must not leave the device
+     * (password fields, views wrapped in RepliqoMask). Coordinates come back
+     * relative to {@code root}, so this must be called with the same canvas
+     * transform used to draw it.
+     */
+    private static void drawMasks(Canvas canvas, View root) {
+        try {
+            List<Rect> rects = MaskCollector.collect(root);
+            if (rects.isEmpty()) return;
+            for (Rect r : rects) {
+                canvas.drawRect(r, MASK_FILL_PAINT);
+                canvas.drawRect(r, MASK_STROKE_PAINT);
+            }
+        } catch (Exception e) {
+            Log.w(TAG, "Failed to draw masks: " + e.getMessage());
+        }
+    }
+
     /**
      * Fallback: capture just the activity's decor view.
      */
@@ -135,6 +180,7 @@ public class MultiWindowCapture {
             Canvas canvas = new Canvas(bitmap);
             canvas.scale(scale, scale);
             decorView.draw(canvas);
+            drawMasks(canvas, decorView);
 
             String base64 = bitmapToBase64(bitmap);
             if (base64 == null) return null;

package/dist/components/RepliqoMask.d.ts

@@ -0,0 +1,41 @@
+import React from 'react';
+import { type ViewProps } from 'react-native';
+/**
+ * Marker value the native capture layer looks for. Must stay in sync with
+ * MaskCollector.MASK_MARKER on the Android side.
+ */
+export declare const REPLIQO_MASK_MARKER = "repliqo-mask";
+export interface RepliqoMaskProps extends ViewProps {
+    /**
+     * Set to false to temporarily disable redaction for this subtree
+     * (e.g. behind a "show password" toggle you explicitly want captured).
+     * Defaults to true.
+     */
+    enabled?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * Redacts everything inside it from session-replay screenshots and heatmap
+ * tiles. The content still renders normally on the device — only the
+ * captured image is masked, and the masking happens ON-DEVICE, before the
+ * image is encoded, so sensitive pixels never reach the network.
+ *
+ * ```tsx
+ * <RepliqoMask>
+ *   <Text>{user.email}</Text>
+ *   <CreditCardForm />
+ * </RepliqoMask>
+ * ```
+ *
+ * Password inputs (`<TextInput secureTextEntry>`) are redacted
+ * AUTOMATICALLY and do not need to be wrapped.
+ *
+ * Implementation note: the marker travels through the `nativeID` prop,
+ * which React Native forwards to the underlying Android view. Any
+ * `nativeID` you pass yourself is preserved (appended after the marker) so
+ * existing view lookups keep working.
+ */
+export declare function RepliqoMask({ enabled, children, nativeID, ...props }: RepliqoMaskProps): React.JSX.Element;
+export declare namespace RepliqoMask {
+    var displayName: string;
+}

package/dist/components/RepliqoMask.js

@@ -0,0 +1,86 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPLIQO_MASK_MARKER = void 0;
+exports.RepliqoMask = RepliqoMask;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const maskRegistry_1 = require("../privacy/maskRegistry");
+/**
+ * Marker value the native capture layer looks for. Must stay in sync with
+ * MaskCollector.MASK_MARKER on the Android side.
+ */
+exports.REPLIQO_MASK_MARKER = 'repliqo-mask';
+/**
+ * Redacts everything inside it from session-replay screenshots and heatmap
+ * tiles. The content still renders normally on the device — only the
+ * captured image is masked, and the masking happens ON-DEVICE, before the
+ * image is encoded, so sensitive pixels never reach the network.
+ *
+ * ```tsx
+ * <RepliqoMask>
+ *   <Text>{user.email}</Text>
+ *   <CreditCardForm />
+ * </RepliqoMask>
+ * ```
+ *
+ * Password inputs (`<TextInput secureTextEntry>`) are redacted
+ * AUTOMATICALLY and do not need to be wrapped.
+ *
+ * Implementation note: the marker travels through the `nativeID` prop,
+ * which React Native forwards to the underlying Android view. Any
+ * `nativeID` you pass yourself is preserved (appended after the marker) so
+ * existing view lookups keep working.
+ */
+function RepliqoMask({ enabled = true, children, nativeID, ...props }) {
+    // Announce this region while it's mounted. If a capture can only be
+    // produced by the fallback path (which cannot redact), the SDK skips
+    // that frame instead of shipping the content this mask protects.
+    (0, react_1.useEffect)(() => {
+        if (!enabled)
+            return;
+        (0, maskRegistry_1.registerMask)();
+        return () => (0, maskRegistry_1.unregisterMask)();
+    }, [enabled]);
+    const markerId = enabled
+        ? nativeID
+            ? `${exports.REPLIQO_MASK_MARKER}:${nativeID}`
+            : exports.REPLIQO_MASK_MARKER
+        : nativeID;
+    return (<react_native_1.View {...props} nativeID={markerId} collapsable={false}>
+      {children}
+    </react_native_1.View>);
+}
+RepliqoMask.displayName = 'RepliqoMask';

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export type { SnapshotCaptureConfig } from './snapshot/capture';
 export type { ScreenshotResult } from './snapshot/captureScreenshot';
 export { RepliqoScrollView } from './components/RepliqoScrollView';
 export { RepliqoFlatList } from './components/RepliqoFlatList';
+export { RepliqoMask, REPLIQO_MASK_MARKER } from './components/RepliqoMask';
+export type { RepliqoMaskProps } from './components/RepliqoMask';
 export type { PersistentStorage } from './core/storage';
 export { DEFAULT_CONFIG } from './core/config';
 export type { ResolvedConfig } from './core/config';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CONFIG = exports.RepliqoFlatList = exports.RepliqoScrollView = exports.captureNativeFrame = exports.isNativeScreenCaptureAvailable = exports.captureScreenshot = exports.SnapshotCapture = exports.ErrorTracker = exports.trackScreenExit = exports.trackScreenEnter = exports.trackScreenChange = exports.useNavigationTracker = exports.TouchTracker = exports.AppAnalytics = void 0;
+exports.DEFAULT_CONFIG = exports.REPLIQO_MASK_MARKER = exports.RepliqoMask = exports.RepliqoFlatList = exports.RepliqoScrollView = exports.captureNativeFrame = exports.isNativeScreenCaptureAvailable = exports.captureScreenshot = exports.SnapshotCapture = exports.ErrorTracker = exports.trackScreenExit = exports.trackScreenEnter = exports.trackScreenChange = exports.useNavigationTracker = exports.TouchTracker = exports.AppAnalytics = void 0;
 // Main class
 var client_1 = require("./core/client");
 Object.defineProperty(exports, "AppAnalytics", { enumerable: true, get: function () { return client_1.AppAnalytics; } });
@@ -28,6 +28,9 @@ var RepliqoScrollView_1 = require("./components/RepliqoScrollView");
 Object.defineProperty(exports, "RepliqoScrollView", { enumerable: true, get: function () { return RepliqoScrollView_1.RepliqoScrollView; } });
 var RepliqoFlatList_1 = require("./components/RepliqoFlatList");
 Object.defineProperty(exports, "RepliqoFlatList", { enumerable: true, get: function () { return RepliqoFlatList_1.RepliqoFlatList; } });
+var RepliqoMask_1 = require("./components/RepliqoMask");
+Object.defineProperty(exports, "RepliqoMask", { enumerable: true, get: function () { return RepliqoMask_1.RepliqoMask; } });
+Object.defineProperty(exports, "REPLIQO_MASK_MARKER", { enumerable: true, get: function () { return RepliqoMask_1.REPLIQO_MASK_MARKER; } });
 // Config
 var config_1 = require("./core/config");
 Object.defineProperty(exports, "DEFAULT_CONFIG", { enumerable: true, get: function () { return config_1.DEFAULT_CONFIG; } });

package/dist/privacy/maskRegistry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Tracks how many <RepliqoMask> regions are currently mounted.
+ *
+ * Redaction is implemented in the native capture path (it paints over the
+ * sensitive regions before the JPEG is encoded). The react-native-view-shot
+ * fallback has no such step, so a frame produced by it would contain the
+ * unredacted pixels.
+ *
+ * This registry lets the capture layer FAIL CLOSED: when the host app has
+ * asked for masking but only the unredacted path is available, the frame is
+ * skipped instead of uploaded. Losing a replay frame is always preferable to
+ * leaking the content the developer explicitly marked as sensitive.
+ *
+ * Lives in its own module so both the component and the capture function can
+ * use it without importing the SDK client (which would be circular).
+ */
+/** Called by RepliqoMask on mount (when enabled). */
+export declare function registerMask(): void;
+/** Called by RepliqoMask on unmount (or when disabled). */
+export declare function unregisterMask(): void;
+/** True when at least one mask region is currently mounted. */
+export declare function hasActiveMasks(): boolean;
+/** Test-only: reset the counter between cases. */
+export declare function __resetMaskRegistryForTests(): void;

package/dist/privacy/maskRegistry.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Tracks how many <RepliqoMask> regions are currently mounted.
+ *
+ * Redaction is implemented in the native capture path (it paints over the
+ * sensitive regions before the JPEG is encoded). The react-native-view-shot
+ * fallback has no such step, so a frame produced by it would contain the
+ * unredacted pixels.
+ *
+ * This registry lets the capture layer FAIL CLOSED: when the host app has
+ * asked for masking but only the unredacted path is available, the frame is
+ * skipped instead of uploaded. Losing a replay frame is always preferable to
+ * leaking the content the developer explicitly marked as sensitive.
+ *
+ * Lives in its own module so both the component and the capture function can
+ * use it without importing the SDK client (which would be circular).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerMask = registerMask;
+exports.unregisterMask = unregisterMask;
+exports.hasActiveMasks = hasActiveMasks;
+exports.__resetMaskRegistryForTests = __resetMaskRegistryForTests;
+let activeMasks = 0;
+/** Called by RepliqoMask on mount (when enabled). */
+function registerMask() {
+    activeMasks++;
+}
+/** Called by RepliqoMask on unmount (or when disabled). */
+function unregisterMask() {
+    activeMasks = Math.max(0, activeMasks - 1);
+}
+/** True when at least one mask region is currently mounted. */
+function hasActiveMasks() {
+    return activeMasks > 0;
+}
+/** Test-only: reset the counter between cases. */
+function __resetMaskRegistryForTests() {
+    activeMasks = 0;
+}

package/dist/snapshot/captureScreenshot.d.ts

@@ -12,9 +12,11 @@ export interface ScreenshotResult {
  *
  *  1. Native multi-window capture (Android) — uses View.draw() on all
  *     app windows via WindowManagerGlobal reflection. Captures modals,
- *     alerts, dialogs, overlays. No permissions needed.
+ *     alerts, dialogs, overlays. No permissions needed. This is the ONLY
+ *     path that applies <RepliqoMask> / password redaction.
  *  2. react-native-view-shot fallback — captures the main RN view only
- *     (no modals or native dialogs)
+ *     (no modals or native dialogs), WITHOUT redaction. Skipped entirely
+ *     when masks are mounted (fail closed).
  *  3. null — if both are unavailable
  *
  * Never throws. Returns null on any failure.

package/dist/snapshot/captureScreenshot.js

@@ -4,6 +4,7 @@ exports.captureScreenshot = captureScreenshot;
 exports.__resetCaptureRefForTests = __resetCaptureRefForTests;
 const react_native_1 = require("react-native");
 const NativeScreenCapture_1 = require("./NativeScreenCapture");
+const maskRegistry_1 = require("../privacy/maskRegistry");
 const TARGET_WIDTH = 390;
 const JPEG_QUALITY = 0.4;
 // --- view-shot fallback (lazy-loaded) ---
@@ -33,9 +34,11 @@ function resolveViewShot() {
  *
  *  1. Native multi-window capture (Android) — uses View.draw() on all
  *     app windows via WindowManagerGlobal reflection. Captures modals,
- *     alerts, dialogs, overlays. No permissions needed.
+ *     alerts, dialogs, overlays. No permissions needed. This is the ONLY
+ *     path that applies <RepliqoMask> / password redaction.
  *  2. react-native-view-shot fallback — captures the main RN view only
- *     (no modals or native dialogs)
+ *     (no modals or native dialogs), WITHOUT redaction. Skipped entirely
+ *     when masks are mounted (fail closed).
  *  3. null — if both are unavailable
  *
  * Never throws. Returns null on any failure.
@@ -49,7 +52,12 @@ async function captureScreenshot() {
         // If native returns null (e.g. first frame not ready), fall through
         // to view-shot for this single frame rather than showing nothing.
     }
-    // Strategy 2: react-native-view-shot fallback
+    // Strategy 2: react-native-view-shot fallback.
+    // FAIL CLOSED: this path cannot redact, so if the host app has mounted
+    // <RepliqoMask> regions we skip the frame rather than upload the
+    // sensitive pixels it explicitly asked to hide.
+    if ((0, maskRegistry_1.hasActiveMasks)())
+        return null;
     const captureScreen = resolveViewShot();
     if (!captureScreen)
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repliqo/sdk-react-native",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Session replay & analytics SDK for React Native. Captures screenshots (including modals/alerts), navigation, screen visits, and custom events.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/components/RepliqoMask.tsx

@@ -0,0 +1,70 @@
+import React, { useEffect } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { registerMask, unregisterMask } from '../privacy/maskRegistry';
+
+/**
+ * Marker value the native capture layer looks for. Must stay in sync with
+ * MaskCollector.MASK_MARKER on the Android side.
+ */
+export const REPLIQO_MASK_MARKER = 'repliqo-mask';
+
+export interface RepliqoMaskProps extends ViewProps {
+  /**
+   * Set to false to temporarily disable redaction for this subtree
+   * (e.g. behind a "show password" toggle you explicitly want captured).
+   * Defaults to true.
+   */
+  enabled?: boolean;
+  children?: React.ReactNode;
+}
+
+/**
+ * Redacts everything inside it from session-replay screenshots and heatmap
+ * tiles. The content still renders normally on the device — only the
+ * captured image is masked, and the masking happens ON-DEVICE, before the
+ * image is encoded, so sensitive pixels never reach the network.
+ *
+ * ```tsx
+ * <RepliqoMask>
+ *   <Text>{user.email}</Text>
+ *   <CreditCardForm />
+ * </RepliqoMask>
+ * ```
+ *
+ * Password inputs (`<TextInput secureTextEntry>`) are redacted
+ * AUTOMATICALLY and do not need to be wrapped.
+ *
+ * Implementation note: the marker travels through the `nativeID` prop,
+ * which React Native forwards to the underlying Android view. Any
+ * `nativeID` you pass yourself is preserved (appended after the marker) so
+ * existing view lookups keep working.
+ */
+export function RepliqoMask({
+  enabled = true,
+  children,
+  nativeID,
+  ...props
+}: RepliqoMaskProps) {
+  // Announce this region while it's mounted. If a capture can only be
+  // produced by the fallback path (which cannot redact), the SDK skips
+  // that frame instead of shipping the content this mask protects.
+  useEffect(() => {
+    if (!enabled) return;
+    registerMask();
+    return () => unregisterMask();
+  }, [enabled]);
+
+  const markerId = enabled
+    ? nativeID
+      ? `${REPLIQO_MASK_MARKER}:${nativeID}`
+      : REPLIQO_MASK_MARKER
+    : nativeID;
+
+  return (
+    <View {...props} nativeID={markerId} collapsable={false}>
+      {children}
+    </View>
+  );
+}
+
+RepliqoMask.displayName = 'RepliqoMask';

package/src/index.ts

@@ -45,6 +45,8 @@ export type { ScreenshotResult } from './snapshot/captureScreenshot';
 // Components
 export { RepliqoScrollView } from './components/RepliqoScrollView';
 export { RepliqoFlatList } from './components/RepliqoFlatList';
+export { RepliqoMask, REPLIQO_MASK_MARKER } from './components/RepliqoMask';
+export type { RepliqoMaskProps } from './components/RepliqoMask';
 
 // Storage (offline persistence contract)
 export type { PersistentStorage } from './core/storage';

package/src/privacy/maskRegistry.ts

@@ -0,0 +1,38 @@
+/**
+ * Tracks how many <RepliqoMask> regions are currently mounted.
+ *
+ * Redaction is implemented in the native capture path (it paints over the
+ * sensitive regions before the JPEG is encoded). The react-native-view-shot
+ * fallback has no such step, so a frame produced by it would contain the
+ * unredacted pixels.
+ *
+ * This registry lets the capture layer FAIL CLOSED: when the host app has
+ * asked for masking but only the unredacted path is available, the frame is
+ * skipped instead of uploaded. Losing a replay frame is always preferable to
+ * leaking the content the developer explicitly marked as sensitive.
+ *
+ * Lives in its own module so both the component and the capture function can
+ * use it without importing the SDK client (which would be circular).
+ */
+
+let activeMasks = 0;
+
+/** Called by RepliqoMask on mount (when enabled). */
+export function registerMask(): void {
+  activeMasks++;
+}
+
+/** Called by RepliqoMask on unmount (or when disabled). */
+export function unregisterMask(): void {
+  activeMasks = Math.max(0, activeMasks - 1);
+}
+
+/** True when at least one mask region is currently mounted. */
+export function hasActiveMasks(): boolean {
+  return activeMasks > 0;
+}
+
+/** Test-only: reset the counter between cases. */
+export function __resetMaskRegistryForTests(): void {
+  activeMasks = 0;
+}

package/src/snapshot/captureScreenshot.ts

@@ -3,6 +3,7 @@ import {
   isNativeScreenCaptureAvailable,
   captureNativeFrame,
 } from './NativeScreenCapture';
+import { hasActiveMasks } from '../privacy/maskRegistry';
 
 export type CaptureSource = 'native' | 'viewshot';
 
@@ -48,9 +49,11 @@ function resolveViewShot(): ((opts: any) => Promise<string>) | null {
  *
  *  1. Native multi-window capture (Android) — uses View.draw() on all
  *     app windows via WindowManagerGlobal reflection. Captures modals,
- *     alerts, dialogs, overlays. No permissions needed.
+ *     alerts, dialogs, overlays. No permissions needed. This is the ONLY
+ *     path that applies <RepliqoMask> / password redaction.
  *  2. react-native-view-shot fallback — captures the main RN view only
- *     (no modals or native dialogs)
+ *     (no modals or native dialogs), WITHOUT redaction. Skipped entirely
+ *     when masks are mounted (fail closed).
  *  3. null — if both are unavailable
  *
  * Never throws. Returns null on any failure.
@@ -64,7 +67,12 @@ export async function captureScreenshot(): Promise<ScreenshotResult | null> {
     // to view-shot for this single frame rather than showing nothing.
   }
 
-  // Strategy 2: react-native-view-shot fallback
+  // Strategy 2: react-native-view-shot fallback.
+  // FAIL CLOSED: this path cannot redact, so if the host app has mounted
+  // <RepliqoMask> regions we skip the frame rather than upload the
+  // sensitive pixels it explicitly asked to hide.
+  if (hasActiveMasks()) return null;
+
   const captureScreen = resolveViewShot();
   if (!captureScreen) return null;