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

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalCoordinator.kt

@@ -261,6 +261,54 @@ internal class ModalCoordinator(
         }
     }
 
+    /**
+     * A modal of a `setRoot`'s layout made with the root, before its turn: it joins the modals layer and renders
+     * unseen while the root waits and comes in, held — it doesn't show, and commands and back don't count it — until
+     * [release]; [animated] as in [showInChain]. A failure is logged, and nothing is made (null).
+     */
+    fun hold(id: String, make: () -> ViewController<*>, animated: Boolean): ModalRecord? = try {
+        start(make, null, ModalRecord.Chain(animated) {}, held = true)
+    } catch (e: Throwable) {
+        val reason = ErrorTexts.reasonOf(e)
+        host.log("[ApexNavigation] setRoot: ${ErrorTexts.couldNot("show the screen '$id'", reason)}")
+        null
+    }
+
+    /**
+     * The turn of a [hold]'s modal in its `setRoot`'s chain: it shows as soon as it rendered, as [showInChain]'s
+     * would, with [done] once it showed or went; at once when it went meanwhile. The function returned stops it while
+     * it waits.
+     */
+    fun release(record: ModalRecord, done: () -> Unit): () -> Unit {
+        if (!record.held || record.state != State.Waiting) {
+            done()
+            return {}
+        }
+        record.chain = ModalRecord.Chain(record.chain?.animated ?: true, done)
+        record.held = false
+        guarded(record) {
+            host.backChanged()
+            // Rendered while held: the targets of its elements are in the layer under it only now.
+            if (record.isReady && !record.targetsAwaited && awaitsTargets(record)) {
+                record.isReady = false
+                awaitTargets(record)
+            } else {
+                presentReady()
+            }
+        }
+        return {
+            record.chain = null
+            if (record.state == State.Waiting) cancel(record, null, reports = false)
+        }
+    }
+
+    /** A [hold]'s modal whose `setRoot` ended before its turn: it goes without a word. */
+    fun drop(record: ModalRecord) {
+        if (!record.held) return
+        record.chain = null
+        if (record.state == State.Waiting) cancel(record, null, reports = false)
+    }
+
     /**
      * `dismissModal` after its shared steps: the record of [componentId], Android's rule of the last modal without a
      * root, [options] merged into the modal's visible screen, the animation of the command's screen with its parents
@@ -279,6 +327,7 @@ internal class ModalCoordinator(
             State.ClosedBelow -> return answer.resolve(record.rootId)
             else -> Unit
         }
+        if (record.held) return answer.reject(ErrorTexts.screenNotShown(componentId))
         if (isLastWithoutRoot(record)) return answer.reject(ErrorTexts.modalWithoutRoot(componentId))
         options?.let { mergeInto(record, it) }
         val from = node?.takeUnless { it.isDestroyed } ?: record.root
@@ -293,7 +342,7 @@ internal class ModalCoordinator(
      * before anything changes, with the id of the top modal's visible screen.
      */
     fun dismissAll(options: Options?, unreadablePath: String?, answer: CommandAnswer) {
-        val members = records.filter { it.batch == null && it.state in BATCHED }
+        val members = records.filter { it.batch == null && !it.held && it.state in BATCHED }
         if (members.isEmpty()) {
             // Nothing else to take: the second one answers with the running batch (N6), else at once.
             val running = batches.lastOrNull()
@@ -347,6 +396,12 @@ internal class ModalCoordinator(
         return true
     }
 
+    /**
+     * The root of the modal that back goes to first; none without one. A back gesture previews only a pop in it: its
+     * dismissal has a preview of its own nowhere yet.
+     */
+    fun backTargetRoot(): ViewController<*>? = backTarget()?.root
+
     /** The mirror of [handleBack], without acting; null without a modal to ask. */
     fun canHandleBack(): Boolean? {
         val record = backTarget() ?: return null
@@ -422,6 +477,8 @@ internal class ModalCoordinator(
         }
         batches.clear()
         for (record in records.toList()) {
+            // A modal of the new root's layout, made with it, stays: it shows over the new root in its turn.
+            if (record.held) continue
             if (record.state == State.Waiting) {
                 cancel(record, null, reports = false)
                 continue
@@ -432,7 +489,7 @@ internal class ModalCoordinator(
             views.carry(record, old)
             carried += record
         }
-        records.clear()
+        records.retainAll { it.held }
         host.backChanged()
     }
 
@@ -482,7 +539,12 @@ internal class ModalCoordinator(
 
     // The show (3, 4).
 
-    private fun start(make: () -> ViewController<*>, answer: CommandAnswer?, chain: ModalRecord.Chain?): ModalRecord {
+    private fun start(
+        make: () -> ViewController<*>,
+        answer: CommandAnswer?,
+        chain: ModalRecord.Chain?,
+        held: Boolean = false,
+    ): ModalRecord {
         val root = make()
         val record: ModalRecord
         val options: Options
@@ -492,6 +554,7 @@ internal class ModalCoordinator(
             val sheet = ModalRecord.isSheet(options)
             root.shownAsSheet = sheet
             record = ModalRecord(root, sheet)
+            record.held = held
         } catch (e: Throwable) {
             root.destroy()
             throw e
@@ -555,7 +618,7 @@ internal class ModalCoordinator(
     private fun ready(record: ModalRecord) {
         if (record.state != State.Waiting) return
         record.wait = null
-        if (!record.targetsAwaited && awaitsTargets(record)) return awaitTargets(record)
+        if (!record.targetsAwaited && !record.held && awaitsTargets(record)) return awaitTargets(record)
         record.cancelLimit()
         record.isReady = true
         presentReady()
@@ -607,7 +670,7 @@ internal class ModalCoordinator(
         if (taking) return
         for (record in records.toList()) {
             if (record.state != State.Waiting) continue
-            if (!record.isReady) return
+            if (record.held || !record.isReady) return
             present(record)
         }
     }
@@ -1156,13 +1219,16 @@ internal class ModalCoordinator(
 
     // A record is the top when no record above it waits, comes in or shows; one that leaves doesn't count.
     private fun isTop(record: ModalRecord): Boolean =
-        records.drop(records.indexOf(record) + 1).none { it.effective in TOP_STATES }
+        records.drop(records.indexOf(record) + 1).none(::countsAsTop)
 
     // The top record, as the commands see it; none.
-    private fun topRecord(): ModalRecord? = records.lastOrNull { it.effective in TOP_STATES }
+    private fun topRecord(): ModalRecord? = records.lastOrNull(::countsAsTop)
 
     // Back goes to the top modal that waits, comes in or shows.
-    private fun backTarget(): ModalRecord? = records.lastOrNull { it.effective in TOP_STATES }
+    private fun backTarget(): ModalRecord? = records.lastOrNull(::countsAsTop)
+
+    // A record that waits, comes in or shows; a held one doesn't count before its turn.
+    private fun countsAsTop(record: ModalRecord): Boolean = !record.held && record.effective in TOP_STATES
 
     // `hardwareBackButton.dismissModalOnPress: false` of the modal's options now.
     private fun holdsBack(record: ModalRecord): Boolean =

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalRecord.kt

@@ -17,7 +17,10 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 internal class ModalRecord(
     /** The top node of the modal's layout. */
     val root: ViewController<*>,
-    /** The modal shows as a Material sheet (`modal.sheet`), decided before its root's view is made. */
+    /**
+     * The modal shows as a Material sheet (`pageSheet`, `formSheet`, `popover`, or `modal.sheet` without a style),
+     * decided before its root's view is made.
+     */
     val isSheet: Boolean,
 ) : WaitingLayer {
     /** Where the modal is. */
@@ -78,6 +81,12 @@ internal class ModalRecord(
     /** Its wait ended: it shows once every older waiting modal showed or went (N1). */
     var isReady = false
 
+    /**
+     * A modal of a `setRoot`'s layout made with the root, before its turn: it renders unseen while the root waits and
+     * comes in, and neither shows nor counts for commands or back until its step of the chain lets it go.
+     */
+    var held = false
+
     /** The wait for its screens while it waits. */
     var wait: RenderWait? = null
 
@@ -160,14 +169,20 @@ internal class ModalRecord(
         /** `modalPresentationStyle` values that keep the layer under in place. */
         private val OVER_STYLES = setOf("overFullScreen", "overCurrentContext")
 
-        /** The styles a sheet shows with: unset, `pageSheet`, `formSheet`. */
-        private val SHEET_STYLES = setOf(null, "pageSheet", "formSheet")
+        /**
+         * The styles that always show as a sheet: the sheets of iOS, and the popover, which an iPhone shows as a sheet
+         * too.
+         */
+        private val SHEET_STYLES = setOf("pageSheet", "formSheet", "popover")
 
         /**
-         * Whether a modal with [options] (resolved, with the defaults) shows as a sheet: any `modal.sheet` field set,
-         * and the style unset, `pageSheet` or `formSheet`.
+         * Whether a modal with [options] (resolved, with the defaults) shows as a sheet: its style is `pageSheet`,
+         * `formSheet` or `popover`, or it has none and any `modal.sheet` field is set.
          */
-        fun isSheet(options: Options): Boolean = options.modal.sheet.hasValue && styleOf(options) in SHEET_STYLES
+        fun isSheet(options: Options): Boolean {
+            val style = styleOf(options)
+            return style in SHEET_STYLES || (style == null && options.modal.sheet.hasValue)
+        }
 
         /**
          * Whether a modal covers the layer under it at the end of its show: full screen, unless it is a sheet or

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalSheet.kt

@@ -29,11 +29,12 @@ import dev.apexnative.navigation.utils.dp
 import kotlin.math.roundToInt
 
 /**
- * A modal shown as a Material bottom sheet (`modal.sheet`): the modal's view in a container with a
- * [BottomSheetBehavior], in the modals' CoordinatorLayout, over a scrim. It stops at the detents of its options —
- * `medium` at half the height, `large` at the full height under the status bar, a number at that height in dp — and the
- * user drags it between them. A drag down past the smallest one closes it, unless `swipeToDismiss` is false: then the
- * sheet stays, and the try is told. The screen under it stays in place.
+ * A modal shown as a Material bottom sheet (`pageSheet`, `formSheet`, `popover`, or `modal.sheet` without a style): the
+ * modal's view in a container with a [BottomSheetBehavior], in the modals' CoordinatorLayout, over a scrim. It stops at
+ * the detents of its options — `medium` at half the height, `large` at the full height under the status bar, a number
+ * at that height in dp — and the user drags it between them. In a window wider than [MAX_WIDTH_DP] it stands in the
+ * middle at that width. A drag down past the smallest one closes it, unless `swipeToDismiss` is false: then the sheet
+ * stays, and the try is told. The screen under it stays in place.
  */
 internal class ModalSheet(
     private val layout: CoordinatorLayout,
@@ -96,11 +97,19 @@ internal class ModalSheet(
                 outline.setRoundRect(0, 0, view.width, view.height + radius.roundToInt(), radius)
             }
         }
-        // The sheet is under the status bar: its screens leave no room for it at their top.
+        // The sheet is under the status bar: its screens leave no room for it at their top. In the middle of a wide
+        // window it reaches no side, and keeps room only for the part of a side bar that is over it.
         ViewCompat.setOnApplyWindowInsetsListener(container) { _, insets ->
             val types = WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout()
             val bars = insets.getInsets(types)
-            WindowInsetsCompat.Builder(insets).setInsets(types, Insets.of(bars.left, 0, bars.right, bars.bottom)).build()
+            val laidOut = container.width > 0
+            val left = if (laidOut) (bars.left - container.left).coerceAtLeast(0) else bars.left
+            val right = if (laidOut) (bars.right - (layout.width - container.right)).coerceAtLeast(0) else bars.right
+            WindowInsetsCompat.Builder(insets).setInsets(types, Insets.of(left, 0, right, bars.bottom)).build()
+        }
+        // Its sides move with the window's width (a rotation, a resize): the room for the side bars follows.
+        container.addOnLayoutChangeListener { _, left, _, right, _, oldLeft, _, oldRight, _ ->
+            if (left != oldLeft || right != oldRight) container.post { ViewCompat.requestApplyInsets(container) }
         }
         container.addView(content, FrameLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT))
         container.addView(grabber, FrameLayout.LayoutParams(WRAP_CONTENT, WRAP_CONTENT, Gravity.TOP or Gravity.CENTER_HORIZONTAL))
@@ -120,7 +129,12 @@ internal class ModalSheet(
         layout.addView(scrim, CoordinatorLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT))
         // As tall as its largest detent (maxHeight), not moved down by a margin: the behavior counts its states from
         // where the sheet is laid out.
-        layout.addView(container, CoordinatorLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT).also { it.behavior = behavior })
+        // In a wide window it stands in the middle, as wide as a Material modal sheet at most.
+        behavior.maxWidth = MAX_WIDTH_DP.dp
+        val params = CoordinatorLayout.LayoutParams(MATCH_PARENT, MATCH_PARENT)
+        params.gravity = Gravity.TOP or Gravity.CENTER_HORIZONTAL
+        params.behavior = behavior
+        layout.addView(container, params)
         shown = onShown
         update(sheetOptions, swipeToDismiss, merge = null)
         selected = sheetOptions.selectedDetent?.takeIf { it in detents }
@@ -334,10 +348,13 @@ internal class ModalSheet(
         }
     }
 
-    private companion object {
+    companion object {
+        /** The widest a sheet is, in dp: the Material modal bottom sheet's `maxWidth`. */
+        const val MAX_WIDTH_DP = 640
+
         /** The dim of a Material modal bottom sheet's scrim. */
-        const val SCRIM_ALPHA = 0.32f
-        const val GRAB_AREA_DP = 48
-        const val ATTEMPT_DISTANCE_DP = 48
+        private const val SCRIM_ALPHA = 0.32f
+        private const val GRAB_AREA_DP = 48
+        private const val ATTEMPT_DISTANCE_DP = 48
     }
 }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/modal/ModalViews.kt

@@ -4,9 +4,9 @@ import android.animation.Animator
 import android.animation.AnimatorListenerAdapter
 import android.animation.AnimatorSet
 import android.animation.ObjectAnimator
-import android.animation.PropertyValuesHolder
 import android.animation.TimeInterpolator
 import android.content.Context
+import android.view.Gravity
 import android.view.View
 import android.view.ViewGroup
 import android.view.animation.LinearInterpolator
@@ -17,6 +17,7 @@ import androidx.core.view.WindowInsetsCompat
 import dev.apexnative.navigation.options.ModalAnimationOptions
 import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.utils.TestIds
+import dev.apexnative.navigation.utils.dp
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
@@ -62,9 +63,15 @@ internal class ModalViews(
         try {
             val view = record.root.view
             (view.parent as? ViewGroup)?.removeView(view)
-            // A sheet's content waits at the sheet's full height, under the status bar.
+            // A sheet's content waits at the sheet's full height, under the status bar, and at its width.
             val params = CoordinatorLayout.LayoutParams(MATCH, MATCH)
-            if (record.isSheet) params.topMargin = statusBarTop()
+            if (record.isSheet) {
+                params.topMargin = statusBarTop()
+                params.gravity = Gravity.CENTER_HORIZONTAL
+                // The modals layer is hidden while it has no modal: the window's content gives the width.
+                val maxWidth = ModalSheet.MAX_WIDTH_DP.dp
+                if (((modalsLayer.parent as? View)?.width ?: 0) > maxWidth) params.width = maxWidth
+            }
             container.addView(view, params)
             modalsLayer.addView(container, FrameLayout.LayoutParams(MATCH, MATCH))
         } catch (e: Throwable) {
@@ -100,14 +107,13 @@ internal class ModalViews(
             container.translationY = 0f
             return playOwn(record, parts, motion, showing = true, onEnd)
         }
+        // The system's slide over the window below: the modal comes up whole, without a fade.
         val distance = distanceOf(container)
-        val animator = ObjectAnimator.ofPropertyValuesHolder(
-            container,
-            PropertyValuesHolder.ofFloat(View.TRANSLATION_Y, distance, 0f),
-            PropertyValuesHolder.ofFloat(View.ALPHA, 0f, 1f),
-        )
-        animator.interpolator = TimeInterpolator { ModalAnimations.decelerate(it) }
-        return play(parts, animator, onEnd)
+        container.alpha = 1f
+        container.translationY = distance
+        val animator = ObjectAnimator.ofFloat(container, View.TRANSLATION_Y, distance, 0f)
+        animator.interpolator = TimeInterpolator { ModalAnimations.linearOutSlowIn(it) }
+        return play(parts, animator, ModalAnimations.SHOW_DURATION, onEnd)
     }
 
     // The root's view leaves the container and goes into the sheet's, in one turn; the sheet slides to its first
@@ -163,13 +169,11 @@ internal class ModalViews(
         if (!animated || !seen) return none(onEnd)
         if (motion != null) return playOwn(record, parts, motion, showing = false, onEnd)
         val container = parts.container
-        val animator = ObjectAnimator.ofPropertyValuesHolder(
-            container,
-            PropertyValuesHolder.ofFloat(View.TRANSLATION_Y, container.translationY, distanceOf(container)),
-            PropertyValuesHolder.ofFloat(View.ALPHA, container.alpha, 0f),
+        val animator = ObjectAnimator.ofFloat(
+            container, View.TRANSLATION_Y, container.translationY, distanceOf(container),
         )
-        animator.interpolator = TimeInterpolator { ModalAnimations.accelerateDecelerate(it) }
-        return play(parts, animator, onEnd)
+        animator.interpolator = TimeInterpolator { ModalAnimations.accelerate(it) }
+        return play(parts, animator, ModalAnimations.DISMISS_DURATION, onEnd)
     }
 
     override fun awaitTargets(
@@ -355,8 +359,8 @@ internal class ModalViews(
     private fun viewOf(node: ViewController<*>): View? =
         parts.entries.firstOrNull { it.key.root === node }?.value?.container ?: node.peekView()
 
-    private fun play(parts: Parts, animator: Animator, onEnd: () -> Unit): () -> Unit {
-        animator.duration = ModalAnimations.DURATION
+    private fun play(parts: Parts, animator: Animator, duration: Long, onEnd: () -> Unit): () -> Unit {
+        animator.duration = duration
         animator.addListener(object : AnimatorListenerAdapter() {
             override fun onAnimationEnd(animation: Animator) {
                 if (parts.animator === animation) parts.animator = null

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/navigator/BackCallbackState.kt

@@ -41,6 +41,10 @@ internal object BackCallbackState {
         entries.removeAll { it.navigator.get().let { attached -> attached == null || attached === navigator } }
     }
 
+    /** JavaScript listens to back (`BackHandler`): it hears a press before the navigation does. */
+    val hasJsListeners: Boolean
+        get() = jsListeners
+
     /** `setBackListeners` of JavaScript; false again when its JavaScript goes. */
     fun setJsListeners(active: Boolean) {
         jsListeners = active

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/navigator/Navigator.kt

@@ -31,6 +31,7 @@ import dev.apexnative.navigation.viewcontrollers.component.ContentReadiness
 import dev.apexnative.navigation.viewcontrollers.component.ScreenReadiness
 import dev.apexnative.navigation.viewcontrollers.externalcomponent.ExternalComponentViewController
 import dev.apexnative.navigation.viewcontrollers.modal.ModalCoordinator
+import dev.apexnative.navigation.viewcontrollers.modal.ModalRecord
 import dev.apexnative.navigation.viewcontrollers.modal.ModalViews
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayCoordinator
 import dev.apexnative.navigation.viewcontrollers.overlay.OverlayRecord
@@ -38,6 +39,7 @@ import dev.apexnative.navigation.viewcontrollers.overlay.OverlayViews
 import dev.apexnative.navigation.viewcontrollers.parent.ParentController
 import dev.apexnative.navigation.viewcontrollers.stack.PreparedPushes
 import dev.apexnative.navigation.viewcontrollers.stack.StackCommands
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.stack.topbar.BarComponents
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.animations.FadeThrough
@@ -153,6 +155,15 @@ class Navigator(
     fun handleBack(listener: CommandListener): Boolean =
         modals.handleBack(listener) ?: (root?.handleBack(listener) == true)
 
+    /**
+     * The stack whose top [handleBack] would take away with the default pop: in the top modal, else in the root; none
+     * when back would do anything else.
+     */
+    internal fun stackPoppedByBack(): StackController? {
+        val modalRoot = modals.backTargetRoot()
+        return if (modalRoot != null) modalRoot.stackPoppedByBack() else root?.stackPoppedByBack()
+    }
+
     /**
      * [layer] may wait to show from now on ([WaitingLayer]): the nodes in it ask it through [isInWaitingLayer] and
      * [shownScreensChanged]. The root's layer is there from the start.
@@ -264,9 +275,7 @@ class Navigator(
         if (!made) return answer.reject(ErrorTexts.notDoneYet("setRoot"))
         val steps = layout.modals.mapIndexed { index, node ->
             val last = index == layout.modals.lastIndex
-            RootCoordinator.LayerStep { done ->
-                modals.showInChain(node.id, { makeLayer(node, isOverlay = false) }, last, done)
-            }
+            ModalLayerStep(node, last)
         } + layout.overlays.map { node ->
             RootCoordinator.LayerStep { done ->
                 overlays.showInChain(node.id, { makeLayer(node, isOverlay = true) }, done)
@@ -275,6 +284,35 @@ class Navigator(
         roots.setRoot({ factory.create(layout.root) }, answer, steps)
     }
 
+    // A modal of a `setRoot`'s layout: made with the root and held until its turn, so it renders while the root waits
+    // and comes in; made in its turn instead while an id of it still shows (a modal of the old root with that id goes
+    // with the old root). A modal that couldn't be made is skipped in its turn.
+    private inner class ModalLayerStep(private val node: LayoutNode, private val animated: Boolean) :
+        RootCoordinator.LayerStep {
+        private var prepared = false
+        private var held: ModalRecord? = null
+
+        override fun prepare() {
+            if (LayoutChecks.firstShownId(listOf(node), ::isShownNow) { false } != null) return
+            prepared = true
+            held = modals.hold(node.id, { factory.create(node) }, animated)
+        }
+
+        override fun discard() {
+            held?.let(modals::drop)
+            held = null
+        }
+
+        override fun show(done: () -> Unit): () -> Unit {
+            val record = held
+            held = null
+            if (record != null) return modals.release(record, done)
+            if (!prepared) return modals.showInChain(node.id, { makeLayer(node, isOverlay = false) }, animated, done)
+            done()
+            return {}
+        }
+    }
+
     // A modal or an overlay of a `setRoot`'s layout, made as its turn comes: an id that shows by then fails it.
     private fun makeLayer(node: LayoutNode, isOverlay: Boolean): ViewController<*> {
         val shown = LayoutChecks.firstShownId(listOf(node), ::isShownNow) { isOverlay && isReplacedOverlay(node, it) }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/navigator/RootCoordinator.kt

@@ -36,7 +36,8 @@ import dev.apexnative.navigation.views.animations.AnimationRules
  * The modals over the old root ([ModalsOverRoot]): taken as the `setRoot` is accepted (commands don't find them), given
  * back when it ends without replacing the root, carried with the old root into its transition and destroyed with it,
  * without `ANN.ModalDismissed`. The modals and the overlays of the layout ([LayerStep]) show after the root, one by
- * one, before the answer: a newer `setRoot` stops them.
+ * one, before the answer: a newer `setRoot` stops them. Its modals are made with the root ([LayerStep.prepare]) and
+ * render unseen while it waits and comes in, so each shows in its turn without a wait of its own.
  *
  * The steps that come later (the wait's timers and readiness signals, the end of the transition, the end of a layer,
  * a stack of the waiting root that changed its top) run under no runner: each goes through one guard, and a failure
@@ -128,11 +129,20 @@ internal class RootCoordinator(
     }
 
     /**
-     * A modal or an overlay of the layout of a `setRoot`, shown after its root: [show] makes it and shows it, and calls
-     * its argument once it showed or went (a failure is logged and skipped); what it returns stops it while it waits —
-     * a newer `setRoot`: it goes without a word.
+     * A modal or an overlay of the layout of a `setRoot`, shown after its root: [show] shows it (made then, unless
+     * [prepare] made it), and calls its argument once it showed or went (a failure is logged and skipped); what it
+     * returns stops it while it waits — a newer `setRoot`: it goes without a word.
      */
     fun interface LayerStep {
+        /**
+         * Right after the root is placed, before its wait: a step may make its layer now, so that it renders unseen
+         * while the root waits and comes in, and shows without a wait of its own in its turn.
+         */
+        fun prepare() = Unit
+
+        /** The `setRoot` ended before this step's turn: what [prepare] made goes without a word. */
+        fun discard() = Unit
+
         fun show(done: () -> Unit): () -> Unit
     }
 
@@ -221,6 +231,7 @@ internal class RootCoordinator(
             modals.rootAccepted()
             val waitForRender = animationsOf(root).enter.waitForRender
             this.pending = pending
+            layers.forEach { it.prepare() }
             firstRoot.rootSet(waitForRender)
             await(pending, waitForRender)
         }
@@ -367,6 +378,14 @@ internal class RootCoordinator(
         if (!done) pending.stopLayer = stop
     }
 
+    // The layers of [pending] not shown yet go: what they made ahead goes unseen, the others aren't made. Each on its
+    // own: one that fails doesn't keep the others.
+    private fun discardLayers(pending: Pending) {
+        val rest = pending.layers.drop(pending.nextLayer)
+        pending.nextLayer = pending.layers.size
+        rest.forEach { attempt { it.discard() } }
+    }
+
     // A new `setRoot` came while this one was on its way.
     private fun supersede() {
         val pending = pending ?: return
@@ -389,14 +408,15 @@ internal class RootCoordinator(
                 pending.replaced = null
                 modals.replacedRootGone()
             }
-            // Its root is the current root: the modal or the overlay that waits now goes without a word, the others
-            // aren't made; those shown stay over its root, and go with it when the new root replaces it.
+            // Its root is the current root: the modal or the overlay that waits now goes without a word, the others go
+            // unseen or aren't made; those shown stay over its root, and go with it when the new root replaces it.
             Phase.Layers -> {
                 pending.stopLayer?.invoke()
                 pending.stopLayer = null
                 releaseState(pending)
             }
         }
+        discardLayers(pending)
         pending.answer.reject(ErrorTexts.setRootReplaced(pending.root.id))
     }
 
@@ -426,6 +446,7 @@ internal class RootCoordinator(
         pending.wait = null
         when (pending.phase) {
             Phase.Waiting -> {
+                discardLayers(pending)
                 attempt { takeAway(pending.root) }
                 attempt { modals.rootKept() }
                 attempt { firstRoot.rootDestroyed() }
@@ -451,6 +472,7 @@ internal class RootCoordinator(
                 pending.stopLayer = null
             }
         }
+        discardLayers(pending)
         // A root that is up takes the splash away, as at its show.
         if (pending.phase != Phase.Waiting) attempt { onRootShown() }
         attempt { releaseState(pending) }
@@ -482,6 +504,7 @@ internal class RootCoordinator(
     // The root was destroyed while it waited, by something other than a newer `setRoot` or the activity going.
     private fun rootGone(pending: Pending) {
         this.pending = null
+        discardLayers(pending)
         releaseState(pending)
         layer.remove(pending.root)
         modals.rootKept()

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/overlay/OverlayCoordinator.kt

@@ -185,6 +185,8 @@ internal class OverlayCoordinator(
 
     private fun start(make: () -> ViewController<*>, answer: CommandAnswer?, chainDone: (() -> Unit)?): OverlayRecord {
         val root = make()
+        // Before the root's view is made: its screens are drawn under the status bar from their first layout.
+        root.shownAsOverlay = true
         val record = OverlayRecord(root)
         // A waiting layer before its views join the window: what is in it isn't on screen from its first layout.
         record.screensChanged = { screensChanged(record) }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/parent/ContainerBackground.kt

@@ -31,9 +31,9 @@ internal object ContainerBackground {
         if (!colour.hasValue()) return null
         val color = colour.get(node.activity, Color.TRANSPARENT) ?: Color.TRANSPARENT
         // The screens' band rule (`ScreenSafeArea.backgroundBand`) for a layout, which keeps no room at its top: the
-        // status bar's height, but none when it is hidden or the layout is drawn under it, in a side menu, a sheet or
-        // a pair.
-        val full = options.statusBar.isHiddenOrDrawBehind || node.isInSideMenu || node.isInSheet ||
+        // status bar's height, but none when it is hidden or the layout is drawn under it (in an overlay by default),
+        // in a side menu, a sheet or a pair.
+        val full = options.statusBar.isHiddenOrDrawBehind(node.isInOverlay) || node.isInSideMenu || node.isInSheet ||
             node.parentController is KeepsStatusBarRoom
         val band = if (full) 0 else SystemUiUtils.getStatusBarHeight(node.activity)
         if (band <= 0) return ColorDrawable(color)

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/parent/ParentController.kt

@@ -8,6 +8,7 @@ import dev.apexnative.navigation.react.CommandListener
 import dev.apexnative.navigation.viewcontrollers.bottomtabs.TabBarMotion
 import dev.apexnative.navigation.viewcontrollers.child.ChildController
 import dev.apexnative.navigation.viewcontrollers.child.ChildControllersRegistry
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.stack.fab.FabPlacement
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
@@ -210,6 +211,8 @@ abstract class ParentController<V : ViewGroup>(
 
     override fun canHandleBack(): Boolean = getCurrentChild()?.canHandleBack() == true
 
+    override fun stackPoppedByBack(): StackController? = getCurrentChild()?.stackPoppedByBack()
+
     override fun destroy() {
         if (isDestroyed) return
         getChildControllers().forEach { it.destroy() }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/sidemenu/SideMenuController.kt

@@ -16,6 +16,7 @@ import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.parent.ChildOffsetFromRest
 import dev.apexnative.navigation.viewcontrollers.parent.ParentController
 import dev.apexnative.navigation.viewcontrollers.sidemenu.SideMenuMotion.Side
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.sidemenu.SideMenuView
@@ -183,6 +184,9 @@ internal class SideMenuController(
 
     override fun canHandleBack(): Boolean = motion.canGoBack || center.canHandleBack()
 
+    // An open menu closes first: no preview of a pop then.
+    override fun stackPoppedByBack(): StackController? = if (motion.canGoBack) null else center.stackPoppedByBack()
+
     // A button's press addressed to the side menu goes to the center.
     override fun sendOnNavigationButtonPressed(buttonId: String) = center.sendOnNavigationButtonPressed(buttonId)
 

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/splitview/SplitViewController.kt

@@ -26,8 +26,8 @@ import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.parent.ChildOffsetFromRest
 import dev.apexnative.navigation.viewcontrollers.parent.ParentController
 import dev.apexnative.navigation.viewcontrollers.parent.ReturnsScreenFromColumn
-import dev.apexnative.navigation.viewcontrollers.parent.ShowsColumns
 import dev.apexnative.navigation.viewcontrollers.parent.ShownChildren
+import dev.apexnative.navigation.viewcontrollers.parent.ShowsColumns
 import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
@@ -366,6 +366,19 @@ class SplitViewController(
         return can || super.canHandleBack()
     }
 
+    // As handleBack: the pane whose back goes first decides; an open sliding pane that would close previews nothing.
+    override fun stackPoppedByBack(): StackController? {
+        if (!isViewCreated) return super.stackPoppedByBack()
+        val layout = getView()
+        return when {
+            layout.isCompact -> compact?.stackPoppedByBack()
+            isSliding && !layout.panes.isOpen -> primary.stackPoppedByBack()
+            isSliding -> if (secondary.canHandleBack()) secondary.stackPoppedByBack() else null
+            secondary.canHandleBack() -> secondary.stackPoppedByBack()
+            else -> primary.stackPoppedByBack()
+        }
+    }
+
     /**
      * How far the pane of [child] is from where it rests: the secondary pane sliding over the primary one rests over
      * it, closed or on its way. Zero for the other children.