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

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

@@ -1,6 +1,6 @@
 package dev.apexnative.navigation.viewcontrollers.component
 
-import dev.apexnative.navigation.react.ScreenInsets
+import dev.apexnative.navigation.react.ScreenEnvironment.Insets
 
 /**
  * The arithmetic of a screen's room, safe area and background on Android, without views: the screen nodes read the
@@ -19,6 +19,7 @@ internal object ScreenSafeArea {
     const val LEFT = "left"
 
     private val ALL_EDGES = setOf(TOP, RIGHT, BOTTOM, LEFT)
+    private val DEFAULT_EDGES = setOf(TOP, RIGHT, LEFT)
     private const val OPAQUE = 0xFF
 
     /**
@@ -57,10 +58,10 @@ internal object ScreenSafeArea {
         headerBottom: Int?,
         tabsTop: Int?,
         density: Float,
-    ): ScreenInsets.Insets {
+    ): Insets {
         val coveredAbove = maxOf(system.top, headerBottom ?: 0)
         val coveredBelow = minOf(windowHeight - system.bottom, tabsTop ?: windowHeight)
-        return ScreenInsets.Insets(
+        return Insets(
             top = dp((coveredAbove - root.top).coerceAtLeast(0), density),
             right = dp((root.right - (windowWidth - system.right)).coerceAtLeast(0), density),
             bottom = dp((root.bottom - coveredBelow).coerceAtLeast(0), density),
@@ -69,26 +70,43 @@ internal object ScreenSafeArea {
     }
 
     /**
-     * The edges the screen's safe area view keeps its content off: exactly [safeAreaEdges] when the options give them;
-     * else all four, but the top when the stack's header hides on scroll or a large title shows ([topFree]) and the
-     * bottom when the tabs hide on scroll ([bottomFree]).
+     * The edges the screen's safe area view keeps its content off: exactly [safeAreaEdges] when the options give them,
+     * but the top under a large title ([largeTitle]); else the top and the sides, but the top when the stack's header
+     * hides on scroll or a large title shows ([topFree]). The bottom is free by default: the content goes down to the
+     * bottom, and a list keeps its last rows clear of the navigation bar with `useSafeAreaInsets()`.
      */
