@onekeyfe/react-native-pager-view 6.7.0-5 → 6.7.0-7

package/docs/SPEC.md

@@ -14,17 +14,32 @@ valid prop values. Both the style and overlay are
 disabled by default. On iOS 26 or newer, a local overlay remains fixed at the
 top of the viewport while the owned vertical `UIScrollView` can draw behind it.
 The component measures the overlay's Fabric layout height and owns the
-corresponding top content inset. It binds UIKit's
+corresponding top content inset.
+For callers with a known initial height, `topOverlayHeightHint` reserves that
+height on the first frame after the overlay is enabled, before Fabric delivers
+`onLayout`. The measured height replaces the hint, and disabling the overlay
+clears the measurement so a later enablement can use a new hint. The hint does
+not enable the effect or reserve an inset without an active local overlay.
+This uses the existing native `topOverlayHeight` prop without changing the
+native interface. For native smooth local Hard mode, a complete Fabric mount
+attaches the overlay slot synchronously before `didMount` returns; incomplete
+slots retain the deferred fallback. It binds UIKit's
 `UIScrollEdgeElementContainerInteraction` to that exact scroll view and selects
 the requested top edge style. Hard has UIKit's dividing line; Soft has its
 gradual blurred transition. A pager owns the effect and inset for its current page;
 its nested NativeList or NativeScroller must not opt into another top overlay.
 Invisible, noninteractive native labels let UIKit recognize the React-drawn
 overlay and sticky header as scroll-edge elements. The pager does not add an
-auxiliary full-area glass or opaque material. It clips scrolling assets above
+auxiliary full-area glass. It clips scrolling assets above
 the fixed overlay boundary; during horizontal transitions it clips its owned
 visible page hosts below the current sticky boundary so text cannot pass in
 front of the fixed controls. Masked assets must not intercept their hit targets.
+On iOS 27 or newer, a local smooth Hard pager with a valid shared-header mask
+fades a bottommost overlay layer using the resolved opaque pager or ancestor
+theme color as the real header collapses, without hard-coded colors or changing
+UIKit's Hard style, owner or interactions. During temporary horizontal owner
+transitions the layer holds its last opacity until geometry is valid again;
+disabling the local overlay, changing style or recycling removes it.
 
 For an iOS 26 pager whose fixed header is rendered by a sibling in the same
 React surface, `externalTopOverlayTag` may identify that header's native view.
@@ -61,6 +76,8 @@ The measured overlay height is excluded from the collapsible header distance:
 overlay. Selection, cancellation, reuse and disposal rebind or release the
 interaction and restore any prior scroll-edge style. Native scroll/refresh
 coordination continues on the main thread without per-frame JavaScript work.
+Refresh retains the pager-owned `overlay + header + sticky` top inset but offsets
+the indicator by `header + sticky`, so its spinner begins below the fixed overlay.
 
 On iOS before 26, the external tag is not forwarded to native. On iOS before
 26, Android and Web the new props have no scroll-edge effect.
@@ -73,17 +90,15 @@ Acceptance requires real iOS 26 scrolling, partial collapse, short/empty page,
 refresh, page transition/cancellation, dynamic tabs and light/dark checks;
 source and build checks alone do not establish visual correctness.
 
-Experimental trial: `CollapsiblePagerView` paints a cover at each owned
+`CollapsiblePagerView` paints a cover at each owned
 fixed-overlay or pinned-sticky boundary with one physical pixel of the nearest
 opaque ancestor background color (system background if none is available).
 These native layers do not receive touches, change insets, or clip glass shadows.
 They are removed for Soft, disabled/detached effects, and recycling. This is a
-visual workaround using public layer APIs, not a UIKit separator setting; rendered
-light/dark, scrolling, and transition acceptance is pending. Standalone
+visual workaround using public layer APIs, not a UIKit separator setting. While
+the sticky header is pinned, only the top cover is hidden; it reappears on unpin,
+and the sticky cover and both Hard interactions remain active. Standalone
 NativeScroller and NativeList retain UIKit's unmodified Hard appearance.
-On the iOS 26.5 simulator, a runtime probe confirmed Hard and the cover layers,
-including pinned-header ownership. The original hairline was not reliably
-reproduced with the covers hidden, so separator suppression is not yet verified.
 
 Style selection crosses Fabric as the enum `none | hard | soft`, defaulting to
 `none`, rather than a hard-effect boolean. Switching Hard ↔ Soft on an attached

package/ios/RNCCollapsiblePagerViewComponentView.mm

@@ -25,6 +25,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 +40,10 @@ static char RNCRefreshControlOffsetKey;
   BOOL _originalMasksToBounds;
   BOOL _applying;
   BOOL _observing;
+  CGFloat _lastLoggedOffset;
+  NSUInteger _lastLoggedOwnerCount;
+  CGFloat _lastLoggedTransformY;
+  BOOL _hasLoggedState;
 }
 
 - (instancetype)initWithControl:(UIRefreshControl *)control
