@rific/scroll-view 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rific/scroll-view",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Blur styled scroll system for React Native. Floating headers/footers, keyboard awareness, and scroll-away chrome",
   "keywords": [
     "react-native",
@@ -59,7 +59,7 @@
   },
   "devDependencies": {
     "@reduxjs/toolkit": "^2.12.0",
-    "@rific/auto-paper": "^0.3.1",
+    "@rific/auto-paper": "^0.4.0",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",
@@ -90,7 +90,7 @@
     "typescript-eslint": "^8.59.3"
   },
   "peerDependencies": {
-    "@rific/auto-paper": "^0.3.1",
+    "@rific/auto-paper": "^0.3.1 || ^0.4.0 || ^0.5.0",
     "react": ">=18.0.0",
     "react-native": ">=0.73.0",
     "react-native-gesture-handler": "*",

package/src/CustomList.tsx

@@ -1,22 +1,27 @@
-import { type ComponentType, memo, type ReactElement, type ReactNode, type RefObject, useCallback, useMemo, useRef } from 'react'
+import { type ComponentType, memo, type ReactElement, type ReactNode, type RefObject, useCallback, useContext, useLayoutEffect, useMemo, useRef } from 'react'
 import { Dimensions, type NativeScrollEvent, type NativeSyntheticEvent, type StyleProp, View, type ViewStyle } from 'react-native'
 import { Gesture, GestureDetector, type GestureType } from 'react-native-gesture-handler'
+import { runOnUI, useSharedValue } from 'react-native-reanimated'
 
 import { RefreshControl } from './internal/RefreshControl'
-import { ScrollViewChip } from './internal/ScrollViewChip'
+import { type ChipProps, ScrollViewChip } from './internal/ScrollViewChip'
 import { useScrollHandler } from './internal/useScrollHandler'
 import { useScrollList } from './internal/useScrollList'
+import { ScrollViewContext } from './ScrollViewContext'
 import { useScrollInit } from './useScrollInit'
 
 type ScrollToOffsetRef = { scrollToOffset: (params: { animated?: boolean; offset: number }) => void }
 
 export type CustomListProps<P extends object> = Omit<P, 'contentInset' | 'contentOffset' | 'onScroll' | 'refreshControl' | 'scrollEventThrottle'> & {
+  chipProps?: ChipProps
+  chipThreshold?: number
   component: ComponentType<P>
   renderFilters?: ReactNode
   footerFixed?: boolean
   gesture?: GestureType
   headerFixed?: boolean
   keyboardAware?: boolean
+  onChipPress?: () => void
   onMomentumScrollEnd?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
   onRefresh?: () => Promise<void> | void
   onScrollBeginDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
@@ -26,11 +31,35 @@ export type CustomListProps<P extends object> = Omit<P, 'contentInset' | 'conten
   style?: StyleProp<ViewStyle>
 }
 
-const CustomListInner = <P extends object>({ component: List, renderFilters, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, keyboardAware, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, scrollRef, style, ...props }: CustomListProps<P>) => {
+const CustomListInner = <P extends object>({ chipProps, chipThreshold, component: List, renderFilters, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, keyboardAware, onChipPress, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, scrollRef, style, ...props }: CustomListProps<P>) => {
   // Intercept ListHeaderComponent so useScrollInit can apply the same 2-phase measurement as FlatList.
   const { ListHeaderComponent: listHeaderComponent, contentContainerStyle: externalContentContainerStyle, ...restProps } = props as Record<string, unknown>
 
   const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, footerFixed, headerFixed } = useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, keyboardAware, pullSearchHeight, style })
