@onekeyfe/react-native-pager-view 6.7.0-2 → 6.7.0-21

package/ios/RNCCollapsiblePagerViewComponentView.mm

@@ -18,6 +18,7 @@
 
 // OneKey patch: deduplicate structural mutation parents before scanning the page.
 #include <unordered_set>
+#include <cmath>
 
 using namespace facebook::react;
 
@@ -25,6 +26,7 @@ static void *RNCCollapsiblePagerContentOffsetContext = &RNCCollapsiblePagerConte
 static void *RNCRefreshControlLayerContext = &RNCRefreshControlLayerContext;
 static void *RNCScrollRefreshControlContext = &RNCScrollRefreshControlContext;
 static char RNCRefreshControlOffsetKey;
+static void RNCCollapsiblePagerLog(NSString *message);
 
 @interface RNCRefreshControlOffsetState : NSObject
 + (void)setOffset:(CGFloat)offset forControl:(UIRefreshControl *)control owner:(id)owner;
@@ -39,6 +41,10 @@ static char RNCRefreshControlOffsetKey;
   BOOL _originalMasksToBounds;
   BOOL _applying;
   BOOL _observing;
+  CGFloat _lastLoggedOffset;
+  NSUInteger _lastLoggedOwnerCount;
+  CGFloat _lastLoggedTransformY;
+  BOOL _hasLoggedState;
 }
 
 - (instancetype)initWithControl:(UIRefreshControl *)control
@@ -79,6 +85,21 @@ static char RNCRefreshControlOffsetKey;
   }
   [CATransaction commit];
   _applying = NO;
+#if DEBUG
+  if (!_hasLoggedState || fabs(_lastLoggedOffset - offset) > 0.01 ||
+      _lastLoggedOwnerCount != _offsets.count ||
+      fabs(_lastLoggedTransformY - transform.m42) > 0.01) {
+    _hasLoggedState = YES;
+    _lastLoggedOffset = offset;
+    _lastLoggedOwnerCount = _offsets.count;
+    _lastLoggedTransformY = transform.m42;
+    RNCCollapsiblePagerLog([NSString stringWithFormat:
+      @"[IOS-HOME-VISUAL] epochMs=%.0f monoMs=%.0f phase=refresh-transform ownerCount=%lu offsetSum=%.1f baselineY=%.1f appliedY=%.1f masksToBounds=%d",
+      [NSDate.date timeIntervalSince1970] * 1000, CACurrentMediaTime() * 1000,
+      (unsigned long)_offsets.count, offset, _baselineTransform.m42,
+      transform.m42, control.layer.masksToBounds]);
+  }
+#endif
 }
 
 + (void)setOffset:(CGFloat)offset forControl:(UIRefreshControl *)control owner:(id)owner
@@ -137,6 +158,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
@@ -348,7 +383,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 @property (nonatomic, copy) RNCCollapsiblePagerNativeTabPressHandler onTabPress;
 - (void)updateItemsJSON:(NSString *)itemsJSON;
 - (void)updateStyleWithHeight:(CGFloat)height
+                      variant:(NSString *)variant
      contentPaddingHorizontal:(CGFloat)contentPaddingHorizontal
+       contentPaddingVertical:(CGFloat)contentPaddingVertical
                   itemSpacing:(CGFloat)itemSpacing
                      fontSize:(CGFloat)fontSize
                    fontFamily:(NSString *)fontFamily
@@ -365,12 +402,15 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 @implementation RNCCollapsiblePagerNativeTabBarView {
   RNCCollapsiblePagerHorizontalScrollView *_scrollView;
+  UIView *_trackView;
   UIView *_indicatorView;
   NSArray<NSDictionary *> *_items;
   NSMutableArray<UIButton *> *_buttons;
   NSMutableArray<NSValue *> *_indicatorFrames;
   CGFloat _barHeight;
   CGFloat _contentPaddingHorizontal;
+  CGFloat _contentPaddingVertical;
+  BOOL _segmented;
   CGFloat _itemSpacing;
   CGFloat _fontSize;
   NSString *_fontFamily;
@@ -393,6 +433,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _indicatorFrames = [NSMutableArray new];
     _barHeight = 44;
     _contentPaddingHorizontal = 20;
+    _contentPaddingVertical = 0;
+    _segmented = NO;
     _itemSpacing = 8;
     _fontSize = 16;
     _activeTextColor = UIColor.labelColor;
@@ -414,6 +456,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _scrollView.delegate = self;
     [self addSubview:_scrollView];
 
+    _trackView = [UIView new];
+    _trackView.userInteractionEnabled = NO;
+    [_scrollView addSubview:_trackView];
+
     _indicatorView = [UIView new];
     _indicatorView.userInteractionEnabled = NO;
     [_scrollView addSubview:_indicatorView];
@@ -468,7 +514,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 }
 
 - (void)updateStyleWithHeight:(CGFloat)height
+                      variant:(NSString *)variant
      contentPaddingHorizontal:(CGFloat)contentPaddingHorizontal
+       contentPaddingVertical:(CGFloat)contentPaddingVertical
                   itemSpacing:(CGFloat)itemSpacing
                      fontSize:(CGFloat)fontSize
                    fontFamily:(NSString *)fontFamily