@@ -79,6 +84,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
@@ -1464,10 +1484,12 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 - (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 +1528,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   UILabel *_stickyEdgeMarker;
   CALayer *_topEdgeSeparatorCover;
   CALayer *_stickyEdgeSeparatorCover;
+  CALayer *_topOverlayThemeBackgroundLayer;
   __weak UIView *_topEdgeInteractionHost;
   __weak UIView *_stickyEdgeInteractionHost;
   __weak UIScrollView *_topEdgeScrollView;
@@ -1576,6 +1599,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;
@@ -1803,6 +1833,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 +1861,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 +1947,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 +1998,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 +2068,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 +2320,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;
@@ -2538,6 +2672,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [_nativeTabBarView updateAncestorGesturePrecedence];
   [_nativeSubHeaderView updateAncestorGesturePrecedence];
   [self updateTopScrollEdgeForScrollView:_observedScrollView];
+  [self logHomeVisualGeometry:shouldPin ? @"pin" : @"unpin"
+                    scrollView:_observedScrollView];
 }
 
 - (void)preparePageForHorizontalTransitionAtIndex:(NSInteger)pageIndex
@@ -2689,6 +2825,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 +2856,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
@@ -2991,6 +3137,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [self updateTopScrollEdgeForScrollView:_observedScrollView];
   [self updateScrollEdgeContentMasks];
   [self updateHeaderSettledStateForceBusy:NO];