-    fun paddedEdges(safeAreaEdges: List<String>?, topFree: Boolean, bottomFree: Boolean): Set<String> {
-        if (safeAreaEdges != null) return safeAreaEdges.filterTo(LinkedHashSet()) { it in ALL_EDGES }
-        val edges = LinkedHashSet(ALL_EDGES)
+    fun paddedEdges(safeAreaEdges: List<String>?, topFree: Boolean, largeTitle: Boolean): Set<String> {
+        if (safeAreaEdges != null) {
+            val edges = safeAreaEdges.filterTo(LinkedHashSet()) { it in ALL_EDGES }
+            // Under a large title the list keeps its first rows clear of the bar itself; a padded top would follow the
+            // header as it collapses and move the list with it.
+            if (largeTitle) edges -= TOP
+            return edges
+        }
+        val edges = LinkedHashSet(DEFAULT_EDGES)
         if (topFree) edges -= TOP
-        if (bottomFree) edges -= BOTTOM
         return edges
     }
 
     /** The padding of the safe area view: the [insets] on the [edges] it keeps, 0 on the others. */
-    fun padding(insets: ScreenInsets.Insets, edges: Set<String>): ScreenInsets.Insets = ScreenInsets.Insets(
+    fun padding(insets: Insets, edges: Set<String>): Insets = Insets(
         top = if (TOP in edges) insets.top else 0.0,
         right = if (RIGHT in edges) insets.right else 0.0,
         bottom = if (BOTTOM in edges) insets.bottom else 0.0,
         left = if (LEFT in edges) insets.left else 0.0,
     )
 
+    /**
+     * The insets JavaScript gets (`useSafeAreaInsets`): what of the [insets] still covers the content once the safe
+     * area view keeps it off its [padding], 0 on a padded edge.
+     */
+    fun uncovered(insets: Insets, padding: Insets) = Insets(
+        top = (insets.top - padding.top).coerceAtLeast(0.0),
+        right = (insets.right - padding.right).coerceAtLeast(0.0),
+        bottom = (insets.bottom - padding.bottom).coerceAtLeast(0.0),
+        left = (insets.left - padding.left).coerceAtLeast(0.0),
+    )
+
     /**
      * The inner padding of a screen's view: the side system bars ([systemBars]) at the sides; at the bottom the larger
      * of the navigation bar (none when the screen draws under it) and the keyboard ([imeBottom]; none with

package/android/src/main/java/dev/apexnative/navigation/viewcontrollers/externalcomponent/ExternalComponentViewController.kt

@@ -10,11 +10,9 @@ import dev.apexnative.navigation.layout.LayoutException
 import dev.apexnative.navigation.nativescreen.NativeScreenContext
 import dev.apexnative.navigation.options.DefaultOptions
 import dev.apexnative.navigation.options.Options
-import dev.apexnative.navigation.react.ArrangementStates
 import dev.apexnative.navigation.react.CommandScope
 import dev.apexnative.navigation.react.ErrorTexts
-import dev.apexnative.navigation.react.ScreenInsets
-import dev.apexnative.navigation.react.ScreenRegions
+import dev.apexnative.navigation.react.ScreenEnvironment
 import dev.apexnative.navigation.react.events.AppearanceDispatcher
 import dev.apexnative.navigation.react.events.ComponentType
 import dev.apexnative.navigation.react.events.ScreenAppearance
@@ -170,9 +168,7 @@ class ExternalComponentViewController internal constructor(
         peekView()?.let { (it.parent as? ViewGroup)?.removeView(it) }
         setParentController(null)
         if (isIdTakenByAnother) return
-        ScreenInsets.remove(id)
-        ScreenRegions.remove(id)
-        ArrangementStates.remove(id)
+        ScreenEnvironment.remove(id)
         ScreenReadiness.remove(id)
         if (!notMade) AppearanceDispatcher.nativeScreenReleased(this)
     }

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

@@ -158,6 +158,9 @@ internal class ModalCoordinator(
 
         /** The record's views lay out again (the activity resumed). */
         fun requestLayout(record: ModalRecord) = Unit
+
+        /** The record's sheet as back sees it; none before its show and for a modal that isn't a sheet. */
+        fun sheetBack(record: ModalRecord): SheetBack? = null
     }
 
     /**
@@ -397,11 +400,26 @@ internal class ModalCoordinator(
     }
 
     /**
-     * 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.
+     * The root of the modal that back goes to first; none without one. A back gesture previews a pop in it, or the
+     * modal's dismissal when it is a sheet ([backTargetSheet]).
      */
     fun backTargetRoot(): ViewController<*>? = backTarget()?.root
 
+    /**
+     * The sheet back would dismiss now, as [handleBack] would, and as a drag down of the user would: the top modal is
+     * a sheet that shows, its content can't go back (else back goes there, and a pop in it has its own preview),
+     * `modal.swipeToDismiss` isn't false, `hardwareBackButton.dismissModalOnPress` doesn't hold back, it isn't the only
+     * modal over no root, and its sheet would hide, not collapse, and isn't closing already ([SheetBack.hidesOnBack]).
+     * None otherwise. The back gesture previews its hide on Android 14+, and its release closes it as the user does.
+     */
+    fun backTargetSheet(): SheetBack? {
+        val record = backTarget()?.takeIf { it.isSheet && it.state == State.Shown } ?: return null
+        if (record.root.canHandleBack() || holdsBack(record) || isLastWithoutRoot(record)) return null
+        val options = record.root.resolveShownOptions(DefaultOptions.current)
+        if (options.modal.swipeToDismiss.isFalse) return null
+        return views.sheetBack(record)?.takeIf { it.hidesOnBack }
+    }
+
     /** The mirror of [handleBack], without acting; null without a modal to ask. */
     fun canHandleBack(): Boolean? {
         val record = backTarget() ?: return null

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

@@ -15,6 +15,7 @@ import android.view.ViewOutlineProvider
 import android.view.ViewTreeObserver
 import android.widget.FrameLayout
 import android.widget.ScrollView
+import androidx.activity.BackEventCompat
 import androidx.coordinatorlayout.widget.CoordinatorLayout
 import androidx.core.graphics.Insets
 import androidx.core.view.ViewCompat
@@ -34,13 +35,14 @@ import kotlin.math.roundToInt
  * the detents of its options — `medium` at half the height, `large` at the full height under the status bar, a number
  * at that height in dp — and the user drags it between them. In a window wider than [MAX_WIDTH_DP] it stands in the
  * middle at that width. A drag down past the smallest one closes it, unless `swipeToDismiss` is false: then the sheet
- * stays, and the try is told. The screen under it stays in place.
+ * stays, and the try is told. The screen under it stays in place. On Android 14+ the back gesture previews its hide
+ * ([SheetBack]): the Material behavior shrinks it with the progress and slides it down at the release.
  */
 internal class ModalSheet(
     private val layout: CoordinatorLayout,
     private val content: View,
     private val events: Events,
-) {
+) : SheetBack {
     interface Events {
         /** The user dragged the sheet to another detent. */
         fun onDetentChanged(detent: SheetDetent)
@@ -66,6 +68,28 @@ internal class ModalSheet(
     private var dragged = false
     private var shown: (() -> Unit)? = null
     private var closing: (() -> Unit)? = null
+    // The back gesture whose preview runs now; none.
+    private var backPreview: BackPreview? = null
+    // Released: the behavior slides the sheet down from where the preview left it, and hides it at the end.
+    private var backFinishing = false
+    // The window's observer the scrim follows the preview's frames through, from its start until the sheet is back
+    // in place or gone; none otherwise.
+    private var backFramesObserver: ViewTreeObserver? = null
+
+    // The behavior tells no slide while back's preview scales the sheet and its release slides it down (they move it by
+    // its transform, not its offset): the scrim follows what is drawn, frame by frame, until the sheet stands again.
+    private val backFrames = ViewTreeObserver.OnPreDrawListener {
+        updateScrim()
+        if (backPreview == null && !backFinishing && container.scaleY == 1f && container.translationY == 0f) {
+            stopBackFrames()
+        }
+        true
+    }
+
+    private val sheetCallback = object : BottomSheetBehavior.BottomSheetCallback() {
+        override fun onStateChanged(sheet: View, newState: Int) = onState(newState)
+        override fun onSlide(sheet: View, slideOffset: Float) = updateScrim()
+    }
 
     // A list inside the sheet scrolls with it, as the Material behavior expects: up at half height the sheet goes up
     // first, down at the top of the list the sheet comes down. The behavior follows views that scroll nested.
@@ -89,6 +113,13 @@ internal class ModalSheet(
             }
         })
         scrim.setOnTouchListener { _, event -> taps.onTouchEvent(event) }
+        // The sheet keeps a touch that lands on it and no view in it takes (its bar, an empty part), as Material's
+        // BottomSheetDialog does: else the touch falls to the scrim under it, and a tap there closes a dimmed sheet;
+        // past an undimmed scrim it reaches the behavior, which takes the sheet into its drag state at the touch's
+        // down, before any move. The back gesture starts with such a touch, and a sheet in the drag state has no
+        // preview. A drag that starts there still moves the sheet: the behavior takes it past the touch slop, as from
+        // the views in it.
+        container.setOnTouchListener { _, _ -> true }
         container.clipToOutline = true
         container.outlineProvider = object : ViewOutlineProvider() {
             // The bottom corners are under the screen's bottom: only the top ones round.
@@ -116,10 +147,7 @@ internal class ModalSheet(
         behavior.isHideable = true
         behavior.state = BottomSheetBehavior.STATE_HIDDEN
         behavior.halfExpandedRatio = 0.5f
-        behavior.addBottomSheetCallback(object : BottomSheetBehavior.BottomSheetCallback() {
-            override fun onStateChanged(sheet: View, newState: Int) = onState(newState)
-            override fun onSlide(sheet: View, slideOffset: Float) = updateScrim()
-        })
+        behavior.addBottomSheetCallback(sheetCallback)
         container.viewTreeObserver.addOnGlobalLayoutListener(scrollViews)
     }
 
@@ -154,10 +182,12 @@ internal class ModalSheet(
         behavior.dragAnywhere = sheetOptions.expandsOnScroll.get(true)
         container.invalidateOutline()
         configure()
-        if (merge == null || closing != null) return
+        if (merge == null || closing != null || backFinishing) return
         val settled = detentOf(behavior.state)
         if (settled != null) behavior.isHideable = swipeToDismiss && settled == detents.first()
         val target = SheetStops.target(settled, detents, merge.selectedDetent, sheetOptions.selectedDetent)
+        // A merge that moves the sheet or keeps it from going down ends a preview of back on it.
+        if (target != null || !behavior.isHideable) stopBackPreview()
         if (target != null) {
             selected = target
             behavior.state = stateOf(target)
@@ -172,12 +202,19 @@ internal class ModalSheet(
             finishClosing()
             return
         }
+        // Released by back, it goes down already: it is closed at the end of that slide.
+        if (backFinishing) return
+        stopBackPreview()
         behavior.isHideable = true
         behavior.state = BottomSheetBehavior.STATE_HIDDEN
     }
 
     /** Takes the sheet's views away; the modal's view is the caller's. */
     fun remove() {
+        // A slide down of back's release that ends after this tells nothing: the modal went already.
+        behavior.removeBottomSheetCallback(sheetCallback)
+        stopBackPreview()
+        stopBackFrames()
         container.viewTreeObserver.removeOnGlobalLayoutListener(scrollViews)
         container.removeView(content)
         layout.removeView(container)
@@ -191,6 +228,69 @@ internal class ModalSheet(
         TestIds.apply(scrim, testId?.let { "$it.scrim" })
     }
 
+    override val hidesOnBack: Boolean
+        get() = closing == null && !backFinishing && behavior.isHideable && container.isLaidOut &&
+            detentOf(behavior.state) != null
+
+    override fun startBackPreview(event: BackEventCompat): SheetBack.Gesture? {
+        if (!hidesOnBack || backPreview != null) return null
+        val preview = BackPreview()
+        backPreview = preview
+        startBackFrames()
+        behavior.startBackProgress(event)
+        return preview
+    }
+
+    // A command closed or moved the sheet, or it goes, while back's preview runs: the sheet grows back where it stands
+    // (the behavior's cancel), and the gesture's release does the usual back.
+    private fun stopBackPreview() {
+        if (backPreview == null) return
+        backPreview = null
+        behavior.cancelBackProgress()
+    }
+
+    private fun startBackFrames() {
+        if (backFramesObserver != null) return
+        backFramesObserver = container.viewTreeObserver.also { it.addOnPreDrawListener(backFrames) }
+    }
+
+    // The listener leaves the observer it joined: a container out of the window has another one.
+    private fun stopBackFrames() {
+        val observer = backFramesObserver ?: return
+        backFramesObserver = null
+        if (observer.isAlive) observer.removeOnPreDrawListener(backFrames)
+    }
+
+    /** The back gesture over this sheet: the Material behavior previews its hide (`MaterialBackHandler`). */
+    private inner class BackPreview : SheetBack.Gesture {
+        override val sheet: SheetBack
+            get() = this@ModalSheet
+
+        override fun progress(event: BackEventCompat) {
+            if (backPreview !== this) return
+            behavior.updateBackProgress(event)
+            updateScrim()
+        }
+
+        override fun cancel() {
+            if (backPreview === this) stopBackPreview()
+        }
+
+        // The behavior slides the sheet down from the preview and sets its hidden state at the end: `onState` closes
+        // it there as a drag down does (`onClosedByUser`), so the modal goes through the user's path once.
+        override fun commit(): Boolean {
+            if (backPreview !== this) return false
+            backPreview = null
+            if (!hidesOnBack) {
+                behavior.cancelBackProgress()
+                return false
+            }
+            backFinishing = true
+            behavior.handleBackInvoked()
+            return true
+        }
+    }
+
     private fun closeByUser() {
         if (!swipeToDismiss) {
             events.onCloseAttempted()
@@ -243,6 +343,7 @@ internal class ModalSheet(
         when (state) {
             BottomSheetBehavior.STATE_DRAGGING -> dragged = true
             BottomSheetBehavior.STATE_HIDDEN -> {
+                backFinishing = false
                 when {
                     closing != null -> finishClosing()
                     else -> {
@@ -280,13 +381,23 @@ internal class ModalSheet(
     // The screen under the sheet dims as the sheet goes up past `largestUndimmedDetent` (from the bottom without
     // one), to the dim of a Material modal sheet at the next detent; while it isn't dimmed, it takes touches.
     private fun updateScrim() {
-        val height = layout.height - container.top
+        // Hidden at the end of back's slide, it still stands at its detent until the next layout.
+        if (behavior.state == BottomSheetBehavior.STATE_HIDDEN) return setDim(0f)
+        val height = layout.height - sheetTop()
         val undimmed = options.largestUndimmedDetent?.takeIf { it in detents }
         val from = undimmed?.let { heightOf(it) } ?: 0
         val to = detents.firstOrNull { heightOf(it) > from }?.let { heightOf(it) } ?: return run { setDim(0f) }
         setDim(((height - from).toFloat() / (to - from)).coerceIn(0f, 1f))
     }
 
+    // The top of the sheet as drawn: its offset, and while back's preview moves it, its slide and its scale toward
+    // the bottom (the behavior's pivot).
+    private fun sheetTop(): Int {
+        if (backFramesObserver == null) return container.top
+        val scaled = container.pivotY * (1f - container.scaleY)
+        return (container.top + container.translationY + scaled).roundToInt()
+    }
+
     private fun setDim(fraction: Float) {
         scrim.alpha = fraction * SCRIM_ALPHA
     }

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

@@ -19,6 +19,7 @@ import dev.apexnative.navigation.options.Options
 import dev.apexnative.navigation.utils.TestIds
 import dev.apexnative.navigation.utils.dp
 import dev.apexnative.navigation.viewcontrollers.viewcontroller.ViewController
+import dev.apexnative.navigation.views.animations.AnimationLayer
 import dev.apexnative.navigation.views.animations.AnimationRules
 import dev.apexnative.navigation.views.animations.SideAnimator
 import dev.apexnative.navigation.views.element.ElementTransition
@@ -263,6 +264,8 @@ internal class ModalViews(
         parts[record]?.container?.requestLayout()
     }
 
+    override fun sheetBack(record: ModalRecord): SheetBack? = parts[record]?.sheet
+
     // `modal.testID` on the modal's view; a sheet's on the sheet's container, `modal.sheet.testID` first, and its
     // grabber and scrim after it.
     private fun applyTestIds(record: ModalRecord, parts: Parts, options: Options) {
@@ -293,7 +296,11 @@ internal class ModalViews(
         val under = motion.underSide?.let { side -> underView?.let { SideAnimator.build(it, side, underBase) } }
         if (under != null && underView != null) {
             if (showing) moved[underView] = record else moved.remove(underView)
+            AnimationLayer.during(underView, under)
         }
+        // A fade of the modal or of the layer under it draws it through a hardware layer, given back at its end and at
+        // any stop (the set's cancel cancels it).
+        for (animator in listOfNotNull(side, fade)) AnimationLayer.during(container, animator)
         val fadeLength = motion.side?.takeIf(AnimationRules::isSingleAlpha)?.let(AnimationRules::lengthOf)
         val elements = motion.elements?.let { animation ->
             val content = modalsLayer.parent as? ViewGroup ?: return@let null

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

@@ -0,0 +1,42 @@
+package dev.apexnative.navigation.viewcontrollers.modal
+
+import androidx.activity.BackEventCompat
+
+/**
+ * A modal's sheet as back sees it ([ModalSheet]): whether a release of back would hide it, and the preview of that
+ * hide during the back gesture (Android 14+). [ModalCoordinator.backTargetSheet] gives the one back would dismiss now.
+ * Main thread only.
+ */
+internal interface SheetBack {
+    /**
+     * Back's release would hide the sheet, as a drag down does: it stands at a detent from which it goes down (its
+     * smallest, while it lets the user close it), laid out, and it isn't closing already. False at a larger detent:
+     * the Material behavior would only collapse it there.
+     */
+    val hidesOnBack: Boolean
+
+    /**
+     * Starts the preview of back on the sheet with the gesture's first [event]: the sheet shrinks a little toward the
+     * bottom with the progress, the scrim following it. None when [hidesOnBack] doesn't hold or a preview runs.
+     */
+    fun startBackPreview(event: BackEventCompat): Gesture?
+
+    /** A back gesture over the sheet ([startBackPreview]). */
+    interface Gesture {
+        /** The sheet the gesture previews. */
+        val sheet: SheetBack
+
+        /** The gesture moved. */
+        fun progress(event: BackEventCompat)
+
+        /** Cancelled, or back went elsewhere: the sheet grows back to where it stood, the scrim with it. */
+        fun cancel()
+
+        /**
+         * Released: the sheet slides down from where the preview left it and goes as one the user dragged down (its
+         * events, its dismissal). False when the preview stopped since it started (a command closed or moved the
+         * sheet): back goes the usual way.
+         */
+        fun commit(): Boolean
+    }
+}

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