@onekeyfe/react-native-pager-view 6.7.0-alpha.369 → 6.7.0-alpha.375

package/docs/SPEC.md

@@ -817,6 +817,51 @@ fallback debounce, including replacement-state restoration. Other collection
 fallbacks keep that safety delay. Caller insets and retained logical offsets
 remain governed by the existing restoration policy.
 
+When the active scroll owner is removed before its replacement becomes usable,
+the pager MUST retain bounded recovery (at most 12 retries per recovery round,
+spaced 100 ms apart). Clearing the completed mount's reattachment flag MUST NOT
+cancel that recovery. A replacement that becomes usable during that round,
+without another Fabric insertion, MUST receive the observer, shared headers,
+insets and retained collapse state. Page selection changes and recycling
+invalidate stale retry callbacks. Repeated mount attempts MUST NOT reset the
+retry budget. Once all 12 retries have been scheduled, an Insert whose parent is
+in the current page subtree MUST reopen recovery if that page retains a released
+scroll owner, including when the final retry callback is still pending. Reopening
+invalidates the old callback before clearing its scheduled state. The Insert
+MUST be recorded during a horizontal drag or transition, while observer and shared
+header attachment remain deferred until selection settles. Cancelling the drag
+on the same page MUST retain the reopened recovery round. Empty transactions,
+removals and inserts outside the current page MUST NOT reopen the budget. Owned
+`NativeScroller` and `NativeList` hosts additionally emit push readiness
+notifications when their scroll views attach and obtain positive bounds so late
+replacements recover immediately even without another Fabric insertion or after
+the retry budget expires; static pages with neither an unready scroll host nor a
+released scroll owner do not schedule retry timers.
+
+Status of transition-time and pending-final-retry recovery: implemented and
+UIKit regression verified on iOS 26.5 (2026-10-27). Both new regressions fail
+before the fix and pass afterward. Cancellation settles on the source page
+before the replacement becomes usable; the pending-final-retry case makes the
+replacement usable after the old timer's deadline. Observer and shared header
+ownership stay detached during the drag, then recover with the retained collapse.
+The full Pager suite executes 85 tests, with one iOS-27-only skip and no failures.
+
+Status of exhausted-budget recovery: implemented and UIKit regression verified
+on iOS 26.5 (2026-10-27). The regression exhausts the initial round, checks that
+empty transactions, removals and offscreen inserts do not reopen it, then inserts
+a current-page replacement whose scroller appears after did-mount. It fails
+before the fix and passes afterward, including preservation of an active round
+and restoration of the observer, shared headers and retained collapse. The full
+Pager suite executes 83 tests, with one iOS-27-only skip and no failures.
+
+Status of replacement recovery: implemented and runtime verified on iOS 26.5
+(2026-10-23). The late-replacement UIKit regression fails before the fix and
+passes afterward; the full Pager suite executes 82 tests, with one iOS-27-only
+skip and no failures. In the consuming app based on x at b0789571d8 with SDK
+6.7.0-9 and this local native change, two empty Favorites-to-Wallet-add-to-Market
+cycles and a Trending/Favorites round trip keep the first row aligned with the
+sticky header. The previously observed 212-point gap is absent.
+
 This is a UI-thread, main-runtime native coordination change with no new props,
 events, background-runtime work, persistence or retained strong view cache.
 Android already prepares discovered scroll children before draw and is unchanged;

package/ios/RNCCollapsiblePagerViewComponentView.mm

@@ -157,6 +157,20 @@ static NSString *const RNCCollapsiblePagerNativeScrollerIDPrefix =
 
 static const CFTimeInterval RNCCollapsiblePagerFallbackDebounceInterval = 0.5;
 
+typedef NS_ENUM(NSInteger, RNCScrollCandidateTier) {
+  RNCScrollCandidateTierNone = 0,
+  RNCScrollCandidateTierGenericFallback = 1,
+  RNCScrollCandidateTierVerifiedNativeList = 2,
+  RNCScrollCandidateTierFabricScrollView = 3,
+  RNCScrollCandidateTierExplicitScroller = 4,
+};
+
+struct RNCScrollCandidateResolution {
+  UIScrollView *scrollView = nil;
+  RNCScrollCandidateTier tier = RNCScrollCandidateTierNone;
+  BOOL hasUnreadyScrollHost = NO;
+};
+
 // OneKey patch: native scroll views can survive a move or be reused for a new
 // Fabric component. Keep weak identity until their page is attached again.
 @interface RNCCollapsiblePagerReleasedScrollState : NSObject
@@ -1475,9 +1489,12 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 - (void)updatePinnedStickyHeader;
 - (UIScrollView *)currentVerticalScrollViewForParentPager;
 - (UIScrollView *)verticalScrollViewForPageAtIndex:(NSInteger)pageIndex;
+- (RNCScrollCandidateResolution)resolveScrollCandidateForPageAtIndex:(NSInteger)pageIndex;
+- (RNCScrollCandidateResolution)resolveScrollCandidateInView:(UIView *)view;
 - (UIScrollView *)findExplicitNativeScrollerInView:(UIView *)view;
 - (UIScrollView *)findFabricScrollViewInView:(UIView *)view;
 - (UIScrollView *)findVerticalScrollViewInView:(UIView *)view;