@@ -480,19 +528,26 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
               indicatorBottom:(CGFloat)indicatorBottom
 {
   _barHeight = MAX(1, height);
+  BOOL wasSegmented = _segmented;
+  _segmented = [variant isEqualToString:@"segmented"];
   _contentPaddingHorizontal = MAX(0, contentPaddingHorizontal);
+  _contentPaddingVertical = MAX(0, contentPaddingVertical);
   _itemSpacing = MAX(0, itemSpacing);
   _fontSize = MAX(1, fontSize);
   _fontFamily = [fontFamily copy];
-  self.backgroundColor = backgroundColor ?: UIColor.clearColor;
+  self.backgroundColor = _segmented ? UIColor.clearColor : (backgroundColor ?: UIColor.clearColor);
   _scrollView.backgroundColor = self.backgroundColor;
+  _scrollView.scrollEnabled = !_segmented;
+  if (_segmented && !wasSegmented) [_scrollView setContentOffset:CGPointZero animated:NO];
+  _trackView.hidden = !_segmented;
+  _trackView.backgroundColor = backgroundColor ?: UIColor.clearColor;
   _activeTextColor = activeTextColor ?: UIColor.labelColor;
   _inactiveTextColor = inactiveTextColor ?: UIColor.secondaryLabelColor;
   _indicatorColor = indicatorColor ?: _activeTextColor;
   _indicatorHeight = MAX(0, indicatorHeight);
   _indicatorBottom = MAX(0, indicatorBottom);
   _indicatorView.backgroundColor = _indicatorColor;
-  _indicatorView.layer.cornerRadius = _indicatorHeight / 2;
+  _indicatorView.layer.cornerRadius = _segmented ? 0 : _indicatorHeight / 2;
   for (UIButton *button in _buttons) button.titleLabel.font = self.tabFont;
   [self setNeedsLayout];
 }
@@ -551,6 +606,33 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 {
   [super layoutSubviews];
   _scrollView.frame = self.bounds;
+  if (_segmented) {
+    CGFloat width = CGRectGetWidth(self.bounds);
+    CGFloat height = CGRectGetHeight(self.bounds);
+    CGFloat insetX = MIN(_contentPaddingHorizontal, width / 2);
+    CGFloat insetY = MIN(_contentPaddingVertical, height / 2);
+    CGRect trackFrame = CGRectMake(insetX, insetY,
+      MAX(0, width - 2 * insetX), MAX(0, height - 2 * insetY));
+    _trackView.frame = trackFrame;
+    _trackView.layer.cornerRadius = CGRectGetHeight(trackFrame) / 2;
+    _scrollView.contentSize = self.bounds.size;
+    [_indicatorFrames removeAllObjects];
+    NSUInteger count = _buttons.count;
+    [_buttons enumerateObjectsUsingBlock:^(UIButton *button, NSUInteger index, BOOL *stop) {
+      CGFloat first = CGRectGetMinX(trackFrame) + CGRectGetWidth(trackFrame) * index / count;
+      CGFloat last = CGRectGetMinX(trackFrame) + CGRectGetWidth(trackFrame) * (index + 1) / count;
+      CGFloat x = self->_leftToRight ? first : CGRectGetMaxX(trackFrame) - (last - CGRectGetMinX(trackFrame));
+      CGFloat end = self->_leftToRight ? last : CGRectGetMaxX(trackFrame) - (first - CGRectGetMinX(trackFrame));
+      button.frame = CGRectMake(x, CGRectGetMinY(trackFrame), MAX(0, end - x), CGRectGetHeight(trackFrame));
+      CGRect thumbFrame = CGRectMake(x + 2, CGRectGetMinY(trackFrame) + 2,
+        MAX(0, CGRectGetWidth(button.frame) - 4), MAX(0, CGRectGetHeight(trackFrame) - 4));
+      [self->_indicatorFrames addObject:[NSValue valueWithCGRect:thumbFrame]];
+    }];
+    _indicatorView.layer.cornerRadius = MAX(0, CGRectGetHeight(trackFrame) - 4) / 2;
+    [self updatePresentation];
+    return;
+  }
+  _trackView.frame = CGRectZero;
   UIFont *font = self.tabFont;
   NSMutableArray<NSNumber *> *widths = [NSMutableArray arrayWithCapacity:_buttons.count];
   CGFloat itemsWidth = 0;
@@ -614,10 +696,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     CGRectGetMinX(fromFrame) + (CGRectGetMinX(toFrame) - CGRectGetMinX(fromFrame)) * fraction,
     CGRectGetMinY(fromFrame),
     CGRectGetWidth(fromFrame) + (CGRectGetWidth(toFrame) - CGRectGetWidth(fromFrame)) * fraction,
-    _indicatorHeight
+    _segmented ? CGRectGetHeight(fromFrame) : _indicatorHeight
   );
   _indicatorView.frame = indicatorFrame;
-  _indicatorView.hidden = _indicatorHeight <= 0;
+  _indicatorView.hidden = CGRectGetHeight(indicatorFrame) <= 0;
 
   NSInteger selectedIndex = (NSInteger)round(progress);
   [_buttons enumerateObjectsUsingBlock:^(UIButton *button, NSUInteger index, BOOL *stop) {
@@ -634,7 +716,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       : UIAccessibilityTraitButton;
   }];
 
