@onekeyfe/react-native-pager-view 3.0.157-alpha.258 → 3.0.157-alpha.273

package/README.md

@@ -73,6 +73,10 @@ non-adjacent presses jump directly to the target without passing intermediate
 pages. Set `nativeTabPressAnimationEnabled={true}` to always animate, or `false`
 to always jump. Swipe gestures and imperative page commands are unchanged.
 
+> **Behavior change:** earlier versions animated every native tab press when
+> `nativeTabPressAnimationEnabled` was omitted. Pass
+> `nativeTabPressAnimationEnabled={true}` to keep that behavior.
+
 Thank you again to Callstack and everyone who contributes to
 `react-native-pager-view` 💙
 

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

@@ -135,8 +135,11 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private var observedOwnedScroller: NativeScrollerViewport? = null
   private var observedOwnedScrollerKey: String? = null
   private var observedOwnedScrollerListener: ViewTreeObserver.OnScrollChangedListener? = null
+  private var observedOwnedScrollerTreeObserver: ViewTreeObserver? = null
   private var observedNativeScroller: ScrollView? = null
   private var observedNativeScrollerListener: ViewTreeObserver.OnScrollChangedListener? = null
+  private var observedNativeScrollerTreeObserver: ViewTreeObserver? = null
+  private var observedPageRemoved = false
   private var attachmentGeneration = 0
   private val touchSlopPx = ViewConfiguration.get(context).scaledTouchSlop
   private val hostIdentity = System.identityHashCode(this)