+- (void)scheduleCoalescedScrollReconcile;
 - (void)scheduleScrollObserverRetryForCurrentPage;
 - (void)preparePageForHorizontalTransitionAtIndex:(NSInteger)pageIndex;
 - (void)updateSharedHeaderPressCancellationGesture;
@@ -1644,6 +1661,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   RNCCollapsiblePagerOuterPagerPanGestureRecognizer *_sharedHeaderOuterPagerGesture;
   RNCCollapsiblePagerVerticalPagerGuardGestureRecognizer *_verticalPagerGesture;
   BOOL _observingContentOffset;
+  BOOL _awaitingScrollOwnerForCurrentPage;
+  BOOL _scrollReconcileScheduled;
   BOOL _scrollResolveRetryScheduled;
   CFTimeInterval _pendingFallbackScrollViewDetectedAt;
   NSInteger _scrollResolveRetryPageIndex;
@@ -1675,6 +1694,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _displayBodyOverrides = [NSMutableDictionary new];
     [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(nativeListScrollCommandAccepted:)
       name:@"OneKeyNativeListScrollCommandAccepted" object:nil];
+    [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(nativeScrollViewDidBecomeReadyNotification:)
+      name:@"OneKeyNativeScrollViewDidBecomeReady" object:nil];
     _pendingPageRestoreKeys = [NSMutableSet new];
     _releasedPageScrollStates = [NSMutableDictionary new];
     _mountingRemovedScrollViews = [NSHashTable weakObjectsHashTable];
@@ -2332,6 +2353,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [self updateTopScrollEdgeForScrollView:nil];
   [self cancelHeaderSettledCheck];
   [[NSNotificationCenter defaultCenter] removeObserver:self name:@"OneKeyNativeListScrollCommandAccepted" object:nil];
+  [[NSNotificationCenter defaultCenter] removeObserver:self name:@"OneKeyNativeScrollViewDidBecomeReady" object:nil];
   for (UIScrollView *scrollView in _originalInsets.keyEnumerator) {
     [self updateNativeScrollerViewport:scrollView stickyHeight:0];
   }
@@ -2874,6 +2896,23 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       [self applyInsetsToScrollView:scrollView pageIndex:index restore:YES];
     }
   }
+  UIView *page = _pageControllers[_currentIndex].view;
+  if (_scrollResolveRetryAttempt >= 12 &&
+      _releasedPageScrollStates[self.currentPageKey] != nil) {
+    for (const auto &mutation : transaction.getMutations()) {
+      if (mutation.type == ShadowViewMutation::Insert && mutation.parentTag > 0 &&
+          [page viewWithTag:mutation.parentTag] != nil) {
+        // A new current-page insertion starts a bounded recovery round after
+        // the previous replacement search has scheduled its final retry.
+        _scrollResolveRetryToken += 1;
+        _scrollResolveRetryScheduled = NO;
+        _scrollResolveRetryAttempt = 0;
+        break;
+      }
+    }
+  }
+
+  // Record recovery during transitions; ownership still waits for settlement.
   if (_transitioning || _isPagerDragging) return;
 
   // OneKey patch: a release must recover even when the changed parent is above
@@ -2882,7 +2921,6 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     [self attachScrollObserverForCurrentPage];
     return;
   }
-  UIView *page = _pageControllers[_currentIndex].view;
   BOOL headerIsAttached = [_sharedHeaderHostView isDescendantOfView:self];
   BOOL currentListIsAttached = _observedScrollView != nil &&
     [_observedScrollView isDescendantOfView:page] && headerIsAttached;
@@ -3056,12 +3094,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   }
   if (self.hasFixedTopOverlay) [_containerView bringSubviewToFront:_topOverlayHostView];
   [self setNeedsLayout];
-  dispatch_async(dispatch_get_main_queue(), ^{
-    if (!self->_isBeingRecycled) {
-      [self prepareAdjacentPageInsets];
-      [self attachScrollObserverForCurrentPage];
-    }
-  });
+  [self scheduleCoalescedScrollReconcile];
 }
 
 - (void)layoutSubviews
@@ -3138,12 +3171,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [self updateScrollEdgeContentMasks];
   [self updateHeaderSettledStateForceBusy:NO];
   [self logHomeVisualGeometry:@"layout" scrollView:_observedScrollView];
-  dispatch_async(dispatch_get_main_queue(), ^{
-    if (!self->_isBeingRecycled) {
-      [self prepareAdjacentPageInsets];
-      [self attachScrollObserverForCurrentPage];
-    }
-  });
+  [self scheduleCoalescedScrollReconcile];
 }
 
 - (void)prepareForRecycle
@@ -3161,6 +3189,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   _generation++;
   [_mountingRemovedScrollViews removeAllObjects];
   _needsScrollObserverReattachAfterMount = NO;
+  _awaitingScrollOwnerForCurrentPage = NO;
+  _scrollReconcileScheduled = NO;
   [_releasedPageScrollStates removeAllObjects];
   [self detachSharedHeaderPressCancellationGesture];
   [self detachScrollObserver];
