@onekeyfe/react-native-pager-view 3.0.157-alpha.257 → 3.0.157-alpha.262

package/docs/SPEC.md

@@ -3,43 +3,287 @@
 Existing PagerView and CollapsiblePagerView APIs are documented in README.md.
 The sections below define native coordination boundaries without new React props.
 
-## Android NativeScroller refresh indicator placement
-
-Status: implemented; Android API 36 Home pull-gesture visibility verified on
-2026-09-28. Spot, Perps and DeFi (RN NativeScroller), plus the unchanged NFT and
-History (NativeList), each pass header-origin and content-origin pulls. Ten
-recordings show a visible indicator below the shared tabs, one refresh event and
-normal disappearance. This verifies UI feedback and event dispatch, not
-downstream request completion. Dynamic caller offset, refresh-time header resize
-and nested-pager replacement remain separate device acceptance work.
-In smooth-header mode, each pager contributes its header-plus-sticky height in
-physical pixels to the RN NativeScroller refresh indicator's `translationY`.
-The coordinator identifies only the refresh layout's direct indicator child;
-it MUST NOT translate the content ScrollView or change refresh offsets, bounds,
-scale, animation, visibility, trigger distance, refreshing state or callbacks.
-RN retains ownership of `progressViewOffset`, including dynamic caller updates.
-NativeList keeps its existing independent refresh-indicator positioning.
-
-One state per indicator combines weak owner contributions on the UI thread.
-Repeated application and header resizing replace only the calling owner's
-contribution. An external translation different from the last applied value
-becomes the new baseline. Removing an owner preserves the remaining contributions;
-removing the final owner restores the latest baseline. A zero contribution still
-has an owner until explicitly released. State MUST NOT strongly retain an owner
-or the indicator. Late mounting, indicator replacement and scroller/pager detach
-use the existing native layout lifecycle; there is no JavaScript frame callback.
-
-The standalone JVM policy test covers nonzero baselines, repeated application,
-resize, nested owners removed in either order, external translation updates,
-zero contributions and final restoration. It does not prove Android view
-discovery, actual refresh state or rendered placement. Runtime acceptance requires
-header-origin and content-origin pulls on NativeScroller pages, caller offset
-changes, refresh-time layout changes, replacement/detach, and visible disappearance
-after completion; existing NativeList pages must remain unchanged.
+## Independent NativeScroller migration
+
+Status: implemented in source. Both native builds pass. Android focused emulator
+cases below and the iOS same-source UIKit harness pass; the full acceptance
+matrix remains incomplete. Device evidence is scoped below.
+NativeScroller keeps React children and their Fabric/Yoga layout, but owns its
+vertical native scrolling implementation: AndroidX NestedScrollView on Android
+and UIScrollView on iOS. It MUST NOT inherit ReactScrollView/RCTScrollView or
+require rebuilding ReactAndroid. Web retains its existing implementation.
+
+The initial compatibility contract covers existing Home callers: viewport style,
+contentContainerStyle including padding and flexGrow, dynamically mounted React
+children, vertical scroll enablement/indicator, stable pagerScrollKey, scroll
+throttling, onScroll/onScrollBeginDrag/onScrollEndDrag and momentum callbacks,
+content-size notification, and scrollTo/scrollToEnd commands. Standard RN
+RefreshControl JSX remains a supported input; its props and onRefresh callback
+are adapted to owned native refresh controls rather than mounting an RN-private
+scroll-view implementation. Supported properties and intentional platform limits
+MUST be explicit in the exported types. Unknown RN ScrollView features MUST NOT
+be silently advertised as supported. No business data or Home-specific geometry
+belongs in the native component.
+
+This is a vertical, non-virtualized subset, not a drop-in implementation of every
+ScrollView prop. Horizontal scrolling, sticky rows, snapping, zoom and automatic
+keyboard insets are outside this contract. iOS owns bounces and decelerationRate;
+Android retains AndroidX fling physics without a public friction override.
+Keyboard persist-tap behavior is coordinated by the JS responder wrapper using
+RN 0.86's TextInput registry, while native owns drag-to-dismiss. The RN-private
+registry dependency and keyboard behavior need validation on RN upgrades.
+Arbitrary custom refresh components are not supported.
+
+Native views, gestures, insets and refresh controllers belong to the UI thread.
+React content layout remains Fabric-owned. Layout-size updates may cross the
+bridge when dimensions change; native scrolling and header coordination MUST NOT
+depend on per-frame JS updates. This is a main/UI component, with no background
+runtime, persistent storage or cross-runtime heap state.
+
+The wrapper mounts one non-collapsible React content View. Native MUST preserve
+its Fabric-assigned frame and transform. A shared Fabric ShadowNode reads native
+state describing local content displacement and separate ancestor displacement;
+it MUST apply the ancestor displacement outside the content transform. UIKit
+updates this state from contentOffset; Android updates it from content origin,
+scroll position and pager consumption. Equal values are deduplicated, and a
+replacement state wrapper is synchronized with the current native position.
+These native state updates do not require per-frame JavaScript callbacks.
+Fabric hit testing and descendant measureInWindow MUST include the displacement,
+so measurement follows visible content after scroll, inset changes and page
+return. Geometry acceptance MUST compare a measured React child with its visible
+position, including the last child after scrollToEnd.
+
+The automatic flexGrow minimum MUST use the native usable content viewport,
+not the raw host height. An internal onContentViewportChange({height}) event
+reports logical units only when static geometry changes; it is not a public
+NativeScroller prop. Android reports viewport height minus caller/pager top
+reservation and caller bottom inset. Its pager viewport already includes the
+extra collapsible-header height. iOS reports bounds height minus caller top and
+bottom insets and the sum of pager-owned sticky reservations. Both describe the
+React area available with the shared header collapsed. The height MUST NOT
+depend on contentSize, current header offset, refresh temporary insets or iOS
+synthetic bottom fill, which would create a layout feedback loop. Owners MUST
+remove their reservation on release. The current value MUST be delivered when
+the view first becomes able to dispatch its event and after reattachment. An
+event queued before its initial emitter is ready MUST be delivered when that
+emitter becomes available. Replacing the emitter on the same attached view does
+not require another event when the usable height is unchanged.
+
+Before the first native viewport event, the wrapper contributes no positive
+automatic minimum. It combines valid native height with an explicit numeric
+caller minHeight using the greater value; nonnumeric explicit minima remain
+untouched. Content padding remains part of Yoga layout. Long-to-short replacement
+MUST clamp the local offset without leaving a pager-inset-sized artificial scroll
+range or hiding the first React child. Tests and device acceptance MUST cover
+long-to-empty/restore, page return, header/sticky resizing, refresh completion
+without minimum-height changes, and an intentionally larger caller minimum.
+
+Android MUST dispatch touch and non-touch nested scrolling continuously across
+the content/header boundary. Content returns to its start before downward travel
+expands the header; upward travel collapses the header before scrolling content.
+Consumed and remaining distance MUST be accounted for once. Only touch pull can
+trigger refresh; inertial movement MUST NOT trigger refresh. iOS MUST preserve a
+single UIScrollView trajectory through the inset/header range. Existing Pager
+refresh foreground placement and shared-header press cancellation remain in
+force. NativeList and unrelated RN ScrollViews retain their implementations.
+
+New touch, page deactivation, replacement of the mounted React content root and
+detach MUST stop stale inertia. Every started drag/momentum sequence has one
+terminal notification. An animated scrollTo/scrollToEnd command with a different
+clamped target emits one momentum begin/end pair, including AndroidX's immediate
+execution branch for closely spaced commands. A target equal to the current
+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
+resized content, fast return through the header boundary, new-touch interruption,
+adjacent/distant page changes, horizontal gestures versus row presses, pull from
+header/content, refresh completion, retained-page return, imperative
+animation/no-op/interruption, and React child measureInWindow versus visible
+geometry. History/NFT and Market/Discover are regression controls. Source/type/build success alone is not
+device acceptance. Implementation findings and remaining limits are recorded
+after validation, before this section is promoted to runtime verified.
+
+Android acceptance checkpoint (2026-09-28): the official local-shell/local-vendor
+DevSession build passed, with custom Fabric descriptor registration verified.
+On the dedicated emulator, native field inspection confirmed NativeScrollerView
+and its AndroidX viewport. Home Spot/Perps/DeFi return gestures crossed the
+content/header boundary. In the final short-fill binary, Perps content offset
+1389 reached zero and the same non-touch momentum continued header offset
+755 -> 648 -> 441 -> 217 -> 56 before natural exhaustion. This proves continuity,
+not that every gesture must fully expand the header.
+
+The first valid binary exposed an artificial 284 px short-content range. After the
+usable-viewport correction, Gallery long-to-empty replacement had local offset 0
+with short text visible; restoring rows and scrollToEnd reached the final child.
+measureInWindow y746.7/h72.0 matched native visible bounds y1960/h189px at
+pixel density2.625. Short-content refresh advanced the fixture counter once and
+controlled completion removed the indicator. Home three-page refresh visibility,
+History/NFT vertical scrolling and Market/Browser horizontal controls passed on
+the preceding valid binary; these control implementations were unchanged by the
+short-fill correction. Evidence is recorded in the app task's ignored
+`ignore/independent-native-scroller/android-acceptance.md`, alongside screenshots,
+recording chunks and native field samples.
+
+This checkpoint does not cover a physical handset, keyboard/multi-touch/accessory
+interactions, exhaustive event counts and command interruption, explicit larger
+caller minHeight, header/sticky resizing or the full refresh matrix. Existing
+development warnings were observed. Android evidence does not establish iOS
+acceptance, and source/build success is not a substitute for its runtime cases.
+
+iOS acceptance checkpoint (2026-09-28): the final official local-shell/local-vendor
+build passed and launched on the dedicated external-image simulator. Nine
+same-source UIKit harness methods and 36 assertions pass, including negative-pull
+preservation during shrink, caller inset ownership, static usable height and
+refresh/recycle interruption. This is UIKit execution, not a formal XCTest run.
+
+On the final binary, Home Spot/Perps/DeFi horizontal transitions and top-positioned
+refresh feedback passed. Gallery scrollToEnd reached the last React row;
+measureInWindow y786/h72 matched its native frame. Long-to-empty replacement,
+restoring rows, controlled refresh counter 0 -> 1 with indicator dismissal,
+normal row press and retained-page return passed. History/NFT scrolling and
+media, Discover Browser -> DeFi and Market vertical scrolling plus Trending ->
+Stocks horizontal transition passed without unintended detail navigation.
+The final device is left on expanded Home Spot. Evidence is in the app task's
+`ignore/independent-native-scroller/ios-acceptance.md` and associated recordings.
+
+These iOS gestures use public XCTest coordinate drags. Earlier private synthesized
+pan attempts had inconsistent timing and are excluded; their cause is not proven.
+Gallery's floating application tab bar overlaps part of the last row, so matching
+coordinates do not establish an unobscured bottom viewport. Existing development
+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.
+
+## 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 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,
+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
+
+Status: implemented; Android Home simulator placement verified on 2026-09-28.
+The previous below-tab placement is not accepted: the Home header can place the
+indicator in the middle of asset rows. In smooth-header mode the outermost
+coordinator MUST draw the active primary scroller's native refresh indicator
+above the shared headers at the coordinator's top. SwipeRefreshLayout retains
+trigger, animation, native visibility and refresh-state ownership. The indicator
+MUST NOT be reparented, and the coordinator MUST NOT reset progress offsets.
+
+NativeScroller and NativeList use the same foreground drawing boundary. A native
+View tag, `onekey_native_scroll_coordinator_refresh_inset`, reports only the
+refresh controller's actual coordinator-applied inset. An absent tag means zero.
+The outer drawer subtracts that inset once, preserving caller geometry and the
+native indicator matrix. This is native drawing metadata, with no JS API or row
+semantics. Nested owners MUST NOT draw duplicate indicators.
+
+The coordinator suppresses only the indicator's original drawing and restores
+its prior alpha when ownership ends, the target changes, or the pager detaches.
+An inactive page MUST NOT appear in the foreground. The foreground must clear
+when the indicator disappears. Native animation transformations MUST NOT be
+advanced a second time during drawing. Focused policy checks and device evidence
+must cover alpha restoration, nested ownership, page changes and dismissal.
+All five Home tabs require top-positioned feedback and stable header position
+through pull, release and refresh completion. Source/compile success is not
+runtime acceptance. Existing iOS/Web behavior is unchanged.
+
+The five Home tabs were recorded from both header and content origins: the
+foreground arc appears at the coordinator top and dismisses normally. The fast
+release reversal that previously changed header offset from 0 to 767 px now
+consumes the pending pull fling and keeps the header expanded. These recordings
+verify visual feedback, not downstream network completion or new callback counts.
+Production-helper tests cover alpha restoration and combined native insets;
+real nested-owner replacement, dynamic caller geometry and detach remain separate
+acceptance work. Direct foreground View drawing preserves the native circle and
+arc but does not reproduce the original RenderNode elevation shadow.
+
+## Android refresh release settlement
+
+Status: implemented; the captured release reversal passes a device A/B check.
+A downward touch gesture that leaves unconsumed travel for the active
+SwipeRefreshLayout is a pending native refresh pull. While that same gesture's
+indicator is visible, the shared header is expanded, and primary content remains
+at the top, the coordinator MUST consume nested pre-fling on release. A small
+upward reversal before lifting must settle the pull instead of starting a
+content fling and abruptly collapsing the header. SwipeRefreshLayout still owns
+whether the release triggers or cancels refresh.
+
+The pending target is weak, scoped to the current touch nested-scroll gesture,
+and cleared at its stop or replacement. An old indicator's exit animation alone
+is not a pending pull. Ordinary upward swipes, content scrolled away from the
+top, inactive pages and non-smooth mode retain existing fling behavior. A pull
+whose indicator is already hidden no longer qualifies. AndroidX can leave the
+indicator visible when reverse travel exactly exhausts the pull; that same
+gesture may still be settled instead of flung. Required regression cases include immediate reversal release,
+a stationary release, below-threshold cancellation, ordinary upward fling and
+header expansion before refresh. No JS timeout or data-refresh suppression is
+introduced.
+
+## Android downward scroll ownership
+
+Status: implemented; Android Home History runtime verified on 2026-09-28.
+Downward scrolling MUST move the active content back to its top before expanding
+the shared header. A refresh wrapper forwarding nested scrolling MUST report its
+child's ability to scroll upward; the wrapper's own scroll range is not evidence
+that the content is at the top. SwipeRefreshLayout's public canChildScrollUp()
+contract, including caller overrides, supplies this check. Other nested-scroll
+targets retain their own canScrollVertically(-1) check.
+
+The correction changes only the downward pre-scroll eligibility check. Existing
+delta consumption, content-observer alignment, refresh ownership and release
+settlement remain unchanged. Runtime comparison captured premature expansion
+with content offset 1960 px before the fix. Afterward the header stayed collapsed
+while content returned to zero, and expanded only at the top, without an observer
+forced collapse. Debugger state traces prove ownership, not frame timing;
+recordings with the debugger detached cover History rapid direction reversal
+and top refresh.
+Spot's scroll-then-refresh release-reversal sequence still jumps in both the
+baseline and corrected builds; that existing NativeScroller case remains open.
+
+## Superseded Android indicator placement
+
+The alpha.257 approach translated the RN indicator below the shared tabs.
+Its ten Home checks established visibility and event dispatch only. Subsequent
+2026-09-28 feedback showed the indicator over asset rows; those checks do not
+establish correct placement. The foreground coordination contract above replaces
+that translation policy. NativeList keeps its controller offset internally and
+publishes only its actual native inset for foreground drawing.
 
 ## iOS refresh indicator placement
 