@@ -340,6 +343,12 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
         stickyHeaderView = null
       }
       else -> {
+        val observed = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
+        if (observed != null && isDescendant(observed, child)) {
+          // The page detaches only later; its scroller must not keep writing this key.
+          detachPrimaryScrollObserver(recordOffset = false)
+          observedPageRemoved = true
+        }
         when (val scrollable =
           findExplicitNativeScrollerInView(child) ?: findVerticalScrollableView(child)) {
           is RecyclerView -> restoreRecyclerInsets(scrollable)
@@ -554,7 +563,8 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     nativeTabBarView.translationY = -offset
     nativeSubHeaderView.translationY = -offset
     observedRecyclerView?.let { publishConsumedOffset(it) }
-    observedOwnedScroller?.let { publishConsumedOffset(it) }
+    // Adjacent owned pages are translated too; unchanged values are not republished.
+    for (scroller in ownedScrollerKeys.keys) publishConsumedOffset(scroller)
   }
 
   private fun pageKey(index: Int): String = pageKeys.getOrNull(index) ?: "page-$index"
@@ -647,7 +657,8 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private fun attachPrimaryScrollObserver() {
     if (selectedPage !in 0 until adapter.itemCount) return
     val previous = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
-    if (previous != null && !isDescendant(previous, adapter.pageAt(selectedPage))) {
+    if (observedPageRemoved || previous != null && !isDescendant(previous, adapter.pageAt(selectedPage))) {
+      observedPageRemoved = false
       detachPrimaryScrollObserver()
       // A replacement scroller starts at the beginning while retaining header collapse.
       pageOffsets[currentPageKey()] = 0
@@ -689,11 +700,11 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     )
   }
 
-  private fun detachRecyclerObserver() {
+  private fun detachRecyclerObserver(recordOffset: Boolean) {
     val recycler = observedRecyclerView
     val listener = observedScrollListener
     if (recycler != null) {
-      pageOffsets[currentPageKey()] = recycler.computeVerticalScrollOffset()
+      if (recordOffset) pageOffsets[currentPageKey()] = recycler.computeVerticalScrollOffset()
       publishConsumedOffset(recycler, remove = true)
     }
     if (recycler != null && listener != null) recycler.removeOnScrollListener(listener)
@@ -716,27 +727,35 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     detachPrimaryScrollObserver()
     observedNativeScroller = scroller
     applyNativeScrollerInsets(scroller, selectedPage)
-    val listener = ViewTreeObserver.OnScrollChangedListener {
-      val contentOffset = scroller.scrollY
-      pageOffsets[currentPageKey()] = contentOffset
-      if (contentOffset > 0 && headerOffsetPx < headerHeightPx) {
-        setHeaderOffset(headerHeightPx)
+    val listener = object : ViewTreeObserver.OnScrollChangedListener {
+      override fun onScrollChanged() {
+        if (observedNativeScrollerListener !== this) {
+          removeScrollChangedListener(null, scroller, this)
+          return
+        }
+        val contentOffset = scroller.scrollY
+        pageOffsets[currentPageKey()] = contentOffset
+        if (contentOffset > 0 && headerOffsetPx < headerHeightPx) {
+          setHeaderOffset(headerHeightPx)
+        }
       }
     }
     observedNativeScrollerListener = listener
-    scroller.viewTreeObserver.addOnScrollChangedListener(listener)
+    observedNativeScrollerTreeObserver = scroller.viewTreeObserver.also {
+      it.addOnScrollChangedListener(listener)
+    }
     log(
       "scroller-observer-attach inner=$selectedPage key=${currentPageKey()} " +
         "scroller=${System.identityHashCode(scroller)}",
     )
   }
 
-  private fun detachNativeScrollerObserver() {
+  private fun detachNativeScrollerObserver(recordOffset: Boolean) {
     val scroller = observedNativeScroller
     val listener = observedNativeScrollerListener
-    if (scroller != null) pageOffsets[currentPageKey()] = scroller.scrollY
-    if (scroller != null && listener != null && scroller.viewTreeObserver.isAlive) {
-      scroller.viewTreeObserver.removeOnScrollChangedListener(listener)
+    if (scroller != null && recordOffset) pageOffsets[currentPageKey()] = scroller.scrollY
+    if (scroller != null && listener != null) {
+      removeScrollChangedListener(observedNativeScrollerTreeObserver, scroller, listener)
     }
     if (scroller != null) {
       log(
@@ -746,12 +765,25 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     }
     observedNativeScroller = null
     observedNativeScrollerListener = null
+    observedNativeScrollerTreeObserver = null
   }
 
-  private fun detachPrimaryScrollObserver() {
-    detachOwnedScrollerObserver()
-    detachRecyclerObserver()
-    detachNativeScrollerObserver()
+  private fun detachPrimaryScrollObserver(recordOffset: Boolean = true) {
+    detachOwnedScrollerObserver(recordOffset)
+    detachRecyclerObserver(recordOffset)
+    detachNativeScrollerObserver(recordOffset)
+  }
+
+  private fun removeScrollChangedListener(
+    registered: ViewTreeObserver?,
+    scroller: View,
+    listener: ViewTreeObserver.OnScrollChangedListener,
+  ) {
+    // A detached scroller returns a new floating observer, while the listener is
+    // still registered on the window observer. Try every instance that can own it.
+    for (observer in arrayOf(registered, scroller.viewTreeObserver, viewTreeObserver)) {
+      if (observer != null && observer.isAlive) observer.removeOnScrollChangedListener(listener)
+    }
   }
 
   private fun applyOwnedScrollerInsets(scroller: NativeScrollerViewport, pageIndex: Int) {
@@ -762,13 +794,14 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     ownedScrollerKeys[scroller] = key
     postForCurrentAttachment {
       if (ownedScrollerKeys[scroller] == key && scroller.isAttachedToWindow) {
-        scroller.scrollTo(0, pageOffsets[key] ?: 0)
+        scroller.host.restoreScrollOffset(pageOffsets[key] ?: 0)
       }
     }
   }
 
   private fun restoreOwnedScrollerInsets(scroller: NativeScrollerViewport) {
     scroller.stopMotion()
+    scroller.host.cancelPendingScrollRestore()
     ownedScrollerKeys.remove(scroller)
     publishConsumedOffset(scroller, remove = true)
     scroller.host.setPagerInset(this, null)
@@ -784,26 +817,35 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     observedOwnedScrollerKey = currentPageKey()
     val key = currentPageKey()
     applyOwnedScrollerInsets(scroller, selectedPage)
-    val listener = ViewTreeObserver.OnScrollChangedListener {
-      val contentOffset = scroller.scrollY
-      pageOffsets[key] = contentOffset
-      if (contentOffset > 0 && headerOffsetPx < headerHeightPx) setHeaderOffset(headerHeightPx)
+    val listener = object : ViewTreeObserver.OnScrollChangedListener {
+      override fun onScrollChanged() {
+        if (observedOwnedScrollerListener !== this) {
+          removeScrollChangedListener(null, scroller, this)
+          return
+        }
+        val contentOffset = scroller.scrollY
+        pageOffsets[key] = contentOffset
+        if (contentOffset > 0 && headerOffsetPx < headerHeightPx) setHeaderOffset(headerHeightPx)
+      }
     }
     observedOwnedScrollerListener = listener
-    scroller.viewTreeObserver.addOnScrollChangedListener(listener)
+    observedOwnedScrollerTreeObserver = scroller.viewTreeObserver.also {
+      it.addOnScrollChangedListener(listener)
+    }
   }
 
-  private fun detachOwnedScrollerObserver() {
+  private fun detachOwnedScrollerObserver(recordOffset: Boolean) {
     val scroller = observedOwnedScroller ?: return
     scroller.stopMotion()
     publishConsumedOffset(scroller, remove = true)
-    observedOwnedScrollerKey?.let { pageOffsets[it] = scroller.scrollY }
+    if (recordOffset) observedOwnedScrollerKey?.let { pageOffsets[it] = scroller.scrollY }
     observedOwnedScrollerListener?.let {
-      if (scroller.viewTreeObserver.isAlive) scroller.viewTreeObserver.removeOnScrollChangedListener(it)
+      removeScrollChangedListener(observedOwnedScrollerTreeObserver, scroller, it)
     }
     observedOwnedScroller = null
     observedOwnedScrollerKey = null
     observedOwnedScrollerListener = null
+    observedOwnedScrollerTreeObserver = null
   }
 
   private fun applyRecyclerInsets(recycler: RecyclerView, pageIndex: Int) {

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

@@ -0,0 +1,26 @@
+package com.reactnativepagerview
+
+/**
+ * A pager-owned offset restoration that NestedScrollView clamped because the
+ * React content height had not reached native yet. It is reapplied on content
+ * layout until reached or cancelled by user/command/content replacement.
+ */
+internal class NativeScrollerPendingRestore {
+  var target: Int? = null
+    private set
+
+  fun request(target: Int, reached: Int) {
+    this.target = if (reached == target) null else target
+  }
+
+  /** The offset to reapply after a content layout pass. */
+  fun anchor(current: Int): Int = target ?: current
+
+  fun settle(reached: Int) {
+    if (target == reached) target = null
+  }
+
+  fun cancel() {
+    target = null
+  }
+}

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

@@ -64,6 +64,8 @@ class NativeScrollerView(context: Context) : FrameLayout(context) {
   private var lastScrollEvent = 0L
   private var laidOut = false
   private var requestedRefresh = false
+  private var refreshStatePending = false
+  private val pendingRestore = NativeScrollerPendingRestore()
   private var refreshOffset = 0
   private var appliedRefreshOffset: Int? = null
   private var appliedRefreshSize = SwipeRefreshLayout.DEFAULT
@@ -175,6 +177,7 @@ class NativeScrollerView(context: Context) : FrameLayout(context) {
 
   internal fun removeReactChild() {
     viewport.stopMotion()
+    pendingRestore.cancel()
     reactChild?.let(contentOriginFrame::removeView)
     reactChild = null
     contentWidthPx = 0
@@ -221,19 +224,35 @@ class NativeScrollerView(context: Context) : FrameLayout(context) {
     )
     refresh.layout(0, 0, width, height)
     // Reapply the current anchor after content shrink; NestedScrollView clamps it.
-    viewport.scrollTo(x, y)
+    // A pager restoration clamped before content reached native resumes as it grows.
+    viewport.scrollTo(x, pendingRestore.anchor(y))
+    pendingRestore.settle(viewport.scrollY)
     laidOut = true
     publishContentViewport()
     publishContentOrigin()
     applyRefreshOffset()
-    if (refresh.isRefreshing != requestedRefresh) refresh.isRefreshing = requestedRefresh
+    // Apply only a prop received before the first layout. Reapplying it on later
+    // layouts would hide a gesture-started spinner before JS commits refreshing.
+    if (refreshStatePending) {
+      refreshStatePending = false
+      if (refresh.isRefreshing != requestedRefresh) refresh.isRefreshing = requestedRefresh
+    }
   }
 
   internal fun setRefreshing(value: Boolean) {
     requestedRefresh = value
-    if (laidOut) refresh.isRefreshing = value
+    if (laidOut) refresh.isRefreshing = value else refreshStatePending = true
+  }
+
+  /** Scrolls to a pager-owned saved offset, retrying while content is too short to reach it. */
+  internal fun restoreScrollOffset(y: Int) {
+    val target = y.coerceAtLeast(0)
+    viewport.scrollTo(0, target)
+    pendingRestore.request(target, viewport.scrollY)
   }
 
+  internal fun cancelPendingScrollRestore() = pendingRestore.cancel()
+
   internal fun setRefreshOffset(value: Int) {
     refreshOffset = value
     applyRefreshOffset()
@@ -273,6 +292,7 @@ class NativeScrollerView(context: Context) : FrameLayout(context) {
 
   internal fun scrollToPosition(x: Int, y: Int, animated: Boolean) {
     viewport.stopMotion()
+    pendingRestore.cancel()
     if (animated) viewport.scrollToAnimated(y)
     else viewport.scrollTo(0, y.coerceAtLeast(0))
     emitScroll(force = true)
@@ -395,6 +415,7 @@ internal class NativeScrollerViewport(context: Context, internal val host: Nativ
   // Record at the refresh boundary so interception does not truncate the pointer history.
   internal fun recordTouchEvent(event: MotionEvent) {
     if (event.actionMasked == MotionEvent.ACTION_DOWN) {
+      host.cancelPendingScrollRestore()
       stopMotion()
       velocityTracker = VelocityTracker.obtain()
       activePointerId = event.getPointerId(0)
@@ -422,6 +443,8 @@ internal class NativeScrollerViewport(context: Context, internal val host: Nativ
   internal fun beginDrag(event: MotionEvent) {
     if (dragging) return
     dragging = true
+    // Header-forwarded touches bypass the refresh boundary's touch stream.
+    host.cancelPendingScrollRestore()
     if (host.keyboardDismissMode != "none") host.dismissKeyboard()
     NativeGestureUtil.notifyNativeGestureStarted(host, event)
     host.emitLifecycle("topScrollBeginDrag")
@@ -481,13 +504,17 @@ internal class NativeScrollerViewport(context: Context, internal val host: Nativ
       try { endDrag(cancel) } finally { cancel.recycle() }
     }
     releaseTouchTracking()
-    stopping = true
-    try {
-      // Replace the same AndroidX trajectory with zero velocity without touching its smooth-scroll clock.
-      super.fling(0)
-      super.stopNestedScroll(ViewCompat.TYPE_NON_TOUCH)
-    } finally {
-      stopping = false
+    // An idle view has nothing to stop. A zero fling would still start and stop a
+    // non-touch nested scroll, which ancestors observe as a finished gesture.
+    if (momentum || hasNestedScrollingParent(ViewCompat.TYPE_NON_TOUCH)) {
+      stopping = true
+      try {
+        // Replace the same AndroidX trajectory with zero velocity without touching its smooth-scroll clock.
+        super.fling(0)
+        super.stopNestedScroll(ViewCompat.TYPE_NON_TOUCH)
+      } finally {
+        stopping = false
+      }
     }
     finishMomentum()
   }

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

@@ -2,7 +2,9 @@ package com.reactnativepagerview
 
 import android.graphics.Color
 import android.view.View
+import com.facebook.react.bridge.ColorPropConverter
 import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableType
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.uimanager.ReactStylesDiffMap
 import com.facebook.react.uimanager.StateWrapper
@@ -100,7 +102,20 @@ class NativeScrollerViewManager : ViewGroupManager<NativeScrollerView>(),
   }
   @ReactProp(name = "refreshColors", customType = "ColorArray")
   override fun setRefreshColors(view: NativeScrollerView, value: ReadableArray?) {
-    view.setRefreshColors(if (value == null) intArrayOf(Color.GRAY) else IntArray(value.size()) { value.getInt(it) })
+    if (value == null) {
+      view.setRefreshColors(intArrayOf(Color.GRAY))
+      return
+    }
+    val colors = ArrayList<Int>(value.size())
+    for (index in 0 until value.size()) {
+      // PlatformColor/DynamicColorIOS values arrive as maps, as in RN's SwipeRefreshLayoutManager.
+      when (value.getType(index)) {
+        ReadableType.Map -> ColorPropConverter.getColor(value.getMap(index), view.context)?.let(colors::add)
+        ReadableType.Number -> colors.add(value.getInt(index))
+        else -> Unit
+      }
+    }
+    view.setRefreshColors(colors.toIntArray())
   }
   @ReactProp(name = "refreshProgressBackgroundColor", customType = "Color")
   override fun setRefreshProgressBackgroundColor(view: NativeScrollerView, value: Int?) =

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

@@ -0,0 +1,31 @@
+package com.reactnativepagerview
+
+/** Standalone JVM regression: compile together with the production helper. */
+fun main() {
+  val restore = NativeScrollerPendingRestore()
+
+  // Reachable immediately: nothing remains pending and layout keeps the current anchor.
+  restore.request(target = 640, reached = 640)
+  check(restore.target == null)
+  check(restore.anchor(320) == 320)
+
+  // Content height has not reached native: NestedScrollView clamped the request to 0.
+  restore.request(target = 640, reached = 0)
+  check(restore.target == 640)
+  check(restore.anchor(0) == 640)
+  // Partial growth keeps retrying the original target, not the partially clamped offset.
+  restore.settle(reached = 300)
+  check(restore.target == 640)
+  check(restore.anchor(300) == 640)
+  // Once reached, later layouts keep the live position again.
+  restore.settle(reached = 640)
+  check(restore.target == null)
+  check(restore.anchor(900) == 900)
+
+  // User touch, commands and content replacement cancel a pending target.
+  restore.request(target = 480, reached = 120)
+  restore.cancel()
+  check(restore.target == null)
+  check(restore.anchor(120) == 120)
+  println("Native scroller pending restore: clamp retry, partial growth, settle and cancel passed")
+}

package/docs/SPEC.md

@@ -96,7 +96,13 @@ position emits no new pair. A new command ends any previous active sequence
 before starting its own, and non-animated movement does not start momentum;
 recycled views MUST NOT emit into an old owner. Content shrink clamps unreachable
 offsets without a blank tail; resize/inset changes MUST NOT accumulate offsets.
+On Android, a pager offset restoration that is clamped because React content has
+not reached native yet is reapplied on content layout until reached; a new touch,
+drag, scroll command, content-root replacement or pager release cancels it.
+Stopping an idle scroller MUST NOT start or end a non-touch nested scroll.
 Refresh is controlled by the caller and emits once per qualifying gesture.
+Android applies a refreshing value when it changes (or at first layout); later
+layout passes do not reassert it over a gesture-started indicator.
 
 Acceptance requires both native builds, focused contract checks and iOS/Android
 recordings: expanded/collapsed Home Spot/Perps/DeFi, short/empty and dynamically
@@ -159,19 +165,46 @@ warnings were observed. Keyboard, multi-touch, physical-device performance and
 the full lifecycle/interaction matrix remain unverified. These are local source
 builds; the currently installed npm version does not yet contain this migration.
 
+## iOS vertical-scroll press cancellation
+
+Status: implemented in source. A source-identical `node_modules` build was
+runtime verified on a dedicated iOS 26.5 HomePager simulator on 2026-09-30:
+a slow drag from the Show more button did not activate it, a fling from the
+same button scrolled the list, and a stationary tap activated it. The Pager
+XCTest suite passed 47/47 tests on a separate iOS 26.5 simulator with its data
+on the external drive on 2026-09-30.
+
+In `CollapsiblePagerView` smooth-header mode, a single-finger
+vertical drag beginning on React page content MUST cancel that Surface's active
+React press before finger-up once vertical displacement reaches 10 points and
+exceeds horizontal displacement. Cancellation MUST leave the native vertical
+scroller's pan and momentum intact. Stationary taps, movement below the threshold,
+horizontal drags, and multi-touch sequences MUST retain their existing behavior.
+The iOS content press bridge owns cancellation on the UI thread; the pager's
+existing horizontal-drag cancellation remains independent. The bridge MUST clear
+per-touch state on end, cancellation, and reuse. Android and Web behavior is
+unchanged. Acceptance requires a real iOS button-origin drag that does not fire
+the button, a button-origin fling that scrolls, an ordinary tap that fires, and
+focused native touch-delivery coverage.
+
 ## Native tab-press animation default
 
+Behavior change: previously an omitted `nativeTabPressAnimationEnabled` animated
+every native tab press. Callers that relied on that default MUST pass `true`.
+
 On iOS and Android, an omitted `nativeTabPressAnimationEnabled` MUST animate a
 press to an adjacent page and jump directly to a non-adjacent page. Adjacency is
-the absolute difference between the target index and the currently selected
-index, not the last requested target. Explicit `true` continues to animate all
+the absolute difference between the target index and the current page. While a
+tab command that native has already received is in flight, its target is the
+current page; otherwise it is the selected index. A request superseded before it
+reached native is ignored. Explicit `true` continues to animate all
 tab presses, and explicit `false` continues to jump for all tab presses.
 Page retention, selection callbacks, swipe gestures, imperative `setPage` /
 `setPageWithoutAnimation` commands and Web behavior retain their contracts.
 Callers rendering their own JS tab bar choose the matching imperative command.
 
-Status: implemented; focused native-wrapper tests cover both directions and
-explicit overrides. Home applies this policy to its JS tab bar, with iOS and
+Status: implemented; focused native-wrapper tests cover both directions,
+explicit overrides and in-flight/superseded command targets. Home applies this policy to its JS tab bar, with iOS and
 Android simulator recordings verifying distant jumps and adjacent transitions.
 
 ## Android refresh foreground coordination
@@ -295,6 +328,24 @@ 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.
 
+When a smooth shared header is attached to the active iOS scroll view, UIKit's
+temporary refresh top inset MUST keep the header and content aligned. Both are
+children of that scroll view and move together with its content offset; the
+pager MUST NOT apply a separate refresh translation to the header. The scroll
+view's inset and offset, the refresh indicator, and refresh callback ownership
+remain unchanged. Removing the refresh inset or control preserves this alignment
+even without a scroll-offset event. Caller inset changes update the pager
+baseline. The sticky tab row MUST pin against the baseline top inset; the
+refresh control's temporary inset MUST NOT move it below the content, including
+rapid direction reversals while the spinner is active. Detaching the header
+restores its normal transform. This applies to RN NativeScroller and NativeList
+pages; non-smooth and detached headers keep
+their existing positioning. The 2026-09-30 Home Spot simulator checkpoint covers
+shared header/content alignment and inset removal. A separate source-identical
+local package build verified the sticky row during active-refresh vertical
+reversals; published-package, other Home pages and physical-device acceptance
+remain open.
+
 ## iOS shared-header hit testing
 
 Smooth-header hit forwarding is restricted to the pager's own interactive
@@ -355,6 +406,10 @@ 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.
+Every NativeScroller viewport the coordinator owns, including adjacent pages it
+translates, receives each header offset change, not only the observed page.
+Content-offset observers are removed from the observer instance they were
+registered on, and a removed page's scroller stops writing offsets immediately.
 
 ## Acceptance
 

package/ios/RNCCollapsiblePagerViewComponentView.mm

@@ -1033,6 +1033,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   __weak UITouch *_trackedTouch;
   UIEvent *_touchEvent;
   BOOL _multipleSurfaceTouchesObserved;
+  CGPoint _trackedTouchStartPoint;
+  BOOL _didCancelReactPressForVerticalMovement;
 }
 
 - (BOOL)canPreventGestureRecognizer:(UIGestureRecognizer *)other
@@ -1069,12 +1071,37 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     return;
   }
   _trackedTouch = touches.anyObject;
+  _trackedTouchStartPoint = [_trackedTouch locationInView:self.view];
+  _didCancelReactPressForVerticalMovement = NO;
   [self recordEvent:event];
 }
 
 - (void)touchesMoved:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
 {
   [self recordEvent:event];
+  UITouch *touch = _trackedTouch;
+  UIGestureRecognizer *handler = self.reactTouchHandler;
+  if (touch == nil || ![touches containsObject:touch] ||
+      self.state != UIGestureRecognizerStatePossible ||
+      _didCancelReactPressForVerticalMovement || _multipleSurfaceTouchesObserved ||
+      handler.view == nil || self.view != handler.view.superview ||
+      handler.state == UIGestureRecognizerStateFailed ||
+      handler.state == UIGestureRecognizerStateCancelled ||
+      handler.state == UIGestureRecognizerStateEnded) return;
+  CGPoint point = [touch locationInView:self.view];
+  CGFloat dx = point.x - _trackedTouchStartPoint.x;
+  CGFloat dy = point.y - _trackedTouchStartPoint.y;
+  if (fabs(dy) < 10.0 || fabs(dy) <= fabs(dx)) return;
+  NSUInteger activeTouches = 0;
+  for (UITouch *activeTouch in event.allTouches) {
+    if (activeTouch.phase == UITouchPhaseEnded ||
+        activeTouch.phase == UITouchPhaseCancelled) continue;
+    if ([activeTouch.view isDescendantOfView:handler.view]) ++activeTouches;
+  }
+  if (activeTouches != 1) return;
+  _didCancelReactPressForVerticalMovement = YES;
+  handler.enabled = NO;
+  handler.enabled = YES;
 }
 
 - (void)cancelPressForPan:(UIPanGestureRecognizer *)pan
@@ -1108,6 +1135,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     ? UIGestureRecognizerStateEnded : UIGestureRecognizerStateFailed;
   _trackedTouch = nil;
   _touchEvent = nil;
+  _didCancelReactPressForVerticalMovement = NO;
 }
 
 - (void)touchesCancelled:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
@@ -1117,6 +1145,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     ? UIGestureRecognizerStateCancelled : UIGestureRecognizerStateFailed;
   _trackedTouch = nil;
   _touchEvent = nil;
+  _didCancelReactPressForVerticalMovement = NO;
 }
 
 - (void)reset
@@ -1125,6 +1154,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   _trackedTouch = nil;
   _touchEvent = nil;
   _multipleSurfaceTouchesObserved = NO;
+  _didCancelReactPressForVerticalMovement = NO;
 }
 
 @end
@@ -2437,6 +2467,10 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
               forKeyPath:@"contentOffset"
                  options:NSKeyValueObservingOptionNew
                  context:RNCCollapsiblePagerContentOffsetContext];
+  [candidate addObserver:self
+              forKeyPath:@"contentInset"
+                 options:NSKeyValueObservingOptionNew
+                 context:RNCCollapsiblePagerContentOffsetContext];
   [candidate addObserver:self
               forKeyPath:@"contentSize"
                  options:NSKeyValueObservingOptionOld | NSKeyValueObservingOptionNew
@@ -2459,6 +2493,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       [scrollView removeObserver:self
                       forKeyPath:@"contentOffset"
                          context:RNCCollapsiblePagerContentOffsetContext];
+      [scrollView removeObserver:self
+                      forKeyPath:@"contentInset"
+                         context:RNCCollapsiblePagerContentOffsetContext];
       [scrollView removeObserver:self
                       forKeyPath:@"contentSize"
                          context:RNCCollapsiblePagerContentOffsetContext];
@@ -2932,6 +2969,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (appliedTop != nil) {
     [_appliedTopInsets setObject:@(appliedTop.doubleValue + next.top - previous.top) forKey:scrollView];
   }
+  if (scrollView == _observedScrollView) [self updateHeaderForScrollView:scrollView];
 }
 
 - (void)reapplyInsetsToObservedScrollView
@@ -2964,10 +3002,16 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
                        context:(void *)context
 {
   if (context == RNCScrollRefreshControlContext) {
-    [self updateRefreshControlForScrollView:(UIScrollView *)object];
+    UIScrollView *scrollView = (UIScrollView *)object;
+    [self updateRefreshControlForScrollView:scrollView];
+    if (scrollView == _observedScrollView) [self updateHeaderForScrollView:scrollView];
     return;
   }
   if (context == RNCCollapsiblePagerContentOffsetContext && object == _observedScrollView) {
+    if ([keyPath isEqualToString:@"contentInset"]) {
+      [self updateHeaderForScrollView:(UIScrollView *)object];
+      return;
+    }
     if ([keyPath isEqualToString:@"contentSize"]) {
       NSValue *oldSize = change[NSKeyValueChangeOldKey];
       NSValue *newSize = change[NSKeyValueChangeNewKey];
@@ -2998,9 +3042,15 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   BOOL attachedToList = _nativeSmoothHeaderScrollEnabled &&
     _sharedHeaderScrollView != nil && !_sharedHeadersLiftedForPagerTransition;
   if (attachedToList) {
+    // The header and content share this scroll view. UIKit's refresh inset
+    // moves both together, so translating the header would separate them.
     _sharedHeaderHostView.transform = CGAffineTransformIdentity;
     _headerView.transform = CGAffineTransformIdentity;
-    CGFloat pinnedTranslation = MAX(0, _currentLogicalOffset - _headerHeight);
+    UIScrollView *scrollView = _sharedHeaderScrollView;
+    NSNumber *appliedTop = [_appliedTopInsets objectForKey:scrollView];
+    CGFloat refreshInset = scrollView.refreshControl != nil && appliedTop != nil
+      ? MAX(0, scrollView.contentInset.top - appliedTop.doubleValue) : 0;
+    CGFloat pinnedTranslation = MAX(0, _currentLogicalOffset - _headerHeight - refreshInset);
     CGAffineTransform stickyTransform = CGAffineTransformMakeTranslation(0, pinnedTranslation);
     _stickyHeaderView.transform = stickyTransform;
     _nativeTabBarView.transform = stickyTransform;