@@ -3501,12 +3531,105 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (UIScrollView *)verticalScrollViewForPageAtIndex:(NSInteger)pageIndex
 {
-  if (pageIndex < 0 || pageIndex >= _pageControllers.count) return nil;
-  UIView *pageView = _pageControllers[pageIndex].view;
-  UIScrollView *explicitScroller = [self findExplicitNativeScrollerInView:pageView];
-  if (explicitScroller != nil) return explicitScroller;
-  UIScrollView *fabricScrollView = [self findFabricScrollViewInView:pageView];
-  return fabricScrollView ?: [self findVerticalScrollViewInView:pageView];
+  return [self resolveScrollCandidateForPageAtIndex:pageIndex].scrollView;
+}
+
+- (RNCScrollCandidateResolution)resolveScrollCandidateForPageAtIndex:(NSInteger)pageIndex
+{
+  if (pageIndex < 0 || pageIndex >= _pageControllers.count) return {};
+  return [self resolveScrollCandidateInView:_pageControllers[pageIndex].view];
+}
+
+// Single-pass tiered resolution replaces three separate subtree walks while
+// distinguishing genuinely static pages from pages with unready scroll hosts.
+- (RNCScrollCandidateResolution)resolveScrollCandidateInView:(UIView *)view
+{
+  RNCScrollCandidateResolution resolution;
+  if (view == nil || view == _sharedHeaderHostView) return resolution;
+  if (view != self &&
+      [view isKindOfClass:RNCCollapsiblePagerViewComponentView.class]) {
+    UIScrollView *nested = [(RNCCollapsiblePagerViewComponentView *)view
+      currentVerticalScrollViewForParentPager];
+    if (nested != nil) {
+      resolution.scrollView = nested;
+      resolution.tier = RNCScrollCandidateTierExplicitScroller;
+    } else {
+      resolution.hasUnreadyScrollHost = YES;
+    }
+    return resolution;
+  }
+
+  Class nativeListClass = NSClassFromString(@"HybridNativeListComponent");
+  if (nativeListClass != Nil && [view isKindOfClass:nativeListClass]) {
+    resolution.hasUnreadyScrollHost = YES;
+  }
+
+  if ([view isKindOfClass:RNCNativeScrollerComponentView.class]) {
+    UIScrollView *scrollView = ((RNCNativeScrollerComponentView *)view).scrollView;
+    if (![_mountingRemovedScrollViews containsObject:scrollView]) {
+      resolution.scrollView = scrollView;
+      resolution.tier = RNCScrollCandidateTierExplicitScroller;
+      return resolution;
+    }
+  } else if ([view isKindOfClass:RCTScrollViewComponentView.class]) {
+    RCTScrollViewComponentView *componentView = (RCTScrollViewComponentView *)view;
+    UIScrollView *scrollView = componentView.scrollView;
+    if (![_mountingRemovedScrollViews containsObject:scrollView]) {
+      if ([componentView.nativeId hasPrefix:RNCCollapsiblePagerNativeScrollerIDPrefix]) {
+        resolution.scrollView = scrollView;
+        resolution.tier = RNCScrollCandidateTierExplicitScroller;
+        return resolution;
+      }
+      if (!scrollView.alwaysBounceHorizontal) {
+        resolution.scrollView = scrollView;
+        resolution.tier = RNCScrollCandidateTierFabricScrollView;
+      }
+    }
+  } else if ([view isKindOfClass:UICollectionView.class]) {
+    UICollectionView *collectionView = (UICollectionView *)view;
+    if (![_mountingRemovedScrollViews containsObject:collectionView]) {
+      UICollectionViewLayout *layout = collectionView.collectionViewLayout;
+      BOOL isVerticalLayout = ![layout isKindOfClass:UICollectionViewFlowLayout.class] ||
+        ((UICollectionViewFlowLayout *)layout).scrollDirection == UICollectionViewScrollDirectionVertical;
+      if (isVerticalLayout) {
+        BOOL hasNativeListHost = RNCNativeListComponentForScrollView(collectionView) != nil;
+        BOOL isMountedNativeList = hasNativeListHost && RNCIsMountedNativeListScrollView(collectionView);
+        BOOL hasUsableBounds = CGRectGetWidth(collectionView.bounds) > 0 &&
+          CGRectGetHeight(collectionView.bounds) > 0;
+        if (hasNativeListHost && !isMountedNativeList) {
+          resolution.hasUnreadyScrollHost = YES;
+        } else if (!hasUsableBounds) {
+          resolution.hasUnreadyScrollHost = YES;
+        } else {
+          resolution.scrollView = collectionView;
+          resolution.tier = isMountedNativeList
+            ? RNCScrollCandidateTierVerifiedNativeList
+            : RNCScrollCandidateTierGenericFallback;
+        }
+      }
+    }
+  } else if ([view isKindOfClass:UIScrollView.class]) {
+    UIScrollView *scrollView = (UIScrollView *)view;
+    if (![_mountingRemovedScrollViews containsObject:scrollView] &&
+        !scrollView.alwaysBounceHorizontal &&
+        scrollView.contentSize.width <= scrollView.bounds.size.width + 1) {
+      resolution.scrollView = scrollView;
+      resolution.tier = RNCScrollCandidateTierGenericFallback;
+    }
+  }
+
+  for (UIView *subview in view.subviews) {
+    RNCScrollCandidateResolution child = [self resolveScrollCandidateInView:subview];
+    resolution.hasUnreadyScrollHost |= child.hasUnreadyScrollHost;
+    if (child.tier > resolution.tier) {
+      resolution.scrollView = child.scrollView;
+      resolution.tier = child.tier;
+      if (resolution.tier == RNCScrollCandidateTierExplicitScroller) {
+        return resolution;
+      }
+    }
+  }
+  return resolution;
 }
 
 - (UIScrollView *)findExplicitNativeScrollerInView:(UIView *)view
