@repliqo/sdk-react-native 0.3.3 → 0.3.5

package/dist/components/RepliqoScrollView.d.ts

@@ -4,8 +4,10 @@ import { ScrollView, type ScrollViewProps } from 'react-native';
  * Drop-in replacement for React Native's ScrollView that:
  *
  *  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
+ *  2. Captures viewport tiles on scroll stops AND during continuous
+ *     scroll for collaborative screen building
+ *  3. Registers its window-relative bounds with the SDK so touches can
+ *     be auto-classified as "content" (inside ScrollView) or "fixed"
+ *     (outside, e.g. nav bars/headers)
  */
 export declare const RepliqoScrollView: React.ForwardRefExoticComponent<ScrollViewProps & React.RefAttributes<ScrollView>>;

package/dist/components/RepliqoScrollView.js

@@ -40,41 +40,91 @@ const client_1 = require("../core/client");
 /** Minimum scroll delta (px) to trigger a new tile capture. */
 const MIN_DELTA_PX = 20;
 /** Debounce: wait this long after scroll stops before capturing. */
-const DEBOUNCE_MS = 300;
+const DEBOUNCE_MS = 250;
 /** Throttle: minimum time between tile captures. */
-const THROTTLE_MS = 500;
+const THROTTLE_MS = 400;
+/**
+ * During continuous scroll, force a capture every this many ms.
+ * Ensures tiles are captured even during fast, uninterrupted scrolls
+ * where the user never pauses long enough for the debounce to fire.
+ */
+const SCROLL_INTERVAL_MS = 1200;
+let scrollViewIdCounter = 0;
+const nextScrollViewId = () => `repliqo-scroll-${++scrollViewIdCounter}`;
 /**
  * Drop-in replacement for React Native's ScrollView that:
  *
  *  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
+ *  2. Captures viewport tiles on scroll stops AND during continuous
+ *     scroll for collaborative screen building
+ *  3. Registers its window-relative bounds with the SDK so touches can
+ *     be auto-classified as "content" (inside ScrollView) or "fixed"
+ *     (outside, e.g. nav bars/headers)
  */
-exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumScrollEnd, onScrollEndDrag, onLayout, ...props }, ref) => {
+exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumScrollEnd, onScrollEndDrag, onLayout, onContentSizeChange, ...props }, ref) => {
     const debounceTimer = (0, react_1.useRef)(null);
+    const scrollIntervalTimer = (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 realContentHeight = (0, react_1.useRef)(0);
+    const scrollViewId = (0, react_1.useRef)(nextScrollViewId());
+    const innerRef = (0, react_1.useRef)(null);
     const scrollState = (0, react_1.useRef)(null);
-    // Cleanup debounce timer on unmount
+    // Forward the inner ref to the parent's ref (if provided)
+    const setRef = (0, react_1.useCallback)((node) => {
+        innerRef.current = node;
+        if (typeof ref === 'function') {
+            ref(node);
+        }
+        else if (ref) {
+            ref.current = node;
+        }
+    }, [ref]);
+    /** Measure window-relative bounds and register with SDK. */
+    const measureAndRegister = (0, react_1.useCallback)(() => {
+        const node = innerRef.current;
+        if (!node || typeof node.measureInWindow !== 'function')
+            return;
+        node.measureInWindow((x, y, width, height) => {
+            if (width <= 0 || height <= 0)
+                return;
+            try {
+                client_1.AppAnalytics.getInstance().registerScrollView(scrollViewId.current, {
+                    x, y, width, height,
+                });
+            }
+            catch { }
+        });
+    }, []);
+    // Cleanup timers + unregister on unmount
     (0, react_1.useEffect)(() => {
+        const id = scrollViewId.current;
         return () => {
             if (debounceTimer.current)
                 clearTimeout(debounceTimer.current);
+            if (scrollIntervalTimer.current)
+                clearInterval(scrollIntervalTimer.current);
+            try {
+                client_1.AppAnalytics.getInstance().unregisterScrollView(id);
+            }
+            catch { }
         };
     }, []);
     /**
      * Core tile capture logic. Reads from refs (stable across renders).
      * Checks throttle + delta before capturing.
+     *
+     * @param force Skip throttle check (used for interval captures)
      */
-    const doCapture = () => {
+    const doCapture = (force = false) => {
         const state = scrollState.current;
         if (!state || state.viewportHeight <= 0)
             return;
         const now = Date.now();
-        if (now - lastCaptureTime.current < THROTTLE_MS)
+        if (!force && now - lastCaptureTime.current < THROTTLE_MS)
             return;
+        // Always check delta — no point re-capturing the same position
         if (Math.abs(state.offsetY - lastCaptureY.current) < MIN_DELTA_PX &&
             initialCaptured.current)
             return;
@@ -86,32 +136,55 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
         }
         catch { }
     };
+    /** Start the interval timer for continuous scroll captures. */
+    const startScrollInterval = () => {
+        if (scrollIntervalTimer.current !== null)
+            return;
+        scrollIntervalTimer.current = setInterval(() => {
+            doCapture(true); // force=true skips throttle
+        }, SCROLL_INTERVAL_MS);
+    };
+    /** Stop the interval timer. */
+    const stopScrollInterval = () => {
+        if (scrollIntervalTimer.current !== null) {
+            clearInterval(scrollIntervalTimer.current);
+            scrollIntervalTimer.current = null;
+        }
+    };
     const handleScroll = (0, react_1.useCallback)((event) => {
         const { contentOffset, layoutMeasurement, contentSize } = event.nativeEvent;
-        // Report scroll offset for touch coords
+        // Update SDK with current scroll offset (both legacy + new registry)
         try {
-            client_1.AppAnalytics.getInstance().setScrollOffset(contentOffset.y);
+            const sdk = client_1.AppAnalytics.getInstance();
+            sdk.setScrollOffset(contentOffset.y);
+            sdk.updateScrollViewOffset(scrollViewId.current, contentOffset.y);
         }
         catch { }
-        // Update scroll state
+        // Update scroll state — use realContentHeight if available
+        const bestContentHeight = realContentHeight.current > 0
+            ? realContentHeight.current
+            : contentSize.height;
         scrollState.current = {
             offsetY: contentOffset.y,
             viewportHeight: layoutMeasurement.height,
-            contentHeight: contentSize.height,
+            contentHeight: bestContentHeight,
         };
         // 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
+        debounceTimer.current = setTimeout(() => doCapture(), DEBOUNCE_MS);
+        // Start interval for continuous scroll captures
+        startScrollInterval();
+        // Capture initial tile (Y~0) on first scroll event with real dims
         if (!initialCaptured.current && contentOffset.y < 10) {
-            setTimeout(doCapture, 200);
+            setTimeout(() => doCapture(), 200);
         }
         onScroll?.(event);
     }, [onScroll]);
     const handleScrollEndDrag = (0, react_1.useCallback)((event) => {
         // User lifted finger — capture immediately
-        doCapture();
+        stopScrollInterval();
+        doCapture(true);
         onScrollEndDrag?.(event);
     }, [onScrollEndDrag]);
     const handleMomentumEnd = (0, react_1.useCallback)((event) => {
@@ -119,7 +192,8 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
             clearTimeout(debounceTimer.current);
             debounceTimer.current = null;
         }
-        doCapture();
+        stopScrollInterval();
+        doCapture(true);
         onMomentumScrollEnd?.(event);
     }, [onMomentumScrollEnd]);
     const handleLayout = (0, react_1.useCallback)((event) => {
@@ -129,12 +203,29 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
             scrollState.current = {
                 offsetY: 0,
                 viewportHeight: height,
-                contentHeight: height, // Will be updated on first scroll
+                contentHeight: realContentHeight.current || height,
             };
-            setTimeout(doCapture, 1000);
+            setTimeout(() => doCapture(), 1000);
         }
+        // Register window-relative bounds with the SDK.
+        // Defer measurement to next tick — onLayout fires before the view
+        // is positioned in the window on some Android versions.
+        setTimeout(measureAndRegister, 50);
         onLayout?.(event);
-    }, [onLayout]);
-    return (<react_native_1.ScrollView ref={ref} {...props} onScroll={handleScroll} onScrollEndDrag={handleScrollEndDrag} onMomentumScrollEnd={handleMomentumEnd} onLayout={handleLayout} scrollEventThrottle={props.scrollEventThrottle ?? 16}/>);
+    }, [onLayout, measureAndRegister]);
+    /**
+     * Track the real content height from onContentSizeChange.
+     * This is more reliable than the first scroll event and ensures
+     * the initial tile at Y=0 has correct contentHeight metadata.
+     */
+    const handleContentSizeChange = (0, react_1.useCallback)((w, h) => {
+        realContentHeight.current = h;
+        // Update scroll state if it exists
+        if (scrollState.current) {
+            scrollState.current.contentHeight = h;
+        }
+        onContentSizeChange?.(w, h);
+    }, [onContentSizeChange]);
+    return (<react_native_1.ScrollView ref={setRef} {...props} onScroll={handleScroll} onScrollEndDrag={handleScrollEndDrag} onMomentumScrollEnd={handleMomentumEnd} onLayout={handleLayout} onContentSizeChange={handleContentSizeChange} scrollEventThrottle={props.scrollEventThrottle ?? 16}/>);
 });
 exports.RepliqoScrollView.displayName = 'RepliqoScrollView';

