@onekeyfe/react-native-pager-view 3.0.157-alpha.253 → 3.0.157-alpha.255

package/README.md

@@ -75,3 +75,5 @@ including unmounted pages that would show blank.
 
 Thank you again to Callstack and everyone who contributes to
 `react-native-pager-view` 💙
+
+The native ancestor-scroll contribution protocol is specified in [docs/SPEC.md](docs/SPEC.md).

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

@@ -20,6 +20,7 @@ import androidx.recyclerview.widget.RecyclerView
 import androidx.viewpager2.widget.ViewPager2
 import com.facebook.react.R as ReactR
 import com.facebook.react.uimanager.events.NativeGestureUtil
+import com.facebook.react.views.scroll.ReactScrollView
 import com.margelo.nitro.nativelogger.OneKeyLog
 import java.util.WeakHashMap
 import kotlin.math.max
@@ -508,6 +509,19 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     applyHeaderOffset()
   }
 
+  private fun publishConsumedOffset(recycler: RecyclerView, remove: Boolean = false) {
+    val key = R.id.onekey_native_scroll_coordinator_consumed_offsets
+    val existing = recycler.getTag(key) as? NativeScrollCoordinatorContributions
+    val contributions = existing ?: if (remove) return else NativeScrollCoordinatorContributions().also {
+      recycler.setTag(key, it)
+    }
+    val changed = if (remove) contributions.clearOwner(this) else contributions.update(this, headerOffsetPx)
+    if (changed) {
+      (recycler.getTag(R.id.onekey_native_scroll_coordinator_offset_listener) as? Runnable)?.run()
+    }
+    if (contributions.isEmpty()) recycler.setTag(key, null)
+  }
+
   private fun applyHeaderOffset() {
     val offset = headerOffsetPx.toFloat()
     pager.translationY = -offset
@@ -515,6 +529,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     stickyHeaderView?.translationY = -offset
     nativeTabBarView.translationY = -offset
     nativeSubHeaderView.translationY = -offset
+    observedRecyclerView?.let { publishConsumedOffset(it) }
   }
 
   private fun pageKey(index: Int): String = pageKeys.getOrNull(index) ?: "page-$index"
