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

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # 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)
+
+
+### Features
+
+* **android:** system stack transitions, an opaque default screen background and predictive back ([#26](https://github.com/apexnative/navigation/issues/26)) ([9f28969](https://github.com/apexnative/navigation/commit/9f28969a30a8902c1512cd2a24c3ddf5439f4642))
+
+
+### Bug Fixes
+
+* **android:** center the back button and the bar buttons in the row ([#35](https://github.com/apexnative/navigation/issues/35)) ([c908971](https://github.com/apexnative/navigation/commit/c9089716ea4e3b3f4bcdc42b16e57134018d76c0))
+* **android:** fade through on a tab switch, a new tab's first frame in place ([#29](https://github.com/apexnative/navigation/issues/29)) ([60d69b6](https://github.com/apexnative/navigation/commit/60d69b618a97c8f7da974fbdf6f427461960d672))
+* **android:** let an overlay cover the status bar ([#27](https://github.com/apexnative/navigation/issues/27)) ([2632194](https://github.com/apexnative/navigation/commit/26321945cf0c457780b3eb7bba1f3d988dad4d96))
+* **android:** match each modal presentation style to its Android equivalent ([#31](https://github.com/apexnative/navigation/issues/31)) ([54ab265](https://github.com/apexnative/navigation/commit/54ab2651f3139e869a2d99a43465b33bfb171414))
+* **android:** move the top bar with its screen in transitions of their own ([#34](https://github.com/apexnative/navigation/issues/34)) ([4d12ee6](https://github.com/apexnative/navigation/commit/4d12ee6d6ec26a04e529bdef8b8111d20e5116aa))
+* close the side menu as a pick in it changes the center ([#28](https://github.com/apexnative/navigation/issues/28)) ([c4b3e81](https://github.com/apexnative/navigation/commit/c4b3e81ba44d2edb6d93d3ddc906eca165d46e29))
+
+
+### Performance Improvements
+
+* **android:** render the modals of a setRoot's layout together with its root ([#32](https://github.com/apexnative/navigation/issues/32)) ([cf3e1d9](https://github.com/apexnative/navigation/commit/cf3e1d98ff7c5d2a05aba6485203e6fe35a3423d))
+
 ## [1.0.0-alpha.2](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.1...v1.0.0-alpha.2) (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.
@@ -73,8 +75,10 @@ top-level folder. Main thread only, unless a line says otherwise.
   `ScreenFrame.kt` (bars' room, window insets, keyboard), `ScreenSafeArea.kt`, `ComponentPresenter.kt` (background),
   `ScreenContentFactory.kt`, `ScreenFocus.kt`; `react/ReactView.kt`; `views/component/ComponentLayout.kt`.
 - Stack (queue, commands, back): `viewcontrollers/stack/StackQueue.kt`, `StackCommands.kt`, `StackController.kt`,
-  `StackViews.kt`, `StackTransitions.kt`, `PreparedPushes.kt`; `views/stack/StackLayout.kt`; back:
-  `NavigationActivity.kt`, `viewcontrollers/navigator/BackCallbackState.kt`.
+  `StackViews.kt`, `StackTransitions.kt`, `PreparedPushes.kt`; `views/stack/StackLayout.kt`, `ScreenEdge.kt` (the edge
+  a moving screen extends); back: `NavigationActivity.kt`, `viewcontrollers/navigator/BackCallbackState.kt`; the
+  preview of a pop during the back gesture (Android 14+): `StackController.BackGesture`, `BackPreview.kt`,
+  `stackPoppedByBack` of the layouts.
 - Stack FAB: `viewcontrollers/stack/fab/FabPresenter.kt`, `FabPlan.kt`, `FabPlacement.kt`; `views/stack/fab/`.
 - Top bar (title, buttons, menus, large title): `viewcontrollers/stack/topbar/TopBarPresenter.kt`, `TopBarRoom.kt`,
   `TopBarVisibility.kt`, `BarComponents.kt`, `ButtonPlaces.kt`, `LargeTitleCollapse.kt`, `BarRowTransition.kt`;
@@ -104,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
@@ -123,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`.
 
@@ -153,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;
@@ -167,6 +179,9 @@ top-level folder. Main thread only, unless a line says otherwise.
   `OverlayCoordinator.guarded`), which rejects the open answer and ends the record, or an exception ends the app and
   the command never answers.
 - A node makes its view in `createView`, never in its constructor.
+- Whether a node keeps the status bar's room (its margin, its background band) goes through
+  `StatusBarOptions.isHiddenOrDrawBehind(node.isInOverlay)`: an overlay covers the whole window, and a rule that reads
+  `drawBehind` alone puts a light band over an overlay's dimmed backdrop.
 - Only `SystemUiWindow` writes to the window. A presenter that changes a bar option calls `SystemUiOwner.invalidate`.
 - The core names a module container only in `LayoutFactory`; elsewhere use a capability or `visibleChildren()`.
 - A hidden stack keeps a `mergeOptions` per entry; applying it for the wrong entry paints the wrong screen's bar.
@@ -177,6 +192,20 @@ top-level folder. Main thread only, unless a line says otherwise.
   offset that `ScrollEventListener.lastOffset` keeps, never to 0, or it comes back expanded over a scrolled list.
 - A view's place in the window while a modal slides or a sheet is dragged comes from layout (`RestPlace`), never from
   `getLocationInWindow`, which counts the translations of the animation.
+- The bar measures to its children: a picture laid into it for a transition that is taller than the bar the incoming
+  screen gives holds the bar at that height to the end (the row's picture of a pop from a large title). What doesn't
+  stay in the bar rides with the leaving screen (`TopBarPresenter.pictureUnderRow`).
+- A `Toolbar` centers its navigation button and its menu in `min(minimumHeight, height)` (`buttonGravity` is top):
+  the row's toolbars take the row's height as their minimum (`TitleBar`); 0 pins the buttons to the row's top.
+- A screen's overlay is clipped to the screen, and a screen without a large title is laid out under the bar (its `top`
+  is the bar's height): a picture of the bar in its overlay doesn't show. The bar's picture in a transition of the
+  stack's own is drawn by the stack's view with the screen's transform (`StackLayout.barTravels`).
+- A React screen without `layout.backgroundColor` is opaque with the theme's `android:colorBackground`
+  (`ComponentPresenter`): a push keeps the covered screen under the new one until it ends, and a transparent screen
+  shows it. Only an explicit `'transparent'` / `null` (overlays, see-through modals) lets it through.
+- The back gesture's preview shows the screen under the top outside any operation of the queue: it may only reveal
+  it and put it back, and its release goes through `StackQueue.cut(gesture = true)`. A command that comes meanwhile
+  stops it through `StackDisplay.stop`, like any transition it takes over.
 - Without edge to edge the window resizes for the keyboard by the manifest's soft input mode, so
   `layout.adjustResize: false` goes through the system UI owner's keyboard group (`SystemUiWindow.setKeyboardCovers`),
   not through the screen's padding.

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.
@@ -91,7 +96,9 @@ The events go from the main thread, synchronously, through `EventEmitter.current
   current root in the root layer, transparent (`RootLayerViews.place`), so its React roots start while the old root keeps
   the touches. It waits (`RenderWait`, by `animations.setRoot.enter.waitForRender`), then fades through or plays its own
   animation, the old root is destroyed with its `ComponentDidDisappear`, `NativeScreenReleased` and `SlotDestroyed`, and
-  the end steps and answer are the same. The layout's modals and overlays show after it, one by one, before the answer.
+  the end steps and answer are the same. The layout's modals and overlays show after it, one by one, before the answer;
+  its modals are made with the root and render unseen in the modals layer, held (`ModalCoordinator.hold`), so each
+  shows in its turn without a wait of its own.
   The last `setRoot` wins: an older one is rejected (`ErrorTexts.setRootReplaced`) or finished at once.
 - **`showModal`** (`Navigator.showModal`, `ModalCoordinator.show`). One `ModalRecord` per modal; it joins the modals
   layer unseen (`ModalViews`), waits with its own `RenderWait`, then slides in (or opens as a `ModalSheet`). It shows

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

@@ -11,6 +11,7 @@ import android.view.View
 import android.view.ViewGroup
 import android.view.ViewTreeObserver
 import android.widget.EditText
+import androidx.activity.BackEventCompat
 import androidx.activity.OnBackPressedCallback
 import androidx.activity.SystemBarStyle
 import androidx.activity.enableEdgeToEdge as enableActivityEdgeToEdge
@@ -37,6 +38,7 @@ import dev.apexnative.navigation.utils.MaterialTheme
 import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackState
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigators
+import dev.apexnative.navigation.viewcontrollers.stack.StackController
 
 /**
  * The activity of an app with the navigation: its content holds, bottom to top, the copy of the splash and the layers
@@ -67,10 +69,36 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     private val reloadBroadcast = ReloadBroadcast(this) { reloadFromDeveloperTools() }
 
     // Enabled while back has something to do in the app (BackCallbackState); otherwise the system does its own back.
+    // From Android 14, where the app hears the progress of the back gesture, a gesture that would pop a stack with the
+    // default transition previews the pop as the system previews back between activities (`StackController
+    // .BackGesture`); JavaScript's listeners hear back first, so with them there is no preview.
     private val backCallback = object : OnBackPressedCallback(false) {
-        override fun handleOnBackPressed() = passBack()
+        override fun handleOnBackStarted(backEvent: BackEventCompat) {
+            backGesture = null
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE || BackCallbackState.hasJsListeners) return
+            val stack = navigator?.stackPoppedByBack() ?: return
+            backGesture = stack.startBackGesture(backEvent.swipeEdge == BackEventCompat.EDGE_LEFT, backEvent.touchY)
+        }
+
+        override fun handleOnBackProgressed(backEvent: BackEventCompat) {
+            backGesture?.progress(backEvent.progress, backEvent.touchY)
+        }
+
+        override fun handleOnBackCancelled() {
+            backGesture?.cancel()
+            backGesture = null
+        }
+
+        override fun handleOnBackPressed() {
+            val gesture = backGesture
+            backGesture = null
+            if (gesture?.commit() == true) BackCallbackState.update() else passBack()
+        }
     }
 
+    // The back gesture that previews a pop now; none.
+    private var backGesture: StackController.BackGesture? = null
+
     // Before each frame of the window: what back does may have changed, and the system decides at the start of a
     // gesture whether the app takes it.
     private val backBeforeFrame = ViewTreeObserver.OnPreDrawListener {

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

@@ -22,9 +22,13 @@ class StatusBarOptions {
     @JvmField var hideWithTopBar: Bool = NullBool()
     @JvmField var blur: Bool = NullBool()
 
-    /** The status bar is hidden, or the screen is drawn under it: the screen keeps no room for it. */
-    val isHiddenOrDrawBehind: Boolean
-        get() = visible.isFalse || drawBehind.isTrue
+    /**
+     * The status bar is hidden, or the screen is drawn under it: the screen keeps no room for it. Without `drawBehind`, a
+     * screen or a layout in an overlay ([inOverlay]) is drawn under it: an overlay covers the whole window, its dimmed
+     * backdrop the status bar too.
+     */
+    fun isHiddenOrDrawBehind(inOverlay: Boolean): Boolean =
+        visible.isFalse || if (drawBehind.hasValue()) drawBehind.isTrue else inOverlay
 
     fun hasValue(): Boolean = visible.hasValue() || style.hasValue() || backgroundColor.hasValue() ||
         drawBehind.hasValue() || translucent.hasValue() || animate.hasValue() || hideWithTopBar.hasValue() ||

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) }
+        }
+    }
+}