@apexnative/navigation 1.0.0-alpha.2 → 1.0.0-alpha.4

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/StackQueue.kt

@@ -15,6 +15,7 @@ import dev.apexnative.navigation.viewcontrollers.component.Readiness
 import dev.apexnative.navigation.viewcontrollers.component.RenderWait
 import dev.apexnative.navigation.viewcontrollers.parent.OptionsScreen
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.BarMotion
+import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.BarTravel
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.BarVisibility
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.Custom
 import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.Elements
@@ -51,8 +52,12 @@ private typealias Node = ViewController<*>
  *
  * Its waits for a screen to render are the core's one wait ([RenderWait]), on the screen it pushes or sets as the top;
  * the readiness signals reach it through [deliver] (the stack posts them to the next turn of the main loop: a signal
- * that comes inside a layout pass or a view's attach moves no view of the container there). A push or a
- * `setStackRoot` with elements waits for its targets after that, a wait like the others: a cut or a replace during it
+ * that comes inside a layout pass or a view's attach moves no view of the container there). A push of a screen with
+ * React content waits for its first mount: [PUSH_WAIT_MILLIS] at most without `waitForRender`, as long as it takes
+ * with `true`, not at all with `false`; its signal reaches the wait through [afterCalls], behind the calls JavaScript
+ * made in the commit of that mount (its `mergeOptions`), so the transition starts with the options of that commit —
+ * content mounted already goes that way too. A push or a `setStackRoot` with elements waits for its targets after
+ * that, a wait like the others, within what is left of its limit without `waitForRender`: a cut or a replace during it
  * interrupts the push, which moves no view into a layer.
  *
  * The transition is the screens' own when the options say so (`AnimationRules.stackIsOwn`): the display plays each
@@ -65,18 +70,31 @@ internal class StackQueue(
     private val scheduler: AppearanceDispatcher.Scheduler,
     private val host: Host,
     private val deliver: (() -> Unit) -> Unit = { it() },
+    /**
+     * How the mount of a pushed screen reaches the push's wait: on the main thread behind every call JavaScript made
+     * before it (the stack: `PendingCalls`, on a later turn of the main loop); at once by default.
+     */
+    private val afterCalls: (() -> Unit) -> Unit = { it() },
 ) {
     /** What the queue tells the stack. */
     interface Host {
         /** The current child (the top of [shown]) changed: a transition started, or an operation ran at once. */
         fun currentChildChanged()
 
+        /** An operation was accepted: a back gesture's preview that shows ends, the stack as it was. */
+        fun operationAccepted() = Unit
+
         /**
          * The current child is about to change, right before [currentChildChanged]: [motion] is the default transition
          * the bar's row goes with, none when the change comes at once or with an animation of its own; [visibility] is
-         * how the bar shows or hides when the new top wants it otherwise.
+         * how the bar shows or hides when the new top wants it otherwise; [travel]: the bar goes with the screens of an
+         * animation of its own without elements.
          */
-        fun barTransition(motion: StackDisplay.BarMotion?, visibility: BarVisibility) = Unit
+        fun barTransition(
+            motion: StackDisplay.BarMotion?,
+            visibility: BarVisibility,
+            travel: StackDisplay.BarTravel? = null,
+        ) = Unit
 
         /**
          * The current child is about to change, right before [barTransition]: [move] is how the transition goes, which
@@ -95,10 +113,10 @@ internal class StackQueue(
         fun operationEnded(topSettled: Boolean)
 
         /**
-         * Whether [node] is a React screen with a root of its own, which a push prepares when its switch is on
-         * ([StackSwitches.preparesOwnRootPushes]).
+         * Whether [node] shows React content whose first mount its push waits for: a React screen (a root of its own or
+         * a slot), or an entry that shows one. A native screen has none: its push starts at once.
          */
-        fun isOwnRootScreen(node: Node): Boolean = false
+        fun hasReactContent(node: Node): Boolean = false
 
         /** One line for the log: a failure that has no command to answer. */
         fun log(text: String) = Unit
@@ -140,6 +158,9 @@ internal class StackQueue(
     private var takenOver = false
     private var destroyed = false
 
+    /** [node]'s content is made and nothing waits for it to render as a lower screen. */
+    fun isRendered(node: Node): Boolean = node !in unrendered && node !in lowerWaits
+
     /** The stack as JavaScript sees it, bottom to top. */
     val entries: List<Node>
         get() = entryList
@@ -199,7 +220,9 @@ internal class StackQueue(
 
     /**
      * A cut to [target], an entry that becomes the top: every entry above it leaves. [answer] gets [value]; a back of
-     * the user has none. [silent]: no animation and no appearance events (`popToRootOnBlur`).
+     * the user has none. [silent]: no animation and no appearance events (`popToRootOnBlur`). [gesture]: the release of
+     * a back gesture whose preview shows the pop already (`StackDisplay.finishBackGesture` ends it, the bar shows the
+     * target at once).
      */
     fun cut(
         target: Node,
@@ -208,6 +231,7 @@ internal class StackQueue(
         what: String,
         value: String?,
         silent: Boolean = false,
+        gesture: Boolean = false,
     ) {
         val index = entryList.indexOf(target)
         if (destroyed || index < 0) return refuse(answer, null, componentId, emptyList())
@@ -219,7 +243,7 @@ internal class StackQueue(
         (waiting as? ReplaceOp)?.let(::completeAtOnce)
         val showsAbove = target in shownList && shownList.last() !== target
         val op = if (showsAbove) {
-            CutOp(seq, answer, componentId, what, target, value, silent)
+            CutOp(seq, answer, componentId, what, target, value, silent, gesture)
         } else {
             // A cut that moves nothing more: its answer at its turn.
             NoneOp(seq, answer, null, componentId, what, value, null)
@@ -341,6 +365,8 @@ internal class StackQueue(
     // The table.
 
     private fun enqueue(op: Op) {
+        // Anything but the release of a back gesture ends its preview first.
+        if (!(op is CutOp && op.gesture)) host.operationAccepted()
         queued.addLast(op)
         drain()
     }
@@ -410,11 +436,12 @@ internal class StackQueue(
         val node = op.node
         val push = resolved(node).animations.push
         op.awaitsTargets = awaitsTargets(push, !push.enabled.isFalse)
+        // A prepared screen rendered before its push; `false`, and a node without React content, start at once.
         val wait = when {
             op.prepared -> Wait.Prepared
             push.waitForRender.isTrue -> Wait.Content
-            StackSwitches.preparesOwnRootPushes && host.isOwnRootScreen(node) -> Wait.Limited
-            else -> Wait.None
+            push.waitForRender.isFalse || !host.hasReactContent(node) -> Wait.None
+            else -> Wait.Limited
         }
         if (wait == Wait.None) return if (op.awaitsTargets) awaitTargets(op) else beginPush(op)
         waiting = op
@@ -422,18 +449,37 @@ internal class StackQueue(
             Wait.Prepared -> awaitPrepared(op)
             Wait.Content -> {
                 // Then the components of the bar drawn in advance, 0.5 s at most after the content (a title or a
-                // background with its own `waitForRender: false` not).
+                // background with its own `waitForRender: false` not). React content mounted already goes behind the
+                // calls too; a native screen starts at once.
                 display.placeWaiting(node)
-                awaitContent(op, node, limit = null, bar = RenderWait.Bar.AfterContent)
+                awaitContent(
+                    op,
+                    node,
+                    limit = null,
+                    bar = RenderWait.Bar.AfterContent,
+                    deliver = afterCalls,
+                    deliversReady = host.hasReactContent(node),
+                )
             }
             else -> {
+                // The screen renders hidden under the top, its signal (or its content mounted already) behind the
+                // calls; the bar's components don't count. The 0.5 s hold for the content and the targets together.
                 display.placeWaiting(node)
-                awaitContent(op, node, limit = OWN_ROOT_WAIT_MILLIS, bar = RenderWait.Bar.None)
+                op.cancelLimit = scheduler.schedule(PUSH_WAIT_MILLIS) { op.overLimit = true }
+                awaitContent(
+                    op,
+                    node,
+                    limit = PUSH_WAIT_MILLIS,
+                    bar = RenderWait.Bar.None,
+                    deliver = afterCalls,
+                    deliversReady = true,
+                )
             }
         }
     }
 
     private fun beginPush(op: PushOp) {
+        op.cancelLimit?.invoke()
         val node = op.node
         val covered = shownList.lastOrNull()
         // The views first: a failure here leaves the lists as they were.
@@ -450,7 +496,7 @@ internal class StackQueue(
         val elements = own && AnimationRules.hasElements(push)
         // The bar's row goes with the default transition only; with an animation of its own it changes at once. The tab
         // bar moves with its screens or by its own side.
-        tellBars(animated, own, elements, push, TabBarMotion.Move.WithPush, BarMotion.Push)
+        tellBars(animated, own, elements, push, TabBarMotion.Move.WithPush, BarMotion.Push, BarTravel.Forward)
         host.currentChildChanged()
         finishTakenOver(ended)
         running += op
@@ -488,6 +534,7 @@ internal class StackQueue(
 
     // Off screen or without a view: at once, without a transition; the top appears when the stack shows.
     private fun pushAtOnce(op: PushOp) {
+        op.cancelLimit?.invoke()
         val node = op.node
         val covered = shownList.lastOrNull()
         if (display.hasView) {
@@ -516,6 +563,7 @@ internal class StackQueue(
         if (op.done) return
         op.done = true
         if (waiting === op) stopWaiting(op)
+        op.cancelLimit?.invoke()
         queued.remove(op)
         val node = op.node
         entryList.remove(node)
@@ -581,7 +629,9 @@ internal class StackQueue(
         val animated = !atOnce && !op.silent && display.canAnimate && !pop.enabled.isFalse
         val own = animated && AnimationRules.stackIsOwn(pop)
         val elements = own && AnimationRules.hasElements(pop)
-        tellBars(animated, own, elements, pop, TabBarMotion.Move.WithPop, BarMotion.Pop)
+        // A back gesture's preview shows the target and its bar already: the bar stays as it is.
+        val gesture = op.gesture && animated && !own && leaving.size == 1 && display.hasBackPreview(top, target)
+        tellBars(animated, own, elements, pop, TabBarMotion.Move.WithPop, BarMotion.Pop, BarTravel.Back, gesture)
         host.currentChildChanged()
         finishTakenOver(ended)
         if (display.hasView) target.onViewBroughtToFront()
@@ -592,6 +642,17 @@ internal class StackQueue(
         // The screens between the top and the target leave without animation.
         leaving.drop(1).forEach(display::hide)
         if (!animated) return finishCut(op)
+        if (gesture) {
+            op.animating += top
+            op.animating += target
+            display.finishBackGesture(
+                top,
+                target,
+                { step(op) { screenDone(op, top) } },
+                { step(op) { screenDone(op, target) } },
+            )
+            return
+        }
         // Its own: no wait on a pop; the leaving screen starts from where it is.
         if (own) return animate(op, backMoves(top, target, pop, elements, moving))
         animate(op, listOf(Move(top, Motion.PopOut, true), Move(target, Motion.PopReveal, moving)))
@@ -657,7 +718,7 @@ internal class StackQueue(
         val elements = own && !op.asPush && AnimationRules.hasElements(played)
         val motion = if (op.asPush) BarMotion.Push else BarMotion.FadeThrough
         val system = if (op.asPush) TabBarMotion.Move.WithPush else TabBarMotion.Move.Slide
-        tellBars(animated, own, elements, played, system, motion)
+        tellBars(animated, own, elements, played, system, motion, BarTravel.Forward)
         host.currentChildChanged()
         finishTakenOver(ended)
         op.owned += moved
@@ -769,8 +830,16 @@ internal class StackQueue(
 
     // The one wait (RenderWait) for [screen], the node the operation brings: at [limit] the content not ready counts
     // as mounted; without one, `waitForRender: true` waits as long as it takes, except for content the readiness store
-    // knows nothing of after 1 s, which counts as ready (the same rule as iOS).
-    private fun awaitContent(op: Op, screen: Node, limit: Long?, bar: RenderWait.Bar) {
+    // knows nothing of after 1 s, which counts as ready (the same rule as iOS). A push's signals come through
+    // [afterCalls] ([deliver]); with [deliversReady], so does content ready at the start.
+    private fun awaitContent(
+        op: Op,
+        screen: Node,
+        limit: Long?,
+        bar: RenderWait.Bar,
+        deliver: (() -> Unit) -> Unit = this.deliver,
+        deliversReady: Boolean = false,
+    ) {
         val wait = RenderWait(
             readiness = readiness,
             scheduler = scheduler,
@@ -778,6 +847,7 @@ internal class StackQueue(
             bar = bar,
             countsUnknownContent = true,
             deliver = deliver,
+            deliversReadyContent = deliversReady,
             step = { work -> step(op) { work() } },
             onEnd = { endWait(op) },
         )
@@ -798,15 +868,32 @@ internal class StackQueue(
         step(op) { wait.retake(RenderWait.waitedScreens(node)) }
     }
 
+    // The prepared screen's slot mounts (or the display's limit passes), then its transition starts behind the calls
+    // JavaScript made before ([afterCalls]): a commit that came after the push (its JavaScript's own limit) brings its
+    // `mergeOptions` first. The same 0.5 s from the start hold for both: the transition starts then anyway.
     private fun awaitPrepared(op: PushOp) {
         val token = Any()
         op.waitToken = token
         val node = op.node
+        val still = { !destroyed && !op.done && op.waitToken === token && waiting === op && op.isCurrent() }
+        var mounted = false
+        val markMounted = {
+            if (!mounted && !readiness.isReady(node)) readiness.markReady(node)
+            mounted = true
+        }
+        val start = { step(op) { if (still()) endWait(op) } }
+        op.cancelCap = scheduler.schedule(PUSH_WAIT_MILLIS) {
+            step(op) {
+                if (!still()) return@step
+                markMounted()
+                endWait(op)
+            }
+        }
         display.awaitPrepared(
             node,
-            waiting = { !destroyed && !op.done && op.waitToken === token && waiting === op && op.isCurrent() },
-            mounted = { step(op) { if (!readiness.isReady(node)) readiness.markReady(node) } },
-            start = { step(op) { if (waiting === op) endWait(op) } },
+            waiting = still,
+            mounted = { step(op) { markMounted() } },
+            start = { afterCalls(start) },
         )
     }
 
@@ -835,7 +922,8 @@ internal class StackQueue(
         val token = Any()
         op.waitToken = token
         val still = { !destroyed && !op.done && op.waitToken === token && waiting === op && op.isCurrent() }
-        // Without `waitForRender` a `setStackRoot`'s 0.5 s holds for its content and its targets together.
+        // Without `waitForRender` the 0.5 s of a `setStackRoot` and of a push of React content hold for the content
+        // and the targets together.
         val from = currentChild
         op.stopTargets = display.awaitTargets(animation, from, to, { still() && !op.overLimit }) {
             step(op) { if (still()) endWait(op) }
@@ -844,6 +932,8 @@ internal class StackQueue(
 
     private fun stopWaiting(op: Op) {
         if (waiting === op) waiting = null
+        op.cancelCap?.invoke()
+        op.cancelCap = null
         op.waitToken = null
         op.wait?.cancel()
         op.wait = null
@@ -1081,9 +1171,10 @@ internal class StackQueue(
     private fun awaitsTargets(animation: StackAnimationOptions, enabled: Boolean): Boolean = enabled &&
         display.canAnimate && !animation.waitForRender.isFalse && AnimationRules.hasElements(animation)
 
-    // The bars with a change of the current child. The row goes with the default transition only; the tab bar rides
-    // with the system's [system] move, slides with an animation of its own or a side of its own, and is where the new
-    // top wants it at once without animation; with elements every bar changes at once.
+    // The bars with a change of the current child. The row goes with the default transition; with an animation of its
+    // own the top bar goes with the screens ([travel]). The tab bar rides with the system's [system] move, slides with an
+    // animation of its own or a side of its own, and is where the new top wants it at once without animation; with
+    // elements every bar changes at once.
     private fun tellBars(
         animated: Boolean,
         own: Boolean,
@@ -1091,6 +1182,9 @@ internal class StackQueue(
         animation: StackAnimationOptions,
         system: TabBarMotion.Move,
         row: BarMotion,
+        travel: BarTravel,
+        // The top bar shows the new top already (a back gesture's preview): it changes at once, the tab bar still moves.
+        barAtOnce: Boolean = false,
     ) {
         val tabs = animation.bottomTabs
         val tabsSide = AnimationRules.barSideGiven(tabs.enter) || AnimationRules.barSideGiven(tabs.exit)
@@ -1100,7 +1194,12 @@ internal class StackQueue(
             else -> system
         }
         host.tabBarTransition(move, tabs.takeIf { move == TabBarMotion.Move.Slide })
-        host.barTransition(if (animated && !own) row else null, barVisibility(animated && !elements, animation.topBar))
+        val barMoves = animated && !barAtOnce
+        host.barTransition(
+            if (barMoves && !own) row else null,
+            barVisibility(barMoves && !elements, animation.topBar),
+            travel.takeIf { barMoves && own && !elements },
+        )
     }
 
     private fun barVisibility(animated: Boolean, side: TopBarEnterExitAnimationOptions): BarVisibility =
@@ -1179,9 +1278,12 @@ internal class StackQueue(
         // It waits for its elements' targets after its content; what stops that wait.
         var awaitsTargets = false
         var stopTargets: (() -> Unit)? = null
-        // The limit of a `setStackRoot` without `waitForRender` passed: its targets get nothing of it any more.
+        // The limit of a `setStackRoot` or a push without `waitForRender` passed: its targets get nothing of it any
+        // more.
         var overLimit = false
         var cancelLimit: (() -> Unit)? = null
+        // The limit of a prepared push's wait, which ends with the wait.
+        var cancelCap: (() -> Unit)? = null
         // Its screen came by an animation of its own: it stays at that animation's end values.
         var keepsEnd = false
         // The listener of a module heard its answer: it hears one only.
@@ -1209,6 +1311,7 @@ internal class StackQueue(
         val target: Node,
         val value: String?,
         val silent: Boolean,
+        val gesture: Boolean,
     ) : Op(seq, answer, null, componentId, what) {
         var leaving: List<Node> = emptyList()
     }
@@ -1255,20 +1358,13 @@ internal class StackQueue(
         /** How long a lower screen stays placed in the container to make its content, at most. */
         const val LOWER_SCREEN_MILLIS = 500L
 
-        /** How long the push of a screen with its own root waits for its content, with the switch on. */
-        const val OWN_ROOT_WAIT_MILLIS = 500L
+        /**
+         * How long a push waits for its screen's first mount without `waitForRender`, and a prepared push for its slot
+         * and the calls before it.
+         */
+        const val PUSH_WAIT_MILLIS = 500L
 
         // The alpha an arriving screen shows with: its own at rest, never the 0 of its wait.
         private const val ARRIVING_ALPHA = 1f
     }
 }
-
-/**
- * The internal switches of the stack. [preparesOwnRootPushes]: the push of a React screen with a root of its own starts
- * its surface hidden in the stack at its size and insets, and starts its transition once the content rendered, 0.5 s at
- * most. Off by default («б»: the push starts at once); it is measured at the end on a phone.
- */
-internal object StackSwitches {
-    @Volatile
-    var preparesOwnRootPushes = false
-}

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/StackTransitions.kt

@@ -16,11 +16,15 @@ import dev.apexnative.navigation.views.animations.SystemTransition
  * system's transition between activities (`SystemTransition`: 96 dp along the axis in 450 ms on
  * `fast_out_extra_slow_in`, mirrored right to left), `setStackRoot` is Material's fade through (`FadeThrough`). What
  * leaves starts from where it is; what comes in on a push is hidden explicitly until it fades in, as a delay doesn't
- * apply an animator's first value. Main thread only.
+ * apply an animator's first value. The system's windows also extend their edge by the distance they move
+ * ([extendsStart], `StackLayout.extendEdge`). Main thread only.
  */
 internal object StackTransitions {
-    /** The animator of [view] for [motion]; [fromCurrent] for a screen taken over from a transition still running. */
-    fun animator(view: View, motion: Motion, fromCurrent: Boolean): Animator {
+    /**
+     * The animator of [view] for [motion]; [fromCurrent] for a screen taken over from a transition still running.
+     * [onSlide] runs at each frame of its slide.
+     */
+    fun animator(view: View, motion: Motion, fromCurrent: Boolean, onSlide: () -> Unit = {}): Animator {
         val distance = SystemTransition.DISTANCE_DP * view.resources.displayMetrics.density
         // Forward is to the end of the line: right to left, the screens move the other way. The stack's view inherits
         // the app's direction, which `layout.direction` sets on the activity's content (`AppDirection`).
@@ -30,24 +34,37 @@ internal object StackTransitions {
                 view.translationX = forward
                 view.alpha = 0f
                 together(
-                    slide(view, 0f),
+                    slide(view, 0f, onSlide),
                     fade(view, 1f, SystemTransition.PUSH_FADE_DELAY),
                 )
             }
-            Motion.PushCover -> slide(view, -forward)
+            Motion.PushCover -> slide(view, -forward, onSlide)
             Motion.PopOut -> together(
-                slide(view, forward),
+                slide(view, forward, onSlide),
                 fade(view, 0f, SystemTransition.POP_FADE_DELAY),
             )
             Motion.PopReveal -> {
                 if (!fromCurrent) view.translationX = -forward
-                if (view.alpha < 1f) together(slide(view, 0f), fade(view, 1f, 0L)) else slide(view, 0f)
+                if (view.alpha < 1f) together(slide(view, 0f, onSlide), fade(view, 1f, 0L)) else slide(view, 0f, onSlide)
             }
             Motion.FadeIn -> FadeThrough.enter(view)
             Motion.FadeOut -> FadeThrough.exit(view)
         }
     }
 
+    /**
+     * Whether a screen moving by [motion] extends its start edge (the side it moves away from on a push in and a pop
+     * out), its end edge (a push cover, a pop reveal), or none (a fade through: null), as the system's windows do.
+     */
+    fun extendsStart(motion: Motion): Boolean? = when (motion) {
+        Motion.PushIn, Motion.PopOut -> true
+        Motion.PushCover, Motion.PopReveal -> false
+        Motion.FadeIn, Motion.FadeOut -> null
+    }
+
+    /** Whether [motion] animates the screen's alpha: it draws through a hardware layer meanwhile. */
+    fun fades(motion: Motion): Boolean = motion != Motion.PushCover && motion != Motion.PopReveal
+
     /**
      * The fade of a screen around elements: in from 0 to 1, out from where it is to 0, linearly in
      * [AnimationRules.SCREEN_FADE]; none for [Fade.None].
@@ -65,10 +82,11 @@ internal object StackTransitions {
         }
     }
 
-    private fun slide(view: View, to: Float): Animator =
+    private fun slide(view: View, to: Float, onFrame: () -> Unit): Animator =
         ObjectAnimator.ofFloat(view, View.TRANSLATION_X, view.translationX, to).apply {
             duration = SystemTransition.DURATION
             interpolator = SystemTransition.CURVE
+            addUpdateListener { onFrame() }
         }
 
     private fun fade(view: View, to: Float, delay: Long): Animator =

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/stack/StackViews.kt

@@ -9,6 +9,7 @@ import androidx.core.view.WindowInsetsCompat
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleOwner
 import dev.apexnative.navigation.options.LayoutAnimation
+import dev.apexnative.navigation.utils.UiThread
 import dev.apexnative.navigation.utils.whenContentMounted
 import dev.apexnative.navigation.viewcontrollers.component.ComponentViewController
 import dev.apexnative.navigation.viewcontrollers.externalcomponent.ExternalComponentViewController
@@ -16,6 +17,7 @@ import dev.apexnative.navigation.viewcontrollers.stack.StackDisplay.Motion
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
+import dev.apexnative.navigation.views.animations.SystemTransition
 import dev.apexnative.navigation.views.element.ElementTransition
 import dev.apexnative.navigation.views.element.TargetsWait
 import dev.apexnative.navigation.views.stack.StackLayout
@@ -29,6 +31,11 @@ import dev.apexnative.navigation.views.stack.StackLayout
  */
 internal class StackViews(private val stack: StackController) : StackDisplay {
     private val animators = HashMap<ViewController<*>, Animator>()
+    // The preview of the back gesture that runs or ends now, and its two screens.
+    private var preview: BackPreview? = null
+    private var previewScreens: Pair<ViewController<*>, ViewController<*>>? = null
+    // The ends of the two screens of a released gesture whose preview plays its end.
+    private var committing: Pair<() -> Unit, () -> Unit>? = null
     // What goes back when a screen's animator ends or stops: the elements its transition carries.
     private val cleanups = HashMap<ViewController<*>, () -> Unit>()
 
@@ -110,11 +117,16 @@ internal class StackViews(private val stack: StackController) : StackDisplay {
     override fun animate(screen: ViewController<*>, motion: Motion, fromCurrent: Boolean, done: () -> Unit) {
         stop(screen)
         val view = screen.peekView() ?: return done()
-        val animator = StackTransitions.animator(view, motion, fromCurrent)
+        val layout = layout
+        val animator = StackTransitions.animator(view, motion, fromCurrent) { layout?.edgesMoved() }
+        cleanups[screen] = dress(view, motion, layout)
         animator.addListener(object : AnimatorListenerAdapter() {
             // Ended or cancelled by anything else than [stop]: the screen's part is done.
             override fun onAnimationEnd(animation: Animator) {
-                if (animators[screen] === animator) animators.remove(screen)
+                if (animators[screen] === animator) {
+                    animators.remove(screen)
+                    cleanups.remove(screen)?.invoke()
+                }
                 done()
             }
         })
@@ -122,6 +134,21 @@ internal class StackViews(private val stack: StackController) : StackDisplay {
         animator.start()
     }
 
+    // For the default transition [view] moves as the system's windows do: its edge extended by the distance it moves,
+    // and its fade drawn through a hardware layer, so the whole screen isn't drawn again at every frame of it. What
+    // undoes both.
+    private fun dress(view: View, motion: Motion, layout: StackLayout?): () -> Unit {
+        StackTransitions.extendsStart(motion)?.let { start ->
+            layout?.extendEdge(view, start, (SystemTransition.DISTANCE_DP * view.resources.displayMetrics.density).toInt())
+        }
+        val layered = StackTransitions.fades(motion) && view.layerType == View.LAYER_TYPE_NONE
+        if (layered) view.setLayerType(View.LAYER_TYPE_HARDWARE, null)
+        return {
+            layout?.dropEdge(view)
+            if (layered && view.layerType == View.LAYER_TYPE_HARDWARE) view.setLayerType(View.LAYER_TYPE_NONE, null)
+        }
+    }
+
     // The elements go into a layer over the screens, and back as the screen's animator ends or stops. A shared element
     // without a duration takes the screen's fade: its own single `alpha`, else 300 ms.
     override fun animateCustom(screen: ViewController<*>, custom: StackDisplay.Custom, done: () -> Unit) {
@@ -167,7 +194,83 @@ internal class StackViews(private val stack: StackController) : StackDisplay {
         done: () -> Unit,
     ): () -> Unit = TargetsWait.start(animation, from, to, waiting, done)
 
+    /**
+     * Starts the preview of a back gesture over [top], [target] under it (`BackPreview`): none without the stack's view
+     * or a window. [onReveal] shows [target] and its bar as the preview's picture is there.
+     */
+    fun startBackPreview(
+        top: ViewController<*>,
+        target: ViewController<*>,
+        fromLeft: Boolean,
+        touchY: Float,
+        onReveal: () -> Unit,
+    ): BackPreview? {
+        val bottomRoom = top.getBottomInset()
+        endPreview()
+        val layout = layout ?: return null
+        val window = stack.activity.window ?: return null
+        val topView = top.peekView() ?: return null
+        val targetView = target.peekView() ?: return null
+        val started = BackPreview(layout, topView, targetView, fromLeft, touchY, bottomRoom, onReveal)
+        preview = started
+        previewScreens = top to target
+        started.start(window)
+        return started
+    }
+
+    /** The preview of the back gesture went: cancelled and put back, or never shown. */
+    fun previewEnded(ended: BackPreview) {
+        if (preview !== ended) return
+        preview = null
+        previewScreens = null
+    }
+
+    override fun hasBackPreview(top: ViewController<*>, target: ViewController<*>): Boolean =
+        preview?.isReady == true && previewScreens == top to target
+
+    override fun finishBackGesture(
+        top: ViewController<*>,
+        target: ViewController<*>,
+        topDone: () -> Unit,
+        targetDone: () -> Unit,
+    ) {
+        val running = preview?.takeIf { hasBackPreview(top, target) } ?: run {
+            topDone()
+            targetDone()
+            return
+        }
+        committing = topDone to targetDone
+        running.commit {
+            committing = null
+            previewEnded(running)
+            topDone()
+            targetDone()
+        }
+    }
+
+    private fun endPreview() {
+        val ended = preview ?: return
+        preview = null
+        previewScreens = null
+        committing = null
+        ended.endAtOnce()
+    }
+
+    // A later transition takes one screen of a released gesture's preview: the preview ends where it is, the popped
+    // screen stays out of sight until the pop takes it away, and the other screen's part ends on the next turn.
+    private fun stopPreview(screen: ViewController<*>) {
+        val (top, target) = previewScreens ?: return
+        if (screen !== top && screen !== target) return
+        val dones = committing
+        endPreview()
+        if (dones == null) return
+        top.peekView()?.alpha = 0f
+        val other = if (screen === top) dones.second else dones.first
+        UiThread.post { other() }
+    }
+
     override fun stop(screen: ViewController<*>) {
+        stopPreview(screen)
         val animator = animators.remove(screen)
         if (animator != null) {
             animator.removeAllListeners()
@@ -185,8 +288,8 @@ internal class StackViews(private val stack: StackController) : StackDisplay {
         screen.whenContentMounted(
             waiting = waiting,
             mounted = {
-                // The frame of the mount: the screen shows transparent and lays out; its transition starts on the
-                // pre-draw of that frame.
+                // The frame of the mount: the screen shows transparent and lays out. The pre-draw of that frame hands
+                // the start to the queue, whose transition begins behind the calls JavaScript made before.
                 screen.peekView()?.let {
                     it.alpha = 0f
                     it.visibility = View.VISIBLE