@repliqo/sdk-react-native 0.3.5 → 0.3.7

package/dist/components/RepliqoScrollView.js

@@ -49,6 +49,12 @@ const THROTTLE_MS = 400;
  * where the user never pauses long enough for the debounce to fire.
  */
 const SCROLL_INTERVAL_MS = 1200;
+/**
+ * During scroll, throttle window-bounds re-measurement to at most once per
+ * this many ms. Bounds rarely change while scrolling, but we still want to
+ * catch orientation changes / keyboard / overlay animations.
+ */
+const REMEASURE_THROTTLE_MS = 500;
 let scrollViewIdCounter = 0;
 const nextScrollViewId = () => `repliqo-scroll-${++scrollViewIdCounter}`;
 /**
@@ -64,16 +70,28 @@ const nextScrollViewId = () => `repliqo-scroll-${++scrollViewIdCounter}`;
 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 initialLayoutTimer = (0, react_1.useRef)(null);
     const lastCaptureTime = (0, react_1.useRef)(0);
     const lastCaptureY = (0, react_1.useRef)(-999);
+    const lastMeasureTime = (0, react_1.useRef)(0);
     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 isMounted = (0, react_1.useRef)(true);
+    // Last measured window-relative top Y of the ScrollView — passed to
+    // captureScrollTile so the backend can crop each tile to just the
+    // scroll viewport area (no fixed header/footer duplication).
+    const lastViewportTop = (0, react_1.useRef)(null);
     const scrollState = (0, react_1.useRef)(null);
-    // Forward the inner ref to the parent's ref (if provided)
+    // Forward the inner ref to the parent's ref (if provided).
+    // IMPORTANT: do NOT clear innerRef on cleanup — RN sometimes calls the
+    // ref callback with null mid-update, and clearing would break async
+    // measurement callbacks that fire after the ref reattaches.
     const setRef = (0, react_1.useCallback)((node) => {
-        innerRef.current = node;
+        if (node !== null) {
+            innerRef.current = node;
+        }
         if (typeof ref === 'function') {
             ref(node);
         }
@@ -81,14 +99,24 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
             ref.current = node;
         }
     }, [ref]);
-    /** Measure window-relative bounds and register with SDK. */
+    /**
+     * Measure window-relative bounds and register with SDK.
+     * Idempotent + safe to call after unmount (guards via isMounted).
+     */
     const measureAndRegister = (0, react_1.useCallback)(() => {
+        if (!isMounted.current)
+            return;
         const node = innerRef.current;
         if (!node || typeof node.measureInWindow !== 'function')
             return;
         node.measureInWindow((x, y, width, height) => {
+            if (!isMounted.current)
+                return;
+            // RN sometimes returns 0/0 dims before the view is positioned —
+            // ignore those, the next onLayout/onScroll will re-measure.
             if (width <= 0 || height <= 0)
                 return;
+            lastViewportTop.current = y;
             try {
                 client_1.AppAnalytics.getInstance().registerScrollView(scrollViewId.current, {
                     x, y, width, height,
@@ -97,20 +125,29 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
             catch { }
         });
     }, []);
-    // Cleanup timers + unregister on unmount
+    // Cleanup all timers + unregister + listeners on unmount
     (0, react_1.useEffect)(() => {
         const id = scrollViewId.current;
+        isMounted.current = true;
+        // Re-measure when keyboard appears/disappears (causes layout shift)
+        const showSub = react_native_1.Keyboard.addListener('keyboardDidShow', measureAndRegister);
+        const hideSub = react_native_1.Keyboard.addListener('keyboardDidHide', measureAndRegister);
         return () => {
+            isMounted.current = false;
             if (debounceTimer.current)
                 clearTimeout(debounceTimer.current);
             if (scrollIntervalTimer.current)
                 clearInterval(scrollIntervalTimer.current);
+            if (initialLayoutTimer.current)
+                clearTimeout(initialLayoutTimer.current);
+            showSub.remove();
+            hideSub.remove();
             try {
                 client_1.AppAnalytics.getInstance().unregisterScrollView(id);
             }
             catch { }
         };
-    }, []);
+    }, [measureAndRegister]);
     /**
      * Core tile capture logic. Reads from refs (stable across renders).
      * Checks throttle + delta before capturing.
@@ -118,6 +155,8 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
      * @param force Skip throttle check (used for interval captures)
      */
     const doCapture = (force = false) => {
+        if (!isMounted.current)
+            return;
         const state = scrollState.current;
         if (!state || state.viewportHeight <= 0)
             return;
@@ -132,7 +171,8 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
         lastCaptureY.current = state.offsetY;
         initialCaptured.current = true;
         try {
-            client_1.AppAnalytics.getInstance().captureScrollTile(state.offsetY, state.viewportHeight, state.contentHeight);
+            const windowHeight = react_native_1.Dimensions.get('window').height;
+            client_1.AppAnalytics.getInstance().captureScrollTile(state.offsetY, state.viewportHeight, state.contentHeight, lastViewportTop.current ?? undefined, windowHeight);
         }
         catch { }
     };
@@ -160,6 +200,13 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
             sdk.updateScrollViewOffset(scrollViewId.current, contentOffset.y);
         }
         catch { }
