@onekeyfe/react-native-pager-view 3.0.173 → 3.0.174

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

@@ -29,6 +29,7 @@ import com.facebook.react.views.scroll.ReactScrollView
 import com.margelo.nitro.nativelogger.OneKeyLog
 import java.lang.ref.WeakReference
 import java.util.WeakHashMap
+import java.util.function.BiConsumer
 import kotlin.math.max
 import kotlin.math.min
 import kotlin.math.roundToInt
@@ -123,6 +124,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private val originalScrollerPadding = WeakHashMap<ScrollView, ScrollerPadding>()
   private val restoredScrollerKeys = WeakHashMap<ScrollView, String>()
   private val ownedScrollerKeys = WeakHashMap<NativeScrollerViewport, String>()
+  private val ownedScrollerRestoreRequests = HashMap<String, Pair<WeakReference<NativeScrollerViewport>, Int?>>()
   private var foregroundRefreshIndicator: WeakReference<ImageView>? = null
   private var refreshForegroundWasVisible = false
   private val refreshForegroundMatrix = Matrix()
@@ -130,13 +132,74 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private val refreshForegroundAncestors = ArrayList<View>()
   private var refreshForegroundAncestorAlpha = 1f
   private val pageOffsets = HashMap<String, Int>()
+  private val pageHeaderOffsets = HashMap<String, Int>()
+  private class RecyclerReadingAnchor(view: RecyclerView, val adapter: RecyclerView.Adapter<*>, val position: Int, val top: Int) {
+    val view = WeakReference(view)
+  }
+  private val recyclerReadingAnchors = HashMap<String, RecyclerReadingAnchor>()
+  private val displayRecyclerAnchors = HashMap<String, RecyclerReadingAnchor>()
+  private var transitionSourceRecyclerAnchor: RecyclerReadingAnchor? = null
+  private val commandBodyKeys = HashSet<String>()
+  private var explicitTopCommand: Pair<String, PageRestoreRequest>? = null
+  private class PagerTopRequest(view: View, val key: String, val pageIndex: Int, val generation: Int, val target: Int, val token: Int) {
+    val view = WeakReference(view)
+  }
+  private var pagerTopRequest: PagerTopRequest? = null
+  private var pagerTopToken = 0
+  private var dispatchingPagerTop = false
+  private val suspendedBodyKeys = HashSet<String>()
+  private val alignedBodyKeys = HashSet<String>()
+  private val transitionAlignedViews = WeakHashMap<View, String>()
+  private var transitionSourceDisplayBody = 0
+  private val displayBodyOverrides = HashMap<String, Int>()
+  private val deferredRecyclerGeometry = WeakHashMap<RecyclerView, Triple<Int, Int, Int>>()
+  private var transitionHeaderOffsets: Map<String, Int>? = null
+  private var transitionPageOffsets: Map<String, Int>? = null
+  private var transitionSourcePage = 0
+  private var transitionTargetPage: Int? = null
+  private var syntheticPageRestore = false
+  private var resumeTransitionSource: Int? = null
+  private val pendingPageRestores = HashSet<String>()
+  private class PageRestoreRequest(view: View, val pageIndex: Int, val generation: Int) {
+    val view = WeakReference(view)
+  }
+  private val pageRestoreRequests = HashMap<String, PageRestoreRequest>()
+
+  private fun registerPageRestore(key: String, view: View, pageIndex: Int): PageRestoreRequest? {
+    if (!nativeSmoothHeaderScrollEnabled) return null
+    val previous = pageRestoreRequests[key]?.view?.get()
+    if (previous is NativeScrollerViewport && previous !== view) previous.host.cancelPendingScrollRestore()
+    ownedScrollerRestoreRequests.remove(key)
+    return PageRestoreRequest(view, pageIndex, attachmentGeneration).also {
+      pageRestoreRequests[key] = it
+      pendingPageRestores.add(key)
+      offsetDiag("request-register", view, key, pageIndex, it)
+    }
+  }
+
+  private fun isCurrentPageRestore(key: String, request: PageRestoreRequest?): Boolean =
+    !nativeSmoothHeaderScrollEnabled || (request != null && pageRestoreRequests[key] === request &&
+      key in pendingPageRestores && request.generation == attachmentGeneration &&
+      pageKey(request.pageIndex) == key)
+
+  private fun clearPageRestoreForView(key: String, view: View, request: PageRestoreRequest? = null) {
+    if (request != null && pageRestoreRequests[key] !== request) return
+    if (pageRestoreRequests[key]?.view?.get() !== view) return
+    offsetDiag("request-clear-before", view, key, request = request ?: pageRestoreRequests[key])
+    pageRestoreRequests.remove(key)
+    pendingPageRestores.remove(key)
+    ownedScrollerRestoreRequests.remove(key)
+    offsetDiag("request-clear-after", view, key, request = request)
+  }
   private var observedRecyclerView: RecyclerView? = null
+  private var observedRecyclerKey: String? = null
   private var observedScrollListener: RecyclerView.OnScrollListener? = null
   private var observedOwnedScroller: NativeScrollerViewport? = null
   private var observedOwnedScrollerKey: String? = null
   private var observedOwnedScrollerListener: ViewTreeObserver.OnScrollChangedListener? = null
   private var observedOwnedScrollerTreeObserver: ViewTreeObserver? = null
   private var observedNativeScroller: ScrollView? = null
+  private var observedNativeScrollerKey: String? = null
   private var observedNativeScrollerListener: ViewTreeObserver.OnScrollChangedListener? = null
   private var observedNativeScrollerTreeObserver: ViewTreeObserver? = null
   private var observedPageRemoved = false
@@ -162,8 +225,14 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     // Apply its header insets before that list first draws.
     prepareAdjacentPages()
     attachPrimaryScrollObserver()
+    finishPagerTopIfSettled()
     // OneKey patch: a filtered short page can reduce the existing collapse range.
     setHeaderOffset(headerOffsetPx)
+    if (offsetDiagEnabled() && offsetDiagNextDraw.isNotEmpty()) {
+      val samples = offsetDiagNextDraw.entries.map { it.key to it.value }
+      offsetDiagNextDraw.clear()
+      samples.forEach { (view, owner) -> offsetDiag("restore-next-predraw", view, owner.first, owner.second) }
+    }
     true
   }
 
@@ -189,6 +258,20 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   var headerOffsetPx = 0
     private set
   var pageKeys: List<String> = emptyList()
+    set(value) {
+      if (field == value) return
+      pageRestoreRequests.entries.toList().forEach { (key, request) ->
+        if ((value.getOrNull(request.pageIndex) ?: "page-${request.pageIndex}") != key) {
+          (request.view.get() as? NativeScrollerViewport)?.host?.cancelPendingScrollRestore()
+          pageRestoreRequests.remove(key)
+          pendingPageRestores.remove(key)
+          ownedScrollerRestoreRequests.remove(key)
+        }
+      }
+      recyclerReadingAnchors.keys.retainAll(value.toSet())
+      displayRecyclerAnchors.keys.retainAll(value.toSet())
+      field = value
+    }
   var retainedPages: String = "[]"
   var onHeaderOffsetChanged: (() -> Unit)? = null
   var nativeSmoothHeaderScrollEnabled = false
@@ -230,6 +313,51 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     OneKeyLog.debug("CollapsiblePager", "host=$hostIdentity $message")
   }
 
