@apexnative/navigation 1.0.0-alpha.1 → 1.0.0-alpha.10

package/android/CORE.md

@@ -10,7 +10,7 @@ otherwise.
 ```
 JS ─ ANNTurboModule (codegen NativeANNTurboModuleSpec)
  │      sync getters answer on the JS thread from stores the main thread fills
- │      (ScreenInsets, ScreenRegions, ArrangementStates, Hinge, StartInfo)
+ │      (ScreenEnvironment, Hinge, StartInfo)
  ▼ module thread
 react/NavigationTurboModule      one override per method
  │  layout/LayoutReader ► options/OptionsReader     the whole layout read and checked, its options read
@@ -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.
 
@@ -91,7 +97,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
@@ -120,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
@@ -134,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.
@@ -164,12 +179,16 @@ 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.
-- **Error texts.** `ErrorTexts`: one function per text, the same words as iOS. JavaScript adds `[navigation] <command>:`.
+  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
+  builders of payloads use it, never a string.
 - **Room for the bars.** A screen's room at the top and bottom is `ScreenFrame` with `ScreenSafeArea` and the
   `ParentController` room hooks (`getTopInset`, `keepsStatusBarRoomOf`, …). A screen in a pair forwards its room to
   the pair (`ScreenFrame.applyRoom`), and the pair's `getTopInset` uses the screens' rule (`ScreenFrame.topRoomOf`)
-  with the options it shows with. A view's place in the window for the safe area (the React root, the stack's header
+  with the options it shows with. The bottom edge is not padded by default (only `'bottom'` in the edges pads it); `roomPadding` still shrinks the view for an opaque navigation bar and the keyboard. A view's place in the window for the safe area (the React root, the stack's header
   bottom in `headerBottomOf`, the tabs' top in `tabsTopOf`) is `RestPlace`: from layout, without translations, a sheet
   at rest.
 - **A container's own move.** A container that moves children in or out of the window without a command (the split
@@ -188,11 +207,12 @@ Modules are the feature classes that plug into the core through its contract (th
   custom row (`BottomTabsCustomRowOptions`).
 - **Views and helpers:** tabs bar (`BottomTabs`, `BottomTabItem`, `BottomTabsCollapseBehavior`, `scrollToTop`), slots
   (`SlotHost`, `SlotView`, `SlotContainers`), safe area (`SafeAreaView`), native screens (`nativescreen/`), splash
-  (`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
-  (`BackCallbackState`), stack (`PreparedFrame`).
+  (`splash/`), animations (`FadeThrough`, `SystemTransition`, `TransitionTargets`, the copies of shared elements:
+  `TextMorph`, `ViewMorph`, `ImageMorph`), utils (`MaterialTheme`, `NavigationLog`, `awaitBarComponents`,
+  `whenDrawn`).
+- **Stores and singletons:** a screen's environment (`ScreenEnvironment`: its insets and padding, its regions as
+  `ScreenRegions` measures them, its pair state), the window (`Hinge`, `WindowFolds`), links (`LaunchLink`,
+  `StartInfo`), events (`NavigationState`), commands (`BackCallbackState`), stack (`PreparedFrame`).
 
 How they plug in:
 
@@ -216,4 +236,8 @@ 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. A screen's environment is one immutable record per id in `ScreenEnvironment` (insets for JavaScript, padding,
+  regions, pair state), replaced at once; the screen's node clears it with one `remove` when it is destroyed, unless a
+  later node has its id; the padding listeners of its safe area views stay until the views stop. 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
@@ -29,11 +33,14 @@ The steps for adding an option and for adding a command to the Android core; rea
 3. The body goes to the owner of the area: `Navigator` (root, modals, overlays), `StackCommands` (stacks), a
    coordinator. A stack operation is a `StackQueue` operation.
 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).
-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
+   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`: 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`).
-7. A new event: `EventEmitter` (`emit…`), the payload type in `src/interfaces`, and for an appearance event the
-   `AppearanceDispatcher.Sender`.
+7. A new event: the payload type in `src/interfaces`, then `node scripts/contract.mjs` for its name and keys in
+   `EventContract`; `EventEmitter` (`emit…`) with those, and for an appearance event the `AppearanceDispatcher.Sender`.

package/android/consumer-rules.pro

@@ -1,2 +1,8 @@
 # The native screens `npx apex-navigation codegen` lists in the app: the navigation finds the list by its name.
 -keep class dev.apexnative.navigation.generated.ApexNavigationGeneratedScreens { *; }
