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

package/android/src/main/java/dev/apexnative/navigation/slots/SlotScreenView.kt

@@ -31,7 +31,12 @@ class SlotScreenView(
     private val whenMounted = mutableListOf<Runnable>()
     private val whenRendered = mutableListOf<Runnable>()
     private val mountedHandlers = LinkedHashMap<String, Runnable>()
-    private var readinessListener: ScreenReadiness.Listener? = null
+    private var listening = false
+
+    // The safe area view of a slot renders in the app's one React tree: every signal of the id is the screen's.
+    private val readiness = object : ScreenReadiness.Listener {
+        override fun onContentRendered() = checkReadiness()
+    }
     private var mounted = false
     private var readyTold = false
     private var destroyed = false
@@ -105,14 +110,9 @@ class SlotScreenView(
         if (readyTold) return listener.run()
         whenRendered += listener
         if (isReady()) return checkReadiness()
-        if (readinessListener != null) return
-        val readiness = object : ScreenReadiness.Listener {
-            override fun onLaidOut() = Unit
-
-            override fun onContentRendered() = checkReadiness()
-        }
-        readinessListener = readiness
-        ScreenReadiness.setListener(componentId, readiness)
+        if (listening) return
+        listening = true
+        ScreenReadiness.addListener(componentId, this, readiness)
     }
 
     override fun whenSlotContentMounted(listener: Runnable) {
@@ -151,8 +151,8 @@ class SlotScreenView(
     }
 
     private fun stopListening() {
-        val readiness = readinessListener ?: return
-        readinessListener = null
-        ScreenReadiness.removeListener(componentId, readiness)
+        if (!listening) return
+        listening = false
+        ScreenReadiness.removeListener(componentId, this)
     }
 }

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/arrangement/ArrangementController.kt

@@ -10,6 +10,7 @@ import dev.apexnative.navigation.NavigationActivity
 import dev.apexnative.navigation.options.DefaultOptions
 import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.react.ArrangementStates
+import dev.apexnative.navigation.react.events.EventEmitter
 import dev.apexnative.navigation.utils.SystemUiUtils
 import dev.apexnative.navigation.utils.WindowFolds
 import dev.apexnative.navigation.viewcontrollers.child.ChildController
@@ -146,11 +147,11 @@ class ArrangementController internal constructor(
         val single = plan.layout == ArrangementPlan.Layout.SINGLE
         if (primary is ComponentViewController) {
             val state = ArrangementStates.State(PRIMARY, layout, front = overlay, hidden = false)
-            ArrangementStates.set(activity, primary.id, state, notify)
+            ArrangementStates.set(primary.id, state, notify, EventEmitter.of(primary.jsGeneration))
         }
         if (secondary is ComponentViewController) {
             val state = ArrangementStates.State(SECONDARY, layout, front = false, hidden = single)
-            ArrangementStates.set(activity, secondary.id, state, notify)
+            ArrangementStates.set(secondary.id, state, notify, EventEmitter.of(secondary.jsGeneration))
         }
     }
 

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

@@ -26,14 +26,12 @@ import dev.apexnative.navigation.utils.scrollToTop
 import dev.apexnative.navigation.viewcontrollers.child.ChildControllersRegistry
 import dev.apexnative.navigation.viewcontrollers.component.ComponentViewController
 import dev.apexnative.navigation.viewcontrollers.component.RestPlace
-import dev.apexnative.navigation.viewcontrollers.component.ScreenReadiness
 import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackState
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.parent.ContainerBackground
 import dev.apexnative.navigation.viewcontrollers.parent.ParentController
 import dev.apexnative.navigation.viewcontrollers.stack.StackController
 import dev.apexnative.navigation.viewcontrollers.stack.fab.FabPlacement
-import dev.apexnative.navigation.viewcontrollers.stack.topbar.BarComponents
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.Presenter
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
 import dev.apexnative.navigation.views.animations.FadeThrough
@@ -379,6 +377,9 @@ class BottomTabsController(
         // A layer that waits for the tabs waits for the tab they show now.
         navigator?.shownScreensChanged(this)
         if (onScreen) AppearanceDispatcher.beginTransition(listOf(shown))
+        // From code and by back the state goes at once, as on iOS: `selectTab` resolves on it, and the command after
+        // it must act in this tab, not in the one still fading out.
+        if (how != How.Press) AppearanceDispatcher.reportState()
         if (views == null) return switched(index, previous, how, onScreen, hasViews = false)
         endSwitch = views.switch(shown, left, animated = onScreen) {
             endSwitch = null
@@ -390,8 +391,8 @@ class BottomTabsController(
      * The switch to the tab at [index] from [previous] ended: what went disappears, what came appears — unless the tabs
      * stopped showing during the fade (a modal over them): it appears when they show again; then for a press
      * `ANN.BottomTabSelected` right after the new screen's DidAppear and the left tab's `popToRootOnBlur`, with the state
-     * as one update after them; from code and by back, `popToRootOnBlur` and the state at once. [onScreen]: the switch
-     * started on screen.
+     * as one update after them; from code and by back, `popToRootOnBlur` and the state, which went at the start too
+     * ([select]). [onScreen]: the switch started on screen.
      */
     private fun switched(index: Int, previous: Int, how: How, onScreen: Boolean, hasViews: Boolean) {
         val left = tabs[previous]
@@ -660,15 +661,12 @@ class BottomTabsController(
     private fun makeCell(index: Int): CustomBottomTabItemView {
         val component = itemOptions(index).component
         val componentId = component.componentId.get(null) ?: "$id.$index"
-        ScreenReadiness.setRendersAtOnce(componentId, true)
-        // Another live root has the id (the same layout set again before the old one went): what it rendered isn't
-        // this one's; the id's readiness goes only with its last root (as the bar's roots).
-        if (BarComponents.isLive(componentId)) ScreenReadiness.forgetRender(componentId)
-        BarComponents.rootMade(componentId)
         val cell = CustomBottomTabItemView(activity)
         val state = cellState(index)
-        cell.show(ReactView(activity, componentId, component.name.get(""), cell.bundleOf(state)), state)
-        cell.onDestroyed = { if (BarComponents.rootStopped(componentId)) ScreenReadiness.remove(componentId) }
+        // Another live root may have the id (the same layout set again before the old one went): each answers by the
+        // render of its own surface, and the id's readiness goes with its last root.
+        val root = ReactView(activity, componentId, component.name.get(""), cell.bundleOf(state), rendersAtOnce = true)
+        cell.show(root, state)
         return cell
     }
 

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

@@ -14,6 +14,7 @@ import dev.apexnative.navigation.react.ScreenInsets
 import dev.apexnative.navigation.react.ScreenRegions
 import dev.apexnative.navigation.react.events.AppearanceDispatcher
 import dev.apexnative.navigation.react.events.ComponentType
+import dev.apexnative.navigation.react.events.EventEmitter
 import dev.apexnative.navigation.slots.SlotScreenView
 import dev.apexnative.navigation.system.SystemUiOwner
 import dev.apexnative.navigation.viewcontrollers.child.ChildController
@@ -177,8 +178,11 @@ class ComponentViewController(
             topFree = parent?.leavesTopEdgeFree(this) == true,
             bottomFree = parent?.leavesBottomEdgeFree(this) == true,
         )
-        ScreenInsets.update(activity, id, insets, ScreenSafeArea.padding(insets, edges))
-        ScreenRegions.update(activity, id, Rect(place.left, place.top, place.right, place.bottom), windowInsets)
+        // The events of the screen go to the JavaScript it was made for, and to no other.
+        val emitter = EventEmitter.of(jsGeneration)
+        ScreenInsets.update(id, insets, ScreenSafeArea.padding(insets, edges), emitter)
+        val area = Rect(place.left, place.top, place.right, place.bottom)
+        ScreenRegions.update(activity, id, area, windowInsets, emitter)
     }
 
     // A layout asked for on the content or on a view around it: it isn't in its place yet.

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

@@ -5,7 +5,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 (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.
+ * itself: the content keeps its own listener of its id and tells every waiter. Main thread only.
  */
 internal interface Readiness {
     /** The content of [screen] rendered; a screen without content to wait for is ready. */

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/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,7 +450,8 @@ 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)
     }
 
     /**

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

@@ -488,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/splitview/SplitViewController.kt

@@ -153,6 +153,9 @@ class SplitViewController(
 
     private fun onWidthChanged(layout: SplitViewLayout) {
         primary.getView().visibility = if (primaryHidden && layout.isWide == true) View.GONE else View.VISIBLE
+        // Compact, side by side or one over the other decides what back does from this measure on: the callback only
+        // takes its value here, nothing moves; the panes' end below computes it again.
+        BackCallbackState.update()
         // Where a later `compactTopColumn` puts the pane over the other at this switch: true open, false closed.
         val settle = if (measured && isSliding) laterTopColumn?.let { it == SECONDARY } else null
         if (!measured) {