+  private var offsetDiagSequence = 0L
+  private val offsetDiagNextDraw = WeakHashMap<View, Pair<String, Int>>()
+
+  private fun offsetDiagEnabled(): Boolean =
+    (context.applicationInfo.flags and android.content.pm.ApplicationInfo.FLAG_DEBUGGABLE) != 0
+
+  private fun offsetDiagAfterDraw(view: View, key: String, pageIndex: Int) {
+    if (offsetDiagEnabled()) offsetDiagNextDraw[view] = key to pageIndex
+  }
+
+  private fun offsetDiag(
+    phase: String,
+    view: View? = null,
+    key: String = currentPageKey(),
+    pageIndex: Int = pageKeys.indexOf(key),
+    request: PageRestoreRequest? = pageRestoreRequests[key],
+  ) {
+    if (!offsetDiagEnabled()) return
+    val safeKey = if (key in setOf("portfolio", "perps", "defi", "nft", "history")) key else "other"
+    val observed = observedOwnedScroller ?: observedNativeScroller ?: observedRecyclerView
+    val observedKey = observedOwnedScrollerKey ?: observedNativeScrollerKey ?: observedRecyclerKey
+    val recycler = view as? RecyclerView
+    val manager = recycler?.layoutManager as? LinearLayoutManager
+    val first = manager?.findFirstVisibleItemPosition()
+    val last = manager?.findLastVisibleItemPosition()
+    val anchor = first?.takeIf { it != RecyclerView.NO_POSITION }?.let { manager?.findViewByPosition(it) }
+    val child = (view as? ViewGroup)?.getChildAt(0)
+    OneKeyLog.debug("CollapsiblePager", "[HOME-OFFSET-DIAG] phase=$phase seq=${++offsetDiagSequence} " +
+      "wallMs=${System.currentTimeMillis()} monoMs=${SystemClock.uptimeMillis()} host=$hostIdentity " +
+      "generation=$attachmentGeneration selectedPage=$selectedPage pagerPage=${pager.currentItem} targetPage=$pageIndex key=$safeKey " +
+      "ownerPage=${pageKeys.indexOf(observedKey)} header=$headerOffsetPx headerHeight=$headerHeightPx stickyHeight=$stickyHeaderHeightPx " +
+      "transition=${transitionHeaderOffsets != null} synthetic=$syntheticPageRestore pending=${key in pendingPageRestores} " +
+      "requestId=${request?.let { System.identityHashCode(it) }} requestGeneration=${request?.generation} " +
+      "requestPage=${request?.pageIndex} requestCurrent=${request != null && pageRestoreRequests[key] === request} " +
+      "view=${view?.let { System.identityHashCode(it) }} tag=${view?.id} observed=${observed?.let { System.identityHashCode(it) }} " +
+      "attached=${view?.isAttachedToWindow} estimatedOffset=${view?.let(::verticalScrollOffset)} " +
+      "cachePresent=${pageOffsets.containsKey(key)} cache=${pageOffsets[key]} snapshot=${transitionPageOffsets?.get(key)} " +
+      "boundsHeight=${view?.height} measuredHeight=${view?.measuredHeight} childHeight=${child?.height} childTop=${child?.top} " +
+      "paddingTop=${view?.paddingTop} paddingBottom=${view?.paddingBottom} childCount=${(view as? ViewGroup)?.childCount} " +
+      "itemCount=${recycler?.adapter?.itemCount} first=$first last=$last anchorTag=${anchor?.id} " +
+      "anchorTop=${anchor?.let { manager?.getDecoratedTop(it) }} anchorRelative=${anchor?.let { manager?.getDecoratedTop(it)?.minus(recycler?.paddingTop ?: 0) }} " +
+      "range=${recycler?.computeVerticalScrollRange()} extent=${recycler?.computeVerticalScrollExtent()} " +
+      "canUp=${view?.canScrollVertically(-1)} canDown=${view?.canScrollVertically(1)} scrollState=${recycler?.scrollState} computing=${recycler?.isComputingLayout}")
+  }
+
   private fun outerPagerIndex(): Int {
     var ancestor = parent as? View
     while (ancestor != null) {
@@ -364,6 +492,19 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   fun removeAllReactChildren() {
     releaseRefreshForeground()
     detachPrimaryScrollObserver()
+    pageRestoreRequests.clear()
+    pendingPageRestores.clear()
+    commandBodyKeys.clear()
+    explicitTopCommand = null
+    suspendedBodyKeys.clear()
+    alignedBodyKeys.clear()
+    transitionAlignedViews.clear()
+    deferredRecyclerGeometry.clear()
+    displayBodyOverrides.clear()
+    displayRecyclerAnchors.clear()
+    ownedScrollerRestoreRequests.clear()
+    recyclerReadingAnchors.clear()
+    transitionSourceRecyclerAnchor = null
     // Weak keys may disappear after size is read; Collection.toArray tolerates this.
     for (recycler in originalRecyclerPadding.keys.toTypedArray()) {
       restoreRecyclerInsets(recycler)
@@ -386,16 +527,90 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
 
   fun reactChildAt(index: Int) = logicalChildren[index]
 
+  internal fun beginPageTransition(target: Int? = null) {
+    cancelPagerTop()
+    if (!nativeSmoothHeaderScrollEnabled || headerHeightPx <= 0) return
+    if (transitionHeaderOffsets == null) {
+      transitionSourceDisplayBody = primaryScrollableForPage(selectedPage)?.let(::verticalScrollOffset) ?: 0
+      transitionSourceRecyclerAnchor = (primaryScrollableForPage(selectedPage) as? RecyclerView)?.let(::captureRecyclerAnchor)
+      pageHeaderOffsets[currentPageKey()] = headerOffsetPx
+      detachPrimaryScrollObserver()
+      transitionSourcePage = selectedPage
+      transitionHeaderOffsets = pageHeaderOffsets.toMap()
+      transitionPageOffsets = pageOffsets.toMap()
+    }
+    if (target != null) {
+      transitionTargetPage = target
+      alignPageBody(target)
+    }
+    offsetDiag("transition-begin-source=$transitionSourcePage", primaryScrollableForPage(selectedPage), pageKey(target ?: selectedPage), target ?: selectedPage)
+  }
+
+  internal fun onPagerScrolled(position: Int, offset: Float) {
+    if (transitionHeaderOffsets == null) return
+    alignPageBody(position)
+    if (position + 1 < adapter.itemCount) alignPageBody(position + 1)
+    updateNativeTabProgress(position, offset)
+  }
+
+  internal fun onPagerScrollStateChanged(state: Int) {
+    if (state == ViewPager2.SCROLL_STATE_DRAGGING || state == ViewPager2.SCROLL_STATE_SETTLING) {
+      beginPageTransition()
+    } else if (state == ViewPager2.SCROLL_STATE_IDLE && transitionHeaderOffsets != null) {
+      finishPageTransition(pager.currentItem)
+    }
+  }
+
+  private fun finishPageTransition(position: Int) {
+    val headers = transitionHeaderOffsets ?: return
+    detachPrimaryScrollObserver(recordOffset = false)
+    releaseRefreshForeground()
+    selectedPage = position.coerceIn(0, adapter.itemCount - 1)
+    syntheticPageRestore = true
+    setHeaderOffset(headers[pageKey(transitionSourcePage)] ?: headerOffsetPx)
+    transitionHeaderOffsets = null
+    transitionPageOffsets = null
+    transitionTargetPage = null
+    syntheticPageRestore = false
+    transitionAlignedViews.clear()
+    if (selectedPage == transitionSourcePage) {
+      displayBodyOverrides[currentPageKey()] = transitionSourceDisplayBody
+      transitionSourceRecyclerAnchor?.let { displayRecyclerAnchors[currentPageKey()] = it }
+    } else {
+      displayBodyOverrides.remove(currentPageKey())
+      displayRecyclerAnchors.remove(currentPageKey())
+    }
+    transitionSourceRecyclerAnchor = null
+    if (headerOffsetPx == headerHeightPx) suspendedBodyKeys.remove(currentPageKey())
+    else if ((pageOffsets[currentPageKey()] ?: 0) > 0) suspendedBodyKeys.add(currentPageKey())
+    alignPageBody(selectedPage, force = true)
+    offsetDiag("transition-finish", primaryScrollableForPage(selectedPage), currentPageKey(), selectedPage)
+    prepareAdjacentPages()
+    attachPrimaryScrollObserver()
+  }
+
   fun selectPage(position: Int) {
+    offsetDiag("select-begin", observedOwnedScroller ?: observedNativeScroller ?: observedRecyclerView, pageKey(position), position)
     pendingRefreshPull = null
     if (adapter.itemCount == 0) return
+    if (nativeSmoothHeaderScrollEnabled && headerHeightPx > 0) {
+      if (transitionHeaderOffsets != null) return
+      beginPageTransition(position)
+      finishPageTransition(position)
+      return
+    }
     detachPrimaryScrollObserver()
     releaseRefreshForeground()
     selectedPage = position.coerceIn(0, adapter.itemCount - 1)
     val savedOffset = pageOffsets[currentPageKey()]
       ?: primaryScrollableForPage(selectedPage)?.let(::verticalScrollOffset)
       ?: 0
-    if (savedOffset > 0) setHeaderOffset(headerHeightPx)
+    offsetDiag("select-offset=$savedOffset-source=${if (pageOffsets[currentPageKey()] != null) "saved" else "live"}")
+    if (savedOffset > 0) {
+      offsetDiag("select-force-collapse-before")
+      setHeaderOffset(headerHeightPx)
+      offsetDiag("select-force-collapse-after")
+    }
     postForCurrentAttachment {
       prepareAdjacentPages()
       attachPrimaryScrollObserver()
@@ -519,7 +734,287 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     }
   }
 
+  private fun restorationBodyOffset(key: String): Int {
+    val saved = if (transitionPageOffsets != null && key == pageKey(transitionSourcePage)) transitionSourceDisplayBody
+      else displayBodyOverrides[key] ?: transitionPageOffsets?.get(key) ?: pageOffsets[key] ?: 0
+    return if (nativeSmoothHeaderScrollEnabled && headerOffsetPx < headerHeightPx) 0 else saved
+  }
+
+  private fun captureRecyclerAnchor(view: RecyclerView): RecyclerReadingAnchor? {
+    val manager = view.layoutManager as? LinearLayoutManager ?: return null
+    if (manager.orientation != RecyclerView.VERTICAL) return null
+    val position = manager.findFirstVisibleItemPosition()
+    val child = manager.findViewByPosition(position) ?: return null
+    val adapter = view.adapter ?: return null
+    return RecyclerReadingAnchor(view, adapter, position, manager.getDecoratedTop(child) - view.paddingTop)
+  }
+
+  private fun saveRecyclerReadingAnchor(key: String, view: RecyclerView) {
+    captureRecyclerAnchor(view)?.let { recyclerReadingAnchors[key] = it }
+  }
+
+  private fun restoreRecyclerAnchor(view: RecyclerView, key: String, index: Int, request: PageRestoreRequest?): Boolean {
+    if (!nativeSmoothHeaderScrollEnabled || pageKey(index) != key ||
+        primaryScrollableForPage(index) !== view || !isCurrentPageRestore(key, request) ||
+        !isAttachedToWindow || !view.isAttachedToWindow || view.width <= 0 || view.height <= 0 ||
+        isInLayout || view.isInLayout || view.isComputingLayout) return false
+    val manager = view.layoutManager as? LinearLayoutManager
+    val reading = recyclerReadingAnchors[key]?.takeIf { it.view.get() === view && it.adapter === view.adapter }
+    val display = (if (transitionPageOffsets != null && index == transitionSourcePage) transitionSourceRecyclerAnchor
+      else displayRecyclerAnchors[key])?.takeIf { it.view.get() === view && it.adapter === view.adapter }
+    if (manager == null || manager.orientation != RecyclerView.VERTICAL ||
+      (headerOffsetPx == headerHeightPx && reading == null && display == null && restorationBodyOffset(key) > 0)) {
+      val saved = restorationBodyOffset(key)
+      val current = view.computeVerticalScrollOffset()
+      val previousSynthetic = syntheticPageRestore
+      syntheticPageRestore = true
+      try { if (saved != current) view.scrollBy(0, saved - current) }
+      finally { syntheticPageRestore = previousSynthetic }
+      return saved <= view.computeVerticalScrollOffset() || view.canScrollVertically(1)
+    }
+    val target = if (headerOffsetPx < headerHeightPx) null else display ?: reading
+    val position = target?.position ?: 0
+    val top = target?.top ?: 0
+    if (position !in 0 until (view.adapter?.itemCount ?: 0)) return false
+    fun reached(): Boolean {
+      val actual = captureRecyclerAnchor(view) ?: return false
+      return actual.position == position && actual.top == top
+    }
+    if (!reached()) {
+      if (!isAttachedToWindow || !view.isAttachedToWindow || width <= 0 || height <= 0 ||
+          view.width <= 0 || view.height <= 0 || isInLayout || view.isInLayout || view.isComputingLayout ||
+          pageKey(index) != key || primaryScrollableForPage(index) !== view || !isCurrentPageRestore(key, request)) return false
+      val previousSynthetic = syntheticPageRestore
+      syntheticPageRestore = true
+      try {
+        manager.scrollToPositionWithOffset(position, top)
+        // Use the existing inset commit boundary once, before the target's first frame.
+        view.forceLayout()
+        view.measure(MeasureSpec.makeMeasureSpec(view.width, MeasureSpec.EXACTLY), MeasureSpec.makeMeasureSpec(view.height, MeasureSpec.EXACTLY))
+        view.layout(view.left, view.top, view.right, view.bottom)
+      } finally {
+        syntheticPageRestore = previousSynthetic
+      }
+      offsetDiag("recycler-anchor-restore-position=$position-top=$top", view, key, index, request)
+    }
+    val readingStillUnreachable = display != null && reading != null &&
+      (reading.position != position || reading.top != top) && !view.canScrollVertically(1)
+    return reached() && !readingStillUnreachable
+  }
+
+  private fun alignPageBody(index: Int, force: Boolean = false) {
+    if (!nativeSmoothHeaderScrollEnabled || index !in 0 until adapter.itemCount) return
+    val view = primaryScrollableForPage(index) ?: return
+    val key = pageKey(index)
+    if (!force && transitionAlignedViews[view] == key) return
+    transitionAlignedViews[view] = key
+    if (transitionPageOffsets != null && index != transitionSourcePage) {
+      displayBodyOverrides.remove(key)
+      displayRecyclerAnchors.remove(key)
+    }
+    alignedBodyKeys.add(key)
+    if (headerOffsetPx < headerHeightPx && (pageOffsets[key] ?: 0) > 0) suspendedBodyKeys.add(key)
+    val previousSynthetic = syntheticPageRestore
+    syntheticPageRestore = true
+    when (view) {
+      is NativeScrollerViewport -> {
+        ownedScrollerKeys.remove(view)
+        applyOwnedScrollerInsets(view, index)
+        view.host.restoreScrollOffset(restorationBodyOffset(key))
+      }
+      is RecyclerView -> {
+        restoredRecyclerKeys.remove(view)
+        applyRecyclerInsets(view, index)
+        restoreRecyclerAnchor(view, key, index, pageRestoreRequests[key])
+      }
+      is ScrollView -> {
+        restoredScrollerKeys.remove(view)
+        applyNativeScrollerInsets(view, index)
+        if (view.height > 0 && view.childCount > 0) view.scrollTo(view.scrollX, restorationBodyOffset(key))
+      }
+    }
+    syntheticPageRestore = previousSynthetic
+  }
+
+  private fun takeOverBodyForVerticalConsumption() {
+    cancelPagerTop()
+    if (!nativeSmoothHeaderScrollEnabled || transitionHeaderOffsets != null || syntheticPageRestore) return
+    val key = currentPageKey()
+    commandBodyKeys.remove(key)
+    explicitTopCommand = null
+    suspendedBodyKeys.remove(key)
+    alignedBodyKeys.remove(key)
+    displayBodyOverrides.remove(key)
+    displayRecyclerAnchors.remove(key)
+    pageOffsets[key] = primaryScrollableForPage(selectedPage)?.let(::verticalScrollOffset) ?: 0
+    (primaryScrollableForPage(selectedPage) as? RecyclerView)?.let { saveRecyclerReadingAnchor(key, it) }
+  }
+
+  internal fun acceptObservedScrollCommand(view: View, explicitTop: Boolean, phase: Int = 0) {
+    if (dispatchingPagerTop && matchesPagerTop(view)) return
+    if (phase == 0 && view === (observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller)) cancelPagerTop()
+    if (phase != 0 && matchesPagerTop(view)) { finishPagerTopIfSettled(); return }
+    val owner = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
+    if (!nativeSmoothHeaderScrollEnabled || view !== owner || transitionHeaderOffsets != null || syntheticPageRestore ||
+      !isAttachedToWindow || !view.isAttachedToWindow) return
+    val key = currentPageKey()
+    val observedKey = observedRecyclerKey ?: observedOwnedScrollerKey ?: observedNativeScrollerKey
+    if (observedKey != key) return
+    if (phase == 1) { commandBodyKeys.add(key); return }
+    if (phase == 2) {
+      if (!commandBodyKeys.remove(key)) return
+      val completingExplicitTop = hasExplicitTopCommand(view, key)
+      val manager = (view as? RecyclerView)?.layoutManager as? LinearLayoutManager
+      val first = manager?.findViewByPosition(0)
+      val atExplicitTop = completingExplicitTop && manager != null && manager.orientation == RecyclerView.VERTICAL &&
+        manager.findFirstVisibleItemPosition() == 0 && first != null &&
+        manager.getDecoratedTop(first) - view.paddingTop == 0
+      explicitTopCommand = null
+      pageOffsets[key] = if (atExplicitTop) 0 else verticalScrollOffset(view)
+      if (view is RecyclerView) saveRecyclerReadingAnchor(key, view)
+      if (atExplicitTop) setHeaderOffset(0)
+      else if ((pageOffsets[key] ?: 0) > 0) setHeaderOffset(headerHeightPx)
+      offsetDiag("command-result-complete", view, key)
+      return
+    }
+    commandBodyKeys.remove(key)
+    explicitTopCommand = if (explicitTop && view is RecyclerView) {
+      key to PageRestoreRequest(view, selectedPage, attachmentGeneration)
+    } else null
+    pageRestoreRequests.remove(key)
+    pendingPageRestores.remove(key)
+    ownedScrollerRestoreRequests.remove(key)
+    if (view is RecyclerView) deferredRecyclerGeometry.remove(view)
+    (view as? NativeScrollerViewport)?.host?.cancelPendingScrollRestore()
+    suspendedBodyKeys.remove(key)
+    alignedBodyKeys.remove(key)
+    displayBodyOverrides.remove(key)
+    displayRecyclerAnchors.remove(key)
+    if (view is RecyclerView) saveRecyclerReadingAnchor(key, view)
+    pageOffsets[key] = if (explicitTop) 0 else verticalScrollOffset(view)
+    if (explicitTop) setHeaderOffset(0)
+    offsetDiag("command-body-takeover-top=$explicitTop", view, key)
+  }
+
+  private fun matchesPagerTop(view: View): Boolean {
+    val request = pagerTopRequest ?: return false
+    val owner = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
+    val observedKey = observedRecyclerKey ?: observedOwnedScrollerKey ?: observedNativeScrollerKey
+    return request.view.get() === view && owner === view && observedKey == request.key &&
+      request.key == currentPageKey() && request.pageIndex == selectedPage &&
+      request.generation == attachmentGeneration && view.isAttachedToWindow && isAttachedToWindow
+  }
+
+  private fun cancelPagerTop() {
+    pagerTopRequest?.let { commandBodyKeys.remove(it.key) }
+    pagerTopRequest = null
+  }
+
+  private fun recyclerIsAtBodyTop(view: RecyclerView): Boolean {
+    val manager = view.layoutManager as? LinearLayoutManager ?: return !view.canScrollVertically(-1)
+    val first = manager.findViewByPosition(0) ?: return view.adapter?.itemCount == 0
+    return manager.orientation == RecyclerView.VERTICAL && manager.findFirstVisibleItemPosition() == 0 &&
+      manager.getDecoratedTop(first) - view.paddingTop == 0
+  }
+
+  private fun finishPagerTopIfSettled() {
+    val request = pagerTopRequest ?: return
+    val view = request.view.get() ?: run { cancelPagerTop(); return }
+    if (!matchesPagerTop(view)) { cancelPagerTop(); return }
+    if (dispatchingPagerTop) return
+    val settled = when (view) {
+      is RecyclerView -> !view.isComputingLayout && view.scrollState == RecyclerView.SCROLL_STATE_IDLE &&
+        view.layoutManager?.isSmoothScrolling != true && recyclerIsAtBodyTop(view)
+      is NativeScrollerViewport -> !view.isReadingMotionActive() && view.scrollY == 0
+      is ScrollView -> view.scrollY == 0
+      else -> false
+    }
+    if (!settled) return
+    pageOffsets[request.key] = 0
+    if (view is RecyclerView) saveRecyclerReadingAnchor(request.key, view)
+    setHeaderOffset(if (request.target == 1) headerHeightPx else 0)
+    offsetDiag("pager-top-complete-target=${request.target}-token=${request.token}", view, request.key)
+    cancelPagerTop()
+  }
+
+  internal fun scrollToTop(target: Int, animated: Boolean) {
+    if (target !in 0..1 || pager.scrollState != ViewPager2.SCROLL_STATE_IDLE || transitionHeaderOffsets != null ||
+      syntheticPageRestore || selectedPage !in 0 until adapter.itemCount || !isAttachedToWindow) return
+    val view = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller ?: return
+    val key = currentPageKey()
+    val ownerKey = observedRecyclerKey ?: observedOwnedScrollerKey ?: observedNativeScrollerKey
+    if (ownerKey != key || !view.isAttachedToWindow || primaryScrollableForPage(selectedPage) !== view) return
+    // Finish old child notifications before installing the new Pager-owned target.
+    cancelPagerTop()
+    if (view is RecyclerView) {
+      (view.getTag(R.id.onekey_native_scroll_coordinator_command_cancel_listener) as? Runnable)?.run()
+      view.stopScroll()
+    } else if (view is NativeScrollerViewport) {
+      view.stopMotion()
+      view.host.cancelPendingScrollRestore()
+    }
+    explicitTopCommand = null
+    pageRestoreRequests.remove(key)
+    pendingPageRestores.remove(key)
+    ownedScrollerRestoreRequests.remove(key)
+    suspendedBodyKeys.remove(key)
+    alignedBodyKeys.remove(key)
+    displayBodyOverrides.remove(key)
+    displayRecyclerAnchors.remove(key)
+    recyclerReadingAnchors.remove(key)
+    if (view is RecyclerView) deferredRecyclerGeometry.remove(view)
+    pageOffsets[key] = 0
+    val request = PagerTopRequest(view, key, selectedPage, attachmentGeneration, target, ++pagerTopToken)
+    pagerTopRequest = request
+    commandBodyKeys.add(key)
+    setHeaderOffset(if (target == 1) headerHeightPx else 0)
+    offsetDiag("pager-top-begin-target=$target-animated=$animated-token=${request.token}", view, key)
+    dispatchingPagerTop = true
+    try {
+      when (view) {
+        is RecyclerView -> {
+          val manager = view.layoutManager as? LinearLayoutManager
+          if (animated && !recyclerIsAtBodyTop(view)) view.smoothScrollToPosition(0)
+          else if (manager != null && manager.orientation == RecyclerView.VERTICAL) {
+            manager.scrollToPositionWithOffset(0, 0)
+            if (view.width > 0 && view.height > 0 && !isInLayout && !view.isInLayout && !view.isComputingLayout) {
+              view.measure(MeasureSpec.makeMeasureSpec(view.width, MeasureSpec.EXACTLY), MeasureSpec.makeMeasureSpec(view.height, MeasureSpec.EXACTLY))
+              view.layout(view.left, view.top, view.right, view.bottom)
+            }
+          } else view.scrollToPosition(0)
+        }
+        is NativeScrollerViewport -> view.host.scrollToPosition(0, 0, animated)
+        is ScrollView -> if (animated) view.smoothScrollTo(0, 0) else view.scrollTo(0, 0)
+      }
+    } finally { dispatchingPagerTop = false }
+    finishPagerTopIfSettled()
+  }
+
+  private fun hasExplicitTopCommand(view: View, key: String): Boolean {
+    val command = explicitTopCommand ?: return false
+    val request = command.second
+    return view is RecyclerView && observedRecyclerView === view && observedRecyclerKey == key &&
+      key == currentPageKey() && command.first == key && request.view.get() === view &&
+      request.pageIndex == selectedPage && request.generation == attachmentGeneration
+  }
+
+  private fun publishScrollCommandListener(recycler: RecyclerView, remove: Boolean = false) {
+    val tag = R.id.onekey_native_scroll_coordinator_command_listener
+    @Suppress("UNCHECKED_CAST")
+    val existing = recycler.getTag(tag) as? MutableMap<Any, BiConsumer<Boolean, Int>>
+    val listeners = existing ?: if (remove) return else mutableMapOf<Any, BiConsumer<Boolean, Int>>().also { recycler.setTag(tag, it) }
+    if (remove) listeners.remove(this)
+    else {
+      val generation = attachmentGeneration
+      val key = currentPageKey()
+      listeners[this] = BiConsumer { explicitTop, phase ->
+        if (generation == attachmentGeneration && key == currentPageKey()) acceptObservedScrollCommand(recycler, explicitTop, phase)
+      }
+    }
+  }
+
   private fun maximumHeaderOffset(): Int {
+    if (nativeSmoothHeaderScrollEnabled) return headerHeightPx
     val scrollable = observedRecyclerView
       ?: observedOwnedScroller
       ?: observedNativeScroller
@@ -537,9 +1032,14 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
 
   private fun setHeaderOffset(offset: Int) {
     // val next = offset.coerceIn(0, headerHeightPx)
-    val next = offset.coerceIn(0, maximumHeaderOffset())
+    val pending = nativeSmoothHeaderScrollEnabled && currentPageKey() in pendingPageRestores
+    val maximum = if (transitionHeaderOffsets != null || pending || pagerTopRequest != null) headerHeightPx else maximumHeaderOffset()
+    val next = offset.coerceIn(0, maximum)
     if (headerOffsetPx == next) return
     headerOffsetPx = next
+    if (nativeSmoothHeaderScrollEnabled && transitionHeaderOffsets == null && !syntheticPageRestore && !pending) {
+      pageHeaderOffsets[currentPageKey()] = next
+    }
     applyHeaderOffset()
   }
 
@@ -656,13 +1156,20 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun attachPrimaryScrollObserver() {
+    if (transitionHeaderOffsets != null) return
     if (selectedPage !in 0 until adapter.itemCount) return
     val previous = observedRecyclerView ?: observedOwnedScroller ?: observedNativeScroller
     if (observedPageRemoved || previous != null && !isDescendant(previous, adapter.pageAt(selectedPage))) {
+      offsetDiag("primary-replacement-before-removed=$observedPageRemoved", previous)
       observedPageRemoved = false
-      detachPrimaryScrollObserver()
+      detachPrimaryScrollObserver(recordOffset = !nativeSmoothHeaderScrollEnabled)
       // A replacement scroller starts at the beginning while retaining header collapse.
-      pageOffsets[currentPageKey()] = 0
+      offsetDiag("primary-replacement-cache-before", previous)
+      if (!nativeSmoothHeaderScrollEnabled) {
+        offsetDiag("cache-write-replacement-new=0", previous)
+        pageOffsets[currentPageKey()] = 0
+      }
+      offsetDiag("primary-replacement-cache-after", previous)
     }
     when (val scrollable = primaryScrollableForPage(selectedPage)) {
       is RecyclerView -> attachRecyclerObserver(scrollable)
@@ -672,24 +1179,45 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun attachRecyclerObserver(recycler: RecyclerView) {
-    if (observedRecyclerView === recycler) {
+    if (observedRecyclerView === recycler && observedRecyclerKey == currentPageKey()) {
       applyRecyclerInsets(recycler, selectedPage)
       publishConsumedOffset(recycler)
       return
     }
 
     detachPrimaryScrollObserver()
+    offsetDiag("recycler-attach-before", recycler)
     observedRecyclerView = recycler
+    observedRecyclerKey = currentPageKey()
+    publishScrollCommandListener(recycler)
     applyRecyclerInsets(recycler, selectedPage)
     publishConsumedOffset(recycler)
+    val key = currentPageKey()
     val listener = object : RecyclerView.OnScrollListener() {
+      override fun onScrollStateChanged(recyclerView: RecyclerView, newState: Int) {
+        if (newState == RecyclerView.SCROLL_STATE_IDLE) finishPagerTopIfSettled()
+      }
       override fun onScrolled(recyclerView: RecyclerView, dx: Int, dy: Int) {
+        if (observedScrollListener !== this || observedRecyclerKey != key ||
+          key != currentPageKey() || !isAttachedToWindow ||
+          transitionHeaderOffsets != null || syntheticPageRestore || key in pendingPageRestores || key in alignedBodyKeys) {
+          if (offsetDiagEnabled() && (dx != 0 || dy != 0 || pageOffsets[key] != recyclerView.computeVerticalScrollOffset())) {
+            offsetDiag("recycler-observer-skip-dx=$dx-dy=$dy-listenerCurrent=${observedScrollListener === this}", recyclerView, key)
+          }
+          return
+        }
+        if (nativeSmoothHeaderScrollEnabled && key !in commandBodyKeys &&
+          (dy == 0 || recyclerView.scrollState == RecyclerView.SCROLL_STATE_IDLE)) return
         val contentOffset = recyclerView.computeVerticalScrollOffset()
-        pageOffsets[currentPageKey()] = contentOffset
+        if (pageOffsets[key] != contentOffset) offsetDiag("cache-write-recycler-observer-new=$contentOffset-dx=$dx-dy=$dy", recyclerView, key)
+        pageOffsets[key] = contentOffset
+        if (nativeSmoothHeaderScrollEnabled) saveRecyclerReadingAnchor(key, recyclerView)
         // Nested touch scrolling moves list content only after the header has
         // collapsed. Programmatic list jumps bypass those parent callbacks.
-        if (contentOffset > 0 && headerOffsetPx < headerHeightPx) {
+        if (contentOffset > 0 && headerOffsetPx < headerHeightPx && !hasExplicitTopCommand(recyclerView, key) && !matchesPagerTop(recyclerView)) {
+          offsetDiag("recycler-positive-collapse-before", recyclerView)
           setHeaderOffset(headerHeightPx)
+          offsetDiag("recycler-positive-collapse-after", recyclerView)
         }
       }
     }
@@ -702,11 +1230,21 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun detachRecyclerObserver(recordOffset: Boolean) {
+    cancelPagerTop()
+    explicitTopCommand = null
     val recycler = observedRecyclerView
     val listener = observedScrollListener
     if (recycler != null) {
-      if (recordOffset) pageOffsets[currentPageKey()] = recycler.computeVerticalScrollOffset()
+      offsetDiag("recycler-detach-save-before-record=$recordOffset", recycler, observedRecyclerKey ?: currentPageKey())
+      if (recordOffset && !nativeSmoothHeaderScrollEnabled && transitionPageOffsets == null) observedRecyclerKey?.let {
+        if (it !in pendingPageRestores) {
+          offsetDiag("cache-write-recycler-detach-new=${recycler.computeVerticalScrollOffset()}", recycler, it)
+          pageOffsets[it] = recycler.computeVerticalScrollOffset()
+        }
+      }
+      offsetDiag("recycler-detach-save-after", recycler, observedRecyclerKey ?: currentPageKey())
       publishConsumedOffset(recycler, remove = true)
+      publishScrollCommandListener(recycler, remove = true)
     }
     if (recycler != null && listener != null) recycler.removeOnScrollListener(listener)
     if (recycler != null) {
@@ -716,28 +1254,38 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
       )
     }
     observedRecyclerView = null
+    observedRecyclerKey = null
     observedScrollListener = null
   }
 
   private fun attachNativeScrollerObserver(scroller: ScrollView) {
-    if (observedNativeScroller === scroller) {
+    if (observedNativeScroller === scroller && observedNativeScrollerKey == currentPageKey()) {
       applyNativeScrollerInsets(scroller, selectedPage)
       return
     }
 
     detachPrimaryScrollObserver()
+    offsetDiag("scrollview-attach-before", scroller)
     observedNativeScroller = scroller
+    observedNativeScrollerKey = currentPageKey()
     applyNativeScrollerInsets(scroller, selectedPage)
+    val key = currentPageKey()
     val listener = object : ViewTreeObserver.OnScrollChangedListener {
       override fun onScrollChanged() {
         if (observedNativeScrollerListener !== this) {
           removeScrollChangedListener(null, scroller, this)
           return
         }
+        if (key != currentPageKey() || !isAttachedToWindow ||
+          transitionHeaderOffsets != null || syntheticPageRestore || key in pendingPageRestores || key in alignedBodyKeys) return
+        if (nativeSmoothHeaderScrollEnabled && nestedScrollingParentHelper.nestedScrollAxes == 0 && key !in commandBodyKeys) return
         val contentOffset = scroller.scrollY
-        pageOffsets[currentPageKey()] = contentOffset
-        if (contentOffset > 0 && headerOffsetPx < headerHeightPx) {
+        if (pageOffsets[key] != contentOffset) offsetDiag("cache-write-scrollview-observer-new=$contentOffset", scroller, key)
+        pageOffsets[key] = contentOffset
+        if (contentOffset > 0 && headerOffsetPx < headerHeightPx && !matchesPagerTop(scroller)) {
+          offsetDiag("scrollview-positive-collapse-before", scroller)
           setHeaderOffset(headerHeightPx)
+          offsetDiag("scrollview-positive-collapse-after", scroller)
         }
       }
     }
@@ -752,9 +1300,17 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   }
 
   private fun detachNativeScrollerObserver(recordOffset: Boolean) {
+    cancelPagerTop()
     val scroller = observedNativeScroller
     val listener = observedNativeScrollerListener
-    if (scroller != null && recordOffset) pageOffsets[currentPageKey()] = scroller.scrollY
+    offsetDiag("scrollview-detach-save-before-record=$recordOffset", scroller, observedNativeScrollerKey ?: currentPageKey())
+    if (scroller != null && recordOffset && !nativeSmoothHeaderScrollEnabled && transitionPageOffsets == null) observedNativeScrollerKey?.let {
+      if (it !in pendingPageRestores) {
+        offsetDiag("cache-write-scrollview-detach-new=${scroller.scrollY}", scroller, it)
+        pageOffsets[it] = scroller.scrollY
+      }
+    }
+    offsetDiag("scrollview-detach-save-after", scroller, observedNativeScrollerKey ?: currentPageKey())
     if (scroller != null && listener != null) {
       removeScrollChangedListener(observedNativeScrollerTreeObserver, scroller, listener)
     }
@@ -765,6 +1321,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
       )
     }
     observedNativeScroller = null
+    observedNativeScrollerKey = null
     observedNativeScrollerListener = null
     observedNativeScrollerTreeObserver = null
   }
@@ -793,9 +1350,24 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     val key = pageKey(pageIndex)
     if (ownedScrollerKeys[scroller] == key) return
     ownedScrollerKeys[scroller] = key
+    val restoreRequest = registerPageRestore(key, scroller, pageIndex)
+    if (nativeSmoothHeaderScrollEnabled) ownedScrollerRestoreRequests[key] = WeakReference(scroller) to null
+    val generation = attachmentGeneration
+    offsetDiag("owned-enqueue", scroller, key, pageIndex, restoreRequest)
     postForCurrentAttachment {
-      if (ownedScrollerKeys[scroller] == key && scroller.isAttachedToWindow) {
-        scroller.host.restoreScrollOffset(pageOffsets[key] ?: 0)
+      offsetDiag("owned-execute", scroller, key, pageIndex, restoreRequest)
+      if (isCurrentPageRestore(key, restoreRequest) && ownedScrollerKeys[scroller] == key && generation == attachmentGeneration &&
+        scroller.isAttachedToWindow && (!nativeSmoothHeaderScrollEnabled ||
+          (key in pendingPageRestores && ownedScrollerRestoreRequests[key]?.first?.get() === scroller))) {
+        offsetDiag("owned-restore-before", scroller, key, pageIndex, restoreRequest)
+        val saved = restorationBodyOffset(key)
+        scroller.host.restoreScrollOffset(saved)
+        if (nativeSmoothHeaderScrollEnabled) {
+          ownedScrollerRestoreRequests[key] = WeakReference(scroller) to generation
+          recordOwnedScrollerOffset(scroller, key)
+        }
+        offsetDiag("owned-restore-after-saved=$saved", scroller, key, pageIndex, restoreRequest)
+        offsetDiagAfterDraw(scroller, key, pageIndex)
       }
     }
   }
@@ -803,7 +1375,10 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private fun restoreOwnedScrollerInsets(scroller: NativeScrollerViewport) {
     scroller.stopMotion()
     scroller.host.cancelPendingScrollRestore()
-    ownedScrollerKeys.remove(scroller)
+    ownedScrollerKeys.remove(scroller)?.let { key ->
+      clearPageRestoreForView(key, scroller)
+      if (ownedScrollerRestoreRequests[key]?.first?.get() === scroller) ownedScrollerRestoreRequests.remove(key)
+    }
     publishConsumedOffset(scroller, remove = true)
     scroller.host.setPagerInset(this, null)
   }
@@ -811,9 +1386,11 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private fun attachOwnedScrollerObserver(scroller: NativeScrollerViewport) {
     if (observedOwnedScroller === scroller && observedOwnedScrollerKey == currentPageKey()) {
       applyOwnedScrollerInsets(scroller, selectedPage)
+      if (nativeSmoothHeaderScrollEnabled) recordOwnedScrollerOffset(scroller, currentPageKey())
       return
     }
     detachPrimaryScrollObserver()
+    offsetDiag("owned-attach-before", scroller)
     observedOwnedScroller = scroller
     observedOwnedScrollerKey = currentPageKey()
     val key = currentPageKey()
@@ -824,9 +1401,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
           removeScrollChangedListener(null, scroller, this)
           return
         }
-        val contentOffset = scroller.scrollY
-        pageOffsets[key] = contentOffset
-        if (contentOffset > 0 && headerOffsetPx < headerHeightPx) setHeaderOffset(headerHeightPx)
+        recordOwnedScrollerOffset(scroller, key)
       }
     }
     observedOwnedScrollerListener = listener
@@ -835,11 +1410,41 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     }
   }
 
+  private fun recordOwnedScrollerOffset(scroller: NativeScrollerViewport, key: String) {
+    if (ownedScrollerKeys[scroller] != key || !isAttachedToWindow || !scroller.isAttachedToWindow) return
+    if (key in pendingPageRestores) {
+      // A false native pending flag before our posted request executes is not cancellation.
+      val request = ownedScrollerRestoreRequests[key]
+      if (request == null || request.first.get() !== scroller || request.second != attachmentGeneration ||
+        scroller.width <= 0 || scroller.height <= 0 || scroller.host.hasPendingScrollRestore()) return
+      clearPageRestoreForView(key, scroller)
+    }
+    if (observedOwnedScroller !== scroller || observedOwnedScrollerKey != key ||
+      key != currentPageKey() || transitionHeaderOffsets != null || syntheticPageRestore || key in alignedBodyKeys) return
+    if (nativeSmoothHeaderScrollEnabled && !scroller.isReadingMotionActive() && key !in commandBodyKeys) return
+    val contentOffset = scroller.scrollY
+    if (pageOffsets[key] != contentOffset) offsetDiag("cache-write-owned-observer-new=$contentOffset", scroller, key)
+    pageOffsets[key] = contentOffset
+    if (contentOffset > 0 && headerOffsetPx < headerHeightPx && !matchesPagerTop(scroller)) {
+      offsetDiag("owned-positive-collapse-before", scroller, key)
+      setHeaderOffset(headerHeightPx)
+      offsetDiag("owned-positive-collapse-after", scroller, key)
+    }
+  }
+
   private fun detachOwnedScrollerObserver(recordOffset: Boolean) {
+    cancelPagerTop()
     val scroller = observedOwnedScroller ?: return
     scroller.stopMotion()
     publishConsumedOffset(scroller, remove = true)
-    if (recordOffset) observedOwnedScrollerKey?.let { pageOffsets[it] = scroller.scrollY }
+    offsetDiag("owned-detach-save-before-record=$recordOffset", scroller, observedOwnedScrollerKey ?: currentPageKey())
+    if (recordOffset && !nativeSmoothHeaderScrollEnabled && transitionPageOffsets == null) observedOwnedScrollerKey?.let {
+      if (it !in pendingPageRestores) {
+        offsetDiag("cache-write-owned-detach-new=${scroller.scrollY}", scroller, it)
+        pageOffsets[it] = scroller.scrollY
+      }
+    }
+    offsetDiag("owned-detach-save-after", scroller, observedOwnedScrollerKey ?: currentPageKey())
     observedOwnedScrollerListener?.let {
       removeScrollChangedListener(observedOwnedScrollerTreeObserver, scroller, it)
     }
@@ -876,6 +1481,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
       val anchorOffset = if (first != RecyclerView.NO_POSITION) {
         manager?.findViewByPosition(first)?.let { manager.getDecoratedTop(it) - recycler.paddingTop }
       } else null
+      offsetDiag("recycler-inset-before-nextTop=$top-anchorPosition=$first-anchorOffset=$anchorOffset", recycler, pageKey(pageIndex), pageIndex)
       recycler.setPadding(original.left, top, original.right, bottom)
       if (anchorOffset != null) manager?.scrollToPositionWithOffset(first, anchorOffset)
       // React Native can stop this nested requestLayout at its React-owned parent.
@@ -889,21 +1495,67 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
         recycler.layout(recycler.left, recycler.top, recycler.right, recycler.bottom)
       }
     }
+    if (original.appliedTopInset != topInset) offsetDiag("recycler-inset-after-old=${original.appliedTopInset}-new=$topInset", recycler, pageKey(pageIndex), pageIndex)
     original.appliedTopInset = topInset
     val key = pageKey(pageIndex)
+    val geometry = Triple(recycler.computeVerticalScrollRange(), recycler.computeVerticalScrollExtent(), recycler.childCount)
+    deferredRecyclerGeometry[recycler]?.let { deferred ->
+      if (geometry != deferred) {
+        restoredRecyclerKeys.remove(recycler)
+        deferredRecyclerGeometry.remove(recycler)
+        if (nativeSmoothHeaderScrollEnabled && headerOffsetPx == headerHeightPx) {
+          displayBodyOverrides.remove(key)
+          displayRecyclerAnchors.remove(key)
+        }
+      }
+    }
     if (restoredRecyclerKeys[recycler] != key) {
       restoredRecyclerKeys[recycler] = key
+      val restoreRequest = registerPageRestore(key, recycler, pageIndex)
       val generation = attachmentGeneration
+      offsetDiag("recycler-enqueue", recycler, key, pageIndex, restoreRequest)
+      if (nativeSmoothHeaderScrollEnabled && recycler.height > 0 && recycler.childCount > 0) {
+        // Consume an available reading anchor before this pre-draw reaches the first frame.
+        restoreRecyclerAnchor(recycler, key, pageIndex, restoreRequest)
+      }
       recycler.post {
+        offsetDiag("recycler-execute", recycler, key, pageIndex, restoreRequest)
+        if (!isCurrentPageRestore(key, restoreRequest)) {
+          offsetDiag("recycler-post-skip-cancelled", recycler, key, pageIndex, restoreRequest)
+          return@post
+        }
         if (!isAttachedToWindow || generation != attachmentGeneration ||
           restoredRecyclerKeys[recycler] != key ||
           originalRecyclerPadding[recycler] !== original) {
           if (restoredRecyclerKeys[recycler] == key) restoredRecyclerKeys.remove(recycler)
+          clearPageRestoreForView(key, recycler, restoreRequest)
           return@post
         }
-        val saved = pageOffsets[key] ?: 0
+        val saved = restorationBodyOffset(key)
         val current = recycler.computeVerticalScrollOffset()
-        if (saved != current) recycler.scrollBy(0, saved - current)
+        offsetDiag("recycler-restore-before-saved=$saved-current=${current}-requestedDelta=${saved - current}", recycler, key, pageIndex, restoreRequest)
+        if (nativeSmoothHeaderScrollEnabled && (recycler.height <= 0 || recycler.childCount == 0)) {
+          restoredRecyclerKeys.remove(recycler)
+          if (pageRestoreRequests[key] === restoreRequest) pageRestoreRequests.remove(key)
+          return@post
+        }
+        if (nativeSmoothHeaderScrollEnabled) {
+          if (!restoreRecyclerAnchor(recycler, key, pageIndex, restoreRequest)) {
+            if (isInLayout || recycler.isInLayout || recycler.isComputingLayout) {
+              restoredRecyclerKeys.remove(recycler)
+              if (pageRestoreRequests[key] === restoreRequest) pageRestoreRequests.remove(key)
+              return@post
+            }
+            deferredRecyclerGeometry[recycler] = Triple(recycler.computeVerticalScrollRange(), recycler.computeVerticalScrollExtent(), recycler.childCount)
+            offsetDiag("recycler-anchor-pending-saved=$saved", recycler, key, pageIndex, restoreRequest)
+            return@post
+          }
+        } else if (saved != current) recycler.scrollBy(0, saved - current)
+        deferredRecyclerGeometry.remove(recycler)
+        if (nativeSmoothHeaderScrollEnabled) clearPageRestoreForView(key, recycler, restoreRequest)
+        else pendingPageRestores.remove(key)
+        offsetDiag("recycler-restore-after-saved=$saved", recycler, key, pageIndex, restoreRequest)
+        offsetDiagAfterDraw(recycler, key, pageIndex)
       }
     }
   }
@@ -949,16 +1601,35 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     val key = pageKey(pageIndex)
     if (restoredScrollerKeys[scroller] != key) {
       restoredScrollerKeys[scroller] = key
+      val restoreRequest = registerPageRestore(key, scroller, pageIndex)
       val generation = attachmentGeneration
+      offsetDiag("scrollview-enqueue", scroller, key, pageIndex, restoreRequest)
       scroller.post {
+        offsetDiag("scrollview-execute", scroller, key, pageIndex, restoreRequest)
+        if (!isCurrentPageRestore(key, restoreRequest)) {
+          offsetDiag("scrollview-post-skip-cancelled", scroller, key, pageIndex, restoreRequest)
+          return@post
+        }
         if (!isAttachedToWindow || generation != attachmentGeneration ||
           restoredScrollerKeys[scroller] != key ||
           originalScrollerPadding[scroller] !== original) {
           if (restoredScrollerKeys[scroller] == key) restoredScrollerKeys.remove(scroller)
+          clearPageRestoreForView(key, scroller, restoreRequest)
+          return@post
+        }
+        val saved = restorationBodyOffset(key)
+        offsetDiag("scrollview-restore-before-saved=$saved-current=${scroller.scrollY}-requestedDelta=${saved - scroller.scrollY}", scroller, key, pageIndex, restoreRequest)
+        if (nativeSmoothHeaderScrollEnabled &&
+          (scroller.height <= 0 || (scroller.getChildAt(0)?.height ?: 0) <= 0)) {
+          restoredScrollerKeys.remove(scroller)
+          if (pageRestoreRequests[key] === restoreRequest) pageRestoreRequests.remove(key)
           return@post
         }
-        val saved = pageOffsets[key] ?: 0
         if (scroller.scrollY != saved) scroller.scrollTo(scroller.scrollX, saved)
+        if (nativeSmoothHeaderScrollEnabled) clearPageRestoreForView(key, scroller, restoreRequest)
+        else pendingPageRestores.remove(key)
+        offsetDiag("scrollview-restore-after-saved=$saved", scroller, key, pageIndex, restoreRequest)
+        offsetDiagAfterDraw(scroller, key, pageIndex)
       }
     }
   }
@@ -1017,7 +1688,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     publishConsumedOffset(recycler, remove = true)
     val original = originalRecyclerPadding.remove(recycler) ?: return
     updateRecyclerPaddingOwnership(recycler, original)
-    restoredRecyclerKeys.remove(recycler)
+    restoredRecyclerKeys.remove(recycler)?.let { clearPageRestoreForView(it, recycler) }
     recycler.clipToPadding = original.clipToPadding
     recycler.setPadding(original.left, original.top, original.right, original.bottom)
   }
@@ -1025,7 +1696,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   private fun restoreNativeScrollerInsets(scroller: ScrollView) {
     val original = originalScrollerPadding.remove(scroller) ?: return
     updateScrollerPaddingOwnership(scroller, original)
-    restoredScrollerKeys.remove(scroller)
+    restoredScrollerKeys.remove(scroller)?.let { clearPageRestoreForView(it, scroller) }
     if (scroller is ReactScrollView) {
       val state = scroller.reactScrollViewScrollState
       scroller.setScrollAwayPaddingEnabledUnstable(
@@ -1399,6 +2070,15 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
   override fun onNestedScrollAccepted(child: View, target: View, axes: Int, type: Int) {
     if (type == ViewCompat.TYPE_TOUCH) pendingRefreshPull = null
     nestedScrollingParentHelper.onNestedScrollAccepted(child, target, axes, type)
+    if (type == ViewCompat.TYPE_TOUCH) {
+      val request = pageRestoreRequests[currentPageKey()]
+      offsetDiag("touch-cancel-before", target, request = request)
+      observedRecyclerView?.let { deferredRecyclerGeometry.remove(it) }
+      pageRestoreRequests.remove(currentPageKey())
+      pendingPageRestores.remove(currentPageKey())
+      ownedScrollerRestoreRequests.remove(currentPageKey())
+      offsetDiag("touch-cancel-after", target, request = request)
+    }
   }
 
   override fun onStopNestedScroll(target: View, type: Int) {
@@ -1415,6 +2095,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     //   val used = min(dy, headerHeightPx - headerOffsetPx)
     if (dy > 0 && headerOffsetPx < maximumOffset) {
       val used = min(dy, maximumOffset - headerOffsetPx)
+      if (type == ViewCompat.TYPE_TOUCH && used != 0) takeOverBodyForVerticalConsumption()
       setHeaderOffset(headerOffsetPx + used)
       consumed[1] += used
     } else if (dy < 0 && headerOffsetPx > 0) {
@@ -1426,6 +2107,7 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
       }
       if (!canScrollUp) {
         val used = max(dy, -headerOffsetPx)
+        if (type == ViewCompat.TYPE_TOUCH && used != 0) takeOverBodyForVerticalConsumption()
         setHeaderOffset(headerOffsetPx + used)
         consumed[1] += used
       }
@@ -1441,8 +2123,11 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     type: Int,
     consumed: IntArray,
   ) {
-    if (!isCurrentPageTarget(target) || dyUnconsumed >= 0) return
+    if (!isCurrentPageTarget(target)) return
+    if (type == ViewCompat.TYPE_TOUCH && dyConsumed != 0) takeOverBodyForVerticalConsumption()
+    if (dyUnconsumed >= 0) return
     val used = max(dyUnconsumed, -headerOffsetPx)
+    if (type == ViewCompat.TYPE_TOUCH && used != 0) takeOverBodyForVerticalConsumption()
     setHeaderOffset(headerOffsetPx + used)
     consumed[1] += used
     if (type == ViewCompat.TYPE_TOUCH && dyUnconsumed < used &&
@@ -1492,6 +2177,13 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     restoredRecyclerKeys.clear()
     restoredScrollerKeys.clear()
     viewTreeObserver.addOnPreDrawListener(pageContentLayoutListener)
+    resumeTransitionSource?.let { source ->
+      resumeTransitionSource = null
+      if (source in 0 until adapter.itemCount) {
+        pager.setCurrentItem(source, false)
+        selectPage(source)
+      }
+    }
     log(
       "host-attach generation=$attachmentGeneration inner=$selectedPage " +
         "outer=${outerPagerIndex()} nativePages=${adapter.itemCount}",
@@ -1511,6 +2203,26 @@ class CollapsiblePagerHost(context: Context) : NestedScrollableHost(context), Ne
     nestedNativeGestureStarted = false
     viewTreeObserver.removeOnPreDrawListener(pageContentLayoutListener)
     detachPrimaryScrollObserver()
+    pageRestoreRequests.clear()
+    pendingPageRestores.clear()
+    commandBodyKeys.clear()
+    explicitTopCommand = null
+    suspendedBodyKeys.clear()
+    alignedBodyKeys.clear()
+    transitionAlignedViews.clear()
+    deferredRecyclerGeometry.clear()
+    displayBodyOverrides.clear()
+    displayRecyclerAnchors.clear()
+    ownedScrollerRestoreRequests.clear()
+    transitionHeaderOffsets?.let { headers ->
+      resumeTransitionSource = transitionSourcePage
+      syntheticPageRestore = true
+      setHeaderOffset(headers[pageKey(transitionSourcePage)] ?: 0)
+      syntheticPageRestore = false
+    }
+    transitionHeaderOffsets = null
+    transitionPageOffsets = null
+    transitionTargetPage = null
     // Snapshot live keys before restoration removes their padding records.
     for (recycler in originalRecyclerPadding.keys.toTypedArray()) {
       restoreRecyclerInsets(recycler)