-  if (_shouldCenterSelectedItem && !_scrollView.tracking && !_scrollView.dragging &&
+  if (_shouldCenterSelectedItem && !_segmented && !_scrollView.tracking && !_scrollView.dragging &&
       !_scrollView.decelerating && CGRectGetWidth(_scrollView.bounds) > 0) {
     CGFloat maximumOffset = MAX(0, _scrollView.contentSize.width - CGRectGetWidth(_scrollView.bounds));
     CGFloat desiredOffset = RNCClamp(
@@ -1451,23 +1533,29 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 - (void)liftSharedHeadersForPagerTransition:(NSString *)reason;
 - (void)restoreSharedHeadersToContainer;
 - (void)layoutSharedHeaders;
+- (void)bringReservedStickyControlToFront;
 - (void)restorePinnedStickyHeader;
 - (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;
 - (void)detachSharedHeaderPressCancellationGesture;
 - (void)updateRefreshControlForScrollView:(UIScrollView *)scrollView;
 - (void)releaseRefreshControlForScrollView:(UIScrollView *)scrollView;
+- (void)logHomeVisualGeometry:(NSString *)phase scrollView:(UIScrollView *)scrollView;
 - (void)cancelTopInsetReboundCheck;
 - (void)scheduleTopInsetReboundCheck;
 - (void)syncScrollEdgeAppearance;
 - (void)updateHardEdgeSeparatorCovers;
+- (void)updateTopOverlayThemeBackground;
 - (void)updateScrollEdgeContentMasks;
 - (void)restoreScrollEdgeContentMasks;
 - (void)sharedHeaderPressCancellationGestureChanged:(UIPanGestureRecognizer *)recognizer;
@@ -1506,6 +1594,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   UILabel *_stickyEdgeMarker;
   CALayer *_topEdgeSeparatorCover;
   CALayer *_stickyEdgeSeparatorCover;
+  CALayer *_topOverlayThemeBackgroundLayer;
   __weak UIView *_topEdgeInteractionHost;
   __weak UIView *_stickyEdgeInteractionHost;
   __weak UIScrollView *_topEdgeScrollView;
@@ -1535,6 +1624,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   NSUInteger _pendingTopInsetReboundGeneration;
   NSTimer *_topInsetReboundTimer;
   CGFloat _nativeTabBarHeight;
+  CGFloat _nativeTabBarTrailingReservedWidth;
   CGFloat _nativeSubHeaderHeight;
   CGFloat _headerOffset;
   BOOL _scrollEnabled;
@@ -1576,6 +1666,13 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   NSMapTable<UIScrollView *, NSValue *> *_originalInsets;
   NSMapTable<UIScrollView *, UIRefreshControl *> *_managedRefreshControls;
   NSHashTable<UIScrollView *> *_refreshControlObservedScrollViews;
+  CFTimeInterval _homeVisualLastScrollLog;
+  CFTimeInterval _homeVisualLastLayoutLog;
+  CFTimeInterval _homeVisualStartMono;
+  NSString *_homeVisualLastGeometrySignature;
+  CGFloat _homeVisualLastThemeOpacity;
+  CFTimeInterval _homeVisualLastThemeLog;
+  BOOL _homeVisualThemeHolding;
   NSMapTable<UIScrollView *, NSNumber *> *_appliedTopInsets;
   NSMapTable<UIScrollView *, NSValue *> *_originalIndicatorInsets;
   NSMapTable<UIScrollView *, NSNumber *> *_originalAlwaysBounceVertical;
@@ -1614,6 +1711,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   RNCCollapsiblePagerOuterPagerPanGestureRecognizer *_sharedHeaderOuterPagerGesture;
   RNCCollapsiblePagerVerticalPagerGuardGestureRecognizer *_verticalPagerGesture;
   BOOL _observingContentOffset;
+  BOOL _awaitingScrollOwnerForCurrentPage;
+  BOOL _scrollReconcileScheduled;
   BOOL _scrollResolveRetryScheduled;
   CFTimeInterval _pendingFallbackScrollViewDetectedAt;
   NSInteger _scrollResolveRetryPageIndex;
@@ -1645,6 +1744,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];
@@ -1803,6 +1904,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [self updateTopScrollEdgeForScrollView:_observedScrollView];
   [self updateSharedHeaderPressCancellationGesture];
   [self updateHeaderSettledStateForceBusy:NO];
+  [self logHomeVisualGeometry:@"window" scrollView:_observedScrollView];
   for (UIScrollView *scrollView in _originalInsets.keyEnumerator) {
     [self updateNativeScrollerViewport:scrollView stickyHeight:self.window == nil ? 0 : _stickyHeaderHeight + self.effectiveTopOverlayHeight];
   }
@@ -1830,7 +1932,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (CGFloat)effectiveTopOverlayHeight
 {
-  return _topOverlayView != nil ? _topOverlayHeight : _externalTopOverlayHeight;
+  BOOL localOverlayPending = _topScrollEdgeEnabled && _topOverlayHeight > 0 &&
+    _externalTopOverlayTag <= 0;
+  return _topOverlayView != nil || localOverlayPending
+    ? _topOverlayHeight : _externalTopOverlayHeight;
 }
 
 - (BOOL)hasFixedTopOverlay
@@ -1913,6 +2018,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [super traitCollectionDidChange:previousTraitCollection];
   if (previousTraitCollection.userInterfaceStyle != self.traitCollection.userInterfaceStyle) {
     [self syncScrollEdgeAppearance];
+    [self updateTopOverlayThemeBackground];
+    [self logHomeVisualGeometry:@"trait" scrollView:_observedScrollView];
   }
 }
 
@@ -1962,6 +2069,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     self.window != nil && !_isBeingRecycled;
   if (!enabled) {
     [self restoreScrollEdgeContentMasks];
+    [self updateTopOverlayThemeBackground];
     return;
   }
   if (self.hasFixedTopOverlay && _sharedHeaderHostView.window == self.window &&
@@ -2031,6 +2139,102 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     [_ownedPageMasks removeObjectForKey:page];
     [_originalPageMasks removeObjectForKey:page];
   }
+  [self updateTopOverlayThemeBackground];
+}
+
+- (void)updateTopOverlayThemeBackground
+{
+  if (@available(iOS 27.0, *)) {
+    BOOL localHardOverlay = !_isBeingRecycled && _topScrollEdgeEnabled &&
+      _topScrollEdgeEffect == RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard &&
+      _nativeSmoothHeaderScrollEnabled && _topOverlayView != nil &&
+      _externalTopOverlayTag <= 0 && _topOverlayHeight > 0 && _headerHeight > 0 &&
+      _topOverlayHostView.window == self.window && self.window != nil &&
+      !CGRectIsEmpty(_topOverlayHostView.bounds);
+    if (!localHardOverlay) {
+      [_topOverlayThemeBackgroundLayer removeFromSuperlayer];
+      _topOverlayThemeBackgroundLayer = nil;
+      _homeVisualThemeHolding = NO;
+      return;
+    }
+
+    UIColor *color = nil;
+    for (UIView *view = self; view != nil; view = view.superview) {
+      UIColor *candidate = [view.backgroundColor resolvedColorWithTraitCollection:
+        _topOverlayHostView.traitCollection];
+      if (candidate != nil && CGColorGetAlpha(candidate.CGColor) >= 1) {
+        color = candidate;
+        break;
+      }
+    }
+    if (color == nil) {
+      [_topOverlayThemeBackgroundLayer removeFromSuperlayer];
+      _topOverlayThemeBackgroundLayer = nil;
+      return;
+    }
+
+    UIScrollView *scrollView = _observedScrollView;
+    BOOL geometryReady = scrollView != nil &&
+      _sharedHeaderScrollView == scrollView && _topEdgeScrollView == scrollView &&
+      _topEdgeInteraction.scrollView == scrollView &&
+      scrollView.topEdgeEffect.style == UIScrollEdgeEffectStyle.hardStyle &&
+      _sharedHeaderMaskView != nil &&
+      _sharedHeaderHostView.maskView == _sharedHeaderMaskView &&
+      _headerView.window == self.window;
+    if (_topOverlayThemeBackgroundLayer == nil && !geometryReady) return;
+    BOOL created = _topOverlayThemeBackgroundLayer == nil;
+    if (created) {
+      _topOverlayThemeBackgroundLayer = [CALayer layer];
+      _topOverlayThemeBackgroundLayer.name = @"onekey-top-overlay-theme-background";
+      _topOverlayThemeBackgroundLayer.actions = @{
+        @"position": NSNull.null, @"bounds": NSNull.null,
+        @"opacity": NSNull.null, @"backgroundColor": NSNull.null
+      };
+      [_topOverlayHostView.layer insertSublayer:_topOverlayThemeBackgroundLayer atIndex:0];
+    }
+    _topOverlayThemeBackgroundLayer.frame = _topOverlayHostView.bounds;
+    _topOverlayThemeBackgroundLayer.backgroundColor = color.CGColor;
+    if (!geometryReady) {
+      if (!_homeVisualThemeHolding) {
+        _homeVisualThemeHolding = YES;
+#if DEBUG
+        RNCCollapsiblePagerLog([NSString stringWithFormat:
+          @"[IOS-HOME-VISUAL] phase=theme-background-hold pagerTag=%ld generation=%lu pageIndex=%ld opacity=%.3f",
+          (long)self.tag, (unsigned long)_generation, (long)_currentIndex,
+          _topOverlayThemeBackgroundLayer.opacity]);
+#endif
+      }
+      return;
+    }
+    _homeVisualThemeHolding = NO;
+    CGRect overlayWindow = [_topOverlayHostView convertRect:_topOverlayHostView.bounds
+                                                     toView:self.window];
+    CGRect headerWindow = [_headerView convertRect:_headerView.bounds
+                                           toView:self.window];
+    CGFloat overlayBottom = CGRectGetMaxY(overlayWindow);
+    CGFloat collapse = MIN(MAX(overlayBottom - CGRectGetMinY(headerWindow), 0),
+      _headerHeight);
+    CGFloat opacity = 1 - collapse / _headerHeight;
+    _topOverlayThemeBackgroundLayer.opacity = opacity;
+#if DEBUG
+    CFTimeInterval now = CACurrentMediaTime();
+    if (created || fabs(opacity - _homeVisualLastThemeOpacity) >= 0.1 ||
+        now - _homeVisualLastThemeLog >= 2.0) {
+      _homeVisualLastThemeOpacity = opacity;
+      _homeVisualLastThemeLog = now;
+      CGFloat red = 0, green = 0, blue = 0, alpha = 0;
+      [color getRed:&red green:&green blue:&blue alpha:&alpha];
+      RNCCollapsiblePagerLog([NSString stringWithFormat:
+        @"[IOS-HOME-VISUAL] phase=theme-background epochMs=%.0f monoMs=%.0f pagerTag=%ld generation=%lu pageIndex=%ld opacity=%.3f collapse=%.1f header=%.1f overlayBottom=%.1f headerY=%.1f bodyYEstimate=%.1f hardOwner=%d rgba=%.3f,%.3f,%.3f,%.3f",
+        NSDate.date.timeIntervalSince1970 * 1000, now * 1000,
+        (long)self.tag, (unsigned long)_generation, (long)_currentIndex,
+        opacity, collapse, (CGFloat)_headerHeight, overlayBottom,
+        CGRectGetMinY(headerWindow), overlayBottom + _headerHeight +
+          _stickyHeaderHeight - collapse, _topEdgeInteraction.scrollView == scrollView,
+        red, green, blue, alpha]);
+    }
+#endif
+  }
 }
 
 - (void)updateEventEmitter:(const EventEmitter::Shared &)eventEmitter
@@ -2187,6 +2391,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
         CGRectGetWidth(_containerView.bounds), pixel);
       cover.contentsScale = scale;
       cover.backgroundColor = color.CGColor;