+        // Re-measure bounds occasionally during scroll — catches layout
+        // shifts from animations, keyboard, orientation changes, etc.
+        const now = Date.now();
+        if (now - lastMeasureTime.current > REMEASURE_THROTTLE_MS) {
+            lastMeasureTime.current = now;
+            measureAndRegister();
+        }
         // Update scroll state — use realContentHeight if available
         const bestContentHeight = realContentHeight.current > 0
             ? realContentHeight.current
@@ -177,10 +224,12 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
         startScrollInterval();
         // Capture initial tile (Y~0) on first scroll event with real dims
         if (!initialCaptured.current && contentOffset.y < 10) {
-            setTimeout(() => doCapture(), 200);
+            if (initialLayoutTimer.current)
+                clearTimeout(initialLayoutTimer.current);
+            initialLayoutTimer.current = setTimeout(() => doCapture(), 200);
         }
         onScroll?.(event);
-    }, [onScroll]);
+    }, [onScroll, measureAndRegister]);
     const handleScrollEndDrag = (0, react_1.useCallback)((event) => {
         // User lifted finger — capture immediately
         stopScrollInterval();
@@ -197,7 +246,6 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
         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 = {
@@ -205,12 +253,15 @@ exports.RepliqoScrollView = react_1.default.forwardRef(({ onScroll, onMomentumSc
                 viewportHeight: height,
                 contentHeight: realContentHeight.current || height,
             };
-            setTimeout(() => doCapture(), 1000);
+            // Clear any prior pending initial-capture timer before scheduling
+            if (initialLayoutTimer.current)
+                clearTimeout(initialLayoutTimer.current);
+            initialLayoutTimer.current = 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);
+        // Register window-relative bounds immediately (no setTimeout).
+        // measureInWindow itself is async; if it returns 0/0 dims, the
+        // next onLayout / onScroll will retry — no race window.
+        measureAndRegister();
         onLayout?.(event);
     }, [onLayout, measureAndRegister]);
     /**

package/dist/core/client.d.ts

@@ -32,6 +32,20 @@ export declare class AppAnalytics {
     static destroy(): void;
     startSession(deviceId: string, deviceInfo?: DeviceInfo): Promise<string>;
     endSession(): Promise<void>;
+    /**
+     * Track a touch event for heatmap analysis.
+     *
+     * @param x Touch X coordinate, in WINDOW coordinates (must match the
+     *          coordinate system of `measureInWindow` — typically `pageX`
+     *          from a React Native gesture event).
+     * @param y Touch Y coordinate, in WINDOW coordinates (must match the
+     *          coordinate system of `measureInWindow` — typically `pageY`
+     *          from a React Native gesture event). On Android with edge-to-edge
+     *          enabled, ensure `pageY` excludes the status bar to stay
+     *          consistent with `measureInWindow`.
+     * @param screenName Optional screen name (defaults to current screen).
+     * @param extra Optional extra data to attach to the event.
+     */
     trackTouch(x: number, y: number, screenName?: string, extra?: Record<string, any>): void;
     trackNavigation(fromScreen: string, toScreen: string): void;
     trackCustomEvent(eventName: string, data?: Record<string, any>): void;
@@ -71,11 +85,16 @@ export declare class AppAnalytics {
      * 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.
+     * The tile includes:
+     *  - `scrollOffsetY`: where in the full content this viewport belongs
+     *  - `viewportTop`: Y position (window logical px) of the ScrollView's
+     *    top edge. Used by the backend to crop each tile to just the
+     *    scrollable area, removing fixed headers/footers that would
+     *    otherwise duplicate in the composite.
+     *  - `windowHeight`: window height in logical px, for image-to-logical
+     *    scale computation during backend cropping.
      */
-    captureScrollTile(scrollOffsetY: number, viewportHeight: number, contentHeight: number): void;
+    captureScrollTile(scrollOffsetY: number, viewportHeight: number, contentHeight: number, viewportTop?: number, windowHeight?: number): void;
     /**
      * Programmatically scroll-scan the current ScrollView and upload all
      * tiles to the backend. Invisible to the user (~300-500ms).

package/dist/core/client.js

@@ -167,6 +167,20 @@ class AppAnalytics {
             this.snapshotCapture.setSessionId(null);
         }
     }
+    /**
+     * Track a touch event for heatmap analysis.
+     *
+     * @param x Touch X coordinate, in WINDOW coordinates (must match the
+     *          coordinate system of `measureInWindow` — typically `pageX`
+     *          from a React Native gesture event).
+     * @param y Touch Y coordinate, in WINDOW coordinates (must match the
+     *          coordinate system of `measureInWindow` — typically `pageY`
+     *          from a React Native gesture event). On Android with edge-to-edge
+     *          enabled, ensure `pageY` excludes the status bar to stay
+     *          consistent with `measureInWindow`.
+     * @param screenName Optional screen name (defaults to current screen).
+     * @param extra Optional extra data to attach to the event.
+     */
     trackTouch(x, y, screenName, extra) {
         if (!this.sessionId) {
             this.logger.warn('Cannot track touch: no active session');
@@ -176,29 +190,48 @@ class AppAnalytics {
             return;
         }
         // 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;
+        // this touch. If multiple match (nested ScrollViews, e.g. FlatList
+        // inside ScrollView), pick the SMALLEST by area — the most-nested
+        // one is the actual scroll context for that touch.
+        let bestMatchOffset = 0;
+        let bestMatchArea = Infinity;
+        let foundMatch = false;
+        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) {
+                const area = bounds.width * bounds.height;
+                if (area < bestMatchArea) {
+                    bestMatchArea = area;
+                    bestMatchOffset = info.scrollOffsetY;
+                    foundMatch = true;
                 }
             }
         }
-        else {
-            // No ScrollViews registered → fall back to legacy behavior
-            // (use the manually-set scrollOffsetY, treat as content touch).
-            activeScrollOffset = this.scrollOffsetY;
+        let activeScrollOffset;
+        let isFixed;
+        if (foundMatch) {
+            // Touch is inside a registered ScrollView → content touch
+            activeScrollOffset = bestMatchOffset;
             isFixed = false;
         }
+        else if (this.scrollViewRegistry.size > 0) {
+            // ScrollViews ARE registered, but this touch is outside all of them
+            // → it's on fixed UI (nav bar, header, etc.)
+            activeScrollOffset = 0;
+            isFixed = true;
+        }
+        else {
+            // No ScrollViews registered at all. Two possible cases:
+            //   (a) The screen has no scrollable content → touch is fixed
+            //   (b) RepliqoScrollView hasn't measured yet (first ~1 frame)
+            // Either way, marking as fixed is safer than guessing content
+            // position with stale scrollOffsetY from a previous screen.
+            activeScrollOffset = 0;
+            isFixed = true;
+        }
         const adjustedY = y + activeScrollOffset;
         const event = {
             type: 'touch',
@@ -298,11 +331,16 @@ class AppAnalytics {
      * 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.
+     * The tile includes:
+     *  - `scrollOffsetY`: where in the full content this viewport belongs
+     *  - `viewportTop`: Y position (window logical px) of the ScrollView's
+     *    top edge. Used by the backend to crop each tile to just the
+     *    scrollable area, removing fixed headers/footers that would
+     *    otherwise duplicate in the composite.
+     *  - `windowHeight`: window height in logical px, for image-to-logical
+     *    scale computation during backend cropping.
      */
-    captureScrollTile(scrollOffsetY, viewportHeight, contentHeight) {
+    captureScrollTile(scrollOffsetY, viewportHeight, contentHeight, viewportTop, windowHeight) {
         if (!this.sessionId || !this.currentScreen)
             return;
         if (viewportHeight <= 0)
@@ -317,8 +355,9 @@ class AppAnalytics {
                     return;
                 this.logger.log(`Scroll tile: "${screenName}" Y=${Math.round(scrollOffsetY)} ` +
                     `vp=${Math.round(viewportHeight)} content=${Math.round(contentHeight)} ` +
+                    `top=${viewportTop !== undefined ? Math.round(viewportTop) : '?'} ` +
                     `${Math.round(frame.image.length / 1024)}KB`);
-                await this.apiClient.uploadScreenTile(sessionId, screenName, frame.image, frame.width, frame.height, scrollOffsetY, viewportHeight, contentHeight);
+                await this.apiClient.uploadScreenTile(sessionId, screenName, frame.image, frame.width, frame.height, scrollOffsetY, viewportHeight, contentHeight, viewportTop, windowHeight);
             }
             catch (err) {
                 this.logger.warn('Scroll tile failed:', err);

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

@@ -32,7 +32,14 @@ export declare class ApiClient {
      */
     /**
      * Upload a scroll tile for collaborative screen building.
+     *
+     * @param viewportTop Y position (window logical px) of the ScrollView's
+     *   top edge. Used by the backend to crop each tile to just the
+     *   scrollable area, removing fixed headers/footers that would
+     *   otherwise duplicate in the composite.
+     * @param windowHeight Window height (logical px) at capture time.
+     *   Used by the backend to compute image-to-logical scale for cropping.
      */
-    uploadScreenTile(sessionId: string, screenName: string, image: string, width: number, height: number, scrollOffsetY: number, viewportHeight: number, contentHeight: number): Promise<void>;
+    uploadScreenTile(sessionId: string, screenName: string, image: string, width: number, height: number, scrollOffsetY: number, viewportHeight: number, contentHeight: number, viewportTop?: number, windowHeight?: number): Promise<void>;
     uploadScreenCapture(screenName: string, image: string, width: number, height: number, isFullContent: boolean): Promise<void>;
 }

package/dist/transport/api.client.js

@@ -158,22 +158,36 @@ class ApiClient {
      */
     /**
      * Upload a scroll tile for collaborative screen building.
+     *
+     * @param viewportTop Y position (window logical px) of the ScrollView's
+     *   top edge. Used by the backend to crop each tile to just the
+     *   scrollable area, removing fixed headers/footers that would
+     *   otherwise duplicate in the composite.
+     * @param windowHeight Window height (logical px) at capture time.
+     *   Used by the backend to compute image-to-logical scale for cropping.
      */
-    async uploadScreenTile(sessionId, screenName, image, width, height, scrollOffsetY, viewportHeight, contentHeight) {
+    async uploadScreenTile(sessionId, screenName, image, width, height, scrollOffsetY, viewportHeight, contentHeight, viewportTop, windowHeight) {
         try {
+            const body = {
+                sessionId,
+                screenName,
+                image,
+                width,
+                height,
+                scrollOffsetY: Math.round(scrollOffsetY),
+                viewportHeight: Math.round(viewportHeight),
+                contentHeight: Math.round(contentHeight),
+            };
+            if (typeof viewportTop === 'number' && Number.isFinite(viewportTop)) {
+                body.viewportTop = Math.round(viewportTop);
+            }
+            if (typeof windowHeight === 'number' && Number.isFinite(windowHeight)) {
+                body.windowHeight = Math.round(windowHeight);
+            }
             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),
-                }),
+                body: JSON.stringify(body),
             });
             if (!response.ok) {
                 const text = await response.text();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@repliqo/sdk-react-native",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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,6 +1,8 @@
 import React, { useCallback, useRef, useEffect } from 'react';
 import {
   ScrollView,
+  Keyboard,
+  Dimensions,
   type ScrollViewProps,
   type NativeSyntheticEvent,
   type NativeScrollEvent,
@@ -20,6 +22,12 @@ const THROTTLE_MS = 400;
  * where the user never pauses long enough for the debounce to fire.
  */
 const SCROLL_INTERVAL_MS = 1200;
+/**
+ * During scroll, throttle window-bounds re-measurement to at most once per
+ * this many ms. Bounds rarely change while scrolling, but we still want to
+ * catch orientation changes / keyboard / overlay animations.
+ */
+const REMEASURE_THROTTLE_MS = 500;
 
 let scrollViewIdCounter = 0;
 const nextScrollViewId = () => `repliqo-scroll-${++scrollViewIdCounter}`;
@@ -38,21 +46,33 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
   ({ onScroll, onMomentumScrollEnd, onScrollEndDrag, onLayout, onContentSizeChange, ...props }, ref) => {
     const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
     const scrollIntervalTimer = useRef<ReturnType<typeof setInterval> | null>(null);
+    const initialLayoutTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
     const lastCaptureTime = useRef(0);
     const lastCaptureY = useRef(-999);
+    const lastMeasureTime = useRef(0);
     const initialCaptured = useRef(false);
     const realContentHeight = useRef(0);
     const scrollViewId = useRef<string>(nextScrollViewId());
     const innerRef = useRef<ScrollView | null>(null);
+    const isMounted = useRef(true);
+    // Last measured window-relative top Y of the ScrollView — passed to
+    // captureScrollTile so the backend can crop each tile to just the
+    // scroll viewport area (no fixed header/footer duplication).
+    const lastViewportTop = useRef<number | null>(null);
     const scrollState = useRef<{
       offsetY: number;
       viewportHeight: number;
       contentHeight: number;
     } | null>(null);
 
-    // Forward the inner ref to the parent's ref (if provided)
+    // Forward the inner ref to the parent's ref (if provided).
+    // IMPORTANT: do NOT clear innerRef on cleanup — RN sometimes calls the
+    // ref callback with null mid-update, and clearing would break async
+    // measurement callbacks that fire after the ref reattaches.
     const setRef = useCallback((node: ScrollView | null) => {
-      innerRef.current = node;
+      if (node !== null) {
+        innerRef.current = node;
+      }
       if (typeof ref === 'function') {
         ref(node);
       } else if (ref) {
@@ -60,12 +80,20 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
       }
     }, [ref]);
 
-    /** Measure window-relative bounds and register with SDK. */
+    /**
+     * Measure window-relative bounds and register with SDK.
+     * Idempotent + safe to call after unmount (guards via isMounted).
+     */
     const measureAndRegister = useCallback(() => {
+      if (!isMounted.current) return;
       const node = innerRef.current as any;
       if (!node || typeof node.measureInWindow !== 'function') return;
       node.measureInWindow((x: number, y: number, width: number, height: number) => {
+        if (!isMounted.current) return;
+        // RN sometimes returns 0/0 dims before the view is positioned —
+        // ignore those, the next onLayout/onScroll will re-measure.
         if (width <= 0 || height <= 0) return;
+        lastViewportTop.current = y;
         try {
           AppAnalytics.getInstance().registerScrollView(scrollViewId.current, {
             x, y, width, height,
@@ -74,17 +102,27 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
       });
     }, []);
 
-    // Cleanup timers + unregister on unmount
+    // Cleanup all timers + unregister + listeners on unmount
     useEffect(() => {
       const id = scrollViewId.current;
+      isMounted.current = true;
+
+      // Re-measure when keyboard appears/disappears (causes layout shift)
+      const showSub = Keyboard.addListener('keyboardDidShow', measureAndRegister);
+      const hideSub = Keyboard.addListener('keyboardDidHide', measureAndRegister);
+
       return () => {
+        isMounted.current = false;
         if (debounceTimer.current) clearTimeout(debounceTimer.current);
         if (scrollIntervalTimer.current) clearInterval(scrollIntervalTimer.current);
+        if (initialLayoutTimer.current) clearTimeout(initialLayoutTimer.current);
+        showSub.remove();
+        hideSub.remove();
         try {
           AppAnalytics.getInstance().unregisterScrollView(id);
         } catch {}
       };
-    }, []);
+    }, [measureAndRegister]);
 
     /**
      * Core tile capture logic. Reads from refs (stable across renders).
@@ -93,6 +131,7 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
      * @param force Skip throttle check (used for interval captures)
      */
     const doCapture = (force = false) => {
+      if (!isMounted.current) return;
       const state = scrollState.current;
       if (!state || state.viewportHeight <= 0) return;
 
@@ -108,10 +147,13 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
       initialCaptured.current = true;
 
       try {
+        const windowHeight = Dimensions.get('window').height;
         AppAnalytics.getInstance().captureScrollTile(
           state.offsetY,
           state.viewportHeight,
           state.contentHeight,
+          lastViewportTop.current ?? undefined,
+          windowHeight,
         );
       } catch {}
     };
@@ -144,6 +186,14 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
           sdk.updateScrollViewOffset(scrollViewId.current, contentOffset.y);
         } catch {}
 
+        // Re-measure bounds occasionally during scroll — catches layout
+        // shifts from animations, keyboard, orientation changes, etc.
+        const now = Date.now();
+        if (now - lastMeasureTime.current > REMEASURE_THROTTLE_MS) {
+          lastMeasureTime.current = now;
+          measureAndRegister();
+        }
+
         // Update scroll state — use realContentHeight if available
         const bestContentHeight = realContentHeight.current > 0
           ? realContentHeight.current
@@ -163,12 +213,13 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
 
         // Capture initial tile (Y~0) on first scroll event with real dims
         if (!initialCaptured.current && contentOffset.y < 10) {
-          setTimeout(() => doCapture(), 200);
+          if (initialLayoutTimer.current) clearTimeout(initialLayoutTimer.current);
+          initialLayoutTimer.current = setTimeout(() => doCapture(), 200);
         }
 
         onScroll?.(event);
       },
-      [onScroll],
+      [onScroll, measureAndRegister],
     );
 
     const handleScrollEndDrag = useCallback(
@@ -196,7 +247,6 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
 
     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 = {
@@ -204,12 +254,14 @@ export const RepliqoScrollView = React.forwardRef<ScrollView, ScrollViewProps>(
             viewportHeight: height,
             contentHeight: realContentHeight.current || height,
           };
-          setTimeout(() => doCapture(), 1000);
+          // Clear any prior pending initial-capture timer before scheduling
+          if (initialLayoutTimer.current) clearTimeout(initialLayoutTimer.current);
+          initialLayoutTimer.current = 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);
+        // Register window-relative bounds immediately (no setTimeout).
+        // measureInWindow itself is async; if it returns 0/0 dims, the
+        // next onLayout / onScroll will retry — no race window.
+        measureAndRegister();
         onLayout?.(event);
       },
       [onLayout, measureAndRegister],

package/src/core/client.ts

@@ -250,6 +250,20 @@ export class AppAnalytics {
     }
   }
 
+  /**
+   * Track a touch event for heatmap analysis.
+   *
+   * @param x Touch X coordinate, in WINDOW coordinates (must match the
+   *          coordinate system of `measureInWindow` — typically `pageX`
+   *          from a React Native gesture event).
+   * @param y Touch Y coordinate, in WINDOW coordinates (must match the
+   *          coordinate system of `measureInWindow` — typically `pageY`
+   *          from a React Native gesture event). On Android with edge-to-edge
+   *          enabled, ensure `pageY` excludes the status bar to stay
+   *          consistent with `measureInWindow`.
+   * @param screenName Optional screen name (defaults to current screen).
+   * @param extra Optional extra data to attach to the event.
+   */
   trackTouch(
     x: number,
     y: number,
@@ -266,30 +280,50 @@ export class AppAnalytics {
     }
 
     // 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;
+    // this touch. If multiple match (nested ScrollViews, e.g. FlatList
+    // inside ScrollView), pick the SMALLEST by area — the most-nested
+    // one is the actual scroll context for that touch.
+    let bestMatchOffset = 0;
+    let bestMatchArea = Infinity;
+    let foundMatch = false;
+
+    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
+      ) {
+        const area = bounds.width * bounds.height;
+        if (area < bestMatchArea) {
+          bestMatchArea = area;
+          bestMatchOffset = info.scrollOffsetY;
+          foundMatch = true;
         }
       }
-    } else {
-      // No ScrollViews registered → fall back to legacy behavior
-      // (use the manually-set scrollOffsetY, treat as content touch).
-      activeScrollOffset = this.scrollOffsetY;
+    }
+
+    let activeScrollOffset: number;
+    let isFixed: boolean;
+
+    if (foundMatch) {
+      // Touch is inside a registered ScrollView → content touch
+      activeScrollOffset = bestMatchOffset;
       isFixed = false;
+    } else if (this.scrollViewRegistry.size > 0) {
+      // ScrollViews ARE registered, but this touch is outside all of them
+      // → it's on fixed UI (nav bar, header, etc.)
+      activeScrollOffset = 0;
+      isFixed = true;
+    } else {
+      // No ScrollViews registered at all. Two possible cases:
+      //   (a) The screen has no scrollable content → touch is fixed
+      //   (b) RepliqoScrollView hasn't measured yet (first ~1 frame)
+      // Either way, marking as fixed is safer than guessing content
+      // position with stale scrollOffsetY from a previous screen.
+      activeScrollOffset = 0;
+      isFixed = true;
     }
 
     const adjustedY = y + activeScrollOffset;
@@ -412,14 +446,21 @@ export class AppAnalytics {
    * 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.
+   * The tile includes:
+   *  - `scrollOffsetY`: where in the full content this viewport belongs
+   *  - `viewportTop`: Y position (window logical px) of the ScrollView's
+   *    top edge. Used by the backend to crop each tile to just the
+   *    scrollable area, removing fixed headers/footers that would
+   *    otherwise duplicate in the composite.
+   *  - `windowHeight`: window height in logical px, for image-to-logical
+   *    scale computation during backend cropping.
    */
   captureScrollTile(
     scrollOffsetY: number,
     viewportHeight: number,
     contentHeight: number,
+    viewportTop?: number,
+    windowHeight?: number,
   ): void {
     if (!this.sessionId || !this.currentScreen) return;
     if (viewportHeight <= 0) return; // No real dimensions yet
@@ -436,6 +477,7 @@ export class AppAnalytics {
         this.logger.log(
           `Scroll tile: "${screenName}" Y=${Math.round(scrollOffsetY)} ` +
             `vp=${Math.round(viewportHeight)} content=${Math.round(contentHeight)} ` +
+            `top=${viewportTop !== undefined ? Math.round(viewportTop) : '?'} ` +
             `${Math.round(frame.image.length / 1024)}KB`,
         );
 
@@ -448,6 +490,8 @@ export class AppAnalytics {
           scrollOffsetY,
           viewportHeight,
           contentHeight,
+          viewportTop,
+          windowHeight,
         );
       } catch (err) {
         this.logger.warn('Scroll tile failed:', err);

package/src/transport/api.client.ts

@@ -229,6 +229,13 @@ export class ApiClient {
    */
   /**
    * Upload a scroll tile for collaborative screen building.
+   *
+   * @param viewportTop Y position (window logical px) of the ScrollView's
+   *   top edge. Used by the backend to crop each tile to just the
+   *   scrollable area, removing fixed headers/footers that would
+   *   otherwise duplicate in the composite.
+   * @param windowHeight Window height (logical px) at capture time.
+   *   Used by the backend to compute image-to-logical scale for cropping.
    */
   async uploadScreenTile(
     sessionId: string,
@@ -239,23 +246,33 @@ export class ApiClient {
     scrollOffsetY: number,
     viewportHeight: number,
     contentHeight: number,
+    viewportTop?: number,
+    windowHeight?: number,
   ): Promise<void> {
     try {
+      const body: Record<string, unknown> = {
+        sessionId,
+        screenName,
+        image,
+        width,
+        height,
+        scrollOffsetY: Math.round(scrollOffsetY),
+        viewportHeight: Math.round(viewportHeight),
+        contentHeight: Math.round(contentHeight),
+      };
+      if (typeof viewportTop === 'number' && Number.isFinite(viewportTop)) {
+        body.viewportTop = Math.round(viewportTop);
+      }
+      if (typeof windowHeight === 'number' && Number.isFinite(windowHeight)) {
+        body.windowHeight = Math.round(windowHeight);
+      }
+
       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),
-          }),
+          body: JSON.stringify(body),
         },
       );