@@ -616,12 +631,14 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private fun attachRecyclerObserver(recycler: RecyclerView) {
     if (observedRecyclerView === recycler) {
       applyRecyclerInsets(recycler, selectedPage)
+      publishConsumedOffset(recycler)
       return
     }
 
     detachPrimaryScrollObserver()
     observedRecyclerView = recycler
     applyRecyclerInsets(recycler, selectedPage)
+    publishConsumedOffset(recycler)
     val listener = object : RecyclerView.OnScrollListener() {
       override fun onScrolled(recyclerView: RecyclerView, dx: Int, dy: Int) {
         val contentOffset = recyclerView.computeVerticalScrollOffset()
@@ -646,6 +663,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     val listener = observedScrollListener
     if (recycler != null) {
       pageOffsets[currentPageKey()] = recycler.computeVerticalScrollOffset()
+      publishConsumedOffset(recycler, remove = true)
     }
     if (recycler != null && listener != null) recycler.removeOnScrollListener(listener)
     if (recycler != null) {
@@ -775,11 +793,29 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     }
     updateScrollerPaddingOwnership(scroller, original)
     val topInset = headerHeightPx + stickyHeaderHeightPx
-    val top = original.top + topInset
     scroller.clipToPadding = false
-    if (scroller.paddingLeft != original.left || scroller.paddingTop != top ||
-      scroller.paddingRight != original.right || scroller.paddingBottom != original.bottom) {
-      scroller.setPadding(original.left, top, original.right, original.bottom)
+    if (scroller is ReactScrollView) {
+      // Fabric owns the content child's layout, so ScrollView padding alone
+      // cannot move it. RN's native ScrollAway API also updates Fabric culling.
+      val state = scroller.reactScrollViewScrollState
+      val scrollAwayTop = nativeScrollerScrollAwayTop(
+        state.scrollAwayPaddingTop, original.appliedTopInset, topInset,
+      )
+      if (state.scrollAwayPaddingTop != scrollAwayTop ||
+        scroller.getChildAt(0)?.translationY != scrollAwayTop.toFloat()) {
+        scroller.setScrollAwayPaddingEnabledUnstable(scrollAwayTop, state.scrollAwayPaddingBottom)
+      }
+      val bottom = original.bottom + topInset
+      if (scroller.paddingLeft != original.left || scroller.paddingTop != original.top ||
+        scroller.paddingRight != original.right || scroller.paddingBottom != bottom) {
+        scroller.setPadding(original.left, original.top, original.right, bottom)
+      }
+    } else {
+      val top = original.top + topInset
+      if (scroller.paddingLeft != original.left || scroller.paddingTop != top ||
+        scroller.paddingRight != original.right || scroller.paddingBottom != original.bottom) {
+        scroller.setPadding(original.left, top, original.right, original.bottom)
+      }
     }
     original.appliedTopInset = topInset
 
@@ -804,13 +840,29 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     scroller: ScrollView,
     original: ScrollerPadding,
   ) {
-    val expectedTop = original.top + original.appliedTopInset
+    val isReactScroller = scroller is ReactScrollView
+    if (scroller is ReactScrollView) {
+      val state = scroller.reactScrollViewScrollState
+      if (nativeScrollerPaddingWasResetByScrollAway(
+          original.appliedTopInset,
+          scroller.paddingLeft, scroller.paddingTop, scroller.paddingRight, scroller.paddingBottom,
+          state.scrollAwayPaddingTop, state.scrollAwayPaddingBottom,
+        )) {
+        // RN may replay ScrollAway state before this pass. Its setter clears
+        // caller padding; that native reset must not become our new baseline.
+        return
+      }
+    }
+    val ownedTop = if (isReactScroller) 0 else original.appliedTopInset
+    val ownedBottom = if (isReactScroller) original.appliedTopInset else 0
     if (scroller.paddingLeft != original.left) original.left = scroller.paddingLeft
-    if (scroller.paddingTop != expectedTop) {
-      original.top = (scroller.paddingTop - original.appliedTopInset).coerceAtLeast(0)
+    if (scroller.paddingTop != original.top + ownedTop) {
+      original.top = (scroller.paddingTop - ownedTop).coerceAtLeast(0)
     }
     if (scroller.paddingRight != original.right) original.right = scroller.paddingRight
-    if (scroller.paddingBottom != original.bottom) original.bottom = scroller.paddingBottom
+    if (scroller.paddingBottom != original.bottom + ownedBottom) {
+      original.bottom = (scroller.paddingBottom - ownedBottom).coerceAtLeast(0)
+    }
     if (scroller.clipToPadding) original.clipToPadding = true
   }
 
@@ -835,6 +887,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun restoreRecyclerInsets(recycler: RecyclerView) {
+    publishConsumedOffset(recycler, remove = true)
     val original = originalRecyclerPadding.remove(recycler) ?: return
     updateRecyclerPaddingOwnership(recycler, original)
     restoredRecyclerKeys.remove(recycler)
@@ -846,6 +899,13 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     val original = originalScrollerPadding.remove(scroller) ?: return
     updateScrollerPaddingOwnership(scroller, original)
     restoredScrollerKeys.remove(scroller)
+    if (scroller is ReactScrollView) {
+      val state = scroller.reactScrollViewScrollState
+      scroller.setScrollAwayPaddingEnabledUnstable(
+        nativeScrollerScrollAwayTop(state.scrollAwayPaddingTop, original.appliedTopInset, 0),
+        state.scrollAwayPaddingBottom,
+      )
+    }
     scroller.clipToPadding = original.clipToPadding
     scroller.setPadding(original.left, original.top, original.right, original.bottom)
   }

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

@@ -0,0 +1,15 @@
+package com.reactnativepagerview
+
+import java.util.WeakHashMap
+
+/** Native tag payload; leaf observers can read it as Map without a pager dependency. */
+internal class NativeScrollCoordinatorContributions : WeakHashMap<Any, Int>() {
+  fun update(owner: Any, pixels: Int): Boolean {
+    val value = pixels.coerceAtLeast(0)
+    if (get(owner) == value) return false
+    put(owner, value)
+    return true
+  }
+
+  fun clearOwner(owner: Any): Boolean = remove(owner) != null
+}

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

@@ -0,0 +1,17 @@
+package com.reactnativepagerview
+
+// Replace only this pager's contribution; another native owner may share the scroller.
+internal fun nativeScrollerScrollAwayTop(currentTop: Int, previousInset: Int, nextInset: Int): Int =
+  (currentTop - previousInset).coerceAtLeast(0) + nextInset
+
+// ReactScrollView's ScrollAway setter always writes this exact padding shape.
+internal fun nativeScrollerPaddingWasResetByScrollAway(
+  appliedInset: Int,
+  left: Int,
+  top: Int,
+  right: Int,
+  bottom: Int,
+  scrollAwayTop: Int,
+  scrollAwayBottom: Int,
+): Boolean = appliedInset > 0 && left == 0 && top == 0 && right == 0 &&
+  bottom == scrollAwayTop + scrollAwayBottom

package/android/src/main/res/values/native_scroll_coordinator_ids.xml

@@ -0,0 +1,4 @@
+<resources>
+    <item name="onekey_native_scroll_coordinator_consumed_offsets" type="id" />
+    <item name="onekey_native_scroll_coordinator_offset_listener" type="id" />
+</resources>

package/android/src/test/java/com/reactnativepagerview/NativeScrollCoordinatorContributionsTest.kt

@@ -0,0 +1,26 @@
+package com.reactnativepagerview
+
+/** Standalone JVM regression: compile together with the production helper. */
+fun main() {
+  val outer = Any()
+  val inner = Any()
+  val firstChild = NativeScrollCoordinatorContributions()
+  check(firstChild.update(outer, 120))
+  check(firstChild.update(inner, 60))
+  check(firstChild.values.sum() == 180)
+  check(!firstChild.update(outer, 120))
+  check(firstChild.update(outer, 30))
+  check(firstChild.values.sum() == 90)
+  check(firstChild.clearOwner(outer))
+  check(firstChild.values.sum() == 60)
+  check(!firstChild.clearOwner(outer))
+  val secondChild = NativeScrollCoordinatorContributions()
+  check(secondChild.update(outer, 30))
+  check(secondChild.values.sum() == 30)
+  check(firstChild.values.sum() == 60)
+  check(firstChild.clearOwner(inner))
+  check(firstChild.isEmpty())
+  check(secondChild.update(outer, -1))
+  check(secondChild.values.sum() == 0)
+  println("Native coordinator contributions: nested owners, duplicate updates, cleanup, and replacement passed")
+}

package/android/src/test/java/com/reactnativepagerview/NativeScrollerScrollAwayInsetsTest.kt

@@ -0,0 +1,37 @@
+package com.reactnativepagerview
+
+/** Standalone JVM contract regression for Fabric scroller inset ownership. */
+fun main() {
+  val initialTop = 24
+  val firstHeader = 182 + 48
+  val initialApplied = nativeScrollerScrollAwayTop(initialTop, 0, firstHeader)
+  check(initialApplied == 254)
+  check(nativeScrollerScrollAwayTop(initialApplied, firstHeader, firstHeader) == initialApplied)
+  val measuredHeader = 310 + 48
+  val resized = nativeScrollerScrollAwayTop(initialApplied, firstHeader, measuredHeader)
+  check(resized == initialTop + measuredHeader)
+  // A second pager's contribution survives the first pager's detach.
+  val nested = nativeScrollerScrollAwayTop(resized, 0, 100)
+  val outerDetached = nativeScrollerScrollAwayTop(nested, measuredHeader, 0)
+  check(outerDetached == initialTop + 100)
+  check(nativeScrollerScrollAwayTop(outerDetached, 100, 0) == initialTop)
+  // Fabric may reset state while replacing its content root; do not apply a negative baseline.
+  check(nativeScrollerScrollAwayTop(0, measuredHeader, firstHeader) == firstHeader)
+  // Caller L/R/B = 16/16/40 must survive RN's setter replay after our 230px inset.
+  val caller = intArrayOf(16, 0, 16, 40)
+  val rnReplay = intArrayOf(0, 0, 0, 230)
+  val keepCaller = nativeScrollerPaddingWasResetByScrollAway(
+    230, rnReplay[0], rnReplay[1], rnReplay[2], rnReplay[3], 230, 0,
+  )
+  check(keepCaller)
+  val restored = if (keepCaller) caller else rnReplay
+  check(restored.contentEquals(intArrayOf(16, 0, 16, 40)))
+  // Nonzero native bottom state is part of RN's reset signature too.
+  check(nativeScrollerPaddingWasResetByScrollAway(230, 0, 0, 0, 278, 254, 24))
+  // Actual caller updates, including clearing all padding, remain observable.
+  check(!nativeScrollerPaddingWasResetByScrollAway(230, 24, 0, 24, 290, 230, 0))
+  check(!nativeScrollerPaddingWasResetByScrollAway(230, 0, 0, 0, 0, 230, 0))
+  // Initial discovery must capture caller values before this pager owns an inset.
+  check(!nativeScrollerPaddingWasResetByScrollAway(0, 0, 0, 0, 230, 230, 0))
+  println("NativeScroller ScrollAway ownership: initial, repeat, measured resize, nested detach, Fabric reset, RN padding replay, and caller updates passed")
+}

package/docs/SPEC.md

@@ -0,0 +1,108 @@
+# PagerView native scrolling contract
+
+Existing PagerView and CollapsiblePagerView APIs are documented in README.md.
+The sections below define native coordination boundaries without new React props.
+
+## iOS shared-header hit testing
+
+Smooth-header hit forwarding is restricted to the pager's own interactive
+viewport. A collapsed header clipped above that viewport MUST NOT intercept
+touches intended for a sibling toolbar. Hidden, disabled and effectively
+transparent pagers do not forward touches. Fabric `pointerEvents="none"` and
+`"box-only"` retain their superclass behavior; `"auto"` and `"box-none"` may
+forward to visible shared-header children inside the pager.
+
+The shared header's internal hit testing still supports sticky children that
+have moved outside the header host's original bounds while remaining inside the
+pager. Focused UIKit tests cover sibling-toolbar hit delivery, pinned-child
+delivery, pointer-event modes and interaction flags. Device acceptance includes
+toolbar taps with expanded and collapsed headers on retained pages.
+
+## iOS cached-offset restoration after content shrink
+
+When restoring a retained page's cached vertical offset, the pager limits only
+the upper bound to the current content height, viewport and applied insets. A
+cache captured before rows were removed MUST NOT restore an offset below the new
+content bottom, including when removal occurs during a page transition. Valid
+deep offsets and the existing lower-bound/header alignment rules are unchanged.
+This check runs only on explicit restoration, not on scroll frames; UIKit pull
+overscroll and refresh settlement retain their existing ownership. An unmeasured
+zero-height viewport defers this upper-bound limit to a later restoration.
+
+The focused policy test covers shrink after the list has already corrected its
+offset, valid deep offsets, negative pull offsets and an unmeasured viewport.
+Runtime acceptance requires clearing a retained page during a page transition,
+then returning without an extra drag to expose its header/empty/footer slots.
+
+
+## Ancestor consumed-scroll contributions
+
+Status: source implementation; real nested-pager runtime verification pending.
+Android collapsible pagers consume header travel before the primary RecyclerView
+receives content-scroll deltas. A leaf threshold observer needs both distances.
+The coordinator publishes a non-negative physical-pixel contribution under its
+own weak owner identity on the active primary RecyclerView. Nested coordinators
+contribute independently; summing their values gives ancestor-consumed travel.
+
+The native View tag named `onekey_native_scroll_coordinator_consumed_offsets`
+stores a WeakHashMap with owner-view keys and integer pixel values. The optional
+`onekey_native_scroll_coordinator_offset_listener` tag holds a Runnable owned by
+the leaf. The publisher updates only its own entry and invokes the listener only
+when that entry changes. An absent map/listener means zero/no observer.
+This protocol depends only on Android View/resources and Java collections; the
+pager MUST NOT depend on NativeList or infer Home/business semantics.
+
+On switching the primary child, restoring insets, or detaching, the coordinator
+removes only its own contribution. It MUST NOT retain an old RecyclerView or
+another coordinator. Zero contributions may remain while the owner is attached;
+weak keys prevent abandoned owners from becoming resource roots. The leaf owns
+listener registration and cleanup. All operations occur on the UI thread; there
+are no JavaScript scroll-frame callbacks in this protocol.
+
+A new child receives current header travel before threshold evaluation. Native
+list offsets remain local to the leaf, while consumers of this protocol add all
+ancestor contributions exactly once. Programmatic scrolling/header restoration
+must publish the resulting header offset through the same path.
+
+## Acceptance
+
+The focused JVM helper test covers independent ancestor contributions and removal.
+Required Android runtime cases are one/nested collapsible pagers, header-only
+scrolling, reversal to expanded top, switching pages, native child replacement,
+and detach/remount without stale offsets. iOS uses its existing normalized
+UIScrollView offset and requires no equivalent tag protocol. Source/helper
+checks do not establish the Android runtime acceptance above.
+
+
+## Android Fabric NativeScroller content insets
+
+A ReactScrollView's content root is laid out by Fabric. Native `setPadding(top)`
+alone MUST NOT be used to reserve a collapsible header: ReactScrollView does not
+perform the platform ScrollView child layout, so that leaves rows under the
+header. For the supported RN 0.86 runtime, the coordinator uses
+`setScrollAwayPaddingEnabledUnstable` to offset the content root and synchronize
+Fabric content-origin/culling state. The equivalent inset is added to the native
+scroll range at the bottom; it is not added a second time at the top. Ordinary
+Android ScrollView and RecyclerView retain their existing inset paths.
+
+Each coordinator replaces only its previous header-plus-sticky contribution.
+Measured-height changes do not accumulate insets; detach restores the remaining
+ScrollAway state and caller padding, including another native owner's inset.
+Content-root replacement reapplies the native offset. No Home layout values,
+new React props, or per-frame JS updates are introduced; iOS/Web are unchanged.
+
+The focused JVM policy regression covers an existing inset, repeated application,
+measured-header resize, nested-owner detach, and Fabric state reset. The API call
+is compile-checked against the installed React Android 0.86.2 artifact. Runtime
+acceptance requires first content below the expanded sticky tabs, collapse and
+expand without overlap, retained-page switching, header height changes, and
+reaching the actual final content without an extra header-sized blank footer.
+
+RN's ScrollAway setter (including native state replay when Fabric culling flags
+are enabled) resets physical padding to `(0, 0, 0, scrollAwayTop + scrollAwayBottom)`.
+While owning an inset, the coordinator recognizes that exact native reset and
+retains saved caller padding; other physical-padding updates remain observable.
+The focused policy regression includes nonzero caller left/right/bottom padding,
+nonzero prior native insets, explicit caller padding changes/clear, and initial
+discovery before ownership. Current Home zero-padding behavior is unchanged by
+this ownership guard.

package/ios/RNCCollapsiblePagerReleasedStatePolicy.h

@@ -9,4 +9,12 @@ FOUNDATION_EXPORT void RNCPruneReleasedPageStates(
   NSArray<NSString *> *validPageKeys
 );
 
+FOUNDATION_EXPORT CGFloat RNCLimitRestoredScrollOffset(
+  CGFloat offset,
+  CGFloat contentHeight,
+  CGFloat viewportHeight,
+  CGFloat topInset,
+  CGFloat bottomInset
+);
+
 NS_ASSUME_NONNULL_END

package/ios/RNCCollapsiblePagerReleasedStatePolicy.m

@@ -1,5 +1,18 @@
 #import "RNCCollapsiblePagerReleasedStatePolicy.h"
 
+CGFloat RNCLimitRestoredScrollOffset(
+  CGFloat offset,
+  CGFloat contentHeight,
+  CGFloat viewportHeight,
+  CGFloat topInset,
+  CGFloat bottomInset
+)
+{
+  if (viewportHeight <= 0) return offset;
+  CGFloat maximum = MAX(-topInset, contentHeight - viewportHeight + bottomInset);
+  return MIN(offset, maximum);
+}
+
 void RNCPruneReleasedPageStates(
   NSMutableDictionary *releasedStates,
   NSArray<NSString *> *validPageKeys

package/ios/RNCCollapsiblePagerViewComponentView.mm

@@ -1145,6 +1145,16 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (UIView *)hitTest:(CGPoint)point withEvent:(UIEvent *)event
 {
+  // Shared headers can sit above their clipped viewport after collapsing.
+  // Forward only viewport touches, so invisible headers cannot cover siblings.
+  if (!self.userInteractionEnabled || self.hidden || self.alpha < 0.01 ||
+      ![self pointInside:point withEvent:event]) return nil;
+  const auto &viewProps =
+    *std::static_pointer_cast<const RNCCollapsiblePagerViewProps>(_props);
+  if (viewProps.pointerEvents == PointerEventsMode::None ||
+      viewProps.pointerEvents == PointerEventsMode::BoxOnly) {
+    return [super hitTest:point withEvent:event];
+  }
   if (_nativeSmoothHeaderScrollEnabled && !_isBeingRecycled &&
       _sharedHeaderHostView.superview != _containerView) {
     CGPoint headerPoint = [_sharedHeaderHostView convertPoint:point fromView:self];
@@ -2580,6 +2590,15 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     }
     targetOffset = restoredLogicalOffset - next.top;
     targetOffset = MAX(targetOffset, -next.top + _headerOffset);
+    // An inactive list may shrink after its offset observer was detached.
+    // Do not overwrite its corrected offset with a now-unreachable cached one.
+    targetOffset = RNCLimitRestoredScrollOffset(
+      targetOffset,
+      scrollView.contentSize.height,
+      scrollView.bounds.size.height,
+      next.top,
+      next.bottom
+    );
   }
   // A bottom-inset change must not cancel UIKit's refresh or bounce settlement.
   if (restore || previousTopInset != next.top) {

package/ios/tests/RNCCollapsiblePagerHitTestTests.mm

@@ -0,0 +1,80 @@
+#import <XCTest/XCTest.h>
+
+#import "RNCCollapsiblePagerViewComponentView.h"
+#import <react/renderer/components/pagerview/Props.h>
+
+using namespace facebook::react;
+
+@interface RNCCollapsiblePagerHitTestTests : XCTestCase
+@property (nonatomic, strong) UIView *root;
+@property (nonatomic, strong) UIButton *toolbar;
+@property (nonatomic, strong) RNCCollapsiblePagerViewComponentView *pager;
+@property (nonatomic, strong) UIButton *sticky;
+@end
+
+@implementation RNCCollapsiblePagerHitTestTests
+
+- (void)setPointerEvents:(PointerEventsMode)mode
+{
+  auto props = std::make_shared<RNCCollapsiblePagerViewProps>();
+  props->nativeSmoothHeaderScrollEnabled = true;
+  props->pointerEvents = mode;
+  [self.pager updateProps:props oldProps:nullptr];
+}
+
+- (void)setUp
+{
+  [super setUp];
+  self.root = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 320, 600)];
+  self.toolbar = [[UIButton alloc] initWithFrame:CGRectMake(0, 36, 320, 64)];
+  [self.root addSubview:self.toolbar];
+  self.pager = [[RNCCollapsiblePagerViewComponentView alloc] init];
+  [self setPointerEvents:PointerEventsMode::Auto];
+  self.pager.frame = CGRectMake(0, 100, 320, 500);
+  [self.root addSubview:self.pager];
+
+  // Model smooth mode's header reparenting and its collapsed, clipped content.
+  UIView *scroll = [[UIView alloc] initWithFrame:self.pager.bounds];
+  [self.pager addSubview:scroll];
+  UIView *header = [self.pager valueForKey:@"sharedHeaderHostView"];
+  for (UIView *child in header.subviews.copy) [child removeFromSuperview];
+  [scroll addSubview:header];
+  header.frame = CGRectMake(0, -64, 320, 108);
+  [header addSubview:[[UIButton alloc] initWithFrame:CGRectMake(0, 0, 320, 64)]];
+  self.sticky = [[UIButton alloc] initWithFrame:CGRectMake(0, 140, 320, 44)];
+  [header addSubview:self.sticky];
+}
+
+- (void)testCollapsedHeaderDoesNotInterceptSiblingToolbar
+{
+  XCTAssertEqual([self.root hitTest:CGPointMake(20, 80) withEvent:nil], self.toolbar);
+}
+
+- (void)testPinnedChildOutsideHeaderHostStillReceivesViewportTouches
+{
+  XCTAssertEqual([self.pager hitTest:CGPointMake(20, 90) withEvent:nil], self.sticky);
+  [self setPointerEvents:PointerEventsMode::BoxNone];
+  XCTAssertEqual([self.pager hitTest:CGPointMake(20, 90) withEvent:nil], self.sticky);
+}
+
+- (void)testFabricPointerEventsAreNotBypassed
+{
+  [self setPointerEvents:PointerEventsMode::None];
+  XCTAssertNil([self.pager hitTest:CGPointMake(20, 90) withEvent:nil]);
+  [self setPointerEvents:PointerEventsMode::BoxOnly];
+  XCTAssertEqual([self.pager hitTest:CGPointMake(20, 90) withEvent:nil], self.pager);
+}
+
+- (void)testNoninteractivePagerDoesNotForwardHeaderTouches
+{
+  self.pager.hidden = YES;
+  XCTAssertNil([self.pager hitTest:CGPointMake(20, 90) withEvent:nil]);
+  self.pager.hidden = NO;
+  self.pager.userInteractionEnabled = NO;
+  XCTAssertNil([self.pager hitTest:CGPointMake(20, 90) withEvent:nil]);
+  self.pager.userInteractionEnabled = YES;
+  self.pager.alpha = 0.005;
+  XCTAssertNil([self.pager hitTest:CGPointMake(20, 90) withEvent:nil]);
+}
+
+@end

package/ios/tests/RNCCollapsiblePagerReleasedStatePolicyTests.mm

@@ -7,6 +7,29 @@
 
 @implementation RNCCollapsiblePagerReleasedStatePolicyTests
 
+- (void)testRestorationAfterInactiveContentShrinkCannotReapplyStaleCache
+{
+  // The list already corrected to -44 while inactive, but the pager still
+  // retains the old logical offset captured before rows were removed.
+  CGFloat savedLogicalOffset = 513.67;
+  CGFloat restored = RNCLimitRestoredScrollOffset(
+    savedLogicalOffset - 108, 132, 708, 108, 532);
+  XCTAssertEqualWithAccuracy(restored, -44, 0.001);
+  XCTAssertEqualWithAccuracy(restored + 108, 64, 0.001);
+  XCTAssertEqualWithAccuracy(
+    RNCLimitRestoredScrollOffset(restored, 132, 708, 108, 532), restored, 0.001);
+}
+
+- (void)testRestorationPreservesValidDeepAndNegativeOffsets
+{
+  XCTAssertEqualWithAccuracy(
+    RNCLimitRestoredScrollOffset(600, 2400, 708, 108, 0), 600, 0.001);
+  XCTAssertEqualWithAccuracy(
+    RNCLimitRestoredScrollOffset(-160, 132, 708, 108, 532), -160, 0.001);
+  XCTAssertEqualWithAccuracy(
+    RNCLimitRestoredScrollOffset(600, 0, 0, 108, 0), 600, 0.001);
+}
+
 - (void)testPrunesRemovedKeysAndKeepsStableKeysAcrossReorders
 {
   NSObject *alpha = [NSObject new];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-pager-view",
-  "version": "3.0.157-alpha.253",
+  "version": "3.0.157-alpha.255",
   "description": "React Native wrapper for Android and iOS ViewPager",
   "source": "./src/index.tsx",
   "main": "./lib/module/index.js",
@@ -21,6 +21,7 @@
     "lib",
     "android",
     "ios",
+    "docs",
     "react-native-pager-view.podspec",
     "!ios/build",
     "!android/build",
@@ -66,7 +67,7 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "@onekeyfe/react-native-native-logger": "3.0.157-alpha.253",
+    "@onekeyfe/react-native-native-logger": "3.0.157-alpha.255",
     "react": "*",
     "react-native": "*"
   },