@onekeyfe/react-native-pager-view 3.0.174 → 3.0.176

package/android/src/main/java/com/reactnativepagerview/CollapsiblePagerHost.kt

@@ -123,6 +123,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private val restoredRecyclerKeys = WeakHashMap<RecyclerView, String>()
   private val originalScrollerPadding = WeakHashMap<ScrollView, ScrollerPadding>()
   private val restoredScrollerKeys = WeakHashMap<ScrollView, String>()
+  private val deferredScrollerGeometry = WeakHashMap<ScrollView, Triple<Int, Int, Int>>()
   private val ownedScrollerKeys = WeakHashMap<NativeScrollerViewport, String>()
   private val ownedScrollerRestoreRequests = HashMap<String, Pair<WeakReference<NativeScrollerViewport>, Int?>>()
   private var foregroundRefreshIndicator: WeakReference<ImageView>? = null
@@ -204,6 +205,18 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private var observedNativeScrollerTreeObserver: ViewTreeObserver? = null
   private var observedPageRemoved = false
   private var attachmentGeneration = 0
+  internal var headerSettledAtTop = false
+    private set
+  var onHeaderSettledStateChanged: (() -> Unit)? = null
+  private var headerSettledOwner: WeakReference<View>? = null
+  private var headerSettledKey: String? = null
+  private var headerSettledGeneration = -1
+  private var headerSettledGeometry: String? = null
+  private var headerSettledSince = 0L
+  private var headerSettledWasBusy = true
+  private var headerSettledCheck: Runnable? = null
+  private var headerCommandOwner: WeakReference<View>? = null
+
   private val touchSlopPx = ViewConfiguration.get(context).scaledTouchSlop
   private val hostIdentity = System.identityHashCode(this)
   private var headerView: View? = null
@@ -228,6 +241,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     finishPagerTopIfSettled()
     // OneKey patch: a filtered short page can reduce the existing collapse range.
     setHeaderOffset(headerOffsetPx)