+
+# The library's C++ measures a React root's content through the surface's handler, which it reads by this getter's
+# name (`android/src/main/jni/ANNContentHeights.cpp`).
+-keepclassmembers class com.facebook.react.runtime.ReactSurfaceImpl {
+    com.facebook.react.fabric.SurfaceHandlerBinding getSurfaceHandler();
+}

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
@@ -34,9 +35,12 @@ 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.modal.SheetBack
+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
+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,14 +71,75 @@ 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`), and one that would dismiss a sheet previews its hide as Material's sheets do (`SheetBack`), its
+    // release closing it as a drag down does; 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
+            sheetGesture = null
+            val navigator = navigator ?: return
+            backCheck?.atBack(navigator)
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE || BackCallbackState.hasJsListeners) return
+            val stack = navigator.stackPoppedByBack()
+            if (stack != null) {
+                backGesture = stack.startBackGesture(backEvent.swipeEdge == BackEventCompat.EDGE_LEFT, backEvent.touchY)
+                return
+            }
+            sheetGesture = navigator.sheetDismissedByBack()?.startBackPreview(backEvent)
+        }
+
+        override fun handleOnBackProgressed(backEvent: BackEventCompat) {
+            backGesture?.progress(backEvent.progress, backEvent.touchY)
+            sheetGesture?.progress(backEvent)
+        }
+
+        override fun handleOnBackCancelled() {
+            backGesture?.cancel()
+            backGesture = null
+            sheetGesture?.cancel()
+            sheetGesture = null
+            navigator?.let(BackCallbackState::update)
+        }
+
+        override fun handleOnBackPressed() {
+            navigator?.let { backCheck?.atBack(it) }
+            val gesture = backGesture
+            backGesture = null
+            val sheet = sheetGesture
+            sheetGesture = null
+            when {
+                gesture?.commit() == true -> BackCallbackState.update()
+                sheet != null && commitSheet(sheet) -> BackCallbackState.update()
+                else -> passBack()
+            }
+        }
     }
 
-    // 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)
+    // The back gesture that previews a pop now; none.
+    private var backGesture: StackController.BackGesture? = null
+
+    // The back gesture that previews a sheet's hide now; none.
+    private var sheetGesture: SheetBack.Gesture? = null
+
+    // A sheet's preview released: the sheet goes as the user's drag down closes it, and back doesn't go on (no
+    // `passBack`, which would dismiss it a second time). A command that changed what back does since the gesture
+    // started (a push in the sheet, a modal over it, a hold) leaves it to the usual back, the sheet back in place.
+    private fun commitSheet(gesture: SheetBack.Gesture): Boolean {
+        if (navigator?.sheetDismissedByBack() !== gesture.sheet) {
+            gesture.cancel()
+            return false
+        }
+        return gesture.commit()
+    }
+
+    // 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
@@ -115,7 +180,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))
@@ -190,6 +257,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)
     }
@@ -211,6 +280,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() {
@@ -274,9 +345,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()
@@ -289,7 +362,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/BottomTabOptions.kt

@@ -105,7 +105,7 @@ class BottomTabOptions {
     @JvmField var textColor: ThemeColour = NullThemeColour()
     @JvmField var selectedIconColor: ThemeColour = NullThemeColour()
     @JvmField var selectedTextColor: ThemeColour = NullThemeColour()
-    @JvmField var font = FontOptions()
+    @ReadFromParent @JvmField var font = FontOptions()
     @JvmField var fontSize: Fraction = NullFraction()
     @JvmField var selectedFontSize: Fraction = NullFraction()
     @JvmField var iconInsets = IconInsetsOptions()

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

@@ -95,6 +95,7 @@ class BottomTabsAccessoryOptions {
 class BottomTabsOptions {
     @JvmField var visible: Bool = NullBool()
     @JvmField var animate: Bool = NullBool()
+    @JvmField var switchAnimation: Text = NullText()
     /** Selects a tab once; a whole number, truncated where it is read. */
     @JvmField var currentTabIndex: Fraction = NullFraction()
     /** Selects a tab once. */
@@ -124,18 +125,19 @@ class BottomTabsOptions {
     @JvmField var minimizeBehavior: Text = NullText()
     @JvmField var bottomAccessory = BottomTabsAccessoryOptions()
 
-    fun hasValue(): Boolean = visible.hasValue() || animate.hasValue() || currentTabIndex.hasValue() ||
-        currentTabId.hasValue() || testID.hasValue() || accessibilityLabel.hasValue() || moreTestID.hasValue() ||
-        drawBehind.hasValue() || backgroundColor.hasValue() || tabsAttachMode.hasValue() || barStyle.hasValue() ||
-        layoutStyle.hasValue() || cornerRadius.hasValue() || bottomMargin.hasValue() || translucent.hasValue() ||
-        hideShadow.hasValue() || titleDisplayMode.hasValue() || elevation.hasValue() || hideOnScroll.hasValue() ||
-        borderColor.hasValue() || borderWidth.hasValue() || shadow.hasValue() || customRow.hasValue() ||
-        sidebar.hasValue() || sidebarLayout.hasValue() || customizationId.hasValue() || minimizeBehavior.hasValue() ||
-        bottomAccessory.hasValue()
+    fun hasValue(): Boolean = visible.hasValue() || animate.hasValue() || switchAnimation.hasValue() ||
+        currentTabIndex.hasValue() || currentTabId.hasValue() || testID.hasValue() || accessibilityLabel.hasValue() ||
+        moreTestID.hasValue() || drawBehind.hasValue() || backgroundColor.hasValue() || tabsAttachMode.hasValue() ||
+        barStyle.hasValue() || layoutStyle.hasValue() || cornerRadius.hasValue() || bottomMargin.hasValue() ||
+        translucent.hasValue() || hideShadow.hasValue() || titleDisplayMode.hasValue() || elevation.hasValue() ||
+        hideOnScroll.hasValue() || borderColor.hasValue() || borderWidth.hasValue() || shadow.hasValue() ||
+        customRow.hasValue() || sidebar.hasValue() || sidebarLayout.hasValue() || customizationId.hasValue() ||
+        minimizeBehavior.hasValue() || bottomAccessory.hasValue()
 
     fun mergeWith(other: BottomTabsOptions) {
         if (other.visible.hasValue()) visible = other.visible
         if (other.animate.hasValue()) animate = other.animate
+        if (other.switchAnimation.hasValue()) switchAnimation = other.switchAnimation
         if (other.currentTabIndex.hasValue()) currentTabIndex = other.currentTabIndex
         if (other.currentTabId.hasValue()) currentTabId = other.currentTabId
         if (other.testID.hasValue()) testID = other.testID
@@ -167,6 +169,7 @@ class BottomTabsOptions {
     fun mergeWithDefault(defaults: BottomTabsOptions) {
         if (!visible.hasValue()) visible = defaults.visible
         if (!animate.hasValue()) animate = defaults.animate
+        if (!switchAnimation.hasValue()) switchAnimation = defaults.switchAnimation
         if (!currentTabIndex.hasValue()) currentTabIndex = defaults.currentTabIndex
         if (!currentTabId.hasValue()) currentTabId = defaults.currentTabId
         if (!testID.hasValue()) testID = defaults.testID
@@ -198,6 +201,7 @@ class BottomTabsOptions {
     fun copy() = BottomTabsOptions().also { it.mergeWith(this) }
 
     companion object {
+        private val SWITCH_ANIMATIONS = setOf("platform", "none")
         private val TABS_ATTACH_MODES = setOf("together", "afterInitialTab", "onSwitchToTab")
         private val BAR_STYLES = setOf("default", "black")
         private val LAYOUT_STYLES = setOf("stretch", "compact")
@@ -212,6 +216,7 @@ class BottomTabsOptions {
             if (map == null) return options
             options.visible = BoolParser.parse(map, "visible")
             options.animate = BoolParser.parse(map, "animate")
+            options.switchAnimation = TextParser.parse(map, "switchAnimation", SWITCH_ANIMATIONS)
             options.currentTabIndex = FractionParser.parse(map, "currentTabIndex")
             options.currentTabId = TextParser.parse(map, "currentTabId")
             options.testID = TextParser.parse(map, "testID")

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

@@ -31,7 +31,7 @@ class ButtonOptions(@JvmField var id: Text = NullText()) {
     @JvmField var systemItem: Text = NullText()
     @JvmField var text: Text = NullText()
     @JvmField var accessibilityLabel: Text = NullText()
-    @JvmField var font = FontOptions()
+    @ReadFromParent @JvmField var font = FontOptions()
     @JvmField var fontSize: Fraction = NullFraction()
     @JvmField var enabled: Bool = NullBool()
     @JvmField var disableIconTint: Bool = NullBool()
@@ -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)