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

package/cli/doctor/checks/app.js

@@ -11,8 +11,10 @@ const {
   reactNativeVersion,
   usesExpo,
 } = require('../../app');
+const { mainActivity } = require('../../links/native');
 const { findProject } = require('../../project');
 const { codeOf } = require('../../setup/source');
+const { loadsReactNativeItself } = require('../../setup/steps/mainApplication');
 const { planCodegen } = require('../../codegen');
 const { readConfig } = require('../../config');
 const { planProject } = require('../../setup');
@@ -27,6 +29,16 @@ const { splashChecks } = require('./splash');
 const SETUP = { label: 'npx apex-navigation setup', run: /** @type {const} */ ('setup') };
 const GENERATED = ['ApexNavigation.generated.swift', 'ApexNavigationGenerated.kt'];
 const CODEGEN = { label: 'npx apex-navigation codegen', run: /** @type {const} */ ('codegen') };
+// The changes the main activity must handle itself; the template's value has them all.
+const CONFIG_CHANGES = [
+  'orientation',
+  'screenSize',
+  'smallestScreenSize',
+  'screenLayout',
+  'uiMode',
+];
+const TEMPLATE_CONFIG_CHANGES =
+  'keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode';
 
 /**
  * React Native, the navigation, and the files setup sets up.
@@ -122,28 +134,64 @@ function appChecks({ root, run }) {
     });
   }
 
+  const configChanges = configChangesCheck(project.manifest);
+  if (configChanges) checks.push(configChanges);
+
   checks.push(...splashChecks(root, project), ...iconChecks(root, project));
 
-  // A second load of React Native crashes the app on start: the most common slip of a setup by hand.
+  // NavigationApplication leaves the load of React Native to the template's call: without it the app closes on start,
+  // and so it does with a second load of the app's own next to it.
   const application = project.mainApplication && fs.readFileSync(project.mainApplication, 'utf8');
-  if (
-    application &&
-    /:\s*NavigationApplication\(\)/.test(application) &&
-    /\bloadReactNative\s*\(/.test(codeOf(application))
-  ) {
-    checks.push({
-      group: 'app',
-      title: 'React Native loads twice',
-      status: 'error',
-      detail: 'MainApplication.kt calls loadReactNative(this), NavigationApplication loads it too',
-      fix: { label: 'Remove loadReactNative(this) from MainApplication.kt' },
-    });
+  if (application && /:\s*NavigationApplication\(/.test(application)) {
+    const loads = /\bloadReactNative\s*\(/.test(codeOf(application));
+    if (!loads) {
+      checks.push({
+        group: 'app',
+        title: 'React Native not loaded',
+        status: 'error',
+        detail: "MainApplication.kt doesn't call loadReactNative(this) in onCreate",
+        fix: SETUP,
+      });
+    } else if (loadsReactNativeItself(application)) {
+      checks.push({
+        group: 'app',
+        title: 'React Native loads twice',
+        status: 'error',
+        detail:
+          'MainApplication.kt loads React Native itself (SoLoader.init or the New Architecture entry point) next to loadReactNative(this)',
+        fix: SETUP,
+      });
+    }
   }
   const generated = generatedCheck(root, run);
   if (generated) checks.push(generated);
   return checks;
 }
 
+/**
+ * Whether the main activity handles the changes of its window itself, as the React Native template has it. Without
+ * one of them Android recreates the activity on a rotation, a resize, a fold or a light/dark switch: every screen goes
+ * with it and the navigation starts again from its root. Nothing without a manifest or a main activity.
+ * @param {string | undefined} manifest
+ * @returns {Check | undefined}
+ */
+function configChangesCheck(manifest) {
+  if (!manifest || !fs.existsSync(manifest)) return undefined;
+  const activity = mainActivity(fs.readFileSync(manifest, 'utf8'));
+  if (!activity) return undefined;
+  const value = /android:configChanges\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(activity.text);
+  const declared = (value?.[1] ?? value?.[2] ?? '').split('|').map((change) => change.trim());
+  const missing = CONFIG_CHANGES.filter((change) => !declared.includes(change));
+  if (missing.length === 0) return undefined;
+  return {
+    group: 'app',
+    title: 'Config changes',
+    status: 'warn',
+    detail: `the main activity doesn't handle ${missing.join(', ')}: Android recreates it, and every screen with it`,
+    fix: { label: `Set android:configChanges="${TEMPLATE_CONFIG_CHANGES}" on the main activity` },
+  };
+}
+
 /**
  * One line for a few files: set up, or which need setup or a change by hand.
  * @param {string} title

package/cli/doctor/checks/splash.js

@@ -17,34 +17,16 @@ const CIRCLE = 192;
 const LOGO_HEIGHT = /<dimen name="apex_navigation_splash_logo_height">([\d.]+)dp<\/dimen>/;
 
 /**
- * The native splash: made from its settings in package.json on both platforms, its logo whole on Android 12+; without
- * settings, a launch screen the navigation can't keep on screen until the first screen draws.
+ * The native splash: made from its settings in package.json on both platforms, its logo whole on Android 12+. Without
+ * settings there is nothing to check: the navigation keeps a copy of a storyboard and of `UILaunchScreen` alike.
  * @param {string} root
  * @param {Project} project
  * @returns {Check[]}
  */
 function splashChecks(root, project) {
-  const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
   const saved = readConfig(root).splash;
-  if (!saved) {
-    // UILaunchScreen alone: iOS shows it, but the navigation keeps only a storyboard while the first screen renders.
-    if (
-      plist?.includes('<key>UILaunchScreen</key>') &&
-      !plist.includes('<key>UILaunchStoryboardName</key>')
-    ) {
-      return [
-        {
-          group: 'app',
-          title: 'Launch screen',
-          status: 'warn',
-          detail:
-            'UILaunchScreen in Info.plist: an empty window shows between it and the first screen',
-          fix: SPLASH,
-        },
-      ];
-    }
-    return [];
-  }
+  if (!saved) return [];
+  const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
   const resolved = resolveSettings(root, {}, saved);
   if ('errors' in resolved) {
     return [

package/cli/migrate/native.js

@@ -3,6 +3,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { withReactNativeLoaded } = require('../setup/steps/mainApplication');
 
 /** @typedef {import('../changes').FileChange} FileChange */
 /** @typedef {import('./report').ReportItem} ReportItem */
@@ -158,6 +159,23 @@ function planNative(project) {
     const before = fs.readFileSync(file, 'utf8');
     let next = before;
     for (const [pattern, replacement] of rewrite.rules) next = next.replace(pattern, replacement);
+    // react-native-navigation loaded React Native itself; the navigation's application leaves it to the template's
+    // loadReactNative(this), which such an app doesn't have.
+    if (file === project.mainApplication && /:\s*NavigationApplication\(/.test(next)) {
+      const loaded = withReactNativeLoaded(next);
+      if (loaded !== undefined) next = loaded;
+      else {
+        report.push({
+          file: path.relative(root, file),
+          line: 1,
+          step: 'native',
+          before: 'onCreate',
+          after: 'super.onCreate() then loadReactNative(this), and no load of its own',
+          what: 'React Native loads through loadReactNative(this) in onCreate: add it by hand',
+          docs: `${DOCS}#native`,
+        });
+      }
+    }
     if (next !== before) {
       changes.push({
         name: path.basename(file),

package/cli/setup/source.js

@@ -35,7 +35,8 @@ function removeUnusedImports(text, names) {
   for (const name of names) {
     const line = new RegExp(`^import\\s+${escape(name)}[ \\t]*\\r?\\n`, 'm');
     const simple = name.slice(name.lastIndexOf('.') + 1);
-    const code = result.replace(/^import\s.*$/gm, '');
+    // A name in a comment is no use of the import.
+    const code = codeOf(result).replace(/^import\s.*$/gm, '');
     if (line.test(result) && !new RegExp(`\\b${escape(simple)}\\b`).test(code))
       result = result.replace(line, '');
   }

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/cli/splash/index.js

@@ -88,7 +88,9 @@ async function splash({
   }
   const plist = project.infoPlist && fs.readFileSync(project.infoPlist, 'utf8');
   if (plist?.includes('<key>UILaunchScreen</key>')) {
-    command.warn('Info.plist has UILaunchScreen too: remove it, so that iOS shows the storyboard.');
+    command.warn(
+      'Info.plist has UILaunchScreen too: iOS shows it instead of the storyboard; remove it, so that iOS shows the storyboard.'
+    );
   }
   return command.apply(
     [

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/containers/modals.md

@@ -52,8 +52,8 @@ Compose shows with a close button at the leading edge of its top bar. The settin
 
 | Setting | What it does |
 | --- | --- |
-| `closeButton` | A close button on the first screen: the system one on iOS, an icon on Android. Needs the stack. |
-| `onDismiss` | Called once the modal is gone, whatever closed it: a swipe, a command, a new root. |
+| `closeButton` | A close button on the first screen: the system one on iOS, an icon on Android. Needs the stack. A new first screen from `setStack` or `replace` in the modal's stack gets it too. |
+| `onDismiss` | Called once the modal is gone, whatever closed it: a swipe, a command, a new root. `setStack` and `replace` in the modal's stack replace its first screen and call it too. |
 | `stack` | `false`: the screen alone, without a stack and its top bar. |
 | `style`, `sheet`, `popover`, `contentSize` | How it looks: see [How a modal looks](#styles). |
 | `transition`, `options` | The animation, and the screen's options for this show. |

package/docs-md/guides/cli.md

@@ -311,7 +311,7 @@ Each file and why: [What the command writes](./splash-screen#files).
 - **The settings** go into `package.json`, under `apexNavigation.splash`. An option given replaces its saved value; to drop the dark logo or color, remove `darkLogo` or `darkBackground` there and run the command again.
 - **A logo whose corners leave the circle** of Android 12's splash icon, 192 dp, gets a warning: Android cuts them. Make `--logo-width` smaller, or give the logo room around it.
 - **A file it can't change** is listed as `manual`, with the change to make: an app without `Images.xcassets` next to `Info.plist`, a manifest whose `MainActivity` and `<application>` have no theme to go over.
-- **`Info.plist` with `UILaunchScreen`** as well gets a warning: remove that dictionary, so that iOS shows the storyboard.
+- **`Info.plist` with `UILaunchScreen`** as well gets a warning: iOS shows that dictionary instead of the storyboard, so remove it.
 - **Its errors** in the JSON: `splash-settings` for a setting it can't take, `splash-image` for a logo it can't read or that doesn't fit (too tall at its width, a dark logo of other proportions), and `sharp-missing`, as for `icons`.
 
 `doctor` checks the splash in the App group:
@@ -320,7 +320,6 @@ Each file and why: [What the command writes](./splash-screen#files).
 | --- | --- |
 | Splash | The files of iOS or Android aren't made from the settings in `package.json`: changed by hand, made on one platform only, or by an older version of the command. Or the settings themselves are wrong, such as a logo that isn't there. |
 | Splash logo | The logo's corners leave Android 12's circle. |
-| Launch screen | Without settings: `Info.plist` has `UILaunchScreen` and no storyboard. iOS shows it at launch, but the navigation can only keep a storyboard on screen, so an empty window shows between it and the first screen. |
 
 Each warning names its fix, such as `npx apex-navigation splash`; `--fix` leaves these to you. What the user sees, and a splash of your own after the native one: [Splash screen](./splash-screen).
 

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
 
@@ -215,9 +232,9 @@ A signed-in user sees Login for a moment, then the app.
 
 (iOS) Between the launch screen and the first screen, the window is empty for a moment.
 
-**Why:** the launch screen is made with the `UILaunchScreen` dictionary of `Info.plist`, not a storyboard. The navigation keeps a copy of a storyboard on screen until the first root, and can't make one of the dictionary. `doctor` warns about it under Launch screen.
+**Why:** the app has no launch screen the navigation can copy: `Info.plist` names no storyboard and has no `UILaunchScreen` dictionary (or `UILaunchScreens` default), and no legacy launch images.
 
-**Fix:** run `npx apex-navigation splash`, or name a storyboard in `UILaunchStoryboardName` and remove `UILaunchScreen`. More: [Make the native splash](../guides/splash-screen#command).
+**Fix:** run `npx apex-navigation splash`, or name a storyboard in `UILaunchStoryboardName`. More: [Make the native splash](../guides/splash-screen#command).
 
 ### Android brings the app back without its pushed screens
 

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
 
@@ -106,6 +106,17 @@ export const MapScreen = defineScreen({
 
 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.
 
+`animations.pop.preview: false` turns the preview off for a screen: the gesture shows nothing, and the screen pops when the user lets go, as on Android 13. It is read from the screen that goes, so the app's `options` turn it off everywhere:
+
+```ts
+defineScreen({
+  component: Checkout,
+  options: { animations: { pop: { preview: false } } },
+});
+```
+
+iOS ignores it: the swipe back there is UIKit's.
+
 ### 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.
@@ -122,6 +133,17 @@ Without it, back on the first screen still leaves the app, at once. See [What se
 
 With the animation on, the system leaves the app itself: an `invokeDefaultOnBackPressed` of the app's `MainActivity` (such as `moveTaskToBack(true)`) isn't called on the first screen. Without it, and before Android 13, the back goes through the activity as before.
 
+`hardwareBackButton.systemAnimation: false` keeps the back in the app on the first screen too, so the system plays no animation there: the gesture shows nothing, and on release the press goes to the [`BackHandler` listeners](#back-handler), then to the activity's own back, `invokeDefaultOnBackPressed` included. It is read from the screen back acts on; for the whole app, set it in the app's `options`:
+
+```ts
+createNavigation({
+  // …
+  options: { hardwareBackButton: { systemAnimation: false } },
+});
+```
+
+iOS ignores it.
+
 ### Handling back yourself: BackHandler
 
 (Android) React Native's `BackHandler` works on every screen, as in any React Native app. A listener runs before the navigation's own back: returning `true` takes the press, `false` passes it on to the next listener, then to the navigation.