@rific/scroll-view 0.2.0 → 0.3.0

package/src/SectionList.tsx

@@ -1,16 +1,17 @@
-import { memo, type ReactNode, type RefObject, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
+import { memo, type ReactNode, type RefObject, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef } from 'react'
 import { Dimensions, type NativeScrollEvent, type NativeSyntheticEvent, SectionList as RNSectionList, type SectionListProps as RNSectionListProps, View } from 'react-native'
 import { Gesture, GestureDetector, type GestureType } from 'react-native-gesture-handler'
-import Animated, { createAnimatedComponent } from 'react-native-reanimated'
+import Animated, { runOnUI, useSharedValue } from 'react-native-reanimated'
 
 import { RefreshControl } from './internal/RefreshControl'
 import { type ChipProps, ScrollViewChip } from './internal/ScrollViewChip'
 import { useScrollHandler } from './internal/useScrollHandler'
 import { useScrollList } from './internal/useScrollList'
 import { useStickyHeaders } from './internal/useStickyHeaders'
+import { ScrollViewContext } from './ScrollViewContext'
 import { useScrollInit } from './useScrollInit'
 
-const AnimatedSectionList = createAnimatedComponent(RNSectionList) as unknown as typeof RNSectionList
+const AnimatedSectionList = Animated.createAnimatedComponent(RNSectionList) as unknown as typeof RNSectionList
 
 export type SectionListProps<ItemT, SectionT extends { data: ReadonlyArray<ItemT> } = { data: ReadonlyArray<ItemT> }> = Omit<RNSectionListProps<ItemT, SectionT>, 'horizontal'> & {
   chipProps?: ChipProps
@@ -34,6 +35,29 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
   const { stickySectionHeadersEnabled = true, renderSectionHeader, ...passThroughProps } = props as RNSectionListProps<ItemT, SectionT>
 
   const { chipHidden, chipStyle, containerStyle, contentInset, contentOffset, footerFixed, headerFixed, headerHeight } = 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 effect (not passive effect): 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])
 
   const usesCustomSticky = stickySectionHeadersEnabled && renderSectionHeader != null
   const { activeIndex, clipStyle, measureHeader, overlayStyle, resetPositions } = useStickyHeaders(headerFixed, usesCustomSticky)
@@ -70,6 +94,8 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
     }
   }, [usesCustomSticky, renderSectionHeader, sections, measureHeader])
 
+  useLayoutEffect(() => () => onListUnmount(), [onListUnmount])
+
   const scrollTo = useCallback((offset: number, animated: boolean) => {
     scrollView.current?.getScrollResponder()?.scrollTo({ y: offset, animated })
   }, [])
@@ -120,12 +146,7 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
 
   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
