@onekeyfe/react-native-pager-view 3.0.157-alpha.254 → 3.0.157-alpha.256

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,133 @@
+# 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 refresh indicator placement
+
+Status: source implementation; real refresh-cycle acceptance pending.
+In smooth-header mode, the pager shifts the refresh control's sublayers upward
+by its header-plus-sticky height. It does not change the refresh control frame,
+bounds, scroll offset, refresh state or JavaScript callback. RN's caller-owned
+`progressViewOffset` remains untouched, including dynamic updates whose bounds
+origin could otherwise collide with a coordinator-applied value.
+
+One internal state per UIRefreshControl combines weak pager-owner contributions.
+It preserves the original sublayer transform and clipping setting. Repeated
+attachment and header resizing replace an owner's contribution. Layer clipping
+is disabled while coordinating so it cannot hide the translated indicator.
+A control replacement, scroll-view release, pager recycling or destruction
+removes only that owner's contribution and restores the baseline when none remain.
+Controls installed after the scroller is attached are also coordinated. Native
+UICollectionView controls and RN ScrollView controls use this same UIKit boundary.
+
+Native layer observations reapply the contribution after an external sublayer
+transform change, without observing or interpreting UIKit/RN bounds writes.
+There is no per-frame JavaScript work. Acceptance must cover real UIKit pulling
+and refresh completion, caller offset changes, late installation/replacement,
+retained-page switching, clipping and nested-owner cleanup. Programmatic UIKit
+unit tests do not substitute for real pull-gesture visibility acceptance.
+
+## 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

@@ -11,6 +11,7 @@
 #import "React/RCTScrollViewComponentView.h"
 #import "React/RCTSurfaceTouchHandler.h"
 #import "React/RCTTouchHandler.h"
+#import <objc/runtime.h>
 
 // OneKey patch: deduplicate structural mutation parents before scanning the page.
 #include <unordered_set>
@@ -18,6 +19,116 @@
 using namespace facebook::react;
 
 static void *RNCCollapsiblePagerContentOffsetContext = &RNCCollapsiblePagerContentOffsetContext;
