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

package/docs-md/architecture/transitions.md

@@ -46,6 +46,8 @@ navigation.showModal('Player', {
 });
 ```
 
+The top bar of a pushed screen goes with the screen on Android and stays in place on iOS: see [the bar in a transition of your own](#custom-bar).
+
 `presentation` of `createNavigation` gives every push or modal of the app its transition: see [Defaults for the whole app](../fundamentals/moving-between-screens#presentation). New roots have presets of their own: see [How a new root comes in](../fundamentals/switching-roots#transitions).
 
 ## Transitions out of a view
@@ -144,7 +146,11 @@ navigation.push('Details', {
 
 Details rises 300 points as it fades in. Each property animates from a value to a value over a time, with a delay and an interpolation if it needs them; the [API](#api) lists every one.
 
-The same goes for `pop`, `showModal`, `dismissModal`, `setStackRoot` and `setRoot`. The swipe back is the exception: (iOS) it always follows the finger with the system's slide, so a custom `pop` plays for the back button and `pop()` only.
+The same goes for `pop`, `showModal`, `dismissModal`, `setStackRoot` and `setRoot`. The swipe back is the exception: (iOS) it always follows the finger with the system's slide, so a custom `pop` plays for the back button and `pop()` only. (Android) A pop with an animation of its own shows no preview under the swipe: the screen pops when the swipe ends.
+
+### The top bar
+
+The top bar goes its platform's way in a preset or an animation of your own. (Android) It goes with its screen, as if it were part of it: with `slideUp` the new screen comes up with its bar over the old one and its bar, and on the way back it goes down with its bar, uncovering the bar below. With `fade` or `scale` the bar fades or grows with its screen. (iOS) UIKit keeps the bar in place and changes its title and buttons as the transition starts; only the screens under it move.
 
 ## Which to pick
 
@@ -162,11 +168,10 @@ A screen can come in before its React content has drawn, or wait for it. Coming
 
 | | By default |
 | --- | --- |
-| (iOS) push | Doesn't wait for the content: the screen slides in with its bar, and the content draws as it comes. It waits only for components in the bar. |
-| (Android) push | Doesn't wait. With `appProvider` a React screen is rendered before the push starts, so it comes in drawn from the first frame. A screen with a React root of its own comes in at once, and its content draws as it comes; so does a native screen. The components of the bar draw as the screen comes in. |
+| Push | Waits for the screen's first mount, half a second at most, so it comes in drawn, with what it set as it rendered (a title from `useScreenOptions`) already in its bar. A native screen comes in at once. (iOS) The components of the bar wait too, each to its own limit from the start of the wait. (Android) The components of the bar draw as the screen comes in; with `appProvider` the screen is rendered before the push starts ([below](#wait-one-tree)). |
 | (Android) modal | Waits for the content and the components of the bar, half a second at most, so the screen comes in drawn. |
 
-`waitForRender` of an animation changes it. `true` waits as long as it takes; `false` comes in at once (a push on Android with `appProvider` [still renders the screen first](#wait-one-tree)):
+`waitForRender` of an animation changes it. `true` waits as long as it takes; `false` comes in at once, the content drawing as it comes (a push on Android with `appProvider` [still renders the screen first](#wait-one-tree)):
 
 ```ts
 navigation.push('Details', {
@@ -174,15 +179,15 @@ navigation.push('Details', {
 });
 ```
 
-A screen that draws nothing at first doesn't hold its transition back: it comes in empty, with its bar.
+A screen that draws nothing at first holds its transition back half a second at most, then comes in with its bar.
 
 ### A push on Android, in one tree
 
-(Android) With `appProvider` a push doesn't wait for the screen, and the screen still comes in drawn: nothing of it mounts during the transition, which would drop frames. It goes in three steps:
+(Android) With `appProvider` the screen comes in drawn without a wait of its own: nothing of it mounts during the transition, which would drop frames. It goes in three steps:
 
 1. The native side lays the screen out in its stack, out of sight, and gives React its size and its safe area.
 2. React renders the screen at that size with its content, at once.
-3. The push starts in the frame in which that content appears; if it doesn't appear, after half a second.
+3. The push starts right after that content appears, once what the screen set as it rendered (its `useScreenOptions`) is applied; if it doesn't appear, after half a second.
 
 So the push starts later by the time React takes to render the screen, as a push in a native app starts once its screen is built. `waitForRender: false` goes the same way here; `true` waits for the content as long as it takes, and for the components of the bar, half a second at most.
 

package/docs-md/containers/modals.md

@@ -70,6 +70,8 @@ navigation.showModal('Compose', { style: 'fullScreen' });
 
 Without `style`, a modal is a sheet on (iOS) and covers the whole screen on (Android).
 
+`'pageSheet'` and `'formSheet'` are sheets on both platforms: on (Android) the Material bottom sheet over the dimmed screen, at the full height under the status bar and at most 640 dp wide. `'fullScreen'` and `'overFullScreen'` come up from the bottom over the whole screen; on Android with the system's motion of a window opening over another, without a fade.
+
 `'overFullScreen'` keeps the screen under the modal in place, so it shows through wherever the modal draws nothing: a dialog of your own, a card over a dimmed app. Give the modal's screen `backgroundColor('transparent')` in its options, so its own background doesn't hide the screen under it.
 
 ### A form on iPad
@@ -83,7 +85,7 @@ navigation.showModal('EditProfile', {
 });
 ```
 
-On iPhone a form sheet is a sheet, and `contentSize` does nothing.
+On iPhone and on Android a form sheet is a sheet, and `contentSize` does nothing.
 
 ### A popover
 
@@ -95,7 +97,7 @@ navigation.showModal('Filters', {
 });
 ```
 
-On iPhone it becomes a sheet, unless `adaptive: false` keeps it a popover. (Android) has no popovers: the modal covers the whole screen, as without `style`.
+On iPhone it becomes a sheet, unless `adaptive: false` keeps it a popover. (Android) has no popovers: the modal is the bottom sheet of `'pageSheet'`.
 
 ## Sheets
 

package/docs-md/containers/overlays.md

@@ -24,7 +24,9 @@ This page answers:
 
 A push or a modal moves the user somewhere. An overlay doesn't move anyone: it puts a screen **on top of everything**, and the app goes on under it.
 
-An overlay is a screen of `screens` like any other: a component, its props, its options. It shows above the tabs, the bars and the modals; on (iOS) it is in a window of its own. Its background is transparent, so the app shows wherever the overlay draws nothing. What overlays are for:
+An overlay is a screen of `screens` like any other: a component, its props, its options. It shows above the tabs, the bars and the modals; on (iOS) it is in a window of its own. Its background is transparent, so the app shows wherever the overlay draws nothing.
+
+An overlay covers the whole window, **the status bar included**: a dialog's dimmed backdrop dims the status bar too, as a system dialog does. Its safe area keeps the content off the bars, so a toast at the top of the overlay sits below the status bar. On (Android) a status bar with a color of its own (`statusBar.backgroundColor`) stays over the backdrop, and `statusBar.drawBehind: false` starts the overlay below the status bar. What overlays are for:
 
 ## Showing and closing
 

package/docs-md/containers/side-menu.md

@@ -74,7 +74,7 @@ A tap on the button opens the menu. A button of the options gets the navigation
 
 ## A pick in the menu
 
-A menu is a screen without a stack, so **its commands act on the center**, and the menu closes once the center has changed. A pick usually switches the section, so the center starts over with it:
+A menu is a screen without a stack, so **its commands act on the center**, and the menu closes as the center changes: it starts to slide away at the tap, and a push slides in as it goes. The command resolves once both are done. A pick usually switches the section, so the center starts over with it:
 
 ```tsx
 import { Button, View } from 'react-native';
@@ -94,7 +94,7 @@ function Menu() {
 }
 ```
 
-A tap on Settings shows Settings in the center, and the menu closes. Which command to use depends on the way back:
+A tap on Settings closes the menu and shows Settings in the center as it goes. Which command to use depends on the way back:
 
 | From the menu | The center |
 | --- | --- |
@@ -108,6 +108,8 @@ A tap on Settings shows Settings in the center, and the menu closes. Which comma
 | (iOS) | Over the content, which dims: `openMode: 'aboveContent'` of the side, the default. Or under it, with the content moved aside: `'pushContent'`. Then `animation(…)` says how the menu appears: `'parallax'`, `'slide'`, `'slide-and-scale'` or `'door'`. |
 | (Android) | The drawer of the platform: over the content, which dims. |
 
+The menu's color is its screen's `layout.backgroundColor`: it fills the whole height of the menu, behind the status bar and the navigation bar, while the menu's content keeps clear of them. A background on the React content stops at the safe area.
+
 `.ios()` keeps the settings that only iOS has apart from the others:
 
 ```ts

package/docs-md/containers/tabs.md

@@ -90,6 +90,8 @@ This is the app's `navigation`: its `push` goes to the stack the user sees, now
 
 Inbox shows, and Chat comes in over it, in the stack of the Inbox tab.
 
+On (Android) the content changes with Material's fade through, as in the system's Phone app: the tab that goes fades out, then the new one fades in and grows to its size, in 300 ms; the tab bar stays. On (iOS) the new tab shows at once, as the system's tab bar does.
+
 ### A press on a tab
 
 A second tap on the selected tab is a convention of both platforms: **back to the start of the tab**. The navigation does it without code:

package/docs-md/flows/forms-in-a-modal.md

@@ -299,7 +299,7 @@ navigation.showModal('EditProfile', {
 });
 ```
 
-On iPhone a form sheet is the same sheet as before, and on Android the modal is unchanged.
+On iPhone a form sheet is the same sheet as before. On Android it is the Material bottom sheet, where the modal without a style covered the whole screen.
 
 ## The whole code
 

package/docs-md/help/glossary.md

@@ -266,7 +266,7 @@ Two screens shown as one entry of a stack: the primary, whose bar shows, and the
 
 ### Popover
 
-(iPadOS) A modal that points at the bar button or the view that opened it. On iPhone it becomes a sheet; on Android the modal covers the screen. More: [A popover](../containers/modals#popover).
+(iPadOS) A modal that points at the bar button or the view that opened it. On iPhone and on Android it becomes a sheet. More: [A popover](../containers/modals#popover).
 
 ### Presentation
 
@@ -370,7 +370,7 @@ The system bar at the top of the screen, with the time and the battery. Each scr
 
 ### Swipe back
 
-(iOS) The swipe from the left edge, and on iOS 26 from the content, that goes back following the finger. `popGesture` narrows it or turns it off. More: [The swipe back](../screen-ui/back-and-gestures#swipe).
+(iOS) The swipe from the left edge, and on iOS 26 from the content, that goes back following the finger. `popGesture` narrows it or turns it off. (Android) 14+ The swipe of the system back shows the pop under the finger, and the user can stop halfway. More: [The swipe back](../screen-ui/back-and-gestures#swipe).
 
 ### System back
 

package/docs-md/help/troubleshooting.md

@@ -73,13 +73,30 @@ Options set in `static options` on a component no longer apply.
 
 **Fix:** move them into `defineScreen({ component, options })`; the object carries over as it is. More: [Options next to the screen](../migration/from-react-native-navigation#options).
 
+### The Android app crashes at start: React Native isn't loaded
+
+(Android) The app closes at once with `NavigationApplication needs React Native loaded first`, and `doctor` reports `MainApplication.kt doesn't call loadReactNative(this) in onCreate`.
+
+**Why:** `NavigationApplication` leaves the load of React Native to the template's `loadReactNative(this)`, which loads it as the app's Gradle files say (the New Architecture, edge-to-edge). Without the call nothing loads it.
+
+**Fix:** keep the template's `onCreate`, or run `npx apex-navigation setup`, which adds it:
+
+```kotlin
+override fun onCreate() {
+  super.onCreate()
+  loadReactNative(this)
+}
+```
+
+More: [Android files](../start/installation#android-files).
+
 ### The Android app crashes at start: React Native loads twice
 
-(Android) The app closes at once, and `doctor` reports `MainApplication.kt calls loadReactNative(this), NavigationApplication loads it too`.
+(Android) The app closes at once, and `doctor` reports `MainApplication.kt loads React Native itself … next to loadReactNative(this)`.
 
-**Why:** `NavigationApplication` loads React Native itself, and a second load crashes the app.
+**Why:** the application loads React Native on its own as well, with `SoLoader.init` or the New Architecture's entry point (`load()`, as apps from react-native-navigation have it), and a second load crashes the app.
 
-**Fix:** remove the `loadReactNative(this)` call from `MainApplication.kt`. More: [Android files](../start/installation#android-files).
+**Fix:** keep only `loadReactNative(this)` in `onCreate`; `npx apex-navigation setup` removes the other load. More: [Android files](../start/installation#android-files).
 
 ### doctor warns about the JDK
 

package/docs-md/index.json

@@ -974,6 +974,10 @@
         "heading": "The system back of Android",
         "anchor": "system-back"
       },
+      {
+        "heading": "The preview of a pop",
+        "anchor": "pop-preview"
+      },
       {
         "heading": "Back to the home screen",
         "anchor": "system-animation"
@@ -1323,6 +1327,10 @@
         "heading": "Animations of your own",
         "anchor": "custom"
       },
+      {
+        "heading": "The top bar",
+        "anchor": "custom-bar"
+      },
       {
         "heading": "Which to pick",
         "anchor": "which"
@@ -3944,6 +3952,10 @@
         "heading": "A screen ignores its static options",
         "anchor": "static-options"
       },
+      {
+        "heading": "The Android app crashes at start: React Native isn't loaded",
+        "anchor": "not-loaded"
+      },
       {
         "heading": "The Android app crashes at start: React Native loads twice",
         "anchor": "loads-twice"

package/docs-md/migration/from-react-native-navigation.md

@@ -140,7 +140,7 @@ Each piece of `react-native-navigation`, and what takes its place. The [steps](#
 | `AppRegistry` left out of `index.js` | `AppRegistry.registerComponent(name, Navigation)` of the package. |
 | `RNNAppDelegate`, `import ReactNativeNavigation` | `ANNAppDelegate`, `import ApexNavigation`. |
 | `com.reactnativenavigation.*` | `dev.apexnative.navigation.*`. |
-| `NavigationReactNativeHost` in `MainApplication` | The template's `reactHost`; `NavigationApplication` loads React Native itself. |
+| `NavigationReactNativeHost` in `MainApplication` | The template's `reactHost`, and its `loadReactNative(this)` in `onCreate`. |
 | `RNNKotlinVersion` in `android/build.gradle` | Nothing: the library reads `kotlinVersion`. |
 
 ## The move, step by step
@@ -212,11 +212,12 @@ import dev.apexnative.navigation.NavigationActivity
 class MainActivity : NavigationActivity()
 ```
 
-The application drops `NavigationReactNativeHost` and keeps the `reactHost` of the React Native template. `NavigationApplication` loads React Native in its `onCreate`, so the app doesn't call `loadReactNative` again.
+The application drops `NavigationReactNativeHost` and keeps the `reactHost` of the React Native template. react-native-navigation loaded React Native itself; the navigation leaves it to the template's `loadReactNative(this)` in `onCreate`, which `migrate` adds.
 
 ```kotlin
 import com.facebook.react.PackageList
 import com.facebook.react.ReactHost
+import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
 import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
 import dev.apexnative.navigation.NavigationApplication
 
@@ -227,6 +228,11 @@ class MainApplication : NavigationApplication() {
       packageList = PackageList(this).packages,
     )
   }
+
+  override fun onCreate() {
+    super.onCreate()
+    loadReactNative(this)
+  }
 }
 ```
 

package/docs-md/screen-ui/back-and-gestures.md

@@ -17,7 +17,7 @@ On iOS the back button of Details reads "Inbox". This page answers:
 
 1. [The ways back](#ways) on each platform.
 2. [The back button](#back-button): [its title](#title) and [its look](#look).
-3. [The swipe back](#swipe) of iOS, and [the system back](#system-back) of Android.
+3. [The swipe back](#swipe) of both platforms, and [the system back](#system-back) of Android.
 4. [How to keep the user on a screen](#prevent) with unsaved changes.
 
 ## The ways back
@@ -85,7 +85,7 @@ export const MapScreen = defineScreen({
 | `'edge'` | From the edge only: a swipe on the content stays with the content. |
 | `false` | Off. The back button still works. |
 
-(Android) The system back swipes from either edge; the app doesn't change it.
+(Android) The swipe is the system's back, from either edge, and `popGesture` doesn't apply to it. On Android 14+ it shows the pop before the user lets go: both screens shrink, the screen under comes in behind a dim, and the screen on top follows the finger. The user can stop halfway and stay, as on iOS. On Android 13 and older the screen pops when the swipe ends. When the preview shows and when it doesn't: [the preview of a pop](#pop-preview).
 
 ## The system back of Android
 
@@ -100,6 +100,12 @@ export const MapScreen = defineScreen({
 | The first screen of a tab | What `Tabs().backBehavior(…)` says: leave the app, go to the first tab, or to the tab before. See [Back on Android](../containers/tabs#back). |
 | The first screen of the app | Leaves the app, as every Android app does, with the system's own animation ([below](#system-animation)). `usePreventLeave` doesn't hold it; to ask first, see [Asking before the user leaves the app](/api/back-and-gestures/usePreventLeave#leaving-the-app). |
 
+### The preview of a pop
+
+(Android) 14+ The back gesture on a pushed screen shows where it goes before the user lets go, as the system does between apps' screens: the screen shrinks toward the side of the swipe with rounded corners and follows the finger, and the screen under it shows behind it, dimmed, with its own bar. Letting go pops the screen; swiping back cancels, and the screen grows back into place.
+
+The preview shows when back pops the screen with the default transition. It doesn't when back does something else first, or when the app takes it: a menu or a search that closes, a screen that holds back (`hardwareBackButton.popStackOnPress: false`, a [`BackHandler` listener](#back-handler), `usePreventLeave`), or a pop with an animation of its own (`animations.pop`). On Android 13 and older the screen pops when the swipe ends.
+
 ### Back to the home screen
 
 (Android) On the first screen of the app, with nothing left to go back to, the navigation leaves the back to the system. The system then plays its predictive back animation: as the user swipes, the app shrinks and the home screen shows behind it, and the user can still change their mind halfway. The system decides this as the swipe starts, so the navigation takes the back only while it has something to do with it: a screen to pop, a modal, a menu or a search to close, a tab to go to (`backBehavior`), or a [`BackHandler` listener](#back-handler) of the app.

package/docs-md/screen-ui/system-ui.md

@@ -249,7 +249,7 @@ iPhone Duo decides by itself too: folded, the outer display shows the app in por
 
 ## Backgrounds
 
-`backgroundColor` colors the screen, behind its React content. Without it, the screen has the background of the [theme](../architecture/theme-and-context).
+`backgroundColor` colors the screen, behind its React content. Without it, the screen has the background of the [theme](../architecture/theme-and-context), or the system's when the theme has none: `systemBackground` on (iOS), `android:colorBackground` of the app's theme on (Android) (a screen in a sheet shows the sheet's surface; a native screen paints its own view). So a React screen is never see-through by accident; `'transparent'` makes it so on purpose, as overlays are.
 
 ```ts
 s.backgroundColor('#F3E9D2');

package/docs-md/start/installation.md

@@ -126,11 +126,13 @@ In an app as the React Native template makes it, the window shows **one React vi
 
 | File | What setup does | Why |
 | --- | --- | --- |
-| `MainApplication.kt` | Extends `NavigationApplication`. | It loads React Native itself and keeps one React host for all screens. Native screens made by `codegen` are registered there, before JS opens them. |
+| `MainApplication.kt` | Extends `NavigationApplication`; keeps the template's `loadReactNative(this)` in `onCreate`, or adds it. | It keeps one React host for all screens, made after `loadReactNative(this)` loaded React Native. Native screens made by `codegen` are registered there, before JS opens them. |
 | `MainActivity.kt` | Extends `NavigationActivity`. | The activity holds the containers of the navigation instead of one React view. It gets the back press, edge-to-edge and configuration changes first. |
 | `AndroidManifest.xml` | Adds `android:enableOnBackInvokedCallback="true"` to `<application>`. | On the first screen the system plays its own animation back to the home screen as the user swipes back (predictive back). Android 16 turns it on for apps that target API 36; an app that targets less opts in here. A value the app set itself stays. See [Back to the home screen](../screen-ui/back-and-gestures#system-animation). |
 | `styles.xml` | `AppTheme` inherits `Theme.ApexNavigation`. | The bars, tabs and search are Material 3 views and take their colors from the app's theme. This one is Material 3 in neutral grays, light and dark; change any color in the same file. A theme of the app's own stays as it is. See [Android's colors](../architecture/theme-and-context#android). |
 
+The main activity keeps the template's `android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"`. Without `orientation`, `screenSize`, `smallestScreenSize`, `screenLayout` or `uiMode` Android recreates the activity on a rotation, a resize, a fold or a light/dark switch, and every screen goes with it; `doctor` warns about it under Config changes.
+
 #### iOS files
 
 | File | What setup does | Why |

package/ios/CLAUDE.md

@@ -27,7 +27,7 @@ Swift is not used here: apps reach the core through the public headers (`Public/
 - `Layouts/SplitView/`: The split view module, plus the core's `ANNSplitViewPresenter` and `ANNSplitViewCommands`.
 - `Layouts/Arrangement/`: The pair (iOS 27.1): `ANNArrangementViewController`, `ANNArrangementState`.
 - `TopBar/`: The bar of a screen: title, buttons, back button, large title, appearance, search, toolbar, edge effects.
-- `Options/`, `Options/Params`: One `ANN<Group>Options` class per group, the field table, the value kinds and parsers (`Bool`, `Color`, `Text`, `Image`, …).
+- `Options/`, `Options/Params`: One `ANN<Group>Options` class per group, the field table, the value kinds and parsers (`Bool`, `Color`, `Text`, `Image`, …), the images' cache and loader (`ANNOptionImages`).
 - `Animations/`: The custom transition engine: plan, animator, wait, frame driver, rules; `Elements/` and `Interpolators/`.
 - `React/`, `React/Slots/`: React views of screens and components, the surface host, the safe area view, the slot host and slot screens.
 - `Public/ApexNavigation/`: The headers apps import: `ApexNavigation.h`, `ANNAppDelegate.h`, `ANNSceneDelegate.h`.
@@ -42,7 +42,7 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - Launch, the app-facing API — `Public/ApexNavigation/`; `Core/`: `ApexNavigation.mm`, `ANNAppDelegate.mm`, `ANNSceneDelegate.mm`, `ApexNavigation+Internal.h`
 - Root, splash, reload — `Layouts/Root/`: `ANNRootCoordinator`, `ANNSplashViewController`; `Core/`: `ANNReloadCoordinator`
 - Screen: React root, slot, native screen — `Layouts/Screen/`: `ANNComponentViewController`; `React/`: `ANNReactView`, `ANNReactViewCreator`, `Slots/`; `Layouts/External/`
-- Screen: insets, background, keyboard focus — `Layouts/Screen/`: `ANNScreenInsets`, `ANNScreenSafeArea`, `ANNScreenBars`, `ANNComponentPresenter` (background, status bar blur), `ANNComponentViewController` (key commands)
+- Screen: insets, background, keyboard focus — `Layouts/Screen/`: `ANNScreenInsets`, `ANNScreenSafeArea`, `ANNScreenBars`, `ANNScreenPlace` (the safe area of a parked screen), `ANNComponentPresenter` (background, status bar blur), `ANNComponentViewController` (key commands)
 - Safe area view — `React/`: `ANNSafeAreaViewComponentView`; `Layouts/Screen/`: `ANNScreenReadiness`; `cpp/`
 - Stack: queue, commands, back, gestures — `Layouts/Stack/`: `ANNStackQueue`, `ANNStackCommands`, `ANNStackController`, `InteractivePopGestureDelegate`, `ANNStackAnimatingDelegate`
 - Top bar: title, buttons, menus, large title — `TopBar/`: `ANNTopBarPresenter`, `ANNBarButtons`, `ANNBarAppearance`, `ANNLargeTitlePresenter`, `ANNBackButtonPresenter`, `ANNTitleView`, `ANNTitleGlassView`
@@ -60,24 +60,31 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - System bars, orientation, direction — `Core/`: `ANNSystemUI`, `ANNSystemUIRules`, `ANNAppDirection`, `ANNNodePresenter` (the answers to UIKit)
 - Events and state — `Core/`: `ANNEventEmitter`, `ANNEventContract` (names and keys, made by `scripts/contract.mjs`), `ANNAppearanceDispatcher`, `ANNScreenAppearance`, `ANNNavigationState`; `TurboModules/`: `ANNTurboEventEmitter`
 - Options: parsing, merging, defaults — `Options/`: `ANNOptions`, `ANNOptionField`, `ANNOptionsReader`, `ANNDefaultOptions`, `ANNOptionsCache`; `Core/`: `ANNOptionsRepaint`
-- Error texts — `Contract/`: `ANNErrorTexts` (made from `src/interfaces/contract/errors.json` by `scripts/contract.mjs`); `Core/`: `ANNErrorHandler`
+- Error texts and answers — `Contract/`: `ANNErrorTexts` and `ANNCommandContract` (made from `src/interfaces/contract/errors.json` and `commands.json` by `scripts/contract.mjs`); `Core/`: `ANNErrorHandler`
 - Links — `Core/`: `ANNDeepLinkQueue`; the `getLaunchLink` method of `ANNTurboModule`
 - Key commands — `Core/`: `ANNKeyCommands`; `Layouts/Screen/`: `ANNComponentViewController`
 - Hinge, regions — `Core/`: `ANNHinge`; `Layouts/Screen/`: `ANNScreenRegions`; `Layouts/Arrangement/`: `ANNArrangementState`
 - Native screens — `Layouts/External/`: `ANNExternalViewController`, `ANNNativeScreenCalls`; `Layouts/Screen/ANNNativeScreenContext.mm`
-- Slots — `React/Slots/`: `ANNSlotHost`, `ANNSlotContainers`, `ANNSlotScreenView`, `ANNSlotComponentView`; `cpp/`
+- Slots — `React/Slots/`: `ANNSlotHost`, `ANNSlotContainers` (containers and slot views by slot id: a change goes
+  straight to the views of its id), `ANNSlotScreenView`, `ANNSlotComponentView`; `cpp/`
 
 ## Threads
 
 - **Module queue:** the layout check (`ANNLayoutReader`) and the sync getters. The check reads only stores safe from
   any thread (`ApexNavigation hasNativeScreenNamed:`, `ANNArrangementState canShowArrangements`).
 - **Main queue:** everything else. A command body starts with `ANNAssertMainQueue()`. The options of a layout are parsed
-  here (`ANNLayoutTreeOptions`, images load while they are read). `ANNEventEmitter` moves an event from another queue
+  here (`ANNLayoutTreeOptions`; an image keeps only its source). `ANNEventEmitter` moves an event from another queue
   to the main queue.
+- **The images' queue** (`ANNOptionImages`, `Options/Params`): every option image decodes there, through one cache.
+  An element that shows an image asks for it when it applies and waits for it (the first frame needs it); only a tab
+  item's new icon on the bar that shows comes later (`ANNBottomTabsPresenter`), the last build of the item winning.
 - **Sync getters** answer JS during a screen's first render: `getScreenInsets`, `getScreenRegions`,
   `getArrangementState`, `getHinge`, `getStartInfo`. They read `ANNScreenInsets`, `ANNScreenRegions`,
   `ANNArrangementState`, `ANNHinge lastValue`, written on the main queue and guarded by `@synchronized`.
   `ANNReloadCoordinator.generation` and `ANNEventEmitter.isCurrent` are readable from any thread.
+- **After the calls of JavaScript:** `ANNJavaScriptCalls afterCallsMadeSoFar:` runs a step on the main queue after
+  every call JavaScript made by then, by the calls' own way (the JavaScript thread, the module's queue, the main
+  queue). A push's wait ends through it, so the `mergeOptions` of its screen's first commit come first.
 
 ## Checks
 
@@ -92,6 +99,11 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 
 - Native code never touches React Native's views (their subviews, their layout, their frames): Fabric owns and recycles
   them. Read them; what a transition writes (`alpha`, `transform`, a hidden flag) goes back on every path.
+- A screen parked by a wait for its content (`ANNParking`) has no parent, and UIKit gives its view no safe area: it lays
+  out with the safe area of its place (`ANNScreenPlace`, measured on a navigation controller of the core's), or its
+  list would move as the push starts and UIKit would show the large title only after the transition. On iOS 26 its
+  large title also keeps a place of the core's for the push (`arrivesByPushOn:`). Check Showcase 1.4 (with a font
+  size), every section panel and 12.6 on push, pop and swipe after any change to waits, parking or the large title.
 - Every change of a stack's children goes through its `ANNStackQueue`. The core's own calls to UIKit's navigation
   come only from there; UIKit's own pops are followed (`uikitShows:`), not fought.
 - Every UIKit present and dismiss in the main window is a step in `ANNPresentationGate`. UIKit drops a transition

package/ios/CORE.md

@@ -68,16 +68,20 @@ dispatcher.
    `+[ANNErrorTexts nowhereToShow]` when there is no window, then runs the body in `@try`. The body finds Home in
    `ANNNodeRegistry` and calls `+[ANNStackCommands push:componentId:what:answer:]`.
 4. **`ANNStackCommands`.** Finds the stack by walking `layoutParent`; checks `ANNLayoutValidator` (an id already shown,
-   what a stack takes); reads the options of the whole tree with `ANNLayoutTreeOptions` (images load here); checks
-   `ANNLayoutFactory canMakeTrees:`; a node with `preview.nativeID` goes to `ANNPreviewPush`; a `key` of an entry below
-   goes back to that entry; else `+[ANNLayoutFactory nodeFromLayout:options:]` makes Profile (an
+   what a stack takes); reads the options of the whole tree with `ANNLayoutTreeOptions` (an image keeps its source,
+   loaded through `ANNOptionImages` when an element shows it); checks `ANNLayoutFactory canMakeTrees:`; a node with
+   `preview.nativeID` goes to `ANNPreviewPush`; a `key` of an entry below goes back to that entry; else
+   `+[ANNLayoutFactory nodeFromLayout:options:]` makes Profile (an
    `ANNComponentViewController` with an `ANNComponentPresenter`, content from `ANNReactViewCreator`) and registers it.
    No view is rendered yet.
 5. **`-[ANNStackQueue push:answer:…]`.** The node joins `entries` now (every check reads `entries`), the operation is
    queued, `runNext` starts it when the queue is at rest.
 6. **`startPush:` and `startPushTransition:`.** By `animations.push.waitForRender` the queue waits through
-   `ANNRenderWait`, for the content and the bar components or for the bar components alone (a screen that waits for its
-   content is parked unseen in the stack's view by `ANNParking`, `stackPark:`), then renders the node, drives the appearance of Home and Profile (`+[ANNAppearanceDispatcher driveAppearanceOf:]`), and calls
+   `ANNRenderWait`: unset, for the content at most 0.5 s, with `true` as long as it takes, then for the bar components
+   (their limits from the wait's start when unset, from the content's end with `true`; the screen is parked unseen in
+   the stack's view by `ANNParking`, `stackPark:`); the content's end, content there already too, waits for the calls
+   JavaScript made by then (`ANNJavaScriptCalls`: the JavaScript thread, the module's queue, the main queue), so the
+   options of the screen's first commit are in the bar; with `false` nothing. Then it renders the node, drives the appearance of Home and Profile (`+[ANNAppearanceDispatcher driveAppearanceOf:]`), and calls
    `+[ANNAppearanceDispatcher beginTransitionShowing:]`. Profile's `ComponentWillAppear` is sent now (held until its
    content mounted, 0.5 s at most). `stackChange:` pushes in UIKit; with an own animation `ANNTransitionPlan` and
    `ANNStackAnimatingDelegate` give UIKit the `ANNTransitionAnimator`.
@@ -85,7 +89,7 @@ dispatcher.
    `+[ANNAppearanceDispatcher endTransitionHiding:showing:events:answer:value:]`. In this order: `ComponentDidDisappear`
    of Home, `ComponentDidAppear` of Profile, `ANN.NavigationStateChanged` (`+[ANNNavigationState updateNow]`), the
    transition's `events`, then `-[ANNCommandAnswer resolve:]`: the state again if it changed
-   (`reportBeforeAnswer`), the promise with Profile's id, then `ANN.CommandCompleted`. `finish:` frees the queue for
+   (`reportBeforeAnswerOf:`), the promise with Profile's id, then `ANN.CommandCompleted`. `finish:` frees the queue for
    the next operation.
 
 Events go out through `ANNEventEmitter` on the main queue and reach JS through `ANNTurboEventEmitter`.
@@ -116,13 +120,14 @@ Each of these owns one rule. Call it; do not copy it.
 - `ANNCommandAnswer`: The answer: state, then promise, then `ANN.CommandCompleted`; once; silent for a JavaScript that went. Called by: Every coordinator and queue.
 - `ANNNodeRegistry`: Every node by id, weakly. Filled by the factory, cleared at a reload. Called by: Commands, modules, `findViewController:`.
 - `ANNLayoutFactory`: The core code that names module classes (`ANNSplitViewController`, `ANNSideMenuViewController`, `ANNArrangementViewController`); `ANNSideMenuPresenter` is the one other file that does. One maker per layout type; registers each node. Called by: Every command that shows a layout.
-- `ANNOptionsCache`: The one invalidation point of resolved options. Called by: The setter of `ANNNodeHelper.options` and `ANNDefaultOptions` only.
-- `ANNNodeHelper resolveOptionsWithDefault`: What a node shows with: defaults, parents' own options, the node's `resolveOptions` (own, then the current child down). Cached, read-only. Called by: Presenters, coordinators.
+- `ANNOptionsCache`: The one invalidation point of resolved options. Called by: The setters of `ANNNodeHelper.options` and of its user layer (`setUserChoice:forKey:`), and `ANNDefaultOptions`, only.
+- `ANNNodeHelper resolveOptionsWithDefault`: What a node shows with: defaults, parents' own options (each with its user layer), the node's `resolveOptions` (own, its user layer, then the current child down). Cached, read-only. Called by: Presenters, coordinators.
 - `ANNAppearanceDispatcher`: The only sender of `ComponentWillAppear`, `ComponentDidAppear`, `ComponentDidDisappear`; the end-of-transition order; the events of a node that goes. Called by: Screens, queues, coordinators.
 - `ANNNavigationState`: The visible screen and the nearest tabs it is in (the last tabs met walking down); coalesced updates, holds, the state before an answer. Called by: The dispatcher, `ANNCommandAnswer`, `ANNRootCoordinator`.
 - `ANNScreenReadiness`: The signals of a screen's safe area view (has one, laid out, content rendered), sticky, by screen id. Called by: `ANNSafeAreaViewComponentView`, `ANNReactView`.
 - `ANNRenderWait`: The one wait for the render of what a command shows: content, bar components, limits, the unknown-content rule. Called by: Root, stack queue, modals, overlays, `showInColumn`.
 - `ANNParking`: Where a view waits for its content unseen: the window, a stack's view, a preview's host view. Called by: Root, stack, modals, overlays, `ANNPreviewPush`.
+- `ANNScreenPlace`: The safe area a parked screen lays out with, measured where it will show on top of a stack. Called by: `ANNStackController` (`stackPark:`), `ANNSplitViewCommands` (`showInColumn`), through `placeWhileParked` of the screen.
 - `ANNPendingLayers`: Layers that wait to show (a pending root, a modal, an overlay); a node inside counts as off screen. Called by: The layer's owner; nodes ask.
 - `ANNShownScreens`: "What a node shows changed": tells the pending layer, the modal hold and the system UI, in that order. Called by: Every container that changes what it shows.
 - `ANNModalCoordinator`, `ANNModal`: One record per modal, its states and waiting commands. Called by: Commands, root, state, repaint, reload.

package/ios/Contract/ANNCommandAnswer.mm

@@ -1,26 +1,12 @@
 #import "ANNCommandAnswer.h"
 #import "ANNAssert.h"
+#import "ANNCommandContract.h"
 #import "ANNErrorHandler.h"
 #import "ANNErrorTexts.h"
 #import "ANNNavigationState.h"
 #import "ANNReloadCoordinator.h"
 #import "ApexNavigation+Internal.h"
 
-// The commands that send `ANN.CommandCompleted` once they resolved: every one that shows or dismisses, not
-// `setColumnShown`, `preparePush` or `getLaunchLink`.
-static NSSet<NSString *> *ANNCompletedCommandNames(void) {
-    static NSSet<NSString *> *names;
-    static dispatch_once_t once;
-    dispatch_once(&once, ^{
-      names = [NSSet setWithArray:@[
-          @"setRoot", @"push", @"pop", @"popTo", @"popToRoot", @"setStackRoot", @"showInColumn",
-          @"showModal", @"dismissModal", @"dismissAllModals", @"showOverlay", @"dismissOverlay",
-          @"dismissAllOverlays"
-      ]];
-    });
-    return names;
-}
-
 @implementation ANNCommandAnswer {
     RCTPromiseResolveBlock _resolve;
     RCTPromiseRejectBlock _reject;
@@ -72,14 +58,13 @@ static NSSet<NSString *> *ANNCompletedCommandNames(void) {
     RCTPromiseResolveBlock resolve = _resolve;
     _resolve = nil;
     _reject = nil;
-    // A command that may change what shows (the 13 and `setColumnShown`): the state goes before the promise, so that
+    // A command that may change what shows (`ANNCommandContract`): the state goes before the promise, so that
     // `getState()` after `await` has the result.
-    BOOL changesWhatShows = [ANNCompletedCommandNames() containsObject:_commandName] ||
-                            [_commandName isEqualToString:@"setColumnShown"];
+    BOOL changesWhatShows = ANNCommandReportsState(_commandName);
     if (changesWhatShows) {
         // The command did its work: a failure of the state step costs only the state, never the answer.
         @try {
-            [ANNNavigationState reportBeforeAnswer];
+            [ANNNavigationState reportBeforeAnswerOf:_commandName];
         } @catch (NSException *exception) {
             NSString *reason = exception.reason.length > 0 ? exception.reason : exception.name;
             [ANNErrorHandler logFailureOf:_commandName
@@ -88,7 +73,7 @@ static NSSet<NSString *> *ANNCompletedCommandNames(void) {
         }
     }
     [ANNErrorHandler resolve:resolve of:_commandName value:value];
-    if (_commandId && [ANNCompletedCommandNames() containsObject:_commandName]) {
+    if (_commandId && ANNCommandSendsCompleted(_commandName)) {
         double completionTime = floor(NSDate.date.timeIntervalSince1970 * 1000);
         [ApexNavigation.eventEmitter sendCommandCompleted:_commandName
                                                 commandId:_commandId

package/ios/Contract/ANNCommandContract.h

@@ -0,0 +1,15 @@
+// Made by scripts/contract.mjs from src/interfaces/contract/commands.json: change that file and run the script again.
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Whether the navigation state goes before the answer of the command `name`: every command that may change what
+/// shows. Any thread.
+FOUNDATION_EXPORT BOOL ANNCommandReportsState(NSString *name);
+
+/// Whether `ANN.CommandCompleted` follows the answer of the command `name`: every command that shows or dismisses.
+/// Any thread.
+FOUNDATION_EXPORT BOOL ANNCommandSendsCompleted(NSString *name);
+
+NS_ASSUME_NONNULL_END

package/ios/Contract/ANNCommandContract.mm

@@ -0,0 +1,78 @@
+// Made by scripts/contract.mjs from src/interfaces/contract/commands.json: change that file and run the script again.
+
+#import "ANNCommandContract.h"
+
+// What each command resolves with:
+// - `setRoot`: the id of the root, once the root and the layout's modals and overlays show.
+// - `push`: the id of the screen that shows; of a pair, the pair's id.
+// - `preparePush`: the frame `{ width, height, padding }` of the prepared screen, or null; always
+//   null on iOS.
+// - `pop`: the id of the screen that went.
+// - `popTo`: the id of the screen it went back to.
+// - `popToRoot`: the id of the first screen of the stack.
+// - `setStackRoot`: the id of the new top screen.
+// - `showModal`: the id of the modal's root.
+// - `dismissModal`: the id of the modal's root.
+// - `dismissAllModals`: an empty string.
+// - `showOverlay`: the id of the overlay's root.
+// - `dismissOverlay`: the id of the overlay's root.
+// - `dismissAllOverlays`: an empty string.
+// - `showInColumn`: the id of the screen that shows.
+// - `setColumnShown`: nothing once the columns stopped moving (`undefined` on iOS, `null` on
+//   Android).
+// - `getLaunchLink`: the link that launched the app, or null.
+
+static NSSet<NSString *> *ANNStateCommandNames(void) {
+    static NSSet<NSString *> *names;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      names = [NSSet setWithArray:@[
+          @"setRoot",
+          @"push",
+          @"pop",
+          @"popTo",
+          @"popToRoot",
+          @"setStackRoot",
+          @"showModal",
+          @"dismissModal",
+          @"dismissAllModals",
+          @"showOverlay",
+          @"dismissOverlay",
+          @"dismissAllOverlays",
+          @"showInColumn",
+          @"setColumnShown",
+      ]];
+    });
+    return names;
+}
+
+static NSSet<NSString *> *ANNCompletedCommandNames(void) {
+    static NSSet<NSString *> *names;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      names = [NSSet setWithArray:@[
+          @"setRoot",
+          @"push",
+          @"pop",
+          @"popTo",
+          @"popToRoot",
+          @"setStackRoot",
+          @"showModal",
+          @"dismissModal",
+          @"dismissAllModals",
+          @"showOverlay",
+          @"dismissOverlay",
+          @"dismissAllOverlays",
+          @"showInColumn",
+      ]];
+    });
+    return names;
+}
+
+BOOL ANNCommandReportsState(NSString *name) {
+    return [ANNStateCommandNames() containsObject:name];
+}
+
+BOOL ANNCommandSendsCompleted(NSString *name) {
+    return [ANNCompletedCommandNames() containsObject:name];
+}

package/ios/Core/ANNAppearanceDispatcher.mm

@@ -305,7 +305,7 @@ static BOOL ANNIsInsideNode(UIViewController *screen, UIViewController *node) {
     for (UIViewController *node in shown) {
         [self nodeDidAppear:node];
     }
-    [ANNNavigationState updateNow];
+    [ANNNavigationState updateNowFor:answer.commandName];
     if (events) {
         events();
     }