@@ -3602,6 +3725,19 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   return nil;
 }
 
+- (void)scheduleCoalescedScrollReconcile
+{
+  if (_isBeingRecycled || _scrollReconcileScheduled) return;
+  _scrollReconcileScheduled = YES;
+  NSUInteger generation = _generation;
+  dispatch_async(dispatch_get_main_queue(), ^{
+    self->_scrollReconcileScheduled = NO;
+    if (self->_isBeingRecycled || self->_generation != generation) return;
+    [self prepareAdjacentPageInsets];
+    [self attachScrollObserverForCurrentPage];
+  });
+}
+
 - (void)scheduleScrollObserverRetryForCurrentPage
 {
   if (_scrollResolveRetryScheduled || _scrollResolveRetryAttempt >= 12 ||
@@ -3654,29 +3790,35 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _pendingFallbackScrollView = nil;
     _pendingFallbackScrollViewDetectedAt = 0;
   }
-  UIScrollView *candidate = [self verticalScrollViewForPageAtIndex:_currentIndex];
+  RNCScrollCandidateResolution resolution = [self resolveScrollCandidateForPageAtIndex:_currentIndex];
+  UIScrollView *candidate = resolution.scrollView;
   if (_nativeSmoothHeaderScrollEnabled && _currentIndex >= 0 && _currentIndex < _pageControllers.count) {
     RNCGuardNestedHorizontalPans(_pageControllers[_currentIndex].view, _verticalPagerGesture);
   }
   if (candidate == nil) {
     [self detachScrollObserver];
     [self restoreSharedHeadersToContainer];
-    // Stop retrying released lists on unrelated commits without discarding a
-    // surviving identity or offset. A relevant insertion resumes recovery.
-    if (_needsScrollObserverReattachAfterMount) {
-      _needsScrollObserverReattachAfterMount = NO;
+    _needsScrollObserverReattachAfterMount = NO;
+    _pendingFallbackScrollView = nil;
+    _pendingFallbackScrollViewDetectedAt = 0;
+    _awaitingScrollOwnerForCurrentPage = YES;
+    // Only schedule bounded retry when the page has an unready scroll host in
+    // its subtree or a released scroll owner awaiting replacement. Static pages
+    // without a scroll host do not spin retry timers, and late replacements on
+    // any page also attach deterministically via readiness notifications.
+    BOOL hasReleasedOwnerAwaitingReplacement = _releasedPageScrollStates[self.currentPageKey] != nil;
+    if (resolution.hasUnreadyScrollHost || hasReleasedOwnerAwaitingReplacement) {
+      [self scheduleScrollObserverRetryForCurrentPage];
+    } else {
       _scrollResolveRetryToken += 1;
       _scrollResolveRetryScheduled = NO;
       _scrollResolveRetryAttempt = 0;
-      _pendingFallbackScrollView = nil;
-      _pendingFallbackScrollViewDetectedAt = 0;
-    } else {
-      [self scheduleScrollObserverRetryForCurrentPage];
     }
     return;
   }
   if ([candidate isKindOfClass:UICollectionView.class] &&
       candidate != _observedScrollView && !RNCIsMountedNativeListScrollView(candidate)) {
+    _awaitingScrollOwnerForCurrentPage = YES;
     if (_pendingFallbackScrollView != candidate) {
       _pendingFallbackScrollView = candidate;
       _pendingFallbackScrollViewDetectedAt = CACurrentMediaTime();
@@ -3688,6 +3830,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       return;
     }
   }
+  _awaitingScrollOwnerForCurrentPage = NO;
   _scrollResolveRetryAttempt = 0;
   _scrollResolveRetryPageIndex = _currentIndex;
   _scrollResolveRetryToken += 1;
@@ -4511,6 +4654,66 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 }
 
 
+- (void)nativeScrollViewDidBecomeReadyNotification:(NSNotification *)notification
+{
+  if ([notification.object isKindOfClass:UIScrollView.class]) {
+    [self nativeScrollViewDidBecomeReady:(UIScrollView *)notification.object];
+  }
+}
+
+- (void)nativeScrollViewDidBecomeReady:(UIScrollView *)scrollView
+{
+  if (_isBeingRecycled || self.window == nil || scrollView == nil ||
+      [_mountingRemovedScrollViews containsObject:scrollView]) return;
+  for (UIView *ancestor = scrollView.superview;
+       ancestor != nil && ancestor != self;
+       ancestor = ancestor.superview) {
+    if ([ancestor isKindOfClass:RNCCollapsiblePagerViewComponentView.class]) {
+      RNCCollapsiblePagerViewComponentView *nestedPager =
+        (RNCCollapsiblePagerViewComponentView *)ancestor;
+      if ([nestedPager currentVerticalScrollViewForParentPager] != scrollView) return;
+      break;
+    }
+  }
+  NSInteger pageIndex = NSNotFound;
+  for (NSInteger index = 0; index < _pageControllers.count; index++) {
+    if ([scrollView isDescendantOfView:_pageControllers[index].view]) {
+      pageIndex = index;
+      break;
+    }
+  }
+  if (pageIndex == NSNotFound) return;
+
+  NSString *pageKey = [self pageKeyForIndex:pageIndex];
+  BOOL hasReleasedStateForPage = _releasedPageScrollStates[pageKey] != nil;
+  BOOL currentPageNeedsOwner = pageIndex == _currentIndex &&
+    (_awaitingScrollOwnerForCurrentPage || _needsScrollObserverReattachAfterMount ||
+     hasReleasedStateForPage ||
+     (_observedScrollView != nil &&
+      [_observedScrollView isKindOfClass:UICollectionView.class] &&
+      !RNCIsMountedNativeListScrollView(_observedScrollView) &&
+      _observedScrollView != scrollView));
+
+  if (!hasReleasedStateForPage && !currentPageNeedsOwner &&
+      !_needsScrollObserverReattachAfterMount) return;
+
+  if (_nativeSmoothHeaderScrollEnabled) {
+    NSInteger first = MAX(0, _currentIndex - 1);
+    NSInteger last = MIN((NSInteger)_pageControllers.count - 1, _currentIndex + 1);
+    BOOL isOwnedScroller = [scrollView.superview isKindOfClass:RNCNativeScrollerComponentView.class] &&
+      ((RNCNativeScrollerComponentView *)scrollView.superview).scrollView == scrollView;
+    if ((pageIndex >= first && pageIndex <= last || pageIndex == _destinationIndex) &&
+        (RNCIsMountedNativeListScrollView(scrollView) || isOwnedScroller) &&
+        [_originalInsets objectForKey:scrollView] == nil) {
+      [self applyInsetsToScrollView:scrollView pageIndex:pageIndex restore:YES];
+    }
+  }
+
+  if (currentPageNeedsOwner && !_transitioning && !_isPagerDragging) {
+    [self attachScrollObserverForCurrentPage];
+  }
+}
+
 - (void)nativeScroller:(RNCNativeScrollerComponentView *)scroller
     callerInsetChangedFrom:(UIEdgeInsets)previous to:(UIEdgeInsets)next
 {

package/ios/RNCNativeScrollerComponentView.h

@@ -13,6 +13,8 @@ NS_ASSUME_NONNULL_BEGIN
 - (void)nativeScrollerWillReceiveScrollCommand:(RNCNativeScrollerComponentView *)scroller;
 - (void)nativeScroller:(RNCNativeScrollerComponentView *)scroller
     callerInsetChangedFrom:(UIEdgeInsets)previous to:(UIEdgeInsets)next;
+@optional
+- (void)nativeScrollViewDidBecomeReady:(UIScrollView *)scrollView;
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/RNCNativeScrollerComponentView.mm

@@ -298,10 +298,23 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
   }
 }
 
