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

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

@@ -204,6 +204,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 +240,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()
@@ -554,6 +567,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 +869,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()
@@ -1030,6 +1052,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 +1147,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 +1306,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 +1440,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)
@@ -2070,6 +2188,7 @@ 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)
@@ -2084,6 +2203,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 +2311,9 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   override fun onDetachedFromWindow() {
+    cancelHeaderSettledCheck()
+    headerCommandOwner = null
+    publishHeaderSettledState(false)
     pendingRefreshPull = null
     releaseRefreshForeground()
     attachmentGeneration += 1

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

@@ -717,3 +717,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/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/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.175",
   "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.175",
     "react": "*",
     "react-native": "*"
   },

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<{