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

package/src/ARCHITECTURE.md

@@ -63,7 +63,8 @@ form of `src/api/events/navigationEvents.ts`. Everything in `src/engine` is inte
   `LinkParams`, `PendingLink`, …). `linkPaths.ts`: a URL into its path and query (`parseLink`), the patterns ordered
   (`compileRoutes`) and matched (`matchLink`). `linking.ts`: the links of the app — the launch link, the `url` events
   of React Native's `Linking`, the routes run, the pending link opened after `setContext`. `pendingLinks.ts`: the one
-  waiting link and its listeners, which `navigation` and `usePendingLink` read.
+  waiting link and its listeners, which `navigation` and `usePendingLink` read. `dispatchedLinks.ts` (iOS): hands
+  `Linking` the links of `ANN.DeepLinkDispatched`.
 - `events/` — `navigationEvents.ts`: the events by name, the native event behind each, `onNavigationEvent`,
   `listeners`. `screenLifecycle.ts`: what goes when a screen unmounts, `whenScreenUnmounts`. `tabPresses.ts`: the
   handlers of `useTabPress`.
@@ -84,24 +85,26 @@ form of `src/api/events/navigationEvents.ts`. Everything in `src/engine` is inte
 
 ## `src/engine` — the engine
 
-| Module                      | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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)`: colors (iOS: a number, `DynamicColorIOS` or `'NoColor'`; Android: `{ light, dark }`), images (`require` resolved), components in options (`componentId`, their props kept here), 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).                                                                                                                                                                                                                                                                                                                                |
-| `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: the root with the newest root tag owns the screen, and an older one that unmounts leaves it alone. |
-| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `events.ts`                 | `toScreenEvent(event)`: an event of a screen as `listeners`, `navigation.on`, the screen hooks and `onPress` get it: the screen as `screen: { id, name }`, without the fields of the native side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `places.ts`                 | Where each screen is, noted as the commands build their layouts: the root, a modal or an overlay, its stack and its index there, its side menu, its pair (`arrangement`: the pair's id and its placement; `alone` for a primary shown without one, `noteAlone`). The column of a split view each stack shows (`columnOf`, `stackOfColumn`), and whether a split view's columns show as one stack (`ANN.SplitViewColumnsStacked`, `listenToSplitViews`): `showInColumn` notes its screen first in the column's stack, or over the screen that asks in the compact column, and the first screen of a column over the one before it can pop (`coversColumn`). `canPop`, `canDismiss`, `dismiss` and `placeFor` read it at once; `isGone` knows the last screens that went.                                                                            |
-| `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).                                                                                                                                                                                                                                                                                                                                 |
-| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `ids.ts`, `mergeOptions.ts` | `nextId` and the merge of options; see Ids and Options in layers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Module                      | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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, `{ 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `events.ts`                 | `toScreenEvent(event)`: an event of a screen as `listeners`, `navigation.on`, the screen hooks and `onPress` get it: the screen as `screen: { id, name }`, without the fields of the native side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `places.ts`                 | Where each screen is, noted as the commands build their layouts: the root, a modal or an overlay, its stack and its index there, its side menu, its pair (`arrangement`: the pair's id and its placement; `alone` for a primary shown without one, `noteAlone`). The column of a split view each stack shows (`columnOf`, `stackOfColumn`), and whether a split view's columns show as one stack (`ANN.SplitViewColumnsStacked`, `listenToSplitViews`): `showInColumn` notes its screen first in the column's stack, or over the screen that asks in the compact column, and the first screen of a column over the one before it can pop (`coversColumn`). `canPop`, `canDismiss`, `dismiss` and `placeFor` read it at once; `isGone` knows the last screens that went. It also notes the layouts each screen shows in (`layoutsOf`): a layout whose last screen went is gone, and so are the props of the components named in its options.                         |
+| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `ids.ts`, `mergeOptions.ts` | `nextId` and the merge of options; see Ids and Options in layers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 ## The start of the app
 
@@ -135,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.
@@ -247,15 +254,19 @@ name and on one id for two screens.
 
 `usePreview(nativeID, { screen, props, actions })` works on iOS only. It arms a `pushPreview` from its screen: a push
 with an id of its own (`Preview14`) and a `preview` option (`nativeID`, `commit`, the menu without its handlers, a
-size). The native side builds the screen and gives the view with that `nativeID` a context menu that previews it. A tap
-on the preview pushes the screen, the push resolves, and the hook arms the next one. A press of a menu item comes as
-`buttonPressed` of the preview's id, and the hook calls its `onPress`. A preview that goes without being shown rejects
-its push, which the hook ignores.
+size). The native side makes the screen's node at once and gives the view with that `nativeID` a context menu that
+previews it; a React screen gets its own root and renders when a press starts (the menu's configuration call, about
+0.5 s before the preview), so a hundred previews hold no rendered screens until one is pressed. A screen of the one
+tree (`appProvider`) and a native screen render at once. A tap on the preview pushes the screen, the push resolves, and
+the hook arms the next one. A press of a menu item comes as `buttonPressed` of the preview's id, and the hook calls its
+`onPress`. A preview that goes without being shown rejects its push, which the hook ignores. One that goes before its
+first press never mounted a root, so the engine forgets what the push noted for it (`forgetUnmountedPreview` in
+`src/engine/commands.ts`, after 1 s, unless a root of it mounted by then).
 
 ## 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
@@ -268,7 +279,9 @@ its push, which the hook ignores.
   given once; JS asks only with `linking`) and `getStartInfo` (synchronous: `coldStart`, true for the whole life of
   the first JavaScript runtime of the process, and `splashLogo`, the size of the native splash's logo the CLI wrote,
   or null; `arrangements`, whether it shows pairs). The links that come while the app runs reach JS through React Native's
-  `Linking`, not through `ANN.*` events.
+  `Linking`, not through `ANN.*` events. One exception, iOS only: a link the app dispatched (`dispatchDeepLinkURL`) that
+  `Linking` doesn't take from the native side (React Native 0.88 and newer, with a scene delegate) comes as
+  `ANN.DeepLinkDispatched`, and `src/api/linking/dispatchedLinks.ts` hands it to `Linking` as a `url` event.
 - Events: `ANN.AppLaunched`, `ANN.ComponentWillAppear`, `ANN.ComponentDidAppear`, `ANN.ComponentDidDisappear`,
   `ANN.NavigationButtonPressed`, `ANN.BottomTabSelected`, `ANN.BottomTabPressed`, `ANN.BottomTabLongPressed`,
   `ANN.ModalDismissed`, `ANN.ModalAttemptedToDismiss`, `ANN.ScreenPopped`, `ANN.SearchBarUpdated`,
@@ -276,8 +289,8 @@ its push, which the hook ignores.
   `ANN.NavigationStateChanged`, `ANN.SlotDestroyed`, `ANN.ScreenInsetsChanged`, `ANN.TitleRenamed`,
   `ANN.BottomAccessoryPlacementChanged`, `ANN.SheetDetentChanged`, `ANN.SplitViewDisplayModeChanged`,
   `ANN.KeyCommandPressed`, `ANN.NativeScreenCall`, `ANN.NativeScreenReleased`, `ANN.ScreenRegionsChanged`,
-  `ANN.ArrangementChanged`, `ANN.HingeChanged`, `ANN.SplitViewColumnsStacked`. Their payloads are typed in
-  `src/interfaces/ComponentEvents.ts` and `Events.ts`. Both platforms also send `ANN.CommandCompleted`
+  `ANN.ArrangementChanged`, `ANN.HingeChanged`, `ANN.SplitViewColumnsStacked`, `ANN.DeepLinkDispatched` (iOS). Their
+  payloads are typed in `src/interfaces/ComponentEvents.ts` and `Events.ts`. Both platforms also send `ANN.CommandCompleted`
   (`CommandCompletedEvent`), which nothing in JS listens to.
 - Native components: `ANNSlot` (`src/api/slots`) and `ANNSafeAreaView` (`src/api/safeArea`), with C++ of their own in
   `ios/cpp`, which Android builds too (their states hold a size and a padding; the first one comes from the props

package/src/adapters/NativeANNTurboModule.ts

@@ -14,7 +14,14 @@ 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;
-  /** Pushes a layout over the screen in its stack; resolves with the id of the screen that shows. */
+  /**
+   * (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>;
   /**
    * (Android, one React tree) Lays the screen of a coming push out in its stack before React renders it, and resolves
@@ -67,7 +74,10 @@ export interface Spec extends TurboModule {
     column: string,
     layout: CodegenTypes.UnsafeObject
   ): Promise<string>;
-  /** Shows or hides a column of the screen's split view; resolves once the columns stopped moving. */
+  /**
+   * Shows or hides a column of the screen's split view; resolves once the columns stopped moving, with nothing (on
+   * Android `null`).
+   */
   setColumnShown(
     commandId: string,
     componentId: 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,
@@ -43,6 +49,7 @@ import {
 import { launchState } from '../../engine/launchState';
 import { watchBackListeners } from '../../engine/backListeners';
 import { resolveRoot, type RootsMap, type RootTarget, type UsesOfRootValue } from './roots';
+import { listenToDispatchedLinks } from '../linking/dispatchedLinks';
 import {
   launchLink,
   launchRoot,
@@ -50,6 +57,7 @@ import {
   linksStarted,
   reportLink,
   setupLinking,
+  updateLinking,
 } from '../linking/linking';
 import type { LinkMatch } from '../linking/linkPaths';
 import type { LinkingConfig } from '../linking/types';
@@ -85,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();
@@ -150,9 +161,9 @@ interface BaseConfig<
   /** The look of the navigation: colors of the bars, tabs and backgrounds; `navigation.setTheme` changes it. */
   theme?: NavigationTheme;
   /**
-   * The edges on which every screen keeps its content out of its safe area. Without it: all four on Android; on iOS
-   * every edge but those where the content goes under a bar that shows. A screen gives its own with `safeArea(...)`
-   * in its options.
+   * The edges on which every screen keeps its content out of its safe area. Without it: the top and the sides, but
+   * those where the content goes under a bar (`layout.safeAreaEdges`); the bottom is free and a list keeps clear of it
+   * with `useSafeAreaInsets()`. A screen gives its own with `safeArea(...)` in its options.
    */
   safeArea?: { edges: SafeAreaEdge[] };
   /** (iOS) The app's window, behind the screens: seen around a modal as it comes in. */
@@ -239,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))
+  );
 }
 
 /**
@@ -276,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.
@@ -324,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.
@@ -332,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,
@@ -484,28 +512,22 @@ 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();
+      listenToDispatchedLinks();
       watchSideMenus();
       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.
@@ -526,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(