+      cover.hidden = index == 0 && _stickyHeaderIsPinned;
     }
     if (index == 0) _topEdgeSeparatorCover = cover;
     else _stickyEdgeSeparatorCover = cover;
@@ -2198,6 +2403,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];
   }
@@ -2345,6 +2551,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   }
   [_nativeTabBarView updateAncestorGesturePrecedence];
   [_nativeSubHeaderView updateAncestorGesturePrecedence];
+  [self bringReservedStickyControlToFront];
 }
 
 - (void)restoreSharedHeadersToContainer
@@ -2450,10 +2657,11 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   CGFloat nativeTabBarVisibleHeight = _nativeTabBarView.hidden
     ? 0
     : MIN(_stickyHeaderHeight, _nativeTabBarHeight);
+  CGFloat tabReservedWidth = MIN(width, MAX(0, _nativeTabBarTrailingReservedWidth));
   _nativeTabBarView.frame = CGRectMake(
-    0,
+    self.isLtrLayout ? 0 : tabReservedWidth,
     stickyChildY,
-    width,
+    width - tabReservedWidth,
     nativeTabBarVisibleHeight
   );
   _nativeSubHeaderView.frame = CGRectMake(
@@ -2467,9 +2675,26 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   );
   _topOverlayHostView.frame = CGRectMake(0, 0, width, self.effectiveTopOverlayHeight);
   _topOverlayView.frame = _topOverlayHostView.bounds;
+  [self bringReservedStickyControlToFront];
   [self applyHeaderOffset];
 }
 