-    scrollTo(-contentInset.top + pullSearchHeight, true)
-  }, [contentInset.top, pullSearchHeight, scrollTo])
-
-  const handleScroll = useScrollHandler({ chipHidden, chipThreshold, footerFixed, headerFixed, onPullSearchZoneEnter: pullSearchHeight ? onPullSearchZoneEnter : undefined })
+  const handleScroll = useScrollHandler({ capturedGeneration, chipHidden, chipThreshold, footerFixed, headerFixed, listGeneration })
 
   const handleScrollToTop = useCallback(() => {
     const offset = pullSearchHeight ? -contentInset.top + pullSearchHeight : -contentInset.top
@@ -147,7 +168,7 @@ const SectionListInner = <ItemT, SectionT extends { data: ReadonlyArray<ItemT> }
   const content = (
     <View style={containerStyle}>
       <AnimatedSectionList
-        key={headerHeight > 0 ? 1 : 0}
+        key={headerHeight !== null && headerHeight > 0 ? 1 : 0}
         {...passThroughProps}
         contentContainerStyle={contentContainerStyle}
         contentInset={contentInset}

package/src/__mocks__/react-native-reanimated.ts

@@ -2,7 +2,34 @@ import React from 'react'
 
 const stub = ({ children }: { children?: React.ReactNode }) => children ?? null
 
-export const useSharedValue = (init: number) => ({ value: init })
+// Real Reanimated shared values persist their `.value` across re-renders (like useRef) — the
+// `init` argument is only honored on the first call. A naive `{ value: init }` per render would
+// silently discard mutations made during a previous render every time the owning component re-renders.
+export const useSharedValue = <T,>(init: T) => {
+  const ref = React.useRef<{ value: T } | null>(null)
+  if (!ref.current) ref.current = { value: init }
+  return ref.current
+}
+
+// Reanimated's useAnimatedRef returns a stable callable that also exposes `.current`, so
+// consumers can either pass it directly as a `ref` prop or read/assign `.current` imperatively.
+export const useAnimatedRef = <T,>() => {
+  const holder = React.useRef<((node: T | null) => void) & { current: T | null }>(undefined as unknown as ((node: T | null) => void) & { current: T | null })
+  if (!holder.current) {
+    let current: T | null = null
+    const fn = ((node: T | null) => {
+      current = node
+    }) as ((node: T | null) => void) & { current: T | null }
+    Object.defineProperty(fn, 'current', {
+      get: () => current,
+      set: (node: T | null) => {
+        current = node
+      }
+    })
+    holder.current = fn
+  }
+  return holder.current
+}
 export const useAnimatedStyle = (_factory: () => object) => ({})
 export const useAnimatedProps = (_factory: () => object) => ({})
 export const useAnimatedScrollHandler = (_handler: unknown) => jest.fn()
@@ -14,6 +41,10 @@ export const runOnJS =
   <T extends (...args: unknown[]) => unknown>(fn: T) =>
   (...args: Parameters<T>) =>
     fn(...args)
+export const runOnUI =
+  <T extends (...args: unknown[]) => unknown>(fn: T) =>
+  (...args: Parameters<T>) =>
+    fn(...args)
 
 export const createAnimatedComponent = (C: React.ComponentType) => C
 

package/src/__tests__/FlatList.test.tsx

@@ -1,11 +1,25 @@
 import { render } from '@testing-library/react'
 import React from 'react'
+import { FlatList as RNFlatList } from 'react-native'
 
 import { FlatList } from '../FlatList'
 import { ScrollViewProvider } from '../ScrollViewProvider'
 
 const wrapper = ({ children }: { children: React.ReactNode }) => <ScrollViewProvider>{children}</ScrollViewProvider>
 
+type MockFlatListProps = {
+  data?: unknown
+  keyExtractor?: (item: never, index: number) => string
+  numColumns?: number
+  renderItem?: (info: unknown) => React.ReactNode
+  [key: string]: unknown
+}
+
+const lastCallProps = () => {
+  const calls = (RNFlatList as unknown as jest.Mock).mock.calls
+  return calls[calls.length - 1]?.[0] as MockFlatListProps | undefined
+}
+
 describe('FlatList', () => {
   it('renders without crashing', () => {
     render(<FlatList data={[]} renderItem={() => null} />, { wrapper })
@@ -50,3 +64,72 @@ describe('FlatList', () => {
     render(<FlatList data={[]} renderItem={() => null} keyboardAware />, { wrapper })
   })
 })
+
+describe('FlatList numColumns row-chunking', () => {
+  beforeEach(() => (RNFlatList as unknown as jest.Mock).mockClear())
+
+  it('passes data through unchanged when numColumns is omitted', () => {
+    const data = ['a', 'b', 'c']
+    render(<FlatList data={data} renderItem={() => null} keyExtractor={(item) => item} />, { wrapper })
+    expect(lastCallProps()?.data).toBe(data)
+  })
+
+  it('passes data through unchanged when numColumns is 1', () => {
+    const data = ['a', 'b', 'c']
+    render(<FlatList data={data} renderItem={() => null} keyExtractor={(item) => item} numColumns={1} />, { wrapper })
+    expect(lastCallProps()?.data).toBe(data)
+  })
+
+  it('never forwards the numColumns prop itself to the underlying RNFlatList', () => {
+    render(<FlatList data={['a', 'b', 'c']} renderItem={() => null} keyExtractor={(item) => item} numColumns={3} />, { wrapper })
+    expect(lastCallProps()?.numColumns).toBeUndefined()
+  })
+
+  it('chunks data into rows of numColumns, with a partial last row', () => {
+    render(<FlatList data={['a', 'b', 'c', 'd', 'e']} renderItem={() => null} keyExtractor={(item) => item} numColumns={2} />, { wrapper })
+    expect(lastCallProps()?.data).toEqual([['a', 'b'], ['c', 'd'], ['e']])
+  })
+
+  it('row keyExtractor joins per-item keys with a colon', () => {
+    render(<FlatList data={['a', 'b', 'c', 'd']} renderItem={() => null} keyExtractor={(item) => item} numColumns={2} />, { wrapper })
+    const rowKeyExtractor = lastCallProps()?.keyExtractor
+    expect(rowKeyExtractor?.(['a', 'b'] as never, 0)).toBe('a:b')
+    expect(rowKeyExtractor?.(['c', 'd'] as never, 1)).toBe('c:d')
+  })
+
+  it('row renderItem renders every item in the row via the original renderItem', () => {
+    render(
+      <FlatList
+        data={['fig', 'kiwi', 'plum']}
+        renderItem={({ item }) => <>{item}</>}
+        keyExtractor={(item) => item}
+        numColumns={2}
+      />,
+      { wrapper }
+    )
+    const rowRenderItem = lastCallProps()?.renderItem
+    const { container } = render(rowRenderItem?.({ index: 0, item: ['fig', 'kiwi'], separators: {} as never }) as React.ReactElement)
+    expect(container.textContent).toContain('fig')
+    expect(container.textContent).toContain('kiwi')
+    expect(container.textContent).not.toContain('plum')
+  })
+
+  it('renderItem indexes items by their position across the whole flattened list, not just within the row', () => {
+    const indices: number[] = []
+    render(
+      <FlatList
+        data={['a', 'b', 'c', 'd', 'e']}
+        renderItem={({ index }) => {
+          indices.push(index)
+          return null
+        }}
+        keyExtractor={(item) => item}
+        numColumns={2}
+      />,
+      { wrapper }
+    )
+    const rowRenderItem = lastCallProps()?.renderItem
+    render(rowRenderItem?.({ index: 2, item: ['e'], separators: {} as never }) as React.ReactElement)
+    expect(indices).toEqual([4]) // row index 2 * numColumns 2 + column 0
+  })
+})

package/src/__tests__/useScrollHandlerJS.test.ts

@@ -0,0 +1,119 @@
+import { renderHook } from '@testing-library/react'
+import React from 'react'
+import type { SharedValue } from 'react-native-reanimated'
+
+import { useScrollHandlerJS } from '../internal/useScrollHandlerJS'
+import { ScrollViewContext, type ScrollViewContextType } from '../ScrollViewContext'
+
+const REMOUNT_RETRY_MAX_ATTEMPTS = 8
+
+const buildContextValue = (): ScrollViewContextType =>
+  ({
+    footerHeightShared: { value: 0 },
+    footerOffset: { value: 0 },
+    headerHeightShared: { value: 0 },
+    headerOffset: { value: 0 },
+    pullSearchHeightShared: { value: 0 },
+    scrollPosition: { value: 0 },
+    snapBackFooterShared: { value: false },
+    snapBackHeaderShared: { value: false }
+  }) as unknown as ScrollViewContextType
+
+const scrollEvent = (y: number) =>
+  ({
+    nativeEvent: {
+      contentOffset: { x: 0, y },
+      contentSize: { height: 1000, width: 0 },
+      layoutMeasurement: { height: 500, width: 0 }
+    }
+  }) as never
+
+const renderScrollHandlerJS = (overrides: Partial<Parameters<typeof useScrollHandlerJS>[0]> = {}) => {
+  const contextValue = buildContextValue()
+  const chipHidden = { value: 0 } as unknown as SharedValue<number>
+  const capturedGeneration = { current: 0 }
+  const jsListGeneration = { current: 0 }
+  const scrollTo = jest.fn()
+  const wrapper = ({ children }: { children: React.ReactNode }) => React.createElement(ScrollViewContext.Provider, { value: contextValue }, children)
+  const rendered = renderHook(
+    () =>
+      useScrollHandlerJS({
+        capturedGeneration,
+        chipHidden,
+        footerFixed: false,
+        headerFixed: false,
+        jsListGeneration,
+        scrollTo,
+        ...overrides
+      }),
+    { wrapper }
+  )
+  return { ...rendered, capturedGeneration, chipHidden, contextValue, jsListGeneration, scrollTo }
+}
+
+describe('useScrollHandlerJS generation guard', () => {
+  it('processes onScroll and updates scrollPosition/chipHidden when the generation matches', () => {
+    const { result, contextValue, chipHidden } = renderScrollHandlerJS({ chipThreshold: 100 })
+    result.current.onScroll(scrollEvent(50))
+    expect(contextValue.scrollPosition.value).toBe(50)
+    expect(chipHidden.value).toBe(1) // below threshold
+
+    result.current.onScroll(scrollEvent(150))
+    expect(contextValue.scrollPosition.value).toBe(150)
+    expect(chipHidden.value).toBe(0) // at/above threshold
+  })
+
+  it('drops onScroll from a zombie handler once jsListGeneration no longer matches its capturedGeneration', () => {
+    const { result, contextValue, capturedGeneration, jsListGeneration } = renderScrollHandlerJS()
+    result.current.onScroll(scrollEvent(10))
+    expect(contextValue.scrollPosition.value).toBe(10)
+
+    // Another list instance mounted/unmounted elsewhere and bumped the shared generation counter —
+    // this handler's own capturedGeneration (frozen at mount) is now stale.
+    jsListGeneration.current = 1
+    expect(capturedGeneration.current).toBe(0)
+
+    result.current.onScroll(scrollEvent(999))
+    expect(contextValue.scrollPosition.value).toBe(10) // unchanged — the stale event was ignored
+  })
+
+  it('lets a fresh instance keep working even while a stale sibling is guarded out', () => {
+    const jsListGeneration = { current: 1 }
+    const { result, contextValue } = renderScrollHandlerJS({ capturedGeneration: { current: 1 }, jsListGeneration })
+    result.current.onScroll(scrollEvent(42))
+    expect(contextValue.scrollPosition.value).toBe(42)
+  })
+})
+
+describe('useScrollHandlerJS remount retry', () => {
+  it('retries with a non-animated scrollTo until an onScroll event confirms the target position', () => {
+    const { result, scrollTo, contextValue } = renderScrollHandlerJS({ remountTarget: -40 })
+    result.current.onScroll(scrollEvent(0)) // native reports the wrong position
+    expect(scrollTo).toHaveBeenCalledWith(-40, false)
+    expect(contextValue.scrollPosition.value).toBe(0) // not yet treated as a real scroll position
+
+    scrollTo.mockClear()
+    result.current.onScroll(scrollEvent(-40)) // confirmed
+    expect(scrollTo).not.toHaveBeenCalled()
+    expect(contextValue.scrollPosition.value).toBe(-40) // now processed normally
+  })
+
+  it('gives up after REMOUNT_RETRY_MAX_ATTEMPTS and falls through to normal processing rather than blocking forever', () => {
+    const { result, scrollTo, contextValue } = renderScrollHandlerJS({ remountTarget: -40 })
+    for (let i = 0; i < REMOUNT_RETRY_MAX_ATTEMPTS; i += 1) result.current.onScroll(scrollEvent(0))
+    expect(scrollTo).toHaveBeenCalledTimes(REMOUNT_RETRY_MAX_ATTEMPTS)
+
+    scrollTo.mockClear()
+    result.current.onScroll(scrollEvent(0)) // one more, past the max — gives up
+    expect(scrollTo).not.toHaveBeenCalled()
+    expect(contextValue.scrollPosition.value).toBe(0) // accepted as-is instead of retrying forever
+  })
+
+  it('the generation guard takes precedence over an in-progress remount retry', () => {
+    const { result, scrollTo, contextValue, jsListGeneration } = renderScrollHandlerJS({ remountTarget: -40 })
+    jsListGeneration.current = 1 // stale before the remount retry ever gets a chance to run
+    result.current.onScroll(scrollEvent(0))
+    expect(scrollTo).not.toHaveBeenCalled()
+    expect(contextValue.scrollPosition.value).toBe(0) // untouched — onScroll bailed out immediately
+  })
+})

package/src/__tests__/useScrollInit.test.ts

@@ -0,0 +1,251 @@
+import { act, renderHook } from '@testing-library/react'
+import React from 'react'
+
+import { ScrollViewContext, type ScrollViewContextType } from '../ScrollViewContext'
+import { useScrollInit } from '../useScrollInit'
+
+const HEADER_HEIGHT = 80
+const PULL_SEARCH_HEIGHT = 40
+const REMOUNT_SYNC_MAX_ATTEMPTS = 8
+const SNAP_VERIFY_MAX_ATTEMPTS = 5
+const SNAP_VERIFY_INITIAL_DELAY_MS = 400
+const SNAP_VERIFY_RETRY_DELAY_MS = 150
+
+const buildContextValue = (headerHeight: number | null): ScrollViewContextType =>
+  ({
+    blur: true,
+    footerHeight: 0,
+    footerHeightShared: { value: 0 },
+    footerFixed: false,
+    footerOffset: { value: 0 },
+    headerHeight,
+    headerHeightShared: { value: headerHeight ?? 0 },
+    headerFixed: false,
+    headerOffset: { value: 0 },
+    listGeneration: { value: 0 },
+    onListUnmount: jest.fn(),
+    progress: null,
+    progressing: false,
+    pullSearchHeightShared: { value: 0 },
+    scrollHeight: 0,
+    scrollPosition: { value: 0 },
+    setFooterHeight: jest.fn(),
+    setHeaderHeight: jest.fn(),
+    setProgress: jest.fn(),
+    setProgressing: jest.fn(),
+    snapBackFooterShared: { value: false },
+    snapBackHeaderShared: { value: false },
+    tabBarHeight: 60
+  }) as unknown as ScrollViewContextType
+
+const renderInit = (headerHeight: number | null, pullSearchHeight?: number) => {
+  const contextValue = buildContextValue(headerHeight)
+  const scrollTo = jest.fn()
+  const wrapper = ({ children }: { children: React.ReactNode }) => React.createElement(ScrollViewContext.Provider, { value: contextValue }, children)
+  const rendered = renderHook(() => useScrollInit({ pullSearchHeight, scrollTo }), { wrapper })
+  return { ...rendered, contextValue, scrollTo }
+}
+
+describe('useScrollInit remount sync', () => {
+  it('true first mount (headerHeight null) skips remount-sync and starts ready', () => {
+    const { result, unmount } = renderInit(null)
+    expect(result.current.scrollReady).toBe(true)
+    expect(result.current.remountSyncTarget.value).toBeNull()
+    unmount()
+  })
+
+  it('remount (headerHeight already known at mount) hides the list and targets showY', () => {
+    const { result, scrollTo, unmount } = renderInit(HEADER_HEIGHT)
+    expect(result.current.scrollReady).toBe(false)
+    expect(result.current.remountSyncTarget.value).toBe(-HEADER_HEIGHT)
+    // Primes a corrective scrollTo immediately, rather than assuming native honored the initial contentOffset.
+    expect(scrollTo).toHaveBeenCalledWith(-HEADER_HEIGHT, false)
+    unmount()
+  })
+
+  it('remount with pullSearchHeight targets hideY directly (skips the 2-phase first-mount dance)', () => {
+    const { result, unmount } = renderInit(HEADER_HEIGHT, 40)
+    expect(result.current.remountSyncTarget.value).toBe(-HEADER_HEIGHT + 40)
+    unmount()
+  })
+
+  it('retries the corrective scrollTo when an onScroll event reports the wrong position, and stays hidden', () => {
+    const { result, scrollTo, unmount } = renderInit(HEADER_HEIGHT)
+    scrollTo.mockClear()
+    act(() => {
+      result.current.onRemountSyncRetry(0) // a spurious post-remount event reporting y=0
+    })
+    expect(scrollTo).toHaveBeenCalledWith(-HEADER_HEIGHT, false)
+    expect(result.current.scrollReady).toBe(false)
+    unmount()
+  })
+
+  it('reveals once a confirmed on-target event arrives', () => {
+    const { result, contextValue, unmount } = renderInit(HEADER_HEIGHT)
+    act(() => {
+      result.current.onRemountSynced(-HEADER_HEIGHT)
+    })
+    expect(result.current.scrollReady).toBe(true)
+    expect(contextValue.scrollPosition.value).toBe(-HEADER_HEIGHT)
+    unmount()
+  })
+
+  it('gives up and reveals anyway after exceeding the max retry attempts, rather than hiding forever', () => {
+    const { result, unmount } = renderInit(HEADER_HEIGHT)
+    act(() => {
+      for (let i = 0; i < REMOUNT_SYNC_MAX_ATTEMPTS + 2; i += 1) result.current.onRemountSyncRetry(0)
+    })
+    expect(result.current.scrollReady).toBe(true)
+    expect(result.current.remountSyncTarget.value).toBeNull()
+    unmount()
+  })
+})
+
+const dragEvent = (y: number) => ({ nativeEvent: { contentOffset: { y } } }) as never
+
+// A true first mount (not a remount): headerHeight starts null, then a rerender simulates the
+// header's async measurement landing, mirroring the real production flow. Using a non-null
+// headerHeight from the start (like the remount-sync tests above) would make useScrollInit treat
+// this as a remount and pull in unrelated machinery — the priming scrollTo, the 40-frame RAF
+// oscillation, and the REMOUNT_SYNC_FALLBACK_MS timer — none of which is relevant to the pull-search
+// snap logic under test here.
+const renderPullSearchInit = (pullSearchHeight: number) => {
+  const scrollTo = jest.fn()
+  let contextValue = buildContextValue(null)
+  const wrapper = ({ children }: { children: React.ReactNode }) => React.createElement(ScrollViewContext.Provider, { value: contextValue }, children)
+  const rendered = renderHook(() => useScrollInit({ pullSearchHeight, scrollTo }), { wrapper })
+  act(() => {
+    contextValue = buildContextValue(HEADER_HEIGHT)
+    rendered.rerender()
+  })
+  scrollTo.mockClear() // drop Effect A's insurance call and Effect B's showY->hideY push
+  return { ...rendered, contextValue, scrollTo }
+}
+
+describe('useScrollInit pull-search snap', () => {
+  const showY = -HEADER_HEIGHT
+  const hideY = -HEADER_HEIGHT + PULL_SEARCH_HEIGHT
+
+  beforeEach(() => jest.useFakeTimers())
+  afterEach(() => jest.useRealTimers())
+
+  it('opens toward showY when dragged down past half the pull-search height', () => {
+    const { result, scrollTo, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    expect(scrollTo).toHaveBeenCalledWith(showY, true)
+    unmount()
+  })
+
+  it('closes toward hideY when released without pulling past the half threshold', () => {
+    const { result, scrollTo, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(hideY - 10))
+    })
+    expect(scrollTo).toHaveBeenCalledWith(hideY, true)
+    unmount()
+  })
+
+  it('does nothing when the release lands outside the pull-search zone entirely', () => {
+    const { result, scrollTo, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(0))
+      result.current.handleScrollEndDrag(dragEvent(0))
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+    unmount()
+  })
+
+  it('keeps retrying (non-animated) until scrollPosition actually confirms the target, then stops', () => {
+    const { result, scrollTo, contextValue, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    contextValue.scrollPosition.value = hideY
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    expect(scrollTo).toHaveBeenCalledTimes(1) // the initial animated call
+
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_INITIAL_DELAY_MS)
+    })
+    expect(scrollTo).toHaveBeenLastCalledWith(showY, false) // first non-animated retry, still short of target
+
+    // The retry "lands" — simulate onScroll confirming the real position.
+    contextValue.scrollPosition.value = showY
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_RETRY_DELAY_MS)
+    })
+    scrollTo.mockClear()
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_RETRY_DELAY_MS * 5)
+    })
+    expect(scrollTo).not.toHaveBeenCalled() // verification stopped once confirmed
+    unmount()
+  })
+
+  it('gives up after exceeding the max retry attempts rather than retrying forever', () => {
+    const { result, scrollTo, contextValue, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    contextValue.scrollPosition.value = hideY // never reaches showY, no matter how many retries
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_INITIAL_DELAY_MS + SNAP_VERIFY_RETRY_DELAY_MS * (SNAP_VERIFY_MAX_ATTEMPTS + 1))
+    })
+    // 1 initial animated call + SNAP_VERIFY_MAX_ATTEMPTS non-animated retries, then it gives up.
+    expect(scrollTo).toHaveBeenCalledTimes(1 + SNAP_VERIFY_MAX_ATTEMPTS)
+
+    scrollTo.mockClear()
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_RETRY_DELAY_MS * 3)
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+    unmount()
+  })
+
+  it('cancels a pending verification when a new drag begins', () => {
+    const { result, scrollTo, contextValue, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    contextValue.scrollPosition.value = hideY
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    scrollTo.mockClear()
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(showY))
+    })
+    act(() => {
+      jest.advanceTimersByTime(SNAP_VERIFY_INITIAL_DELAY_MS * 3)
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+    unmount()
+  })
+
+  it('handleMomentumScrollEnd auto-closes when momentum alone carried it into the zone with no drag-committed target', () => {
+    const { result, scrollTo, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    act(() => {
+      result.current.handleMomentumScrollEnd(dragEvent(hideY - 10))
+    })
+    expect(scrollTo).toHaveBeenCalledWith(hideY, true)
+    unmount()
+  })
+
+  it('handleMomentumScrollEnd defers to an already-pending drag-committed target instead of double-correcting', () => {
+    const { result, scrollTo, contextValue, unmount } = renderPullSearchInit(PULL_SEARCH_HEIGHT)
+    contextValue.scrollPosition.value = hideY
+    act(() => {
+      result.current.handleScrollBeginDrag(dragEvent(hideY))
+      result.current.handleScrollEndDrag(dragEvent(showY))
+    })
+    scrollTo.mockClear()
+    act(() => {
+      result.current.handleMomentumScrollEnd(dragEvent(hideY - 10))
+    })
+    expect(scrollTo).not.toHaveBeenCalled()
+    unmount()
+  })
+})