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

package/android/src/main/java/dev/apexnative/navigation/options/StackAnimationOptions.kt

@@ -99,8 +99,8 @@ class BottomTabsEnterExitAnimationOptions {
 }
 
 /**
- * `StackAnimationOptions`: the animation of `pop`, and the base of `push` and `setStackRoot`; over the shared elements
- * and element transitions of [LayoutAnimation].
+ * `StackAnimationOptions`: the base of the animations of `push`, `pop` and `setStackRoot`; over the shared elements and
+ * element transitions of [LayoutAnimation].
  */
 open class StackAnimationOptions : LayoutAnimation() {
     @JvmField var enabled: Bool = NullBool()
@@ -188,6 +188,44 @@ class StackPushAnimationOptions : StackAnimationOptions() {
     }
 }
 
+/**
+ * `StackPopAnimationOptions`: the animation of `pop`, and `preview`: whether a back gesture over the stack previews the
+ * pop of its top (Android 14+); `false` pops it when the gesture is released, as on Android 13.
+ */
+class StackPopAnimationOptions : StackAnimationOptions() {
+    @JvmField var preview: Bool = NullBool()
+
+    override fun hasValue(): Boolean = super.hasValue() || preview.hasValue()
+
+    fun mergeWith(other: StackPopAnimationOptions) {
+        super.mergeWith(other)
+        if (other.preview.hasValue()) preview = other.preview
+    }
+
+    fun mergeWithDefault(defaults: StackPopAnimationOptions) {
+        super.mergeWithDefault(defaults)
+        if (!preview.hasValue()) preview = defaults.preview
+    }
+
+    override fun copy(): StackPopAnimationOptions = StackPopAnimationOptions().also { it.mergeWith(this) }
+
+    // Reads the fields of this class from [map], after those of its parent.
+    private fun readStackPopAnimationOptions(map: ReadableMap) {
+        readStackAnimationOptions(map)
+        preview = BoolParser.parse(map, "preview")
+    }
+
+    companion object {
+        @JvmStatic
+        fun parse(map: ReadableMap?): StackPopAnimationOptions {
+            val options = StackPopAnimationOptions()
+            if (map == null) return options
+            options.readStackPopAnimationOptions(map)
+            return options
+        }
+    }
+}
+
 /** `SetStackRootAnimationOptions`: the animation of `setStackRoot`. */
 class SetStackRootAnimationOptions : StackAnimationOptions() {
     @JvmField var asPush: Bool = NullBool()

package/android/src/main/java/dev/apexnative/navigation/options/UserChoices.kt

@@ -0,0 +1,159 @@
+package dev.apexnative.navigation.options
+
+import dev.apexnative.navigation.options.params.Text
+
+/**
+ * The user layer of a node: what the user chose in the native UI, kept apart from the node's own options so that the
+ * app's next `mergeOptions` or `setDefaultOptions` doesn't wipe it. The choices are the check of a single-selection
+ * menu (a bar button's `menu`, by the button's id; `topBar.overflowMenu`) and the search scope
+ * (`topBar.searchBar.selectedScope`).
+ *
+ * It goes over everything else as the node's options resolve (defaults < parents < own < user), by identity rather
+ * than as a tree merged over: a menu's check by the button's id and the item's id, the scope by its id. A choice whose
+ * button, item or scope is gone is not applied, and leaves at the node's next merge; a merge that gives a chosen field
+ * a value other than the one the app had there before takes the choice away ([yieldTo]). `setDefaultOptions` never
+ * clears it. The node owns it and writes it through `ViewController.changeChoices`, which moves [OptionsCache]. Main
+ * thread only.
+ */
+internal class UserChoices {
+    // The menus' checks: per menu (a button's id, OVERFLOW for `overflowMenu`) the item picked in each of its levels,
+    // in the order of the picks.
+    private val checks = LinkedHashMap<String, MutableList<String>>()
+    private var scope: String? = null
+
+    /** The user chose nothing that stays. */
+    val isEmpty: Boolean
+        get() = checks.isEmpty() && scope == null
+
+    /**
+     * The user picked [itemId] in [menu], the menu of the button [buttonId] or `overflowMenu` (null), as it showed: it
+     * takes the place of an earlier pick in the same level.
+     */
+    fun check(buttonId: String?, menu: ButtonMenuOptions, itemId: String) {
+        val picks = checks.getOrPut(keyOf(buttonId)) { mutableListOf() }
+        val level = levelItems(menu.items, itemId)?.map { it.id }.orEmpty()
+        picks.removeAll { it == itemId || it in level }
+        picks += itemId
+    }
+
+    /** The user picked the search scope [scopeId]. */
+    fun pickScope(scopeId: String) {
+        scope = scopeId
+    }
+
+    /**
+     * Writes the choices into [resolved], a result of resolution nobody else holds yet; the menus it changes are copied
+     * first, as a resolved result shares its menus with the layers they come from. Returns [resolved].
+     */
+    fun applyTo(resolved: Options): Options {
+        if (isEmpty) return resolved
+        val topBar = resolved.topBar
+        for ((key, picks) in checks) {
+            if (key == OVERFLOW) {
+                val menu = topBar.overflowMenu ?: continue
+                topBar.overflowMenu = menu.copyMenu().also { copy -> picks.forEach { mark(copy, it) } }
+                continue
+            }
+            val button = buttonIn(topBar.buttons, key) ?: continue
+            val menu = button.menu ?: continue
+            button.menu = menu.copyMenu().also { copy -> picks.forEach { mark(copy, it) } }
+        }
+        scope?.let { picked ->
+            val searchBar = topBar.searchBar
+            if (searchBar.scopes?.any { it.id == picked } == true) searchBar.selectedScope = Text(picked)
+        }
+        return resolved
+    }
+
+    /**
+     * The app merged [delta] into the node. A choice leaves when what it was made in is gone from [after] (the node's
+     * options as they resolve after the merge, without this layer), or when [delta] gives its field a value other than
+     * the one the node's own options had before the merge ([own]; where they had none, the app's resolution before the
+     * merge, [before]). The same value sent again (a re-render) keeps the choice. Returns whether a choice left.
+     */
+    fun yieldTo(delta: Options, own: Options, before: Options, after: Options): Boolean {
+        var changed = false
+        val entries = checks.entries.iterator()
+        while (entries.hasNext()) {
+            val (key, picks) = entries.next()
+            val now = menuIn(after, key)
+            val given = menuIn(delta, key)
+            val was = menuIn(own, key) ?: menuIn(before, key)
+            val left = picks.removeAll { itemId ->
+                val gone = now == null || levelItems(now.items, itemId) == null
+                gone || (given != null && checkedInLevel(given, itemId) != was?.let { checkedInLevel(it, itemId) })
+            }
+            if (left) changed = true
+            if (picks.isEmpty()) entries.remove()
+        }
+        scope?.let { picked ->
+            val given = delta.topBar.searchBar.selectedScope
+            val ownScope = own.topBar.searchBar.selectedScope
+            val was = (if (ownScope.hasValue()) ownScope else before.topBar.searchBar.selectedScope).get(null)
+            val changedByApp = given.hasValue() && given.get(null) != was
+            val gone = after.topBar.searchBar.scopes?.any { it.id == picked } != true
+            if (changedByApp || gone) {
+                scope = null
+                changed = true
+            }
+        }
+        return changed
+    }
+
+    companion object {
+        // The key of `overflowMenu`, which has no button; no placed button has an empty id.
+        private const val OVERFLOW = ""
+
+        private fun keyOf(buttonId: String?): String = buttonId ?: OVERFLOW
+
+        /** Whether picking [itemId] in [menu] moves a check: its level has `singleSelection`. */
+        fun checks(menu: ButtonMenuOptions, itemId: String): Boolean =
+            levelOf(menu.items, menu.singleSelection, itemId) == true
+
+        /** Moves the check of [itemId]'s level to it, in [menu] itself; nothing in a level without single selection. */
+        fun mark(menu: ButtonMenuOptions, itemId: String) {
+            mark(menu.items, menu.singleSelection, itemId)
+        }
+
+        private fun buttonIn(buttons: TopBarButtons, id: String): ButtonOptions? =
+            buttons.left?.firstOrNull { it.id.get(null) == id } ?: buttons.right?.firstOrNull { it.id.get(null) == id }
+
+        // The menu the key names in [options]: `overflowMenu`, or the menu of the button with that id.
+        private fun menuIn(options: Options, key: String): ButtonMenuOptions? =
+            if (key == OVERFLOW) options.topBar.overflowMenu else buttonIn(options.topBar.buttons, key)?.menu
+
+        // The checked items of the level that holds [itemId] in [menu]: the field a merge gives that level.
+        private fun checkedInLevel(menu: ButtonMenuOptions, itemId: String): Set<String>? =
+            levelItems(menu.items, itemId)?.filter { it.checked }?.map { it.id }?.toSet()
+
+        // The items of the level that holds [itemId]; null when it isn't in [elements].
+        private fun levelItems(
+            elements: List<ButtonMenuOptions.Element>,
+            itemId: String,
+        ): List<ButtonMenuOptions.Item>? {
+            val items = elements.filterIsInstance<ButtonMenuOptions.Item>()
+            if (items.any { it.id == itemId }) return items
+            return elements.filterIsInstance<ButtonMenuOptions.Submenu>().firstNotNullOfOrNull {
+                levelItems(it.items, itemId)
+            }
+        }
+
+        // Whether the level holding [itemId] has single selection; null when [itemId] isn't in [elements].
+        private fun levelOf(elements: List<ButtonMenuOptions.Element>, single: Boolean, itemId: String): Boolean? {
+            if (elements.any { it is ButtonMenuOptions.Item && it.id == itemId }) return single
+            for (element in elements) {
+                if (element !is ButtonMenuOptions.Submenu) continue
+                levelOf(element.items, element.singleSelection, itemId)?.let { return it }
+            }
+            return null
+        }
+
+        private fun mark(elements: List<ButtonMenuOptions.Element>, single: Boolean, itemId: String): Boolean {
+            if (elements.any { it is ButtonMenuOptions.Item && it.id == itemId }) {
+                if (single) elements.forEach { if (it is ButtonMenuOptions.Item) it.checked = it.id == itemId }
+                return true
+            }
+            return elements.any { it is ButtonMenuOptions.Submenu && mark(it.items, it.singleSelection, itemId) }
+        }
+    }
+}

package/android/src/main/java/dev/apexnative/navigation/react/ArrangementStates.kt

@@ -1,7 +1,5 @@
 package dev.apexnative.navigation.react
 
-import android.content.Context
-import com.facebook.react.ReactApplication
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.WritableMap
 import dev.apexnative.navigation.react.events.EventContract
@@ -19,11 +17,13 @@ internal object ArrangementStates {
 
     private val states = ConcurrentHashMap<String, State>()
 
-    /** Keeps the screen's state, and tells JavaScript when it changed and [notify] holds. Main thread only. */
-    fun set(context: Context, screenId: String, state: State, notify: Boolean) {
+    /**
+     * Keeps the screen's state, and tells JavaScript when it changed and [notify] holds, through [emitter], the one of
+     * the JavaScript the screen was made for: silent once it went. Main thread only.
+     */
+    fun set(screenId: String, state: State, notify: Boolean, emitter: EventEmitter) {
         if (states.put(screenId, state) == state || !notify) return
-        val reactContext = (context.applicationContext as? ReactApplication)?.reactHost?.currentReactContext ?: return
-        EventEmitter(reactContext).emitArrangementChanged(screenId, toMap(state))
+        emitter.emitArrangementChanged(screenId, toMap(state))
     }
 
     /** `{ placement, layout, front, hidden }`, empty for a screen outside a pair. Any thread. */

package/android/src/main/java/dev/apexnative/navigation/react/CommandAnswer.kt

@@ -3,13 +3,14 @@ package dev.apexnative.navigation.react
 import android.util.Log
 import com.facebook.react.bridge.Promise
 import dev.apexnative.navigation.react.events.EventEmitter
-import dev.apexnative.navigation.react.events.NavigationStateReporter
+import dev.apexnative.navigation.react.events.NavigationState
 import dev.apexnative.navigation.utils.NavigationLog
 
 /**
  * The one answer of a command with a promise: [resolve] or [reject], once; after that, and once the JavaScript it came
- * from went ([generation]), nothing. [CommandRunner] makes it on the main thread for each command; area code that takes
- * a [CommandListener] answers through [asListener]. Main thread only.
+ * from went ([generation]), nothing. It owns the command's one state step ([reportStateNow]). [CommandRunner] makes it
+ * on the main thread for each command; area code that takes a [CommandListener] answers through [asListener]. Main
+ * thread only.
  */
 internal class CommandAnswer(
     /** The method of the command: `push`, `setRoot`, … */
@@ -27,22 +28,39 @@ internal class CommandAnswer(
     var isAnswered = false
         private set
 
+    // The state step of this answer ran ([reportStateNow]).
+    private var stateReported = false
+
     /** Whether an answer now would reach the JavaScript the command came from. */
     val canAnswer: Boolean
         get() = !isAnswered && ReloadCoordinator.isCurrent(generation)
 
     /**
-     * Resolves the promise with [value]. For the commands that change what shows, the navigation state goes first,
-     * when it changed, so JavaScript has it when its `await` goes on; `ANN.CommandCompleted` follows the promise, for
-     * the commands that show or dismiss. A failure of either is logged; the promise goes all the same.
+     * The navigation state now, sent when it changed, once per answer: the end of the command's transition asks for it
+     * after the DidAppear it sends and before the transition's own events (`AppearanceDispatcher.endTransition`);
+     * otherwise [resolve] asks for it before the promise. A later call sends nothing, and nothing goes for a JavaScript
+     * that went. A failure of the step is logged and costs only the state.
+     */
+    fun reportStateNow() {
+        if (stateReported) return
+        stateReported = true
+        if (!ReloadCoordinator.isCurrent(generation)) return
+        guarded("report the navigation state") { events.stateNow() }
+    }
+
+    /**
+     * Resolves the promise with [value]. For the commands that change what shows (`CommandContract.STATE`), the
+     * navigation state goes first, when it changed and the command's transition didn't send it already
+     * ([reportStateNow]), so JavaScript has it when its `await` goes on; `ANN.CommandCompleted` follows the promise,
+     * for the commands that show or dismiss. A failure of either is logged; the promise goes all the same.
      */
     fun resolve(value: Any?) {
         if (!canAnswer) return
         isAnswered = true
-        if (commandName in STATE_COMMANDS) guarded("report the navigation state") { events.beforeAnswer() }
+        if (commandName in CommandContract.STATE) reportStateNow()
         promise.resolve(value)
         val commandId = commandId
-        if (commandName in COMPLETED_COMMANDS && commandId != null) {
+        if (commandName in CommandContract.COMPLETED && commandId != null) {
             guarded("send ANN.CommandCompleted") { events.commandCompleted(commandName, commandId, clock()) }
         }
     }
@@ -65,44 +83,19 @@ internal class CommandAnswer(
             log("[ApexNavigation] $commandName: ${ErrorTexts.couldNot(what, ErrorTexts.reasonOf(e))}")
         }
     }
-
-    companion object {
-        // The commands that send `ANN.CommandCompleted` (EVT-CommandCompleted).
-        val COMPLETED_COMMANDS = setOf(
-            "setRoot",
-            "push",
-            "pop",
-            "popTo",
-            "popToRoot",
-            "setStackRoot",
-            "showInColumn",
-            "showModal",
-            "dismissModal",
-            "dismissAllModals",
-            "showOverlay",
-            "dismissOverlay",
-            "dismissAllOverlays",
-        )
-
-        // The commands whose answer comes after the navigation state: those and `setColumnShown`.
-        val STATE_COMMANDS = COMPLETED_COMMANDS + "setColumnShown"
-    }
 }
 
 /** What goes to JavaScript around the answer of a command. Main thread only. */
 internal interface AnswerEvents {
-    /** Right before the promise resolves: the navigation state, when it changed. */
-    fun beforeAnswer()
+    /** The answer's one state step ([CommandAnswer.reportStateNow]): the navigation state now, when it changed. */
+    fun stateNow()
 
     /** After the promise resolved: `ANN.CommandCompleted`. */
     fun commandCompleted(commandName: String, commandId: String, completionTime: Long)
 
     /** Through the sender of the JavaScript that runs now. */
     object Current : AnswerEvents {
-        override fun beforeAnswer() {
-            val emitter = EventEmitter.current()
-            if (emitter.canSend) NavigationStateReporter.updateNow(emitter)
-        }
+        override fun stateNow() = NavigationState.updateNow()
 
         override fun commandCompleted(commandName: String, commandId: String, completionTime: Long) {
             EventEmitter.current().emitCommandCompleted(commandName, commandId, completionTime)

package/android/src/main/java/dev/apexnative/navigation/react/CommandContract.kt

@@ -0,0 +1,59 @@
+// Made by scripts/contract.mjs from src/interfaces/contract/commands.json: change that file and run the script again.
+
+package dev.apexnative.navigation.react
+
+/**
+ * What the commands with a promise answer, the same table as iOS. What each resolves with:
+ * - `setRoot`: the id of the root, once the root and the layout's modals and overlays show.
+ * - `push`: the id of the screen that shows; of a pair, the pair's id.
+ * - `preparePush`: the frame `{ width, height, padding }` of the prepared screen, or null; always null on iOS.
+ * - `pop`: the id of the screen that went.
+ * - `popTo`: the id of the screen it went back to.
+ * - `popToRoot`: the id of the first screen of the stack.
+ * - `setStackRoot`: the id of the new top screen.
+ * - `showModal`: the id of the modal's root.
+ * - `dismissModal`: the id of the modal's root.
+ * - `dismissAllModals`: an empty string.
+ * - `showOverlay`: the id of the overlay's root.
+ * - `dismissOverlay`: the id of the overlay's root.
+ * - `dismissAllOverlays`: an empty string.
+ * - `showInColumn`: the id of the screen that shows.
+ * - `setColumnShown`: nothing once the columns stopped moving (`undefined` on iOS, `null` on Android).
+ * - `getLaunchLink`: the link that launched the app, or null.
+ */
+internal object CommandContract {
+    /** The commands whose answer comes after the navigation state: every one that may change what shows. */
+    val STATE: Set<String> = setOf(
+        "setRoot",
+        "push",
+        "pop",
+        "popTo",
+        "popToRoot",
+        "setStackRoot",
+        "showModal",
+        "dismissModal",
+        "dismissAllModals",
+        "showOverlay",
+        "dismissOverlay",
+        "dismissAllOverlays",
+        "showInColumn",
+        "setColumnShown",
+    )
+
+    /** The commands that send `ANN.CommandCompleted` after their answer: every one that shows or dismisses. */
+    val COMPLETED: Set<String> = setOf(
+        "setRoot",
+        "push",
+        "pop",
+        "popTo",
+        "popToRoot",
+        "setStackRoot",
+        "showModal",
+        "dismissModal",
+        "dismissAllModals",
+        "showOverlay",
+        "dismissOverlay",
+        "dismissAllOverlays",
+        "showInColumn",
+    )
+}

package/android/src/main/java/dev/apexnative/navigation/react/Hinge.kt

@@ -9,7 +9,6 @@ import android.os.Build
 import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleOwner
-import com.facebook.react.ReactApplication
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.WritableMap
 import dev.apexnative.navigation.react.events.EventContract
@@ -19,17 +18,23 @@ import java.lang.ref.WeakReference
 
 /**
  * The device's hinge (`useHinge`): its state from the fold in the activity's window, its angle from the hinge angle
- * sensor (Android 11+). Android has no public state of a closed device: closed is a window without a fold and an
- * angle under 90°. No sensor and no fold: no hinge, `{}`. It runs while JavaScript has a hook mounted
- * (`setHingeUpdates`), the sensor only while the activity is resumed too; the same value is not sent twice. Main
- * thread only, but [get].
+ * sensor (Android 11+), in degrees to a tenth as on iOS. Android has no public state of a closed device: closed is a
+ * window without a fold, or an angle under 90° ([valueOf]). No sensor and no fold: no hinge, `{}`. It runs while
+ * JavaScript has a hook mounted (`setHingeUpdates`), the sensor only while the activity is resumed too; the same value
+ * is not sent twice. The values go to the JavaScript that turned the updates on (`EventEmitter.current` then): after a
+ * reload, until the updates stop, they go nowhere. Main thread only, but [get].
  */
 internal object Hinge {
-    data class Value(val state: String, val angle: Float?)
+    /** A value of the hinge: its state, and its angle in degrees to a tenth; none while the state is unknown. */
+    data class Value(val state: String, val angle: Double?)
+
+    private const val UNKNOWN = "unknown"
 
     private const val CLOSED_BELOW = 90f
 
     private var enabled = false
+    // The sender of the JavaScript that turned the updates on; none while they are off.
+    private var emitter: EventEmitter? = null
     private var activity: WeakReference<Activity>? = null
     private var folds: WindowFolds? = null
     private var sensorManager: SensorManager? = null
@@ -60,9 +65,11 @@ internal object Hinge {
     fun setEnabled(activity: Activity?, enabled: Boolean) {
         this.enabled = enabled
         if (!enabled) {
+            emitter = null
             detach()
             return
         }
+        emitter = EventEmitter.current()
         activity?.let(::attachTo)
         update()
     }
@@ -128,28 +135,32 @@ internal object Hinge {
         if (!enabled) return
         val folds = folds ?: return
         if (!folds.hasInfo || (listening && angle == null)) return
-        val fold = folds.folds.firstOrNull()
-        val angle = angle
-        val value = if (fold == null && sensor == null) {
-            null
-        } else {
-            val state = when {
-                fold?.halfOpened == true -> "partiallyOpen"
-                fold != null -> "fullyOpen"
-                angle != null && angle < CLOSED_BELOW -> "closed"
-                else -> "unknown"
-            }
-            Value(state, angle)
-        }
+        val value = valueOf(folds.folds.firstOrNull(), sensor != null, angle)
         if (value == last) return
         last = value
-        val reactContext = (activity?.get()?.application as? ReactApplication)?.reactHost?.currentReactContext ?: return
-        EventEmitter(reactContext).emitHingeChanged(toMap(value))
+        emitter?.emitHingeChanged(toMap(value))
+    }
+
+    /**
+     * The value of the window's first [fold] and the sensor's [angle]: none without a fold and without a sensor
+     * ([hasSensor]). `closed` without a fold or under 90°, else `partiallyOpen` for a half-opened fold and `fullyOpen`
+     * for a flat one. The angle goes to a tenth, as iOS gives it: the sensor's noise doesn't make a new value, and it
+     * is left out while the state is unknown.
+     */
+    fun valueOf(fold: WindowFolds.Fold?, hasSensor: Boolean, angle: Float?): Value? {
+        if (fold == null && !hasSensor) return null
+        val state = when {
+            fold == null || (angle != null && angle < CLOSED_BELOW) -> "closed"
+            fold.halfOpened -> "partiallyOpen"
+            else -> "fullyOpen"
+        }
+        val tenths = angle?.let { Math.round(it * 10.0) / 10.0 }
+        return Value(state, tenths.takeIf { state != UNKNOWN })
     }
 
     private fun toMap(value: Value?): WritableMap = Arguments.createMap().apply {
         if (value == null) return@apply
         putString(EventContract.HingeChanged.STATE, value.state)
-        value.angle?.let { putDouble(EventContract.HingeChanged.ANGLE, it.toDouble()) }
+        if (value.state != UNKNOWN) value.angle?.let { putDouble(EventContract.HingeChanged.ANGLE, it) }
     }
 }

package/android/src/main/java/dev/apexnative/navigation/react/NavigationTurboModule.kt

@@ -211,7 +211,7 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
         layout: ReadableMap,
         promise: Promise,
     ) {
-        // Android has one column to show screens in: the secondary pane (`showInColumn`).
+        // Android's split view has the primary and the secondary pane; another column rejects (`showInColumn`).
         val what = "show the screen '${LayoutReader.idOf(layout)}' in the '$column' column"
         runner.run(
             name = "showInColumn",
@@ -219,7 +219,7 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
             what = what,
             promise = promise,
             check = { LayoutReader.node(layout, context = appContext()) },
-        ) { node, answer -> navigator().stackCommands.showInColumn(componentId, node, answer, what) }
+        ) { node, answer -> navigator().stackCommands.showInColumn(componentId, column, node, answer, what) }
     }
 
     override fun setColumnShown(
@@ -295,9 +295,10 @@ class NavigationTurboModule(reactContext: ReactApplicationContext) : NativeANNTu
         })
     }
 
-    // The navigation of the activity the command runs in; the runner checked there is one.
+    // The navigation of the activity the command runs in; the runner checked there is an activity. One without its
+    // navigation yet (or any more) has nowhere to show screens either: the command rejects with the runner's own text.
     private fun navigator(): Navigator =
-        requireNotNull(Navigators.current()?.navigator) { "the activity has no navigation" }
+        Navigators.current()?.navigator ?: throw LayoutException(ErrorTexts.nowhereToShow())
 
     // The app's context, which the colors of the options resolve platform colors with.
     private fun appContext(): Context = reactApplicationContext.applicationContext

package/android/src/main/java/dev/apexnative/navigation/react/PendingCalls.kt

@@ -0,0 +1,48 @@
+package dev.apexnative.navigation.react
+
+import dev.apexnative.navigation.NavigationApplication
+import dev.apexnative.navigation.utils.UiThread
+
+/**
+ * The calls JavaScript made to the module that may not have reached the main thread yet: [after] runs a task on the
+ * main thread behind every one of them. A screen's first mount reaches the main thread from Fabric while a
+ * `mergeOptions` of the same React commit (its layout effects: `useScreenOptions`) may still be on its way: an
+ * asynchronous method goes from the JavaScript thread to the module's thread (`BridgelessNativeMethodCallInvoker`),
+ * which reads its options there and posts its body to the main thread ([CommandRunner]). The task goes the same way: a
+ * turn of the JavaScript thread, which comes after the task of the commit with its layout effects; then the module's
+ * thread, behind the calls that task made; then the main thread, behind their bodies. Each of the three runs its queue
+ * in order, so every call JavaScript made before the mount has applied when the task runs.
+ *
+ * Without JavaScript (none yet, a reload, a queue that ended) the task is posted to the main thread at once: nothing is
+ * on its way. A queue that ends while the task is on it drops it, and a wait with no limit of its own (a push with
+ * `waitForRender: true` whose content has mounted: the task is its only end) would not end; a queue ends only as the
+ * JavaScript goes (a reload, the host destroyed), and then the layouts go with it (`ReloadCoordinator`), the stack
+ * and its waiting push too. Main thread.
+ */
+internal object PendingCalls {
+    /** A queue the task goes through: it runs what it takes in order, and says false when it ended and took nothing. */
+    fun interface Queue {
+        fun run(task: Runnable): Boolean
+    }
+
+    /** Runs [task] on the main thread, on a later turn, after every call JavaScript made so far has applied there. */
+    fun after(task: () -> Unit) {
+        val context = NavigationApplication.instanceOrNull?.reactGatewayOrNull?.currentReactContext
+            ?.takeIf { it.hasActiveReactInstance() }
+        val js = context?.jsMessageQueueThread?.let { Queue(it::runOnQueue) }
+        val module = context?.nativeModulesMessageQueueThread?.let { Queue(it::runOnQueue) }
+        after(js, module, UiThread::post, task)
+    }
+
+    /**
+     * The way of [after] over the queues given: [js], then [module], then [main]; straight to [main] without one of
+     * them, or from where a queue refused it. The unit tests run it over their own queues.
+     */
+    fun after(js: Queue?, module: Queue?, main: (Runnable) -> Unit, task: () -> Unit) {
+        val onMain = Runnable(task)
+        if (js == null || module == null) return main(onMain)
+        val toMain = Runnable { main(onMain) }
+        val toModule = Runnable { if (!module.run(toMain)) main(onMain) }
+        if (!js.run(toModule)) main(onMain)
+    }
+}