+  [self logHomeVisualGeometry:@"layout" scrollView:_observedScrollView];
   dispatch_async(dispatch_get_main_queue(), ^{
     if (!self->_isBeingRecycled) {
       [self prepareAdjacentPageInsets];
@@ -3110,6 +3257,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   _externalOuterTransitioning = NO;
   _topScrollEdgeEnabled = NO;
   _topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::None;
+  _homeVisualStartMono = 0;
+  _homeVisualLastScrollLog = 0;
+  _homeVisualLastLayoutLog = 0;
+  _homeVisualLastGeometrySignature = nil;
   _nativeTabBarHeight = 44;
   _nativeSubHeaderHeight = 74;
   _headerOffset = 0;
@@ -3314,6 +3465,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (insetsChanged) {
     [self reapplyInsetsToObservedScrollView];
     [self setNeedsLayout];
+    [self logHomeVisualGeometry:@"props-inset" scrollView:_observedScrollView];
   }
   _applyingTopOverlayInsetChange = NO;
   if (!_nativeTabBarView.hidden) {
@@ -3894,8 +4046,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
@@ -4313,6 +4562,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 +4570,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) {

package/ios/RNCNativeScrollerComponentView.mm

@@ -8,6 +8,25 @@
 
 using namespace facebook::react;
 
+static void RNCNativeScrollerHomeVisualLog(NSString *phase, UIScrollView *scrollView)
+{
+#if DEBUG
+  Class logClass = NSClassFromString(@"ReactNativeNativeLogger.OneKeyLog");
+  if (logClass == nil) logClass = NSClassFromString(@"OneKeyLog");
+  SEL selector = NSSelectorFromString(@"debug::");
+  if (logClass == nil || ![logClass respondsToSelector:selector]) return;
+  UIRefreshControl *control = scrollView.refreshControl;
+  NSString *message = [NSString stringWithFormat:
+    @"[IOS-HOME-VISUAL] epochMs=%.0f monoMs=%.0f phase=scroller-%@ scrollTag=%ld refresh=%d refreshing=%d scrollY=%.1f insetTop=%.1f",
+    [NSDate.date timeIntervalSince1970] * 1000, CACurrentMediaTime() * 1000,
+    phase, (long)scrollView.tag, control != nil, control.isRefreshing,
+    scrollView.contentOffset.y, scrollView.contentInset.top];
+  typedef void (*LogFunction)(id, SEL, NSString *, NSString *);
+  LogFunction logFunction = (LogFunction)[logClass methodForSelector:selector];
+  logFunction(logClass, selector, @"NativeScroller", message);
+#endif
+}
+
 @interface RNCNativeVerticalScrollView : UIScrollView
 @end
 @implementation RNCNativeVerticalScrollView
@@ -156,6 +175,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
     [_refreshControl addTarget:self action:@selector(refreshTriggered:)
              forControlEvents:UIControlEventValueChanged];
     _scrollView.refreshControl = _refreshControl;
+    RNCNativeScrollerHomeVisualLog(@"refresh-created", _scrollView);
   } else if (!next.refreshEnabled && _refreshControl != nil) {
     [_refreshControl endRefreshing];
     _scrollView.refreshControl = nil;
@@ -174,8 +194,10 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
     }
     if (next.refreshing && !_refreshControl.refreshing) {
       [_refreshControl beginRefreshing];
+      RNCNativeScrollerHomeVisualLog(@"refresh-begin-prop", _scrollView);
     } else if (!next.refreshing && (previous.refreshing || createdRefreshControl)) {
       [_refreshControl endRefreshing];
+      if (previous.refreshing) RNCNativeScrollerHomeVisualLog(@"refresh-end-prop", _scrollView);
     }
   }
 
@@ -379,6 +401,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
   const auto &props = *std::static_pointer_cast<const RNCNativeScrollerProps>(_props);
   if (!props.refreshEnabled || props.refreshing) return;
   _refreshEventSentForDrag = YES;
+  RNCNativeScrollerHomeVisualLog(@"refresh-native-trigger", _scrollView);
   if (_eventEmitter) {
     std::static_pointer_cast<const RNCNativeScrollerEventEmitter>(_eventEmitter)->onRefresh({});
   }
@@ -523,6 +546,7 @@ static Event RNCScrollerMetrics(UIScrollView *scroll, CGPoint velocity, CGPoint
 - (void)setRefreshing:(BOOL)refreshing
 {
   if (_recycled || _refreshControl == nil) return;
+  RNCNativeScrollerHomeVisualLog(refreshing ? @"refresh-command-start" : @"refresh-command-stop", _scrollView);
   if (refreshing) {
     if (!_refreshControl.refreshing) [_refreshControl beginRefreshing];
   } else {

package/ios/tests/RNCCollapsiblePagerFirstFrameTests.mm

@@ -1,6 +1,7 @@
 #import <XCTest/XCTest.h>
 #import "RNCCollapsiblePagerViewComponentView.h"
 #import "RNCNativeScrollerComponentView.h"
+#import <react/renderer/components/pagerview/Props.h>
 #import <react/renderer/mounting/MountingTransaction.h>
 
 using namespace facebook::react;
@@ -22,6 +23,10 @@ using namespace facebook::react;
 - (void)updateHeaderSettledStateForceBusy:(BOOL)forceBusy;
 - (void)preparePageForHorizontalTransitionAtIndex:(NSInteger)index;
 - (void)applyInsetsToScrollView:(UIScrollView *)scrollView pageIndex:(NSInteger)index restore:(BOOL)restore;
+- (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &)oldProps;
+- (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView index:(NSInteger)index;
+- (CGFloat)effectiveTopOverlayHeight;
+- (void)updateRefreshControlForScrollView:(UIScrollView *)scrollView;
 @end
 
 @interface RNCNativeScrollerComponentView (ScrollCommandTesting)
@@ -34,6 +39,125 @@ using namespace facebook::react;
 
 @implementation RNCCollapsiblePagerFirstFrameTests
 
+- (void)testPendingLocalOverlayReservesManagedScrollerInsetBeforeSlotRebuild
+{
+  RNCCollapsiblePagerViewComponentView *pager =
+    [[RNCCollapsiblePagerViewComponentView alloc] initWithFrame:CGRectMake(0, 0, 320, 844)];
+  UIWindow *window = [[UIWindow alloc] initWithFrame:pager.frame];
+  UIViewController *root = [UIViewController new];
+  window.rootViewController = root;
+  [root.view addSubview:pager];
+  window.hidden = NO;
+  [self addTeardownBlock:^{
+    [pager prepareForRecycle];
+    window.hidden = YES;
+  }];
+
+  auto baseline = std::make_shared<RNCCollapsiblePagerViewProps>();
+  baseline->nativeSmoothHeaderScrollEnabled = true;
+  baseline->headerHeight = 120;
+  baseline->stickyHeaderHeight = 44;
+  baseline->pageKeys = "[\"page-0\"]";
+  [pager updateProps:baseline oldProps:nullptr];
+
+  UIView *header = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 120)];
+  UIView *sticky = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 44)];
+  UIView *page = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 844)];
+  RNCNativeScrollerComponentView *scroller = [RNCNativeScrollerComponentView new];
+  scroller.frame = page.bounds;
+  scroller.scrollView.frame = scroller.bounds;
+  scroller.scrollView.contentSize = CGSizeMake(320, 1500);
+  [page addSubview:scroller];
+  [pager mountChildComponentView:(id)header index:0];
+  [pager mountChildComponentView:(id)sticky index:1];
+  [pager mountChildComponentView:(id)page index:2];
+  [root.view layoutIfNeeded];
+  [pager layoutIfNeeded];
+  XCTestExpectation *settled = [self expectationWithDescription:@"Baseline slots and observer settled"];
+  dispatch_async(dispatch_get_main_queue(), ^{ [settled fulfill]; });
+  [self waitForExpectations:@[settled] timeout:1];
+  [pager attachScrollObserverForCurrentPage];
+  UIScrollView *ownedScroll = scroller.scrollView;
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], ownedScroll);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 164, 0.01);
+  [scroller scrollTo:0 y:40 - ownedScroll.contentInset.top animated:NO];
+  [pager setValue:@40 forKey:@"headerOffset"];
+  CGFloat initialLogicalOffset = ownedScroll.contentOffset.y + ownedScroll.contentInset.top;
+  XCTAssertEqualWithAccuracy(initialLogicalOffset, 40, 0.01);
+
+  auto hard = std::make_shared<RNCCollapsiblePagerViewProps>();
+  hard->nativeSmoothHeaderScrollEnabled = true;
+  hard->headerHeight = 120;
+  hard->stickyHeaderHeight = 44;
+  hard->pageKeys = "[\"page-0\"]";
+  hard->topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard;
+  hard->topOverlayHeight = 162;
+  [pager updateProps:hard oldProps:baseline];
+  XCTAssertNil([pager valueForKey:@"topOverlayView"]);
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], ownedScroll);
+  XCTAssertEqualWithAccuracy([pager effectiveTopOverlayHeight], 162, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 326, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentOffset.y + ownedScroll.contentInset.top,
+                             initialLogicalOffset, 0.01);
+  [self finishMount:pager];
+  XCTAssertNil([pager valueForKey:@"topOverlayView"]);
+  XCTAssertTrue([[pager valueForKey:@"deferTopEdgeSlotRebuild"] boolValue]);
+
+  UIView *overlay = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 162)];
+  [pager mountChildComponentView:(id)overlay index:2];
+  XCTAssertNil([pager valueForKey:@"topOverlayView"]);
+  [self finishMount:pager];
+  UIView *overlayHost = [pager valueForKey:@"topOverlayHostView"];
+  XCTAssertEqual([pager valueForKey:@"topOverlayView"], overlay);
+  XCTAssertEqual(overlay.superview, overlayHost);
+  XCTAssertEqual(overlay.window, window);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 326, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentOffset.y + ownedScroll.contentInset.top,
+                             initialLogicalOffset, 0.01);
+  XCTestExpectation *rebuilt = [self expectationWithDescription:@"Post-mount observer restored"];
+  dispatch_async(dispatch_get_main_queue(), ^{ [rebuilt fulfill]; });
+  [self waitForExpectations:@[rebuilt] timeout:1];
+  [pager attachScrollObserverForCurrentPage];
+  XCTAssertEqual([pager valueForKey:@"topOverlayView"], overlay);
+  XCTAssertEqual([pager valueForKey:@"observedScrollView"], ownedScroll);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 326, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentOffset.y + ownedScroll.contentInset.top,
+                             initialLogicalOffset, 0.01);
+
+  UIRefreshControl *control = [UIRefreshControl new];
+  ownedScroll.refreshControl = control;
+  [pager updateRefreshControlForScrollView:ownedScroll];
+  UIEdgeInsets refreshingInset = ownedScroll.contentInset;
+  refreshingInset.top += 60;
+  ownedScroll.contentInset = refreshingInset;
+  auto disabled = std::make_shared<RNCCollapsiblePagerViewProps>();
+  disabled->nativeSmoothHeaderScrollEnabled = true;
+  disabled->headerHeight = 120;
+  disabled->stickyHeaderHeight = 44;
+  disabled->pageKeys = "[\"page-0\"]";
+  disabled->topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::None;
+  disabled->topOverlayHeight = 0;
+  [pager updateProps:disabled oldProps:hard];
+  XCTAssertEqual(ownedScroll.refreshControl, control);
+  XCTAssertEqualWithAccuracy([pager effectiveTopOverlayHeight], 0, 0.01);
+  XCTAssertEqualWithAccuracy(ownedScroll.contentInset.top, 224, 0.01);
+}
+
+- (void)testPendingLocalOverlayHeightDoesNotOverrideExternalGeometry
+{
+  RNCCollapsiblePagerViewComponentView *pager = [RNCCollapsiblePagerViewComponentView new];
+  auto props = std::make_shared<RNCCollapsiblePagerViewProps>();
+  props->topScrollEdgeEffect = RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard;
+  props->topOverlayHeight = 162;
+  props->externalTopOverlayTag = 999;
+  [pager updateProps:props oldProps:nullptr];
+  XCTAssertNil([pager valueForKey:@"topOverlayView"]);
+  XCTAssertEqualWithAccuracy([pager effectiveTopOverlayHeight], 0, 0.01);
+  [pager setValue:@64 forKey:@"externalTopOverlayHeight"];
+  XCTAssertEqualWithAccuracy([pager effectiveTopOverlayHeight], 64, 0.01);
+  [pager prepareForRecycle];
+}
+
 - (void)testHeaderSettledAtTopRequiresCurrentQuietOwnerAndCancelsDetachedTimer
 {
   RNCCollapsiblePagerViewComponentView *pager = [self pagerWithPageCount:1];

package/ios/tests/RNCCollapsiblePagerHitTestTests.mm

@@ -8,6 +8,7 @@ using namespace facebook::react;
 
 @interface RNCCollapsiblePagerViewComponentView (ScrollEdgeTesting)
 - (void)updateTopScrollEdgeForScrollView:(UIScrollView *)scrollView;
+- (void)updateScrollEdgeContentMasks;
 @end
 
 @interface RNCCollapsiblePagerHitTestTests : XCTestCase
@@ -151,4 +152,163 @@ using namespace facebook::react;
   }
 }
 
