@onekeyfe/react-native-native-list 3.0.173 → 3.0.175

package/android/src/main/java/com/onekey/nativelist/NativeListView.kt

@@ -44,6 +44,7 @@ import org.json.JSONArray
 import org.json.JSONObject
 import java.lang.ref.WeakReference
 import java.util.UUID
+import java.util.function.BiConsumer
 import kotlin.math.abs
 import kotlin.math.ceil
 import kotlin.math.cos
@@ -60,6 +61,15 @@ private class NativeListGridLayoutManager(
 ) : GridLayoutManager(context, spanCount) {
   var onChildLaidOut: ((View, Int) -> Unit)? = null
   var onLayoutPassCompleted: (() -> Unit)? = null
+  var onBeforeDataLayout: (() -> Unit)? = null
+  var onDiagnosticLayout: ((String, RecyclerView.State) -> Unit)? = null
+
+  override fun onLayoutChildren(recycler: RecyclerView.Recycler, state: RecyclerView.State) {
+    onDiagnosticLayout?.invoke("layout-children-before", state)
+    if (!state.isPreLayout) onBeforeDataLayout?.invoke()
+    super.onLayoutChildren(recycler, state)
+    onDiagnosticLayout?.invoke("layout-children-after", state)
+  }
 
   // Scroll fills and layout passes both place children here, including rows that a
   // positional jump lays out and immediately leaves offscreen.
@@ -70,6 +80,7 @@ private class NativeListGridLayoutManager(
 
   override fun onLayoutCompleted(state: RecyclerView.State) {
     super.onLayoutCompleted(state)
+    onDiagnosticLayout?.invoke("layout-completed", state)
     onLayoutPassCompleted?.invoke()
   }
 
@@ -192,6 +203,46 @@ class NativeListView(
   private val footerSlotAdapter = NativeListContainerSlotAdapter()
   private val scrollContentAdapter = ConcatAdapter(headerSlotAdapter, adapter, emptySlotAdapter, footerSlotAdapter)
 
+  private val homeOffsetDiagnosticEnabled =
+    context.applicationInfo.flags and android.content.pm.ApplicationInfo.FLAG_DEBUGGABLE != 0
+  private var homeOffsetDiagnosticSequence = 0L
+
+  private fun homeOffsetDiagnostic(phase: String, state: RecyclerView.State? = null) {
+    if (!homeOffsetDiagnosticEnabled) return
+    try {
+      val first = layoutManager.findFirstVisibleItemPosition()
+      val firstView = layoutManager.findViewByPosition(first)
+      val holder = firstView?.let { recyclerView.getChildViewHolder(it) }
+      val lastView = layoutManager.findViewByPosition(layoutManager.findLastVisibleItemPosition())
+      val lastHolder = lastView?.let { recyclerView.getChildViewHolder(it) }
+      fun adapterOrdinal(value: RecyclerView.Adapter<*>?): Int = when (value) {
+        headerSlotAdapter -> 0
+        adapter -> 1
+        emptySlotAdapter -> 2
+        footerSlotAdapter -> 3
+        else -> -1
+      }
+      val focused = recyclerView.findFocus()
+      val focusChild = focused?.let { recyclerView.findContainingItemView(it) }
+      val focusHolder = focusChild?.let { recyclerView.getChildViewHolder(it) }
+      OneKeyLog.debug("NativeList", "[HOME-OFFSET-DIAG] listPhase=$phase " +
+        "seq=${++homeOffsetDiagnosticSequence} wallMs=${System.currentTimeMillis()} monoMs=${SystemClock.uptimeMillis()} " +
+        "list=${System.identityHashCode(this)} view=${System.identityHashCode(recyclerView)} tag=$id " +
+        "generation=${config?.generation} configuredCount=${config?.items?.size} " +
+        "counts=${headerSlotAdapter.itemCount},${adapter.itemCount},${emptySlotAdapter.itemCount},${footerSlotAdapter.itemCount} " +
+        "total=${scrollContentAdapter.itemCount} pendingCommand=${pendingScrollRequest?.javaClass?.simpleName ?: "none"} " +
+        "stateCount=${state?.itemCount} preLayout=${state?.isPreLayout} structureChanged=${state?.didStructureChange()} predictive=${state?.willRunPredictiveAnimations()} " +
+        "first=$first last=${layoutManager.findLastVisibleItemPosition()} " +
+        "adapterOrdinal=${adapterOrdinal(holder?.bindingAdapter)} layout=${holder?.layoutPosition} absolute=${holder?.absoluteAdapterPosition} binding=${holder?.bindingAdapterPosition} lastAdapterOrdinal=${adapterOrdinal(lastHolder?.bindingAdapter)} lastLayout=${lastHolder?.layoutPosition} lastAbsolute=${lastHolder?.absoluteAdapterPosition} lastBinding=${lastHolder?.bindingAdapterPosition} " +
+        "anchorTop=${firstView?.let(layoutManager::getDecoratedTop)} paddingTop=${recyclerView.paddingTop} " +
+        "childHeight=${firstView?.height} height=${recyclerView.height} range=${recyclerView.computeVerticalScrollRange()} extent=${recyclerView.computeVerticalScrollExtent()} " +
+        "canUp=${recyclerView.canScrollVertically(-1)} canDown=${recyclerView.canScrollVertically(1)} " +
+        "focusClass=${focused?.javaClass?.simpleName ?: "none"} focusId=${focused?.id} focusAdapterOrdinal=${adapterOrdinal(focusHolder?.bindingAdapter)} focusLayout=${focusHolder?.layoutPosition} focusPosition=${focusHolder?.absoluteAdapterPosition} focusBinding=${focusHolder?.bindingAdapterPosition}")
+    } catch (_: Exception) {
+      // Diagnostic reads must not affect layout or command delivery.
+    }
+  }
+
   fun mountContainerSlot(view: View, index: Int) {
     containerSlots.add(index.coerceIn(0, containerSlots.size), view)
     updateContainerSlots()
@@ -243,9 +294,11 @@ class NativeListView(
   }
 
   private fun updateContainerSlots() {
+    homeOffsetDiagnostic("slots-before")
     headerSlotAdapter.update(containerSlots.getOrNull(0), slotHeights[0], true)
     emptySlotAdapter.update(containerSlots.getOrNull(1), slotHeights[1], config?.items?.isEmpty() != false)
     footerSlotAdapter.update(containerSlots.getOrNull(2), slotHeights[2], true)
+    homeOffsetDiagnostic("slots-after")
     layoutManager.spanSizeLookup.invalidateSpanIndexCache()
     recyclerView.requestLayout()
   }
@@ -456,6 +509,7 @@ class NativeListView(
   }
   private val stickyPreDraw = android.view.ViewTreeObserver.OnPreDrawListener {
     updateStickyHeader()
+    finishScrollCommandIfSettled()
     true
   }
   // Registered only while attached, on the captured window observer, so detach
@@ -493,6 +547,14 @@ class NativeListView(
     true
   }
   private var pendingScrollRequest: ScrollRequest? = null
+  private var acceptedScrollRequest: ScrollRequest? = null
+  private var executingScrollCommand = false
+  private var dispatchingScrollRequest: ScrollRequest? = null
+  private var commandLayoutRequest: ScrollRequest? = null
+  private var commandAlignmentRequest: ScrollRequest? = null
+  private var commandFinishDiagnosticReason: String? = null
+  private var readingIntentEpoch = 0L
+  private var pendingBodyStartEpoch: Long? = null
   private val actionAnchorInstanceId = UUID.randomUUID().toString()
   private var actionAnchorCounter = 0L
   private var actionAnchor: ActionAnchorRecord? = null
@@ -514,10 +576,20 @@ class NativeListView(
     // OneKey patch: full-width selector header backgrounds do not change row content insets.
     recyclerView.addItemDecoration(SelectorBackgroundDecoration(adapter))
     recyclerView.addItemDecoration(ContainerSlotInsetDecoration { slotInsetPx })
+    if (homeOffsetDiagnosticEnabled) layoutManager.onDiagnosticLayout = ::homeOffsetDiagnostic
+    layoutManager.onBeforeDataLayout = {
+      if (pendingBodyStartEpoch == readingIntentEpoch && adapter.itemCount > 0 && pendingScrollRequest == null) {
+        layoutManager.scrollToPositionWithOffset(0, 0)
+        pendingBodyStartEpoch = null
+        homeOffsetDiagnostic("first-fill-body-start")
+      }
+    }
     layoutManager.onChildLaidOut = ::recordLaidOutRowExtent
     layoutManager.onLayoutPassCompleted = {
       emitScrollPositionThresholdIfNeeded(resync = true)
       if (containerSlotRelayoutPending) scheduleContainerSlotRelayout()
+      if (commandLayoutRequest === acceptedScrollRequest) commandLayoutRequest = null
+      finishScrollCommandIfSettled()
     }
     recyclerView.setHasFixedSize(false)
     layoutManager.spanSizeLookup = object : GridLayoutManager.SpanSizeLookup() {
@@ -607,6 +679,11 @@ class NativeListView(
 
     recyclerView.addOnScrollListener(object : RecyclerView.OnScrollListener() {
       override fun onScrollStateChanged(recyclerView: RecyclerView, newState: Int) {
+        if (newState == RecyclerView.SCROLL_STATE_DRAGGING) {
+          cancelExecutingScrollCommand()
+          readingIntentEpoch++
+          pendingBodyStartEpoch = null
+        }
         when (newState) {
           RecyclerView.SCROLL_STATE_DRAGGING -> {
             sectionIndexProgrammaticScroll = false
@@ -618,7 +695,10 @@ class NativeListView(
               dismissKeyboard()
             }
           }
-          RecyclerView.SCROLL_STATE_IDLE -> sectionIndexProgrammaticScroll = false
+          RecyclerView.SCROLL_STATE_IDLE -> {
+            sectionIndexProgrammaticScroll = false
+            finishScrollCommandIfSettled()
+          }
         }
       }
 
@@ -709,6 +789,8 @@ class NativeListView(
     super.onAttachedToWindow()
     if (containerSlotRelayoutPending) scheduleContainerSlotRelayout()
     recyclerView.setTag(R.id.onekey_native_scroll_coordinator_offset_listener, coordinatorOffsetListener)
+    val cancelTag = R.id.onekey_native_scroll_coordinator_command_cancel_listener
+    if (recyclerView.getTag(cancelTag) == null) recyclerView.setTag(cancelTag, coordinatorCommandCancelListener)
     emitScrollPositionThresholdIfNeeded()
     startStickyHeaderTracking()
     updateSectionIndexAttachment()
@@ -719,6 +801,9 @@ class NativeListView(
   }
 
   override fun onDetachedFromWindow() {
+    val cancelTag = R.id.onekey_native_scroll_coordinator_command_cancel_listener
+    if (recyclerView.getTag(cancelTag) === coordinatorCommandCancelListener) recyclerView.setTag(cancelTag, null)
+    cancelExecutingScrollCommand()
     if (recyclerView.getTag(R.id.onekey_native_scroll_coordinator_offset_listener) === coordinatorOffsetListener) {
       recyclerView.setTag(R.id.onekey_native_scroll_coordinator_offset_listener, null)
     }
@@ -736,8 +821,17 @@ class NativeListView(
     } catch (_: Exception) {
       return
     }
+    homeOffsetDiagnostic("snapshot-before-nextCount=${next.items.size}")
     invalidateActionAnchor("snapshot")
     val previous = config
+    if (previous?.items?.isEmpty() == true && next.items.isNotEmpty() && adapter.itemCount == 0 &&
+      pendingScrollRequest == null && recyclerView.scrollState != RecyclerView.SCROLL_STATE_DRAGGING &&
+      !recyclerView.canScrollVertically(-1) && layoutManager.findFirstVisibleItemPosition() == 0) {
+      val first = layoutManager.findViewByPosition(0)
+      if (first != null && kotlin.math.abs(layoutManager.getDecoratedTop(first) - recyclerView.paddingTop) <= 1) {
+        pendingBodyStartEpoch = readingIntentEpoch
+      }
+    }
     if (previous != null && canApplyStableContentUpdate(previous, next)) {
       // OneKey patch: authorize a diff payload only against this exact validated baseline.
       next.items.forEachIndexed { index, item ->
@@ -765,6 +859,7 @@ class NativeListView(
       // outside the adapter, so a listStyle-only snapshot must rebind it here.
       if (previous.listStyle?.toString() != next.listStyle?.toString()) bindFooter(next)
       adapter.submitList(next.items) {
+        homeOffsetDiagnostic("snapshot-stable-submit-commit")
         // OneKey patch: DiffUtil has dispatched its payloads; release the old serialized rows.
         next.items.forEach { it.selectionUpdateFromContent = null }
         recyclerView.post {
@@ -805,6 +900,7 @@ class NativeListView(
     configureSectionIndex(next)
     updateLayout(next)
     adapter.submitList(next.items) {
+      homeOffsetDiagnostic("snapshot-submit-commit-marketAnchor=${marketStartOffset != null}")
       if (marketStartOffset != null) {
         layoutManager.scrollToPositionWithOffset(scrollPositionForRow(0), marketStartOffset)
       }
@@ -1089,9 +1185,90 @@ class NativeListView(
     requestScroll(ScrollRequest.End(animated))
   }
 
+  private fun acceptScrollRequest(request: ScrollRequest) {
+    if (acceptedScrollRequest === request) return
+    val current = config ?: return
+    val valid = when (request) {
+      is ScrollRequest.Key -> current.items.any { it.key == request.key } && request.viewPosition.isFinite() && request.viewOffset.isFinite()
+      is ScrollRequest.Index -> request.index in current.items.indices && request.viewPosition.isFinite() && request.viewOffset.isFinite()
+      is ScrollRequest.Offset -> request.offset.isFinite()
+      is ScrollRequest.End -> true
+    }
+    if (!valid) return
+    executingScrollCommand = false
+    dispatchingScrollRequest = null
+    commandLayoutRequest = null
+    commandAlignmentRequest = null
+    acceptedScrollRequest = request
+    commandFinishDiagnosticReason = null
+    readingIntentEpoch++
+    pendingBodyStartEpoch = null
+    val explicitTop = when (request) {
+      is ScrollRequest.Offset -> request.offset <= 0
+      is ScrollRequest.Index -> request.index == 0 && request.alignment == "start" && request.viewOffset == 0.0 && request.viewPosition == 0.0
+      is ScrollRequest.Key -> current.items.firstOrNull()?.key == request.key && request.alignment == "start" && request.viewOffset == 0.0 && request.viewPosition == 0.0
+      is ScrollRequest.End -> false
+    }
+    notifyScrollCommand(explicitTop, 0)
+  }
+
+  private fun notifyScrollCommand(explicitTop: Boolean, phase: Int) {
+    @Suppress("UNCHECKED_CAST")
+    val listeners = recyclerView.getTag(R.id.onekey_native_scroll_coordinator_command_listener) as? Map<Any, BiConsumer<Boolean, Int>>
+    listeners?.values?.toList()?.forEach { it.accept(explicitTop, phase) }
+  }
+
+  private val coordinatorCommandCancelListener = Runnable {
+    if (disposed) return@Runnable
+    pendingScrollRequest = null
+    readingIntentEpoch++
+    pendingBodyStartEpoch = null
+    cancelExecutingScrollCommand()
+    recyclerView.stopScroll()
+  }
+
+  private fun cancelExecutingScrollCommand() {
+    val request = acceptedScrollRequest
+    val wasExecuting = executingScrollCommand
+    executingScrollCommand = false
+    acceptedScrollRequest = null
+    dispatchingScrollRequest = null
+    commandLayoutRequest = null
+    commandAlignmentRequest = null
+    if (request != null && pendingScrollRequest === request) pendingScrollRequest = null
+    if (wasExecuting) notifyScrollCommand(false, 2)
+  }
+
+  private fun finishScrollCommandIfSettled() {
+    val request = acceptedScrollRequest ?: return
+    if (homeOffsetDiagnosticEnabled && executingScrollCommand) {
+      val reason = "pendingOwn=${pendingScrollRequest === request}-dispatchOwn=${dispatchingScrollRequest === request}" +
+        "-layoutOwn=${commandLayoutRequest === request}-alignOwn=${commandAlignmentRequest === request}" +
+        "-computing=${recyclerView.isComputingLayout}-scrollState=${recyclerView.scrollState}-smooth=${layoutManager.isSmoothScrolling}"
+      if (commandFinishDiagnosticReason != reason) {
+        commandFinishDiagnosticReason = reason
+        homeOffsetDiagnostic("command-finish-gates-$reason")
+      }
+    }
+    if (
+      !executingScrollCommand || pendingScrollRequest === request ||
+      dispatchingScrollRequest === request || commandLayoutRequest === request ||
+      commandAlignmentRequest === request || recyclerView.isComputingLayout ||
+      recyclerView.scrollState != RecyclerView.SCROLL_STATE_IDLE || layoutManager.isSmoothScrolling
+    ) return
+    executingScrollCommand = false
+    commandLayoutRequest = null
+    commandAlignmentRequest = null
+    notifyScrollCommand(false, 2)
+  }
+
   private fun requestScroll(request: ScrollRequest) {
+    acceptScrollRequest(request)
+    if (config != null && acceptedScrollRequest !== request) return
+    homeOffsetDiagnostic("command-request-kind=${request.javaClass.simpleName}")
     if (performScroll(request)) {
       pendingScrollRequest = null
+      finishScrollCommandIfSettled()
     } else {
       pendingScrollRequest = request
     }
@@ -1099,84 +1276,109 @@ class NativeListView(
 
   private fun performPendingScrollIfNeeded() {
     val request = pendingScrollRequest ?: return
-    if (performScroll(request)) pendingScrollRequest = null
+    acceptScrollRequest(request)
+    if (config != null && acceptedScrollRequest !== request) {
+      if (pendingScrollRequest === request) pendingScrollRequest = null
+      return
+    }
+    homeOffsetDiagnostic("command-pending-kind=${request.javaClass.simpleName}")
+    if (performScroll(request)) {
+      pendingScrollRequest = null
+      finishScrollCommandIfSettled()
+    }
   }
 
   private fun performScroll(request: ScrollRequest): Boolean {
+    homeOffsetDiagnostic("command-perform-kind=${request.javaClass.simpleName}")
     val current = config ?: return false
     if (adapter.itemCount != current.items.size) return false
     if (recyclerView.width <= 0 || recyclerView.height <= 0) return false
-    return when (request) {
-      is ScrollRequest.Key -> {
-        val index = current.items.indexOfFirst { it.key == request.key }
-        if (index >= 0) {
-          performIndexScroll(
-            index,
-            request.animated,
-            request.alignment,
-            request.viewPosition,
-            request.viewOffset,
-          )
+    if (acceptedScrollRequest === request) {
+      dispatchingScrollRequest = request
+      executingScrollCommand = true
+      notifyScrollCommand(false, 1)
+    }
+    try {
+      return when (request) {
+        is ScrollRequest.Key -> {
+          val index = current.items.indexOfFirst { it.key == request.key }
+          if (index >= 0) {
+            performIndexScroll(
+              request,
+              index,
+              request.animated,
+              request.alignment,
+              request.viewPosition,
+              request.viewOffset,
+            )
+          }
+          true
         }
-        true
-      }
-      is ScrollRequest.Index -> {
-        if (request.index in current.items.indices) {
-          performIndexScroll(
-            request.index,
-            request.animated,
-            request.alignment,
-            request.viewPosition,
-            request.viewOffset,
-          )
+        is ScrollRequest.Index -> {
+          if (request.index in current.items.indices) {
+            performIndexScroll(
+              request,
+              request.index,
+              request.animated,
+              request.alignment,
+              request.viewPosition,
+              request.viewOffset,
+            )
+          }
+          true
         }
-        true
-      }
-      is ScrollRequest.Offset -> {
-        performOffsetScroll(request.offset, request.animated)
-        true
-      }
-      is ScrollRequest.End -> {
-        val finalSlotHeight = when {
-          footerSlotAdapter.itemCount > 0 -> slotHeights[2]
-          emptySlotAdapter.itemCount > 0 -> slotHeights[1]
-          adapter.itemCount == 0 && headerSlotAdapter.itemCount > 0 -> slotHeights[0]
-          else -> null
+        is ScrollRequest.Offset -> {
+          performOffsetScroll(request, request.offset, request.animated)
+          true
         }
-        if (finalSlotHeight != null) {
-          val target = scrollContentAdapter.itemCount - 1
-          if (request.animated) {
-            val manager = layoutManager
-            val scroller = object : LinearSmoothScroller(context) {
-              override fun calculateDyToMakeVisible(view: View, snapPreference: Int): Int =
-                nativeListEndAlignmentOffset(
-                  manager.height - manager.paddingBottom,
-                  manager.getDecoratedBottom(view),
-                )
+        is ScrollRequest.End -> {
+          val finalSlotHeight = when {
+            footerSlotAdapter.itemCount > 0 -> slotHeights[2]
+            emptySlotAdapter.itemCount > 0 -> slotHeights[1]
+            adapter.itemCount == 0 && headerSlotAdapter.itemCount > 0 -> slotHeights[0]
+            else -> null
+          }
+          if (finalSlotHeight != null) {
+            val target = scrollContentAdapter.itemCount - 1
+            if (request.animated) {
+              val manager = layoutManager
+              val scroller = object : LinearSmoothScroller(context) {
+                override fun calculateDyToMakeVisible(view: View, snapPreference: Int): Int =
+                  nativeListEndAlignmentOffset(
+                    manager.height - manager.paddingBottom,
+                    manager.getDecoratedBottom(view),
+                  )
+              }
+              scroller.targetPosition = target
+              layoutManager.startSmoothScroll(scroller)
+            } else {
+              if (acceptedScrollRequest === request) commandLayoutRequest = request
+              layoutManager.scrollToPositionWithOffset(
+                target,
+                nativeListEndAlignmentOffset(viewportLength(layoutManager), finalSlotHeight),
+              )
+              relayoutRecyclerView()
             }
-            scroller.targetPosition = target
-            layoutManager.startSmoothScroll(scroller)
-          } else {
-            layoutManager.scrollToPositionWithOffset(
-              target,
-              nativeListEndAlignmentOffset(viewportLength(layoutManager), finalSlotHeight),
+          } else if (current.items.isNotEmpty()) {
+            performIndexScroll(
+              request,
+              current.items.lastIndex,
+              request.animated,
+              "end",
+              1.0,
+              0.0,
             )
           }
-        } else if (current.items.isNotEmpty()) {
-          performIndexScroll(
-            current.items.lastIndex,
-            request.animated,
-            "end",
-            1.0,
-            0.0,
-          )
+          true
         }
-        true
       }
+    } finally {
+      if (dispatchingScrollRequest === request) dispatchingScrollRequest = null
     }
   }
 
   private fun performIndexScroll(
+    request: ScrollRequest,
     index: Int,
     animated: Boolean,
     alignment: String,
@@ -1241,12 +1443,16 @@ class NativeListView(
     val layoutOffset = nativeListProvisionalStart(
       viewportLength(manager), viewPosition, offsetPx, nearest,
     )
+    if (acceptedScrollRequest === request) {
+      commandLayoutRequest = request
+      commandAlignmentRequest = request
+    }
     manager.scrollToPositionWithOffset(scrollPositionForRow(index), layoutOffset)
     relayoutRecyclerView()
-    alignAfterLayout(index, viewPosition, offsetPx, nearest)
+    alignAfterLayout(request, index, viewPosition, offsetPx, nearest)
   }
 
-  private fun performOffsetScroll(offset: Double, animated: Boolean) {
+  private fun performOffsetScroll(request: ScrollRequest, offset: Double, animated: Boolean) {
     val manager = recyclerView.layoutManager as? LinearLayoutManager ?: return
     val target = (offset * density).roundToInt().coerceAtLeast(0)
     if (!animated) {
@@ -1254,11 +1460,24 @@ class NativeListView(
     }
     if (!animated) {
       recyclerView.stopScroll()
+      if (acceptedScrollRequest === request) commandLayoutRequest = request
       manager.scrollToPositionWithOffset(0, -target)
       relayoutRecyclerView()
       return
     }
     if (target == 0) {
+      val startView = manager.findViewByPosition(0)
+      val paddingStart = if (manager.orientation == RecyclerView.VERTICAL) manager.paddingTop else manager.paddingLeft
+      val relativeStart = startView?.let { decoratedStart(manager, it) - paddingStart }
+      homeOffsetDiagnostic("command-top-dispatch-first=${manager.findFirstVisibleItemPosition()}-relativeStart=$relativeStart-smooth=${manager.isSmoothScrolling}")
+      if (
+        startView != null && manager.findFirstVisibleItemPosition() == 0 && relativeStart == 0 &&
+        recyclerView.scrollState == RecyclerView.SCROLL_STATE_IDLE &&
+        !recyclerView.isComputingLayout && !manager.isSmoothScrolling
+      ) {
+        homeOffsetDiagnostic("command-top-noop")
+        return
+      }
       recyclerView.smoothScrollToPosition(0)
       return
     }
@@ -1276,6 +1495,7 @@ class NativeListView(
   }
 
   private fun alignAfterLayout(
+    request: ScrollRequest,
     index: Int,
     viewPosition: Double,
     viewOffset: Int,
@@ -1283,15 +1503,26 @@ class NativeListView(
     attemptsRemaining: Int = 2,
   ) {
     recyclerView.post {
-      val manager = recyclerView.layoutManager as? LinearLayoutManager ?: return@post
-      val view = manager.findViewByPosition(scrollPositionForRow(index))
-      if (view == null) {
+      if (acceptedScrollRequest !== request || !executingScrollCommand || disposed || !isAttachedToWindow) return@post
+      val manager = recyclerView.layoutManager as? LinearLayoutManager
+      val view = manager?.findViewByPosition(scrollPositionForRow(index))
+      if (view == null || recyclerView.isComputingLayout) {
         if (attemptsRemaining > 0) {
-          alignAfterLayout(index, viewPosition, viewOffset, nearest, attemptsRemaining - 1)
+          alignAfterLayout(request, index, viewPosition, viewOffset, nearest, attemptsRemaining - 1)
+          return@post
         }
-        return@post
+      } else if (manager != null) {
+        dispatchingScrollRequest = request
+        try {
+          alignVisibleView(manager, view, viewPosition, viewOffset, false, nearest)
+        } finally {
+          if (dispatchingScrollRequest === request) dispatchingScrollRequest = null
+        }
+      }
+      if (acceptedScrollRequest === request && commandAlignmentRequest === request) {
+        commandAlignmentRequest = null
+        finishScrollCommandIfSettled()
       }
-      alignVisibleView(manager, view, viewPosition, viewOffset, false, nearest)
     }
   }
 
@@ -1397,6 +1628,8 @@ class NativeListView(
   fun dispose() {
     if (disposed) return
     disposed = true
+    val cancelTag = R.id.onekey_native_scroll_coordinator_command_cancel_listener
+    if (recyclerView.getTag(cancelTag) === coordinatorCommandCancelListener) recyclerView.setTag(cancelTag, null)
     containerSlotRelayoutPending = false
     onScrollPositionThresholdChange = null
     if (!isAttachedToWindow) disposeResources()
@@ -1414,6 +1647,14 @@ class NativeListView(
     visibleEventScheduled = false
     layoutManager.onChildLaidOut = null
     layoutManager.onLayoutPassCompleted = null
+    layoutManager.onDiagnosticLayout = null
+    layoutManager.onBeforeDataLayout = null
+    pendingBodyStartEpoch = null
+    executingScrollCommand = false
+    acceptedScrollRequest = null
+    dispatchingScrollRequest = null
+    commandLayoutRequest = null
+    commandAlignmentRequest = null
     measuredRowExtentsPx.clear()
     measuredRowExtentSumPx = 0L
     reorderTouchHandler?.removeCallbacksAndMessages(null)

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

@@ -2,4 +2,6 @@
     <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" />
+    <item name="onekey_native_scroll_coordinator_command_listener" type="id" />
+    <item name="onekey_native_scroll_coordinator_command_cancel_listener" type="id" />
 </resources>

package/docs/SPEC.md

@@ -70,6 +70,53 @@ Acceptance requires loading → idle → loading reuse, title color updates and
 detachment on each native platform. A title's localized confirming text remains
 caller-owned; the renderer does not infer transaction status.
 
+
+### First-fill position and imperative command ownership
+
+Status: implemented in source and verified in the consuming app's local native
+builds; acceptance of the newly published package remains pending.
+
+On Android, empty-to-populated data MUST preserve the actual body-start anchor
+through the first committed layout. This applies only when the old body was
+empty and the view was actually at its start; it MUST NOT reset a non-empty
+refresh, pagination, deep reading position, or a newer accepted command.
+Continuous snapshots retain this intent until the first populated layout.
+A real drag or valid command invalidates the intent. Container-slot positions
+and scrollbar estimates MUST NOT be mistaken for data-row reading anchors.
+
+An accepted imperative command owns its request, execution, pending-layout and
+posted-alignment work. Invalid commands MUST NOT cancel a valid request.
+On iOS, known-configuration validation MUST precede changing accepted, pending
+or animated-command state; invalid input MUST preserve the existing terminal
+notification, while configuration-unavailable requests retain deferred validation.
+Completion on Android requires the current request to have finished dispatch,
+its own pending layout/alignment barriers to have completed, and native scrolling
+to be idle without an active layout-manager animation. A true animated top
+no-op completes without starting redundant native motion. Non-animated key and
+end alignment complete after their requested layout/alignment, not beforehand.
+An unrelated layout request MUST NOT indefinitely postpone command completion.
+Replacement, actual drag, detach and disposal invalidate old callbacks; a stale
+callback MUST NOT move the view or clear a newer command's barriers.
+
+A valid command can privately notify the owning Pager before execution, including
+a same-position no-op; this does not add a public NativeList API. A Pager-owned
+page-top or sticky-top command can privately cancel only its owned list's old
+pending command and native animation before acquiring its own target. On iOS
+the notification identifies the collection view; on Android the listener belongs
+to the actual owned RecyclerView. No notification may take over another owner.
+
+On Web, the owned viewport's private cancellation event clears pending list
+commands and stops old browser smooth motion. A newly accepted valid list
+command invalidates a queued Pager target; invalid commands do not. Destroy
+removes the exact listeners and clears pending work. Other list viewports and
+rendering work remain independent.
+
+Conformance: NativeListView.kt, RNCNativeListView.swift, NativeListWebEngine.ts,
+and the related Pager owner coordination. Runtime acceptance must exercise
+first populated layout, command replacement, animated/non-animated completion,
+true top no-op, and short pending content followed by usable geometry on the
+actual installed package; source or helper-only checks are not runtime evidence.
+
 ## Data, cache and identity
 
 `row.key` identifies data; renderer reuse identity describes compatible view

package/ios/RNCNativeListView.swift

@@ -167,6 +167,10 @@ final class NativeListView: UIView {
   private var sectionIndexHapticsEnabled = true
   private var lastLayoutDirection: UIUserInterfaceLayoutDirection?
   private var lastLayoutSize: CGSize?
+  private var commandAcceptedForPendingScroll = false
+  private var performingExplicitScrollCommand = false
+  private var animatedExplicitScrollCommand = false
+  private var pagerCommandCancelObserver: NSObjectProtocol?
   private var pendingScrollRequest: ScrollRequest?
   private let sectionIndexFeedback = UISelectionFeedbackGenerator()
   private lazy var reorderLongPress = UILongPressGestureRecognizer(
@@ -217,6 +221,17 @@ final class NativeListView: UIView {
 
   override init(frame: CGRect) {
     super.init(frame: frame)
+    pagerCommandCancelObserver = NotificationCenter.default.addObserver(
+      forName: Notification.Name("OneKeyNativeListCancelScrollCommand"),
+      object: collectionView, queue: .main
+    ) { [weak self] notification in
+      guard let self, !self.disposed, (notification.object as? UICollectionView) === self.collectionView else { return }
+      self.pendingScrollRequest = nil
+      self.commandAcceptedForPendingScroll = false
+      self.scrollViewDidEndScrollingAnimation(self.collectionView)
+      self.performingExplicitScrollCommand = false
+      self.collectionView.setContentOffset(self.collectionView.contentOffset, animated: false)
+    }
     NativeListRendererRegistry.register(in: collectionView)
     collectionView.backgroundColor = .clear
     collectionView.delegate = self
@@ -392,6 +407,10 @@ final class NativeListView: UIView {
     return item.isRowPressEnabled
   }
 
+  deinit {
+    if let pagerCommandCancelObserver { NotificationCenter.default.removeObserver(pagerCommandCancelObserver) }
+  }
+
   required init?(coder: NSCoder) {
     fatalError("init(coder:) has not been implemented")
   }
@@ -638,7 +657,38 @@ final class NativeListView: UIView {
     requestScroll(.end(animated))
   }
 
+  private func explicitTopForScrollCommand(_ request: ScrollRequest) -> Bool? {
+    guard let config else { return nil }
+    let explicitTop: Bool
+    switch request {
+    case let .key(key, _, alignment, viewPosition, viewOffset):
+      guard config.items.contains(where: { $0.key == key }), viewPosition.isFinite, viewOffset.isFinite else { return nil }
+      explicitTop = config.items.first?.key == key && alignment == "start" && viewPosition == 0 && viewOffset == 0
+    case let .index(index, _, alignment, viewPosition, viewOffset):
+      guard index >= 0, index < config.items.count, viewPosition.isFinite, viewOffset.isFinite else { return nil }
+      explicitTop = index == 0 && alignment == "start" && viewPosition == 0 && viewOffset == 0
+    case let .offset(offset, _):
+      guard offset.isFinite else { return nil }
+      explicitTop = offset <= 0
+    case .end:
+      explicitTop = false
+    }
+    return explicitTop
+  }
+
+  private func acceptScrollCommand(_ request: ScrollRequest) {
+    guard !commandAcceptedForPendingScroll,
+          let explicitTop = explicitTopForScrollCommand(request) else { return }
+    commandAcceptedForPendingScroll = true
+    NotificationCenter.default.post(name: Notification.Name("OneKeyNativeListScrollCommandAccepted"),
+      object: collectionView, userInfo: ["explicitTop": explicitTop, "phase": 0])
+  }
+
   private func requestScroll(_ request: ScrollRequest) {
+    if config != nil && explicitTopForScrollCommand(request) == nil { return }
+    animatedExplicitScrollCommand = false
+    commandAcceptedForPendingScroll = false
+    acceptScrollCommand(request)
     if performScroll(request) {
       pendingScrollRequest = nil
     } else {
@@ -647,7 +697,9 @@ final class NativeListView: UIView {
   }
 
   private func performPendingScrollIfNeeded() {
-    guard let request = pendingScrollRequest, performScroll(request) else { return }
+    guard let request = pendingScrollRequest else { return }
+    acceptScrollCommand(request)
+    guard performScroll(request) else { return }
     pendingScrollRequest = nil
   }
 
@@ -660,6 +712,8 @@ final class NativeListView: UIView {
       : collectionView.bounds.height
     guard viewportLength > 0 else { return false }
     collectionView.layoutIfNeeded()
+    performingExplicitScrollCommand = commandAcceptedForPendingScroll
+    defer { performingExplicitScrollCommand = false }
 
     switch request {
     case let .key(key, animated, alignment, viewPosition, viewOffset):
@@ -764,7 +818,17 @@ final class NativeListView: UIView {
     let point = isHorizontal
       ? CGPoint(x: offset, y: collectionView.contentOffset.y)
       : CGPoint(x: collectionView.contentOffset.x, y: offset)
+    let moved = point != collectionView.contentOffset
+    if performingExplicitScrollCommand && moved {
+      NotificationCenter.default.post(name: Notification.Name("OneKeyNativeListScrollCommandAccepted"),
+        object: collectionView, userInfo: ["phase": 1])
+    }
+    if performingExplicitScrollCommand && moved { animatedExplicitScrollCommand = animated }
     collectionView.setContentOffset(point, animated: animated)
+    if performingExplicitScrollCommand && moved && !animated {
+      NotificationCenter.default.post(name: Notification.Name("OneKeyNativeListScrollCommandAccepted"),
+        object: collectionView, userInfo: ["phase": 2])
+    }
   }
 
   private func contentLayoutDidChange() {
@@ -1981,7 +2045,14 @@ final class NativeListView: UIView {
     config = nil
     itemsByKey.removeAll()
     sectionIndexEntries.removeAll()
+    if let pagerCommandCancelObserver {
+      NotificationCenter.default.removeObserver(pagerCommandCancelObserver)
+      self.pagerCommandCancelObserver = nil
+    }
     pendingScrollRequest = nil
+    performingExplicitScrollCommand = false
+    animatedExplicitScrollCommand = false
+    commandAcceptedForPendingScroll = false
     needsContentShrinkCorrection = false
     lastLaidOutContentHeight = nil
     lastVisibleRange = nil
@@ -2281,7 +2352,15 @@ extension NativeListView: UICollectionViewDelegateFlowLayout {
     return item.isRowPressEnabled
   }
 
+  func scrollViewDidEndScrollingAnimation(_ scrollView: UIScrollView) {
+    guard animatedExplicitScrollCommand else { return }
+    animatedExplicitScrollCommand = false
+    NotificationCenter.default.post(name: Notification.Name("OneKeyNativeListScrollCommandAccepted"),
+      object: collectionView, userInfo: ["phase": 2])
+  }
+
   func scrollViewWillBeginDragging(_ scrollView: UIScrollView) {
+    scrollViewDidEndScrollingAnimation(scrollView)
     minimumDragOffset = 0
     refreshEmittedForDrag = false
   }

package/ios/tests/NativeListLifecycleTests.swift

@@ -4,6 +4,63 @@ import XCTest
 
 @MainActor
 final class NativeListLifecycleTests: XCTestCase {
+  func testInvalidCommandsPreserveAcceptedAnimationCompletion() throws {
+    for invalid in 0..<3 {
+      let view = try makeScrollingList()
+      let window = UIWindow(frame: view.frame)
+      let controller = UIViewController()
+      window.rootViewController = controller
+      controller.view.addSubview(view)
+      window.isHidden = false
+      defer { window.isHidden = true }
+      window.layoutIfNeeded()
+      view.layoutIfNeeded()
+      drainMainQueue()
+      let list = try XCTUnwrap(view.subviews.compactMap { $0 as? UICollectionView }.first)
+      XCTAssertNotNil(view.window)
+      XCTAssertGreaterThan(list.contentSize.height - list.bounds.height +
+        list.adjustedContentInset.top + list.adjustedContentInset.bottom, 800)
+      let phases = NSMutableArray()
+      let observer = NotificationCenter.default.addObserver(
+        forName: Notification.Name("OneKeyNativeListScrollCommandAccepted"),
+        object: list, queue: nil
+      ) { notification in
+        if let phase = notification.userInfo?["phase"] as? Int { phases.add(phase) }
+      }
+      defer { NotificationCenter.default.removeObserver(observer) }
+      view.scrollToOffset(800, animated: true)
+      XCTAssertEqual(phases as? [Int], [0, 1])
+      switch invalid {
+      case 0: view.scrollToKey("missing-fixture-key", animated: true, alignment: "start")
+      case 1: view.scrollToIndex(-1, animated: true, alignment: "start")
+      default: view.scrollToOffset(.nan, animated: true)
+      }
+      XCTAssertEqual(phases as? [Int], [0, 1], "Invalid input must not accept or end another command")
+      // Exercise the actual delegate terminal callback, not a copied state helper.
+      view.scrollViewDidEndScrollingAnimation(list)
+      XCTAssertEqual(phases as? [Int], [0, 1, 2])
+      view.scrollViewDidEndScrollingAnimation(list)
+      XCTAssertEqual(phases as? [Int], [0, 1, 2], "Completion is emitted once")
+    }
+  }
+
+  func testInvalidKeyPreservesValidPendingScrollUntilGeometryArrives() throws {
+    let view = try makeScrollingList()
+    let list = try XCTUnwrap(view.subviews.compactMap { $0 as? UICollectionView }.first)
+    view.frame.size.height = 0
+    view.setNeedsLayout()
+    view.layoutIfNeeded()
+    XCTAssertEqual(list.bounds.height, 0)
+    view.scrollToOffset(500, animated: false)
+    view.scrollToKey("missing-fixture-key", animated: true, alignment: "start")
+    view.frame.size.height = 708
+    view.setNeedsLayout()
+    view.layoutIfNeeded()
+    list.layoutIfNeeded()
+    drainMainQueue()
+    XCTAssertEqual(list.contentOffset.y, 500 - list.adjustedContentInset.top, accuracy: 0.5)
+  }
+
   func testSectionLoadingStopsOnRebindReuseAndDetach() throws {
     let window = UIWindow(frame: CGRect(x: 0, y: 0, width: 320, height: 480))
     let controller = UIViewController()

package/lib/module/web/NativeListWebEngine.js

@@ -1252,6 +1252,20 @@ export class NativeListWebEngine {
   sectionIndexAlignStart = false;
   // Renderers report intrinsic height after browser text wrapping.
   measuredRendererHeights = new Map();
+  notifyScrollCommandAccepted() {
+    if (this.destroyed) return;
+    const EventConstructor = this.viewport.ownerDocument.defaultView?.Event;
+    if (EventConstructor) this.viewport.dispatchEvent(new EventConstructor('ok-native-list-scroll-command-accepted'));
+  }
+  handlePagerScrollCommandCancel = event => {
+    if (this.destroyed || event.target !== this.viewport) return;
+    this.pendingScroll = undefined;
+    this.viewport.scrollTo({
+      left: this.viewport.scrollLeft,
+      top: this.viewport.scrollTop,
+      behavior: 'instant'
+    });
+  };
   constructor(host, snapshot, callbacks, virtualizationEnabled = true, sectionIndexContainer) {
     this.document = host.ownerDocument;
     this.snapshot = validateSnapshot(snapshot);
@@ -1285,6 +1299,7 @@ export class NativeListWebEngine {
     this.viewportFrame.append(this.viewport, this.sticky, this.indexRail, this.refreshIndicator);
     this.root.append(style, this.viewportFrame, this.footer);
     host.appendChild(this.root);
+    this.viewport.addEventListener('ok-collapsible-pager-cancel-scroll-command', this.handlePagerScrollCommandCancel);
     this.viewport.addEventListener('scroll', this.handleScroll, {
       passive: true
     });
@@ -1392,6 +1407,7 @@ export class NativeListWebEngine {
       this.emitScrollFailure(index, 'index-out-of-range');
       return;
     }
+    this.notifyScrollCommandAccepted();
     if (!this.canScroll()) {
       this.pendingScroll = {
         kind: 'index',
@@ -1430,6 +1446,7 @@ export class NativeListWebEngine {
   }
   scrollToOffset(offset, animated) {
     validateOffset(offset);
+    this.notifyScrollCommandAccepted();
     if (!this.canScroll()) {
       this.pendingScroll = {
         kind: 'offset',
@@ -1441,6 +1458,7 @@ export class NativeListWebEngine {
     this.scrollToAbsoluteOffset(offset, animated);
   }
   scrollToEnd(animated) {
+    this.notifyScrollCommandAccepted();
     if (!this.canScroll()) {
       this.pendingScroll = {
         kind: 'end',
@@ -1499,6 +1517,8 @@ export class NativeListWebEngine {
     this.resizeObserver?.disconnect();
     this.sectionIndexTransformObserver?.disconnect();
     this.document.defaultView?.removeEventListener('resize', this.handleWindowResize);
+    this.pendingScroll = undefined;
+    this.viewport.removeEventListener('ok-collapsible-pager-cancel-scroll-command', this.handlePagerScrollCommandCancel);
     this.viewport.removeEventListener('scroll', this.handleScroll);
     this.viewport.removeEventListener('ok-collapsible-pager-insets-changed', this.handleCollapsiblePagerInsetsChanged);
     this.root.removeEventListener('click', this.handleClick);

package/lib/typescript/src/web/NativeListWebEngine.d.ts

@@ -142,6 +142,8 @@ export declare class NativeListWebEngine {
     private destroyed;
     private sectionIndexAlignStart;
     private measuredRendererHeights;
+    private notifyScrollCommandAccepted;
+    private readonly handlePagerScrollCommandCancel;
     constructor(host: HTMLElement, snapshot: NativeListSnapshot, callbacks: NativeListWebCallbacks, virtualizationEnabled?: boolean, sectionIndexContainer?: HTMLElement | null);
     updateCallbacks(callbacks: NativeListWebCallbacks): void;
     setVirtualizationEnabled(enabled: boolean): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/react-native-native-list",
-  "version": "3.0.173",
+  "version": "3.0.175",
   "description": "Template-driven native RecyclerView and UICollectionView for React Native",
   "source": "./src/index.ts",
   "main": "./lib/module/index.js",
@@ -87,8 +87,8 @@
     "typescript": "^5.9.2"
   },
   "peerDependencies": {
-    "@onekeyfe/react-native-image": "3.0.173",
-    "@onekeyfe/react-native-native-logger": "3.0.173",
+    "@onekeyfe/react-native-image": "3.0.175",
+    "@onekeyfe/react-native-native-logger": "3.0.175",
     "react": "*",
     "react-native": "*",
     "react-native-nitro-modules": "0.37.0"

package/src/web/NativeListWebEngine.ts

@@ -2025,6 +2025,25 @@ export class NativeListWebEngine {
     { signature: string; height: number }
   >();
 
+  private notifyScrollCommandAccepted() {
+    if (this.destroyed) return;
+    const EventConstructor = this.viewport.ownerDocument.defaultView?.Event;
+    if (EventConstructor)
+      this.viewport.dispatchEvent(
+        new EventConstructor('ok-native-list-scroll-command-accepted')
+      );
+  }
+
+  private readonly handlePagerScrollCommandCancel = (event: Event) => {
+    if (this.destroyed || event.target !== this.viewport) return;
+    this.pendingScroll = undefined;
+    this.viewport.scrollTo({
+      left: this.viewport.scrollLeft,
+      top: this.viewport.scrollTop,
+      behavior: 'instant',
+    });
+  };
+
   constructor(
     host: HTMLElement,
     snapshot: NativeListSnapshot,
@@ -2100,6 +2119,10 @@ export class NativeListWebEngine {
     this.root.append(style, this.viewportFrame, this.footer);
     host.appendChild(this.root);
 
+    this.viewport.addEventListener(
+      'ok-collapsible-pager-cancel-scroll-command',
+      this.handlePagerScrollCommandCancel
+    );
     this.viewport.addEventListener('scroll', this.handleScroll, {
       passive: true,
     });
@@ -2242,6 +2265,7 @@ export class NativeListWebEngine {
       this.emitScrollFailure(index, 'index-out-of-range');
       return;
     }
+    this.notifyScrollCommandAccepted();
     if (!this.canScroll()) {
       this.pendingScroll = { kind: 'index', index, scroll };
       return;
@@ -2274,6 +2298,7 @@ export class NativeListWebEngine {
 
   scrollToOffset(offset: number, animated: boolean) {
     validateOffset(offset);
+    this.notifyScrollCommandAccepted();
     if (!this.canScroll()) {
       this.pendingScroll = { kind: 'offset', offset, animated };
       return;
@@ -2282,6 +2307,7 @@ export class NativeListWebEngine {
   }
 
   scrollToEnd(animated: boolean) {
+    this.notifyScrollCommandAccepted();
     if (!this.canScroll()) {
       this.pendingScroll = { kind: 'end', animated };
       return;
@@ -2360,6 +2386,11 @@ export class NativeListWebEngine {
       'resize',
       this.handleWindowResize
     );
+    this.pendingScroll = undefined;
+    this.viewport.removeEventListener(
+      'ok-collapsible-pager-cancel-scroll-command',
+      this.handlePagerScrollCommandCancel
+    );
     this.viewport.removeEventListener('scroll', this.handleScroll);
     this.viewport.removeEventListener(
       'ok-collapsible-pager-insets-changed',