+- (void)notifyCoordinatorScrollViewReadyIfNeeded
+{
+  if (_recycled || self.window == nil ||
+      CGRectGetWidth(_scrollView.bounds) <= 0 || CGRectGetHeight(_scrollView.bounds) <= 0) return;
+  for (UIView *owner = self.superview; owner != nil; owner = owner.superview) {
+    if ([owner conformsToProtocol:@protocol(RNCNativeScrollerInsetCoordinator)] &&
+        [owner respondsToSelector:@selector(nativeScrollViewDidBecomeReady:)]) {
+      [(id<RNCNativeScrollerInsetCoordinator>)owner nativeScrollViewDidBecomeReady:_scrollView];
+    }
+  }
+}
+
 - (void)didMoveToSuperview
 {
   [super didMoveToSuperview];
   [self updateTopScrollEdge];
+  [self notifyCoordinatorScrollViewReadyIfNeeded];
 }
 
 - (void)updateLayoutMetrics:(const LayoutMetrics &)layoutMetrics
@@ -314,6 +327,10 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
   if (!CGSizeEqualToSize(previous, _scrollView.bounds.size)) {
     _needsContentClamp = YES;
     [self scheduleContentClamp];
+    if ((previous.width <= 0 || previous.height <= 0) &&
+        _scrollView.bounds.size.width > 0 && _scrollView.bounds.size.height > 0) {
+      [self notifyCoordinatorScrollViewReadyIfNeeded];
+    }
   }
 }
 
@@ -574,6 +591,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
     const auto &props = *std::static_pointer_cast<const RNCNativeScrollerProps>(_props);
     if (props.refreshing) [_refreshControl beginRefreshing];
     [self scheduleContentClamp];
+    [self notifyCoordinatorScrollViewReadyIfNeeded];
   }
 }
 

package/ios/tests/RNCCollapsiblePagerFirstFrameTests.mm

@@ -459,6 +459,138 @@ using namespace facebook::react;
   XCTAssertTrue([[pager valueForKey:@"pendingPageRestoreKeys"] containsObject:@"page-1"]);
 }
 
