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

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [1.0.0-alpha.4](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2026-10-23)
+
+
+### Bug Fixes
+
+* **ci:** keep a closed React Native issue instead of opening a second one ([#37](https://github.com/apexnative/navigation/issues/37)) ([242030c](https://github.com/apexnative/navigation/commit/242030c8559a6fe186f44781ada85d09970c8318))
+* **ios:** lay a waiting screen out in its place, so the large title comes in with it ([#41](https://github.com/apexnative/navigation/issues/41)) ([85bfaa8](https://github.com/apexnative/navigation/commit/85bfaa877d3775264c1ba1114942cf875f890f29))
+* one native contract, options as layers and pushes that wait for the first render ([#39](https://github.com/apexnative/navigation/issues/39)) ([888f21e](https://github.com/apexnative/navigation/commit/888f21eb2b3e1aec413413bbdab9546a7a8f5a6b))
+
 ## [1.0.0-alpha.3](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.2...v1.0.0-alpha.3) (2026-10-22)
 
 

package/android/CLAUDE.md

@@ -21,8 +21,9 @@ top-level folder. Main thread only, unless a line says otherwise.
   `OptionsReader`, `OptionsCache`, `DefaultOptions`. `params/` has the value types (`Bool`, `Text`, `Fraction`,
   `Variant`, `ThemeColour`); `parsers/` reads them tolerantly from React Native data.
 - `react/`: the way in and out: `NavigationTurboModule`, `CommandRunner`, `CommandAnswer`, `ErrorTexts`,
-  `OptionsCommands`, `ReloadCoordinator`, `ReactGateway`, `ReactView` (a React root), the stores (`ScreenInsets`,
-  `ScreenRegions`, `ArrangementStates`, `Hinge`, `StartInfo`), `LaunchLink`, `ScrollEvents`.
+  `OptionsCommands`, `PendingCalls` (a task behind the calls JavaScript made), `ReloadCoordinator`, `ReactGateway`,
+  `ReactView` (a React root), the stores (`ScreenInsets`, `ScreenRegions`, `ArrangementStates`, `Hinge`, `StartInfo`),
+  `LaunchLink`, `ScrollEvents`.
 - `react/events/`: `AppearanceDispatcher`, `ScreenAppearance`, `EventEmitter`, `EventContract` (made by
   `scripts/contract.mjs`), `NavigationStateReporter`, `ComponentType`.
 - `viewcontrollers/viewcontroller/`: `ViewController` (the base of every node), `Presenter`, `IReactView` (what a
@@ -53,7 +54,8 @@ top-level folder. Main thread only, unless a line says otherwise.
 - `slots/`, `safearea/`, `nativescreen/`: the views of `ANNSlot` and `ANNSafeAreaView`, the slot screen, the
   native-screen context and calls.
 - `splash/`, `customrow/`, `utils/`: the splash hold, theme and copy; the tabs' custom row options; helpers
-  (`UiThread`, `ImageLoader`, `MaterialTheme`, `TestIds`, `WindowFolds`, `DevelopmentLog`).
+  (`UiThread`, `ImageLoader` with `OptionImages`, `ImageKey`, `ImageRequests`, `MaterialTheme`, `TestIds`, `WindowFolds`,
+  `DevelopmentLog`).
 - `android/src/main/jni/`: `CMakeLists.txt` builds the codegen target with the C++ of `ios/cpp` (the slot's and the
   safe area view's shadow nodes); `ApexNavigationSpec.h` replaces the generated header so autolinking sees their
   descriptors.
@@ -106,12 +108,14 @@ top-level folder. Main thread only, unless a line says otherwise.
   `NavigationStateReporter.kt`; `react/CommandAnswer.kt`.
 - Options (parsing, merging): `options/Options.kt`, `OptionsReader.kt`, `OptionsCache.kt`, `DefaultOptions.kt`,
   `params/`, `parsers/`; `viewcontrollers/viewcontroller/ViewController.kt` (resolution).
-- Error texts: `react/ErrorTexts.kt`, made by `scripts/contract.mjs` from `src/interfaces/contract/errors.json`.
+- Error texts and answers: `react/ErrorTexts.kt` and `react/CommandContract.kt`, made by `scripts/contract.mjs` from
+  `src/interfaces/contract/errors.json` and `commands.json`.
 - Links: `react/LaunchLink.kt`, `NavigationActivity.kt` (`onNewIntent`); `react/StartInfo.kt`.
 - Hinge and regions: `react/Hinge.kt`, `react/ScreenRegions.kt`, `react/ScreenInsets.kt`, `utils/WindowFolds.kt`.
 - Native screens: `nativescreen/NativeScreenContext.kt`, `NativeScreenCalls.kt`, `NativeScreenCreator.kt`;
   `viewcontrollers/externalcomponent/`.
-- Slots: `slots/SlotHost.kt`, `SlotView.kt`, `SlotScreenView.kt`, `SlotContainers.kt`, `SlotViewManager.kt`.
+- Slots: `slots/SlotHost.kt`, `SlotView.kt`, `SlotScreenView.kt`, `SlotContainers.kt` (containers and slot views by
+  slot id: a change goes straight to the views of its id, `SlotViews.kt`), `SlotViewManager.kt`.
 - Safe area: `safearea/SafeAreaView.kt`, `SafeAreaViewManager.kt`; `viewcontrollers/component/ScreenReadiness.kt`;
   `react/ScreenInsets.kt`.
 - The C++ of `ANNSlot`, `ANNSafeAreaView`: `android/src/main/jni/CMakeLists.txt`, `ApexNavigationSpec.h`; sources in
@@ -125,7 +129,11 @@ top-level folder. Main thread only, unless a line says otherwise.
 - **Module thread.** The `check` of every command with a promise: `LayoutReader` and, through it, `OptionsReader` (also
   for `setDefaultOptions`, `mergeOptions` and the options of `dismissModal`, in the runner's `prepare` step);
   `ReadableJson` for native-screen props. The registry of native screens is read under its lock. Images are not loaded
-  here; `ImageLoader` loads them when the options apply, on main.
+  here; they load when the options apply, through the one cache of `utils/OptionImages` (by `ImageKey`): at once on
+  main where the first frame needs them (`ImageLoader`: the top bar's buttons, menus, back button and search
+  suggestions; a tab's first icon; a new FAB), on its background thread for a file or a drawable of the app where the
+  view takes them when ready (`ImageRequests`: a changed tab icon or one that didn't load, a FAB's changed icon, the
+  icon of a FAB hidden with `visible: false`, the FAB menu's actions).
 - **Main thread.** Everything else: the command body, nodes, views, events, the stores' writes. Any thread may read
   `ReloadCoordinator.generation`.
 
@@ -155,7 +163,9 @@ top-level folder. Main thread only, unless a line says otherwise.
   skips the table that decides interrupts and answers.
 - Every event of an appearance goes through `AppearanceDispatcher`. A container with its own loop of
   `onViewWillAppear` / `onViewDidAppear` / `onViewDisappear` sends the events in the wrong order.
-- Never change a resolved options object: it is cached and shared. Copy it, or write through `changeOptions`.
+- Never change a resolved options object: it is cached and shared. Copy it, or write through `changeOptions`; a
+  user's choice goes through `changeChoices` (the user layer), never into own options, or the next `mergeOptions`
+  wipes it.
 - A new option field that is not in `mergeWith`, `mergeWithDefault`, `copy` or the fixture is dropped silently somewhere
   in the chain; `WholeTreeTest` exists to catch it.
 - A new wait is a new `RenderWait` value, not a new timer. A wait that survives a destroy or a supersede hangs a promise;

package/android/CORE.md

@@ -72,8 +72,13 @@ react/events/AppearanceDispatcher ─► NavigationStateReporter ─► EventEmi
 5. **Make and join.** `LayoutFactory.create` makes Profile (a `ComponentViewController`, registered in the
    `ChildControllersRegistry`); `StackController.join` adds it; `StackQueue.push` accepts it as an entry.
 6. **`StackQueue`** is the only way to change a stack's children. `drain` starts the operation when nothing blocks it.
-   `startPush` decides the wait: none, `waitForRender`, or a prepared push. A wait is a `RenderWait` on Profile, and the
-   queue's `deliver` posts readiness signals to the next turn of the loop.
+   `startPush` decides the wait: a prepared push; `waitForRender: true` (as long as it takes); unset, for a screen with
+   React content, Profile's first mount, 0.5 s at most (`PUSH_WAIT_MILLIS`); none for `false`, a native screen or a
+   stack off screen. A wait is a `RenderWait` on Profile. Its mount reaches the push through the queue's `afterCalls`
+   (`PendingCalls`: once through the JavaScript thread, the module's thread and the main thread, the way of a
+   `mergeOptions`), so the `mergeOptions` of the commit that mounted it (`useScreenOptions`) has applied when the
+   transition starts, content mounted before the push too; the prepared push starts the same way after its slot
+   mounted. Unset, the targets of elements take what is left of the 0.5 s.
 7. **Begin.** `beginPush` raises Profile's view (`StackViews`), moves the bar and the tab bar
    (`StackQueue.Host.barTransition`, `tabBarTransition`), calls `StackController` through `currentChildChanged`, then
    `AppearanceDispatcher.beginTransition`: **`ComponentWillAppear`** of Profile. The transition runs
@@ -82,7 +87,7 @@ react/events/AppearanceDispatcher ─► NavigationStateReporter ─► EventEmi
    **`ComponentDidAppear`** of Profile, then `reportState` (**`NavigationStateChanged`**, only if it changed), then the
    transition's own events (none for a push), then `CommandAnswer.resolve` with Profile's id.
 9. **Answer.** `resolve` sends the state once more if it changed (`AnswerEvents.beforeAnswer`), resolves the promise,
-   then sends **`CommandCompleted`** (`COMPLETED_COMMANDS`). After the task, `BackCallbackState.update` recomputes what
+   then sends **`CommandCompleted`** (`CommandContract.COMPLETED`). After the task, `BackCallbackState.update` recomputes what
    back does.
 
 The events go from the main thread, synchronously, through `EventEmitter.current()`; the promise is answered once.

package/android/RECIPES.md

@@ -14,7 +14,11 @@ The steps for adding an option and for adding a command to the Android core; rea
    (a repaint after a light/dark switch or `setDefaultOptions`); a system-bar option goes through `SystemUiRules`.
    Read colors with `ThemeColour.get` at apply so they follow the theme.
 4. The cache needs nothing: own options are written only through `ViewController.options`, `changeOptions` and
-   `mergeOptions`, defaults only through `DefaultOptions.set`. Never change a resolved result.
+   `mergeOptions` (`mergeOwnOptions`), defaults only through `DefaultOptions.set`. Never change a resolved result.
+   What the user chooses in the native UI (a menu's check, a search scope) is not written into own options: it goes
+   into the node's user layer through `ViewController.changeChoices` (`options/UserChoices.kt`), which applies it by
+   id over the resolved options and lets it go when a merge changes that field. A new kind of choice is a field of
+   `UserChoices` with its `applyTo` and `yieldTo`; `changeOptions` stays for the library's own bookkeeping of a merge.
 5. Tests: add the field to `OptionsFixture.full()`. `WholeTreeTest` walks the tree by reflection and fails when a field
    is not read, copied, merged or defaulted. Add cases to `ReadersTest`, `MergeRuleTest` and the area's rules test.
 6. The docs page and a Showcase control; one meaning on both platforms, and where Android can't do it the JSDoc says so
@@ -31,8 +35,10 @@ The steps for adding an option and for adding a command to the Android core; rea
 4. New layout fields are read and checked in `LayoutReader`; checks against what shows are in `LayoutChecks` or in the
    command, before any node is made. Every rejection text is a function in `ErrorTexts` (same words as iOS),
    made by `node scripts/contract.mjs` from `src/interfaces/contract/errors.json`: a new text goes there.
-5. The answer goes through `CommandAnswer`: add the name to `COMPLETED_COMMANDS` when the command changes what shows
-   (then the state, the promise and `CommandCompleted` follow in that order). A transition ends through
+5. The answer goes through `CommandAnswer`: give the command its entry in `src/interfaces/contract/commands.json`
+   (what it resolves with, `state` when it may change what shows, `completed` when it shows or dismisses) and run
+   `node scripts/contract.mjs`, which makes `CommandContract` (then the state, the promise and `CommandCompleted` follow
+   in that order). A transition ends through
    `AppearanceDispatcher.endTransition`.
 6. Tests: `CommandRunnerTest`, `CommandAnswerTest`, `ErrorTextsTest`, `LayoutReaderTest`; a stack operation also needs a
    case in the queue tests (`StackQueueHarness`).

package/android/src/main/java/dev/apexnative/navigation/NavigationApplication.kt

@@ -3,32 +3,49 @@ package dev.apexnative.navigation
 import android.app.Application
 import android.util.Log
 import com.facebook.react.ReactApplication
-import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint
-import com.facebook.react.soloader.OpenSourceMergedSoMapping
 import com.facebook.soloader.SoLoader
 import dev.apexnative.navigation.nativescreen.NativeScreenCreator
 import dev.apexnative.navigation.react.ReactGateway
 import dev.apexnative.navigation.utils.NavigationLog
 
 /**
- * The application class of an app with the navigation: it loads React Native itself (the app doesn't call
- * `loadReactNative`), keeps one React host for every screen ([reactGateway]) and the native screens by name. The app
- * gives the host (`reactHost`) and registers its native screens in its `onCreate`, after this one.
+ * The application class of an app with the navigation: it keeps one React host for every screen ([reactGateway]) and
+ * the native screens by name. The app gives the host (`reactHost`) and loads React Native in its `onCreate` as the
+ * React Native template does, so the load follows the app's Gradle settings (the New Architecture, edge-to-edge):
+ *
+ * ```kotlin
+ * override fun onCreate() {
+ *     super.onCreate()
+ *     loadReactNative(this)
+ *     registerNativeScreen("Profile") { activity, context -> ProfileView(activity, context) }
+ * }
+ * ```
+ *
+ * The gateway, and with it the host, is made the first time something needs it (the first activity), after the app's
+ * `onCreate` loaded React Native.
  */
 abstract class NavigationApplication : Application(), ReactApplication {
     // Written on the main thread as the app registers, read on the module thread by the layout checks: under its lock.
     private val nativeScreens = LinkedHashMap<String, NativeScreenCreator>()
 
-    /** The app's React host as the navigation runs it. */
-    lateinit var reactGateway: ReactGateway
-        private set
+    // Made once, by the first activity ([reactGateway]); [reactGatewayOrNull] only reads it.
+    private val gateway: Lazy<ReactGateway> = lazy {
+        check(SoLoader.isInitialized()) {
+            "NavigationApplication needs React Native loaded first: call loadReactNative(this) in onCreate, " +
+                "as the React Native template does"
+        }
+        createReactGateway()
+    }
+
+    /**
+     * The app's React host as the navigation runs it, made when it is first asked for (the first activity's
+     * `onCreate`). React Native must be loaded by then: the app calls `loadReactNative(this)` in its `onCreate`.
+     */
+    val reactGateway: ReactGateway by gateway
 
     override fun onCreate() {
         super.onCreate()
         instance = this
-        SoLoader.init(this, OpenSourceMergedSoMapping)
-        DefaultNewArchitectureEntryPoint.load()
-        reactGateway = createReactGateway()
         registerGeneratedScreens()
     }
 
@@ -57,9 +74,13 @@ abstract class NavigationApplication : Application(), ReactApplication {
     internal fun isNativeScreenRegistered(name: String): Boolean =
         synchronized(nativeScreens) { nativeScreens.containsKey(name) }
 
-    /** [reactGateway] once `onCreate` made it. */
+    /**
+     * [reactGateway] once the first activity made it; none before. It never makes it: its callers (the log, the
+     * events, a React root) may run first, also off the main thread, and the app's `reactHost` isn't theirs to make.
+     * Any thread.
+     */
     internal val reactGatewayOrNull: ReactGateway?
-        get() = if (::reactGateway.isInitialized) reactGateway else null
+        get() = if (gateway.isInitialized()) gateway.value else null
 
     // The list of `npx apex-navigation codegen`, found by its name: an app without native screens has none.
     private fun registerGeneratedScreens() {

package/android/src/main/java/dev/apexnative/navigation/layout/LayoutChecks.kt

@@ -47,5 +47,9 @@ internal object LayoutChecks {
      */
     @JvmStatic
     fun checkStackChild(node: LayoutNode, stackId: String): String? =
-        if (node.type in stackChildren) null else ErrorTexts.stackTakesScreens(stackId, node.type.jsName)
+        if (isStackChild(node)) null else ErrorTexts.stackTakesScreens(stackId, node.type.jsName)
+
+    /** Whether a stack takes [node]: a screen, a native screen or a pair, not a container. */
+    @JvmStatic
+    fun isStackChild(node: LayoutNode): Boolean = node.type in stackChildren
 }

package/android/src/main/java/dev/apexnative/navigation/layout/LayoutNode.kt

@@ -82,10 +82,14 @@ internal data class LayoutNode(
         private val COLUMN_NAMES = setOf(PRIMARY, SECONDARY, SUPPLEMENTARY, COMPACT, INSPECTOR)
         private val COLUMNS_WITHOUT_NAMES = listOf(PRIMARY, SECONDARY)
 
-        /** The column of the child at [index] of a split view with [columns]; none for a child without one. */
+        /**
+         * The column of the child at [index] of a split view with [columns]; none for a child without one, and none
+         * for a repeat of a name an earlier child has (the first takes the column), as on iOS.
+         */
         internal fun columnName(columns: List<String>, index: Int): String? {
             val names = columns.ifEmpty { COLUMNS_WITHOUT_NAMES }
-            return names.getOrNull(index)?.takeIf { it in COLUMN_NAMES }
+            val name = names.getOrNull(index)?.takeIf { it in COLUMN_NAMES } ?: return null
+            return name.takeIf { names.indexOf(it) == index }
         }
     }
 }

package/android/src/main/java/dev/apexnative/navigation/nativescreen/NativeScreenContext.kt

@@ -44,8 +44,8 @@ class NativeScreenContext @RestrictTo(RestrictTo.Scope.LIBRARY) constructor(
 
     /**
      * Runs a command of the navigation from this screen in JS, as `useNavigation()` of a React screen does: push, pop,
-     * popTo, popToRoot, showInColumn, showModal, dismiss, showOverlay, dismissOverlay, setOptions, selectTab,
-     * setTabBadge. [arguments] are those of the JS command; [result] gets what it resolved with.
+     * popTo, popToRoot, showInColumn, showModal, dismiss, showOverlay, setOptions, selectTab, setTabBadge.
+     * [arguments] are those of the JS command; [result] gets what it resolved with.
      */
     @JvmOverloads
     fun navigate(command: String, arguments: JSONArray = JSONArray(), result: ((Result<Any?>) -> Unit)? = null) =

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

@@ -8,8 +8,8 @@ import dev.apexnative.navigation.options.parsers.IconParser
  * A menu of the bar: `topBar.overflowMenu`, or the `menu` of a button. Its items, and submenus among them; with
  * `singleSelection` one item of a level has a checkmark at a time.
  *
- * Copied options share it, so the checkmark a pick moves stays with the screen when it appears again, until new
- * options give the menu again.
+ * Copied options share it, so nobody changes a menu in place but in a copy of its own: the check a user's pick moves
+ * lives in the screen's user layer (`UserChoices`), which goes into a copy as the screen's options resolve.
  */
 class ButtonMenuOptions(
     @JvmField val singleSelection: Boolean,

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

@@ -197,8 +197,8 @@ class ButtonOptions(@JvmField var id: Text = NullText()) {
 
 /**
  * A copy of the menu with new items and submenus and the same values. A menu taken from the default options is copied
- * first, so that the module's in-place `checked` never writes into [DefaultOptions.current]; copies between a node's
- * own and resolved options share the menu on purpose.
+ * first, so that nothing written into a resolved result reaches [DefaultOptions.current]; the user layer writes its
+ * checks into a copy too (`UserChoices`), and copies between a node's own and resolved options share the menu.
  */
 internal fun ButtonMenuOptions.copyMenu(): ButtonMenuOptions =
     ButtonMenuOptions(singleSelection, items.map(::copyElement), testID)

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

@@ -3,9 +3,10 @@ package dev.apexnative.navigation.options
 /**
  * The one point where the options of the app change: a process-wide generation that grows at each change. A node's
  * resolved options are kept while the generation stays and the nodes they were built along are the same
- * (`ViewController.resolveCurrentOptions`). Exactly two places call [optionsChanged]: the write of a node's own options
- * (`ViewController.options`, and `changeOptions` through it) and the store of new default options
- * ([DefaultOptions.set]). Nothing else changes a node's own options or the defaults. Main thread only.
+ * (`ViewController.resolveCurrentOptions`). Three places call [optionsChanged]: the write of a node's own options
+ * (`ViewController.options`, and `changeOptions` and `mergeOwnOptions` through it), the write of a node's user layer
+ * (`ViewController.changeChoices`, and a merge that takes a choice away) and the store of new default options
+ * ([DefaultOptions.set]). Nothing else changes a node's own options, its user layer or the defaults. Main thread only.
  */
 object OptionsCache {
     /** The generation of the options; it only grows. */
@@ -13,7 +14,10 @@ object OptionsCache {
     var generation: Long = 0
         private set
 
-    /** A node's own options or the default options changed: every resolved result built before is stale. */
+    /**
+     * A node's own options, its user layer or the default options changed: every resolved result built before is
+     * stale.
+     */
     @JvmStatic
     fun optionsChanged() {
         generation++

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

@@ -39,10 +39,10 @@ internal class CommandAnswer(
     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) guarded("report the navigation state") { events.beforeAnswer() }
         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,28 +65,6 @@ 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. */

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

@@ -19,13 +19,16 @@ 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. 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
 
@@ -128,28 +131,33 @@ 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))
     }
 
+    /**
+     * 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) }
     }
 }