+- (void)bringReservedStickyControlToFront
+{
+  if (_stickyHeaderView != nil &&
+      _stickyHeaderView.superview == _nativeTabBarView.superview) {
+    if (_nativeTabBarTrailingReservedWidth > 0) {
+      [_stickyHeaderView.superview bringSubviewToFront:_stickyHeaderView];
+    } else {
+      [_nativeTabBarView.superview bringSubviewToFront:_nativeTabBarView];
+      if (!_nativeSubHeaderView.hidden &&
+          _nativeSubHeaderView.superview == _nativeTabBarView.superview) {
+        [_nativeSubHeaderView.superview bringSubviewToFront:_nativeSubHeaderView];
+      }
+    }
+  }
+}
+
 - (void)updatePinnedStickyHeader
 {
   BOOL attachedToList = _nativeSmoothHeaderScrollEnabled &&
@@ -2516,8 +2741,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   CGFloat childY = shouldPin ? 0 : _headerHeight;
   CGFloat width = CGRectGetWidth(self.bounds);
   CGFloat tabHeight = _nativeTabBarView.hidden ? 0 : MIN(_stickyHeaderHeight, _nativeTabBarHeight);
+  CGFloat tabReservedWidth = MIN(width, MAX(0, _nativeTabBarTrailingReservedWidth));
   _stickyHeaderView.frame = CGRectMake(0, childY, width, _stickyHeaderHeight);
-  _nativeTabBarView.frame = CGRectMake(0, childY, width, tabHeight);
+  _nativeTabBarView.frame = CGRectMake(self.isLtrLayout ? 0 : tabReservedWidth,
+    childY, width - tabReservedWidth, tabHeight);
   _nativeSubHeaderView.frame = CGRectMake(0, childY + tabHeight, width,
     MIN(MAX(0, _stickyHeaderHeight - tabHeight), _nativeSubHeaderHeight));
   _pinnedStickyHostView.hidden = !shouldPin;
@@ -2537,7 +2764,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   }
   [_nativeTabBarView updateAncestorGesturePrecedence];
   [_nativeSubHeaderView updateAncestorGesturePrecedence];
+  [self bringReservedStickyControlToFront];
   [self updateTopScrollEdgeForScrollView:_observedScrollView];
+  [self logHomeVisualGeometry:shouldPin ? @"pin" : @"unpin"
+                    scrollView:_observedScrollView];
 }
 
 - (void)preparePageForHorizontalTransitionAtIndex:(NSInteger)pageIndex
@@ -2689,6 +2919,15 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 - (void)mountingTransactionDidMount:(const MountingTransaction &)transaction
                withSurfaceTelemetry:(const SurfaceTelemetry &)surfaceTelemetry
 {
+  if (_needsSlotRebuild && _deferTopEdgeSlotRebuild &&
+      _topScrollEdgeEnabled && _nativeSmoothHeaderScrollEnabled &&
+      _topScrollEdgeEffect == RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard &&
+      _topOverlayHeight > 0 && _pageKeys.count > 0 &&
+      _externalTopOverlayTag <= 0 &&
+      _logicalChildren.count == _pageKeys.count + 3 &&
+      !_transitioning && !_isPagerDragging && !_isBeingRecycled) {
+    _deferTopEdgeSlotRebuild = NO;
+  }
   if (_needsSlotRebuild && !_deferTopEdgeSlotRebuild &&
       !_transitioning && !_isPagerDragging) {
     [self rebuildSlots];
@@ -2711,6 +2950,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   }
   [self updateScrollEdgeContentMasks];
   [_mountingRemovedScrollViews removeAllObjects];
+  [self logHomeVisualGeometry:@"did-mount" scrollView:_observedScrollView];
   if (!_nativeSmoothHeaderScrollEnabled || _isBeingRecycled || self.window == nil ||
       _currentIndex < 0 || _currentIndex >= _pageControllers.count) return;
   // Prepare newly mounted owned scrollers before their first frame, even while
@@ -2728,6 +2968,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
@@ -2736,7 +2993,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;
@@ -2904,18 +3160,14 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (_stickyHeaderView != nil) [_sharedHeaderHostView bringSubviewToFront:_stickyHeaderView];
   if (!_nativeTabBarView.hidden) [_sharedHeaderHostView bringSubviewToFront:_nativeTabBarView];
   if (!_nativeSubHeaderView.hidden) [_sharedHeaderHostView bringSubviewToFront:_nativeSubHeaderView];
+  [self bringReservedStickyControlToFront];
   [_containerView bringSubviewToFront:_sharedHeaderHostView];
   if (_stickyHeaderIsPinned) {
     [_pinnedStickyHostView.superview bringSubviewToFront:_pinnedStickyHostView];
   }
   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
@@ -2991,12 +3243,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [self updateTopScrollEdgeForScrollView:_observedScrollView];
   [self updateScrollEdgeContentMasks];
   [self updateHeaderSettledStateForceBusy:NO];
-  dispatch_async(dispatch_get_main_queue(), ^{
-    if (!self->_isBeingRecycled) {
-      [self prepareAdjacentPageInsets];
-      [self attachScrollObserverForCurrentPage];
-    }
-  });
+  [self logHomeVisualGeometry:@"layout" scrollView:_observedScrollView];
+  [self scheduleCoalescedScrollReconcile];
 }
 
 - (void)prepareForRecycle
@@ -3014,6 +3262,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   _generation++;
   [_mountingRemovedScrollViews removeAllObjects];
   _needsScrollObserverReattachAfterMount = NO;
+  _awaitingScrollOwnerForCurrentPage = NO;
+  _scrollReconcileScheduled = NO;
   [_releasedPageScrollStates removeAllObjects];
   [self detachSharedHeaderPressCancellationGesture];
   [self detachScrollObserver];
@@ -3110,7 +3360,12 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   _externalOuterTransitioning = NO;
   _topScrollEdgeEnabled = NO;
   _topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::None;
+  _homeVisualStartMono = 0;
+  _homeVisualLastScrollLog = 0;
+  _homeVisualLastLayoutLog = 0;
+  _homeVisualLastGeometrySignature = nil;
   _nativeTabBarHeight = 44;
+  _nativeTabBarTrailingReservedWidth = 0;
   _nativeSubHeaderHeight = 74;
   _headerOffset = 0;
   _currentLogicalOffset = 0;
