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

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

@@ -0,0 +1,130 @@
+package com.reactnativepagerview
+
+import android.graphics.Color
+import android.view.View
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.ReactStylesDiffMap
+import com.facebook.react.uimanager.StateWrapper
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.uimanager.annotations.ReactProp
+import com.facebook.react.viewmanagers.RNCNativeScrollerManagerDelegate
+import com.facebook.react.viewmanagers.RNCNativeScrollerManagerInterface
+
+@ReactModule(name = NativeScrollerViewManager.NAME)
+class NativeScrollerViewManager : ViewGroupManager<NativeScrollerView>(),
+  RNCNativeScrollerManagerInterface<NativeScrollerView> {
+  private val delegate: ViewManagerDelegate<NativeScrollerView> = RNCNativeScrollerManagerDelegate(this)
+  override fun getDelegate() = delegate
+  override fun getName() = NAME
+  override fun createViewInstance(context: ThemedReactContext) = NativeScrollerView(context)
+  override fun needsCustomLayoutForChildren() = false
+  override fun addView(parent: NativeScrollerView, child: View, index: Int) = parent.addReactChild(child, index)
+  override fun getChildCount(parent: NativeScrollerView) = parent.reactChildCount()
+  override fun getChildAt(parent: NativeScrollerView, index: Int) = parent.reactChildAt(index)
+  override fun removeViewAt(parent: NativeScrollerView, index: Int) {
+    require(index == 0)
+    parent.removeReactChild()
+  }
+  override fun removeAllViews(parent: NativeScrollerView) = parent.removeReactChild()
+  override fun onDropViewInstance(view: NativeScrollerView) {
+    view.viewport.stopMotion()
+    view.setFabricState(null)
+    super.onDropViewInstance(view)
+  }
+  override fun updateState(view: NativeScrollerView, props: ReactStylesDiffMap, stateWrapper: StateWrapper): Any? {
+    view.setFabricState(stateWrapper)
+    return null
+  }
+  override fun onAfterUpdateTransaction(view: NativeScrollerView) {
+    super.onAfterUpdateTransaction(view)
+    view.scheduleLayout()
+  }
+
+  @ReactProp(name = "contentWidth")
+  override fun setContentWidth(view: NativeScrollerView, value: Double) = view.setContentSize(width = view.dip(value))
+  @ReactProp(name = "contentHeight")
+  override fun setContentHeight(view: NativeScrollerView, value: Double) = view.setContentSize(height = view.dip(value))
+  @ReactProp(name = "scrollEnabled", defaultBoolean = true)
+  override fun setScrollEnabled(view: NativeScrollerView, value: Boolean) = view.setScrollEnabled(value)
+  @ReactProp(name = "nestedScrollEnabled", defaultBoolean = true)
+  override fun setNestedScrollEnabled(view: NativeScrollerView, value: Boolean) {
+    if (!value) view.viewport.stopMotion()
+    view.viewport.isNestedScrollingEnabled = value
+  }
+  @ReactProp(name = "showsVerticalScrollIndicator", defaultBoolean = true)
+  override fun setShowsVerticalScrollIndicator(view: NativeScrollerView, value: Boolean) {
+    view.viewport.isVerticalScrollBarEnabled = value
+  }
+  @ReactProp(name = "showsHorizontalScrollIndicator")
+  override fun setShowsHorizontalScrollIndicator(view: NativeScrollerView, value: Boolean) {
+    view.viewport.isHorizontalScrollBarEnabled = value
+  }
+  // UIKit-only properties: Android keeps the platform NestedScrollView fling/edge policy.
+  @ReactProp(name = "bounces", defaultBoolean = true)
+  override fun setBounces(view: NativeScrollerView, value: Boolean) = Unit
+  @ReactProp(name = "alwaysBounceVertical", defaultBoolean = true)
+  override fun setAlwaysBounceVertical(view: NativeScrollerView, value: Boolean) = Unit
+  @ReactProp(name = "decelerationRate", defaultDouble = 0.998)
+  override fun setDecelerationRate(view: NativeScrollerView, value: Double) = Unit
+  @ReactProp(name = "keyboardDismissMode")
+  override fun setKeyboardDismissMode(view: NativeScrollerView, value: String?) {
+    view.keyboardDismissMode = value ?: "none"
+  }
+  @ReactProp(name = "keyboardShouldPersistTaps")
+  override fun setKeyboardShouldPersistTaps(view: NativeScrollerView, value: String?) {
+    // The JS responder wrapper owns never/handled/always and TextInput exceptions.
+    view.keyboardShouldPersistTaps = value ?: "never"
+  }
+  @ReactProp(name = "scrollEventThrottle")
+  override fun setScrollEventThrottle(view: NativeScrollerView, value: Double) {
+    view.scrollEventThrottle = value.coerceAtLeast(0.0)
+  }
+  @ReactProp(name = "contentInsetTop")
+  override fun setContentInsetTop(view: NativeScrollerView, value: Double) { view.insetTop = view.dip(value).coerceAtLeast(0) }
+  @ReactProp(name = "contentInsetRight")
+  override fun setContentInsetRight(view: NativeScrollerView, value: Double) { view.insetRight = view.dip(value).coerceAtLeast(0) }
+  @ReactProp(name = "contentInsetBottom")
+  override fun setContentInsetBottom(view: NativeScrollerView, value: Double) { view.insetBottom = view.dip(value).coerceAtLeast(0) }
+  @ReactProp(name = "contentInsetLeft")
+  override fun setContentInsetLeft(view: NativeScrollerView, value: Double) { view.insetLeft = view.dip(value).coerceAtLeast(0) }
+  @ReactProp(name = "refreshEnabled")
+  override fun setRefreshEnabled(view: NativeScrollerView, value: Boolean) { view.refreshEnabled = value }
+  @ReactProp(name = "refreshing")
+  override fun setRefreshing(view: NativeScrollerView, value: Boolean) = view.setRefreshing(value)
+  @ReactProp(name = "refreshTintColor", customType = "Color")
+  override fun setRefreshTintColor(view: NativeScrollerView, value: Int?) {
+    // Android's refreshColors determines the native arc; tintColor is iOS-only.
+  }
+  @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) })
+  }
+  @ReactProp(name = "refreshProgressBackgroundColor", customType = "Color")
+  override fun setRefreshProgressBackgroundColor(view: NativeScrollerView, value: Int?) =
+    view.setRefreshBackground(value ?: Color.WHITE)
+  @ReactProp(name = "refreshProgressViewOffset")
+  override fun setRefreshProgressViewOffset(view: NativeScrollerView, value: Double) = view.setRefreshOffset(view.dip(value))
+  @ReactProp(name = "refreshTitle")
+  override fun setRefreshTitle(view: NativeScrollerView, value: String?) = Unit
+  @ReactProp(name = "refreshTitleColor", customType = "Color")
+  override fun setRefreshTitleColor(view: NativeScrollerView, value: Int?) = Unit
+  @ReactProp(name = "refreshSize")
+  override fun setRefreshSize(view: NativeScrollerView, value: String?) = view.setRefreshSize(value)
+
+  override fun receiveCommand(view: NativeScrollerView, commandId: String, args: ReadableArray?) =
+    delegate.receiveCommand(view, commandId, args)
+  override fun setRefreshState(view: NativeScrollerView, refreshing: Boolean) = view.setRefreshing(refreshing)
+  override fun scrollTo(view: NativeScrollerView, x: Double, y: Double, animated: Boolean) =
+    view.scrollToPosition(view.dip(x), view.dip(y), animated)
+  override fun scrollToEnd(view: NativeScrollerView, animated: Boolean) = view.scrollToEnd(animated)
+  override fun flashScrollIndicators(view: NativeScrollerView) { view.viewport.flashIndicators() }
+
+  override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Map<String, String>> =
+    listOf("Scroll", "ScrollBeginDrag", "ScrollEndDrag", "MomentumScrollBegin", "MomentumScrollEnd", "Refresh", "ContentViewportChange")
+      .associate { "top$it" to mapOf("registrationName" to "on$it") }.toMutableMap()
+
+  companion object { const val NAME = "RNCNativeScroller" }
+}

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

