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

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.0.0-alpha.5](https://github.com/apexnative/navigation/compare/v1.0.0-alpha.4...v1.0.0-alpha.5) (2026-10-23)
+
+
+### Features
+
+* android back options, a launch screen copy from UILaunchScreen, modal and back fixes ([#43](https://github.com/apexnative/navigation/issues/43)) ([29f311e](https://github.com/apexnative/navigation/commit/29f311e318134f284a0c6279e6c86e15612c9343))
+
+
+### Bug Fixes
+
+* **android:** send the state of a tab switch from code at its start ([#44](https://github.com/apexnative/navigation/issues/44)) ([34d03d0](https://github.com/apexnative/navigation/commit/34d03d0214cf09e14329d0bae51e47d46063f054))
+* **hooks:** measure agent folder scopes from the worktree a file is in ([#42](https://github.com/apexnative/navigation/issues/42)) ([d306137](https://github.com/apexnative/navigation/commit/d306137534d3ba551fab8a7346c7ad7300c0faf7))
+
+## [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,10 +21,11 @@ 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`.
+  `scripts/contract.mjs`), `NavigationState`, `ComponentType`.
 - `viewcontrollers/viewcontroller/`: `ViewController` (the base of every node), `Presenter`, `IReactView` (what a
   screen shows), `ScrollEventListener`.
 - `viewcontrollers/child/`, `parent/`: `ChildController` and the registry; `ParentController` (the base of layouts),
@@ -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.
@@ -103,15 +105,17 @@ top-level folder. Main thread only, unless a line says otherwise.
 - System bars: `system/SystemUiOwner.kt`, `SystemUiLayers.kt`, `SystemUiRules.kt`, `SystemUiWindow.kt`,
   `AppDirection.kt`; `viewcontrollers/parent/ContainerBackground.kt`.
 - Events and state: `react/events/AppearanceDispatcher.kt`, `ScreenAppearance.kt`, `EventEmitter.kt`,
-  `NavigationStateReporter.kt`; `react/CommandAnswer.kt`.
+  `NavigationState.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,13 +163,18 @@ 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;
   `cancel` it on every exit.
 - A layer that waits to show must be a `WaitingLayer` and leave on every exit (show, supersede, destroy, root gone).
 - Never resolve a promise yourself: only `CommandAnswer` knows whether its JavaScript went and sends the state first.
+- An event of a screen goes to the JavaScript the screen was made for: `EventEmitter.of(node.jsGeneration)`, or an
+  emitter kept from then (it goes silent after a reload). React Native keeps one context across a reload, so a sender
+  taken from the context at event time tells the new JavaScript about a screen it never had.
 - A signal that comes inside a layout pass or a view's attach must not move views there; the stack posts readiness
   (`deliver`).
 - A step that runs later (a timer, a readiness signal, an animator's end, a user callback) runs under no runner: it
@@ -196,6 +209,10 @@ top-level folder. Main thread only, unless a line says otherwise.
 - 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.
+- What back does (`Navigator.canHandleBack`, `keepsBackFromSystem`) is computed on events, not before each frame: a
+  new path that changes it without a command (a gesture, an animator's end, a layout's switch) calls
+  `BackCallbackState.update`, or the system's back leaves the app where it should go back. Debug builds log a missed
+  one (`BackCallbackCheck`).
 - 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

@@ -31,7 +31,7 @@ coordinators: RootCoordinator · StackQueue (one per stack) · ModalCoordinator
 presenters: ComponentPresenter · StackPresenter + TopBarPresenter · BottomTabsPresenter · SideMenuPresenter ·
             SplitViewPresenter · system/SystemUiOwner (status bar, navigation bar, orientation, keyboard)
  ▼
-react/events/AppearanceDispatcher ─► NavigationStateReporter ─► EventEmitter ─► ANN.* events ─► JS
+react/events/AppearanceDispatcher ─► NavigationState ─► EventEmitter ─► ANN.* events ─► JS
 ```
 
 - **Way in.** `NavigationTurboModule` only turns a method into a `CommandRunner` call; it holds no navigation logic. It
@@ -72,18 +72,24 @@ 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
    (`StackTransitions`, `SystemTransition`, or the screens' own animation, `AnimationRules.stackIsOwn`).
 8. **End.** `finishPush` calls `AppearanceDispatcher.endTransition`: **`ComponentDidDisappear`** of Home, then
-   **`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
-   back does.
+   **`ComponentDidAppear`** of Profile, then the answer's one state step (`CommandAnswer.reportStateNow`:
+   **`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 only when no transition sent it (`reportStateNow` runs once per answer: a
+   `setRoot` with layout modals sends it here), resolves the promise, 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.
 
@@ -122,13 +128,16 @@ Each rule has one owner. Change the owner, not a caller; if a new feature needs
   `beginTransition` starts the appearances; `endTransition` runs what left, then what came, then the state, then the
   transition's events, then the answer. Events asked before a screen's content is ready are held in its
   `ScreenAppearance` (until the content mounts or `HOLD_LIMIT_MILLIS`).
-- **Navigation state.** `AppearanceDispatcher.state` (`StateUpdates`) is the one way to ask for it: `StateHold`
-  coalesces the asks to one posted update per pass of the main loop and keeps it while held; the update calls
-  `NavigationStateReporter.updateNow`. `updateNow` also runs before every answer of a command that changes what shows
-  (`CommandAnswer`) and is never held. It reads the navigator through `Navigators.current()`, and `stateOf` finds the
+- **Navigation state.** `NavigationState` owns it: the last state sent, the walk (`stateOf`), the posted update and its
+  holds (`NavigationState.Updates`). `AppearanceDispatcher.state` (`StateUpdates`) is the one way to ask for it:
+  `setNeedsUpdate` coalesces the asks to one posted update per pass of the main loop and keeps it while held; the
+  update calls `updateNow`. A command's answer sends it once, at once and never held (`CommandAnswer.reportStateNow`):
+  at the end of its transition, else right before its promise for the commands that change what shows; nothing for a
+  JavaScript that went. It reads the navigator through `Navigators.current()`, and `stateOf` finds the
   `tab` as the nearest tabs of the visible screen (the last tabs met walking down from the visible layout). A `setRoot`
   with layout modals or overlays takes `AppearanceDispatcher.StateUpdates.hold()` and releases it right before its
-  answer, so JavaScript hears one state; every hold has one `release()`.
+  answer, so JavaScript hears one state; every hold has one `release()`. The holds go when the JavaScript goes
+  (`NavigationState.javaScriptWent`), so one left by its `setRoot` never holds the next JavaScript's updates.
 - **Answer.** `CommandAnswer`: resolves or rejects once, and nothing once the JavaScript went. The id a stack entry
   answers with is one rule, `StackController.answerIdOf` (the queue asks it through `StackQueue.Host.answerIdOf` with
   an `AnswerKind`): `push` answers the entry's own id (a pair's), every other command the screen it stands for (a
@@ -136,7 +145,11 @@ Each rule has one owner. Change the owner, not a caller; if a new feature needs
 - **Stack queue.** `StackQueue`: every command, back and return of a container goes through it; it keeps `entries`
   (what JavaScript sees) and `shown` (what the container shows) and answers once.
 - **Screen readiness.** `ScreenReadiness` (by id; written by `SafeAreaView`) and `ContentReadiness` (the `Readiness`
-  the waits ask, through `IReactView.isReady`).
+  the waits ask, through `IReactView.isReady`). As on iOS, the signals are kept (a listener that comes later hears them
+  at once), an id has a listener per key (several roots of one bar component), and each signal carries the React
+  surface it came from: a `ReactView` takes only its own surface's, so an old root with the same id never makes a new
+  one ready. An id renders at once while a root marks it (`ReactView`'s `rendersAtOnce`); the last one takes the id's
+  signals with it. A screen's id is cleared as the screen is made and destroyed, everything on reload.
 - **Render wait.** `RenderWait`: the one wait for screens to render, used by `RootCoordinator`, `ModalCoordinator`,
   `OverlayCoordinator` and `StackQueue`; `RenderWait.waitedScreens` walks `ParentController.waitedChildren()` at every
   level. What differs between users are values (limit, bar phase, unknown-content rule), never steps.
@@ -166,7 +179,8 @@ Each rule has one owner. Change the owner, not a caller; if a new feature needs
 - **Back.** `NavigationActivity.passBack` → `ReactGateway.onBackPressed` (JavaScript's `BackHandler`) →
   `invokeDefaultOnBackPressed` → `Navigator.handleBack` → `ModalCoordinator.handleBack` → the root's
   `ParentController.handleBack` → `StackController.handleBack` → `StackQueue.cut`. `BackCallbackState` keeps the
-  system callback enabled only while back has something to do.
+  system callback enabled only while back has something to do, computed again on the events that change it (its KDoc
+  lists them), never before each frame; debug builds check it (`BackCallbackCheck`).
 - **Error texts.** `ErrorTexts`: one function per text, the same words as iOS, made with iOS's from
   `src/interfaces/contract/errors.json` (`scripts/contract.mjs`). JavaScript adds `[navigation] <command>:`.
 - **Event names and keys.** `EventContract`, made from the event types of `src/interfaces/`; `EventEmitter` and the
@@ -196,7 +210,7 @@ Modules are the feature classes that plug into the core through its contract (th
   (`splash/`), animations (`FadeThrough`, `SystemTransition`, `TransitionTargets`, three element animators), utils
   (`MaterialTheme`, `NavigationLog`, `awaitBarComponents`, `whenDrawn`).
 - **Stores and singletons:** regions (`Hinge`, `ScreenInsets`, `ScreenRegions`, `WindowFolds`), pair state
-  (`ArrangementStates`), links (`LaunchLink`, `StartInfo`), events (`NavigationStateReporter`), commands
+  (`ArrangementStates`), links (`LaunchLink`, `StartInfo`), events (`NavigationState`), commands
   (`BackCallbackState`), stack (`PreparedFrame`).
 
 How they plug in:
@@ -221,4 +235,5 @@ How they plug in:
 - **Core code in a module's folder:** `viewcontrollers/splitview/SplitViewPresenter.kt`, `slots/SlotScreenView.kt`,
   and in `views/animations/` and `views/element/` everything except the files named above.
 - **Stores** are written on the main thread by the core and read from any thread; they are cleared with their nodes and on
-  reload.
+  reload. Their events, and the search's, go through the emitter of the JavaScript the screen was made for
+  (`EventEmitter.of(node.jsGeneration)`); the hinge keeps the `EventEmitter.current()` of the call that turned it on.

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

@@ -35,6 +35,7 @@ import dev.apexnative.navigation.splash.SplashTheme
 import dev.apexnative.navigation.splash.SplashView
 import dev.apexnative.navigation.system.SystemUiWindow
 import dev.apexnative.navigation.utils.MaterialTheme
+import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackCheck
 import dev.apexnative.navigation.viewcontrollers.navigator.BackCallbackState
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigator
 import dev.apexnative.navigation.viewcontrollers.navigator.Navigators
@@ -75,6 +76,7 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     private val backCallback = object : OnBackPressedCallback(false) {
         override fun handleOnBackStarted(backEvent: BackEventCompat) {
             backGesture = null
+            navigator?.let { backCheck?.atBack(it) }
             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)
@@ -87,9 +89,11 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
         override fun handleOnBackCancelled() {
             backGesture?.cancel()
             backGesture = null
+            navigator?.let(BackCallbackState::update)
         }
 
         override fun handleOnBackPressed() {
+            navigator?.let { backCheck?.atBack(it) }
             val gesture = backGesture
             backGesture = null
             if (gesture?.commit() == true) BackCallbackState.update() else passBack()
@@ -99,10 +103,12 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     // 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 {
-        navigator?.let(BackCallbackState::update)
+    // Debug builds only: the check that what back does never changes without its trigger (BackCallbackState), sampled
+    // before frames and at back events. It only logs; release builds have neither the check nor the listener.
+    private val backCheck = if (BuildConfig.DEBUG) BackCallbackCheck() else null
+    private val backCheckBeforeFrame = ViewTreeObserver.OnPreDrawListener {
+        val navigator = navigator
+        if (navigator != null) backCheck?.sample(navigator, SystemClock.uptimeMillis())
         true
     }
     private var frameObserver: ViewTreeObserver? = null
@@ -143,7 +149,9 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
         SlotHost.attachIfStarted(this)
         reactGateway.onActivityCreated(this)
         onBackPressedDispatcher.addCallback(this, backCallback)
-        frameObserver = window.decorView.viewTreeObserver.also { it.addOnPreDrawListener(backBeforeFrame) }
+        if (backCheck != null) {
+            frameObserver = window.decorView.viewTreeObserver.also { it.addOnPreDrawListener(backCheckBeforeFrame) }
+        }
         // The activity's system UI: its owner remembers the theme's colors and the manifest's orientation now, before
         // anything changes them.
         navigator.systemUi.start(SystemUiWindow.of(this))
@@ -218,6 +226,8 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
         isNavigationResumed = true
         // The root, the modals and the overlays lay out again; nothing is sent.
         navigator?.onResume()
+        // A safety net: what back does changes on its own triggers, and the system asks the callback from here on.
+        navigator?.let(BackCallbackState::update)
         if (developerSupport() != null) reloadBroadcast.register()
         ReloadCoordinator.launchIfDue(this)
     }
@@ -239,6 +249,8 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     override fun onWindowFocusChanged(hasFocus: Boolean) {
         super.onWindowFocusChanged(hasFocus)
         if (reactGateway.currentReactContext != null) reactGateway.host.onWindowFocusChange(hasFocus)
+        // A safety net, as at onResume: back after a dialog or another window over the activity.
+        if (hasFocus) navigator?.let(BackCallbackState::update)
     }
 
     override fun onUserLeaveHint() {
@@ -302,9 +314,11 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
         splashHold = null
         reloadBroadcast.release()
         navigator?.let(BackCallbackState::detach)
-        // The window's observer now, and the one the listener was added to, if they differ.
-        val observers = listOfNotNull(frameObserver, window?.peekDecorView()?.viewTreeObserver).distinct()
-        observers.forEach { if (it.isAlive) it.removeOnPreDrawListener(backBeforeFrame) }
+        // The debug check's listener: from the window's observer now, and the one it was added to, if they differ.
+        if (backCheck != null) {
+            val observers = listOfNotNull(frameObserver, window?.peekDecorView()?.viewTreeObserver).distinct()
+            observers.forEach { if (it.isAlive) it.removeOnPreDrawListener(backCheckBeforeFrame) }
+        }
         frameObserver = null
         SlotHost.detach(this)
         navigator?.destroyWithActivity()
@@ -317,7 +331,9 @@ open class NavigationActivity : AppCompatActivity(), DefaultHardwareBackBtnHandl
     /**
      * Back that JavaScript's listeners didn't take: the navigation does its step first — a stack's top leaves or holds,
      * a pane closes —; with nothing to do there, the activity's own back, as without the navigation. An app may
-     * override it (e.g. `moveTaskToBack(true)`).
+     * override it (e.g. `moveTaskToBack(true)`). The callback is off for that back only: the dispatcher's own back is
+     * the activity's, not [onBackPressed]; then it is computed again, and `hardwareBackButton.systemAnimation: false`
+     * turns it on again.
      */
     override fun invokeDefaultOnBackPressed() {
         val handled = navigator?.handleBack(CommandListenerAdapter()) == true

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

@@ -8,7 +8,7 @@ import com.facebook.react.bridge.ReadableMap
  */
 class AnimationsOptions {
     @JvmField var push = StackPushAnimationOptions()
-    @JvmField var pop = StackAnimationOptions()
+    @JvmField var pop = StackPopAnimationOptions()
     @JvmField var setStackRoot = SetStackRootAnimationOptions()
     @JvmField var setRoot = EnterExitAnimationOptions()
     @JvmField var showModal = ModalAnimationOptions()
@@ -43,7 +43,7 @@ class AnimationsOptions {
             val options = AnimationsOptions()
             if (map == null) return options
             options.push = map.group("push") { StackPushAnimationOptions.parse(it) }
-            options.pop = map.group("pop") { StackAnimationOptions.parse(it) }
+            options.pop = map.group("pop") { StackPopAnimationOptions.parse(it) }
             options.setStackRoot = map.group("setStackRoot") { SetStackRootAnimationOptions.parse(it) }
             options.setRoot = map.group("setRoot") { EnterExitAnimationOptions.parse(it) }
             options.showModal = map.group("showModal") { ModalAnimationOptions.parse(it) }

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

@@ -15,20 +15,27 @@ class HardwareBackButtonOptions {
     @JvmField var popStackOnPress: Bool = NullBool()
     /** Internal. */
     @JvmField var dismissModalOnPress: Bool = NullBool()
+    /**
+     * `systemAnimation`: `false` keeps back in the app on the first screen too, so the system doesn't play its
+     * animation of going home; the press then does the activity's own back.
+     */
+    @JvmField var systemAnimation: Bool = NullBool()
 
     fun hasValue(): Boolean = bottomTabsOnPress.hasValue() || popStackOnPress.hasValue() ||
-        dismissModalOnPress.hasValue()
+        dismissModalOnPress.hasValue() || systemAnimation.hasValue()
 
     fun mergeWith(other: HardwareBackButtonOptions) {
         if (other.bottomTabsOnPress.hasValue()) bottomTabsOnPress = other.bottomTabsOnPress
         if (other.popStackOnPress.hasValue()) popStackOnPress = other.popStackOnPress
         if (other.dismissModalOnPress.hasValue()) dismissModalOnPress = other.dismissModalOnPress
+        if (other.systemAnimation.hasValue()) systemAnimation = other.systemAnimation
     }
 
     fun mergeWithDefault(defaults: HardwareBackButtonOptions) {
         if (!bottomTabsOnPress.hasValue()) bottomTabsOnPress = defaults.bottomTabsOnPress
         if (!popStackOnPress.hasValue()) popStackOnPress = defaults.popStackOnPress
         if (!dismissModalOnPress.hasValue()) dismissModalOnPress = defaults.dismissModalOnPress
+        if (!systemAnimation.hasValue()) systemAnimation = defaults.systemAnimation
     }
 
     fun copy() = HardwareBackButtonOptions().also { it.mergeWith(this) }
@@ -43,6 +50,7 @@ class HardwareBackButtonOptions {
             options.bottomTabsOnPress = TextParser.parse(map, "bottomTabsOnPress", BOTTOM_TABS_ON_PRESS)
             options.popStackOnPress = BoolParser.parse(map, "popStackOnPress")
             options.dismissModalOnPress = BoolParser.parse(map, "dismissModalOnPress")
+            options.systemAnimation = BoolParser.parse(map, "systemAnimation")
             return options
         }
     }

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