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

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/bottomtabs/BottomTabsPresenter.kt

@@ -6,7 +6,6 @@ import android.animation.AnimatorSet
 import android.animation.ObjectAnimator
 import android.app.Activity
 import android.graphics.Color
-import android.graphics.drawable.Drawable
 import android.view.View
 import android.view.animation.LinearInterpolator
 import android.view.animation.PathInterpolator
@@ -20,8 +19,8 @@ import dev.apexnative.navigation.options.params.LayoutDirection
 import dev.apexnative.navigation.options.params.ThemeColour
 import dev.apexnative.navigation.options.parsers.TypefaceLoader
 import dev.apexnative.navigation.system.SystemUiOwner
-import dev.apexnative.navigation.utils.ImageLoader
-import dev.apexnative.navigation.utils.ImageLoadingListenerAdapter
+import dev.apexnative.navigation.utils.ImageRequests
+import dev.apexnative.navigation.utils.OptionImages
 import dev.apexnative.navigation.utils.TestIds
 import dev.apexnative.navigation.utils.UiUtils
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
@@ -67,8 +66,9 @@ internal open class BottomTabsPresenter(activity: Activity) : Presenter(activity
 
     private var layout: BottomTabsLayout? = null
     private val typefaces = TypefaceLoader(activity)
-    private val icons = HashMap<String, Drawable>()
-    private val applied = HashMap<Pair<Int, Class<*>>, TabItems.Call>()
+    // The icons of the items by item and kind (selected or not): those of the cache at once, the others as below.
+    private val icons = ImageRequests<Pair<Int, Boolean>>(OptionImages.source(activity))
+    private val applied = AppliedTabCalls(icons::key)
     private var motion: Animator? = null
     private var anyIcon = false
     private var testId: String? = null
@@ -100,25 +100,24 @@ internal open class BottomTabsPresenter(activity: Activity) : Presenter(activity
 
     /**
      * Runs [calls] on the bar's items; a call equal to the last of its kind for its item is skipped (an icon isn't
-     * loaded and set again as a screen appears). The badge always goes: its default colors are read at each set.
+     * loaded and set again as a screen appears), except the badge and the font, an icon that didn't load and a `file:`
+     * icon whose file changed ([AppliedTabCalls]).
      */
     open fun run(calls: List<TabItems.Call>) {
         val bar = layout?.bar ?: return
         for (call in calls) {
             if (call is TabItems.Call.TestId && !itemTestIds) continue
-            val key = call.index to call.javaClass
-            if (call !is TabItems.Call.Badge && call !is TabItems.Call.Font && applied[key] == call) continue
-            applied[key] = call
-            run(bar, call)
+            val next = applied.next(call) ?: continue
+            run(bar, call, next)
         }
     }
 
-    private fun run(bar: BottomTabs, call: TabItems.Call) {
+    private fun run(bar: BottomTabs, call: TabItems.Call, next: AppliedTabCalls.Next) {
         val index = call.index
         when (call) {
             is TabItems.Call.Title -> bar.setText(index, call.text)
-            is TabItems.Call.Icon -> iconOf(call.uri)?.let { bar.setIcon(index, it) }
-            is TabItems.Call.SelectedIcon -> iconOf(call.uri)?.let { bar.setSelectedIcon(index, it) }
+            is TabItems.Call.Icon -> icon(bar, call, call.uri, false, next)
+            is TabItems.Call.SelectedIcon -> icon(bar, call, call.uri, true, next)
             is TabItems.Call.Colors -> {
                 bar.setIconActiveColor(index, call.iconActive)
                 bar.setIconInactiveColor(index, call.iconInactive)
@@ -344,17 +343,19 @@ internal open class BottomTabsPresenter(activity: Activity) : Presenter(activity
 
     private fun colorOf(colour: ThemeColour): Int? = colour.get(activity, null)
 
-    // Icons load as they apply and never throw: an icon that doesn't load leaves the item as it was.
-    private fun iconOf(uri: String): Drawable? {
-        icons[uri]?.let { return it.constantState?.newDrawable()?.mutate() ?: it }
-        var loaded: Drawable? = null
-        ImageLoader().loadIcon(activity, uri, object : ImageLoadingListenerAdapter() {
-            override fun onComplete(drawable: Drawable) {
-                loaded = drawable
-            }
-        })
-        loaded?.let { icons[uri] = it }
-        return loaded
+    // Icons never throw: one that doesn't load leaves the item without it (without its selected icon, the item shows
+    // its icon when selected). An item's first icon loads at once, its tab's first frame shows it; a change of it on
+    // the bar that shows loads off the main thread when it can, and the item takes it when ready, unless a newer icon
+    // of the item came first.
+    // The key of a `file:` icon was built for the comparison: the request takes it, its file read once.
+    private fun icon(bar: BottomTabs, call: TabItems.Call, uri: String, selected: Boolean, next: AppliedTabCalls.Next) {
+        val index = call.index
+        val key = next.image ?: icons.key(uri)
+        icons.request(index to selected, key, mayWait = next.isChange && bar.isAttachedToWindow) { icon ->
+            if (icon == null) applied.failed(call)
+            val shown = layout?.bar ?: return@request
+            if (selected) shown.setSelectedIcon(index, icon) else shown.setIcon(index, icon)
+        }
     }
 
     private companion object {

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/component/ComponentPresenter.kt

@@ -6,6 +6,7 @@ import android.graphics.drawable.ColorDrawable
 import android.graphics.drawable.Drawable
 import android.graphics.drawable.LayerDrawable
 import android.view.View
+import com.google.android.material.color.MaterialColors
 import dev.apexnative.navigation.options.DefaultOptions
 import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.options.params.ThemeColour
@@ -15,9 +16,9 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 
 /**
- * The presenter of a screen, React or native: its background — the screen's view takes `layout.backgroundColor`, kept
- * out of the status bar's height where the status bar shows over it, and the React content takes
- * `layout.componentBackgroundColor` over it —, its room for the bars, and its safe area again on `mergeOptions`
+ * The presenter of a screen, React or native: its background — the screen's view takes `layout.backgroundColor` (a
+ * React screen without it the theme's background), kept out of the status bar's height where the status bar shows over
+ * it, and the React content takes `layout.componentBackgroundColor` over it —, its room for the bars, and its safe area again on `mergeOptions`
  * (`mergeOptions` step 4). It applies as the screen appears, on `mergeOptions` of what it covers, and again with new
  * default options or after a light/dark switch from the resolved options it is given, which it never writes. Each
  * appearance tells the activity's system UI owner, which follows the screen on top. Main thread only.
@@ -49,8 +50,8 @@ open class ComponentPresenter(activity: Activity) : Presenter(activity, DefaultO
         applyBackground(controller, options)
 
     /**
-     * The colors of [screen] from its resolved [options]: `layout.backgroundColor` on the screen's view, none without
-     * it (the window shows); `layout.componentBackgroundColor` on its React content.
+     * The colors of [screen] from its resolved [options]: `layout.backgroundColor` on the screen's view, without it the
+     * theme's background for a React screen ([defaultColorOf]); `layout.componentBackgroundColor` on its React content.
      */
     fun applyBackground(screen: ViewController<*>, options: Options) {
         val view = screen.peekView() ?: return
@@ -59,11 +60,11 @@ open class ComponentPresenter(activity: Activity) : Presenter(activity, DefaultO
     }
 
     private fun screenBackground(screen: ViewController<*>, options: Options): Drawable? {
-        val color = colorOf(options.layout.backgroundColor) ?: return null
+        val color = colorOf(options.layout.backgroundColor) ?: defaultColorOf(screen) ?: return null
         val frame = frameOf(screen) ?: return ColorDrawable(color)
         val band = ScreenSafeArea.backgroundBand(
             statusBarHeight = frame.statusBarHeight,
-            hiddenOrDrawBehind = options.statusBar.isHiddenOrDrawBehind,
+            hiddenOrDrawBehind = options.statusBar.isHiddenOrDrawBehind(screen.isInOverlay),
             inSideMenu = screen.isInSideMenu,
             inSheet = screen.isInSheet,
             inPair = frame.isInPair,
@@ -79,6 +80,15 @@ open class ComponentPresenter(activity: Activity) : Presenter(activity, DefaultO
     private fun colorOf(colour: ThemeColour): Int? =
         if (colour.hasValue()) colour.get(activity, Color.TRANSPARENT) ?: Color.TRANSPARENT else null
 
+    // A React screen is opaque without a color of its own, as iOS gives it the system background: the screen under it
+    // never shows through, also while a push slides it aside. The app theme's `android:colorBackground`, read now, so a
+    // light/dark switch takes the new mode's. A screen of a sheet shows the sheet's surface; a native screen paints its
+    // own view.
+    private fun defaultColorOf(screen: ViewController<*>): Int? {
+        if (screen !is ComponentViewController || screen.isInSheet) return null
+        return themeBackgroundOf(activity)
+    }
+
     private fun frameOf(screen: ViewController<*>): ScreenFrame? = when (screen) {
         is ComponentViewController -> screen.frame
         is ExternalComponentViewController -> screen.frame
@@ -87,4 +97,15 @@ open class ComponentPresenter(activity: Activity) : Presenter(activity, DefaultO
 
     // The view under the React content: the React root, or the container of a slot screen. A native screen has none.
     private fun contentOf(screen: ViewController<*>): View? = (screen as? ComponentViewController)?.content?.asView()
+
+    internal companion object {
+        /**
+         * The background of a React screen without `layout.backgroundColor`: `android:colorBackground` of [activity]'s
+         * theme now. None for an activity without a theme (the unit tests' fakes).
+         */
+        fun themeBackgroundOf(activity: Activity): Int? {
+            if (activity.theme == null) return null
+            return MaterialColors.getColor(activity, android.R.attr.colorBackground, Color.WHITE)
+        }
+    }
 }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/component/ContentReadiness.kt

@@ -4,7 +4,7 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 
 /**
  * Whether a screen's content rendered, which a command waits for before the screen comes in: a new root (`setRoot`),
- * a push with `waitForRender: true`, the new top of a `setStackRoot`. A wait never listens to the readiness store
+ * a push (unless `waitForRender: false`), the new top of a `setStackRoot`. A wait never listens to the readiness store
  * itself: the content keeps the one listener of its id and tells every waiter. Main thread only.
  */
 internal interface Readiness {

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/component/RenderWait.kt

@@ -16,8 +16,10 @@ import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
  * without a limit.
  *
  * What differs between its users are its values, never its steps: the readiness and the clock (fakes in the unit
- * tests), [countsUnknownContent], how a readiness signal is delivered ([deliver]: at once, or posted to the next turn
- * of the main loop), and [step], the guard the user runs every later step in (a timer, a signal). Main thread only.
+ * tests), [countsUnknownContent], how a readiness signal is delivered ([deliver]: at once, posted to the next turn of
+ * the main loop, or behind the calls of JavaScript), whether content ready at once is delivered too
+ * ([deliversReadyContent]), and [step], the guard the user runs every later step in (a timer, a signal). Main thread
+ * only.
  */
 internal class RenderWait(
     private val readiness: Readiness,
@@ -32,6 +34,12 @@ internal class RenderWait(
     private val countsUnknownContent: Boolean,
     /** How a readiness signal reaches the wait: at once by default; posted, when a signal may come inside a layout. */
     private val deliver: (() -> Unit) -> Unit = { it() },
+    /**
+     * Content ready when the wait starts (or retakes) still reaches its end through [deliver], within the limit that
+     * runs: what [deliver] waits behind (a push's: the calls JavaScript made in the commit of that content) comes
+     * first. Off: such content ends the wait at once.
+     */
+    private val deliversReadyContent: Boolean = false,
     /** Runs a later step of the wait (a timer, a signal): the user's guards and protection; as it is by default. */
     private val step: (() -> Unit) -> Unit = { it() },
     private val onEnd: () -> Unit,
@@ -70,7 +78,8 @@ internal class RenderWait(
 
     /**
      * Starts waiting for [screens], and for the content of [unseen] within its first [UNSEEN_LIMIT_MILLIS]; with all
-     * of them ready (and their bars' components, when they count within the limit) it ends at once, before it returns.
+     * of them ready (and their bars' components, when they count within the limit) it ends at once, before it returns,
+     * or through [deliver] with [deliversReadyContent].
      */
     fun start(screens: List<ViewController<*>>, unseen: List<ViewController<*>> = emptyList()) {
         this.screens = screens
@@ -78,15 +87,18 @@ internal class RenderWait(
         unseenDone = unseen.isEmpty()
         waiting = true
         token = Any()
-        // Content ready at once ends the wait, unless the bar's components count within a limit: it runs for them.
-        if (contentReady() && !(bar == Bar.WithinLimit && limitMillis != null)) return contentDone()
+        // Content ready at once ends the wait, unless the bar's components count within a limit (it runs for them) or
+        // the content goes through [deliver] too.
+        val ready = contentReady()
+        if (ready && !deliversReadyContent && !(bar == Bar.WithinLimit && limitMillis != null)) return contentDone()
+        // The timers first: a [deliver] that runs at once may end the wait before this returns.
         cancelContentTimer = when {
             limitMillis != null -> scheduler.schedule(limitMillis) { step { atLimit() } }
             countsUnknownContent -> scheduler.schedule(UNKNOWN_CONTENT_MILLIS) { step { atUnknownContentLimit() } }
             else -> null
         }
         startUnseenLimit()
-        await()
+        if (ready && deliversReadyContent) deliverReady() else await()
     }
 
     /**
@@ -98,7 +110,7 @@ internal class RenderWait(
         this.screens = screens
         this.unseen = unseen
         token = Any()
-        await()
+        if (deliversReadyContent && contentReady()) deliverReady() else await()
     }
 
     /** Ends the wait without [onEnd]: its timers stop, and the signals still to come do nothing. */
@@ -129,6 +141,14 @@ internal class RenderWait(
         if (contentReady() && cancelBarPhase == null) contentDone()
     }
 
+    // The content is ready already: it goes once through [deliver] as a signal would, then on as [await] says.
+    private fun deliverReady() {
+        val token = token
+        deliver {
+            step { if (waiting && this.token === token) await() }
+        }
+    }
+
     // The content of every screen ready: on to the bars; else the signals of those not ready.
     private fun await() {
         if (contentReady()) return contentDone()

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/component/ScreenFrame.kt

@@ -143,7 +143,7 @@ internal class ScreenFrame(
             val parent = node.parentController
             val statusBar = ScreenSafeArea.statusBarRoom(
                 statusBarHeight = statusBarHeight,
-                hiddenOrDrawBehind = options.statusBar.isHiddenOrDrawBehind,
+                hiddenOrDrawBehind = options.statusBar.isHiddenOrDrawBehind(node.isInOverlay),
                 inSheet = node.isInSheet,
                 inSideMenu = node.isInSideMenu,
                 keptAround = parent?.keepsStatusBarRoomOf(node) == true,

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

@@ -1,40 +1,38 @@
 package dev.apexnative.navigation.viewcontrollers.modal
 
-import kotlin.math.PI
-import kotlin.math.cos
+import dev.apexnative.navigation.views.animations.Curves
 
 /**
- * The default animations of a modal on Android, as values: it comes up from the bottom of the window by the window's
- * height (in a split screen or a window, the window's, not the display's) and fades in, [DURATION] with a deceleration
- * at the end; it goes down and fades out in the same time, accelerating and decelerating (the system's cosine, not the
- * option's `accelerateDecelerate`). A sheet moves only by the Material sheet's own motion. Pure arithmetic.
+ * The default animations of a modal over the whole screen on Android, as values: the system's motion of a window that
+ * opens over the one below it (`activity_translucent_open_enter` and `activity_translucent_close_exit` of the
+ * platform, which Android 16 plays for a translucent activity). The modal comes up from the bottom of the window by the
+ * window's height (in a split screen or a window, the window's, not the display's) in [SHOW_DURATION], slowing down at
+ * the end; it goes down in [DISMISS_DURATION], speeding up. It doesn't fade: the screen below is seen only around it,
+ * as under a translucent activity. A sheet moves only by the Material sheet's own motion. Pure arithmetic.
  */
 internal object ModalAnimations {
-    /** How long the default show and the default dismissal last (ms). */
-    const val DURATION = 300L
+    /** How long the default show lasts (ms): `activity_translucent_open_enter`. */
+    const val SHOW_DURATION = 300L
+
+    /** How long the default dismissal lasts (ms): `activity_translucent_close_exit`. */
+    const val DISMISS_DURATION = 250L
+
+    // `linear_out_slow_in` of the platform: the path (0, 0) (0, 0) (0.2, 1) (1, 1).
+    private val linearOutSlowIn = Curves.CubicBezier(0.0, 0.0, 0.2, 1.0)
 
     /** How far a modal comes up and goes down: the window's height ([windowHeight]), or the display's while it is 0. */
     fun distance(windowHeight: Int, displayHeight: Int): Float =
         (if (windowHeight > 0) windowHeight else displayHeight).toFloat()
 
-    /** The curve of the show: a deceleration, 1 − (1 − p)². */
-    fun decelerate(progress: Float): Float = 1f - (1f - progress) * (1f - progress)
+    /** The curve of the show: the platform's `linear_out_slow_in`, fast at first and slow at the end. */
+    fun linearOutSlowIn(progress: Float): Float = linearOutSlowIn.getInterpolation(progress)
 
-    /** The curve of the dismissal: an acceleration then a deceleration, cos((p + 1)π) / 2 + 0.5. */
-    fun accelerateDecelerate(progress: Float): Float = (cos((progress + 1) * PI) / 2 + 0.5).toFloat()
+    /** The curve of the dismissal: the platform's `accelerate_quad`, p². */
+    fun accelerate(progress: Float): Float = progress.coerceIn(0f, 1f).let { it * it }
 
-    /** Where a modal is at [progress] (0 … 1, in time) of its show over [distance]: its translation and its alpha. */
-    fun show(progress: Float, distance: Float): Frame {
-        val value = decelerate(progress)
-        return Frame(translationY = distance * (1f - value), alpha = value)
-    }
+    /** Where a modal is at [progress] (0 … 1, in time) of its show over [distance]: its translation. */
+    fun show(progress: Float, distance: Float): Float = distance * (1f - linearOutSlowIn(progress))
 
     /** Where a modal is at [progress] of its dismissal over [distance], from where it rests. */
-    fun dismiss(progress: Float, distance: Float): Frame {
-        val value = accelerateDecelerate(progress)
-        return Frame(translationY = distance * value, alpha = 1f - value)
-    }
-
-    /** A modal's place in its animation. */
-    data class Frame(val translationY: Float, val alpha: Float)
+    fun dismiss(progress: Float, distance: Float): Float = distance * accelerate(progress)
 }

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)
         }
     }
@@ -668,7 +731,7 @@ internal class ModalCoordinator(
     // without the events not sent yet; what waits for it rejects, the layer it took out comes back, and the modals that
     // wait go on.
     private fun dismissFailed(record: ModalRecord, e: Throwable) {
-        val text = ErrorTexts.couldNot("dismiss the modal of the screen '${record.rootId}'", ErrorTexts.reasonOf(e))
+        val text = ErrorTexts.couldNot("dismiss the modal '${record.rootId}'", ErrorTexts.reasonOf(e))
         val listed = record in records
         val under = layerUnder(record)
         runCatching { record.stopAnimation?.invoke() }
@@ -772,8 +835,8 @@ internal class ModalCoordinator(
             State.Presenting -> record.waitingDismissals += dismissal
             State.Shown -> if (isTop(record)) beginDismissal(record, dismissal) else closeBelow(record, dismissal)
             State.Dismissing -> dismissal.answer?.let(record.answers::add)
-            State.ClosedBelow -> dismissal.answer?.resolve(record.rootId)
-            State.WithOldRoot, State.Gone -> dismissal.answer?.reject(ErrorTexts.screenNotShown(record.rootId))
+            // It went already, or goes with the old root: the dismissal just completes, as on iOS.
+            State.ClosedBelow, State.WithOldRoot, State.Gone -> dismissal.answer?.resolve(record.rootId)
         }
     }
 
@@ -787,7 +850,7 @@ internal class ModalCoordinator(
         record.state = State.Gone
         records.remove(record)
         views.remove(record)
-        val screen = AppearanceDispatcher.visibleNode(record.root)
+        val screen = AppearanceDispatcher.modalScreen(record.root)
         record.showAnswer?.resolve(record.rootId)
         record.showAnswer = null
         record.chain?.let {
@@ -949,7 +1012,7 @@ internal class ModalCoordinator(
         val wasOut = isOut(revealed)
         val counted = members.filter { it.state != State.ClosedBelow && !it.reported }
         batch.count = counted.size
-        batch.screen = counted.lastOrNull()?.let { AppearanceDispatcher.visibleNode(it.root) }
+        batch.screen = counted.lastOrNull()?.let { AppearanceDispatcher.modalScreen(it.root) }
         // The top that leaves with its animation: one already leaving keeps its own.
         val top = members.lastOrNull { it.state in ANIMATED_IN_BATCH }
         batch.top = top
@@ -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