+  const { listGeneration, onListUnmount } = useContext(ScrollViewContext)
+  // -1 never matches a real generation (starts at 0, only increments) — the runOnUI call below
+  // corrects it before any scroll event could observe the placeholder.
+  const capturedGeneration = useSharedValue(-1)
+  // Layout effects (not passive effects): React guarantees all layout-effect cleanups for fibers
+  // removed in a commit run before any layout-effect setups for fibers added in that same commit,
+  // but gives no such ordering guarantee for passive effects. On a key-forced remount, the outgoing
+  // instance's unmount and the incoming instance's mount land in the same commit — with passive
+  // effects, the incoming instance's sync could run before the outgoing instance's bump, permanently
+  // capturing a stale generation and silently disabling this instance's onScroll handling forever.
+  // Correct ordering alone isn't sufficient, though: the onScroll worklet reads capturedGeneration
+  // on the UI thread, and a plain JS-thread write to a SharedValue is not guaranteed to be visible
+  // there before a scroll event the UI thread schedules shortly after (e.g. useScrollInit's mount-time
+  // imperative scrollTo calls). Routing the write itself through runOnUI puts it on the UI thread's
+  // own serial queue, so it's guaranteed to run before any onScroll worklet invocation that could
+  // only be queued after this component finishes mounting.
+  useLayoutEffect(() => {
+    const generation = listGeneration.value
+    runOnUI((gen: number) => {
+      'worklet'
+      capturedGeneration.value = gen
+    })(generation)
+  }, [capturedGeneration, listGeneration])
+  useLayoutEffect(() => () => onListUnmount(), [onListUnmount])
 
   const scrollViewInternal = useRef<ScrollToOffsetRef | null>(null)
 