+    updateHeaderSettledState()
     if (offsetDiagEnabled() && offsetDiagNextDraw.isNotEmpty()) {
       val samples = offsetDiagNextDraw.entries.map { it.key to it.value }
       offsetDiagNextDraw.clear()
@@ -500,6 +514,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     alignedBodyKeys.clear()
     transitionAlignedViews.clear()
     deferredRecyclerGeometry.clear()
+    deferredScrollerGeometry.clear()
     displayBodyOverrides.clear()
     displayRecyclerAnchors.clear()
     ownedScrollerRestoreRequests.clear()
@@ -554,6 +569,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   internal fun onPagerScrollStateChanged(state: Int) {
+    updateHeaderSettledState(forceBusy = state != ViewPager2.SCROLL_STATE_IDLE)
     if (state == ViewPager2.SCROLL_STATE_DRAGGING || state == ViewPager2.SCROLL_STATE_SETTLING) {
       beginPageTransition()
     } else if (state == ViewPager2.SCROLL_STATE_IDLE && transitionHeaderOffsets != null) {
@@ -855,6 +871,14 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     if (phase == 0 && view === (observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller)) cancelPagerTop()
     if (phase != 0 && matchesPagerTop(view)) { finishPagerTopIfSettled(); return }
     val owner = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
+    val stateOwner = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
+    val stateKey = observedRecyclerKey ?: observedOwnedScrollerKey ?: observedNativeScrollerKey
+    if (view === stateOwner && stateKey == currentPageKey() && view.isAttachedToWindow && isAttachedToWindow && transitionHeaderOffsets == null && !syntheticPageRestore) {
+      updateHeaderSettledState()
+      if (phase == 1) headerCommandOwner = WeakReference(view)
+      else if (phase == 0 || phase == 2) headerCommandOwner = null
+      updateHeaderSettledState(forceBusy = phase != 2)
+    }
     if (!nativeSmoothHeaderScrollEnabled || view !== owner || transitionHeaderOffsets != null || syntheticPageRestore ||
       !isAttachedToWindow || !view.isAttachedToWindow) return
     val key = currentPageKey()
@@ -885,6 +909,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     pendingPageRestores.remove(key)
     ownedScrollerRestoreRequests.remove(key)
     if (view is RecyclerView) deferredRecyclerGeometry.remove(view)
+    if (view is ScrollView) deferredScrollerGeometry.remove(view)
     (view as? NativeScrollerViewport)?.host?.cancelPendingScrollRestore()
     suspendedBodyKeys.remove(key)
     alignedBodyKeys.remove(key)
@@ -963,6 +988,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     displayRecyclerAnchors.remove(key)
     recyclerReadingAnchors.remove(key)
     if (view is RecyclerView) deferredRecyclerGeometry.remove(view)
+    if (view is ScrollView) deferredScrollerGeometry.remove(view)
     pageOffsets[key] = 0
     val request = PagerTopRequest(view, key, selectedPage, attachmentGeneration, target, ++pagerTopToken)
     pagerTopRequest = request
@@ -1030,6 +1056,94 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     return (contentHeight.roundToInt() - height).coerceIn(0, headerHeightPx)
   }
 
+  internal fun headerStatePageKey(): String = currentPageKey()
+
+  private fun publishHeaderSettledState(settled: Boolean, identityChanged: Boolean = false) {
+    if (headerSettledAtTop == settled && !identityChanged) return
+    headerSettledAtTop = settled
+    log("header-settled-state page=$selectedPage generation=$attachmentGeneration settled=$settled")
+    onHeaderSettledStateChanged?.invoke()
+  }
+
+  private fun cancelHeaderSettledCheck() {
+    headerSettledCheck?.let(::removeCallbacks)
+    headerSettledCheck = null
+  }
+
+  private fun updateHeaderSettledState(forceBusy: Boolean = false) {
+    val owner = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
+    val ownerKey = observedRecyclerKey ?: observedOwnedScrollerKey ?: observedNativeScrollerKey
+    val valid = isAttachedToWindow && width > 0 && height > 0 && headerHeightPx > 0 &&
+      headerView?.isAttachedToWindow == true && owner != null && owner.isAttachedToWindow &&
+      owner.width > 0 && owner.height > 0 && ownerKey == currentPageKey() &&
+      selectedPage in 0 until adapter.itemCount && isDescendant(owner, adapter.pageAt(selectedPage))
+    val identityChanged = headerSettledOwner?.get() !== owner || headerSettledKey != currentPageKey() ||
+      headerSettledGeneration != attachmentGeneration
+    if (identityChanged) {
+      cancelHeaderSettledCheck()
+      headerCommandOwner = null
+      headerSettledOwner = owner?.let(::WeakReference)
+      headerSettledKey = currentPageKey()
+      headerSettledGeneration = attachmentGeneration
+      headerSettledGeometry = null
+      headerSettledWasBusy = true
+      publishHeaderSettledState(false, true)
+    }
+    if (!valid || owner == null || headerOffsetPx != 0) {
+      cancelHeaderSettledCheck()
+      headerSettledGeometry = null
+      headerSettledWasBusy = true
+      publishHeaderSettledState(false)
+      return
+    }
+    val windowPoint = IntArray(2)
+    owner.getLocationInWindow(windowPoint)
+    val recycler = owner as? RecyclerView
+    val manager = recycler?.layoutManager as? LinearLayoutManager
+    val first = manager?.findFirstVisibleItemPosition() ?: -1
+    val firstTop = manager?.let { layoutManager ->
+      layoutManager.findViewByPosition(first)?.let(layoutManager::getDecoratedTop)
+    } ?: 0
+    val content = (owner as? ViewGroup)?.getChildAt(0)
+    val geometry = listOf(headerOffsetPx, headerHeightPx, stickyHeaderHeightPx, width, height,
+      owner.width, owner.height, owner.paddingTop, owner.paddingBottom, owner.scrollY,
+      windowPoint[0], windowPoint[1], first, firstTop, recycler?.adapter?.itemCount ?: 0,
+      content?.height ?: 0, headerView?.height ?: 0).joinToString(":")
+    val busy = forceBusy || pager.isFakeDragging || pager.scrollState != ViewPager2.SCROLL_STATE_IDLE ||
+      transitionHeaderOffsets != null || syntheticPageRestore || pagerTopRequest != null ||
+      headerCommandOwner?.get() === owner ||
+      nestedScrollingParentHelper.nestedScrollAxes and ViewCompat.SCROLL_AXIS_VERTICAL != 0 ||
+      (recycler != null && (recycler.scrollState != RecyclerView.SCROLL_STATE_IDLE ||
+        recycler.isComputingLayout || recycler.layoutManager?.isSmoothScrolling == true)) ||
+      (owner is NativeScrollerViewport && owner.isReadingMotionActive())
+    val changed = geometry != headerSettledGeometry
+    val now = SystemClock.uptimeMillis()
+    if (changed || busy || headerSettledWasBusy) {
+      headerSettledSince = now
+      headerSettledGeometry = geometry
+      cancelHeaderSettledCheck()
+      publishHeaderSettledState(false)
+    }
+    headerSettledWasBusy = busy
+    if (!busy && now - headerSettledSince >= 150L) {
+      cancelHeaderSettledCheck()
+      publishHeaderSettledState(true)
+      return
+    }
+    if (headerSettledCheck == null) {
+      val weakOwner = WeakReference(owner)
+      val key = currentPageKey()
+      val generation = attachmentGeneration
+      val check = Runnable {
+        headerSettledCheck = null
+        if (generation == attachmentGeneration && key == currentPageKey() && weakOwner.get() ===
+          (observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller)) updateHeaderSettledState()
+      }
+      headerSettledCheck = check
+      postDelayed(check, 150L)
+    }
+  }
+
   private fun setHeaderOffset(offset: Int) {
     // val next = offset.coerceIn(0, headerHeightPx)
     val pending = nativeSmoothHeaderScrollEnabled && currentPageKey() in pendingPageRestores
@@ -1037,6 +1151,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     val next = offset.coerceIn(0, maximum)
     if (headerOffsetPx == next) return
     headerOffsetPx = next
+    updateHeaderSettledState(forceBusy = true)
     if (nativeSmoothHeaderScrollEnabled && transitionHeaderOffsets == null && !syntheticPageRestore && !pending) {
       pageHeaderOffsets[currentPageKey()] = next
     }
@@ -1195,9 +1310,11 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     val key = currentPageKey()
     val listener = object : RecyclerView.OnScrollListener() {
       override fun onScrollStateChanged(recyclerView: RecyclerView, newState: Int) {
+        if (observedRecyclerView === recyclerView) updateHeaderSettledState(forceBusy = newState != RecyclerView.SCROLL_STATE_IDLE)
         if (newState == RecyclerView.SCROLL_STATE_IDLE) finishPagerTopIfSettled()
       }
       override fun onScrolled(recyclerView: RecyclerView, dx: Int, dy: Int) {
+        if (observedRecyclerView === recyclerView && (dx != 0 || dy != 0)) updateHeaderSettledState(forceBusy = true)
         if (observedScrollListener !== this || observedRecyclerKey != key ||
           key != currentPageKey() || !isAttachedToWindow ||
           transitionHeaderOffsets != null || syntheticPageRestore || key in pendingPageRestores || key in alignedBodyKeys) {
@@ -1327,6 +1444,11 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun detachPrimaryScrollObserver(recordOffset: Boolean = true) {
+    cancelHeaderSettledCheck()
+    headerCommandOwner = null
+    headerSettledGeometry = null
+    headerSettledWasBusy = true
+    publishHeaderSettledState(false)
     detachOwnedScrollerObserver(recordOffset)
     detachRecyclerObserver(recordOffset)
     detachNativeScrollerObserver(recordOffset)
@@ -1599,6 +1721,17 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     original.appliedTopInset = topInset
 
     val key = pageKey(pageIndex)
+    val geometry = Triple(scroller.getChildAt(0)?.height ?: 0, scroller.height,
+      scroller.paddingTop + scroller.paddingBottom)
+    deferredScrollerGeometry[scroller]?.let { deferred ->
+      if (geometry != deferred) {
+        deferredScrollerGeometry.remove(scroller)
+        restoredScrollerKeys.remove(scroller)
+        if (nativeSmoothHeaderScrollEnabled && headerOffsetPx == headerHeightPx) {
+          displayBodyOverrides.remove(key)
+        }
+      }
+    }
     if (restoredScrollerKeys[scroller] != key) {
       restoredScrollerKeys[scroller] = key
       val restoreRequest = registerPageRestore(key, scroller, pageIndex)
@@ -1626,6 +1759,16 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
           return@post
         }
         if (scroller.scrollY != saved) scroller.scrollTo(scroller.scrollX, saved)
+        val unreachableReadingIntent = nativeSmoothHeaderScrollEnabled &&
+          headerOffsetPx == headerHeightPx && displayBodyOverrides.containsKey(key) &&
+          (pageOffsets[key] ?: 0) > scroller.scrollY && !scroller.canScrollVertically(1)
+        if (nativeSmoothHeaderScrollEnabled && (scroller.scrollY != saved || unreachableReadingIntent)) {
+          deferredScrollerGeometry[scroller] = Triple(scroller.getChildAt(0)?.height ?: 0,
+            scroller.height, scroller.paddingTop + scroller.paddingBottom)
+          offsetDiag("scrollview-restore-pending-saved=$saved-current=${scroller.scrollY}", scroller, key, pageIndex, restoreRequest)
+          return@post
+        }
+        deferredScrollerGeometry.remove(scroller)
         if (nativeSmoothHeaderScrollEnabled) clearPageRestoreForView(key, scroller, restoreRequest)
         else pendingPageRestores.remove(key)
         offsetDiag("scrollview-restore-after-saved=$saved", scroller, key, pageIndex, restoreRequest)
@@ -1695,6 +1838,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
 
   private fun restoreNativeScrollerInsets(scroller: ScrollView) {
     val original = originalScrollerPadding.remove(scroller) ?: return
+    deferredScrollerGeometry.remove(scroller)
     updateScrollerPaddingOwnership(scroller, original)
     restoredScrollerKeys.remove(scroller)?.let { clearPageRestoreForView(it, scroller) }
     if (scroller is ReactScrollView) {
@@ -2070,10 +2214,12 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   override fun onNestedScrollAccepted(child: View, target: View, axes: Int, type: Int) {
     if (type == ViewCompat.TYPE_TOUCH) pendingRefreshPull = null
     nestedScrollingParentHelper.onNestedScrollAccepted(child, target, axes, type)
+    updateHeaderSettledState(forceBusy = true)
     if (type == ViewCompat.TYPE_TOUCH) {
       val request = pageRestoreRequests[currentPageKey()]
       offsetDiag("touch-cancel-before", target, request = request)
       observedRecyclerView?.let { deferredRecyclerGeometry.remove(it) }
+      observedNativeScroller?.let { deferredScrollerGeometry.remove(it) }
       pageRestoreRequests.remove(currentPageKey())
       pendingPageRestores.remove(currentPageKey())
       ownedScrollerRestoreRequests.remove(currentPageKey())
@@ -2084,6 +2230,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   override fun onStopNestedScroll(target: View, type: Int) {
     if (pendingRefreshPull?.get() === target) pendingRefreshPull = null
     nestedScrollingParentHelper.onStopNestedScroll(target, type)
+    updateHeaderSettledState()
     onHeaderOffsetChanged?.invoke()
   }
 
@@ -2191,6 +2338,9 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   override fun onDetachedFromWindow() {
+    cancelHeaderSettledCheck()
+    headerCommandOwner = null
+    publishHeaderSettledState(false)
     pendingRefreshPull = null
     releaseRefreshForeground()
     attachmentGeneration += 1
@@ -2211,6 +2361,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     alignedBodyKeys.clear()
     transitionAlignedViews.clear()
     deferredRecyclerGeometry.clear()
+    deferredScrollerGeometry.clear()
     displayBodyOverrides.clear()
     displayRecyclerAnchors.clear()
     ownedScrollerRestoreRequests.clear()

package/android/src/main/java/com/reactnativepagerview/CollapsiblePagerViewManager.kt

@@ -94,6 +94,9 @@ class CollapsiblePagerViewManager : ViewGroupManager<CollapsiblePagerHost>(),
         ),
       )
     }
+    host.onHeaderSettledStateChanged = {
+      dispatchDiagnostics(reactContext, host, "header-settled-state")
+    }
     host.onHeaderOffsetChanged = {
       if (!host.pager.isFakeDragging && host.pager.scrollState == ViewPager2.SCROLL_STATE_IDLE) {
         dispatchDiagnostics(reactContext, host, "vertical-idle")
@@ -127,6 +130,8 @@ class CollapsiblePagerViewManager : ViewGroupManager<CollapsiblePagerHost>(),
         host.observedScrollableCount(),
         host.retainedPages,
         reason,
+        host.headerStatePageKey(),
+        host.headerSettledAtTop,
       ),
     )
   }

package/android/src/main/java/com/reactnativepagerview/event/CollapsibleStateChangedEvent.kt

@@ -14,6 +14,8 @@ class CollapsibleStateChangedEvent(
   private val observedScrollableCount: Int,
   private val retainedPages: String,
   private val reason: String,
+  private val pageKey: String,
+  private val headerSettledAtTop: Boolean,
 ) : Event<CollapsibleStateChangedEvent>(viewTag) {
   override fun getEventName() = EVENT_NAME
 
@@ -31,6 +33,8 @@ class CollapsibleStateChangedEvent(
     putInt("observedScrollableCount", observedScrollableCount)
     putString("retainedPages", retainedPages)
     putString("reason", reason)
+    putString("pageKey", pageKey)
+    putBoolean("headerSettledAtTop", headerSettledAtTop)
   }
 
   companion object {

package/docs/SPEC.md

@@ -38,6 +38,12 @@ Late callbacks cannot revive cancelled restoration or erase a newer request.
 Observers and commands must match page key, view identity and generation.
 Removed or recycled owners cannot apply callbacks to another page; recycling
 resets owned memory.
+The Web backend shares C and stores per-page B separately from absolute DOM
+scrollTop. Selection aligns to C while expanded and C + B while fully collapsed;
+programmatic alignment and geometry-only scrollend events MUST NOT erase the
+suspended reading position. Real vertical input or a valid List command takes
+over the current display. PageTop/StickyTop clear only the current B.
+
 Legacy mode and pagers without a collapsible header retain their existing
 behavior. Vertical scrolling, refresh, snapping and repeated-current-tab behavior
 are unchanged. This state belongs to native UI instances, with no new React prop
@@ -717,3 +723,12 @@ cases additionally verified recorded refresh, header, restoration and gesture
 paths; they do not establish every possible sequence or runtime acceptance of a
 newly installed module release. Physical-device feel and semantic accessibility
 activation remain unverified.
+
+
+### Native Header stability snapshot
+
+`onCollapsibleStateChanged` retains its existing diagnostic fields and reasons and adds native-only `pageKey: string` and `headerSettledAtTop: boolean`. The key is the actual mounted React child key, not an application tab identifier. Unattached, unknown, replaced or transitioning owners MUST report false. A mounted current owner emits an initial identity snapshot without requiring a first user scroll.
+
+The Header is settled only when C is at its expanded top, the current attached view/key/index/generation still matches, and there is no actual drag, deceleration, scrolling command or horizontal transition. Offset/inset/content/header geometry MUST remain stable for 150ms before true is emitted. Motion or geometry changes revoke true promptly. Deferred reading memory alone MUST NOT be treated as active motion. Pull-to-refresh may settle at a normalized negative offset after drag, bounce and inset geometry stop; network refreshing alone is not a motion gate. Checks stop for collapsed, detached and recycled owners; delayed callbacks revalidate their captured identity. State changes are deduplicated; identity changes still publish an unknown/false snapshot.
+
+The native Home Spotlight adapter consumes this snapshot in the main UI runtime and keeps unknown states paused. It MUST use the mounted page-key mapping and reject old page/source callbacks. Native snapshots already include the 150ms stabilization delay: consumers MUST NOT add another such delay. Legacy Tabs keep their existing normalized-offset and debounce behavior. Anchor measurement, guide qualification and the existing display delay remain independent gates.

package/ios/RNCCollapsiblePagerViewComponentView.mm

@@ -1517,6 +1517,16 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 #endif
   NSInteger _transitionSourceIndex;
   BOOL _syntheticPageRestore;
+  BOOL _headerSettledAtTop;
+  __weak UIScrollView *_headerSettledOwner;
+  NSString *_headerSettledKey;
+  NSUInteger _headerSettledGeneration;
+  NSString *_headerSettledGeometry;
+  CFTimeInterval _headerSettledSince;
+  BOOL _headerSettledWasBusy;
+  NSTimer *_headerSettledTimer;
+  __weak UIScrollView *_headerCommandOwner;
+
   BOOL _finishingPageStateTransition;
   NSMutableSet<NSString *> *_pendingPageRestoreKeys;
   __weak UIScrollView *_sharedHeaderScrollView;
@@ -1677,6 +1687,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 {
   [super didMoveToWindow];
   [self updateSharedHeaderPressCancellationGesture];
+  [self updateHeaderSettledStateForceBusy:NO];
   for (UIScrollView *scrollView in _originalInsets.keyEnumerator) {
     [self updateNativeScrollerViewport:scrollView stickyHeight:self.window == nil ? 0 : _stickyHeaderHeight];
   }
@@ -1703,6 +1714,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)dealloc
 {
+  [self cancelHeaderSettledCheck];
   [[NSNotificationCenter defaultCenter] removeObserver:self name:@"OneKeyNativeListScrollCommandAccepted" object:nil];
   for (UIScrollView *scrollView in _originalInsets.keyEnumerator) {
     [self updateNativeScrollerViewport:scrollView stickyHeight:0];
@@ -2363,6 +2375,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     }
   }
   [self layoutSharedHeaders];
+  [self updateHeaderSettledStateForceBusy:NO];
   dispatch_async(dispatch_get_main_queue(), ^{
     if (!self->_isBeingRecycled) {
       [self prepareAdjacentPageInsets];
@@ -2373,6 +2386,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)prepareForRecycle
 {
+  [self cancelHeaderSettledCheck];
+  [self publishHeaderSettledAtTop:NO identityChanged:NO];
   _isBeingRecycled = YES;
   _generation++;
   [_mountingRemovedScrollViews removeAllObjects];
@@ -2896,10 +2911,16 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   _currentLogicalOffset = candidate.contentOffset.y + candidate.contentInset.top;
   [self attachSharedHeadersToScrollView:candidate];
   [self updateSharedHeaderPressCancellationGesture];
+  [self updateHeaderSettledStateForceBusy:NO];
 }
 
 - (void)detachScrollObserver
 {
+  [self cancelHeaderSettledCheck];
+  _headerCommandOwner = nil;
+  _headerSettledGeometry = nil;
+  _headerSettledWasBusy = YES;
+  [self publishHeaderSettledAtTop:NO identityChanged:NO];
   [self cancelPagerTop];
   UIScrollView *scrollView = _observedScrollView;
   if (scrollView != nil) {
@@ -3117,6 +3138,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)observedListPanChanged:(UIPanGestureRecognizer *)recognizer
 {
+  if (recognizer == _observedScrollView.panGestureRecognizer) {
+    [self updateHeaderSettledStateForceBusy:
+      recognizer.state == UIGestureRecognizerStateBegan || recognizer.state == UIGestureRecognizerStateChanged];
+  }
   if (!_nativeSmoothHeaderScrollEnabled || recognizer != _observedScrollView.panGestureRecognizer) {
     return;
   }
@@ -3454,6 +3479,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       _observedPageIndex != _currentIndex || _observedPageGeneration != _generation ||
       _transitioning || _isPagerDragging || _transitionPageOffsets != nil || _syntheticPageRestore) return;
   NSInteger phase = [notification.userInfo[@"phase"] integerValue];
+  [self updateHeaderSettledStateForceBusy:NO];
+  if (phase == 1) _headerCommandOwner = scrollView;
+  else if (phase == 0 || phase == 2) _headerCommandOwner = nil;
+  [self updateHeaderSettledStateForceBusy:phase != 2];
   if ([self matchesPagerTop:scrollView]) {
     if (phase == 0) [self cancelPagerTop];
     else return;
@@ -3569,6 +3598,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     return;
   }
   if (context == RNCCollapsiblePagerContentOffsetContext && object == _observedScrollView) {
+    if (![change[NSKeyValueChangeOldKey] isEqual:change[NSKeyValueChangeNewKey]]) {
+      [self updateHeaderSettledStateForceBusy:YES];
+    }
     if ((_nativeSmoothHeaderScrollEnabled || [_alignedBodyKeys containsObject:_observedPageKey]) &&
         (_observedPageGeneration != _generation || _observedPageKey == nil ||
          _observedPageIndex != _currentIndex || ![_observedPageKey isEqualToString:self.currentPageKey] ||
@@ -3668,6 +3700,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)applyHeaderOffset
 {
+  [self updateHeaderSettledStateForceBusy:NO];
   BOOL attachedToList = _nativeSmoothHeaderScrollEnabled &&
     _sharedHeaderScrollView != nil && !_sharedHeadersLiftedForPagerTransition;
   if (attachedToList) {
@@ -3884,6 +3917,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)scrollViewWillBeginDragging:(UIScrollView *)scrollView
 {
+  [self updateHeaderSettledStateForceBusy:YES];
   [self offsetDiag:@"pager-drag-begin" page:_currentIndex scroll:_observedScrollView];
   if (_nativeSmoothHeaderScrollEnabled && scrollView == _pagerScrollView) {
     [_contentPressCancellationGesture cancelPressForPan:scrollView.panGestureRecognizer];
@@ -4081,6 +4115,93 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (emitter) emitter->onPageSelected({.position = (double)position});
 }
 
+- (void)publishHeaderSettledAtTop:(BOOL)settled identityChanged:(BOOL)identityChanged
+{
+  if (_headerSettledAtTop == settled && !identityChanged) return;
+  _headerSettledAtTop = settled;
+  RNCCollapsiblePagerLog([NSString stringWithFormat:@"header-settled-state page=%ld generation=%lu settled=%d",
+    (long)_currentIndex, (unsigned long)_generation, settled]);
+  [self emitDiagnostics:@"header-settled-state"];
+}
+
+- (void)cancelHeaderSettledCheck
+{
+  [_headerSettledTimer invalidate];
+  _headerSettledTimer = nil;
+}
+
+- (void)updateHeaderSettledStateForceBusy:(BOOL)forceBusy
+{
+  UIScrollView *owner = _observedScrollView;
+  NSString *key = self.currentPageKey;
+  BOOL valid = !_isBeingRecycled && self.window != nil && _headerView.window == self.window &&
+    _headerHeight > 0 && owner.window == self.window && owner != nil &&
+    CGRectGetWidth(owner.bounds) > 0 && CGRectGetHeight(owner.bounds) > 0 &&
+    _observedPageGeneration == _generation && _observedPageIndex == _currentIndex &&
+    _currentIndex >= 0 && _currentIndex < _pageControllers.count &&
+    [_observedPageKey isEqualToString:key] && [owner isDescendantOfView:_pageControllers[_currentIndex].view];
+  BOOL identityChanged = _headerSettledOwner != owner || ![_headerSettledKey isEqualToString:key] ||
+    _headerSettledGeneration != _generation;
+  if (identityChanged) {
+    [self cancelHeaderSettledCheck];
+    _headerCommandOwner = nil;
+    _headerSettledOwner = owner;
+    _headerSettledKey = [key copy];
+    _headerSettledGeneration = _generation;
+    _headerSettledGeometry = nil;
+    _headerSettledWasBusy = YES;
+    [self publishHeaderSettledAtTop:NO identityChanged:YES];
+  }
+  if (!valid || fabs(_headerOffset) > 0.5) {
+    [self cancelHeaderSettledCheck];
+    _headerSettledGeometry = nil;
+    _headerSettledWasBusy = YES;
+    [self publishHeaderSettledAtTop:NO identityChanged:NO];
+    return;
+  }
+  CGRect headerRect = [_headerView convertRect:_headerView.bounds toView:self.window];
+  CGRect ownerRect = [owner convertRect:owner.bounds toView:self.window];
+  UIEdgeInsets inset = owner.contentInset;
+  UIEdgeInsets adjustedInset = owner.adjustedContentInset;
+  NSString *geometry = [NSString stringWithFormat:
+    @"%.4f:%ld:%ld:%@:%@:%@:%@:%@:%@:%@",
+    _headerOffset, (long)_headerHeight, (long)_stickyHeaderHeight,
+    NSStringFromCGPoint(owner.contentOffset), NSStringFromCGSize(owner.contentSize),
+    NSStringFromCGRect(owner.bounds), NSStringFromUIEdgeInsets(inset),
+    NSStringFromUIEdgeInsets(adjustedInset), NSStringFromCGRect(headerRect), NSStringFromCGRect(ownerRect)];
+  UIGestureRecognizerState panState = owner.panGestureRecognizer.state;
+  BOOL busy = forceBusy || _transitioning || _isPagerDragging || _transitionPageOffsets != nil ||
+    _syntheticPageRestore || _pagerTopPageKey != nil || _headerCommandOwner == owner ||
+    owner.isDragging || owner.isDecelerating || owner.isTracking ||
+    panState == UIGestureRecognizerStateBegan || panState == UIGestureRecognizerStateChanged;
+  CFTimeInterval now = CACurrentMediaTime();
+  if (![geometry isEqualToString:_headerSettledGeometry] || busy || _headerSettledWasBusy) {
+    _headerSettledSince = now;
+    _headerSettledGeometry = geometry;
+    [self cancelHeaderSettledCheck];
+    [self publishHeaderSettledAtTop:NO identityChanged:NO];
+  }
+  _headerSettledWasBusy = busy;
+  if (!busy && now - _headerSettledSince >= 0.15) {
+    [self cancelHeaderSettledCheck];
+    [self publishHeaderSettledAtTop:YES identityChanged:NO];
+    return;
+  }
+  if (_headerSettledTimer == nil) {
+    __weak RNCCollapsiblePagerViewComponentView *weakSelf = self;
+    __weak UIScrollView *weakOwner = owner;
+    NSUInteger generation = _generation;
+    _headerSettledTimer = [NSTimer scheduledTimerWithTimeInterval:0.15 repeats:NO block:^(NSTimer *timer) {
+      RNCCollapsiblePagerViewComponentView *strongSelf = weakSelf;
+      if (strongSelf == nil) return;
+      if (strongSelf->_headerSettledTimer != timer) return;
+      strongSelf->_headerSettledTimer = nil;
+      if (strongSelf->_generation == generation && [strongSelf.currentPageKey isEqualToString:key] &&
+          strongSelf->_observedScrollView == weakOwner) [strongSelf updateHeaderSettledStateForceBusy:NO];
+    }];
+  }
+}
+
 - (void)emitDiagnostics:(NSString *)reason
 {
   const auto emitter = [self eventEmitter];
@@ -4096,7 +4217,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     .attachedPageCount = (int)attached,
     .observedScrollableCount = (int)_originalInsets.count,
     .retainedPages = std::string(_retainedPages.UTF8String ?: "[]"),
-    .reason = std::string(reason.UTF8String ?: "unknown")
+    .reason = std::string(reason.UTF8String ?: "unknown"),
+    .pageKey = std::string(self.currentPageKey.UTF8String ?: ""),
+    .headerSettledAtTop = (bool)_headerSettledAtTop
   });
 }
 

package/ios/tests/RNCCollapsiblePagerFirstFrameTests.mm

@@ -19,6 +19,7 @@ using namespace facebook::react;
 - (void)updatePageStateTransitionProgress:(CGFloat)progress;
 - (void)finishPageStateTransition;
 - (void)scrollToTop:(NSInteger)target animated:(BOOL)animated;
+- (void)updateHeaderSettledStateForceBusy:(BOOL)forceBusy;
 - (void)preparePageForHorizontalTransitionAtIndex:(NSInteger)index;
 - (void)applyInsetsToScrollView:(UIScrollView *)scrollView pageIndex:(NSInteger)index restore:(BOOL)restore;
 @end
@@ -33,6 +34,44 @@ using namespace facebook::react;
 
 @implementation RNCCollapsiblePagerFirstFrameTests
 
+- (void)testHeaderSettledAtTopRequiresCurrentQuietOwnerAndCancelsDetachedTimer
+{
+  RNCCollapsiblePagerViewComponentView *pager = [self pagerWithPageCount:1];
+  // The fixture mounts page 0 directly; UIKit must not select it again.
+  [pager setValue:@YES forKey:@"hasAppliedInitialPage"];
+  UIView *header = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 120)];
+  [pager addSubview:header];
+  [pager setValue:header forKey:@"headerView"];
+  RNCNativeScrollerComponentView *scroller = [self addScrollerToPager:pager atIndex:0];
+  [pager.window layoutIfNeeded];
+  [pager layoutIfNeeded];
+  XCTestExpectation *initialLayout = [self expectationWithDescription:@"Initial observer attachment drained"];
+  dispatch_async(dispatch_get_main_queue(), ^{ [initialLayout fulfill]; });
+  [self waitForExpectations:@[initialLayout] timeout:1];
+  [pager detachScrollObserver];
+  [pager attachScrollObserverForCurrentPage];
+  [pager updateHeaderSettledStateForceBusy:NO];
+  XCTAssertFalse([[pager valueForKey:@"headerSettledAtTop"] boolValue]);
+  [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.25]];
+  XCTAssertTrue([[pager valueForKey:@"headerSettledAtTop"] boolValue]);
+
+  [scroller scrollTo:0 y:200 - scroller.scrollView.contentInset.top animated:NO];
+  XCTAssertFalse([[pager valueForKey:@"headerSettledAtTop"] boolValue]);
+  [scroller scrollTo:0 y:-scroller.scrollView.adjustedContentInset.top animated:NO];
+  [pager updateHeaderSettledStateForceBusy:NO];
+  XCTAssertFalse([[pager valueForKey:@"headerSettledAtTop"] boolValue]);
+  [pager detachScrollObserver];
+  [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.25]];
+  XCTAssertFalse([[pager valueForKey:@"headerSettledAtTop"] boolValue]);
+  XCTAssertNil([pager valueForKey:@"headerSettledTimer"]);
+
+  [pager attachScrollObserverForCurrentPage];
+  [pager updateHeaderSettledStateForceBusy:NO];
+  XCTAssertFalse([[pager valueForKey:@"headerSettledAtTop"] boolValue]);
+  [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.25]];
+  XCTAssertTrue([[pager valueForKey:@"headerSettledAtTop"] boolValue]);
+}
+
 - (void)testReachableTopCommandBeforeLayoutMustNotReplayPendingPagePosition
 {
   for (NSNumber *command in @[@0, @1, @2]) {

package/lib/module/CollapsiblePagerView.web.js

@@ -44,6 +44,8 @@ export class CollapsiblePagerView extends React.PureComponent {
   pageOffsets = new Map();
   pageHosts = new Map();
   sharedHeaderOffset = 0;
+  selectionRestoreToken = 0;
+  bodyAlignment = null;
   scrollEnabled = this.props.scrollEnabled ?? true;
   lastMountSignature = null;
   configureFrame = null;
@@ -71,6 +73,7 @@ export class CollapsiblePagerView extends React.PureComponent {
     const pageCount = this.pages().length;
     const selectedPage = clampedPageIndex(this.state.selectedPage, pageCount);
     if (selectedPage !== this.state.selectedPage) {
+      this.selectionRestoreToken += 1;
       this.cancelPendingTopFrame();
       this.finishPageTransition();
       this.setState({
@@ -83,6 +86,7 @@ export class CollapsiblePagerView extends React.PureComponent {
     this.notifyMountedPagesChanged();
   }
   componentWillUnmount() {
+    this.selectionRestoreToken += 1;
     this.cancelPendingTopFrame();
     this.savePageOffset(this.state.selectedPage);
     if (this.configureFrame !== null) {
@@ -116,16 +120,32 @@ export class CollapsiblePagerView extends React.PureComponent {
     if (this.pageScrollElement(this.state.selectedPage) === pending.element && this.pages().map(pageKey)[this.state.selectedPage] === pending.key) this.savePageOffset(this.state.selectedPage);
   };
   onQueuedTopWheel = event => {
-    if (event.deltaY !== 0) this.cancelPendingTopFrame();
+    if (event.deltaY !== 0) this.takeOverVerticalScroll();
+  };
+  onScrollbarPointerDown = event => {
+    const element = this.pageScrollElement(this.state.selectedPage);
+    if (!element || event.target !== element || event.button !== 0) return;
+    const rect = element.getBoundingClientRect();
+    const computed = element.ownerDocument.defaultView?.getComputedStyle(element);
+    const borderLeft = Number.parseFloat(computed?.borderLeftWidth ?? "0") || 0;
+    const borderRight = Number.parseFloat(computed?.borderRightWidth ?? "0") || 0;
+    const clientStart = rect.left + element.clientLeft;
+    const clientEnd = clientStart + element.clientWidth;
+    const leftGutter = clientStart - (rect.left + borderLeft);
+    const rightGutter = rect.right - borderRight - clientEnd;
+    const inVerticalTrack = event.clientY >= rect.top + element.clientTop && event.clientY < rect.top + element.clientTop + element.clientHeight;
+    const inGutter = leftGutter > 0 && event.clientX >= rect.left + borderLeft && event.clientX < clientStart || rightGutter > 0 && event.clientX >= clientEnd && event.clientX < rect.right - borderRight;
+    if (inVerticalTrack && inGutter) this.takeOverVerticalScroll();
   };
   onQueuedTopKey = event => {
-    if (["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " "].includes(event.key)) this.cancelPendingTopFrame();
+    if (["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " "].includes(event.key)) this.takeOverVerticalScroll();
   };
   scrollCurrentPageToTop(offset, animated) {
     if (this.horizontalTouch || this.transitionTimer !== null) return;
     const element = this.pageScrollElement(this.state.selectedPage);
     const key = this.pages().map(pageKey)[this.state.selectedPage];
     if (!element?.isConnected || !key) return;
+    this.selectionRestoreToken += 1;
     this.cancelPendingTopFrame();
     const EventConstructor = element.ownerDocument.defaultView?.Event;
     if (EventConstructor) element.dispatchEvent(new EventConstructor("ok-collapsible-pager-cancel-scroll-command"));
@@ -138,8 +158,12 @@ export class CollapsiblePagerView extends React.PureComponent {
       if (this.pendingTopFrame?.frame !== frame) return;
       this.pendingTopFrame = null;
       if (!element.isConnected || this.horizontalTouch || this.transitionTimer !== null || this.pageScrollElement(this.state.selectedPage) !== element || this.pages().map(pageKey)[this.state.selectedPage] !== key) return;
-      this.pageOffsets.set(key, offset);
+      this.pageOffsets.set(key, 0);
       this.sharedHeaderOffset = offset;
+      this.bodyAlignment = {
+        element,
+        key
+      };
       element.scrollTo({
         top: offset,
         behavior: animated ? "smooth" : "instant"
@@ -218,8 +242,9 @@ export class CollapsiblePagerView extends React.PureComponent {
     const configured = this.configuredScrollElement;
     if (!configured) return;
     this.cancelPendingTopFrame();
-    configured.element.removeEventListener("ok-native-list-scroll-command-accepted", this.cancelPendingTopFrame);
+    configured.element.removeEventListener("ok-native-list-scroll-command-accepted", this.onListScrollCommandAccepted);
     configured.element.removeEventListener("wheel", this.onQueuedTopWheel);
+    configured.element.removeEventListener("pointerdown", this.onScrollbarPointerDown);
     configured.element.removeEventListener("keydown", this.onQueuedTopKey);
     configured.element.removeEventListener("scrollend", this.onVerticalScrollSettled);
     const style = timelineStyle(configured.element);
@@ -234,6 +259,7 @@ export class CollapsiblePagerView extends React.PureComponent {
     configured.element.removeAttribute("data-collapsible-pager-active");
     this.notifyInsetsChanged(configured.element);
     this.configuredScrollElement = null;
+    if (this.bodyAlignment?.element === configured.element) this.bodyAlignment = null;
   }
   configureActiveScrollElement = () => {
     this.configureFrame = null;
@@ -269,8 +295,9 @@ export class CollapsiblePagerView extends React.PureComponent {
         pagerStickyInset: style.getPropertyValue(PAGER_STICKY_INSET)
       };
       element.addEventListener("scrollend", this.onVerticalScrollSettled);
-      element.addEventListener("ok-native-list-scroll-command-accepted", this.cancelPendingTopFrame);
+      element.addEventListener("ok-native-list-scroll-command-accepted", this.onListScrollCommandAccepted);
       element.addEventListener("wheel", this.onQueuedTopWheel);
+      element.addEventListener("pointerdown", this.onScrollbarPointerDown);
       element.addEventListener("keydown", this.onQueuedTopKey);
     }
     const style = timelineStyle(element);
@@ -299,8 +326,18 @@ export class CollapsiblePagerView extends React.PureComponent {
       this.configureActiveScrollElement();
     }
   }
-  onVerticalScrollSettled = () => {
-    if (this.pendingTopFrame) return;
+  takeOverVerticalScroll = () => {
+    this.selectionRestoreToken += 1;
+    this.bodyAlignment = null;
+    this.cancelPendingTopFrame();
+    this.savePageOffset(this.state.selectedPage);
+  };
+  onListScrollCommandAccepted = event => {
+    if (event.target !== this.pageScrollElement(this.state.selectedPage)) return;
+    this.takeOverVerticalScroll();
+  };
+  onVerticalScrollSettled = event => {
+    if (this.pendingTopFrame || event && event.target !== this.pageScrollElement(this.state.selectedPage)) return;
     this.savePageOffset(this.state.selectedPage);
     this.emitDiagnostics("scroll-settled");
   };
@@ -308,15 +345,24 @@ export class CollapsiblePagerView extends React.PureComponent {
     const key = this.pages().map(pageKey)[index];
     const scrollElement = this.pageScrollElement(index);
     if (key && scrollElement) {
-      this.pageOffsets.set(key, scrollElement.scrollTop);
-      this.sharedHeaderOffset = Math.min(Math.max(scrollElement.scrollTop, 0), Math.max(0, this.props.headerHeight));
+      if (this.bodyAlignment?.key === key && this.bodyAlignment.element === scrollElement) return;
+      const D = Math.max(0, this.props.headerHeight);
+      this.pageOffsets.set(key, Math.max(0, scrollElement.scrollTop - D));
+      this.sharedHeaderOffset = Math.min(Math.max(scrollElement.scrollTop, 0), D);
     }
   }
   restorePageOffset(index) {
     const key = this.pages().map(pageKey)[index];
     const scrollElement = this.pageScrollElement(index);
     if (!key || !scrollElement) return;
-    scrollElement.scrollTop = Math.max(this.pageOffsets.get(key) ?? this.sharedHeaderOffset, this.sharedHeaderOffset);
+    const D = Math.max(0, this.props.headerHeight);
+    const C = Math.min(Math.max(0, this.sharedHeaderOffset), D);
+    const expectedQ = C + (C === D ? this.pageOffsets.get(key) ?? 0 : 0);
+    this.bodyAlignment = {
+      element: scrollElement,
+      key
+    };
+    scrollElement.scrollTop = expectedQ;
   }
   selectPage(selectedPage, animated) {
     const pages = this.pages();
@@ -324,6 +370,8 @@ export class CollapsiblePagerView extends React.PureComponent {
     if (position === null || position < 0 || position >= pages.length || position === this.state.selectedPage) {
       return;
     }
+    const selectionToken = ++this.selectionRestoreToken;
+    const expectedKey = this.pages().map(pageKey)[position];
     this.cancelPendingTopFrame();
     this.savePageOffset(this.state.selectedPage);
     if (animated) this.beginPageTransition();else this.finishPageTransition();
@@ -333,6 +381,7 @@ export class CollapsiblePagerView extends React.PureComponent {
     }, () => {
       this.scheduleScrollConfiguration();
       const restore = () => {
+        if (this.selectionRestoreToken !== selectionToken || this.state.selectedPage !== position || this.pages().map(pageKey)[position] !== expectedKey || !this.pageScrollElement(position)?.isConnected) return;
         this.configureActiveScrollElement();
         this.restorePageOffset(position);
       };
@@ -392,7 +441,7 @@ export class CollapsiblePagerView extends React.PureComponent {
     if (!touch) return;
     const deltaX = touch.pageX - this.touchStartX;
     const deltaY = touch.pageY - (this.touchStartY ?? touch.pageY);
-    if (Math.abs(deltaY) >= 8 && Math.abs(deltaY) > Math.abs(deltaX)) this.cancelPendingTopFrame();
+    if (Math.abs(deltaY) >= 8 && Math.abs(deltaY) > Math.abs(deltaX)) this.takeOverVerticalScroll();
     if (Math.abs(deltaX) >= 8 && Math.abs(deltaX) > Math.abs(deltaY)) {
       this.cancelPendingTopFrame();
       this.horizontalTouch = true;

package/lib/module/CollapsiblePagerViewNativeComponent.ts

@@ -35,6 +35,8 @@ export type OnCollapsibleStateChangedEventData = Readonly<{
   observedScrollableCount: Int32;
   retainedPages: string;
   reason: string;
+  pageKey: string;
+  headerSettledAtTop: boolean;
 }>;
 
 export type OnNativeTabPressEventData = Readonly<{

package/lib/typescript/src/CollapsiblePagerView.web.d.ts

@@ -59,6 +59,8 @@ export declare class CollapsiblePagerView extends React.PureComponent<Collapsibl
     private pageOffsets;
     private pageHosts;
     private sharedHeaderOffset;
+    private selectionRestoreToken;
+    private bodyAlignment;
     private scrollEnabled;
     private lastMountSignature;
     private configureFrame;
@@ -80,6 +82,7 @@ export declare class CollapsiblePagerView extends React.PureComponent<Collapsibl
     }>) => void;
     private cancelPendingTopFrame;
     private onQueuedTopWheel;
+    private onScrollbarPointerDown;
     private onQueuedTopKey;
     private scrollCurrentPageToTop;
     setScrollEnabled: (scrollEnabled: boolean) => void;
@@ -97,6 +100,8 @@ export declare class CollapsiblePagerView extends React.PureComponent<Collapsibl
     private restoreConfiguredScrollElement;
     private configureActiveScrollElement;
     private scheduleScrollConfiguration;
+    private takeOverVerticalScroll;
+    private onListScrollCommandAccepted;
     private onVerticalScrollSettled;
     private savePageOffset;
     private restorePageOffset;

package/lib/typescript/src/CollapsiblePagerViewNativeComponent.d.ts

@@ -19,6 +19,8 @@ export type OnCollapsibleStateChangedEventData = Readonly<{
     observedScrollableCount: Int32;
     retainedPages: string;
     reason: string;
+    pageKey: string;
+    headerSettledAtTop: boolean;
 }>;
 export type OnNativeTabPressEventData = Readonly<{
     position: Int32;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-pager-view",
-  "version": "3.0.174",
+  "version": "3.0.176",
   "description": "React Native wrapper for Android and iOS ViewPager",
   "source": "./src/index.tsx",
   "main": "./lib/module/index.js",
@@ -72,7 +72,7 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "@onekeyfe/react-native-native-logger": "3.0.174",
+    "@onekeyfe/react-native-native-logger": "3.0.176",
     "react": "*",
     "react-native": "*"
   },

package/src/CollapsiblePagerView.web.tsx

@@ -154,6 +154,11 @@ export class CollapsiblePagerView extends React.PureComponent<
   private pageOffsets = new Map<string, number>();
   private pageHosts = new Map<number, HTMLElement>();
   private sharedHeaderOffset = 0;
+  private selectionRestoreToken = 0;
+  private bodyAlignment: Readonly<{
+    element: HTMLElement;
+    key: string;
+  }> | null = null;
   private scrollEnabled = this.props.scrollEnabled ?? true;
   private lastMountSignature: string | null = null;
   private configureFrame: number | null = null;
@@ -188,6 +193,7 @@ export class CollapsiblePagerView extends React.PureComponent<
     const pageCount = this.pages().length;
     const selectedPage = clampedPageIndex(this.state.selectedPage, pageCount);
     if (selectedPage !== this.state.selectedPage) {
+      this.selectionRestoreToken += 1;
       this.cancelPendingTopFrame();
       this.finishPageTransition();
       this.setState({
@@ -201,6 +207,7 @@ export class CollapsiblePagerView extends React.PureComponent<
   }
 
   componentWillUnmount() {
+    this.selectionRestoreToken += 1;
     this.cancelPendingTopFrame();
     this.savePageOffset(this.state.selectedPage);
     if (this.configureFrame !== null) {
@@ -247,7 +254,33 @@ export class CollapsiblePagerView extends React.PureComponent<
   };
 
   private onQueuedTopWheel = (event: WheelEvent) => {
-    if (event.deltaY !== 0) this.cancelPendingTopFrame();
+    if (event.deltaY !== 0) this.takeOverVerticalScroll();
+  };
+
+  private onScrollbarPointerDown = (event: PointerEvent) => {
+    const element = this.pageScrollElement(this.state.selectedPage);
+    if (!element || event.target !== element || event.button !== 0) return;
+    const rect = element.getBoundingClientRect();
+    const computed =
+      element.ownerDocument.defaultView?.getComputedStyle(element);
+    const borderLeft = Number.parseFloat(computed?.borderLeftWidth ?? "0") || 0;
+    const borderRight =
+      Number.parseFloat(computed?.borderRightWidth ?? "0") || 0;
+    const clientStart = rect.left + element.clientLeft;
+    const clientEnd = clientStart + element.clientWidth;
+    const leftGutter = clientStart - (rect.left + borderLeft);
+    const rightGutter = rect.right - borderRight - clientEnd;
+    const inVerticalTrack =
+      event.clientY >= rect.top + element.clientTop &&
+      event.clientY < rect.top + element.clientTop + element.clientHeight;
+    const inGutter =
+      (leftGutter > 0 &&
+        event.clientX >= rect.left + borderLeft &&
+        event.clientX < clientStart) ||
+      (rightGutter > 0 &&
+        event.clientX >= clientEnd &&
+        event.clientX < rect.right - borderRight);
+    if (inVerticalTrack && inGutter) this.takeOverVerticalScroll();
   };
 
   private onQueuedTopKey = (event: KeyboardEvent) => {
@@ -262,7 +295,7 @@ export class CollapsiblePagerView extends React.PureComponent<
         " ",
       ].includes(event.key)
     )
-      this.cancelPendingTopFrame();
+      this.takeOverVerticalScroll();
   };
 
   private scrollCurrentPageToTop(offset: number, animated: boolean) {
@@ -270,6 +303,7 @@ export class CollapsiblePagerView extends React.PureComponent<
     const element = this.pageScrollElement(this.state.selectedPage);
     const key = this.pages().map(pageKey)[this.state.selectedPage];
     if (!element?.isConnected || !key) return;
+    this.selectionRestoreToken += 1;
     this.cancelPendingTopFrame();
     const EventConstructor = element.ownerDocument.defaultView?.Event;
     if (EventConstructor)
@@ -292,8 +326,9 @@ export class CollapsiblePagerView extends React.PureComponent<
         this.pages().map(pageKey)[this.state.selectedPage] !== key
       )
         return;
-      this.pageOffsets.set(key, offset);
+      this.pageOffsets.set(key, 0);
       this.sharedHeaderOffset = offset;
+      this.bodyAlignment = { element, key };
       element.scrollTo({
         top: offset,
         behavior: animated ? "smooth" : "instant",
@@ -392,9 +427,13 @@ export class CollapsiblePagerView extends React.PureComponent<
     this.cancelPendingTopFrame();
     configured.element.removeEventListener(
       "ok-native-list-scroll-command-accepted",
-      this.cancelPendingTopFrame
+      this.onListScrollCommandAccepted
     );
     configured.element.removeEventListener("wheel", this.onQueuedTopWheel);
+    configured.element.removeEventListener(
+      "pointerdown",
+      this.onScrollbarPointerDown
+    );
     configured.element.removeEventListener("keydown", this.onQueuedTopKey);
     configured.element.removeEventListener(
       "scrollend",
@@ -412,6 +451,8 @@ export class CollapsiblePagerView extends React.PureComponent<
     configured.element.removeAttribute("data-collapsible-pager-active");
     this.notifyInsetsChanged(configured.element);
     this.configuredScrollElement = null;
+    if (this.bodyAlignment?.element === configured.element)
+      this.bodyAlignment = null;
   }
 
   private configureActiveScrollElement = () => {
@@ -458,9 +499,10 @@ export class CollapsiblePagerView extends React.PureComponent<
       element.addEventListener("scrollend", this.onVerticalScrollSettled);
       element.addEventListener(
         "ok-native-list-scroll-command-accepted",
-        this.cancelPendingTopFrame
+        this.onListScrollCommandAccepted
       );
       element.addEventListener("wheel", this.onQueuedTopWheel);
+      element.addEventListener("pointerdown", this.onScrollbarPointerDown);
       element.addEventListener("keydown", this.onQueuedTopKey);
     }
 
@@ -501,8 +543,26 @@ export class CollapsiblePagerView extends React.PureComponent<
     }
   }
 
-  private onVerticalScrollSettled = () => {
-    if (this.pendingTopFrame) return;
+  private takeOverVerticalScroll = () => {
+    this.selectionRestoreToken += 1;
+    this.bodyAlignment = null;
+    this.cancelPendingTopFrame();
+    this.savePageOffset(this.state.selectedPage);
+  };
+
+  private onListScrollCommandAccepted = (event: Event) => {
+    if (event.target !== this.pageScrollElement(this.state.selectedPage))
+      return;
+    this.takeOverVerticalScroll();
+  };
+
+  private onVerticalScrollSettled = (event?: Event) => {
+    if (
+      this.pendingTopFrame ||
+      (event &&
+        event.target !== this.pageScrollElement(this.state.selectedPage))
+    )
+      return;
     this.savePageOffset(this.state.selectedPage);
     this.emitDiagnostics("scroll-settled");
   };
@@ -511,10 +571,16 @@ export class CollapsiblePagerView extends React.PureComponent<
     const key = this.pages().map(pageKey)[index];
     const scrollElement = this.pageScrollElement(index);
     if (key && scrollElement) {
-      this.pageOffsets.set(key, scrollElement.scrollTop);
+      if (
+        this.bodyAlignment?.key === key &&
+        this.bodyAlignment.element === scrollElement
+      )
+        return;
+      const D = Math.max(0, this.props.headerHeight);
+      this.pageOffsets.set(key, Math.max(0, scrollElement.scrollTop - D));
       this.sharedHeaderOffset = Math.min(
         Math.max(scrollElement.scrollTop, 0),
-        Math.max(0, this.props.headerHeight)
+        D
       );
     }
   }
@@ -523,10 +589,11 @@ export class CollapsiblePagerView extends React.PureComponent<
     const key = this.pages().map(pageKey)[index];
     const scrollElement = this.pageScrollElement(index);
     if (!key || !scrollElement) return;
-    scrollElement.scrollTop = Math.max(
-      this.pageOffsets.get(key) ?? this.sharedHeaderOffset,
-      this.sharedHeaderOffset
-    );
+    const D = Math.max(0, this.props.headerHeight);
+    const C = Math.min(Math.max(0, this.sharedHeaderOffset), D);
+    const expectedQ = C + (C === D ? this.pageOffsets.get(key) ?? 0 : 0);
+    this.bodyAlignment = { element: scrollElement, key };
+    scrollElement.scrollTop = expectedQ;
   }
 
   private selectPage(selectedPage: number, animated: boolean) {
@@ -540,6 +607,8 @@ export class CollapsiblePagerView extends React.PureComponent<
     ) {
       return;
     }
+    const selectionToken = ++this.selectionRestoreToken;
+    const expectedKey = this.pages().map(pageKey)[position];
     this.cancelPendingTopFrame();
     this.savePageOffset(this.state.selectedPage);
 
@@ -550,6 +619,13 @@ export class CollapsiblePagerView extends React.PureComponent<
       () => {
         this.scheduleScrollConfiguration();
         const restore = () => {
+          if (
+            this.selectionRestoreToken !== selectionToken ||
+            this.state.selectedPage !== position ||
+            this.pages().map(pageKey)[position] !== expectedKey ||
+            !this.pageScrollElement(position)?.isConnected
+          )
+            return;
           this.configureActiveScrollElement();
           this.restorePageOffset(position);
         };
@@ -629,7 +705,7 @@ export class CollapsiblePagerView extends React.PureComponent<
     const deltaX = touch.pageX - this.touchStartX;
     const deltaY = touch.pageY - (this.touchStartY ?? touch.pageY);
     if (Math.abs(deltaY) >= 8 && Math.abs(deltaY) > Math.abs(deltaX))
-      this.cancelPendingTopFrame();
+      this.takeOverVerticalScroll();
     if (Math.abs(deltaX) >= 8 && Math.abs(deltaX) > Math.abs(deltaY)) {
       this.cancelPendingTopFrame();
       this.horizontalTouch = true;

package/src/CollapsiblePagerViewNativeComponent.ts

@@ -35,6 +35,8 @@ export type OnCollapsibleStateChangedEventData = Readonly<{
   observedScrollableCount: Int32;
   retainedPages: string;
   reason: string;
+  pageKey: string;
+  headerSettledAtTop: boolean;
 }>;
 
 export type OnNativeTabPressEventData = Readonly<{