-Status: source implementation; real refresh-cycle acceptance pending.
+Status: implemented; iOS Home pull-gesture visibility verified on 2026-09-27.
+Spot, Perps and DeFi (RN NativeScroller), plus NFT and History (NativeList),
+each pass header-origin and content-origin pulls: ten recordings show a visible
+indicator above the shared header, one refresh event and normal disappearance.
+This verifies UI feedback and event dispatch, not downstream request completion.
+The Pager UIKit suite passes 14 tests, including six refresh-control cases
+(native-tests run 36318243869). Rapid nested gestures and iPad geometry remain
+separate acceptance work.
 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
@@ -122,6 +366,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

@@ -1,4 +1,5 @@
 #import "RNCCollapsiblePagerViewComponentView.h"
+#import "RNCNativeScrollerComponentView.h"
 #import "RNCCollapsiblePagerReleasedStatePolicy.h"
 
 #import <react/renderer/components/pagerview/ComponentDescriptors.h>
@@ -12,6 +13,7 @@
 #import "React/RCTSurfaceTouchHandler.h"
 #import "React/RCTTouchHandler.h"
 #import <objc/runtime.h>
+#import <UIKit/UIGestureRecognizerSubclass.h>
 
 // OneKey patch: deduplicate structural mutation parents before scanning the page.
 #include <unordered_set>