+- (void)testReleasedOwnerRecoversReplacementWithoutAnotherFabricInsertion
+{
+  RNCCollapsiblePagerViewComponentView *pager = [self pagerWithPageCount:1];
+  // The fixture mounts page 0 directly; UIKit must not select it again.
+  [pager setValue:@YES forKey:@"hasAppliedInitialPage"];
+  RNCNativeScrollerComponentView *source = [self addScrollerToPager:pager atIndex:0];
+  source.tag = 91001;
+  [pager.window layoutIfNeeded];
+  [pager layoutIfNeeded];
+  [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.15]];
+  [pager setValue:@120 forKey:@"headerOffset"];
+  [pager attachScrollObserverForCurrentPage];
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], source.scrollView);
+
+  // Finish the old owner's removal before the replacement becomes available.
+  ShadowView removedView;
+  removedView.tag = (Tag)source.tag;
+  MountingTransaction removal(1, 1, {ShadowViewMutation::RemoveMutation(1, removedView, 0)}, {});
+  SurfaceTelemetry telemetry;
+  [pager mountingTransactionWillMount:removal withSurfaceTelemetry:telemetry];
+  [source removeFromSuperview];
+  [self finishMount:pager];
+  XCTAssertNil([pager valueForKey:@"observedScrollView"]);
+
+  RNCNativeScrollerComponentView *replacement = [self addScrollerToPager:pager atIndex:0];
+  [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.3]];
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], replacement.scrollView);
+  XCTAssertEqual([pager valueForKey:@"sharedHeaderScrollView"], replacement.scrollView);
+  XCTAssertEqualWithAccuracy(replacement.scrollView.contentOffset.y + replacement.scrollView.contentInset.top,
+                            120, 0.01);
+  XCTAssertEqualWithAccuracy([[pager valueForKey:@"headerOffset"] doubleValue], 120, 0.01);
+}
+
+- (void)testCurrentPageInsertionRestartsExhaustedReplacementRecovery
+{
+  [self assertReplacementRecoveryWithCancelledDrag:NO finalRetryPending:NO];
+}
+
+- (void)testCancelledDragRetainsReplacementRecoveryFromInsertion
+{
+  [self assertReplacementRecoveryWithCancelledDrag:YES finalRetryPending:NO];
+}
+
+- (void)testInsertionInvalidatesPendingFinalReplacementRetry
+{
+  [self assertReplacementRecoveryWithCancelledDrag:NO finalRetryPending:YES];
+}
+
+- (void)assertReplacementRecoveryWithCancelledDrag:(BOOL)cancelDrag
+                                finalRetryPending:(BOOL)finalRetryPending
+{
+  RNCCollapsiblePagerViewComponentView *pager = [self pagerWithPageCount:2];
+  [pager setValue:@YES forKey:@"hasAppliedInitialPage"];
+  RNCNativeScrollerComponentView *source = [self addScrollerToPager:pager atIndex:0];
+  source.tag = 91001;
+  UIView *page = source.superview;
+  page.tag = 92001;
+  UIViewController *otherPage = [pager valueForKey:@"pageControllers"][1];
+  otherPage.view.tag = 92002;
+  [pager.window layoutIfNeeded];
+  [pager layoutIfNeeded];
+  [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.15]];
+  [pager setValue:@120 forKey:@"headerOffset"];
+  [pager attachScrollObserverForCurrentPage];
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], source.scrollView);
+
+  ShadowView removedView;
+  removedView.tag = (Tag)source.tag;
+  MountingTransaction removal(1, 1, {ShadowViewMutation::RemoveMutation((Tag)page.tag, removedView, 0)}, {});
+  SurfaceTelemetry telemetry;
+  [pager mountingTransactionWillMount:removal withSurfaceTelemetry:telemetry];
+  [source removeFromSuperview];
+  [self finishMount:pager];
+  NSDate *deadline = [NSDate dateWithTimeIntervalSinceNow:3];
+  while (([[pager valueForKey:@"scrollResolveRetryAttempt"] integerValue] < 12 ||
+          (!finalRetryPending && [[pager valueForKey:@"scrollResolveRetryScheduled"] boolValue])) &&
+         deadline.timeIntervalSinceNow > 0) {
+    [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.01]];
+  }
+  XCTAssertEqualObjects([pager valueForKey:@"scrollResolveRetryAttempt"], @12);
+  XCTAssertEqualObjects([pager valueForKey:@"scrollResolveRetryScheduled"], @(finalRetryPending));
+  XCTAssertNotNil([pager valueForKey:@"releasedPageScrollStates"][@"page-0"]);
+
+  // Only a new insertion in the current page can reopen the exhausted budget.
+  [self finishMount:pager];
+  [pager mountingTransactionDidMount:removal withSurfaceTelemetry:telemetry];
+  UIView *replacementHost = [UIView new];
+  replacementHost.tag = 93001;
+  [otherPage.view addSubview:replacementHost];
+  ShadowView insertedView;
+  insertedView.tag = (Tag)replacementHost.tag;
+  MountingTransaction unrelated(1, 2, {ShadowViewMutation::InsertMutation((Tag)otherPage.view.tag, insertedView, 0)}, {});
+  [pager mountingTransactionDidMount:unrelated withSurfaceTelemetry:telemetry];
+  XCTAssertEqualObjects([pager valueForKey:@"scrollResolveRetryAttempt"], @12);
+  XCTAssertEqualObjects([pager valueForKey:@"scrollResolveRetryScheduled"], @(finalRetryPending));
+
+  if (cancelDrag) {
+    [pager beginPageStateTransition];
+    [pager setValue:@YES forKey:@"transitioning"];
+    [pager setValue:@YES forKey:@"isPagerDragging"];
+  }
+  [page addSubview:replacementHost];
+  MountingTransaction insertion(1, 3, {ShadowViewMutation::InsertMutation((Tag)page.tag, insertedView, 0)}, {});
+  [pager mountingTransactionDidMount:insertion withSurfaceTelemetry:telemetry];
+  XCTAssertNil([pager valueForKey:@"observedScrollView"]);
+  NSNumber *retryToken = [pager valueForKey:@"scrollResolveRetryToken"];
+  [pager mountingTransactionDidMount:insertion withSurfaceTelemetry:telemetry];
+  XCTAssertEqualObjects([pager valueForKey:@"scrollResolveRetryToken"], retryToken);
+  if (cancelDrag) {
+    XCTAssertNil([pager valueForKey:@"sharedHeaderScrollView"]);
+    XCTAssertFalse([[pager valueForKey:@"scrollResolveRetryScheduled"] boolValue]);
+    // Settle on the source page while the replacement is still unavailable.
+    [pager attachScrollObserverForCurrentPageAfterTransition:YES];
+    [pager setValue:@NO forKey:@"isPagerDragging"];
+    [pager setValue:@NO forKey:@"transitioning"];
+    [pager attachScrollObserverForCurrentPage];
+    XCTAssertEqualObjects([pager valueForKey:@"currentIndex"], @0);
+  }
+  __block RNCNativeScrollerComponentView *replacement;
+  int64_t replacementDelay = finalRetryPending ? 150 : 50;
+  dispatch_after(dispatch_time(DISPATCH_TIME_NOW, replacementDelay * NSEC_PER_MSEC), dispatch_get_main_queue(), ^{
+    replacement = [self addScrollerToPager:pager atIndex:0];
+    [replacementHost addSubview:replacement];
+  });
+  [[NSRunLoop mainRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.3]];
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], replacement.scrollView);
+  XCTAssertEqual([pager valueForKey:@"sharedHeaderScrollView"], replacement.scrollView);
+  XCTAssertEqualWithAccuracy(replacement.scrollView.contentOffset.y + replacement.scrollView.contentInset.top,
+                            120, 0.01);
+  XCTAssertEqualWithAccuracy([[pager valueForKey:@"headerOffset"] doubleValue], 120, 0.01);
+}
+
 - (void)testRenamedPageDoesNotResurrectPrunedObserverCache
 {
   RNCCollapsiblePagerViewComponentView *pager = [self pagerWithPageCount:1];
@@ -603,4 +735,58 @@ using namespace facebook::react;
   XCTAssertEqual(removed.count, 0u);
 }
 