@@ -52,7 +81,10 @@ const CustomListInner = <P extends object>({ component: List, renderFilters, foo
     handleScrollBeginDrag,
     handleScrollEndDrag,
     hiddenHeader,
-    pullSearchMinHeight
+    onRemountSyncRetry,
+    onRemountSynced,
+    pullSearchMinHeight,
+    remountSyncTarget
   } = useScrollInit({
     listHeaderComponent: listHeaderComponent as ComponentType<object> | ReactElement | null | undefined,
     onMomentumScrollEnd: externalMomentumScrollEnd,
@@ -76,12 +108,7 @@ const CustomListInner = <P extends object>({ component: List, renderFilters, foo
 
   const contentContainerStyle = useMemo(() => [{ minHeight: Dimensions.get('window').height - contentInset.top - contentInset.bottom + pullSearchMinHeight }, externalContentContainerStyle], [contentInset.bottom, contentInset.top, externalContentContainerStyle, pullSearchMinHeight])
 
-  const onPullSearchZoneEnter = useCallback(() => {
-    if (!pullSearchHeight) return
-    scrollViewInternal.current?.scrollToOffset({ offset: -contentInset.top + pullSearchHeight, animated: true })
-  }, [contentInset.top, pullSearchHeight])
-
-  const onScroll = useScrollHandler({ chipHidden, footerFixed, headerFixed, onPullSearchZoneEnter: pullSearchHeight ? onPullSearchZoneEnter : undefined })
+  const onScroll = useScrollHandler({ capturedGeneration, chipHidden, chipThreshold, footerFixed, headerFixed, listGeneration, onRemountSyncRetry, onRemountSynced, remountSyncTarget })
 
   const handleScrollToTop = useCallback(() => {
     const offset = pullSearchHeight ? -contentInset.top + pullSearchHeight : -contentInset.top
@@ -116,7 +143,7 @@ const CustomListInner = <P extends object>({ component: List, renderFilters, foo
           {hiddenHeader}
         </View>
       )}
-      <ScrollViewChip onPress={handleScrollToTop} style={chipStyle} />
+      <ScrollViewChip chipProps={chipProps} onChipPress={onChipPress} onPress={handleScrollToTop} style={chipStyle} />
     </View>
   )
   return detectorGesture ? <GestureDetector gesture={detectorGesture}>{content}</GestureDetector> : content

package/src/FlatList.tsx

@@ -1,21 +1,24 @@
-import { memo, type ReactNode, type RefObject, useCallback, useMemo, useRef } from 'react'
-import { Dimensions, FlatList as RNFlatList, type FlatListProps as RNFlatListProps, type NativeScrollEvent, type NativeSyntheticEvent, View } from 'react-native'
+import { Fragment, memo, type ReactNode, type RefObject, useCallback, useContext, useLayoutEffect, useMemo, useRef } from 'react'
+import { Dimensions, FlatList as RNFlatList, type FlatListProps as RNFlatListProps, type ListRenderItem, type NativeScrollEvent, type NativeSyntheticEvent, type StyleProp, View, type ViewStyle } from 'react-native'
 import { Gesture, GestureDetector, type GestureType } from 'react-native-gesture-handler'
-import Animated from 'react-native-reanimated'
 
 import { HorizontalDots } from './internal/HorizontalDots'
 import { RefreshControl } from './internal/RefreshControl'
-import { ScrollViewChip } from './internal/ScrollViewChip'
-import { useScrollHandler } from './internal/useScrollHandler'
+import { type ChipProps, ScrollViewChip } from './internal/ScrollViewChip'
+import { useScrollHandlerJS } from './internal/useScrollHandlerJS'
 import { useScrollList } from './internal/useScrollList'
+import { ScrollViewContext } from './ScrollViewContext'
 import { useScrollInit } from './useScrollInit'
 
 export type FlatListProps<T> = Omit<RNFlatListProps<T>, 'onRefresh' | 'refreshing'> & {
+  chipProps?: ChipProps
+  chipThreshold?: number
   renderFilters?: ReactNode
   footerFixed?: boolean
   gesture?: GestureType
   headerFixed?: boolean
   keyboardAware?: boolean
+  onChipPress?: () => void
   onMomentumScrollEnd?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
   onRefresh?: () => Promise<void> | void
   onScrollBeginDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
@@ -24,12 +27,65 @@ export type FlatListProps<T> = Omit<RNFlatListProps<T>, 'onRefresh' | 'refreshin
   ref?: RefObject<RNFlatList | null>
 }
 
-const FlatListInner = <T,>({ contentContainerStyle: externalContentContainerStyle, data, initialNumToRender = 20, maxToRenderPerBatch = 50, renderFilters, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, horizontal, keyboardAware, ListHeaderComponent: externalListHeaderComponent, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pagingEnabled, pullSearchHeight, removeClippedSubviews = false, showsHorizontalScrollIndicator, showsVerticalScrollIndicator, style, onContentSizeChange, ref: externalRef, windowSize = 100, ...props }: FlatListProps<T>) => {
-  const scrollView = useRef<RNFlatList>(null)
+const FlatListInner = <T,>({ chipProps, chipThreshold, columnWrapperStyle, contentContainerStyle: externalContentContainerStyle, data, initialNumToRender = 20, keyExtractor, maxToRenderPerBatch = 50, numColumns, renderFilters, renderItem, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, horizontal, keyboardAware, ListHeaderComponent: externalListHeaderComponent, onChipPress, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pagingEnabled, pullSearchHeight, removeClippedSubviews = false, showsHorizontalScrollIndicator, showsVerticalScrollIndicator, style, onContentSizeChange, ref: externalRef, windowSize = 100, ...props }: FlatListProps<T>) => {
+  // Plain (non-Animated) FlatList: react-native-reanimated's Animated.FlatList does not reliably
+  // honor the initial `contentOffset` prop on a key-forced remount — the header/list can briefly
+  // render at the wrong position. A plain FlatList honors it correctly, so scroll position is driven
+  // by a regular JS onScroll callback (useScrollHandlerJS) instead of a Reanimated worklet — which
+  // also avoids the "WorkletEventHandler" crash that a worklet handler triggers when attached to a
+  // non-Animated component.
+  const scrollView = useRef<RNFlatList<T>>(null)
   const isHorizontal = horizontal === true
   const showDots = isHorizontal && pagingEnabled === true && (data?.length ?? 0) > 1
 
+  // RN's own FlatList implements numColumns by chunking `data` into rows internally, but throws if
+  // numColumns ever changes without the caller changing `key` to force a full remount. On iOS,
+  // Fabric pools/recycles native ScrollView instances by component type across such a remount, and
+  // the recycled instance's onScroll can silently stop firing for the new React instance entirely —
+  // a native event-routing issue, not something a JS-side retry loop can detect or correct. Doing
+  // the row-chunking ourselves here and always passing numColumns={1} through to the underlying
+  // RNFlatList means numColumns never "changes" from RN's perspective — only `data`/`renderItem`
+  // change, which RNFlatList treats as an ordinary prop update with no remount at all, so callers
+  // can toggle numColumns freely (e.g. switching a list to a grid) without ever hitting this class
+  // of bug.
+  const cols = numColumns && numColumns > 1 ? numColumns : 1
+  const rowData = useMemo(() => {
+    if (cols <= 1 || !data) return data
+    const items = Array.from(data)
+    const rows: T[][] = []
+    for (let i = 0; i < items.length; i += cols) rows.push(items.slice(i, i + cols))
+    return rows as unknown as readonly T[]
+  }, [cols, data])
+  const rowKeyExtractor = useCallback(
+    (row: T | T[], rowIndex: number) => {
+      if (cols <= 1) return keyExtractor ? keyExtractor(row as T, rowIndex) : defaultKeyExtractor(row as T, rowIndex)
+      return (row as T[]).map((item, kk) => (keyExtractor ? keyExtractor(item, rowIndex * cols + kk) : defaultKeyExtractor(item, rowIndex * cols + kk))).join(':')
+    },
+    [cols, keyExtractor]
+  )
+  const rowRenderItem = useCallback<ListRenderItem<T>>(
+    (info) => {
+      if (cols <= 1) return renderItem ? renderItem(info) : null
+      const row = info.item as unknown as T[]
+      return (
+        <View style={[styles.row, columnWrapperStyle] as StyleProp<ViewStyle>}>
+          {row.map((item, kk) => (
+            <Fragment key={kk}>{renderItem ? renderItem({ index: info.index * cols + kk, item, separators: info.separators }) : null}</Fragment>
+          ))}
+        </View>
+      )
+    },
+    [cols, columnWrapperStyle, renderItem]
+  )
+
   const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, footerFixed, headerFixed } = useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, isHorizontal, keyboardAware, pullSearchHeight, style })
+  const { jsListGeneration, onJsListUnmount } = useContext(ScrollViewContext)
+  // Plain ref, not a SharedValue: see the comment on ScrollViewContextType.jsListGeneration for why.
+  const capturedGeneration = useRef(jsListGeneration.current)
+  useLayoutEffect(() => {
+    capturedGeneration.current = jsListGeneration.current
+  }, [jsListGeneration])
+  useLayoutEffect(() => () => onJsListUnmount(), [onJsListUnmount])
 
   const scrollTo = useCallback((offset: number, animated: boolean) => {
     scrollView.current?.scrollToOffset({ offset, animated })
@@ -41,7 +97,8 @@ const FlatListInner = <T,>({ contentContainerStyle: externalContentContainerStyl
     handleScrollBeginDrag,
     handleScrollEndDrag,
     hiddenHeader,
-    pullSearchMinHeight
+    pullSearchMinHeight,
+    remountTarget
   } = useScrollInit({
     listHeaderComponent: externalListHeaderComponent,
     onMomentumScrollEnd: externalMomentumScrollEnd,
@@ -65,12 +122,31 @@ const FlatListInner = <T,>({ contentContainerStyle: externalContentContainerStyl
 
   const contentContainerStyle = useMemo(() => (isHorizontal ? externalContentContainerStyle : [{ minHeight: Dimensions.get('window').height - contentInset.top - contentInset.bottom + pullSearchMinHeight }, externalContentContainerStyle]), [isHorizontal, contentInset.bottom, contentInset.top, externalContentContainerStyle, pullSearchMinHeight])
 
-  const onPullSearchZoneEnter = useCallback(() => {
-    if (!pullSearchHeight) return
-    scrollView.current?.scrollToOffset({ offset: -contentInset.top + pullSearchHeight, animated: true })
-  }, [contentInset.top, pullSearchHeight])
+  const scrollHandler = useScrollHandlerJS({ capturedGeneration, chipHidden, chipThreshold, footerFixed, headerFixed, isHorizontal, jsListGeneration, remountTarget, scrollTo })
+
+  const onScrollBeginDrag = useCallback(
+    (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+      scrollHandler.onScrollBeginDrag(e)
+      handleScrollBeginDrag(e)
+    },
+    [scrollHandler, handleScrollBeginDrag]
+  )
+
+  const onScrollEndDrag = useCallback(
+    (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+      scrollHandler.onScrollEndDrag(e)
+      handleScrollEndDrag(e)
+    },
+    [scrollHandler, handleScrollEndDrag]
+  )
 
-  const handleScroll = useScrollHandler({ chipHidden, footerFixed, headerFixed, isHorizontal, onPullSearchZoneEnter: pullSearchHeight ? onPullSearchZoneEnter : undefined })
+  const onMomentumScrollEnd = useCallback(
+    (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+      scrollHandler.onMomentumScrollEnd(e)
+      handleMomentumScrollEnd(e)
+    },
+    [scrollHandler, handleMomentumScrollEnd]
+  )
 
   const handleScrollToTop = useCallback(() => {
     if (isHorizontal) {
@@ -95,23 +171,27 @@ const FlatListInner = <T,>({ contentContainerStyle: externalContentContainerStyl
 
   const content = (
     <View style={containerStyle}>
-      <Animated.FlatList
+      <RNFlatList
         {...(props as Omit<RNFlatListProps<T>, 'CellRendererComponent'>)}
         contentContainerStyle={contentContainerStyle}
         contentInset={contentInset}
+        contentInsetAdjustmentBehavior='never'
         contentOffset={contentOffset}
-        data={data}
+        data={cols > 1 ? rowData : data}
         horizontal={isHorizontal}
         initialNumToRender={initialNumToRender}
+        keyExtractor={cols > 1 ? rowKeyExtractor : keyExtractor}
         ListHeaderComponent={activeListHeader}
         maxToRenderPerBatch={maxToRenderPerBatch}
         onContentSizeChange={handleContentSizeChange}
-        onMomentumScrollEnd={handleMomentumScrollEnd}
-        onScroll={handleScroll}
-        onScrollBeginDrag={handleScrollBeginDrag}
-        onScrollEndDrag={handleScrollEndDrag}
+        onMomentumScrollBegin={scrollHandler.onMomentumScrollBegin}
+        onMomentumScrollEnd={onMomentumScrollEnd}
+        onScroll={scrollHandler.onScroll}
+        onScrollBeginDrag={onScrollBeginDrag}
+        onScrollEndDrag={onScrollEndDrag}
         pagingEnabled={pagingEnabled}
-        ref={(el: RNFlatList | null) => {
+        renderItem={cols > 1 ? rowRenderItem : renderItem}
+        ref={(el: RNFlatList<T> | null) => {
           if (externalRef) externalRef.current = el
           scrollView.current = el
         }}
@@ -127,13 +207,18 @@ const FlatListInner = <T,>({ contentContainerStyle: externalContentContainerStyl
           {hiddenHeader}
         </View>
       )}
-      <ScrollViewChip isHorizontal={isHorizontal} onPress={handleScrollToTop} style={chipStyle} />
+      <ScrollViewChip chipProps={chipProps} isHorizontal={isHorizontal} onChipPress={onChipPress} onPress={handleScrollToTop} style={chipStyle} />
       {showDots && <HorizontalDots total={data?.length ?? 0} />}
     </View>
   )
   return detectorGesture ? <GestureDetector gesture={detectorGesture}>{content}</GestureDetector> : content
 }
 
-const styles = { measureContainer: { left: 0, opacity: 0, position: 'absolute' as const, right: 0, top: -9999 } }
+const defaultKeyExtractor = <T,>(item: T, index: number): string => {
+  const key = (item as { id?: string; key?: string } | null)?.key ?? (item as { id?: string; key?: string } | null)?.id
+  return key != null ? String(key) : String(index)
+}
+
+const styles = { measureContainer: { left: 0, opacity: 0, position: 'absolute' as const, right: 0, top: -9999 }, row: { flexDirection: 'row' as const } }
 
 export const FlatList = memo(FlatListInner) as typeof FlatListInner

package/src/PullSearch.tsx

@@ -42,7 +42,7 @@ export const PullSearch = forwardRef<PullSearchHandle, PullSearchProps>(function
   useAnimatedReaction(
     () => {
       if (barHeight === 0) return false
-      return scrollPosition.value >= -headerHeight + barHeight
+      return scrollPosition.value >= -(headerHeight ?? 0) + barHeight
     },
     (isHidden, wasHidden) => {
       if (isHidden && !wasHidden) runOnJS(blurInput)()
@@ -81,8 +81,9 @@ export const PullSearch = forwardRef<PullSearchHandle, PullSearchProps>(function
   // hideY = -headerHeight + barHeight: bar scrolled behind header, opacity 0.
   const animatedStyle = useAnimatedStyle(() => {
     if (barHeight === 0) return { opacity: 0 }
-    const showY = -headerHeight
-    const hideY = -headerHeight + barHeight
+    const h = headerHeight ?? 0
+    const showY = -h
+    const hideY = -h + barHeight
     return { opacity: interpolate(scrollPosition.value, [showY, hideY], [1, 0], Extrapolation.CLAMP) }
   }, [barHeight, headerHeight])
 

package/src/ScrollView.tsx

@@ -1,19 +1,23 @@
-import { memo, type RefObject, useCallback, useMemo, useRef } from 'react'
+import { memo, type RefObject, useCallback, useContext, useLayoutEffect, useMemo, useRef } from 'react'
 import { type NativeScrollEvent, type NativeSyntheticEvent, ScrollView as RNScrollView, type ScrollViewProps as RNScrollViewProps, View } from 'react-native'
 import { Gesture, GestureDetector, type GestureType } from 'react-native-gesture-handler'
-import Animated from 'react-native-reanimated'
+import Animated, { runOnUI, useSharedValue } from 'react-native-reanimated'
 
 import { RefreshControl } from './internal/RefreshControl'
-import { ScrollViewChip } from './internal/ScrollViewChip'
+import { type ChipProps, ScrollViewChip } from './internal/ScrollViewChip'
 import { useScrollHandler } from './internal/useScrollHandler'
 import { useScrollList } from './internal/useScrollList'
+import { ScrollViewContext } from './ScrollViewContext'
 import { useScrollInit } from './useScrollInit'
 
 export type ScrollViewProps = RNScrollViewProps & {
+  chipProps?: ChipProps
+  chipThreshold?: number
   footerFixed?: boolean
   gesture?: GestureType
   headerFixed?: boolean
   keyboardAware?: boolean
+  onChipPress?: () => void
   onRefresh?: () => void
   onScrollBeginDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
   onScrollEndDrag?: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
@@ -22,11 +26,35 @@ export type ScrollViewProps = RNScrollViewProps & {
   refreshing?: boolean
 }
 
-const ScrollViewInner = ({ children, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, horizontal, keyboardAware, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, refreshing, style, ...props }: ScrollViewProps) => {
+const ScrollViewInner = ({ chipProps, chipThreshold, children, footerFixed: footerFixedProp, gesture, headerFixed: headerFixedProp, horizontal, keyboardAware, onChipPress, onMomentumScrollEnd: externalMomentumScrollEnd, onRefresh, onScrollBeginDrag: externalScrollBeginDrag, onScrollEndDrag: externalScrollEndDrag, pullSearchHeight, refreshing, style, ...props }: ScrollViewProps) => {
   const scrollView = useRef<RNScrollView>(null)
   const isHorizontal = horizontal === true
 
   const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, footerFixed, headerFixed } = useScrollList({ footerFixed: footerFixedProp, headerFixed: headerFixedProp, isHorizontal, keyboardAware, pullSearchHeight, style })
+  const { listGeneration, onListUnmount } = useContext(ScrollViewContext)
+  // -1 never matches a real generation (starts at 0, only increments) — the runOnUI call below
+  // corrects it before any scroll event could observe the placeholder.
+  const capturedGeneration = useSharedValue(-1)
+  // Layout effects (not passive effects): React guarantees all layout-effect cleanups for fibers
+  // removed in a commit run before any layout-effect setups for fibers added in that same commit,
+  // but gives no such ordering guarantee for passive effects. On a key-forced remount, the outgoing
+  // instance's unmount and the incoming instance's mount land in the same commit — with passive
+  // effects, the incoming instance's sync could run before the outgoing instance's bump, permanently
+  // capturing a stale generation and silently disabling this instance's onScroll handling forever.
+  // Correct ordering alone isn't sufficient, though: the onScroll worklet reads capturedGeneration
+  // on the UI thread, and a plain JS-thread write to a SharedValue is not guaranteed to be visible
+  // there before a scroll event the UI thread schedules shortly after (e.g. useScrollInit's mount-time
+  // imperative scrollTo calls). Routing the write itself through runOnUI puts it on the UI thread's
+  // own serial queue, so it's guaranteed to run before any onScroll worklet invocation that could
+  // only be queued after this component finishes mounting.
+  useLayoutEffect(() => {
+    const generation = listGeneration.value
+    runOnUI((gen: number) => {
+      'worklet'
+      capturedGeneration.value = gen
+    })(generation)
+  }, [capturedGeneration, listGeneration])
+  useLayoutEffect(() => () => onListUnmount(), [onListUnmount])
 
   const scrollTo = useCallback((offset: number, animated: boolean) => {
     scrollView.current?.scrollTo({ y: offset, animated })
@@ -40,12 +68,7 @@ const ScrollViewInner = ({ children, footerFixed: footerFixedProp, gesture, head
     scrollTo
   })
 
-  const onPullSearchZoneEnter = useCallback(() => {
-    if (!pullSearchHeight) return
-    scrollTo(-contentInset.top + pullSearchHeight, true)
-  }, [contentInset.top, pullSearchHeight, scrollTo])
-
-  const handleScroll = useScrollHandler({ chipHidden, footerFixed, headerFixed, isHorizontal, onPullSearchZoneEnter: pullSearchHeight ? onPullSearchZoneEnter : undefined })
+  const handleScroll = useScrollHandler({ capturedGeneration, chipHidden, chipThreshold, footerFixed, headerFixed, isHorizontal, listGeneration })
 
   const handleScrollToTop = useCallback(() => {
     if (isHorizontal) {
@@ -80,7 +103,7 @@ const ScrollViewInner = ({ children, footerFixed: footerFixedProp, gesture, head
       >
         {children}
       </Animated.ScrollView>
-      <ScrollViewChip isHorizontal={isHorizontal} onPress={handleScrollToTop} style={chipStyle} />
+      <ScrollViewChip chipProps={chipProps} isHorizontal={isHorizontal} onChipPress={onChipPress} onPress={handleScrollToTop} style={chipStyle} />
     </View>
   )
   return detectorGesture ? <GestureDetector gesture={detectorGesture}>{content}</GestureDetector> : content

package/src/ScrollViewContext.ts

@@ -1,4 +1,4 @@
-import { createContext } from 'react'
+import { createContext, type RefObject } from 'react'
 import { SharedValue } from 'react-native-reanimated'
 
 export type ScrollViewContextType = {
@@ -7,10 +7,19 @@ export type ScrollViewContextType = {
   footerHeightShared: SharedValue<number>
   footerFixed: boolean
   footerOffset: SharedValue<number>
-  headerHeight: number
+  headerHeight: number | null
   headerHeightShared: SharedValue<number>
   headerFixed: boolean
   headerOffset: SharedValue<number>
+  // Plain (non-Reanimated) counter for JS-thread-only scroll handlers (FlatList's useScrollHandlerJS).
+  // A SharedValue is deliberately NOT used here: mutating `.value` from inside a React commit-phase
+  // callback (a layout effect) is not synchronously visible even to an immediate subsequent read in
+  // the same callback — Reanimated defers the actual flush — which silently broke the "did another
+  // list instance just unmount" check this counter exists for. A plain ref has no such batching.
+  jsListGeneration: RefObject<number>
+  listGeneration: SharedValue<number>
+  onJsListUnmount: () => void
+  onListUnmount: () => void
   progress: number | null
   pullSearchHeightShared: SharedValue<number>
   snapBackFooterShared: SharedValue<boolean>
@@ -19,7 +28,7 @@ export type ScrollViewContextType = {
   scrollHeight: number
   scrollPosition: SharedValue<number>
   setFooterHeight: (h: number) => void
-  setHeaderHeight: (h: number) => void
+  setHeaderHeight: (h: number | null) => void
   setProgress: (p: number | null) => void
   setProgressing: (b: boolean) => void
   tabBarHeight: number
@@ -31,10 +40,14 @@ export const ScrollViewContext = createContext<ScrollViewContextType>({
   footerHeightShared: null as unknown as SharedValue<number>,
   footerFixed: false,
   footerOffset: null as unknown as SharedValue<number>,
-  headerHeight: 0,
+  headerHeight: null,
   headerHeightShared: null as unknown as SharedValue<number>,
   headerFixed: false,
   headerOffset: null as unknown as SharedValue<number>,
+  jsListGeneration: { current: 0 },
+  listGeneration: null as unknown as SharedValue<number>,
+  onJsListUnmount: () => {},
+  onListUnmount: () => {},
   progress: null,
   progressing: false,
   pullSearchHeightShared: null as unknown as SharedValue<number>,

package/src/ScrollViewHeader.tsx

@@ -56,20 +56,22 @@ export const ScrollViewHeader = ({ actionSize = 48, actionStyle, backAction, bac
   const translateStyle = useAnimatedStyle(() => {
     if (headerFixed) return { transform: [{ translateY: 0 }] }
     if (snapBackHeaderShared.value) return { transform: [{ translateY: headerOffset.value }] }
-    const effective = scrollPosition.value + headerHeight - pullSearchHeightShared.value
+    const effective = scrollPosition.value + (headerHeight ?? 0) - pullSearchHeightShared.value
     if (effective <= 0) return { transform: [{ translateY: 0 }] }
     return { transform: [{ translateY: -effective }] }
   }, [headerFixed, headerHeight])
   const blurStyle = useAnimatedStyle(() => {
     if (!headerHeight) return { height: 0 }
     if (headerFixed) return { height: headerHeight }
-    const translateY = snapBackHeaderShared.value ? headerOffset.value : -Math.max(0, scrollPosition.value + headerHeight - pullSearchHeightShared.value)
-    return { height: Math.max(headerHeight + translateY, top) }
+    const h = headerHeight ?? 0
+    const translateY = snapBackHeaderShared.value ? headerOffset.value : -Math.max(0, scrollPosition.value + h - pullSearchHeightShared.value)
+    return { height: Math.max(h + translateY, top) }
   }, [headerFixed, headerHeight, top])
   const progressStyle = useAnimatedStyle(() => {
-    if (headerFixed) return { top: headerHeight }
-    const slide = snapBackHeaderShared.value ? -headerOffset.value : Math.max(0, scrollPosition.value + headerHeight - pullSearchHeightShared.value)
-    return { top: Math.max(headerHeight - slide, top) }
+    const h = headerHeight ?? 0
+    if (headerFixed) return { top: h }
+    const slide = snapBackHeaderShared.value ? -headerOffset.value : Math.max(0, scrollPosition.value + h - pullSearchHeightShared.value)
+    return { top: Math.max(h - slide, top) }
   }, [headerFixed, headerHeight, top])
   const actionMargin = 4
   const contentMinHeight = actionSize + 2 * actionMargin
@@ -81,33 +83,34 @@ export const ScrollViewHeader = ({ actionSize = 48, actionStyle, backAction, bac
   return (
     <>
       <Animated.View pointerEvents='none' style={[styles.blur, blurStyle]}>
-        {headerHeight > 0 && <BlurView blur={blur} style={[styles.blurInner, { height: headerHeight }]} />}
+        {headerHeight !== null && headerHeight > 0 && <BlurView blur={blur} style={[styles.blurInner, { height: headerHeight }]} />}
       </Animated.View>
-      <Animated.View onLayout={handleLayout} pointerEvents='box-none' style={[headerHeight === 0 ? styles.headerInit : styles.header, translateStyle]}>
+      <Animated.View onLayout={handleLayout} pointerEvents='box-none' style={[headerHeight === null ? styles.headerInit : styles.header, translateStyle]}>
         <View style={[{ paddingTop: top }, style]}>
-          <View style={[styles.content, { minHeight: contentMinHeight }]}>
-            <View style={styles.side} />
-            <View style={styles.spacer} />
-            <View style={styles.side}>{children}</View>
-            {(centerContent || title || caption) && (
-              <View style={[StyleSheet.absoluteFill, styles.titleContainer]} pointerEvents={centerContent ? 'box-none' : 'none'}>
-                {centerContent ?? (
-                  <>
-                    {title && (
-                      <Text numberOfLines={1} style={[styles.title, { color: theme.colors.onSurface }]}>
-                        {title}
-                      </Text>
-                    )}
-                    {caption && (
-                      <Text numberOfLines={1} style={[styles.caption, { color: theme.colors.onSurfaceVariant }]}>
-                        {caption}
-                      </Text>
-                    )}
-                  </>
-                )}
-              </View>
-            )}
-          </View>
+          {children ?? (
+            <View style={[styles.content, { minHeight: contentMinHeight }]}>
+              <View style={styles.side} />
+              <View style={styles.spacer} />
+              {(centerContent || title || caption) && (
+                <View style={[StyleSheet.absoluteFill, styles.titleContainer]} pointerEvents={centerContent ? 'box-none' : 'none'}>
+                  {centerContent ?? (
+                    <>
+                      {title && (
+                        <Text numberOfLines={1} style={[styles.title, { color: theme.colors.onSurface }]}>
+                          {title}
+                        </Text>
+                      )}
+                      {caption && (
+                        <Text numberOfLines={1} style={[styles.caption, { color: theme.colors.onSurfaceVariant }]}>
+                          {caption}
+                        </Text>
+                      )}
+                    </>
+                  )}
+                </View>
+              )}
+            </View>
+          )}
         </View>
         {!blur && <View style={[styles.divider, { backgroundColor: theme.colors.outlineVariant }]} />}
       </Animated.View>