@repliqo/sdk-react-native 0.2.2 → 0.3.0

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

@@ -132,4 +132,31 @@ public class ScreenCaptureModule extends ReactContextBaseJavaModule {
             }
         });
     }
+
+    /**
+     * Perform a fast programmatic scroll-scan of the main ScrollView.
+     * Captures the entire content as viewport tiles in ~300-500ms.
+     * Invisible to the user (scroll is restored to original position).
+     *
+     * Returns: Array<{ image, width, height, scrollOffsetY, viewportHeight,
+     *                   contentHeight, format }>
+     */
+    @ReactMethod
+    public void scanFullContent(Promise promise) {
+        Activity activity = getCurrentActivity();
+        if (activity == null) {
+            promise.resolve(null);
+            return;
+        }
+
+        mainHandler.post(() -> {
+            try {
+                WritableArray tiles = ScrollScanCapture.scan(activity);
+                promise.resolve(tiles);
+            } catch (Exception e) {
+                Log.w(TAG, "scanFullContent failed: " + e.getMessage());
+                promise.resolve(null);
+            }
+        });
+    }
 }

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

@@ -0,0 +1,248 @@
+package com.repliqo.screencapture;
+
+import android.app.Activity;
+import android.graphics.Bitmap;
+import android.graphics.Canvas;
+import android.util.Base64;
+import android.util.Log;
+import android.view.View;
+import android.view.ViewGroup;
+import android.widget.ScrollView;
+
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.WritableMap;
+
+import java.io.ByteArrayOutputStream;
+import java.lang.reflect.Field;
+import java.util.ArrayList;
+
+/**
+ * Performs a fast programmatic scroll-scan of the main ScrollView to
+ * capture the ENTIRE content as a series of viewport tiles.
+ *
+ * The scan is invisible to the user:
+ *   1. Save current scroll position
+ *   2. scrollTo(0, 0) — instant, no animation
+ *   3. Capture viewport at Y=0
+ *   4. scrollTo(0, viewportHeight) — instant
+ *   5. Capture viewport at Y=viewportHeight
+ *   6. ... repeat until end of content
+ *   7. scrollTo(0, originalY) — restore position
+ *
+ * Total time: ~300-500ms for a typical screen. The user sees a brief
+ * flicker at most (usually nothing because it happens within one frame).
+ *
+ * Must run on the UI thread.
+ */
+public class ScrollScanCapture {
+    private static final String TAG = "RepliqoCapture";
+    private static final int TARGET_WIDTH = 390;
+    private static final int JPEG_QUALITY = 40;
+
+    /**
+     * Scan the ScrollView and return all viewport tiles.
+     *
+     * @return WritableArray of tile objects, or null on failure
+     */
+    public static WritableArray scan(Activity activity) {
+        if (activity == null || activity.isFinishing()) return null;
+
+        try {
+            View scrollView = findVerticalScrollView(activity);
+            if (scrollView == null) {
+                Log.d(TAG, "No ScrollView found for scan");
+                return null;
+            }
+
+            View contentView = getContentChild(scrollView);
+            if (contentView == null) return null;
+
+            int viewportWidth = scrollView.getWidth();
+            int viewportHeight = scrollView.getHeight();
+            int contentHeight = contentView.getHeight();
+
+            if (viewportWidth <= 0 || viewportHeight <= 0 || contentHeight <= 0) {
+                return null;
+            }
+
+            // If content fits in viewport, just capture once
+            if (contentHeight <= viewportHeight) {
+                WritableArray tiles = Arguments.createArray();
+                WritableMap tile = captureSingleTile(
+                    scrollView, 0, viewportWidth, viewportHeight, contentHeight
+                );
+                if (tile != null) tiles.pushMap(tile);
+                return tiles;
+            }
+
+            // Save original scroll position
+            int originalScrollY = scrollView.getScrollY();
+
+            WritableArray tiles = Arguments.createArray();
+
+            // Scan from top to bottom in viewport-sized steps
+            // Use 80% overlap to avoid gaps from scroll imprecision
+            int step = (int) (viewportHeight * 0.8);
+            int y = 0;
+
+            while (y < contentHeight) {
+                // Scroll to position — instant, no animation
+                scrollView.scrollTo(0, y);
+
+                // Force a layout pass so the views at this position render
+                scrollView.invalidate();
+                contentView.invalidate();
+
+                // Capture the viewport at this position
+                WritableMap tile = captureSingleTile(
+                    scrollView, y, viewportWidth, viewportHeight, contentHeight
+                );
+                if (tile != null) {
+                    tiles.pushMap(tile);
+                }
+
+                y += step;
+
+                // Last step: capture the very bottom
+                if (y >= contentHeight && y - step < contentHeight - viewportHeight) {
+                    y = contentHeight - viewportHeight;
+                    scrollView.scrollTo(0, y);
+                    scrollView.invalidate();
+                    contentView.invalidate();
+
+                    WritableMap lastTile = captureSingleTile(
+                        scrollView, y, viewportWidth, viewportHeight, contentHeight
+                    );
+                    if (lastTile != null) {
+                        tiles.pushMap(lastTile);
+                    }
+                    break;
+                }
+            }
+
+            // Restore original scroll position — instant
+            scrollView.scrollTo(0, originalScrollY);
+
+            Log.d(TAG, "Scroll scan complete: " + tiles.size() +
+                    " tiles, content=" + contentHeight + "px");
+
+            return tiles;
+
+        } catch (Exception e) {
+            Log.w(TAG, "ScrollScanCapture failed: " + e.getMessage());
+            return null;
+        }
+    }
+
+    private static WritableMap captureSingleTile(
+            View scrollView, int scrollY,
+            int viewportWidth, int viewportHeight, int contentHeight) {
+        try {
+            // Scale to target width
+            float scale = (float) TARGET_WIDTH / viewportWidth;
+            int outWidth = TARGET_WIDTH;
+            int outHeight = Math.round(viewportHeight * scale);
+
+            if (outWidth <= 0 || outHeight <= 0) return null;
+
+            Bitmap bitmap = Bitmap.createBitmap(outWidth, outHeight,
+                    Bitmap.Config.ARGB_8888);
+            Canvas canvas = new Canvas(bitmap);
+            canvas.scale(scale, scale);
+
+            // Translate canvas to account for scroll position within the view
+            canvas.translate(0, -scrollView.getScrollY());
+
+            // Draw the scrollview's content
+            View content = getContentChild(scrollView);
+            if (content != null) {
+                content.draw(canvas);
+            } else {
+                scrollView.draw(canvas);
+            }
+
+            // Compress to JPEG
+            ByteArrayOutputStream baos = new ByteArrayOutputStream();
+            bitmap.compress(Bitmap.CompressFormat.JPEG, JPEG_QUALITY, baos);
+            String base64 = Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP);
+            bitmap.recycle();
+
+            WritableMap tile = Arguments.createMap();
+            tile.putString("image", base64);
+            tile.putInt("width", outWidth);
+            tile.putInt("height", outHeight);
+            tile.putInt("scrollOffsetY", scrollY);
+            tile.putInt("viewportHeight", viewportHeight);
+            tile.putInt("contentHeight", contentHeight);
+            tile.putString("format", "jpeg");
+            return tile;
+
+        } catch (Exception e) {
+            Log.w(TAG, "Tile capture at Y=" + scrollY + " failed: " + e.getMessage());
+            return null;
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private static View findVerticalScrollView(Activity activity) {
+        View decorView = activity.getWindow().getDecorView();
+        View found = findInTree(decorView);
+        if (found != null) return found;
+
+        try {
+            Class<?> wmgClass = Class.forName("android.view.WindowManagerGlobal");
+            Object wmg = wmgClass.getMethod("getInstance").invoke(null);
+            Field viewsField = wmgClass.getDeclaredField("mViews");
+            viewsField.setAccessible(true);
+            ArrayList<View> views = (ArrayList<View>) viewsField.get(wmg);
+            if (views != null) {
+                for (View root : views) {
+                    if (root == decorView) continue;
+                    found = findInTree(root);
+                    if (found != null) return found;
+                }
+            }
+        } catch (Exception e) { }
+
+        return null;
+    }
+
+    private static View findInTree(View view) {
+        if (view == null) return null;
+        if (isVerticalScroll(view) && view instanceof ViewGroup
+                && ((ViewGroup) view).getChildCount() > 0) {
+            return view;
+        }
+        if (view instanceof ViewGroup) {
+            ViewGroup group = (ViewGroup) view;
+            for (int i = 0; i < group.getChildCount(); i++) {
+                View found = findInTree(group.getChildAt(i));
+                if (found != null) return found;
+            }
+        }
+        return null;
+    }
+
+    private static boolean isVerticalScroll(View view) {
+        if (view instanceof ScrollView) return true;
+        Class<?> clazz = view.getClass();
+        while (clazz != null && clazz != View.class) {
+            String name = clazz.getName();
+            if (name.contains("Horizontal")) return false;
+            if (name.contains("NestedScrollView") ||
+                name.contains("ReactScrollView") ||
+                name.endsWith("ScrollView")) return true;
+            clazz = clazz.getSuperclass();
+        }
+        return false;
+    }
+
+    private static View getContentChild(View scrollView) {
+        if (scrollView instanceof ViewGroup) {
+            ViewGroup group = (ViewGroup) scrollView;
+            if (group.getChildCount() > 0) return group.getChildAt(0);
+        }
+        return null;
+    }
+}

package/dist/components/RepliqoScrollView.d.ts

@@ -1,26 +1,11 @@
 import React from 'react';
 import { ScrollView, type ScrollViewProps } from 'react-native';
 /**
- * Drop-in replacement for React Native's ScrollView that automatically
- * reports the scroll offset to Repliqo for accurate heatmaps.
+ * Drop-in replacement for React Native's ScrollView that:
  *
- * Without this, touch coordinates on scrollable screens are relative to
- * the visible viewport. With this, they're relative to the full content,
- * so heatmaps accurately show which content elements users touch.
- *
- * Usage — just replace `<ScrollView>` with `<RepliqoScrollView>`:
- *
- * ```tsx
- * import { RepliqoScrollView } from '@repliqo/sdk-react-native';
- *
- * // Before:
- * <ScrollView>...</ScrollView>
- *
- * // After:
- * <RepliqoScrollView>...</RepliqoScrollView>
- * ```
- *
- * All ScrollView props are forwarded. Your existing `onScroll` handler
- * still fires normally.
+ *  1. Reports scroll offset for accurate heatmap touch coords
+ *  2. Captures viewport tiles on scroll stops for collaborative
+ *     screen building — the backend composites these into a
+ *     full-content image over time from multiple user sessions
  */
 export declare const RepliqoScrollView: React.ForwardRefExoticComponent<ScrollViewProps & React.RefAttributes<ScrollView>>;

package/dist/components/RepliqoScrollView.js

@@ -37,42 +37,99 @@ exports.RepliqoScrollView = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
 const client_1 = require("../core/client");
+/** Minimum scroll delta (px) to trigger a new tile capture. */
+const MIN_DELTA_PX = 50;
+/** Debounce: wait this long after scroll stops before capturing. */
+const DEBOUNCE_MS = 500;
+/** Throttle: minimum time between tile captures. */
+const THROTTLE_MS = 3000;
 /**
- * Drop-in replacement for React Native's ScrollView that automatically
- * reports the scroll offset to Repliqo for accurate heatmaps.
+ * Drop-in replacement for React Native's ScrollView that:
  *
- * Without this, touch coordinates on scrollable screens are relative to
- * the visible viewport. With this, they're relative to the full content,
- * so heatmaps accurately show which content elements users touch.
- *
- * Usage — just replace `<ScrollView>` with `<RepliqoScrollView>`:
- *
- * ```tsx
- * import { RepliqoScrollView } from '@repliqo/sdk-react-native';
- *
- * // Before:
- * <ScrollView>...</ScrollView>
- *
- * // After:
- * <RepliqoScrollView>...</RepliqoScrollView>
- * ```
- *
- * All ScrollView props are forwarded. Your existing `onScroll` handler
- * still fires normally.
+ *  1. Reports scroll offset for accurate heatmap touch coords
+ *  2. Captures viewport tiles on scroll stops for collaborative
+ *     screen building — the backend composites these into a
+ *     full-content image over time from multiple user sessions
  */
-exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, ...props }, ref) => {
+exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumScrollEnd, onLayout, ...props }, ref) => {
+    const debounceTimer = (0, react_1.useRef)(null);
+    const lastCaptureTime = (0, react_1.useRef)(0);
+    const lastCaptureY = (0, react_1.useRef)(-999);
+    const initialCaptured = (0, react_1.useRef)(false);
+    const scrollState = (0, react_1.useRef)(null);
+    // Cleanup debounce timer on unmount
+    (0, react_1.useEffect)(() => {
+        return () => {
+            if (debounceTimer.current)
+                clearTimeout(debounceTimer.current);
+        };
+    }, []);
+    /**
+     * Core tile capture logic. Reads from refs (stable across renders).
+     * Checks throttle + delta before capturing.
+     */
+    const doCapture = () => {
+        const state = scrollState.current;
+        if (!state || state.viewportHeight <= 0)
+            return;
+        const now = Date.now();
+        if (now - lastCaptureTime.current < THROTTLE_MS)
+            return;
+        if (Math.abs(state.offsetY - lastCaptureY.current) < MIN_DELTA_PX &&
+            initialCaptured.current)
+            return;
+        lastCaptureTime.current = now;
+        lastCaptureY.current = state.offsetY;
+        initialCaptured.current = true;
+        try {
+            client_1.AppAnalytics.getInstance().captureScrollTile(state.offsetY, state.viewportHeight, state.contentHeight);
+        }
+        catch { }
+    };
     const handleScroll = (0, react_1.useCallback)((event) => {
-        // Report scroll offset to the SDK
+        const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
+        // Report scroll offset for touch coords
         try {
-            const offsetY = event.nativeEvent.contentOffset.y;
-            client_1.AppAnalytics.getInstance().setScrollOffset(offsetY);
+            client_1.AppAnalytics.getInstance().setScrollOffset(contentOffset.y);
         }
-        catch {
-            // SDK not initialized, ignore
+        catch { }
+        // Update scroll state
+        scrollState.current = {
+            offsetY: contentOffset.y,
+            viewportHeight: layoutMeasurement.height,
+            contentHeight: contentSize.height,
+        };
+        // Debounce: capture after scroll stops
+        if (debounceTimer.current)
+            clearTimeout(debounceTimer.current);
+        debounceTimer.current = setTimeout(doCapture, DEBOUNCE_MS);
+        // Capture initial tile (Y≈0) on first scroll event with real dimensions
+        if (!initialCaptured.current && contentOffset.y < 10) {
+            setTimeout(doCapture, 200);
         }
-        // Forward to the original onScroll handler
         onScroll?.(event);
     }, [onScroll]);
-    return (<react_native_1.ScrollView ref={ref} {...props} onScroll={handleScroll} scrollEventThrottle={props.scrollEventThrottle ?? 16}/>);
+    const handleMomentumEnd = (0, react_1.useCallback)((event) => {
+        if (debounceTimer.current) {
+            clearTimeout(debounceTimer.current);
+            debounceTimer.current = null;
+        }
+        setTimeout(doCapture, 200);
+        onMomentumScrollEnd?.(event);
+    }, [onMomentumScrollEnd]);
+    const handleLayout = (0, react_1.useCallback)((event) => {
+        // Capture initial tile after layout (gets real viewportHeight)
+        const { height } = event.nativeEvent.layout;
+        if (!initialCaptured.current && height > 0) {
+            scrollState.current = {
+                offsetY: 0,
+                viewportHeight: height,
+                contentHeight: height, // Will be updated on first scroll
+            };
+            setTimeout(doCapture, 1000);
+        }
+        onLayout?.(event);
+    }, [onLayout]);
+    return (<react_native_1.ScrollView ref={ref} {...props} onScroll={handleScroll} onMomentumScrollEnd={handleMomentumEnd} onLayout={handleLayout} scrollEventThrottle={props.scrollEventThrottle ?? 16}/>);
 });
 exports.RepliqoScrollView.displayName = 'RepliqoScrollView';