+- (void)testEmptyPageWithoutReleasedOwnerOrScrollHostDoesNotScheduleRetry
+{
+  RNCCollapsiblePagerViewComponentView *pager = [self pagerWithPageCount:1];
+  [pager attachScrollObserverForCurrentPage];
+  XCTAssertNil([pager valueForKey:@"observedScrollView"]);
+  XCTAssertFalse([[pager valueForKey:@"scrollResolveRetryScheduled"] boolValue]);
+  XCTAssertEqual([[pager valueForKey:@"scrollResolveRetryAttempt"] integerValue], 0);
+}
+
+- (void)testLateReplacementRecoversImmediatelyOnReadinessEvenAfterRetryBudgetExpires
+{
+  RNCCollapsiblePagerViewComponentView *pager = [self pagerWithPageCount:1];
+  RNCNativeScrollerComponentView *previous = [self addScrollerToPager:pager atIndex:0];
+  previous.tag = 91003;
+  [pager attachScrollObserverForCurrentPage];
+  UIView *sharedHeader = [pager valueForKey:@"sharedHeaderHostView"];
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], previous.scrollView);
+
+  ShadowView removedView;
+  removedView.tag = (Tag)previous.tag;
+  MountingTransaction removal(1, 1, {ShadowViewMutation::RemoveMutation(1, removedView, 0)}, {});
+  SurfaceTelemetry telemetry;
+  [pager mountingTransactionWillMount:removal withSurfaceTelemetry:telemetry];
+  [previous removeFromSuperview];
+  [self finishMount:pager];
+  XCTAssertNil([pager valueForKey:@"observedScrollView"]);
+
+  // Simulate retry budget exhaustion before the replacement becomes ready.
+  [pager setValue:@12 forKey:@"scrollResolveRetryAttempt"];
+  [pager setValue:@NO forKey:@"scrollResolveRetryScheduled"];
+  NSUInteger oldToken = [[pager valueForKey:@"scrollResolveRetryToken"] unsignedIntegerValue];
+  [pager setValue:@(oldToken + 1) forKey:@"scrollResolveRetryToken"];
+
+  UIViewController *page = [pager valueForKey:@"pageControllers"][0];
+  UICollectionView *lateList = [[UICollectionView alloc]
+    initWithFrame:CGRectMake(0, 0, 320, 600)
+    collectionViewLayout:[UICollectionViewFlowLayout new]];
+  [page.view addSubview:lateList];
+
+  // Readiness notification triggers immediate reconcile even after retry budget expired.
+  [[NSNotificationCenter defaultCenter]
+    postNotificationName:@"OneKeyNativeScrollViewDidBecomeReady"
+                  object:lateList];
+  XCTAssertEqualObjects([pager valueForKey:@"pendingFallbackScrollView"], lateList);
+
+  // Explicit scroller readiness attaches synchronously with zero debounce delay.
+  [lateList removeFromSuperview];
+  RNCNativeScrollerComponentView *lateScroller = [self addScrollerToPager:pager atIndex:0];
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], lateScroller.scrollView);
+  XCTAssertEqual(sharedHeader.superview, lateScroller.scrollView);
+  XCTAssertEqualWithAccuracy(lateScroller.scrollView.contentInset.top, 164, 0.01);
+  XCTAssertNil([pager valueForKey:@"releasedPageScrollStates"][@"page-0"]);
+}
+
 @end