@@ -3192,6 +3447,13 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _layoutDirection = RCTNSStringFromString(toString(newViewProps.layoutDirection));
     [_nativeTabBarView setLeftToRight:self.isLtrLayout];
     [_nativeSubHeaderView setLeftToRight:self.isLtrLayout];
+    [self setNeedsLayout];
+  }
+  if (_needsPropsReapply ||
+      oldViewProps.nativeTabBarTrailingReservedWidth != newViewProps.nativeTabBarTrailingReservedWidth) {
+    double reserved = newViewProps.nativeTabBarTrailingReservedWidth;
+    _nativeTabBarTrailingReservedWidth = std::isfinite(reserved) && reserved >= 0 ? reserved : 0;
+    [self setNeedsLayout];
   }
   BOOL insetsChanged = NO;
   if (_needsPropsReapply || oldViewProps.headerHeight != newViewProps.headerHeight) {
@@ -3272,7 +3534,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   }
   if (_needsPropsReapply ||
       oldViewProps.nativeTabBarHeight != newViewProps.nativeTabBarHeight ||
+      oldViewProps.nativeTabBarVariant != newViewProps.nativeTabBarVariant ||
       oldViewProps.nativeTabBarContentPaddingHorizontal != newViewProps.nativeTabBarContentPaddingHorizontal ||
+      oldViewProps.nativeTabBarContentPaddingVertical != newViewProps.nativeTabBarContentPaddingVertical ||
       oldViewProps.nativeTabBarItemSpacing != newViewProps.nativeTabBarItemSpacing ||
       oldViewProps.nativeTabBarFontSize != newViewProps.nativeTabBarFontSize ||
       oldViewProps.nativeTabBarFontFamily != newViewProps.nativeTabBarFontFamily ||
@@ -3289,7 +3553,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     NSString *fontFamily = RCTNSStringFromString(newViewProps.nativeTabBarFontFamily);
     [_nativeTabBarView
       updateStyleWithHeight:_nativeTabBarHeight
+      variant:RCTNSStringFromString(newViewProps.nativeTabBarVariant)
       contentPaddingHorizontal:MAX(0, newViewProps.nativeTabBarContentPaddingHorizontal)
+      contentPaddingVertical:MAX(0, newViewProps.nativeTabBarContentPaddingVertical)
       itemSpacing:MAX(0, newViewProps.nativeTabBarItemSpacing)
       fontSize:newViewProps.nativeTabBarFontSize > 0 ? newViewProps.nativeTabBarFontSize : 16
       fontFamily:fontFamily
@@ -3314,6 +3580,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (insetsChanged) {
     [self reapplyInsetsToObservedScrollView];
     [self setNeedsLayout];
+    [self logHomeVisualGeometry:@"props-inset" scrollView:_observedScrollView];
   }
   _applyingTopOverlayInsetChange = NO;
   if (!_nativeTabBarView.hidden) {
@@ -3322,6 +3589,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (!_nativeSubHeaderView.hidden) {
     [_nativeSubHeaderView.superview bringSubviewToFront:_nativeSubHeaderView];
   }
+  [self bringReservedStickyControlToFront];
   [_sharedHeaderHostView.superview bringSubviewToFront:_sharedHeaderHostView];
   if (_stickyHeaderIsPinned) {
     [_pinnedStickyHostView.superview bringSubviewToFront:_pinnedStickyHostView];
@@ -3349,12 +3617,107 @@ 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;
+          // React slots inside a verified list may own independent scroll views.
+          if (isMountedNativeList) return resolution;
+        }
+      }
+    }
+  } 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
@@ -3450,6 +3813,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 ||
@@ -3502,29 +3878,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();
@@ -3536,6 +3918,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       return;
     }
   }
+  _awaitingScrollOwnerForCurrentPage = NO;
   _scrollResolveRetryAttempt = 0;
   _scrollResolveRetryPageIndex = _currentIndex;
   _scrollResolveRetryToken += 1;
@@ -3894,8 +4277,105 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     [_managedRefreshControls removeObjectForKey:scrollView];
     if (current != nil) [_managedRefreshControls setObject:current forKey:scrollView];
   }
