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

package/cli/setup/steps/mainApplication.js

@@ -5,24 +5,51 @@ const { addImport, codeOf, removeUnusedImports } = require('../source');
 
 /** @typedef {import('./types').StepResult} StepResult */
 
-const HOW_TO = `Extend NavigationApplication. It loads React Native itself, so loadReactNative(this) goes:
-calling it again crashes the app on start.
+const HOW_TO = `Extend NavigationApplication and keep the template's loadReactNative(this) in onCreate: it loads
+React Native as the app's Gradle files say, and the navigation makes its React host after it.
 
+  import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
   import dev.apexnative.navigation.NavigationApplication
 
   class MainApplication : NavigationApplication() {
     override val reactHost: ReactHost by lazy { ... }   // as it is
+
+    override fun onCreate() {
+      super.onCreate()
+      loadReactNative(this)
+    }
   }`;
 
+const LOAD_IMPORT = 'import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative';
+
 // Imports of the template that the change leaves unused.
-const TEMPLATE_IMPORTS = [
-  'android.app.Application',
-  'com.facebook.react.ReactApplication',
-  'com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative',
+const TEMPLATE_IMPORTS = ['android.app.Application', 'com.facebook.react.ReactApplication'];
+
+// A load of React Native of the app's own, next to loadReactNative(this) a second one that crashes the app at start:
+// the New Architecture's entry point (react-native-navigation's apps call it in onCreate) and SoLoader.
+// A bare `load()` is the entry point's only where the file imports it. A form these don't take out (`load` with
+// arguments, an `if` without braces) is left to the app's author.
+const OWN_LOAD = [
+  /^[ \t]*if\s*\(\s*BuildConfig\.IS_NEW_ARCHITECTURE_ENABLED\s*\)\s*\{(?:\s*\/\/[^\n]*)*\s*DefaultNewArchitectureEntryPoint\.load\(\)\s*\}[ \t]*\r?\n/gm,
+  /^[ \t]*DefaultNewArchitectureEntryPoint\.load\(\)[ \t]*\r?\n/gm,
+  /^[ \t]*SoLoader\.init\([^\n]*\)[ \t]*\r?\n/gm,
+];
+const BARE_LOAD = [
+  /^[ \t]*if\s*\(\s*BuildConfig\.IS_NEW_ARCHITECTURE_ENABLED\s*\)\s*\{(?:\s*\/\/[^\n]*)*\s*load\(\)\s*\}[ \t]*\r?\n/gm,
+  /^[ \t]*load\(\)[ \t]*\r?\n/gm,
+];
+const BARE_LOAD_IMPORT =
+  /^import\s+com\.facebook\.react\.defaults\.DefaultNewArchitectureEntryPoint\.load\b/m;
+const OWN_LOAD_IMPORTS = [
+  'com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.load',
+  'com.facebook.react.defaults.DefaultNewArchitectureEntryPoint',
+  'com.facebook.soloader.SoLoader',
+  'com.facebook.react.soloader.OpenSourceMergedSoMapping',
 ];
 
 /**
- * MainApplication.kt: the application becomes a NavigationApplication.
+ * MainApplication.kt: the application becomes a NavigationApplication, and loads React Native in its onCreate as the
+ * template does.
  * @param {string} text
  * @returns {StepResult}
  */
@@ -32,21 +59,20 @@ function planMainApplication(text) {
     note: 'changed by hand, see below',
     howTo: HOW_TO,
   });
-  if (/:\s*NavigationApplication\(\)/.test(text)) {
-    return /\bloadReactNative\s*\(/.test(codeOf(text))
+  if (/:\s*NavigationApplication\(/.test(text)) {
+    if (loadsReactNative(text) && !loadsReactNativeItself(text)) {
+      return { status: 'done', note: 'already set up' };
+    }
+    const next = withReactNativeLoaded(text);
+    return next === undefined
       ? manual
-      : { status: 'done', note: 'already set up' };
+      : { status: 'change', next, note: 'loadReactNative(this) in onCreate' };
   }
   const header = /class\s+(\w+)\s*:\s*Application\(\)\s*,\s*ReactApplication\b/;
   if (!header.test(text)) return manual;
-  let next = text.replace(header, 'class $1 : NavigationApplication()');
-  // The template's onCreate only loads React Native, so it goes; another one keeps the rest of its code.
-  next = next.replace(
-    /\n\n?[ \t]*override\s+fun\s+onCreate\(\)\s*\{\s*super\.onCreate\(\)\s*loadReactNative\(this\)\s*\}/,
-    ''
-  );
-  next = next.replace(/^[ \t]*loadReactNative\(this\)[ \t]*\r?\n/m, '');
-  if (/\bloadReactNative\s*\(/.test(codeOf(next))) return manual;
+  // The template's onCreate stays: its loadReactNative(this) loads React Native for the navigation too.
+  let next = withReactNativeLoaded(text.replace(header, 'class $1 : NavigationApplication()'));
+  if (next === undefined) return manual;
   // Added first: with the template's imports gone the file would have none to sort it among.
   next = addImport(next, 'import dev.apexnative.navigation.NavigationApplication', {
     sorted: true,
@@ -55,4 +81,93 @@ function planMainApplication(text) {
   return { status: 'change', next, note: 'NavigationApplication' };
 }
 
-module.exports = { planMainApplication };
+/**
+ * Whether the code of the file, not a comment, calls loadReactNative.
+ * @param {string} text
+ */
+function loadsReactNative(text) {
+  return /\bloadReactNative\s*\(/.test(codeOf(text));
+}
+
+/**
+ * Whether the code of the file loads React Native on its own as well: the New Architecture's entry point or SoLoader.
+ * @param {string} text
+ */
+function loadsReactNativeItself(text) {
+  const code = codeOf(text);
+  return (
+    /\bSoLoader\.init\s*\(/.test(code) ||
+    /\bDefaultNewArchitectureEntryPoint\.load\s*\(/.test(code) ||
+    (BARE_LOAD_IMPORT.test(text) && /(?<![\w.])load\s*\(/.test(code))
+  );
+}
+
+/**
+ * The application with `loadReactNative(this)` in its onCreate, after `super.onCreate()`: as it is when it has the
+ * call, with an onCreate of the template's when it has none. Undefined for an onCreate that doesn't call
+ * `super.onCreate()`, whose order only its author knows.
+ * @param {string} text
+ * @returns {string | undefined}
+ */
+function withReactNativeLoaded(text) {
+  let without = text;
+  const patterns = BARE_LOAD_IMPORT.test(text) ? [...OWN_LOAD, ...BARE_LOAD] : OWN_LOAD;
+  for (const pattern of patterns) without = without.replace(pattern, '');
+  without = removeUnusedImports(without, OWN_LOAD_IMPORTS);
+  if (loadsReactNativeItself(without)) return undefined;
+  if (loadsReactNative(without)) return without;
+  return withLoadCall(without);
+}
+
+/**
+ * @param {string} text an application without a load of React Native
+ * @returns {string | undefined}
+ */
+function withLoadCall(text) {
+  let next;
+  const superCall = /^([ \t]*)super\.onCreate\(\)[ \t]*\r?\n/m;
+  if (/\boverride\s+fun\s+onCreate\s*\(/.test(text)) {
+    if (!superCall.test(text)) return undefined;
+    next = text.replace(superCall, (line, indent) => `${line}${indent}loadReactNative(this)\n`);
+  } else {
+    const close = classEnd(text);
+    if (close === undefined) return undefined;
+    const indent = /^([ \t]+)override\b/m.exec(text)?.[1] ?? '  ';
+    const body = text.slice(0, close).replace(/\s*$/, '');
+    const onCreate = [
+      '',
+      `${indent}override fun onCreate() {`,
+      `${indent}${indent}super.onCreate()`,
+      `${indent}${indent}loadReactNative(this)`,
+      `${indent}}`,
+    ].join('\n');
+    next = `${body}\n${onCreate}\n${text.slice(close)}`;
+  }
+  return addImport(next, LOAD_IMPORT, { sorted: true });
+}
+
+/**
+ * The index of the closing brace of the file's application class: its braces counted from the class's own, past any
+ * declaration or comment after it. Undefined when the braces don't close.
+ * @param {string} text
+ * @returns {number | undefined}
+ */
+function classEnd(text) {
+  // The comments and the string and character literals blanked out, so that an index in it is one in the text and a
+  // brace in a literal doesn't count.
+  const blank = (/** @type {string} */ part) => part.replace(/[^\n]/g, ' ');
+  const code = text
+    .replace(/\/\*[\s\S]*?\*\//g, blank)
+    .replace(/\/\/.*$/gm, blank)
+    .replace(/"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/g, blank);
+  const header = /\bclass\s+\w+\s*:[^{]*\{/.exec(code);
+  if (!header) return undefined;
+  let depth = 0;
+  for (let index = header.index + header[0].length - 1; index < code.length; index++) {
+    if (code[index] === '{') depth++;
+    else if (code[index] === '}' && --depth === 0) return index;
+  }
+  return undefined;
+}
+
+module.exports = { planMainApplication, withReactNativeLoaded, loadsReactNativeItself };

package/docs-md/architecture/transitions.md

@@ -146,7 +146,7 @@ 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
 
@@ -168,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', {
@@ -180,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/help/glossary.md

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

@@ -3952,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
 

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];
+}