@@ -1019,6 +1021,114 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 @end
 
+// This observer never competes for scrolling. The owning pager explicitly
+// recognizes it only after its real pan begins, so UIKit terminates RN presses.
+@interface RNCCollapsiblePagerContentPressCancellationGestureRecognizer : UIGestureRecognizer
+@property (nonatomic, weak) UIGestureRecognizer *reactTouchHandler;
+- (void)cancelPressForPan:(UIPanGestureRecognizer *)pan;
+- (void)observeIncomingTouch:(UITouch *)touch;
+@end
+
+@implementation RNCCollapsiblePagerContentPressCancellationGestureRecognizer {
+  __weak UITouch *_trackedTouch;
+  UIEvent *_touchEvent;
+  BOOL _multipleSurfaceTouchesObserved;
+}
+
+- (BOOL)canPreventGestureRecognizer:(UIGestureRecognizer *)other
+{
+  return other == self.reactTouchHandler;
+}
+
+- (void)observeIncomingTouch:(UITouch *)touch
+{
+  if (_trackedTouch != nil && touch != _trackedTouch &&
+      [touch.view isDescendantOfView:self.reactTouchHandler.view]) {
+    _multipleSurfaceTouchesObserved = YES;
+  }
+}
+
+- (void)recordEvent:(UIEvent *)event
+{
+  _touchEvent = event;
+  NSUInteger count = 0;
+  for (UITouch *touch in event.allTouches) {
+    if (touch.phase != UITouchPhaseEnded && touch.phase != UITouchPhaseCancelled &&
+        [touch.view isDescendantOfView:self.reactTouchHandler.view]) ++count;
+  }
+  if (count > 1) _multipleSurfaceTouchesObserved = YES;
+}
+
+- (void)touchesBegan:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
+{
+  if (_trackedTouch != nil || touches.count != 1) {
+    _multipleSurfaceTouchesObserved = YES;
+    if (self.state == UIGestureRecognizerStatePossible) {
+      self.state = UIGestureRecognizerStateFailed;
+    }
+    return;
+  }
+  _trackedTouch = touches.anyObject;
+  [self recordEvent:event];
+}
+
+- (void)touchesMoved:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
+{
+  [self recordEvent:event];
+}
+
+- (void)cancelPressForPan:(UIPanGestureRecognizer *)pan
+{
+  UIGestureRecognizer *handler = self.reactTouchHandler;
+  UITouch *touch = _trackedTouch;
+  if (self.state != UIGestureRecognizerStatePossible || _multipleSurfaceTouchesObserved ||
+      pan.state != UIGestureRecognizerStateBegan || touch == nil ||
+      touch.phase == UITouchPhaseEnded || touch.phase == UITouchPhaseCancelled ||
+      handler.view == nil || self.view != handler.view.superview ||
+      handler.state == UIGestureRecognizerStateFailed ||
+      handler.state == UIGestureRecognizerStateCancelled ||
+      handler.state == UIGestureRecognizerStateEnded) return;
+
+  // RN cancellation belongs to a Surface, not one finger. Do not terminate an
+  // unrelated, already active touch on that Surface during a multi-touch sequence.
+  NSUInteger activeTouches = 0;
+  for (UITouch *activeTouch in _touchEvent.allTouches) {
+    if (activeTouch.phase == UITouchPhaseEnded ||
+        activeTouch.phase == UITouchPhaseCancelled) continue;
+    if ([activeTouch.view isDescendantOfView:handler.view]) ++activeTouches;
+  }
+  if (activeTouches != 1) return;
+  self.state = UIGestureRecognizerStateBegan;
+}
+
+- (void)touchesEnded:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
+{
+  if (![touches containsObject:_trackedTouch]) return;
+  self.state = self.state == UIGestureRecognizerStateBegan
+    ? UIGestureRecognizerStateEnded : UIGestureRecognizerStateFailed;
+  _trackedTouch = nil;
+  _touchEvent = nil;
+}
+
+- (void)touchesCancelled:(NSSet<UITouch *> *)touches withEvent:(UIEvent *)event
+{
+  if (![touches containsObject:_trackedTouch]) return;
+  self.state = self.state == UIGestureRecognizerStateBegan
+    ? UIGestureRecognizerStateCancelled : UIGestureRecognizerStateFailed;
+  _trackedTouch = nil;
+  _touchEvent = nil;
+}
+
+- (void)reset
+{
+  [super reset];
+  _trackedTouch = nil;
+  _touchEvent = nil;
+  _multipleSurfaceTouchesObserved = NO;
+}
+
+@end
+
 @interface RNCCollapsiblePagerOuterPagerPanGestureRecognizer : UIPanGestureRecognizer
 @property (nonatomic, strong) NSHashTable<UIGestureRecognizer *> *blockedPagerGestures;
 @end