package/dist/core/client.d.ts

@@ -14,6 +14,18 @@ export declare class AppAnalytics {
     private scrollOffsetY;
     private logger;
     private appStateSubscription;
+    /**
+     * Registry of active ScrollViews on the current screen.
+     * Each RepliqoScrollView registers its window-relative bounds and current
+     * scroll state. Used by trackTouch to auto-detect:
+     *   - If touch is INSIDE a ScrollView → adjust Y by that ScrollView's
+     *     scrollOffset, mark as content touch
+     *   - If touch is OUTSIDE all ScrollViews → mark as fixed UI (no adjust)
+     *
+     * This makes heatmaps render fixed elements (nav bars, headers) at their
+     * viewport position, while still mapping scrollable content correctly.
+     */
+    private scrollViewRegistry;
     private constructor();
     static init(config: SDKConfig): AppAnalytics;
     static getInstance(): AppAnalytics;
@@ -29,8 +41,32 @@ export declare class AppAnalytics {
      * or manually from the host app's ScrollView onScroll handler.
      * The offset is added to touch Y coordinates for accurate heatmaps
      * on scrollable screens.
+     *
+     * @deprecated Prefer registerScrollView + updateScrollViewOffset for
+     * auto-detection of fixed vs scrollable touches. Kept for backward compat.
      */
     setScrollOffset(y: number): void;
+    /**
+     * Register a ScrollView's window-relative bounds with the SDK.
+     * Called by RepliqoScrollView on layout. Used to auto-detect whether
+     * a touch is on scrollable content or on fixed UI (nav bars, headers).
+     */
+    registerScrollView(id: string, bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Update the scroll offset for a previously-registered ScrollView.
+     * Called by RepliqoScrollView on every scroll event.
+     */
+    updateScrollViewOffset(id: string, scrollOffsetY: number): void;
+    /**
+     * Remove a ScrollView from the registry. Called by RepliqoScrollView
+     * on unmount.
+     */
+    unregisterScrollView(id: string): void;
     /**
      * Capture the current viewport as a tile for collaborative screen
      * building. Called by RepliqoScrollView on scroll stops.

package/dist/core/client.js

@@ -18,6 +18,18 @@ class AppAnalytics {
         this.currentScreenEnteredAt = null;
         this.scrollOffsetY = 0;
         this.appStateSubscription = null;
+        /**
+         * Registry of active ScrollViews on the current screen.
+         * Each RepliqoScrollView registers its window-relative bounds and current
+         * scroll state. Used by trackTouch to auto-detect:
+         *   - If touch is INSIDE a ScrollView → adjust Y by that ScrollView's
+         *     scrollOffset, mark as content touch
+         *   - If touch is OUTSIDE all ScrollViews → mark as fixed UI (no adjust)
+         *
+         * This makes heatmaps render fixed elements (nav bars, headers) at their
+         * viewport position, while still mapping scrollable content correctly.
+         */
+        this.scrollViewRegistry = new Map();
         this.config = (0, config_1.resolveConfig)(config);
         this.logger = new logger_1.Logger(this.config.debug);
         this.apiClient = new api_client_1.ApiClient(config_1.REPLIQO_API_URL, this.config.apiKey, this.logger);
@@ -163,14 +175,41 @@ class AppAnalytics {
         if (!this.config.enableTouchTracking) {
             return;
         }
-        // Adjust Y by the current scroll offset so touches map to content
-        // position, not just viewport position. This makes heatmaps accurate
-        // for scrollable screens.
-        const adjustedY = y + this.scrollOffsetY;
+        // Auto-detect: find which (if any) registered ScrollView contains
+        // this touch. If inside, adjust Y by that ScrollView's scroll offset.
+        // If outside all ScrollViews, treat as fixed UI (no adjustment).
+        let activeScrollOffset = 0;
+        let isFixed = true;
+        if (this.scrollViewRegistry.size > 0) {
+            for (const info of this.scrollViewRegistry.values()) {
+                const { bounds } = info;
+                if (x >= bounds.x &&
+                    x <= bounds.x + bounds.width &&
+                    y >= bounds.y &&
+                    y <= bounds.y + bounds.height) {
+                    activeScrollOffset = info.scrollOffsetY;
+                    isFixed = false;
+                    break;
+                }
+            }
+        }
+        else {
+            // No ScrollViews registered → fall back to legacy behavior
+            // (use the manually-set scrollOffsetY, treat as content touch).
+            activeScrollOffset = this.scrollOffsetY;
+            isFixed = false;
+        }
+        const adjustedY = y + activeScrollOffset;
         const event = {
             type: 'touch',
             screenName: screenName || this.currentScreen || undefined,
-            data: { x, y: adjustedY, scrollOffsetY: this.scrollOffsetY, ...extra },
+            data: {
+                x,
+                y: adjustedY,
+                scrollOffsetY: activeScrollOffset,
+                isFixed,
+                ...extra,
+            },
             timestamp: new Date().toISOString(),
         };
         this.eventQueue.add(event);
@@ -219,10 +258,42 @@ class AppAnalytics {
      * or manually from the host app's ScrollView onScroll handler.
      * The offset is added to touch Y coordinates for accurate heatmaps
      * on scrollable screens.
+     *
+     * @deprecated Prefer registerScrollView + updateScrollViewOffset for
+     * auto-detection of fixed vs scrollable touches. Kept for backward compat.
      */
     setScrollOffset(y) {
         this.scrollOffsetY = y;
     }
+    /**
+     * Register a ScrollView's window-relative bounds with the SDK.
+     * Called by RepliqoScrollView on layout. Used to auto-detect whether
+     * a touch is on scrollable content or on fixed UI (nav bars, headers).
+     */
+    registerScrollView(id, bounds) {
+        const existing = this.scrollViewRegistry.get(id);
+        this.scrollViewRegistry.set(id, {
+            bounds,
+            scrollOffsetY: existing?.scrollOffsetY ?? 0,
+        });
+    }
+    /**
+     * Update the scroll offset for a previously-registered ScrollView.
+     * Called by RepliqoScrollView on every scroll event.
+     */
+    updateScrollViewOffset(id, scrollOffsetY) {
+        const existing = this.scrollViewRegistry.get(id);
+        if (existing) {
+            existing.scrollOffsetY = scrollOffsetY;
+        }
+    }
+    /**
+     * Remove a ScrollView from the registry. Called by RepliqoScrollView
+     * on unmount.
+     */
+    unregisterScrollView(id) {
+        this.scrollViewRegistry.delete(id);
+    }
     /**
      * Capture the current viewport as a tile for collaborative screen
      * building. Called by RepliqoScrollView on scroll stops.
@@ -282,18 +353,18 @@ class AppAnalytics {
         this.currentScreen = screenName;
         this.currentScreenEnteredAt = new Date().toISOString();
         this.scrollOffsetY = 0;
+        // Clear the ScrollView registry — old screen's scrollviews are gone
+        this.scrollViewRegistry.clear();
         this.errorTracker?.setCurrentScreen(screenName);
         this.snapshotCapture?.setCurrentScreen(screenName);
-        // Auto-scan with PixelCopy: captures entire ScrollView content
-        // by scrolling programmatically + PixelCopy from GPU framebuffer.
-        // Fires 2s after screen enter to let content fully render.
-        if (this.config.enableHeatmapCapture) {
-            setTimeout(() => {
-                if (this.currentScreen !== screenName || !this.sessionId)
-                    return;
-                this.autoScanScreen(screenName);
-            }, 2000);
-        }
+        // NOTE: autoScanScreen (PixelCopy / programmatic scroll) is DISABLED.
+        // React Native does NOT render off-screen content to the GPU or view
+        // tree, so programmatic scroll + View.draw()/PixelCopy produces blank
+        // tiles. Worse, those blank tiles poison the dedup cache and block
+        // real tiles captured during natural user scroll.
+        //
+        // Full-content capture relies entirely on RepliqoScrollView capturing
+        // viewport tiles as the user naturally scrolls through the content.
         this.logger.log('Screen entered:', screenName);
     }
     onScreenExit(screenName) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repliqo/sdk-react-native",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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

@@ -11,47 +11,95 @@ import { AppAnalytics } from '../core/client';
 /** Minimum scroll delta (px) to trigger a new tile capture. */
 const MIN_DELTA_PX = 20;
 /** Debounce: wait this long after scroll stops before capturing. */
-const DEBOUNCE_MS = 300;
+const DEBOUNCE_MS = 250;
 /** Throttle: minimum time between tile captures. */
-const THROTTLE_MS = 500;
+const THROTTLE_MS = 400;
+/**
+ * During continuous scroll, force a capture every this many ms.
+ * Ensures tiles are captured even during fast, uninterrupted scrolls
+ * where the user never pauses long enough for the debounce to fire.
+ */
+const SCROLL_INTERVAL_MS = 1200;
+
+let scrollViewIdCounter = 0;
+const nextScrollViewId = () => `repliqo-scroll-${++scrollViewIdCounter}`;
 
 /**
  * Drop-in replacement for React Native's ScrollView that:
  *
  *  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
+ *  2. Captures viewport tiles on scroll stops AND during continuous
+ *     scroll for collaborative screen building
+ *  3. Registers its window-relative bounds with the SDK so touches can
+ *     be auto-classified as "content" (inside ScrollView) or "fixed"
+ *     (outside, e.g. nav bars/headers)
  */
 export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
-  ({ onScroll, onMomentumScrollEnd, onScrollEndDrag, onLayout, ...props }, ref) => {
+  ({ onScroll, onMomentumScrollEnd, onScrollEndDrag, onLayout, onContentSizeChange, ...props }, ref) => {
     const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const scrollIntervalTimer = useRef<ReturnType<typeof setInterval> | null>(null);
     const lastCaptureTime = useRef(0);
     const lastCaptureY = useRef(-999);
     const initialCaptured = useRef(false);
+    const realContentHeight = useRef(0);
+    const scrollViewId = useRef<string>(nextScrollViewId());
+    const innerRef = useRef<ScrollView | null>(null);
     const scrollState = useRef<{
       offsetY: number;
       viewportHeight: number;
       contentHeight: number;
     } | null>(null);
 
-    // Cleanup debounce timer on unmount
+    // Forward the inner ref to the parent's ref (if provided)
+    const setRef = useCallback((node: ScrollView | null) => {
+      innerRef.current = node;
+      if (typeof ref === 'function') {
+        ref(node);
+      } else if (ref) {
+        (ref as React.MutableRefObject<ScrollView | null>).current = node;
+      }
+    }, [ref]);
+
+    /** Measure window-relative bounds and register with SDK. */
+    const measureAndRegister = useCallback(() => {
+      const node = innerRef.current as any;
+      if (!node || typeof node.measureInWindow !== 'function') return;
+      node.measureInWindow((x: number, y: number, width: number, height: number) => {
+        if (width <= 0 || height <= 0) return;
+        try {
+          AppAnalytics.getInstance().registerScrollView(scrollViewId.current, {
+            x, y, width, height,
+          });
+        } catch {}
+      });
+    }, []);
+
+    // Cleanup timers + unregister on unmount
     useEffect(() => {
+      const id = scrollViewId.current;
       return () => {
         if (debounceTimer.current) clearTimeout(debounceTimer.current);
+        if (scrollIntervalTimer.current) clearInterval(scrollIntervalTimer.current);
+        try {
+          AppAnalytics.getInstance().unregisterScrollView(id);
+        } catch {}
       };
     }, []);
 
     /**
      * Core tile capture logic. Reads from refs (stable across renders).
      * Checks throttle + delta before capturing.
+     *
+     * @param force Skip throttle check (used for interval captures)
      */
-    const doCapture = () => {
+    const doCapture = (force = false) => {
       const state = scrollState.current;
       if (!state || state.viewportHeight <= 0) return;
 
       const now = Date.now();
-      if (now - lastCaptureTime.current < THROTTLE_MS) return;
+      if (!force && now - lastCaptureTime.current < THROTTLE_MS) return;
+
+      // Always check delta — no point re-capturing the same position
       if (Math.abs(state.offsetY - lastCaptureY.current) < MIN_DELTA_PX &&
           initialCaptured.current) return;
 
@@ -68,30 +116,54 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
       } catch {}
     };
 
+    /** Start the interval timer for continuous scroll captures. */
+    const startScrollInterval = () => {
+      if (scrollIntervalTimer.current !== null) return;
+      scrollIntervalTimer.current = setInterval(() => {
+        doCapture(true); // force=true skips throttle
+      }, SCROLL_INTERVAL_MS);
+    };
+
+    /** Stop the interval timer. */
+    const stopScrollInterval = () => {
+      if (scrollIntervalTimer.current !== null) {
+        clearInterval(scrollIntervalTimer.current);
+        scrollIntervalTimer.current = null;
+      }
+    };
+
     const handleScroll = useCallback(
       (event: NativeSyntheticEvent<NativeScrollEvent>) => {
         const { contentOffset, layoutMeasurement, contentSize } =
           event.nativeEvent;
 
-        // Report scroll offset for touch coords
+        // Update SDK with current scroll offset (both legacy + new registry)
         try {
-          AppAnalytics.getInstance().setScrollOffset(contentOffset.y);
+          const sdk = AppAnalytics.getInstance();
+          sdk.setScrollOffset(contentOffset.y);
+          sdk.updateScrollViewOffset(scrollViewId.current, contentOffset.y);
         } catch {}
 
-        // Update scroll state
+        // Update scroll state — use realContentHeight if available
+        const bestContentHeight = realContentHeight.current > 0
+          ? realContentHeight.current
+          : contentSize.height;
         scrollState.current = {
           offsetY: contentOffset.y,
           viewportHeight: layoutMeasurement.height,
-          contentHeight: contentSize.height,
+          contentHeight: bestContentHeight,
         };
 
         // Debounce: capture after scroll stops
         if (debounceTimer.current) clearTimeout(debounceTimer.current);
-        debounceTimer.current = setTimeout(doCapture, DEBOUNCE_MS);
+        debounceTimer.current = setTimeout(() => doCapture(), DEBOUNCE_MS);
 
-        // Capture initial tile (Y≈0) on first scroll event with real dimensions
+        // Start interval for continuous scroll captures
+        startScrollInterval();
+
+        // Capture initial tile (Y~0) on first scroll event with real dims
         if (!initialCaptured.current && contentOffset.y < 10) {
-          setTimeout(doCapture, 200);
+          setTimeout(() => doCapture(), 200);
         }
 
         onScroll?.(event);
@@ -102,7 +174,8 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
     const handleScrollEndDrag = useCallback(
       (event: NativeSyntheticEvent<NativeScrollEvent>) => {
         // User lifted finger — capture immediately
-        doCapture();
+        stopScrollInterval();
+        doCapture(true);
         onScrollEndDrag?.(event);
       },
       [onScrollEndDrag],
@@ -114,7 +187,8 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
           clearTimeout(debounceTimer.current);
           debounceTimer.current = null;
         }
-        doCapture();
+        stopScrollInterval();
+        doCapture(true);
         onMomentumScrollEnd?.(event);
       },
       [onMomentumScrollEnd],
@@ -128,23 +202,45 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
           scrollState.current = {
             offsetY: 0,
             viewportHeight: height,
-            contentHeight: height, // Will be updated on first scroll
+            contentHeight: realContentHeight.current || height,
           };
-          setTimeout(doCapture, 1000);
+          setTimeout(() => doCapture(), 1000);
         }
+        // Register window-relative bounds with the SDK.
+        // Defer measurement to next tick — onLayout fires before the view
+        // is positioned in the window on some Android versions.
+        setTimeout(measureAndRegister, 50);
         onLayout?.(event);
       },
-      [onLayout],
+      [onLayout, measureAndRegister],
+    );
+
+    /**
+     * Track the real content height from onContentSizeChange.
+     * This is more reliable than the first scroll event and ensures
+     * the initial tile at Y=0 has correct contentHeight metadata.
+     */
+    const handleContentSizeChange = useCallback(
+      (w: number, h: number) => {
+        realContentHeight.current = h;
+        // Update scroll state if it exists
+        if (scrollState.current) {
+          scrollState.current.contentHeight = h;
+        }
+        onContentSizeChange?.(w, h);
+      },
+      [onContentSizeChange],
     );
 
     return (
       <ScrollView
-        ref={ref}
+        ref={setRef}
         {...props}
         onScroll={handleScroll}
         onScrollEndDrag={handleScrollEndDrag}
         onMomentumScrollEnd={handleMomentumEnd}
         onLayout={handleLayout}
+        onContentSizeChange={handleContentSizeChange}
         scrollEventThrottle={props.scrollEventThrottle ?? 16}
       />
     );

package/src/core/client.ts

@@ -31,6 +31,25 @@ export class AppAnalytics {
   private logger: Logger;
   private appStateSubscription: { remove: () => void } | null = null;
 
+  /**
+   * Registry of active ScrollViews on the current screen.
+   * Each RepliqoScrollView registers its window-relative bounds and current
+   * scroll state. Used by trackTouch to auto-detect:
+   *   - If touch is INSIDE a ScrollView → adjust Y by that ScrollView's
+   *     scrollOffset, mark as content touch
+   *   - If touch is OUTSIDE all ScrollViews → mark as fixed UI (no adjust)
+   *
+   * This makes heatmaps render fixed elements (nav bars, headers) at their
+   * viewport position, while still mapping scrollable content correctly.
+   */
+  private scrollViewRegistry = new Map<
+    string,
+    {
+      bounds: { x: number; y: number; width: number; height: number };
+      scrollOffsetY: number;
+    }
+  >();
+
   private constructor(config: SDKConfig) {
     this.config = resolveConfig(config);
     this.logger = new Logger(this.config.debug);
@@ -246,15 +265,45 @@ export class AppAnalytics {
       return;
     }
 
-    // Adjust Y by the current scroll offset so touches map to content
-    // position, not just viewport position. This makes heatmaps accurate
-    // for scrollable screens.
-    const adjustedY = y + this.scrollOffsetY;
+    // Auto-detect: find which (if any) registered ScrollView contains
+    // this touch. If inside, adjust Y by that ScrollView's scroll offset.
+    // If outside all ScrollViews, treat as fixed UI (no adjustment).
+    let activeScrollOffset = 0;
+    let isFixed = true;
+
+    if (this.scrollViewRegistry.size > 0) {
+      for (const info of this.scrollViewRegistry.values()) {
+        const { bounds } = info;
+        if (
+          x >= bounds.x &&
+          x <= bounds.x + bounds.width &&
+          y >= bounds.y &&
+          y <= bounds.y + bounds.height
+        ) {
+          activeScrollOffset = info.scrollOffsetY;
+          isFixed = false;
+          break;
+        }
+      }
+    } else {
+      // No ScrollViews registered → fall back to legacy behavior
+      // (use the manually-set scrollOffsetY, treat as content touch).
+      activeScrollOffset = this.scrollOffsetY;
+      isFixed = false;
+    }
+
+    const adjustedY = y + activeScrollOffset;
 
     const event: AnalyticsEvent = {
       type: 'touch',
       screenName: screenName || this.currentScreen || undefined,
-      data: { x, y: adjustedY, scrollOffsetY: this.scrollOffsetY, ...extra },
+      data: {
+        x,
+        y: adjustedY,
+        scrollOffsetY: activeScrollOffset,
+        isFixed,
+        ...extra,
+      },
       timestamp: new Date().toISOString(),
     };
 
@@ -316,11 +365,49 @@ export class AppAnalytics {
    * or manually from the host app's ScrollView onScroll handler.
    * The offset is added to touch Y coordinates for accurate heatmaps
    * on scrollable screens.
+   *
+   * @deprecated Prefer registerScrollView + updateScrollViewOffset for
+   * auto-detection of fixed vs scrollable touches. Kept for backward compat.
    */
   setScrollOffset(y: number): void {
     this.scrollOffsetY = y;
   }
 
+  /**
+   * Register a ScrollView's window-relative bounds with the SDK.
+   * Called by RepliqoScrollView on layout. Used to auto-detect whether
+   * a touch is on scrollable content or on fixed UI (nav bars, headers).
+   */
+  registerScrollView(
+    id: string,
+    bounds: { x: number; y: number; width: number; height: number },
+  ): void {
+    const existing = this.scrollViewRegistry.get(id);
+    this.scrollViewRegistry.set(id, {
+      bounds,
+      scrollOffsetY: existing?.scrollOffsetY ?? 0,
+    });
+  }
+
+  /**
+   * Update the scroll offset for a previously-registered ScrollView.
+   * Called by RepliqoScrollView on every scroll event.
+   */
+  updateScrollViewOffset(id: string, scrollOffsetY: number): void {
+    const existing = this.scrollViewRegistry.get(id);
+    if (existing) {
+      existing.scrollOffsetY = scrollOffsetY;
+    }
+  }
+
+  /**
+   * Remove a ScrollView from the registry. Called by RepliqoScrollView
+   * on unmount.
+   */
+  unregisterScrollView(id: string): void {
+    this.scrollViewRegistry.delete(id);
+  }
+
   /**
    * Capture the current viewport as a tile for collaborative screen
    * building. Called by RepliqoScrollView on scroll stops.
@@ -414,17 +501,18 @@ export class AppAnalytics {
     this.currentScreen = screenName;
     this.currentScreenEnteredAt = new Date().toISOString();
     this.scrollOffsetY = 0;
+    // Clear the ScrollView registry — old screen's scrollviews are gone
+    this.scrollViewRegistry.clear();
     this.errorTracker?.setCurrentScreen(screenName);
     this.snapshotCapture?.setCurrentScreen(screenName);
-    // Auto-scan with PixelCopy: captures entire ScrollView content
-    // by scrolling programmatically + PixelCopy from GPU framebuffer.
-    // Fires 2s after screen enter to let content fully render.
-    if (this.config.enableHeatmapCapture) {
-      setTimeout(() => {
-        if (this.currentScreen !== screenName || !this.sessionId) return;
-        this.autoScanScreen(screenName);
-      }, 2000);
-    }
+    // NOTE: autoScanScreen (PixelCopy / programmatic scroll) is DISABLED.
+    // React Native does NOT render off-screen content to the GPU or view
+    // tree, so programmatic scroll + View.draw()/PixelCopy produces blank
+    // tiles. Worse, those blank tiles poison the dedup cache and block
+    // real tiles captured during natural user scroll.
+    //
+    // Full-content capture relies entirely on RepliqoScrollView capturing
+    // viewport tiles as the user naturally scrolls through the content.
 
     this.logger.log('Screen entered:', screenName);
   }