+- (void)testPinnedHardEdgeHidesOnlyTopSeparatorCoverUntilUnpinned
+{
+  if (@available(iOS 26.0, *)) {
+    UIWindow *window = [[UIWindow alloc] initWithFrame:self.root.bounds];
+    [window addSubview:self.root];
+    [self addTeardownBlock:^{ window.hidden = YES; }];
+    window.hidden = NO;
+    UIScrollView *scrollView = [[UIScrollView alloc] initWithFrame:self.pager.bounds];
+    [self.pager addSubview:scrollView];
+    [self.pager setValue:@YES forKey:@"topScrollEdgeEnabled"];
+    [self.pager setValue:@(static_cast<NSInteger>(RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard))
+                 forKey:@"topScrollEdgeEffect"];
+    [self.pager setValue:@123 forKey:@"externalTopOverlayTag"];
+    [self.pager setValue:@64 forKey:@"externalTopOverlayHeight"];
+    [self.pager setValue:self.sticky forKey:@"stickyHeaderView"];
+    UIView *container = [self.pager valueForKey:@"containerView"];
+    container.frame = self.pager.bounds;
+    UIView *overlayHost = [self.pager valueForKey:@"topOverlayHostView"];
+    overlayHost.frame = CGRectMake(0, 0, 320, 64);
+    overlayHost.hidden = NO;
+    UIView *pinnedHost = [self.pager valueForKey:@"pinnedStickyHostView"];
+    pinnedHost.frame = CGRectMake(0, 64, 320, 44);
+    pinnedHost.hidden = NO;
+    [scrollView addSubview:pinnedHost];
+
+    [self.pager updateTopScrollEdgeForScrollView:scrollView];
+    UIScrollEdgeElementContainerInteraction *topInteraction =
+      [self.pager valueForKey:@"topEdgeInteraction"];
+    CALayer *topCover = [self.pager valueForKey:@"topEdgeSeparatorCover"];
+    XCTAssertNotNil(topInteraction);
+    XCTAssertNotNil(topCover);
+    XCTAssertFalse(topCover.hidden);
+    XCTAssertEqual(scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+
+    [self.pager setValue:@YES forKey:@"stickyHeaderIsPinned"];
+    [self.pager updateTopScrollEdgeForScrollView:scrollView];
+    UIScrollEdgeElementContainerInteraction *stickyInteraction =
+      [self.pager valueForKey:@"stickyEdgeInteraction"];
+    CALayer *stickyCover = [self.pager valueForKey:@"stickyEdgeSeparatorCover"];
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeInteraction"], topInteraction);
+    XCTAssertEqual(topInteraction.scrollView, scrollView);
+    XCTAssertEqual(stickyInteraction.scrollView, scrollView);
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeSeparatorCover"], topCover);
+    XCTAssertTrue(topCover.hidden);
+    XCTAssertNotNil(stickyCover);
+    XCTAssertFalse(stickyCover.hidden);
+    XCTAssertEqual(scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+
+    [self.pager setValue:@NO forKey:@"stickyHeaderIsPinned"];
+    [self.pager updateTopScrollEdgeForScrollView:scrollView];
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeInteraction"], topInteraction);
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeSeparatorCover"], topCover);
+    XCTAssertFalse(topCover.hidden);
+    XCTAssertEqual(scrollView.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+    [self.root removeFromSuperview];
+  } else {
+    XCTSkip(@"Scroll-edge interactions require iOS 26 or newer");
+  }
+}
+
+- (void)testIOS27LocalHardThemeBackgroundTracksMaskedHeaderGeometry
+{
+  if (@available(iOS 27.0, *)) {
+    UIWindowScene *scene = nil;
+    for (UIScene *connectedScene in UIApplication.sharedApplication.connectedScenes) {
+      if ([connectedScene isKindOfClass:UIWindowScene.class]) {
+        scene = (UIWindowScene *)connectedScene;
+        break;
+      }
+    }
+    XCTAssertNotNil(scene);
+    UIWindow *window = [[UIWindow alloc] initWithWindowScene:scene];
+    window.frame = self.root.bounds;
+    [window addSubview:self.root];
+    window.hidden = NO;
+    [self addTeardownBlock:^{ window.hidden = YES; }];
+    [self.pager layoutIfNeeded];
+    self.pager.backgroundColor = [UIColor colorWithWhite:0.2 alpha:1];
+    UIView *container = [self.pager valueForKey:@"containerView"];
+    container.frame = self.pager.bounds;
+    UIScrollView *scroll = [[UIScrollView alloc] initWithFrame:container.bounds];
+    scroll.contentInsetAdjustmentBehavior = UIScrollViewContentInsetAdjustmentNever;
+    scroll.alwaysBounceVertical = YES;
+    scroll.contentSize = CGSizeMake(320, 1200);
+    scroll.contentInset = UIEdgeInsetsMake(50 + 100 + 20, 0, 0, 0);
+    [container insertSubview:scroll atIndex:0];
+    UIView *sharedHost = [self.pager valueForKey:@"sharedHeaderHostView"];
+    for (UIView *child in sharedHost.subviews.copy) [child removeFromSuperview];
+    [scroll addSubview:sharedHost];
+    sharedHost.frame = CGRectMake(0, -120, 320, 120);
+    UIView *header = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 100)];
+    [sharedHost addSubview:header];
+    [self.pager setValue:header forKey:@"headerView"];
+    UIView *overlayHost = [self.pager valueForKey:@"topOverlayHostView"];
+    overlayHost.frame = CGRectMake(0, 0, 320, 50);
+    overlayHost.hidden = NO;
+    UIView *overlay = [[UIView alloc] initWithFrame:overlayHost.bounds];
+    [overlayHost addSubview:overlay];
+    [self.pager setValue:overlay forKey:@"topOverlayView"];
+    [self.pager setValue:@50 forKey:@"topOverlayHeight"];
+    [self.pager setValue:@100 forKey:@"headerHeight"];
+    [self.pager setValue:@20 forKey:@"stickyHeaderHeight"];
+    [self.pager setValue:@YES forKey:@"nativeSmoothHeaderScrollEnabled"];
+    [self.pager setValue:@YES forKey:@"topScrollEdgeEnabled"];
+    [self.pager setValue:@(static_cast<NSInteger>(RNCCollapsiblePagerViewTopScrollEdgeEffect::Hard))
+                 forKey:@"topScrollEdgeEffect"];
+    [self.pager setValue:scroll forKey:@"observedScrollView"];
+    [self.pager setValue:scroll forKey:@"sharedHeaderScrollView"];
+    scroll.contentOffset = CGPointMake(0, -170);
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    CALayer *layer = [self.pager valueForKey:@"topOverlayThemeBackgroundLayer"];
+    XCTAssertNotNil(layer);
+    XCTAssertEqual(layer.superlayer, overlayHost.layer);
+    XCTAssertEqualWithAccuracy(layer.opacity, 1, 0.01);
+    XCTAssertEqual(scroll.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+    XCTAssertEqual([self.pager valueForKey:@"topEdgeScrollView"], scroll);
+
+    scroll.contentOffset = CGPointMake(0, -120);
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertEqualWithAccuracy(layer.opacity, 0.5, 0.01);
+    scroll.contentOffset = CGPointMake(0, -70);
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertEqualWithAccuracy(layer.opacity, 0, 0.01);
+    scroll.contentOffset = CGPointMake(0, -210);
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertEqualWithAccuracy(layer.opacity, 1, 0.01);
+
+    scroll.contentInset = UIEdgeInsetsMake(230, 0, 0, 0);
+    scroll.contentOffset = CGPointMake(0, -230);
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertEqualWithAccuracy(layer.opacity, 1, 0.01);
+    self.pager.backgroundColor = UIColor.whiteColor;
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertTrue(CGColorEqualToColor(layer.backgroundColor, UIColor.whiteColor.CGColor));
+
+    [self.pager updateTopScrollEdgeForScrollView:nil];
+    XCTAssertEqual([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"], layer);
+    XCTAssertEqualWithAccuracy(layer.opacity, 1, 0.01);
+    [self.pager setValue:@YES forKey:@"topScrollEdgeEnabled"];
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    [self.pager setValue:@123 forKey:@"externalTopOverlayTag"];
+    [self.pager updateScrollEdgeContentMasks];
+    XCTAssertNil([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"]);
+    [self.pager setValue:@0 forKey:@"externalTopOverlayTag"];
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    XCTAssertEqual(scroll.topEdgeEffect.style, UIScrollEdgeEffectStyle.hardStyle);
+    [self.pager setValue:@NO forKey:@"topScrollEdgeEnabled"];
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    XCTAssertNil([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"]);
+    [self.pager setValue:@YES forKey:@"topScrollEdgeEnabled"];
+    [self.pager updateTopScrollEdgeForScrollView:scroll];
+    XCTAssertNotNil([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"]);
+    [self.pager prepareForRecycle];
+    XCTAssertNil([self.pager valueForKey:@"topOverlayThemeBackgroundLayer"]);
+  } else {
+    XCTSkip(@"The theme background applies only on iOS 27 or newer");
+  }
+}
+
 @end

package/ios/tests/RNCCollapsiblePagerRefreshControlTests.mm

@@ -60,6 +60,56 @@
   XCTAssertEqualWithAccuracy(control.bounds.origin.x, 3, 0.001);
 }
 
+- (void)testRefreshLayerWindowGeometryStartsBelowFixedOverlay
+{
+  for (NSNumber *overlayHeight in @[@0, @162]) {
+    CGFloat fixedHeight = overlayHeight.doubleValue;
+    CGFloat baseInset = fixedHeight + 180 + 44;
+    UIWindow *window = [[UIWindow alloc] initWithFrame:CGRectMake(0, 0, 390, 844)];
+    UIViewController *root = [UIViewController new];
+    window.rootViewController = root;
+    UIScrollView *scroll = [[UIScrollView alloc] initWithFrame:window.bounds];
+    scroll.contentInsetAdjustmentBehavior = UIScrollViewContentInsetAdjustmentNever;
+    scroll.contentSize = CGSizeMake(390, 1500);
+    scroll.contentInset = UIEdgeInsetsMake(baseInset + 60, 0, 0, 0);
+    scroll.contentOffset = CGPointMake(0, -baseInset - 102);
+    [root.view addSubview:scroll];
+    UIView *overlay = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 390, fixedHeight)];
+    [root.view addSubview:overlay];
+    UIRefreshControl *control = [UIRefreshControl new];
+    scroll.refreshControl = control;
+    window.hidden = NO;
+    [root.view layoutIfNeeded];
+    [control layoutIfNeeded];
+    // Match the control's window position recorded during a real refresh drag.
+    control.frame = [scroll convertRect:CGRectMake(0, baseInset, 390, 60)
+                                fromView:window];
+
+    RNCCollapsiblePagerViewComponentView *pager = [self pagerWithHeader:180];
+    [pager setValue:@(fixedHeight) forKey:@"topOverlayHeight"];
+    if (fixedHeight > 0) [pager setValue:overlay forKey:@"topOverlayView"];
+    [pager updateRefreshControlForScrollView:scroll];
+    [CATransaction flush];
+    CALayer *firstChild = control.layer.sublayers.firstObject;
+    XCTAssertNotNil(firstChild);
+    XCTAssertEqual(control.window, window);
+    CGRect overlayWindow = [overlay convertRect:overlay.bounds toView:window];
+    CGRect controlWindow = [control convertRect:control.bounds toView:window];
+    CGRect childWindow = [firstChild convertRect:firstChild.bounds toLayer:window.layer];
+    XCTAssertEqualWithAccuracy(CGRectGetMinY(controlWindow), baseInset, 0.01);
+    XCTAssertEqualWithAccuracy(CGRectGetMinY(childWindow),
+      CGRectGetMaxY(overlayWindow), 0.01);
+    XCTAssertEqualWithAccuracy(scroll.contentInset.top, baseInset + 60, 0.01);
+    [pager updateRefreshControlForScrollView:scroll];
+    XCTAssertEqualWithAccuracy(CGRectGetMinY(
+      [firstChild convertRect:firstChild.bounds toLayer:window.layer]),
+      CGRectGetMaxY(overlayWindow), 0.01);
+    [pager releaseRefreshControlForScrollView:scroll];
+    XCTAssertTrue(CATransform3DIsIdentity(control.layer.sublayerTransform));
+    window.hidden = YES;
+  }
+}
+
 - (void)testUIKitSizeChangesAndRefreshCycleDoNotAccumulateOffset
 {
   RNCCollapsiblePagerViewComponentView *pager = [self pagerWithHeader:64];

package/lib/module/CollapsiblePagerView.js

@@ -23,7 +23,7 @@ const pageKey = (child, index) => {
  */
 export class CollapsiblePagerView extends React.PureComponent {
   state = {
-    topOverlayHeight: 0,
+    topOverlayHeight: null,
     selectedPage: clampedPageIndex(this.props.initialPage ?? 0, React.Children.toArray(this.props.children).length),
     transientRetainedPages: []
   };
@@ -41,7 +41,14 @@ export class CollapsiblePagerView extends React.PureComponent {
   componentDidMount() {
     this.notifyMountedPagesChanged();
   }
-  componentDidUpdate() {
+  componentDidUpdate(previousProps) {
+    const previousOverlayEnabled = previousProps.topOverlay != null && (previousProps.topScrollEdgeEffect === "hard" || previousProps.topScrollEdgeEffect === "soft");
+    const overlayEnabled = this.props.topOverlay != null && (this.props.topScrollEdgeEffect === "hard" || this.props.topScrollEdgeEffect === "soft");
+    if (previousOverlayEnabled && !overlayEnabled && this.state.topOverlayHeight !== null) {
+      this.setState({
+        topOverlayHeight: null
+      });
+    }
     const pageCount = this.pages().length;
     const selectedPage = clampedPageIndex(this.state.selectedPage, pageCount);
     if (selectedPage !== this.state.selectedPage) {
@@ -197,6 +204,7 @@ export class CollapsiblePagerView extends React.PureComponent {
       headerHeight,
       stickyHeaderHeight,
       topOverlay,
+      topOverlayHeightHint,
       externalTopOverlayTag,
       topScrollEdgeEffect,
       topOverlayColorScheme,
@@ -219,6 +227,7 @@ export class CollapsiblePagerView extends React.PureComponent {
     const supportsTopScrollEdge = Platform.OS === "ios" && parseInt(String(Platform.Version), 10) >= 26;
     const scrollEdgeEnabled = supportsTopScrollEdge && (topScrollEdgeEffect === "hard" || topScrollEdgeEffect === "soft");
     const hasTopOverlay = scrollEdgeEnabled && topOverlay != null;
+    const initialTopOverlayHeight = typeof topOverlayHeightHint === "number" && Number.isFinite(topOverlayHeightHint) ? Math.max(0, Math.ceil(topOverlayHeightHint)) : 0;
     const pageKeys = pages.map(pageKey);
     const retained = new Set(this.mountedPages(pages.length));
     const deducedLayoutDirection = !layoutDirection || layoutDirection === "locale" ? I18nManager.isRTL ? "rtl" : "ltr" : layoutDirection;
@@ -245,7 +254,7 @@ export class CollapsiblePagerView extends React.PureComponent {
       stickyHeaderHeight: Math.max(0, Math.round(stickyHeaderHeight)),
       topScrollEdgeEffect: scrollEdgeEnabled ? topScrollEdgeEffect : "none",
       topOverlayColorScheme: scrollEdgeEnabled ? topOverlayColorScheme : undefined,
-      topOverlayHeight: hasTopOverlay ? this.state.topOverlayHeight : 0,
+      topOverlayHeight: hasTopOverlay ? this.state.topOverlayHeight ?? initialTopOverlayHeight : 0,
       externalTopOverlayTag: supportsTopScrollEdge && !hasTopOverlay ? externalTopOverlayTag ?? 0 : 0,
       nativeSmoothHeaderScrollEnabled: nativeSmoothHeaderScrollEnabled,
       pageKeys: JSON.stringify(pageKeys),

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

@@ -67,6 +67,8 @@ export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children"
     stickyHeaderHeight: number;
     /** Fixed content above the collapsible header on iOS 26 and newer. */
     topOverlay?: React.ReactNode;
+    /** Known overlay height to reserve until its first layout measurement. */
+    topOverlayHeightHint?: number;
     /** Existing fixed header shared with a parent pager on iOS 26 and newer. */
     externalTopOverlayTag?: number;
     /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
@@ -102,7 +104,7 @@ export interface CollapsiblePagerViewProps extends Omit<NativeProps, "children"
 type State = {
     selectedPage: number;
     transientRetainedPages: readonly number[];
-    topOverlayHeight: number;
+    topOverlayHeight: number | null;
 };
 /**
  * Pager variant whose vertical header coordination is performed by the native
@@ -120,7 +122,7 @@ export declare class CollapsiblePagerView extends React.PureComponent<Collapsibl
     private nativePagerScrollState;
     private nativeTabCommandQueuedDuringScroll;
     componentDidMount(): void;
-    componentDidUpdate(): void;
+    componentDidUpdate(previousProps: CollapsiblePagerViewProps): void;
     setPage: (selectedPage: number) => void;
     setPageWithoutAnimation: (selectedPage: number) => void;
     scrollToPageTop: (options?: Readonly<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-pager-view",
-  "version": "6.7.0-5",
+  "version": "6.7.0-7",
   "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-5",
+    "@onekeyfe/react-native-native-logger": "6.7.0-7",
     "react": "*",
     "react-native": "*"
   },

package/src/CollapsiblePagerView.tsx

@@ -120,6 +120,8 @@ export interface CollapsiblePagerViewProps
   stickyHeaderHeight: number;
   /** Fixed content above the collapsible header on iOS 26 and newer. */
   topOverlay?: React.ReactNode;
+  /** Known overlay height to reserve until its first layout measurement. */
+  topOverlayHeightHint?: number;
   /** Existing fixed header shared with a parent pager on iOS 26 and newer. */
   externalTopOverlayTag?: number;
   /** Selects UIKit's top scroll-edge effect on iOS 26 and newer. */
@@ -158,7 +160,7 @@ export interface CollapsiblePagerViewProps
 type State = {
   selectedPage: number;
   transientRetainedPages: readonly number[];
-  topOverlayHeight: number;
+  topOverlayHeight: number | null;
 };
 
 const pageIndex = (value: number) => {
@@ -186,7 +188,7 @@ export class CollapsiblePagerView extends React.PureComponent<
   State
 > {
   state: State = {
-    topOverlayHeight: 0,
+    topOverlayHeight: null,
     selectedPage: clampedPageIndex(
       this.props.initialPage ?? 0,
       React.Children.toArray(this.props.children).length
@@ -219,7 +221,22 @@ export class CollapsiblePagerView extends React.PureComponent<
     this.notifyMountedPagesChanged();
   }
 
-  componentDidUpdate() {
+  componentDidUpdate(previousProps: CollapsiblePagerViewProps) {
+    const previousOverlayEnabled =
+      previousProps.topOverlay != null &&
+      (previousProps.topScrollEdgeEffect === "hard" ||
+        previousProps.topScrollEdgeEffect === "soft");
+    const overlayEnabled =
+      this.props.topOverlay != null &&
+      (this.props.topScrollEdgeEffect === "hard" ||
+        this.props.topScrollEdgeEffect === "soft");
+    if (
+      previousOverlayEnabled &&
+      !overlayEnabled &&
+      this.state.topOverlayHeight !== null
+    ) {
+      this.setState({ topOverlayHeight: null });
+    }
     const pageCount = this.pages().length;
     const selectedPage = clampedPageIndex(this.state.selectedPage, pageCount);
     if (selectedPage !== this.state.selectedPage) {
@@ -473,6 +490,7 @@ export class CollapsiblePagerView extends React.PureComponent<
       headerHeight,
       stickyHeaderHeight,
       topOverlay,
+      topOverlayHeightHint,
       externalTopOverlayTag,
       topScrollEdgeEffect,
       topOverlayColorScheme,
@@ -498,6 +516,11 @@ export class CollapsiblePagerView extends React.PureComponent<
       supportsTopScrollEdge &&
       (topScrollEdgeEffect === "hard" || topScrollEdgeEffect === "soft");
     const hasTopOverlay = scrollEdgeEnabled && topOverlay != null;
+    const initialTopOverlayHeight =
+      typeof topOverlayHeightHint === "number" &&
+      Number.isFinite(topOverlayHeightHint)
+        ? Math.max(0, Math.ceil(topOverlayHeightHint))
+        : 0;
     const pageKeys = pages.map(pageKey);
     const retained = new Set(this.mountedPages(pages.length));
     const deducedLayoutDirection =
@@ -542,7 +565,11 @@ export class CollapsiblePagerView extends React.PureComponent<
         topOverlayColorScheme={
           scrollEdgeEnabled ? topOverlayColorScheme : undefined
         }
-        topOverlayHeight={hasTopOverlay ? this.state.topOverlayHeight : 0}
+        topOverlayHeight={
+          hasTopOverlay
+            ? this.state.topOverlayHeight ?? initialTopOverlayHeight
+            : 0
+        }
         externalTopOverlayTag={
           supportsTopScrollEdge && !hasTopOverlay
             ? externalTopOverlayTag ?? 0