@@ -1065,7 +1175,8 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   UIPageViewControllerDelegate,
   UIScrollViewDelegate,
   UIGestureRecognizerDelegate,
-  RCTMountingTransactionObserving
+  RCTMountingTransactionObserving,
+  RNCNativeScrollerInsetCoordinator
 >
 - (void)finishPagerScrollEmittingSelection:(BOOL)emitSelection;
 - (void)completeTransitionOnNextRunLoopForGeneration:(NSUInteger)generation
@@ -1151,6 +1262,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   __weak UIView *_sharedHeaderPressCancellationGestureHost;
   __weak UIGestureRecognizer *_reactTouchHandler;
   UIPanGestureRecognizer *_sharedHeaderPressCancellationGesture;
+  RNCCollapsiblePagerContentPressCancellationGestureRecognizer *_contentPressCancellationGesture;
   RNCCollapsiblePagerOuterPagerPanGestureRecognizer *_sharedHeaderOuterPagerGesture;
   UIPanGestureRecognizer *_verticalPagerGesture;
   BOOL _observingContentOffset;
@@ -1295,6 +1407,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 {
   [super didMoveToWindow];
   [self updateSharedHeaderPressCancellationGesture];
+  for (UIScrollView *scrollView in _originalInsets.keyEnumerator) {
+    [self updateNativeScrollerViewport:scrollView stickyHeight:self.window == nil ? 0 : _stickyHeaderHeight];
+  }
   // OneKey patch: removing a decelerating page from its window can suppress
   // UIKit's final scroll callback. Restore the last acknowledged page on reattach.
   if (self.window != nil && _isPagerDragging &&
@@ -1318,6 +1433,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)dealloc
 {
+  for (UIScrollView *scrollView in _originalInsets.keyEnumerator) {
+    [self updateNativeScrollerViewport:scrollView stickyHeight:0];
+  }
   for (UIScrollView *scrollView in _refreshControlObservedScrollViews.allObjects) {
     [self releaseRefreshControlForScrollView:scrollView];
   }
@@ -1863,6 +1981,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     [self releaseRefreshControlForScrollView:scrollView];
   }
   for (UIScrollView *scrollView in _originalInsets.keyEnumerator) {
+    [self updateNativeScrollerViewport:scrollView stickyHeight:0];
     NSValue *value = [_originalInsets objectForKey:scrollView];
     if (value != nil) {
       UIEdgeInsets original = value.UIEdgeInsetsValue;
@@ -2130,6 +2249,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     return [(RNCCollapsiblePagerViewComponentView *)view
       currentVerticalScrollViewForParentPager];
   }
+  if ([view isKindOfClass:RNCNativeScrollerComponentView.class]) {
+    return ((RNCNativeScrollerComponentView *)view).scrollView;
+  }
   if ([view isKindOfClass:RCTScrollViewComponentView.class]) {
     RCTScrollViewComponentView *componentView =
       (RCTScrollViewComponentView *)view;
@@ -2344,10 +2466,18 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   }
   _observingContentOffset = NO;
   _observedScrollView = nil;
+  if ([scrollView.superview isKindOfClass:RNCNativeScrollerComponentView.class]) {
+    [(RNCNativeScrollerComponentView *)scrollView.superview stopScrolling];
+  }
 }
 
 - (void)detachSharedHeaderPressCancellationGesture
 {
+  if (_contentPressCancellationGesture.view != nil) {
+    [_contentPressCancellationGesture.view removeGestureRecognizer:_contentPressCancellationGesture];
+  }
+  _contentPressCancellationGesture.reactTouchHandler = nil;
+  _contentPressCancellationGesture = nil;
   if (_sharedHeaderPressCancellationGesture.view != nil) {
     [_sharedHeaderPressCancellationGesture.view
       removeGestureRecognizer:_sharedHeaderPressCancellationGesture];
@@ -2432,6 +2562,18 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
     _sharedHeaderOuterPagerGesture.maximumNumberOfTouches = 1;
   }
   _sharedHeaderOuterPagerGesture.blockedPagerGestures = outerPagerGestures;
+  if (_contentPressCancellationGesture == nil) {
+    _contentPressCancellationGesture =
+      [RNCCollapsiblePagerContentPressCancellationGestureRecognizer new];
+    _contentPressCancellationGesture.delegate = self;
+    // RN's external-recognizer path cancels its responder immediately only
+    // when this flag is set; otherwise reset can be deferred until finger-up.
+    _contentPressCancellationGesture.cancelsTouchesInView = YES;
+    _contentPressCancellationGesture.delaysTouchesBegan = NO;
+    _contentPressCancellationGesture.delaysTouchesEnded = NO;
+  }
+  _contentPressCancellationGesture.reactTouchHandler = reactTouchHandler;
+  [gestureHost addGestureRecognizer:_contentPressCancellationGesture];
   _reactTouchHandler = reactTouchHandler;
   _sharedHeaderPressCancellationGestureHost = gestureHost;
   [gestureHost addGestureRecognizer:_sharedHeaderPressCancellationGesture];
@@ -2588,6 +2730,7 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 // still represents the old list, before Fabric applies its next owner's props.
 - (void)restoreScrollViewState:(UIScrollView *)scrollView resetSavedOffset:(BOOL)resetSavedOffset
 {
+  [self updateNativeScrollerViewport:scrollView stickyHeight:0];
   [self releaseRefreshControlForScrollView:scrollView];
   if (scrollView == _observedScrollView) {
     [self detachScrollObserver];
@@ -2705,6 +2848,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 updateNativeScrollerViewport:scrollView stickyHeight:_stickyHeaderHeight];
   [self updateRefreshControlForScrollView:scrollView];
   CGFloat previousTopInset = scrollView.contentInset.top;
   CGFloat previousLogicalOffset = scrollView.contentOffset.y + previousTopInset;
@@ -2765,6 +2909,31 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
   if (pageIndex == _currentIndex) [self updateHeaderForScrollView:scrollView];
 }
 
+- (void)updateNativeScrollerViewport:(UIScrollView *)scrollView stickyHeight:(CGFloat)height
+{
+  if ([scrollView.superview isKindOfClass:RNCNativeScrollerComponentView.class]) {
+    [(RNCNativeScrollerComponentView *)scrollView.superview setPagerStickyHeight:height forOwner:self];
+  }
+}
+
+- (void)nativeScroller:(RNCNativeScrollerComponentView *)scroller
+    callerInsetChangedFrom:(UIEdgeInsets)previous to:(UIEdgeInsets)next
+{
+  UIScrollView *scrollView = scroller.scrollView;
+  NSValue *stored = [_originalInsets objectForKey:scrollView];
+  if (stored == nil) return;
+  UIEdgeInsets original = stored.UIEdgeInsetsValue;
+  original.top += next.top - previous.top;
+  original.left += next.left - previous.left;
+  original.bottom += next.bottom - previous.bottom;
+  original.right += next.right - previous.right;
+  [_originalInsets setObject:[NSValue valueWithUIEdgeInsets:original] forKey:scrollView];
+  NSNumber *appliedTop = [_appliedTopInsets objectForKey:scrollView];
+  if (appliedTop != nil) {
+    [_appliedTopInsets setObject:@(appliedTop.doubleValue + next.top - previous.top) forKey:scrollView];
+  }
+}
+
 - (void)reapplyInsetsToObservedScrollView
 {
   [self restoreDetachedScrollInsets];
@@ -3030,6 +3199,9 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
 
 - (void)scrollViewWillBeginDragging:(UIScrollView *)scrollView
 {
+  if (_nativeSmoothHeaderScrollEnabled && scrollView == _pagerScrollView) {
+    [_contentPressCancellationGesture cancelPressForPan:scrollView.panGestureRecognizer];
+  }
   if (_directNativePagerEnabled) {
     [self preparePageForHorizontalTransitionAtIndex:_currentIndex - 1];
     [self preparePageForHorizontalTransitionAtIndex:_currentIndex + 1];
@@ -3375,6 +3547,14 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       (unsigned long)_sharedHeaderOuterPagerGesture.blockedPagerGestures.count]);
     return YES;
   }
+  if (gestureRecognizer == _contentPressCancellationGesture) {
+    [_contentPressCancellationGesture observeIncomingTouch:touch];
+    UIView *touchView = touch.view;
+    return _nativeSmoothHeaderScrollEnabled && !_isBeingRecycled &&
+      _contentPressCancellationGesture.view != nil &&
+      [touchView isDescendantOfView:_pagerScrollView] &&
+      ![touchView isDescendantOfView:_sharedHeaderHostView];
+  }
   if (gestureRecognizer == _sharedHeaderPressCancellationGesture) {
     if (!_nativeSmoothHeaderScrollEnabled || _isBeingRecycled ||
         _sharedHeaderPressCancellationGestureHost == nil) return NO;
@@ -3415,6 +3595,12 @@ static void RNCLogNativeTabScrollBoundary(NSString *owner,
       ![other isKindOfClass:RCTTouchHandler.class] &&
       ![_sharedHeaderOuterPagerGesture.blockedPagerGestures containsObject:other];
   }
+  if (gestureRecognizer == _contentPressCancellationGesture ||
+      otherGestureRecognizer == _contentPressCancellationGesture) {
+    UIGestureRecognizer *other = gestureRecognizer == _contentPressCancellationGesture
+      ? otherGestureRecognizer : gestureRecognizer;
+    return other != _contentPressCancellationGesture.reactTouchHandler;
+  }
   if (gestureRecognizer == _sharedHeaderPressCancellationGesture ||
       otherGestureRecognizer == _sharedHeaderPressCancellationGesture) {
     UIGestureRecognizer *other = gestureRecognizer == _sharedHeaderPressCancellationGesture

package/ios/RNCNativeScrollerComponentView.h

@@ -0,0 +1,17 @@
+#import <React/RCTViewComponentView.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface RNCNativeScrollerComponentView : RCTViewComponentView
+@property (nonatomic, readonly) UIScrollView *scrollView;
+- (void)stopScrolling;
+- (void)setPagerStickyHeight:(CGFloat)height forOwner:(id)owner;
+@end
+
+// Native inset ownership stays separate from Fabric/Yoga content layout.
+@protocol RNCNativeScrollerInsetCoordinator <NSObject>
+- (void)nativeScroller:(RNCNativeScrollerComponentView *)scroller
+    callerInsetChangedFrom:(UIEdgeInsets)previous to:(UIEdgeInsets)next;
+@end
+
+NS_ASSUME_NONNULL_END