@apexnative/navigation 1.0.0-alpha.6 → 1.0.0-alpha.8

package/src/ARCHITECTURE.md

@@ -89,8 +89,8 @@ form of `src/api/events/navigationEvents.ts`. Everything in `src/engine` is inte
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `native.ts`                 | `commands`: the TurboModule (`src/adapters/NativeANNTurboModule.ts`). `onNativeEvent(name, listener)`: one native event, `ANN.<name>`. iOS sends events through `ANNTurboEventEmitter`; Android without a module. `getLaunchLink()`: the URL that launched the native side, null without the native side (Jest). `getStartInfo()`: `{ coldStart, splashLogo, arrangements }`, asked once; without the native side a cold start without a logo and without arrangements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `layout.ts`                 | `toNativeLayout(layout)`: a `LayoutNode`, `{ id, type, data: { name, options, passProps?, functions?, key?, columns? }, children }`. For a screen, in this order: a name that shows a pair becomes an `Arrangement` node (see Pairs, regions and the hinge), an unknown name fails, its id, its own options under those of the show, the press handlers of its buttons taken out; then a native screen goes as an external component (`showNativeScreen`), a React screen with its `key`, its props kept here, as a slot in one tree.                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `options.ts`                | `toNativeOptions(options, owner)`: colors (iOS: a number, `DynamicColorIOS` or `'NoColor'`; Android: `{ light, dark }`), images (`require` resolved), components in options (`componentId`, their props kept here; without an `id` of their own, `<owner>/<place>/<name>`, e.g. `Component12/topBar.title/Clock`, a list item by its id where it has one (`topBar.rightButtons[Save]`), the same on every `mergeOptions` of the node, so the native side keeps the mounted root), the props of buttons with a component, the roots of the bar buttons' components (`*Buttons`, the toolbar's `buttons`) remembered. Options come in their own form only.                                                                                                                                                                                                                                                                                                            |
-| `commands.ts`               | `setRoot`, `push`, `pop`, `popTo`, `popToRoot`, `setStackRoot`, `showInColumn`, `setColumnShown`, `showModal`, `dismissModal`, `dismissAllModals`, `showOverlay`, `dismissOverlay`, `dismissAllOverlays`, `mergeOptions`, `setDefaultOptions`. One that shows screens waits for lazy ones (`afterLoading`), checks the ids (`checkIds`), notes the places and waits for the hooks of native screens (`whenNativeScreensReady`). On Android, in one tree, a push goes through `preparePush` first (see One command).                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `options.ts`                | `toNativeOptions(options, owner)`: colors (iOS: a number, `{ light, dark }` or `'NoColor'`; Android: always `{ light, dark }`), images (`require` resolved), components in options (`componentId`, their props kept here; without an `id` of their own, `<owner>/<place>/<name>`, e.g. `Component12/topBar.title/Clock`, a list item by its id where it has one (`topBar.rightButtons[Save]`), the same on every `mergeOptions` of the node, so the native side keeps the mounted root), the props of buttons with a component, the roots of the bar buttons' components (`*Buttons`, the toolbar's `buttons`) remembered. Options come in their own form only.                                                                                                                                                                                                                                                                                                            |
+| `commands.ts`               | `setRoot`, `push`, `pop`, `popTo`, `popToRoot`, `setStackRoot`, `showInColumn`, `setColumnShown`, `showModal`, `dismissModal`, `dismissAllModals`, `showOverlay`, `dismissOverlay`, `dismissAllOverlays`, `mergeOptions`, `clearOptions` (Fast Refresh, development), `setDefaultOptions`. One that shows screens waits for lazy ones (`afterLoading`), checks the ids (`checkIds`), notes the places and waits for the hooks of native screens (`whenNativeScreensReady`). On Android, in one tree, a push goes through `preparePush` first (see One command).                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `screens.tsx`               | The screens by name: a React component with its options, `key`, `load` (a lazy screen) and `arrangement` (its pair, if it has a secondary), a native screen (`nativeName`, the controller of its `useProps`, `arrangement`), or a pair entry of `defineArrangement` (`pair`). `arrangementOf(name)`: the pair a name shows; `checkArrangements` at registration, `checkArrangement` when a lazy screen's pair shows. `loadScreens`/`afterLoading`: a command goes once its lazy screens loaded, at once when none waits. A React screen is registered with `AppRegistry` as a root (`screenRoot`) that renders it with the props left for its id. After a JavaScript reload React Native starts the old roots again under the new screens' ids: a root that unmounts while another root of the id is mounted leaves the screen alone. The props of a component the library named in options go with its node, not with a root (several roots may show one default). |
 | `nativeScreens.ts`          | The native screens shown, by id. Data props go as JSON (`passProps`); functions stay here, their names in `data.functions`, and the native side calls them (`ANN.NativeScreenCall`, answered with `resolveNativeScreenCall`). With `useProps`: the hidden host runs the hook (`startHost`, 5 s to start), the command waits for its first result, later changes go with `updateNativeScreenProps`. `ANN.NativeScreenReleased` forgets one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `props.ts`                  | The props of screens and of components in options, by id: a command puts them here before the native side creates the view; React Native passes a root only its id. Also which roots are the components of bar buttons (`isButtonRoot`): on iOS their wrapper centers the content in the slot.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