package/ios/tests/RNCCollapsiblePagerPressCancellationTests.mm

@@ -668,6 +668,7 @@ typedef struct __IOHIDEvent *RNCTestHIDEventRef;
 @property (nonatomic, strong) RNCSynthesizedTouchDriver *driver;
 @property (nonatomic, strong) UIView *firstPage;
 @property (nonatomic) NSUInteger longPressBegins;
+@property (nonatomic, strong) XCTestExpectation *longPressExpectation;
 @property (nonatomic) NSUInteger pagerPanBegins;
 @end
 
@@ -1001,7 +1002,10 @@ typedef struct __IOHIDEvent *RNCTestHIDEventRef;
 
 - (void)nestedLongPress:(UILongPressGestureRecognizer *)recognizer
 {
-  if (recognizer.state == UIGestureRecognizerStateBegan) self.longPressBegins += 1;
+  if (recognizer.state == UIGestureRecognizerStateBegan) {
+    self.longPressBegins += 1;
+    [self.longPressExpectation fulfill];
+  }
 }
 
 - (CGPoint)pressPointInNestedScrollView:(UIScrollView *)scroll
@@ -1022,14 +1026,12 @@ typedef struct __IOHIDEvent *RNCTestHIDEventRef;
   [pager addGestureRecognizer:longPress];
   // Exercise production wiring after a root recognizer is attached.
   ((void (*)(id, SEL))objc_msgSend)(self.pager, NSSelectorFromString(@"connectVerticalPagerGuard"));
+  self.longPressExpectation = [self expectationWithDescription:@"root long press recognized before finger-up"];
   UITouch *touch = [self.driver beginAt:[self pressPoint]];
   UIGestureRecognizer *guard = [self.pager valueForKey:@"verticalPagerGesture"];
   XCTAssertEqual(guard.state, UIGestureRecognizerStatePossible);
   XCTAssertEqual(pager.panGestureRecognizer.minimumNumberOfTouches, 2);
-  XCTestExpectation *hold = [self expectationWithDescription:@"root stationary finger held"];
-  dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(0.25 * NSEC_PER_SEC)),
-                 dispatch_get_main_queue(), ^{ [hold fulfill]; });
-  [self waitForExpectations:@[hold] timeout:2];
+  [self waitForExpectations:@[self.longPressExpectation] timeout:2];
   NSLog(@"[PagerPressDelivery] rootLongPress begins=%lu state=%ld touchPhase=%ld guardState=%ld pagerPanMinTouches=%lu",
         (unsigned long)self.longPressBegins, (long)longPress.state, (long)touch.phase,
         (long)guard.state, (unsigned long)pager.panGestureRecognizer.minimumNumberOfTouches);
@@ -1045,14 +1047,12 @@ typedef struct __IOHIDEvent *RNCTestHIDEventRef;
 - (void)testNestedStationaryNativeLongPressRecognizesBeforeFingerUp
 {
   UIScrollView *scroll = [self mountNestedHorizontalScrollView];
+  self.longPressExpectation = [self expectationWithDescription:@"nested long press recognized before finger-up"];
   UITouch *touch = [self.driver beginAt:[self pressPointInNestedScrollView:scroll]];
   UIGestureRecognizer *guard = [self.pager valueForKey:@"verticalPagerGesture"];
   XCTAssertEqual(guard.state, UIGestureRecognizerStatePossible);
   XCTAssertEqual(scroll.panGestureRecognizer.minimumNumberOfTouches, 2);
-  XCTestExpectation *hold = [self expectationWithDescription:@"stationary finger held"];
-  dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(0.25 * NSEC_PER_SEC)),
-                 dispatch_get_main_queue(), ^{ [hold fulfill]; });
-  [self waitForExpectations:@[hold] timeout:2];
+  [self waitForExpectations:@[self.longPressExpectation] timeout:2];
   // The real UIKit target action must arrive while the finger is still down.
   XCTAssertEqual(self.longPressBegins, 1);
   XCTAssertEqual(touch.phase, UITouchPhaseBegan);

package/package.json

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