@@ -12,6 +12,6 @@ class PagerViewPackage : ReactPackage {
     }
 
     override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
-        return listOf(PagerViewViewManager(), CollapsiblePagerViewManager())
+        return listOf(PagerViewViewManager(), CollapsiblePagerViewManager(), NativeScrollerViewManager())
     }
 }

package/android/src/main/jni/CMakeLists.txt

@@ -0,0 +1,19 @@
+cmake_minimum_required(VERSION 3.13)
+
+set(PAGER_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/../../../..)
+set(PAGER_GENERATED ${PAGER_ROOT}/android/build/generated/source/codegen/jni)
+set(PAGER_COMMON ${PAGER_ROOT}/common/cpp)
+file(GLOB PAGER_GENERATED_SOURCES CONFIGURE_DEPENDS
+  ${PAGER_GENERATED}/*.cpp
+  ${PAGER_GENERATED}/react/renderer/components/pagerview/*.cpp)
+
+add_library(react_codegen_pagerview OBJECT
+  ${PAGER_GENERATED_SOURCES}
+  ${PAGER_COMMON}/react/renderer/components/pagerview/RNCNativeScrollerShadowNode.cpp)
+target_include_directories(react_codegen_pagerview PUBLIC
+  ${CMAKE_CURRENT_SOURCE_DIR}
+  ${PAGER_COMMON}
+  ${PAGER_GENERATED}
+  ${PAGER_GENERATED}/react/renderer/components/pagerview)
+target_link_libraries(react_codegen_pagerview fbjni jsi reactnative)
+target_compile_reactnative_options(react_codegen_pagerview PRIVATE)

package/android/src/main/jni/pagerview.h

@@ -0,0 +1,11 @@
+#pragma once
+
+#include <ReactCommon/JavaTurboModule.h>
+#include <ReactCommon/TurboModule.h>
+#include <jsi/jsi.h>
+#include <react/renderer/components/pagerview/RNCNativeScrollerComponentDescriptor.h>
+
+namespace facebook::react {
+JSI_EXPORT std::shared_ptr<TurboModule> pagerview_ModuleProvider(
+    const std::string &moduleName, const JavaTurboModule::InitParams &params);
+} // namespace facebook::react

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

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

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

@@ -34,4 +34,42 @@ fun main() {
   // 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")
+
+  val firstOwner = Any()
+  val secondOwner = Any()
+  val alpha = NativeRefreshForegroundAlpha(0.75f)
+  check(alpha.isEmpty)
+  var current = alpha.update(0.75f, firstOwner, acquire = true)
+  check(current == 0f && alpha.drawingAlpha == 0.75f && !alpha.isEmpty)
+  current = alpha.update(current, firstOwner, acquire = true)
+  check(current == 0f && alpha.drawingAlpha == 0.75f)
+  current = alpha.update(current, secondOwner, acquire = true)
+  current = alpha.update(current, firstOwner, acquire = false)
+  check(current == 0f && !alpha.isEmpty)
+  current = alpha.update(current, secondOwner, acquire = false)
+  check(current == 0.75f && alpha.isEmpty)
+
+  current = alpha.update(current, firstOwner, acquire = true)
+  current = alpha.update(current, secondOwner, acquire = true)
+  current = alpha.update(current, secondOwner, acquire = false)
+  check(current == 0f)
+  current = alpha.update(current, firstOwner, acquire = false)
+  check(current == 0.75f && alpha.isEmpty)
+
+  current = alpha.update(current, firstOwner, acquire = true)
+  current = alpha.update(0.4f, firstOwner, acquire = true)
+  check(current == 0f && alpha.drawingAlpha == 0.4f)
+  current = alpha.update(current, firstOwner, acquire = false)
+  check(current == 0.4f && alpha.isEmpty)
+
+  val transparent = NativeRefreshForegroundAlpha(0f)
+  check(transparent.update(0f, firstOwner, acquire = true) == 0f)
+  check(!transparent.isEmpty && transparent.drawingAlpha == 0f)
+  check(transparent.update(0f, firstOwner, acquire = false) == 0f && transparent.isEmpty)
+  // RN caller offset is already in top; an absent coordinator inset is zero.
+  check(nativeRefreshForegroundTop(37, 0f) == 37f)
+  // A list publishes the sum of both actual ancestor insets; subtract it once.
+  check(nativeRefreshForegroundTop(37 + 230 + 64, 294f) == 37f)
+  check(nativeRefreshForegroundTop(-40 + 294, 294f) == -40f)
+  println("Refresh foreground policy: repeat, owner transfer/release, external alpha, transparent baseline, caller offset, and combined nested inset passed")
 }

package/common/cpp/react/renderer/components/pagerview/RNCNativeScrollerComponentDescriptor.h

@@ -0,0 +1,8 @@
+#pragma once
+
+#include <react/renderer/components/pagerview/RNCNativeScrollerShadowNode.h>
+#include <react/renderer/core/ConcreteComponentDescriptor.h>
+
+namespace facebook::react {
+using RNCNativeScrollerComponentDescriptor = ConcreteComponentDescriptor<RNCNativeScrollerShadowNode>;
+} // namespace facebook::react

package/common/cpp/react/renderer/components/pagerview/RNCNativeScrollerShadowNode.cpp

@@ -0,0 +1,15 @@
+#include <react/renderer/components/pagerview/RNCNativeScrollerShadowNode.h>
+
+namespace facebook::react {
+
+const char RNCNativeScrollerComponentName[] = "RNCNativeScroller";
+
+Point RNCNativeScrollerShadowNode::getContentOriginOffset(bool includeTransform) const {
+  const auto state = getStateData();
+  const auto origin = state.contentOrigin;
+  const auto transform = includeTransform ? getTransform() : Transform::Identity();
+  const auto result = transform * Vector{origin.x, origin.y, 0.0f, 1.0f};
+  return {result.x + state.ancestorOffset.x, result.y + state.ancestorOffset.y};
+}
+
+} // namespace facebook::react

package/common/cpp/react/renderer/components/pagerview/RNCNativeScrollerShadowNode.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <jsi/jsi.h>
+#include <react/renderer/components/pagerview/EventEmitters.h>
+#include <react/renderer/components/pagerview/Props.h>
+#include <react/renderer/components/pagerview/RNCNativeScrollerState.h>
+#include <react/renderer/components/view/ConcreteViewShadowNode.h>
+
+namespace facebook::react {
+
+JSI_EXPORT extern const char RNCNativeScrollerComponentName[];
+
+class JSI_EXPORT RNCNativeScrollerShadowNode final
+    : public ConcreteViewShadowNode<RNCNativeScrollerComponentName,
+                                    RNCNativeScrollerProps,
+                                    RNCNativeScrollerEventEmitter,
+                                    RNCNativeScrollerState> {
+ public:
+  using ConcreteViewShadowNode::ConcreteViewShadowNode;
+  Point getContentOriginOffset(bool includeTransform) const override;
+};
+
+} // namespace facebook::react

package/common/cpp/react/renderer/components/pagerview/RNCNativeScrollerState.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include <react/renderer/graphics/Point.h>
+#ifdef RN_SERIALIZABLE_STATE
+#include <folly/dynamic.h>
+#endif
+
+namespace facebook::react {
+
+// Local content displacement and ancestor translation have different transform spaces.
+class RNCNativeScrollerState final {
+ public:
+  Point contentOrigin{};
+  Point ancestorOffset{};
+  RNCNativeScrollerState() = default;
+  explicit RNCNativeScrollerState(Point origin) : contentOrigin(origin) {}
+
+#ifdef RN_SERIALIZABLE_STATE
+  RNCNativeScrollerState(const RNCNativeScrollerState &, folly::dynamic data)
+      : contentOrigin({static_cast<Float>(data["contentOriginX"].getDouble()),
+                       static_cast<Float>(data["contentOriginY"].getDouble())}),
+        ancestorOffset({static_cast<Float>(data.getDefault("ancestorOffsetX", 0.0).getDouble()),
+                        static_cast<Float>(data.getDefault("ancestorOffsetY", 0.0).getDouble())}) {}
+
+  folly::dynamic getDynamic() const {
+    return folly::dynamic::object("contentOriginX", contentOrigin.x)
+        ("contentOriginY", contentOrigin.y)
+        ("ancestorOffsetX", ancestorOffset.x)("ancestorOffsetY", ancestorOffset.y);
+  }
+#endif
+};
+
+} // namespace facebook::react

package/docs/SPEC.md

@@ -3,9 +3,276 @@
 Existing PagerView and CollapsiblePagerView APIs are documented in README.md.
 The sections below define native coordination boundaries without new React props.
 
+## 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.
+Refresh is controlled by the caller and emits once per qualifying gesture.
+
+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
+
+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
+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
+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