-  [RNCRefreshControlOffsetState setOffset:self.effectiveTopOverlayHeight + _headerHeight + _stickyHeaderHeight
+  [RNCRefreshControlOffsetState setOffset:_headerHeight + _stickyHeaderHeight
                              forControl:current owner:self];
+  if (previous != current) [self logHomeVisualGeometry:@"refresh-bind" scrollView:scrollView];
+}
+
+- (void)logHomeVisualGeometry:(NSString *)phase scrollView:(UIScrollView *)scrollView
+{
+#if DEBUG
+  if (self.window == nil || _isBeingRecycled) return;
+  CFTimeInterval now = CACurrentMediaTime();
+  if (_homeVisualStartMono == 0) _homeVisualStartMono = now;
+  if ([phase isEqualToString:@"pull"] && now - _homeVisualLastScrollLog < 0.2) return;
+  if ([phase isEqualToString:@"pull"]) _homeVisualLastScrollLog = now;
+  UIRefreshControl *control = scrollView.refreshControl;
+  CGRect controlWindow = control != nil
+    ? [control convertRect:control.bounds toView:self.window] : CGRectZero;
+  CGRect overlayWindow = [_topOverlayHostView convertRect:_topOverlayHostView.bounds
+                                                   toView:self.window];
+  CGRect stickyWindow = [_stickyHeaderView convertRect:_stickyHeaderView.bounds
+                                                toView:self.window];
+  CGRect maskWindow = _sharedHeaderMaskView != nil
+    ? [_sharedHeaderHostView convertRect:_sharedHeaderMaskView.frame toView:self.window]
+    : CGRectZero;
+  CGFloat pageMaskWindowY = [_containerView convertPoint:
+    CGPointMake(0, _pageMaskBoundary) toView:self.window].y;
+  BOOL layoutPhase = [phase isEqualToString:@"layout"] ||
+    [phase isEqualToString:@"did-mount"];
+  NSString *signature = [NSString stringWithFormat:
+    @"%.1f:%ld:%ld:%.1f:%d:%.1f:%.1f:%.1f:%d:%d",
+    self.effectiveTopOverlayHeight, (long)_headerHeight,
+    (long)_stickyHeaderHeight, scrollView.contentInset.top, control != nil,
+    CGRectGetMinY(maskWindow), CGRectGetHeight(maskWindow), _pageMaskBoundary,
+    _stickyHeaderIsPinned, _topScrollEdgeEnabled];
+  if (layoutPhase && now - _homeVisualStartMono >= 2.0 &&
+      [_homeVisualLastGeometrySignature isEqualToString:signature] &&
+      now - _homeVisualLastLayoutLog < 2.0) return;
+  if (layoutPhase) {
+    _homeVisualLastLayoutLog = now;
+    _homeVisualLastGeometrySignature = signature;
+  }
+  CGFloat visualYEstimate = CGRectGetMinY(controlWindow) +
+    (control != nil ? control.layer.sublayerTransform.m42 : 0);
+  CALayer *firstChild = control.layer.sublayers.firstObject;
+  BOOL childAttached = firstChild != nil && control.window == self.window;
+  CGRect firstChildWindow = childAttached
+    ? [firstChild convertRect:firstChild.bounds toLayer:self.window.layer]
+    : CGRectZero;
+  CGFloat overscroll = scrollView != nil
+    ? -(scrollView.contentOffset.y + scrollView.contentInset.top) : 0;
+  double epochMs = [NSDate.date timeIntervalSince1970] * 1000;
+  double monoMs = now * 1000;
+  RNCCollapsiblePagerLog([NSString stringWithFormat:
+    @"[IOS-HOME-VISUAL] epochMs=%.0f monoMs=%.0f phase=%@ pagerTag=%ld generation=%lu pageIndex=%ld window=%d edge=%d overlay=%.1f header=%ld sticky=%ld collapse=%.1f scrollY=%.1f insetTop=%.1f overscroll=%.1f refresh=%d refreshing=%d controlY=%.1f controlH=%.1f sublayerY=%.1f visualYEstimate=%.1f overlayY=%.1f overlayBottom=%.1f stickyY=%.1f stickyBottom=%.1f maskY=%.1f maskH=%.1f pageMaskWindowY=%.1f",
+    epochMs, monoMs, phase, (long)self.tag, (unsigned long)_generation,
+    (long)_currentIndex, self.window != nil, _topScrollEdgeEnabled,
+    self.effectiveTopOverlayHeight, (long)_headerHeight, (long)_stickyHeaderHeight,
+    _headerOffset, scrollView.contentOffset.y, scrollView.contentInset.top,
+    overscroll, control != nil, control.isRefreshing,
+    CGRectGetMinY(controlWindow), CGRectGetHeight(controlWindow),
+    control != nil ? control.layer.sublayerTransform.m42 : 0, visualYEstimate,
+    CGRectGetMinY(overlayWindow), CGRectGetMaxY(overlayWindow),
+    CGRectGetMinY(stickyWindow), CGRectGetMaxY(stickyWindow),
+    CGRectGetMinY(maskWindow), CGRectGetHeight(maskWindow), pageMaskWindowY]);
+  RNCCollapsiblePagerLog([NSString stringWithFormat:
+    @"[IOS-HOME-VISUAL] epochMs=%.0f monoMs=%.0f phase=%@-refresh-layer pagerTag=%ld generation=%lu pageIndex=%ld boundsY=%.1f boundsH=%.1f centerY=%.1f transformTY=%.1f layerPositionY=%.1f layerTransformY=%.1f directChildCount=%lu firstChildAttached=%d firstChildWindowY=%.1f firstChildWindowH=%.1f",
+    epochMs, monoMs, phase, (long)self.tag, (unsigned long)_generation,
+    (long)_currentIndex, control.bounds.origin.y, control.bounds.size.height,
+    control.center.y, control.transform.ty, control.layer.position.y,
+    control.layer.transform.m42, (unsigned long)control.layer.sublayers.count,
+    childAttached, CGRectGetMinY(firstChildWindow), CGRectGetHeight(firstChildWindow)]);
+  if (![phase isEqualToString:@"pull"]) {
+    CALayer *topCover = _topEdgeSeparatorCover;
+    CALayer *stickyCover = _stickyEdgeSeparatorCover;
+    UIColor *color = topCover.backgroundColor != nil
+      ? [UIColor colorWithCGColor:topCover.backgroundColor] : nil;
+    CGFloat red = 0, green = 0, blue = 0, alpha = 0;
+    [color getRed:&red green:&green blue:&blue alpha:&alpha];
+    CGRect topCoverWindow = topCover.superlayer != nil
+      ? [topCover convertRect:topCover.bounds toLayer:self.window.layer] : CGRectZero;
+    CGRect stickyCoverWindow = stickyCover.superlayer != nil
+      ? [stickyCover convertRect:stickyCover.bounds toLayer:self.window.layer] : CGRectZero;
+    RNCCollapsiblePagerLog([NSString stringWithFormat:
+      @"[IOS-HOME-VISUAL] epochMs=%.0f monoMs=%.0f phase=%@-edge pagerTag=%ld generation=%lu pageIndex=%ld trait=%ld override=%ld style=%ld pinned=%d topHostY=%.1f topHostBottom=%.1f stickyHostY=%.1f stickyHostBottom=%.1f topInteractionSameScroll=%d stickyInteractionSameScroll=%d topCover=%d topCoverHidden=%d topCoverY=%.1f topCoverH=%.3f stickyCover=%d stickyCoverHidden=%d stickyCoverY=%.1f stickyCoverH=%.3f coverRGBA=%.3f,%.3f,%.3f,%.3f scale=%.1f",
+      epochMs, monoMs, phase, (long)self.tag, (unsigned long)_generation,
+      (long)_currentIndex, (long)self.traitCollection.userInterfaceStyle,
+      (long)_topOverlayHostView.overrideUserInterfaceStyle,
+      (long)_topScrollEdgeEffect, _stickyHeaderIsPinned,
+      CGRectGetMinY(overlayWindow), CGRectGetMaxY(overlayWindow),
+      CGRectGetMinY(stickyWindow), CGRectGetMaxY(stickyWindow),
+      _topEdgeInteraction.scrollView == scrollView,
+      _stickyEdgeInteraction.scrollView == scrollView,
+      topCover != nil, topCover.hidden, CGRectGetMinY(topCoverWindow),
+      CGRectGetHeight(topCoverWindow), stickyCover != nil,
+      stickyCover.hidden,
+      CGRectGetMinY(stickyCoverWindow),
+      CGRectGetHeight(stickyCoverWindow), red, green, blue, alpha,
+      self.window.screen.scale]);
+  }
+#endif
 }
 
 - (void)releaseRefreshControlForScrollView:(UIScrollView *)scrollView