+static void *RNCRefreshControlLayerContext = &RNCRefreshControlLayerContext;
+static void *RNCScrollRefreshControlContext = &RNCScrollRefreshControlContext;
+static char RNCRefreshControlOffsetKey;
+
+@interface RNCRefreshControlOffsetState : NSObject
++ (void)setOffset:(CGFloat)offset forControl:(UIRefreshControl *)control owner:(id)owner;
++ (void)removeControl:(UIRefreshControl *)control owner:(id)owner;
+@end
+
+@implementation RNCRefreshControlOffsetState {
+  __weak UIRefreshControl *_control;
+  NSMapTable<id, NSNumber *> *_offsets;
+  CATransform3D _baselineTransform;
+  CATransform3D _appliedTransform;
+  BOOL _originalMasksToBounds;
+  BOOL _applying;
+  BOOL _observing;
+}
+
+- (instancetype)initWithControl:(UIRefreshControl *)control
+{
+  if ((self = [super init])) {
+    _control = control;
+    _baselineTransform = control.layer.sublayerTransform;
+    _originalMasksToBounds = control.layer.masksToBounds;
+    _offsets = [NSMapTable weakToStrongObjectsMapTable];
+    [control.layer addObserver:self forKeyPath:@"sublayerTransform"
+                       options:NSKeyValueObservingOptionNew
+                       context:RNCRefreshControlLayerContext];
+    [control.layer addObserver:self forKeyPath:@"masksToBounds"
+                       options:NSKeyValueObservingOptionNew
+                       context:RNCRefreshControlLayerContext];
+    _observing = YES;
+  }
+  return self;
+}
+
+- (void)apply
+{
+  UIRefreshControl *control = _control;
+  if (control == nil) return;
+  CGFloat offset = 0;
+  for (NSNumber *value in _offsets.objectEnumerator) offset += value.doubleValue;
+  CATransform3D transform = CATransform3DConcat(
+    _baselineTransform, CATransform3DMakeTranslation(0, -offset, 0));
+  _appliedTransform = transform;
+  _applying = YES;
+  // Visual placement must not change UIKit's refresh geometry or RN's bounds
+  // origin (progressViewOffset). Allow the shifted indicator outside its host.
+  [CATransaction begin];
+  [CATransaction setDisableActions:YES];
+  control.layer.masksToBounds = _offsets.count == 0 ? _originalMasksToBounds : NO;
+  if (!CATransform3DEqualToTransform(control.layer.sublayerTransform, transform)) {
+    control.layer.sublayerTransform = transform;
+  }
+  [CATransaction commit];
+  _applying = NO;
+}
+
++ (void)setOffset:(CGFloat)offset forControl:(UIRefreshControl *)control owner:(id)owner
+{
+  if (control == nil) return;
+  RNCRefreshControlOffsetState *state = objc_getAssociatedObject(control, &RNCRefreshControlOffsetKey);
+  if (state == nil) {
+    state = [[self alloc] initWithControl:control];
+    objc_setAssociatedObject(control, &RNCRefreshControlOffsetKey, state, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+  }
+  [state->_offsets setObject:@(offset) forKey:owner];
+  [state apply];
+}
+
++ (void)removeControl:(UIRefreshControl *)control owner:(id)owner
+{
+  if (control == nil) return;
+  RNCRefreshControlOffsetState *state = objc_getAssociatedObject(control, &RNCRefreshControlOffsetKey);
+  if (state == nil) return;
+  [state->_offsets removeObjectForKey:owner];
+  [state apply];
+  if (state->_offsets.count == 0) {
+    [control.layer removeObserver:state forKeyPath:@"sublayerTransform" context:RNCRefreshControlLayerContext];
+    [control.layer removeObserver:state forKeyPath:@"masksToBounds" context:RNCRefreshControlLayerContext];
+    state->_observing = NO;
+    objc_setAssociatedObject(control, &RNCRefreshControlOffsetKey, nil, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+  }
+}
+
+- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object
+                      change:(NSDictionary<NSKeyValueChangeKey, id> *)change context:(void *)context
+{
+  if (context == RNCRefreshControlLayerContext) {
+    if (_applying) return;
+    if ([keyPath isEqualToString:@"sublayerTransform"]) {
+      CATransform3D next = [change[NSKeyValueChangeNewKey] CATransform3DValue];
+      if (CATransform3DEqualToTransform(next, _appliedTransform)) return;
+      _baselineTransform = next;
+    }
+    [self apply];
+    return;
+  }
+  [super observeValueForKeyPath:keyPath ofObject:object change:change context:context];
+}
+
+- (void)dealloc
+{
+  if (_observing && _control != nil) {
+    [_control.layer removeObserver:self forKeyPath:@"sublayerTransform" context:RNCRefreshControlLayerContext];
+    [_control.layer removeObserver:self forKeyPath:@"masksToBounds" context:RNCRefreshControlLayerContext];
+  }
+}
+@end
 static NSString *const RNCCollapsiblePagerNativeScrollerIDPrefix =
   @"rnc-collapsible-pager-native-scroller:";
 
@@ -973,6 +1084,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 - (void)preparePageForHorizontalTransitionAtIndex:(NSInteger)pageIndex;
 - (void)updateSharedHeaderPressCancellationGesture;
 - (void)detachSharedHeaderPressCancellationGesture;
+- (void)updateRefreshControlForScrollView:(UIScrollView *)scrollView;
+- (void)releaseRefreshControlForScrollView:(UIScrollView *)scrollView;
 - (void)sharedHeaderPressCancellationGestureChanged:(UIPanGestureRecognizer *)recognizer;
 - (void)outerPagerGestureChanged:(UIPanGestureRecognizer *)recognizer;
 - (void)verticalPagerGuardGestureChanged:(UIPanGestureRecognizer *)recognizer;
@@ -1023,6 +1136,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   NSString *_retainedPages;
   NSMutableDictionary<NSString *, NSNumber *> *_pageOffsets;
   NSMapTable<UIScrollView *, NSValue *> *_originalInsets;
+  NSMapTable<UIScrollView *, UIRefreshControl *> *_managedRefreshControls;
+  NSHashTable<UIScrollView *> *_refreshControlObservedScrollViews;
   NSMapTable<UIScrollView *, NSNumber *> *_appliedTopInsets;
   NSMapTable<UIScrollView *, NSValue *> *_originalIndicatorInsets;
   NSMapTable<UIScrollView *, NSNumber *> *_originalAlwaysBounceVertical;
@@ -1066,6 +1181,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _pageOffsets = [NSMutableDictionary new];
     _releasedPageScrollStates = [NSMutableDictionary new];
     _originalInsets = [NSMapTable weakToStrongObjectsMapTable];
+    _managedRefreshControls = [NSMapTable weakToWeakObjectsMapTable];
+    _refreshControlObservedScrollViews = [NSHashTable weakObjectsHashTable];
     _appliedTopInsets = [NSMapTable weakToStrongObjectsMapTable];
     _originalIndicatorInsets = [NSMapTable weakToStrongObjectsMapTable];
     _originalAlwaysBounceVertical = [NSMapTable weakToStrongObjectsMapTable];
@@ -1145,6 +1262,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];
@@ -1191,6 +1318,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)dealloc
 {
+  for (UIScrollView *scrollView in _refreshControlObservedScrollViews.allObjects) {
+    [self releaseRefreshControlForScrollView:scrollView];
+  }
   [self detachSharedHeaderPressCancellationGesture];
 }
 