@@ -99,6 +99,8 @@ form of `src/api/events/navigationEvents.ts`. Everything in `src/engine` is inte
 | `buttons.ts`                | The `onPress` handlers of the buttons of each screen and of their menu items, called on `NavigationButtonPressed`; the API gives the event its form (`setPressEvent`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `tabs.ts`                   | The press handlers of `Tab().onPress()`: they come with the tabs' layout, stay under the id the tabs are shown with, and go once every React screen shown in the tabs (pushed ones too) unmounted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `slots.ts`                  | One tree (`appProvider`): `slotName` sends a React screen as `slot:<name>`, the native side gives it an empty container, and the slot with its id in `SlotHost` renders it. `withSlots` takes back the slots of a failed command; `ANN.SlotDestroyed` removes one. For a push on Android: `holdSlot` (nothing renders until the native side laid the screen out), `showSlot` (at its `SlotFrame`; resolves once React committed it, `slotCommitted`), `preparedPadding` (the first padding of its safe area view).                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `refresh.ts` | Development only. Fast Refresh runs an edited module again and every export is a new function; `familyOf` and the newest-version lookup read React Refresh's family of a component (Metro registers each export under its module and name), so what the library keeps of a screen (options, `key`, `arrangement`) follows an edit without a reload. Nothing in a release build. |
+| `optionsChange.ts` | `optionsChange(previous, next)`: what an edit of a screen's options changes: the options to merge (objects compare key by key, arrays and other values as a whole, functions by source) and the paths taken out, which go to the native `clearOptions`. |
 | `launchState.ts`            | The last root and default options: Android destroys the activity while JavaScript lives on and sends `AppLaunched` again; the app sets them again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `backListeners.ts`          | Android: wraps `BackHandler.addEventListener` at the launch to count the listeners, and tells the native side whether there is one (`setBackListeners`): the navigation takes the back button only while it can go back or JavaScript listens. A listener added before the launch isn't counted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `reactMeasures.ts`          | Development only: every command that shows or closes screens drops React's `performance.measure` entries of component renders (named after the component with U+200B in front). React Native keeps them without a limit, and a long session ran out of memory; the app's own measures stay.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -136,6 +138,10 @@ form of `src/api/events/navigationEvents.ts`. Everything in `src/engine` is inte
    `launchState.root`, as it was passed (functions in props included), is set again. Then, with `linking`, the new
    activity's link runs as in a running app (`linksRelaunched`).
 
+## Hot update
+
+`@apexnative/navigation/metro` (`withApexNavigation`) wraps the Metro config: it applies React Refresh's Babel plugin that React Native 0.87's transformer skips, and makes the module that imports `createNavigation` accept hot updates. When that module runs again, `createNavigation` meets a running navigation and updates it instead of starting: the screens (`registerScreens` again; a defined screen's options through `optionsChange` become `mergeOptions` and `clearOptions` on the screens that show; `key` and `arrangement` apply from the next show), the default options when `theme` or `options` changed, the roots, the listeners and the link routes. What only the start reads (the first root, `willMount`, the splash, the context) isn't run again. `defineScreen` returns the component, so a file that exports only screens is a Fast Refresh boundary; a native screen's component runs its `useProps`, and a change of its native name or of having `useProps` restarts the app.
+
 ## Links
 
 `linking` of `createNavigation` (`src/api/linking/`) turns URLs into commands; the native side keeps no routes.
@@ -260,7 +266,7 @@ first press never mounted a root, so the engine forgets what the push noted for
 ## The native side's contract
 
 - Commands: the methods of `ANNTurboModule` (`src/adapters/NativeANNTurboModule.ts`), with the JSON above: those of
-  `commands.ts`, each but `mergeOptions` and `setDefaultOptions` with a command id and a promise. A command that changed
+  `commands.ts`, each but `mergeOptions`, `clearOptions` and `setDefaultOptions` with a command id and a promise. A command that changed
   what the user sees sends `ANN.NavigationStateChanged` right before its promise resolves, so `getState()` after
   `await` shows its result and the next command acts from there. Besides them: `setBackListeners` (Android: whether
   JavaScript has `BackHandler` listeners; iOS does nothing), `preparePush` and `cancelPreparedPush` (Android, one

package/src/adapters/NativeANNTurboModule.ts

@@ -14,6 +14,13 @@ export interface Spec extends TurboModule {
   setDefaultOptions(options: CodegenTypes.UnsafeObject): void;
   /** Merges options into the layout with the id and applies them to what shows; an unknown id does nothing. */
   mergeOptions(componentId: string, options: CodegenTypes.UnsafeObject): void;
+  /**
+   * (Development) Takes the options at the paths (`topBar.subtitle`, a group's path for the whole group) out of the own
+   * options of the layout with the id, so it shows what the layouts around it and the defaults give there, and applies
+   * the result to what shows as `setDefaultOptions` does. An unknown id or path does nothing. Fast Refresh sends it
+   * for the options an edit took out of a screen that shows.
+   */
+  clearOptions(componentId: string, paths: ReadonlyArray<string>): void;
   /** Pushes a layout over the screen in its stack; resolves with the id of the screen that shows (of a pair: its id). */
   push(commandId: string, componentId: string, layout: CodegenTypes.UnsafeObject): Promise<string>;
   /**

package/src/api/app/AppRegistry.ts

@@ -1,8 +1,14 @@
 import { AppRegistry as ReactNativeAppRegistry } from 'react-native';
 import { onNativeEvent } from '../../engine/native';
+import { familyOf } from '../../engine/refresh';
 import { SLOT_HOST_MODULE } from '../../engine/slots';
 import { SlotHost } from '../slots/SlotHost';
-import { isNavigationApp, type NavigationApp, startApp } from './createNavigation';
+import {
+  isNavigationApp,
+  type NavigationApp,
+  noteReplacingApp,
+  startApp,
+} from './createNavigation';
 
 type NavigationAppProvider = () => NavigationApp<any, any>;
 
@@ -35,7 +41,15 @@ function registerComponent(
   navigation: NavigationApp<any, any> | NavigationAppProvider
 ): string {
   if (__DEV__ && registered) {
-    console.warn(`[navigation] '${key}' replaces the app registered as '${appKey}'`);
+    // The entry file running again after an edit (Fast Refresh) registers its new version of the same app under the
+    // same name; Metro puts one it exports in the family of the old one once the file ran.
+    if (key === appKey) noteReplacingApp(navigation);
+    const before = { key: appKey, app: registered };
+    Promise.resolve().then(() => {
+      const family = familyOf(before.app);
+      if (key === before.key || (family && family === familyOf(navigation))) return;
+      console.warn(`[navigation] '${key}' replaces the app registered as '${before.key}'`);
+    });
   }
   appKey = key;
   registered = navigation;

package/src/api/app/createNavigation.ts

@@ -1,7 +1,10 @@
 import type { ComponentType } from 'react';
+import { DevSettings } from 'react-native';
 import { setDefaultOptions, setRoot } from '../../engine/commands';
 import { type AppProvider, enableSlots, withSlots } from '../../engine/slots';
 import { listenToNativeScreens, startHost } from '../../engine/nativeScreens';
+import { sameValue } from '../../engine/optionsChange';
+import { familyOf, keepStateOf, refreshRuns } from '../../engine/refresh';
 import { listenToSplitViews } from '../../engine/places';
 import { hasNativeScreenHooks } from '../../engine/screens';
 import type { LayoutRoot } from '../../interfaces/Layout';
@@ -24,7 +27,10 @@ import type { ErrorFallbackProps } from '../screens/ScreenBoundary';
 import { getAppContext, setAppContext } from '../context/appContext';
 import {
   type AppOptionsInput,
+  getDirection,
+  getTheme,
   initTheme,
+  setTheme,
   type NavigationDirection,
   type NavigationTheme,
   themedDefaultOptions,
@@ -51,6 +57,7 @@ import {
   linksStarted,
   reportLink,
   setupLinking,
+  updateLinking,
 } from '../linking/linking';
 import type { LinkMatch } from '../linking/linkPaths';
 import type { LinkingConfig } from '../linking/types';
@@ -86,6 +93,9 @@ const starts = new WeakMap<NavigationApp<any, any>, () => Promise<void>>();
 
 /** Starts the app, or brings back its root when the native side launches again. */
 export function startApp(app: NavigationApp<any, any>): Promise<void> {
+  // An app made after another launched knows once its module ran whether it is that app's next version.
+  const waiting = pending.get(app);
+  if (waiting) return waiting.then(() => startApp(app));
   const start = starts.get(app);
   if (!start) throw new Error('[navigation] Not an app made by createNavigation');
   return start();
@@ -240,7 +250,11 @@ type CheckedRoots<Root, Roots, AppScreens> = {
 };
 
 export function isNavigationApp(value: unknown): value is NavigationApp {
-  return typeof value === 'object' && value !== null && starts.has(value as NavigationApp);
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (starts.has(value as NavigationApp) || pending.has(value as NavigationApp))
+  );
 }
 
 /**
@@ -277,14 +291,18 @@ export function createNavigation<
   > &
     NoInfer<CheckedRoots<FirstLayout, Roots, AllScreens<AppScreens, Groups>>>
 ): NavigationApp<Roots, AllScreens<AppScreens, Groups>> {
+  // The app that launched before, when this call may be its module running again after an edit (Fast Refresh): what
+  // the call starts waits until that is known.
+  const launched = __DEV__ ? hotCandidate() : undefined;
   // Counted from here: a "back again to leave" listener of the app's entry file comes after this call.
-  watchBackListeners();
+  if (!launched) watchBackListeners();
   // idle: not started yet, or the last start failed. mounting: the first root is on its way. mounted: it is shown.
   let phase: 'idle' | 'mounting' | 'mounted' = 'idle';
   let screensRegistered = false;
   // The splash shows at the first start of this runtime only: a start that failed and runs again goes without it.
   let splashChecked = false;
   let listening = false;
+  let removeListeners: (() => void) | undefined;
   let prepared: Promise<void> | undefined;
   let markMounted!: () => void;
   // A new activity came while the first root was on its way (Android): its link is taken once that root is shown.
@@ -325,6 +343,62 @@ export function createNavigation<
     return buildRoot(typeof root === 'function' ? root(context) : root);
   }
 
+  // The screens of the app, its groups, the screen of a failed start and the splash, with what wraps each of them.
+  function registerAppScreens() {
+    const wrapper = {
+      errorFallback: config.errorFallback,
+      loadingFallback: config.loadingFallback,
+      onError:
+        config.onError &&
+        ((error: unknown, screen: ScreenInfo, componentStack: string | null | undefined) =>
+          config.onError?.(error, { type: 'screen', screen, componentStack })),
+    };
+    registerScreens(
+      [
+        { source: 'screens', screens: config.screens ?? {} },
+        ...Object.entries(config.groups ?? {}).map(([group, { screens, options }]) => ({
+          source: `the group '${group}'`,
+          screens,
+          options,
+        })),
+        ...(config.errorFallback
+          ? [
+              {
+                source: 'the start',
+                screens: { [START_FAILURE_SCREEN]: startFailureScreen(config.errorFallback) },
+              },
+            ]
+          : []),
+      ],
+      { ...wrapper, provider: config.screenProvider }
+    );
+    // The splash renders before willMount ends: a root of its own, without the app's providers, which may need what
+    // willMount prepares.
+    if (config.splash) {
+      registerScreens(
+        [
+          {
+            source: 'the splash',
+            screens: { [SPLASH_SCREEN]: config.splash.component },
+            ownRoot: true,
+          },
+        ],
+        {
+          ...wrapper,
+          // A splash that failed to render can't call hide(): the start goes on without waiting for it.
+          onError: (
+            error: unknown,
+            screen: ScreenInfo,
+            componentStack: string | null | undefined
+          ) => {
+            releaseSplash();
+            wrapper.onError?.(error, screen, componentStack);
+          },
+        }
+      );
+    }
+  }
+
   async function mount() {
     phase = 'mounting';
     // The state before the first root: the links wait for a newer one, which tells the screen they act from.
@@ -333,54 +407,7 @@ export function createNavigation<
     let linkHandled = false;
     try {
       if (!screensRegistered) {
-        const wrapper = {
-          errorFallback: config.errorFallback,
-          loadingFallback: config.loadingFallback,
-          onError:
-            config.onError &&
-            ((error: unknown, screen: ScreenInfo, componentStack: string | null | undefined) =>
-              config.onError?.(error, { type: 'screen', screen, componentStack })),
-        };
-        registerScreens(
-          [
-            { source: 'screens', screens: config.screens ?? {} },
-            ...Object.entries(config.groups ?? {}).map(([group, { screens, options }]) => ({
-              source: `the group '${group}'`,
-              screens,
-              options,
-            })),
-            ...(config.errorFallback
-              ? [
-                  {
-                    source: 'the start',
-                    screens: { [START_FAILURE_SCREEN]: startFailureScreen(config.errorFallback) },
-                  },
-                ]
-              : []),
-          ],
-          { ...wrapper, provider: config.screenProvider }
-        );
-        // The splash renders before willMount ends: a root of its own, without the app's providers, which may need what
-        // willMount prepares.
-        if (config.splash) {
-          registerScreens(
-            [
-              {
-                source: 'the splash',
-                screens: { [SPLASH_SCREEN]: config.splash.component },
-                ownRoot: true,
-              },
-            ],
-            {
-              ...wrapper,
-              // A splash that failed to render can't call hide(): the start goes on without waiting for it.
-              onError: (error: unknown, screen: ScreenInfo, componentStack: string | null | undefined) => {
-                releaseSplash();
-                wrapper.onError?.(error, screen, componentStack);
-              },
-            }
-          );
-        }
+        registerAppScreens();
         screensRegistered = true;
       }
       // The link that launched the app is asked for first: on iOS the first React content to appear (the host below,
@@ -485,20 +512,13 @@ export function createNavigation<
   }
 
   async function launch() {
+    if (__DEV__) launchedApp = app;
     setActiveApp({ roots: config.roots, presentation: config.presentation, mounted });
     if (!listening) {
       listening = true;
       // The edges of `safeArea` go under the app's options; the window's color goes with them, as the native side
       // takes it from the default options.
-      initTheme(
-        config.theme,
-        {
-          under: config.safeArea && { layout: { safeAreaEdges: config.safeArea.edges } },
-          options: config.options,
-          over: config.window && { window: config.window },
-        },
-        config.direction
-      );
+      initTheme(config.theme, appDefaults(), config.direction);
       if (config.context !== undefined) setAppContext(config.context);
       if (config.appProvider) enableSlots(config.appProvider);
       listenToNavigationState();
@@ -507,7 +527,7 @@ export function createNavigation<
       listenToNativeScreens();
       listenToSplitViews();
       listenToNativeScreenCalls();
-      if (config.listeners) addNavigationListeners(config.listeners);
+      if (config.listeners) removeListeners = addNavigationListeners(config.listeners);
     }
     launchState.launch++;
     // A new activity has no default options: the last ones set come back, else the theme's and the app's.
@@ -528,19 +548,131 @@ export function createNavigation<
     relaunchWaiters.splice(0).forEach((resume) => resume());
   }
 
-  // The links listen from now on: one that comes before the native side launches waits for the first root.
-  if (config.linking) {
-    setupLinking(config.linking, {
+  // The routes of the links, the roots they name and where their errors go.
+  function linkingOptions() {
+    return {
       roots: config.roots,
-      onError: config.onError && ((error, url) => config.onError?.(error, { type: 'link', url })),
-    });
+      onError:
+        config.onError &&
+        ((error: unknown, url: string) => config.onError?.(error, { type: 'link', url })),
+    };
+  }
+
+  // Fast Refresh ran the module that makes the app again (development): its new config takes the place of the old.
+  // What only the start reads (the first root, willMount, the splash, the context) has done its part; the screens, the
+  // default options, the roots, the listeners and the links take the new one. A theme the same as before leaves the one
+  // the app set since. The providers and fallbacks are in the families of the ones before (`keepStateOf`): React
+  // Refresh puts the new ones in place, with the state of what they wrap.
+  function update(next: typeof config) {
+    const before = config;
+    // The app's one tree is set up at the start, or not: a provider added or taken out starts the app again.
+    if (!before.appProvider !== !next.appProvider) {
+      DevSettings.reload('[navigation] appProvider was added or taken out');
+      return;
+    }
+    config = next;
+    if (screensRegistered) registerAppScreens();
+    setActiveApp({ roots: config.roots, presentation: config.presentation, mounted });
+    // A direction the app set since stays too, unless the edit changes the config's.
+    const defaultsBefore = themedDefaultOptions();
+    const direction = sameValue(before.direction, next.direction) ? getDirection() : next.direction;
+    initTheme(getTheme(), appDefaults(), direction);
+    if (!sameValue(before.theme, next.theme)) {
+      setTheme(next.theme ?? {});
+    } else {
+      const defaults = themedDefaultOptions();
+      if (!sameValue(defaultsBefore, defaults)) setDefaultOptions(defaults ?? {});
+    }
+    if (listening) {
+      removeListeners?.();
+      removeListeners = config.listeners && addNavigationListeners(config.listeners);
+    }
+    if (config.linking && linkingStarted) updateLinking(config.linking, linkingOptions());
+    else startLinking();
+  }
+
+  // The default options of the app, under and over the theme's.
+  function appDefaults() {
+    return {
+      under: config.safeArea && { layout: { safeAreaEdges: config.safeArea.edges } },
+      options: config.options,
+      over: config.window && { window: config.window },
+    };
+  }
+
+  // The links listen from now on: one that comes before the native side launches waits for the first root.
+  let linkingStarted = false;
+  function startLinking() {
+    if (!config.linking || linkingStarted) return;
+    linkingStarted = true;
+    setupLinking(config.linking, linkingOptions());
+  }
+
+  // The components of the app keep their state across Fast Refresh, as the screens' do.
+  function keepComponentsState() {
+    if (!__DEV__) return;
+    keepStateOf(app, config.appProvider, 'appProvider');
+    keepStateOf(app, config.screenProvider, 'screenProvider');
+    keepStateOf(app, config.errorFallback, 'errorFallback');
+    keepStateOf(app, config.loadingFallback, 'loadingFallback');
+    keepStateOf(app, config.splash?.component, 'splash');
   }
 
   const app: NavigationApp<Roots, AllScreens<AppScreens, Groups>> = { [NAVIGATION_APP]: true };
-  starts.set(app, () => reportStart(launch));
+  keepComponentsState();
+  const start = () => {
+    startLinking();
+    starts.set(app, () => reportStart(launch));
+    if (__DEV__) updates.set(app, update as (config: unknown) => void);
+  };
+  if (!launched) {
+    start();
+    return app;
+  }
+  // Once the module ran, Metro has put its exports in the families of the ones of its run before: the same family as
+  // the app that launched, or the app's entry registering it under the app's name again (an app it doesn't export),
+  // means this is its module again, and the app that runs takes the new config.
+  pending.set(
+    app,
+    Promise.resolve().then(() => {
+      pending.delete(app);
+      const family = familyOf(app);
+      if ((family && family === familyOf(launched)) || replacing.delete(app)) {
+        updates.get(launched)?.(config);
+        starts.set(app, starts.get(launched)!);
+        updates.set(app, updates.get(launched)!);
+        return;
+      }
+      watchBackListeners();
+      start();
+    })
+  );
   return app;
 }
 
+// The app that launched in this runtime, and what takes the config of its module when it runs again (development).
+let launchedApp: NavigationApp<any, any> | undefined;
+const updates = new WeakMap<NavigationApp<any, any>, (config: unknown) => void>();
+// The apps made after the launch until their module ran, and those the app's entry registered again under its name.
+const pending = new WeakMap<NavigationApp<any, any>, Promise<void>>();
+const replacing = new WeakSet<NavigationApp<any, any>>();
+
+/**
+ * Notes an app the entry file registers under the name of the app that launched: the entry ran again after an edit
+ * (development), and the new app is the old one's next version.
+ */
+export function noteReplacingApp(app: unknown): void {
+  if (__DEV__ && launchedApp && typeof app === 'object' && app !== null && NAVIGATION_APP in app) {
+    replacing.add(app as NavigationApp<any, any>);
+  }
+}
+
+// The app that launched, when React Refresh runs and a new app may be its module running again: one its module
+// exports (Metro gives it a family), or one the entry registers again under the app's name.
+function hotCandidate(): NavigationApp<any, any> | undefined {
+  return launchedApp && refreshRuns() ? launchedApp : undefined;
+}
+
 // A willMount that never ends keeps the splash screen for good: in development the app hears of it.
 function warnIfLong(willMount: Promise<void>) {
   const timer = setTimeout(

package/src/api/events/navigationEvents.ts

@@ -166,10 +166,16 @@ export function onNavigationEvent<Name extends NavigationEventName>(
   return onNativeEvent(nativeName, deliver);
 }
 
-/** Listens to the events of `listeners`, for as long as the app runs. */
-export function addNavigationListeners(listeners: NavigationListeners) {
+/** Listens to the events of `listeners` until the function it gives is called. */
+export function addNavigationListeners(listeners: NavigationListeners): () => void {
+  const removers: (() => void)[] = [];
   for (const name of Object.keys(listeners) as NavigationEventName[]) {
     const handler = listeners[name];
-    if (handler) onNavigationEvent(name, handler as (event: NavigationEvents[typeof name]) => void);
+    if (handler) {
+      removers.push(
+        onNavigationEvent(name, handler as (event: NavigationEvents[typeof name]) => void)
+      );
+    }
   }
+  return () => removers.forEach((remove) => remove());
 }

package/src/api/index.ts

@@ -109,6 +109,7 @@ export type { NativeScreen } from './screens/nativeScreens';
 export { defineArrangement } from './screens/arrangement';
 export type { Arrangement, ArrangementDefinition, ScreenArrangement } from './screens/arrangement';
 export type {
+  DefinedScreen,
   OptionsEnvironment,
   ScreenDefinition,
   ScreenOptionsInput,

package/src/api/linking/linking.ts

@@ -6,7 +6,11 @@ import { commandsStarted, whenCommandsSettle } from '../commands/errors';
 import { getAppContext, subscribeAppContext } from '../context/appContext';
 import { buildRoot, type RootLayout } from '../layout/Root';
 import { navigation } from '../navigation';
-import { getNavigationState, whenScreenAfter, type NavigationState } from '../state/navigationState';
+import {
+  getNavigationState,
+  whenScreenAfter,
+  type NavigationState,
+} from '../state/navigationState';
 import {
   compileRoutes,
   matchLink,
@@ -68,6 +72,23 @@ export function setupLinking(
   setPendingLinkOpener((link) => run(link, routeOf(link), false));
 }
 
+/**
+ * Takes the routes, the roots and `onError` of an app whose module ran again after an edit (Fast Refresh, development):
+ * the links that come from now on find the new routes.
+ */
+export function updateLinking(
+  linking: Config,
+  options: {
+    roots: RootsMap | undefined;
+    onError: ((error: unknown, url: string) => void) | undefined;
+  }
+): void {
+  config = linking;
+  roots = options.roots;
+  onError = options.onError;
+  routes = compileRoutes(Object.keys(linking.routes));
+}
+
 /**
  * The link that launched the app, matched as the app starts (`unmatched` may run commands then); the same one for
  * every try of the first start.

package/src/api/screens/defineScreen.ts

@@ -1,5 +1,6 @@
-import type { ComponentType } from 'react';
+import { type ComponentType, createElement } from 'react';
 import type { Options } from '../../interfaces/Options';
+import { keepStateOf, newestType, redefined } from '../../engine/refresh';
 import { getAppContext } from '../context/appContext';
 import { readScreenOptions, ScreenOptions } from '../options/ScreenOptions';
 import { getTheme, type NavigationTheme } from '../theme/theme';
@@ -38,12 +39,55 @@ export interface ScreenDefinition<Props = any> {
   arrangement?: ScreenArrangement<Props & object>;
 }
 
+const SCREEN_DEFINITION = Symbol('apexnative.navigation.screenDefinition');
+
+/**
+ * A screen of `defineScreen`: a component of its own, which renders the screen's component and carries the screen's
+ * definition. It goes right into `screens` of createNavigation, and rendered on its own (a test) it renders the screen.
+ */
+export type DefinedScreen<Props> = ComponentType<Props> & {
+  readonly [SCREEN_DEFINITION]: ScreenDefinition<Props>;
+};
+
+/**
+ * Describes a screen next to its component, so its registration stays one line. It gives a component that renders the
+ * screen and goes right into `screens` of createNavigation: a file that exports only its screens stays a boundary of
+ * Fast Refresh, so an edit of the screen, its options too, updates it in place instead of reloading the app.
+ */
+export function defineScreen<Props>(definition: ScreenDefinition<Props>): DefinedScreen<Props> {
+  const { component } = definition;
+  // A component of each definition, so the app's own component stays as it is for any other use of it.
+  const Component = component as ComponentType<object>;
+  function Screen(props: Props) {
+    return createElement(Component, props as object);
+  }
+  Screen.displayName = component.displayName ?? component.name;
+  Object.defineProperty(Screen, SCREEN_DEFINITION, { value: definition });
+  keepStateOf(Screen, component);
+  redefined(Screen);
+  return Screen as DefinedScreen<Props>;
+}
+
 /**
- * Describes a screen next to its component, so its registration stays one line. The same object can go right into
- * `screens` of createNavigation.
+ * The definition a screen of `defineScreen` carries, the newest one after Fast Refresh ran the screen's module again;
+ * undefined for anything else.
  */
-export function defineScreen<Props>(definition: ScreenDefinition<Props>): ScreenDefinition<Props> {
-  return definition;
+export function definitionOf(value: unknown): ScreenDefinition | undefined {
+  return isDefinedScreen(value) ? ownDefinitionOf(newestType(value)) : undefined;
+}
+
+/** The definition a screen of `defineScreen` carries itself, not a newer one; undefined for anything else. */
+export function ownDefinitionOf(value: unknown): ScreenDefinition | undefined {
+  return isDefinedScreen(value) ? value[SCREEN_DEFINITION] : undefined;
+}
+
+/** Whether the value is a screen of `defineScreen`. */
+export function isDefinedScreen(value: unknown): value is DefinedScreen<any> {
+  return (
+    (typeof value === 'function' || typeof value === 'object') &&
+    value !== null &&
+    SCREEN_DEFINITION in value
+  );
 }
 
 export function buildScreenOptions<Props>(