@@ -4189,8 +4669,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)updateNativeScrollerViewport:(UIScrollView *)scrollView stickyHeight:(CGFloat)height
 {
-  if ([scrollView.superview isKindOfClass:RNCNativeScrollerComponentView.class]) {
-    [(RNCNativeScrollerComponentView *)scrollView.superview setPagerStickyHeight:height forOwner:self];
+  id host = scrollView.superview;
+  if ([host respondsToSelector:@selector(setPagerStickyHeight:forOwner:)]) {
+    [host setPagerStickyHeight:height forOwner:self];
   }
 }
 
@@ -4262,6 +4743,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
 {
@@ -4313,6 +4854,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (context == RNCScrollRefreshControlContext) {
     UIScrollView *scrollView = (UIScrollView *)object;
     [self updateRefreshControlForScrollView:scrollView];
+    [self logHomeVisualGeometry:@"refresh-control-change" scrollView:scrollView];
     if (scrollView == _observedScrollView && !_syntheticPageRestore &&
         (!_nativeSmoothHeaderScrollEnabled || (!_transitioning && _transitionPageOffsets == nil))) {
       [self updateHeaderForScrollView:scrollView];
@@ -4320,6 +4862,11 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     return;
   }
   if (context == RNCCollapsiblePagerContentOffsetContext && object == _observedScrollView) {
+    if ([keyPath isEqualToString:@"contentOffset"] &&
+        -(((UIScrollView *)object).contentOffset.y +
+          ((UIScrollView *)object).contentInset.top) > 5) {
+      [self logHomeVisualGeometry:@"pull" scrollView:(UIScrollView *)object];
+    }
     if (_pendingTopInsetReboundScrollView == object &&
         ([keyPath isEqualToString:@"contentOffset"] || [keyPath isEqualToString:@"contentInset"])) {
       if (((UIScrollView *)object).panGestureRecognizer.state == UIGestureRecognizerStateChanged) {
@@ -4978,6 +5525,13 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 {
   UIScrollView *scrollView = _pagerTopScrollView;
   if (_dispatchingPagerTop || ![self matchesPagerTop:scrollView]) return;
+  CGFloat clampedTarget = MIN(MAX(_pagerTopLogicalTarget, 0), _headerHeight);
+  if (clampedTarget != _pagerTopLogicalTarget) {
+    _pagerTopLogicalTarget = clampedTarget;
+    CGFloat physicalTarget = RNCLimitRestoredScrollOffset(clampedTarget - scrollView.contentInset.top,
+      scrollView.contentSize.height, scrollView.bounds.size.height, scrollView.contentInset.top, scrollView.contentInset.bottom);
+    [scrollView setContentOffset:CGPointMake(scrollView.contentOffset.x, physicalTarget) animated:NO];
+  }
   CGFloat logical = scrollView.contentOffset.y + scrollView.contentInset.top;
   if (fabs(logical - _pagerTopLogicalTarget) > 0.5) return;
   _pageOffsets[_pagerTopPageKey] = @(_nativeSmoothHeaderScrollEnabled ? 0 : _pagerTopLogicalTarget);
@@ -4989,11 +5543,29 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 }
 
 - (void)scrollToTop:(NSInteger)target animated:(BOOL)animated
+{
+  if (target != 0 && target != 1) return;
+  [self scrollHeaderToOffset:(target == 1 ? _headerHeight : 0) animated:animated];
+}
+
+- (void)scrollHeaderBy:(double)delta
+{
+  if (!std::isfinite(delta)) return;
+  [self scrollHeaderToOffset:MIN(MAX(_headerOffset + delta, 0), _headerHeight) animated:NO];
+}
+
+- (void)scrollHeaderToOffset:(double)offset
+{
+  if (!std::isfinite(offset)) return;
+  [self scrollHeaderToOffset:MIN(MAX(offset, 0), _headerHeight) animated:NO];
+}
+
+- (void)scrollHeaderToOffset:(CGFloat)logicalTarget animated:(BOOL)animated
 {
   [self cancelTopInsetReboundCheck];
   UIScrollView *scrollView = _observedScrollView;
   NSString *key = _observedPageKey;
-  if ((target != 0 && target != 1) || _isBeingRecycled || _transitioning || _isPagerDragging ||
+  if (_isBeingRecycled || _transitioning || _isPagerDragging ||
       _transitionPageOffsets != nil || _syntheticPageRestore || scrollView == nil || scrollView.window == nil ||
       key == nil || ![key isEqualToString:self.currentPageKey] || _observedPageIndex != _currentIndex ||
       _observedPageGeneration != _generation || self.window == nil) return;
@@ -5009,7 +5581,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [_alignedBodyKeys removeObject:key];
   [_suspendedBodyKeys removeObject:key];
   [_displayBodyOverrides removeObjectForKey:key];
-  CGFloat logicalTarget = target == 1 ? _headerHeight : 0;
+  logicalTarget = MIN(MAX(logicalTarget, 0), _headerHeight);
   _pageOffsets[key] = @(_nativeSmoothHeaderScrollEnabled ? 0 : logicalTarget);
   _pagerTopScrollView = scrollView;
   _pagerTopPageKey = [key copy];