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

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/ScreenReadiness.kt

@@ -1,93 +1,128 @@
 package dev.apexnative.navigation.viewcontrollers.component
 
 /**
- * The readiness of each screen by its id: the safe area view of a screen (`ANNSafeAreaView`) tells it here that it is
- * laid out in its place and that the screen's content rendered into it, and asks whether the screen waits for that at
- * all. The screen's container listens by the screen's id: no view walks up or down the views to find the other. Main
- * thread only.
+ * The readiness of each screen by its id: the safe area view of a screen (`ANNSafeAreaView`) tells it here that it
+ * has one, that it is laid out in its place and that the screen's content rendered into it, and asks whether the
+ * screen waits for that at all. The content of a screen or of a component listens by the id: no view walks up or down
+ * the views to find the other. Main thread only.
+ *
+ * As on iOS (`ANNScreenReadiness`), what a safe area view said is kept: a listener that comes later hears it at once.
+ * Several listeners may wait on one id (the roots of a bar component that several screens show with one id), each
+ * under a key of its own, which removes it. Each signal carries its source, the React surface of the safe area view
+ * that gave it, and a listener hears only the sources it [accepts][Listener.accepts]: React Native never gives a
+ * surface's id twice in a process, so the late signal of another root with the same id (a root of the JavaScript that
+ * went, a destroyed screen, another live root of a bar component) never makes a new root ready.
  */
 object ScreenReadiness {
-    /** What a screen's container hears from the safe area view of its screen. */
+    /** The source of a signal that names none: a listener that accepts every source hears it. */
+    const val NO_SOURCE = -1
+
+    /** What the content of a screen or of a component hears from the safe area view of its id. */
     interface Listener {
+        /**
+         * Whether a signal of [source] (the id of the React surface of the safe area view that gave it) is this
+         * listener's: by default every one is.
+         */
+        fun accepts(source: Int): Boolean = true
+
         /** The safe area view is laid out in its place, with a size. */
-        fun onLaidOut()
+        fun onLaidOut() = Unit
 
         /** The screen rendered its content into its safe area view, also when it renders nothing (`null`). */
         fun onContentRendered()
     }
 
-    private val atOnce = HashSet<String>()
-    private val wrapped = HashSet<String>()
-    private val laidOut = HashSet<String>()
-    private val rendered = HashSet<String>()
-    private val listeners = HashMap<String, Listener>()
+    // What the safe area views of one id said: that one exists, and the sources that are laid out and rendered.
+    private class Entry {
+        var wrapped = false
+        val laidOut = HashSet<Int>()
+        val rendered = HashSet<Int>()
+    }
+
+    private val entries = HashMap<String, Entry>()
+    private val listeners = HashMap<String, LinkedHashMap<Any, Listener>>()
+    // The roots that render at once, by id: an id renders at once while one of them lives.
+    private val atOnce = HashMap<String, MutableSet<Any>>()
 
     /**
      * Whether the screen [screenId] waits for its safe area view to be laid out before its content renders: every
-     * screen does, as on iOS, unless the core marked it as one that renders at once ([setRendersAtOnce]) — a React
-     * component of a bar or a tab item, whose size comes from its content.
+     * screen does, as on iOS, unless a root of the id renders at once ([setRendersAtOnce]) — a React component of a
+     * bar or a tab item, whose size comes from its content.
      */
-    fun waitsForReadiness(screenId: String): Boolean = screenId !in atOnce
+    fun waitsForReadiness(screenId: String): Boolean = atOnce[screenId].isNullOrEmpty()
 
-    /** The core marks a React root it made as one that renders at once (a component of a bar, a tab item), or not. */
-    fun setRendersAtOnce(screenId: String, rendersAtOnce: Boolean) {
-        if (rendersAtOnce) atOnce += screenId else atOnce -= screenId
+    /**
+     * The root [key] of [screenId] renders at once (a component of a bar, a tab item), or stopped. The id renders at
+     * once while a root marks it; when the last one stops, what was said of the id goes too, so a later root with it
+     * starts anew.
+     */
+    fun setRendersAtOnce(screenId: String, key: Any, rendersAtOnce: Boolean) {
+        if (rendersAtOnce) {
+            atOnce.getOrPut(screenId, ::HashSet).add(key)
+            return
+        }
+        val keys = atOnce[screenId] ?: return
+        if (!keys.remove(key) || keys.isNotEmpty()) return
+        atOnce.remove(screenId)
+        entries.remove(screenId)
     }
 
     /** The screen [screenId] has a safe area view: it is rendered only once that view says so. */
     fun wrapped(screenId: String) {
-        wrapped += screenId
+        entryOf(screenId).wrapped = true
     }
 
-    /** The safe area view of [screenId] is laid out in its place, with a size. */
-    fun laidOut(screenId: String) {
-        if (laidOut.add(screenId)) listeners[screenId]?.onLaidOut()
+    /** The safe area view of [screenId], in the React surface [source], is laid out in its place, with a size. */
+    fun laidOut(screenId: String, source: Int = NO_SOURCE) {
+        val entry = entryOf(screenId)
+        entry.wrapped = true
+        if (entry.laidOut.add(source)) tell(screenId, source, Listener::onLaidOut)
     }
 
-    /** The screen [screenId] rendered its content into its safe area view. */
-    fun contentRendered(screenId: String) {
-        if (rendered.add(screenId)) listeners[screenId]?.onContentRendered()
+    /** The screen [screenId] rendered its content into its safe area view, in the React surface [source]. */
+    fun contentRendered(screenId: String, source: Int = NO_SOURCE) {
+        val entry = entryOf(screenId)
+        entry.wrapped = true
+        if (entry.rendered.add(source)) tell(screenId, source, Listener::onContentRendered)
     }
 
     /**
-     * Whether the screen [screenId] rendered its content into its safe area view; null when no safe area view told
-     * anything of it (a screen without one, of the old API: its container decides by its own content).
+     * Whether the screen [screenId] rendered its content into its safe area view, in a source [listener] accepts (any
+     * source without one); null when no safe area view told anything of the id (a screen without one, of the old API:
+     * its content decides by its own children).
      */
-    fun isContentRendered(screenId: String): Boolean? = when (screenId) {
-        in rendered -> true
-        in laidOut, in wrapped -> false
-        else -> null
-    }
-
-    /** [listener] hears the signals of [screenId] from now on; null stops it. */
-    fun setListener(screenId: String, listener: Listener?) {
-        if (listener == null) listeners.remove(screenId) else listeners[screenId] = listener
+    fun isContentRendered(screenId: String, listener: Listener? = null): Boolean? {
+        val entry = entries[screenId] ?: return null
+        return entry.rendered.any { listener?.accepts(it) ?: true }
     }
 
     /**
-     * [listener] stops hearing [screenId], if it is the one that listens: a later screen with the same id (a `setRoot`
-     * makes the new root before the old one goes) keeps its own.
+     * [listener] hears the signals of [screenId] under [key] (its owner) until [removeListener] with the key: a key
+     * has one listener per id, the other keys keep theirs. What the safe area views said before reaches it at once, in
+     * order, for the sources it accepts.
      */
-    fun removeListener(screenId: String, listener: Listener) {
-        if (listeners[screenId] === listener) listeners.remove(screenId)
+    fun addListener(screenId: String, key: Any, listener: Listener) {
+        listeners.getOrPut(screenId, ::LinkedHashMap)[key] = listener
+        val entry = entries[screenId] ?: return
+        if (entry.laidOut.any(listener::accepts) && isListening(screenId, key, listener)) listener.onLaidOut()
+        if (entry.rendered.any(listener::accepts) && isListening(screenId, key, listener)) listener.onContentRendered()
     }
 
-    /**
-     * A new root takes [screenId] while another with it lives (a component of a bar on two screens): what the other
-     * rendered isn't the new one's, which waits for its own render. Its mark of rendering at once stays.
-     */
-    fun forgetRender(screenId: String) {
-        laidOut -= screenId
-        rendered -= screenId
+    /** The listener of [key] stops hearing [screenId]; those of other keys (a later root with the id) keep theirs. */
+    fun removeListener(screenId: String, key: Any) {
+        val keys = listeners[screenId] ?: return
+        keys.remove(key)
+        if (keys.isEmpty()) listeners.remove(screenId)
     }
 
-    /** The screen is destroyed: what was kept of it goes, so a later screen with the same id starts anew. */
+    /**
+     * The screen [screenId] owns the id from now on (made), or went while no other node has it (destroyed): what its
+     * safe area views said and the marks of rendering at once go, so a later screen with the id starts anew. The
+     * listeners stay with their keys, which remove them.
+     */
     fun remove(screenId: String) {
-        atOnce -= screenId
-        wrapped -= screenId
-        laidOut -= screenId
-        rendered -= screenId
-        listeners -= screenId
+        entries.remove(screenId)
+        atOnce.remove(screenId)
     }
 
     /**
@@ -95,10 +130,22 @@ object ScreenReadiness {
      * "rendered" kept for a screen of the old one would make its new screen with the same id ready at once.
      */
     fun reset() {
-        atOnce.clear()
-        wrapped.clear()
-        laidOut.clear()
-        rendered.clear()
+        entries.clear()
         listeners.clear()
+        atOnce.clear()
+    }
+
+    private fun entryOf(screenId: String): Entry = entries.getOrPut(screenId, ::Entry)
+
+    private fun isListening(screenId: String, key: Any, listener: Listener): Boolean =
+        listeners[screenId]?.get(key) === listener
+
+    // Each listener of the id that accepts the source, as they are now: one that a listener before it removed hears
+    // nothing.
+    private fun tell(screenId: String, source: Int, signal: (Listener) -> Unit) {
+        val now = listeners[screenId]?.entries?.toList() ?: return
+        for ((key, listener) in now) {
+            if (isListening(screenId, key, listener) && listener.accepts(source)) signal(listener)
+        }
     }
 }

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

@@ -731,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() }
@@ -835,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)
         }
     }
 
@@ -850,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 {
@@ -1012,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

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

@@ -0,0 +1,50 @@
+package dev.apexnative.navigation.viewcontrollers.navigator
+
+import android.util.Log
+import dev.apexnative.navigation.utils.NavigationLog
+
+/**
+ * The check of [BackCallbackState]'s triggers in debug builds (`NavigationActivity` makes it only when
+ * `BuildConfig.DEBUG`): it compares an activity's back callback with what back does now
+ * ([BackCallbackState.mismatchOf]) and writes a mismatch to the log once per state, with the screen on top. It never
+ * changes the callback, so a missing trigger behaves as in a release build. A [sample] before a frame runs at most
+ * every [SAMPLE_MILLIS] and reports a mismatch only when the sample before saw the same one: a change whose trigger
+ * comes at the end of its motion (a pane that slides, a menu dragged open) isn't reported while it moves. A back event
+ * ([atBack]) reports at once. Main thread only.
+ */
+internal class BackCallbackCheck(
+    private val log: (String) -> Unit = { Log.w(NavigationLog.TAG, it) },
+) {
+    private var lastSample: Long? = null
+    private var previous: String? = null
+    private val logged = HashSet<String>()
+
+    /** Before a frame of the activity of [navigator], at [now] (`SystemClock.uptimeMillis`). */
+    fun sample(navigator: Navigator, now: Long) {
+        val last = lastSample
+        if (last != null && now - last < SAMPLE_MILLIS) return
+        lastSample = now
+        val mismatch = BackCallbackState.mismatchOf(navigator)
+        if (mismatch != null && mismatch == previous) report(mismatch)
+        previous = mismatch
+    }
+
+    /** A back event reached the callback of the activity of [navigator], before it acts. */
+    fun atBack(navigator: Navigator) {
+        BackCallbackState.mismatchOf(navigator)?.let(::report)
+    }
+
+    // Once per state, and not without end.
+    private fun report(mismatch: String) {
+        if (logged.size >= MAX_LOGGED || !logged.add(mismatch)) return
+        log("[ApexNavigation] $mismatch: a change of what back does came without its trigger")
+    }
+
+    companion object {
+        /** The least time between two samples. */
+        const val SAMPLE_MILLIS = 500L
+
+        // The states logged at most: a debug check, not a second log.
+        private const val MAX_LOGGED = 32
+    }
+}

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

@@ -2,21 +2,38 @@ package dev.apexnative.navigation.viewcontrollers.navigator
 
 import android.util.Log
 import androidx.activity.OnBackPressedCallback
+import dev.apexnative.navigation.react.events.AppearanceDispatcher
 import dev.apexnative.navigation.utils.NavigationLog
 import java.lang.ref.WeakReference
 
 /**
  * Keeps the back callback of each navigation activity enabled only while back has something to do in the app: its
- * navigation can go back ([Navigator.canHandleBack]), or JavaScript listens to it (`BackHandler`). Otherwise the
- * callback is disabled and the system does its own back. The system plays its back animation (to the home screen, to
- * another task) only when no callback of the app is enabled as the gesture starts, and it decides that before the app
- * hears of the gesture.
+ * navigation can go back ([Navigator.canHandleBack]), the screen back acts on keeps it from the system
+ * (`hardwareBackButton.systemAnimation: false`, [Navigator.keepsBackFromSystem]), or JavaScript listens to it
+ * (`BackHandler`). Otherwise the callback is disabled and the system does its own back. The system plays its back
+ * animation (to the home screen, to another task) only when no callback of the app is enabled as the gesture starts,
+ * and it decides that before the app hears of the gesture.
  *
  * A stale "enabled" only loses that animation; a stale "disabled" would leave the app where back has to go back. So
- * the value is computed again whenever what back does can have changed: before each frame of the activity's window,
- * when a command is done, when JavaScript reports its listeners, and when a side menu, the panes of a split view or a
- * search open or close (the first two after their last frame). Each activity has its own navigator and callback; the
- * listeners of JavaScript count for all of them. Main thread only.
+ * the value is computed again on every event that can change what back does, never by walking the layouts before
+ * each frame:
+ * - the end of each command's main-thread task, `setDefaultOptions` and `mergeOptions` too (`CommandRunner`);
+ * - a stack's operation accepted, its current child changed, and the operation ended or rejected
+ *   (`StackController`'s queue host), which covers a push or a `setStackRoot` that waited for its screen, a prepared
+ *   push, back of the user and the back arrow;
+ * - a layout that changed the screens it shows (`Navigator.shownScreensChanged`: the tabs, a side menu, a split view,
+ *   a pair) and the end of a tab's switch;
+ * - every change of the modals (`ModalCoordinator.Host.backChanged`): a show, a dismissal by a command, by back or by
+ *   the user (a sheet dragged down, its scrim), a failure, a `setRoot` that takes them;
+ * - a root that changed or showed, and the layers that went (a reload: `Navigator.destroy`);
+ * - a side menu, the panes of a split view or a search that opened or closed (the first two after their last frame),
+ *   and a split view's width that changed;
+ * - the release and the cancel of a back gesture, and each back press;
+ * - JavaScript's listeners ([setJsListeners]), and the activity resumed or focused, as a safety net.
+ *
+ * Overlays don't count: back never goes to them. Each activity has its own navigator and callback; the listeners of
+ * JavaScript count for all of them. Debug builds check the triggers ([mismatchOf], `BackCallbackCheck`). Main thread
+ * only.
  */
 internal object BackCallbackState {
     private class Entry(navigator: Navigator, callback: OnBackPressedCallback) {
@@ -56,22 +73,36 @@ internal object BackCallbackState {
         for (entry in entries.toList()) update(entry)
     }
 
-    /** The callback of the activity of [navigator]: before its frames and at its back presses. */
+    /** The callback of the activity of [navigator]: after a change in its navigation. */
     fun update(navigator: Navigator) {
         entries.firstOrNull { it.navigator.get() === navigator }?.let(::update)
     }
 
+    /**
+     * Debug builds only: a callback of [navigator]'s activity that differs from what back does now — a change without
+     * its trigger —, described with the screen on top; null when it is right or not attached. It changes nothing.
+     */
+    fun mismatchOf(navigator: Navigator): String? {
+        val callback = entries.firstOrNull { it.navigator.get() === navigator }?.callback?.get() ?: return null
+        val expected = jsListeners || takesBack(navigator)
+        if (callback.isEnabled == expected) return null
+        val top = navigator.visibleLayout?.let { AppearanceDispatcher.visibleNode(it).id } ?: "none"
+        val state = if (callback.isEnabled) "enabled" else "disabled"
+        val back = if (expected) "back stays in the app" else "back leaves the app"
+        return "the back callback is $state where $back (on top: '$top')"
+    }
+
     // Enables or disables the callback when what back does changed.
     private fun update(entry: Entry) {
         val callback = entry.callback.get() ?: return
-        val enabled = jsListeners || canHandleBack(entry.navigator.get())
+        val enabled = jsListeners || takesBack(entry.navigator.get())
         if (callback.isEnabled != enabled) callback.isEnabled = enabled
     }
 
-    // A layout that fails to answer leaves back to the navigation, as before: this runs before each frame, and an
-    // exception here would end the app.
-    private fun canHandleBack(navigator: Navigator?): Boolean = try {
-        navigator?.canHandleBack() == true
+    // A layout that fails to answer leaves back to the navigation, as before: this runs from the triggers of layouts
+    // and animators, and an exception here would end the app.
+    private fun takesBack(navigator: Navigator?): Boolean = try {
+        navigator != null && (navigator.canHandleBack() || navigator.keepsBackFromSystem())
     } catch (e: RuntimeException) {
         if (!failureLogged) {
             failureLogged = true

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

@@ -40,7 +40,6 @@ 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
 import dev.apexnative.navigation.views.animations.SideAnimator
@@ -105,7 +104,10 @@ class Navigator(
         readiness = ContentReadiness,
         scheduler = scheduler,
         firstRoot = firstRootDraw,
-        onRootChanged = { root = it },
+        onRootChanged = {
+            root = it
+            BackCallbackState.update(this)
+        },
         onRootShown = {
             onRootShown?.invoke()
             BackCallbackState.update(this)
@@ -142,10 +144,21 @@ class Navigator(
 
     /**
      * Whether back has something to do in the navigation: the mirror of [handleBack], without acting — the top modal
-     * first, then the root. The back callback asks it before each frame (`BackCallbackState`).
+     * first, then the root. The back callback asks it whenever what back does can have changed (`BackCallbackState`).
      */
     fun canHandleBack(): Boolean = modals.canHandleBack() ?: (root?.canHandleBack() == true)
 
+    /**
+     * Whether back stays in the app also when the navigation has nothing to do: the layout back acts on — the top
+     * modal's, else the root — shows a screen with `hardwareBackButton.systemAnimation: false`. The system then doesn't
+     * play its animation of going home, and the press does the activity's own back ([handleBack] is false). The back
+     * callback asks it with [canHandleBack] (`BackCallbackState`).
+     */
+    fun keepsBackFromSystem(): Boolean {
+        val layout = modals.backTargetRoot() ?: root ?: return false
+        return layout.resolveShownOptions(DefaultOptions.current).hardwareBackButton.systemAnimation.isFalse
+    }
+
     /**
      * The navigation's step of back, after JavaScript's listeners didn't take it: the top modal first (its content,
      * else it closes or holds), else the root does the first thing it can (a stack's top leaves or holds, an open side
@@ -187,12 +200,14 @@ class Navigator(
      * A layout of [node] (a stack, the tabs, a side menu, a split view, a pair) changed the screens it shows: when it
      * is in a layer that still waits, the layer waits for the screens it shows now, and no longer for one that went
      * ([WaitingLayer.shownScreensChanged]); so does the operation of its stack that waits for [node] as its entry (a
-     * pushed pair); a modal's sheet takes the hold of the screen it shows now.
+     * pushed pair); a modal's sheet takes the hold of the screen it shows now; what back does is computed again (the
+     * tab, the pane or the menu back goes to, and the options of the screen it shows).
      */
     internal fun shownScreensChanged(node: ViewController<*>) {
         waitingLayerOf(node)?.shownScreensChanged()
         node.findParentStack()?.queue?.shownScreensChanged(node)
         modals.visibleScreenChanged(node)
+        BackCallbackState.update(this)
     }
 
     // The waiting layer [node] is in, up through the layouts around it; none.
@@ -435,13 +450,15 @@ class Navigator(
         destroyLayers(answerPending = false)
         // Nothing the old screens told of their readiness holds for the screens of the new JavaScript.
         ScreenReadiness.reset()
-        BarComponents.reset()
+        // Without layers back leaves the app until the new JavaScript sets its root.
+        BackCallbackState.update(this)
     }
 
     /**
-     * The activity is destroyed: every layer goes, with the events of a destroy; a `setRoot` on its way resolves with
-     * `''` (JavaScript sets its root again in the next activity), a modal's or an overlay's show and the commands that
-     * wait for a modal with their roots' ids. Main thread only.
+     * The activity is destroyed: every layer goes, with the events of a destroy; a `setRoot` whose root still waited
+     * resolves with `''` (JavaScript sets its root again in the next activity), one whose root showed resolves with
+     * its id, and a modal's or an overlay's show and the commands that wait for a modal resolve with their roots' ids.
+     * Main thread only.
      */
     internal fun destroyWithActivity() {
         destroyLayers(answerPending = true)

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

@@ -240,8 +240,9 @@ internal class RootCoordinator(
     /**
      * The activity's layers go: the `setRoot` on its way ends, then the root it replaced, the current root and its root
      * are destroyed, as at any destroy (their events reach only their own JavaScript). [answerPending]: the activity
-     * went, the waiting `setRoot` resolves with `''` (JavaScript sets the root again in the next activity); otherwise
-     * (a reload) it gets no answer.
+     * went; a `setRoot` whose root still waited resolves with `''` (JavaScript sets the root again in the next
+     * activity), one whose root showed (its transition ran, or the modals and overlays of its layout were showing)
+     * resolves with the root's id. Otherwise (a reload) it gets no answer.
      */
     fun destroyAll(answerPending: Boolean) {
         val pending = pending
@@ -256,7 +257,9 @@ internal class RootCoordinator(
         modals.replacedRootGone()
         pending?.let(::releaseState)
         if (pending != null && pending.phase == Phase.Waiting) firstRoot.rootDestroyed()
-        if (answerPending) pending?.answer?.resolve("")
+        if (!answerPending || pending == null) return
+        // An empty id tells JavaScript the root didn't show: its start waits for the next activity and sets it there.
+        pending.answer.resolve(if (pending.phase == Phase.Waiting) "" else pending.root.id)
     }
 
     // Waits for the screens that show when the root shows, then runs its transition. Without `waitForRender` one limit
@@ -485,8 +488,8 @@ internal class RootCoordinator(
     }
 
     // The navigation state goes once, when the root is in place and its layers have shown, right before the answer:
-    // what the old root's destroy, the root's appearance and each layer ask for meanwhile waits (StateHold). Taken once
-    // per `setRoot`, before the old root goes.
+    // what the old root's destroy, the root's appearance and each layer ask for meanwhile waits (the hold of
+    // NavigationState). Taken once per `setRoot`, before the old root goes.
     private fun holdState(pending: Pending) {
         if (pending.holdsState) return
         pending.holdsState = true

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

@@ -124,18 +124,18 @@ internal class OverlayCoordinator(
     }
 
     /**
-     * `dismissOverlay`: the overlays with the root id [componentId] go — one that waits is cancelled, one that shows
-     * goes with its events (both, when a replacement of a shown one waits) — and [answer] resolves with the id. An id
-     * no node has: `not shown`; a node that is no overlay's root (Android takes only the root's id): `not in an
-     * overlay`.
+     * `dismissOverlay`: the overlay [componentId] is in — its root or any screen inside it — goes with every overlay of
+     * the same root id: one that waits is cancelled, one that shows goes with its events (both, when a replacement of
+     * a shown one waits). [answer] resolves with the overlay's root id, as on iOS. An id no node has: `not shown`; a
+     * node in no overlay: `not in an overlay`.
      */
     fun dismiss(componentId: String, answer: CommandAnswer) {
-        if (host.find(componentId) == null) return answer.reject(ErrorTexts.screenNotShown(componentId))
-        val matches = records.filter { it.rootId == componentId }
-        if (matches.isEmpty()) return answer.reject(ErrorTexts.notInOverlay(componentId))
+        val node = host.find(componentId) ?: return answer.reject(ErrorTexts.screenNotShown(componentId))
+        val rootId = recordOf(node)?.rootId ?: return answer.reject(ErrorTexts.notInOverlay(componentId))
+        val matches = records.filter { it.rootId == rootId }
         matches.filter { it.state == OverlayRecord.State.Waiting }.forEach(::cancel)
         val shown = matches.filter { it.state == OverlayRecord.State.Shown }
-        if (shown.isEmpty()) return answer.resolve(componentId)
+        if (shown.isEmpty()) return answer.resolve(rootId)
         shown.dropLast(1).forEach { remove(it, null) }
         remove(shown.last(), answer)
     }