package/dist/core/client.d.ts

@@ -7,7 +7,6 @@ export declare class AppAnalytics {
     private screenVisitQueue;
     private snapshotQueue;
     private snapshotCapture;
-    private screenCaptureManager;
     private errorTracker;
     private sessionId;
     private currentScreen;
@@ -32,6 +31,20 @@ export declare class AppAnalytics {
      * on scrollable screens.
      */
     setScrollOffset(y: number): void;
+    /**
+     * Capture the current viewport as a tile for collaborative screen
+     * building. Called by RepliqoScrollView on scroll stops.
+     *
+     * The tile includes the scrollOffsetY so the backend knows where
+     * in the full content this viewport belongs. Multiple users/sessions
+     * contribute tiles until the full content is covered.
+     */
+    captureScrollTile(scrollOffsetY: number, viewportHeight: number, contentHeight: number): void;
+    /**
+     * Programmatically scroll-scan the current ScrollView and upload all
+     * tiles to the backend. Invisible to the user (~300-500ms).
+     */
+    private autoScanScreen;
     onScreenEnter(screenName: string): void;
     onScreenExit(screenName: string): void;
     flush(): Promise<void>;

package/dist/core/client.js

@@ -3,18 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppAnalytics = void 0;
 const react_native_1 = require("react-native");
 const capture_1 = require("../snapshot/capture");
-const ScreenCaptureManager_1 = require("../snapshot/ScreenCaptureManager");
 const config_1 = require("./config");
 const logger_1 = require("./logger");
 const api_client_1 = require("../transport/api.client");
 const batch_queue_1 = require("../transport/batch-queue");
 const error_tracker_1 = require("../trackers/error.tracker");
-// Native multi-window capture is used automatically via captureScreenshot()
-// when the ScreenCaptureModule is linked. No permission or service needed.
+const NativeScreenCapture_1 = require("../snapshot/NativeScreenCapture");
 class AppAnalytics {
     constructor(config) {
         this.snapshotCapture = null;
-        this.screenCaptureManager = null;
         this.errorTracker = null;
         this.sessionId = null;
         this.currentScreen = null;
@@ -52,12 +49,6 @@ class AppAnalytics {
             }, undefined, // default captureScreenshot provider
             (...args) => this.logger.log(...args), (...args) => this.logger.warn(...args));
         }
-        // Screen capture manager for heatmap backgrounds.
-        // Captures full ScrollView content on screen enter (24h cache).
-        // Independent of session replay snapshots.
-        if (this.config.enableHeatmapCapture) {
-            this.screenCaptureManager = new ScreenCaptureManager_1.ScreenCaptureManager((screenName, image, width, height, isFullContent) => this.apiClient.uploadScreenCapture(screenName, image, width, height, isFullContent), this.config.debug);
-        }
         if (this.config.enableCrashTracking) {
             this.errorTracker = new error_tracker_1.ErrorTracker((crash) => {
                 // Crash reports are sent immediately (fire-and-forget), not batched
@@ -102,8 +93,6 @@ class AppAnalytics {
                 instance.snapshotCapture.stop();
                 instance.snapshotCapture = null;
             }
-            instance.screenCaptureManager?.reset();
-            instance.screenCaptureManager = null;
             instance.eventQueue.stopAutoFlush();
             instance.screenVisitQueue.stopAutoFlush();
             instance.snapshotQueue.stopAutoFlush();
@@ -234,14 +223,76 @@ class AppAnalytics {
     setScrollOffset(y) {
         this.scrollOffsetY = y;
     }
+    /**
+     * Capture the current viewport as a tile for collaborative screen
+     * building. Called by RepliqoScrollView on scroll stops.
+     *
+     * The tile includes the scrollOffsetY so the backend knows where
+     * in the full content this viewport belongs. Multiple users/sessions
+     * contribute tiles until the full content is covered.
+     */
+    captureScrollTile(scrollOffsetY, viewportHeight, contentHeight) {
+        if (!this.sessionId || !this.currentScreen)
+            return;
+        if (viewportHeight <= 0)
+            return; // No real dimensions yet
+        const screenName = this.currentScreen;
+        const sessionId = this.sessionId;
+        // Fire-and-forget: capture + upload in background
+        (async () => {
+            try {
+                const frame = await (0, NativeScreenCapture_1.captureNativeFrame)();
+                if (!frame)
+                    return;
+                this.logger.log(`Scroll tile: "${screenName}" Y=${Math.round(scrollOffsetY)} ` +
+                    `vp=${Math.round(viewportHeight)} content=${Math.round(contentHeight)} ` +
+                    `${Math.round(frame.image.length / 1024)}KB`);
+                await this.apiClient.uploadScreenTile(sessionId, screenName, frame.image, frame.width, frame.height, scrollOffsetY, viewportHeight, contentHeight);
+            }
+            catch (err) {
+                this.logger.warn('Scroll tile failed:', err);
+            }
+        })();
+    }
+    /**
+     * Programmatically scroll-scan the current ScrollView and upload all
+     * tiles to the backend. Invisible to the user (~300-500ms).
+     */
+    autoScanScreen(screenName) {
+        (async () => {
+            try {
+                const tiles = await (0, NativeScreenCapture_1.scanFullContent)();
+                if (!tiles || tiles.length === 0) {
+                    this.logger.log(`Auto-scan: no ScrollView found for "${screenName}"`);
+                    return;
+                }
+                this.logger.log(`Auto-scan: "${screenName}" captured ${tiles.length} tiles ` +
+                    `(content=${tiles[0].contentHeight}px)`);
+                // Upload all tiles in parallel
+                const sessionId = this.sessionId;
+                await Promise.all(tiles.map((tile) => this.apiClient.uploadScreenTile(sessionId, screenName, tile.image, tile.width, tile.height, tile.scrollOffsetY, tile.viewportHeight, tile.contentHeight).catch(() => { })));
+                this.logger.log(`Auto-scan: "${screenName}" tiles uploaded`);
+            }
+            catch (err) {
+                this.logger.warn('Auto-scan failed:', err);
+            }
+        })();
+    }
     onScreenEnter(screenName) {
         this.currentScreen = screenName;
         this.currentScreenEnteredAt = new Date().toISOString();
         this.scrollOffsetY = 0;
         this.errorTracker?.setCurrentScreen(screenName);
         this.snapshotCapture?.setCurrentScreen(screenName);
-        // Trigger full-content capture for heatmap backgrounds (async, non-blocking)
-        this.screenCaptureManager?.onScreenEnter(screenName);
+        // Auto-scan: programmatically scroll the ScrollView and capture
+        // all viewport tiles in ~300ms. Fire-and-forget, invisible to user.
+        if (this.config.enableHeatmapCapture) {
+            setTimeout(() => {
+                if (this.currentScreen !== screenName || !this.sessionId)
+                    return;
+                this.autoScanScreen(screenName);
+            }, 1500); // Wait for screen to fully render
+        }
         this.logger.log('Screen entered:', screenName);
     }
     onScreenExit(screenName) {

package/dist/snapshot/NativeScreenCapture.d.ts

@@ -41,3 +41,21 @@ export interface FullContentResult extends NativeFrameResult {
  * @returns FullContentResult with isFullContent flag, or null
  */
 export declare function captureFullContent(): Promise<FullContentResult | null>;
+export interface ScanTile {
+    image: string;
+    width: number;
+    height: number;
+    scrollOffsetY: number;
+    viewportHeight: number;
+    contentHeight: number;
+}
+/**
+ * Perform a fast programmatic scroll-scan of the main ScrollView.
+ * Captures the entire content as viewport tiles in ~300-500ms.
+ *
+ * The scan is invisible to the user — scroll position is saved and
+ * restored. Returns an array of tiles covering the full content.
+ *
+ * @returns Array of tiles, or null if no ScrollView or not available
+ */
+export declare function scanFullContent(): Promise<ScanTile[] | null>;

package/dist/snapshot/NativeScreenCapture.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isNativeScreenCaptureAvailable = isNativeScreenCaptureAvailable;
 exports.captureNativeFrame = captureNativeFrame;
 exports.captureFullContent = captureFullContent;
+exports.scanFullContent = scanFullContent;
 const react_native_1 = require("react-native");
 const NativeModule = react_native_1.Platform.OS === 'android'
     ? react_native_1.NativeModules.ScreenCaptureModule ?? null
@@ -68,3 +69,34 @@ async function captureFullContent() {
         return null;
     }
 }
+/**
+ * Perform a fast programmatic scroll-scan of the main ScrollView.
+ * Captures the entire content as viewport tiles in ~300-500ms.
+ *
+ * The scan is invisible to the user — scroll position is saved and
+ * restored. Returns an array of tiles covering the full content.
+ *
+ * @returns Array of tiles, or null if no ScrollView or not available
+ */
+async function scanFullContent() {
+    if (!NativeModule)
+        return null;
+    try {
+        const tiles = await NativeModule.scanFullContent();
+        if (!tiles || !Array.isArray(tiles) || tiles.length === 0)
+            return null;
+        return tiles
+            .filter((t) => t && t.image)
+            .map((t) => ({
+            image: t.image,
+            width: t.width,
+            height: t.height,
+            scrollOffsetY: t.scrollOffsetY,
+            viewportHeight: t.viewportHeight,
+            contentHeight: t.contentHeight,
+        }));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/transport/api.client.d.ts

@@ -30,5 +30,9 @@ export declare class ApiClient {
      * Upload a full-content screen capture for heatmap backgrounds.
      * Fire-and-forget: errors are logged but never thrown.
      */
+    /**
+     * Upload a scroll tile for collaborative screen building.
+     */
+    uploadScreenTile(sessionId: string, screenName: string, image: string, width: number, height: number, scrollOffsetY: number, viewportHeight: number, contentHeight: number): Promise<void>;
     uploadScreenCapture(screenName: string, image: string, width: number, height: number, isFullContent: boolean): Promise<void>;
 }

package/dist/transport/api.client.js

@@ -156,6 +156,34 @@ class ApiClient {
      * Upload a full-content screen capture for heatmap backgrounds.
      * Fire-and-forget: errors are logged but never thrown.
      */
+    /**
+     * Upload a scroll tile for collaborative screen building.
+     */
+    async uploadScreenTile(sessionId, screenName, image, width, height, scrollOffsetY, viewportHeight, contentHeight) {
+        try {
+            const response = await fetch(`${this.baseUrl}/api/screen-tiles`, {
+                method: 'POST',
+                headers: this.getHeaders(),
+                body: JSON.stringify({
+                    sessionId,
+                    screenName,
+                    image,
+                    width,
+                    height,
+                    scrollOffsetY: Math.round(scrollOffsetY),
+                    viewportHeight: Math.round(viewportHeight),
+                    contentHeight: Math.round(contentHeight),
+                }),
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                this.logger.warn('Screen tile upload failed:', response.status, text?.substring(0, 200));
+            }
+        }
+        catch (error) {
+            this.logger.warn('Error uploading screen tile:', error);
+        }
+    }
     async uploadScreenCapture(screenName, image, width, height, isFullContent) {
         try {
             const response = await fetch(`${this.baseUrl}/api/screen-captures`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repliqo/sdk-react-native",
-  "version": "0.2.2",
+  "version": "0.3.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/RepliqoScrollView.tsx

@@ -1,58 +1,140 @@
-import React, { useCallback } from 'react';
+import React, { useCallback, useRef, useEffect } from 'react';
 import {
   ScrollView,
   type ScrollViewProps,
   type NativeSyntheticEvent,
   type NativeScrollEvent,
+  type LayoutChangeEvent,
 } from 'react-native';
 import { AppAnalytics } from '../core/client';
 
+/** Minimum scroll delta (px) to trigger a new tile capture. */
+const MIN_DELTA_PX = 50;
+/** Debounce: wait this long after scroll stops before capturing. */
+const DEBOUNCE_MS = 500;
+/** Throttle: minimum time between tile captures. */
+const THROTTLE_MS = 3000;
+
 /**
- * Drop-in replacement for React Native's ScrollView that automatically
- * reports the scroll offset to Repliqo for accurate heatmaps.
- *
- * Without this, touch coordinates on scrollable screens are relative to
- * the visible viewport. With this, they're relative to the full content,
- * so heatmaps accurately show which content elements users touch.
- *
- * Usage — just replace `<ScrollView>` with `<RepliqoScrollView>`:
- *
- * ```tsx
- * import { RepliqoScrollView } from '@repliqo/sdk-react-native';
+ * Drop-in replacement for React Native's ScrollView that:
  *
- * // Before:
- * <ScrollView>...</ScrollView>
- *
- * // After:
- * <RepliqoScrollView>...</RepliqoScrollView>
- * ```
- *
- * All ScrollView props are forwarded. Your existing `onScroll` handler
- * still fires normally.
+ *  1. Reports scroll offset for accurate heatmap touch coords
+ *  2. Captures viewport tiles on scroll stops for collaborative
+ *     screen building — the backend composites these into a
+ *     full-content image over time from multiple user sessions
  */
 export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
-  ({ onScroll, ...props }, ref) => {
+  ({ onScroll, onMomentumScrollEnd, onLayout, ...props }, ref) => {
+    const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const lastCaptureTime = useRef(0);
+    const lastCaptureY = useRef(-999);
+    const initialCaptured = useRef(false);
+    const scrollState = useRef<{
+      offsetY: number;
+      viewportHeight: number;
+      contentHeight: number;
+    } | null>(null);
+
+    // Cleanup debounce timer on unmount
+    useEffect(() => {
+      return () => {
+        if (debounceTimer.current) clearTimeout(debounceTimer.current);
+      };
+    }, []);
+
+    /**
+     * Core tile capture logic. Reads from refs (stable across renders).
+     * Checks throttle + delta before capturing.
+     */
+    const doCapture = () => {
+      const state = scrollState.current;
+      if (!state || state.viewportHeight <= 0) return;
+
+      const now = Date.now();
+      if (now - lastCaptureTime.current < THROTTLE_MS) return;
+      if (Math.abs(state.offsetY - lastCaptureY.current) < MIN_DELTA_PX &&
+          initialCaptured.current) return;
+
+      lastCaptureTime.current = now;
+      lastCaptureY.current = state.offsetY;
+      initialCaptured.current = true;
+
+      try {
+        AppAnalytics.getInstance().captureScrollTile(
+          state.offsetY,
+          state.viewportHeight,
+          state.contentHeight,
+        );
+      } catch {}
+    };
+
     const handleScroll = useCallback(
       (event: NativeSyntheticEvent<NativeScrollEvent>) => {
-        // Report scroll offset to the SDK
+        const { contentOffset, layoutMeasurement, contentSize } =
+          event.nativeEvent;
+
+        // Report scroll offset for touch coords
         try {
-          const offsetY = event.nativeEvent.contentOffset.y;
-          AppAnalytics.getInstance().setScrollOffset(offsetY);
-        } catch {
-          // SDK not initialized, ignore
+          AppAnalytics.getInstance().setScrollOffset(contentOffset.y);
+        } catch {}
+
+        // Update scroll state
+        scrollState.current = {
+          offsetY: contentOffset.y,
+          viewportHeight: layoutMeasurement.height,
+          contentHeight: contentSize.height,
+        };
+
+        // Debounce: capture after scroll stops
+        if (debounceTimer.current) clearTimeout(debounceTimer.current);
+        debounceTimer.current = setTimeout(doCapture, DEBOUNCE_MS);
+
+        // Capture initial tile (Y≈0) on first scroll event with real dimensions
+        if (!initialCaptured.current && contentOffset.y < 10) {
+          setTimeout(doCapture, 200);
         }
 
-        // Forward to the original onScroll handler
         onScroll?.(event);
       },
       [onScroll],
     );
 
+    const handleMomentumEnd = useCallback(
+      (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+        if (debounceTimer.current) {
+          clearTimeout(debounceTimer.current);
+          debounceTimer.current = null;
+        }
+        setTimeout(doCapture, 200);
+        onMomentumScrollEnd?.(event);
+      },
+      [onMomentumScrollEnd],
+    );
+
+    const handleLayout = useCallback(
+      (event: LayoutChangeEvent) => {
+        // Capture initial tile after layout (gets real viewportHeight)
+        const { height } = event.nativeEvent.layout;
+        if (!initialCaptured.current && height > 0) {
+          scrollState.current = {
+            offsetY: 0,
+            viewportHeight: height,
+            contentHeight: height, // Will be updated on first scroll
+          };
+          setTimeout(doCapture, 1000);
+        }
+        onLayout?.(event);
+      },
+      [onLayout],
+    );
+
     return (
       <ScrollView
         ref={ref}
         {...props}
         onScroll={handleScroll}
+        onMomentumScrollEnd={handleMomentumEnd}
+        onLayout={handleLayout}
         scrollEventThrottle={props.scrollEventThrottle ?? 16}
       />
     );

package/src/core/client.ts

@@ -7,14 +7,12 @@ import {
 } from '../types/events';
 import { SnapshotPayload } from '../types/snapshot';
 import { SnapshotCapture } from '../snapshot/capture';
-import { ScreenCaptureManager } from '../snapshot/ScreenCaptureManager';
 import { ResolvedConfig, resolveConfig, REPLIQO_API_URL } from './config';
 import { Logger } from './logger';
 import { ApiClient } from '../transport/api.client';
 import { BatchQueue } from '../transport/batch-queue';
 import { ErrorTracker } from '../trackers/error.tracker';
-// Native multi-window capture is used automatically via captureScreenshot()
-// when the ScreenCaptureModule is linked. No permission or service needed.
+import { captureNativeFrame, scanFullContent } from '../snapshot/NativeScreenCapture';
 
 export class AppAnalytics {
   private static instance: AppAnalytics | null = null;
@@ -25,7 +23,6 @@ export class AppAnalytics {
   private screenVisitQueue: BatchQueue<ScreenVisit>;
   private snapshotQueue: BatchQueue<SnapshotPayload>;
   private snapshotCapture: SnapshotCapture | null = null;
-  private screenCaptureManager: ScreenCaptureManager | null = null;
   private errorTracker: ErrorTracker | null = null;
   private sessionId: string | null = null;
   private currentScreen: string | null = null;
@@ -96,19 +93,6 @@ export class AppAnalytics {
       );
     }
 
-    // Screen capture manager for heatmap backgrounds.
-    // Captures full ScrollView content on screen enter (24h cache).
-    // Independent of session replay snapshots.
-    if (this.config.enableHeatmapCapture) {
-      this.screenCaptureManager = new ScreenCaptureManager(
-        (screenName, image, width, height, isFullContent) =>
-          this.apiClient.uploadScreenCapture(
-            screenName, image, width, height, isFullContent,
-          ),
-        this.config.debug,
-      );
-    }
-
     if (this.config.enableCrashTracking) {
       this.errorTracker = new ErrorTracker((crash) => {
         // Crash reports are sent immediately (fire-and-forget), not batched
@@ -166,8 +150,6 @@ export class AppAnalytics {
         instance.snapshotCapture = null;
       }
 
-      instance.screenCaptureManager?.reset();
-      instance.screenCaptureManager = null;
 
       instance.eventQueue.stopAutoFlush();
       instance.screenVisitQueue.stopAutoFlush();
@@ -339,14 +321,110 @@ export class AppAnalytics {
     this.scrollOffsetY = y;
   }
 
+  /**
+   * Capture the current viewport as a tile for collaborative screen
+   * building. Called by RepliqoScrollView on scroll stops.
+   *
+   * The tile includes the scrollOffsetY so the backend knows where
+   * in the full content this viewport belongs. Multiple users/sessions
+   * contribute tiles until the full content is covered.
+   */
+  captureScrollTile(
+    scrollOffsetY: number,
+    viewportHeight: number,
+    contentHeight: number,
+  ): void {
+    if (!this.sessionId || !this.currentScreen) return;
+    if (viewportHeight <= 0) return; // No real dimensions yet
+
+    const screenName = this.currentScreen;
+    const sessionId = this.sessionId;
+
+    // Fire-and-forget: capture + upload in background
+    (async () => {
+      try {
+        const frame = await captureNativeFrame();
+        if (!frame) return;
+
+        this.logger.log(
+          `Scroll tile: "${screenName}" Y=${Math.round(scrollOffsetY)} ` +
+            `vp=${Math.round(viewportHeight)} content=${Math.round(contentHeight)} ` +
+            `${Math.round(frame.image.length / 1024)}KB`,
+        );
+
+        await this.apiClient.uploadScreenTile(
+          sessionId,
+          screenName,
+          frame.image,
+          frame.width,
+          frame.height,
+          scrollOffsetY,
+          viewportHeight,
+          contentHeight,
+        );
+      } catch (err) {
+        this.logger.warn('Scroll tile failed:', err);
+      }
+    })();
+  }
+
+  /**
+   * Programmatically scroll-scan the current ScrollView and upload all
+   * tiles to the backend. Invisible to the user (~300-500ms).
+   */
+  private autoScanScreen(screenName: string): void {
+    (async () => {
+      try {
+        const tiles = await scanFullContent();
+        if (!tiles || tiles.length === 0) {
+          this.logger.log(`Auto-scan: no ScrollView found for "${screenName}"`);
+          return;
+        }
+
+        this.logger.log(
+          `Auto-scan: "${screenName}" captured ${tiles.length} tiles ` +
+            `(content=${tiles[0].contentHeight}px)`,
+        );
+
+        // Upload all tiles in parallel
+        const sessionId = this.sessionId!;
+        await Promise.all(
+          tiles.map((tile) =>
+            this.apiClient.uploadScreenTile(
+              sessionId,
+              screenName,
+              tile.image,
+              tile.width,
+              tile.height,
+              tile.scrollOffsetY,
+              tile.viewportHeight,
+              tile.contentHeight,
+            ).catch(() => {}),
+          ),
+        );
+
+        this.logger.log(`Auto-scan: "${screenName}" tiles uploaded`);
+      } catch (err) {
+        this.logger.warn('Auto-scan failed:', err);
+      }
+    })();
+  }
+
   onScreenEnter(screenName: string): void {
     this.currentScreen = screenName;
     this.currentScreenEnteredAt = new Date().toISOString();
     this.scrollOffsetY = 0;
     this.errorTracker?.setCurrentScreen(screenName);
     this.snapshotCapture?.setCurrentScreen(screenName);
-    // Trigger full-content capture for heatmap backgrounds (async, non-blocking)
-    this.screenCaptureManager?.onScreenEnter(screenName);
+    // Auto-scan: programmatically scroll the ScrollView and capture
+    // all viewport tiles in ~300ms. Fire-and-forget, invisible to user.
+    if (this.config.enableHeatmapCapture) {
+      setTimeout(() => {
+        if (this.currentScreen !== screenName || !this.sessionId) return;
+        this.autoScanScreen(screenName);
+      }, 1500); // Wait for screen to fully render
+    }
+
     this.logger.log('Screen entered:', screenName);
   }
 

package/src/snapshot/NativeScreenCapture.ts

@@ -18,9 +18,20 @@ interface NativeFullContentResult extends NativeCaptureResult {
   isFullContent: boolean;
 }
 
+interface NativeTile {
+  image: string;
+  width: number;
+  height: number;
+  scrollOffsetY: number;
+  viewportHeight: number;
+  contentHeight: number;
+  format: string;
+}
+
 interface NativeScreenCaptureModule {
   captureFrame(): Promise<NativeCaptureResult | null>;
   captureFullContent(): Promise<NativeFullContentResult | null>;
+  scanFullContent(): Promise<NativeTile[] | null>;
   isAvailable(): Promise<boolean>;
 }
 
@@ -104,3 +115,43 @@ export async function captureFullContent(): Promise<FullContentResult | null> {
     return null;
   }
 }
+
+export interface ScanTile {
+  image: string;
+  width: number;
+  height: number;
+  scrollOffsetY: number;
+  viewportHeight: number;
+  contentHeight: number;
+}
+
+/**
+ * Perform a fast programmatic scroll-scan of the main ScrollView.
+ * Captures the entire content as viewport tiles in ~300-500ms.
+ *
+ * The scan is invisible to the user — scroll position is saved and
+ * restored. Returns an array of tiles covering the full content.
+ *
+ * @returns Array of tiles, or null if no ScrollView or not available
+ */
+export async function scanFullContent(): Promise<ScanTile[] | null> {
+  if (!NativeModule) return null;
+
+  try {
+    const tiles = await NativeModule.scanFullContent();
+    if (!tiles || !Array.isArray(tiles) || tiles.length === 0) return null;
+
+    return tiles
+      .filter((t) => t && t.image)
+      .map((t) => ({
+        image: t.image,
+        width: t.width,
+        height: t.height,
+        scrollOffsetY: t.scrollOffsetY,
+        viewportHeight: t.viewportHeight,
+        contentHeight: t.contentHeight,
+      }));
+  } catch {
+    return null;
+  }
+}

package/src/transport/api.client.ts

@@ -227,6 +227,51 @@ export class ApiClient {
    * Upload a full-content screen capture for heatmap backgrounds.
    * Fire-and-forget: errors are logged but never thrown.
    */
+  /**
+   * Upload a scroll tile for collaborative screen building.
+   */
+  async uploadScreenTile(
+    sessionId: string,
+    screenName: string,
+    image: string,
+    width: number,
+    height: number,
+    scrollOffsetY: number,
+    viewportHeight: number,
+    contentHeight: number,
+  ): Promise<void> {
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/api/screen-tiles`,
+        {
+          method: 'POST',
+          headers: this.getHeaders(),
+          body: JSON.stringify({
+            sessionId,
+            screenName,
+            image,
+            width,
+            height,
+            scrollOffsetY: Math.round(scrollOffsetY),
+            viewportHeight: Math.round(viewportHeight),
+            contentHeight: Math.round(contentHeight),
+          }),
+        },
+      );
+
+      if (!response.ok) {
+        const text = await response.text();
+        this.logger.warn(
+          'Screen tile upload failed:',
+          response.status,
+          text?.substring(0, 200),
+        );
+      }
+    } catch (error) {
+      this.logger.warn('Error uploading screen tile:', error);
+    }
+  }
+
   async uploadScreenCapture(
     screenName: string,
     image: string,