@@ -1729,6 +1859,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   [self detachSharedHeaderPressCancellationGesture];
   [self detachScrollObserver];
   [self restoreSharedHeadersToContainer];
+  for (UIScrollView *scrollView in _refreshControlObservedScrollViews.allObjects) {
+    [self releaseRefreshControlForScrollView:scrollView];
+  }
   for (UIScrollView *scrollView in _originalInsets.keyEnumerator) {
     NSValue *value = [_originalInsets objectForKey:scrollView];
     if (value != nil) {
@@ -2418,10 +2551,44 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   }
 }
 
+- (void)updateRefreshControlForScrollView:(UIScrollView *)scrollView
+{
+  if (!_nativeSmoothHeaderScrollEnabled || _isBeingRecycled) {
+    [self releaseRefreshControlForScrollView:scrollView];
+    return;
+  }
+  if (![_refreshControlObservedScrollViews containsObject:scrollView]) {
+    [_refreshControlObservedScrollViews addObject:scrollView];
+    [scrollView addObserver:self forKeyPath:@"refreshControl"
+                   options:NSKeyValueObservingOptionNew
+                   context:RNCScrollRefreshControlContext];
+  }
+  UIRefreshControl *previous = [_managedRefreshControls objectForKey:scrollView];
+  UIRefreshControl *current = scrollView.refreshControl;
+  if (previous != current) {
+    [RNCRefreshControlOffsetState removeControl:previous owner:self];
+    [_managedRefreshControls removeObjectForKey:scrollView];
+    if (current != nil) [_managedRefreshControls setObject:current forKey:scrollView];
+  }
+  [RNCRefreshControlOffsetState setOffset:_headerHeight + _stickyHeaderHeight
+                             forControl:current owner:self];
+}
+
+- (void)releaseRefreshControlForScrollView:(UIScrollView *)scrollView
+{
+  if ([_refreshControlObservedScrollViews containsObject:scrollView]) {
+    [scrollView removeObserver:self forKeyPath:@"refreshControl" context:RNCScrollRefreshControlContext];
+    [_refreshControlObservedScrollViews removeObject:scrollView];
+  }
+  [RNCRefreshControlOffsetState removeControl:[_managedRefreshControls objectForKey:scrollView] owner:self];
+  [_managedRefreshControls removeObjectForKey:scrollView];
+}
+
 // OneKey patch: release observers, headers and saved state while the scroll view
 // still represents the old list, before Fabric applies its next owner's props.
 - (void)restoreScrollViewState:(UIScrollView *)scrollView resetSavedOffset:(BOOL)resetSavedOffset
 {
+  [self releaseRefreshControlForScrollView:scrollView];
   if (scrollView == _observedScrollView) {
     [self detachScrollObserver];
     if (resetSavedOffset) _pageOffsets[self.currentPageKey] = @(_headerOffset);
@@ -2538,6 +2705,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   // This host already includes the fixed header and safe area in its frame.
   // UIKit automatic adjustment would add them a second time to short pages.
   scrollView.contentInsetAdjustmentBehavior = UIScrollViewContentInsetAdjustmentNever;
+  [self updateRefreshControlForScrollView:scrollView];
   CGFloat previousTopInset = scrollView.contentInset.top;
   CGFloat previousLogicalOffset = scrollView.contentOffset.y + previousTopInset;
   NSNumber *appliedTop = [_appliedTopInsets objectForKey:scrollView];
@@ -2580,6 +2748,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) {
@@ -2617,6 +2794,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
                         change:(NSDictionary<NSKeyValueChangeKey,id> *)change
                        context:(void *)context
 {
+  if (context == RNCScrollRefreshControlContext) {
+    [self updateRefreshControlForScrollView:(UIScrollView *)object];
+    return;
+  }
   if (context == RNCCollapsiblePagerContentOffsetContext && object == _observedScrollView) {
     if ([keyPath isEqualToString:@"contentSize"]) {
       NSValue *oldSize = change[NSKeyValueChangeOldKey];

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/RNCCollapsiblePagerRefreshControlTests.mm

@@ -0,0 +1,180 @@
+#import <XCTest/XCTest.h>
+#import "RNCCollapsiblePagerViewComponentView.h"
+
+@interface RNCCollapsiblePagerViewComponentView (RefreshControlTesting)
+- (void)updateRefreshControlForScrollView:(UIScrollView *)scrollView;
+- (void)releaseRefreshControlForScrollView:(UIScrollView *)scrollView;
+@end
+
+@interface RNCCollapsiblePagerRefreshControlTests : XCTestCase
+@end
+
+@implementation RNCCollapsiblePagerRefreshControlTests
+
+- (RNCCollapsiblePagerViewComponentView *)pagerWithHeader:(CGFloat)height
+{
+  RNCCollapsiblePagerViewComponentView *pager = [RNCCollapsiblePagerViewComponentView new];
+  [pager setValue:@YES forKey:@"nativeSmoothHeaderScrollEnabled"];
+  [pager setValue:@(height) forKey:@"headerHeight"];
+  [pager setValue:@44 forKey:@"stickyHeaderHeight"];
+  return pager;
+}
+
+- (void)testLateControlAndCallerOffsetUpdatesPreserveBaseline
+{
+  RNCCollapsiblePagerViewComponentView *pager = [self pagerWithHeader:64];
+  UIScrollView *scroll = [[UIScrollView alloc] initWithFrame:CGRectMake(0, 0, 320, 600)];
+  [pager updateRefreshControlForScrollView:scroll];
+  UIRefreshControl *control = [UIRefreshControl new];
+  control.bounds = CGRectMake(3, -12, 320, 60);
+  scroll.refreshControl = control;
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -108, 0.001);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, -12, 0.001);
+  [pager updateRefreshControlForScrollView:scroll];
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -108, 0.001);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, -12, 0.001);
+  control.layer.sublayerTransform = control.layer.sublayerTransform;
+  // Also cover an explicit no-op KVO notification, even if CALayer's setter
+  // suppresses notifications for equal transforms on the current OS.
+  [control.layer willChangeValueForKey:@"sublayerTransform"];
+  [control.layer didChangeValueForKey:@"sublayerTransform"];
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -108, 0.001);
+
+  // Fabric's progressViewOffset setter replaces bounds.origin.y directly.
+  control.bounds = CGRectMake(3, -20, 320, 60);
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -108, 0.001);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, -20, 0.001);
+  [pager setValue:@100 forKey:@"headerHeight"];
+  [pager updateRefreshControlForScrollView:scroll];
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -144, 0.001);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, -20, 0.001);
+  [pager releaseRefreshControlForScrollView:scroll];
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, -20, 0.001);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.x, 3, 0.001);
+}
+
+- (void)testUIKitSizeChangesAndRefreshCycleDoNotAccumulateOffset
+{
+  RNCCollapsiblePagerViewComponentView *pager = [self pagerWithHeader:64];
+  UIScrollView *scroll = [[UIScrollView alloc] initWithFrame:CGRectMake(0, 0, 320, 600)];
+  // UIKit ignores offscreen beginRefreshing calls. Exercise the actual refresh
+  // lifecycle in a visible window rather than weakening the state assertion.
+  UIWindow *window = [[UIWindow alloc] initWithFrame:scroll.frame];
+  UIViewController *controller = [UIViewController new];
+  window.rootViewController = controller;
+  scroll.contentInsetAdjustmentBehavior = UIScrollViewContentInsetAdjustmentNever;
+  [controller.view addSubview:scroll];
+  window.hidden = NO;
+  [self addTeardownBlock:^{ window.hidden = YES; }];
+  UIRefreshControl *control = [UIRefreshControl new];
+  scroll.refreshControl = control;
+  [window layoutIfNeeded];
+  [scroll layoutIfNeeded];
+  XCTAssertEqual(control.window, window);
+  [pager updateRefreshControlForScrollView:scroll];
+  CGRect bounds = control.bounds;
+  bounds.size = CGSizeMake(320, 60);
+  control.bounds = bounds;
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -108, 0.001);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, 0, 0.001);
+  [control beginRefreshing];
+  [control layoutIfNeeded];
+  [pager updateRefreshControlForScrollView:scroll];
+  XCTAssertTrue(control.isRefreshing);
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -108, 0.001);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, 0, 0.001);
+  [control endRefreshing];
+  [control layoutIfNeeded];
+  XCTAssertFalse(control.isRefreshing);
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -108, 0.001);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, 0, 0.001);
+  [pager releaseRefreshControlForScrollView:scroll];
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, 0, 0.001);
+  XCTAssertTrue(CATransform3DIsIdentity(control.layer.sublayerTransform));
+}
+
+- (void)testReplacementAndNestedOwnerReleaseRestoreOnlyTheirContributions
+{
+  RNCCollapsiblePagerViewComponentView *first = [self pagerWithHeader:64];
+  RNCCollapsiblePagerViewComponentView *second = [self pagerWithHeader:20];
+  UICollectionView *scroll = [[UICollectionView alloc] initWithFrame:CGRectMake(0, 0, 320, 600)
+                                                        collectionViewLayout:[UICollectionViewFlowLayout new]];
+  UIRefreshControl *original = [UIRefreshControl new];
+  scroll.refreshControl = original;
+  [first updateRefreshControlForScrollView:scroll];
+  [second updateRefreshControlForScrollView:scroll];
+  XCTAssertEqualWithAccuracy(original.layer.sublayerTransform.m42, -172, 0.001);
+  [first releaseRefreshControlForScrollView:scroll];
+  XCTAssertEqualWithAccuracy(original.layer.sublayerTransform.m42, -64, 0.001);
+
+  UIRefreshControl *replacement = [UIRefreshControl new];
+  replacement.bounds = CGRectMake(0, -8, 320, 60);
+  scroll.refreshControl = replacement;
+  XCTAssertTrue(CATransform3DIsIdentity(original.layer.sublayerTransform));
+  XCTAssertEqualWithAccuracy(replacement.layer.sublayerTransform.m42, -64, 0.001);
+  XCTAssertEqualWithAccuracy(replacement.bounds.origin.y, -8, 0.001);
+  [second prepareForRecycle];
+  XCTAssertEqualWithAccuracy(replacement.bounds.origin.y, -8, 0.001);
+  XCTAssertTrue(CATransform3DIsIdentity(replacement.layer.sublayerTransform));
+  scroll.refreshControl = nil;
+}
+
+- (void)testPagerDestructionRestoresControl
+{
+  UIScrollView *scroll = [UIScrollView new];
+  UIRefreshControl *control = [UIRefreshControl new];
+  scroll.refreshControl = control;
+  @autoreleasepool {
+    RNCCollapsiblePagerViewComponentView *pager = [self pagerWithHeader:64];
+    [pager updateRefreshControlForScrollView:scroll];
+    XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -108, 0.001);
+    XCTAssertEqualWithAccuracy(control.bounds.origin.y, 0, 0.001);
+  }
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, 0, 0.001);
+  XCTAssertTrue(CATransform3DIsIdentity(control.layer.sublayerTransform));
+}
+
+- (void)testCallerOffsetCollisionDoesNotAffectVisualContribution
+{
+  RNCCollapsiblePagerViewComponentView *pager = [self pagerWithHeader:56];
+  UIScrollView *scroll = [UIScrollView new];
+  UIRefreshControl *control = [UIRefreshControl new];
+  scroll.refreshControl = control;
+  control.bounds = CGRectMake(0, -200, 320, 60);
+  [pager updateRefreshControlForScrollView:scroll];
+  control.bounds = CGRectMake(0, -100, 320, 60);
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, -100, 0.001);
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, -100, 0.001);
+  [pager releaseRefreshControlForScrollView:scroll];
+  XCTAssertEqualWithAccuracy(control.bounds.origin.y, -100, 0.001);
+  XCTAssertTrue(CATransform3DIsIdentity(control.layer.sublayerTransform));
+}
+
+- (void)testNestedOwnerDestructionPreservesBaselineAndRestoresClipping
+{
+  RNCCollapsiblePagerViewComponentView *second = [self pagerWithHeader:20];
+  UIScrollView *scroll = [UIScrollView new];
+  UIRefreshControl *control = [UIRefreshControl new];
+  scroll.refreshControl = control;
+  CATransform3D baseline = CATransform3DMakeTranslation(7, 13, 0);
+  control.layer.sublayerTransform = baseline;
+  control.layer.masksToBounds = YES;
+  @autoreleasepool {
+    RNCCollapsiblePagerViewComponentView *first = [self pagerWithHeader:64];
+    [first updateRefreshControlForScrollView:scroll];
+    [second updateRefreshControlForScrollView:scroll];
+    XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, 13 - 172, 0.001);
+    XCTAssertFalse(control.layer.masksToBounds);
+  }
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, 13 - 64, 0.001);
+  // A UIKit layer reset must not discard the remaining visual contribution.
+  control.layer.sublayerTransform = baseline;
+  control.layer.masksToBounds = YES;
+  XCTAssertEqualWithAccuracy(control.layer.sublayerTransform.m42, 13 - 64, 0.001);
+  XCTAssertFalse(control.layer.masksToBounds);
+  [second releaseRefreshControlForScrollView:scroll];
+  XCTAssertTrue(CATransform3DEqualToTransform(control.layer.sublayerTransform, baseline));
+  XCTAssertTrue(control.layer.masksToBounds);
+}
+
+@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.254",
+  "version": "3.0.157-alpha.256",
   "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.254",
+    "@onekeyfe/react-native-native-logger": "3.0.157-alpha.255",
     "react": "*",
     "react-native": "*"
   },