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

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(

package/src/api/commands/commands.ts

@@ -19,7 +19,7 @@ import { stackChild, type StackEntry } from '../layout/Stack';
 import { badgeText } from '../layout/Tabs';
 import { mergeOptions } from '../../engine/mergeOptions';
 import { buildScreenOptions, type ScreenOptionsInput } from '../screens/defineScreen';
-import { coversColumn, placeOf } from '../../engine/places';
+import { coversColumn, firstScreenOf, placeOf, type ScreenPlace } from '../../engine/places';
 import { command, placeFor } from './errors';
 import type { ColumnConfig, ModalConfig, OverlayConfig, PushConfig } from './presentation';
 import { defined, modalAnimations, pushAnimations } from './transitions';
@@ -30,6 +30,10 @@ const CLOSE_BUTTON = 'CloseButton';
 // The modals shown by `showModal`, for the ids of their first screens.
 let modals = 0;
 
+// The stacks of the modals shown with a close button, by id: `setStack` and `replace` there give it to the new first
+// screen. A stack's id is its modal's layer.
+const closeButtonStacks = new Set<string>();
+
 // The settings of a command with the props of the screen it shows.
 type WithProps<Config> = Config & { props?: object };
 
@@ -115,7 +119,19 @@ export function popToRoot(fromId: string): Promise<string> {
 export function setStack(fromId: string, entries: StackEntry[]): Promise<string> {
   return command('setStack', () => {
     placeFor('setStack', fromId, { stack: true });
-    return withSlots(() => engine.setStackRoot(fromId, entries.map(stackChild)));
+    const children = entries.map(stackChild);
+    const first = children[0]?.component;
+    if (!first || !hasCloseButton(placeOf(fromId))) {
+      return withSlots(() => engine.setStackRoot(fromId, children));
+    }
+    return afterLoading([first.name], () => {
+      // The screen's own buttons stay after the close button: the options of the layout replace them.
+      const id = first.id ?? nextId('Component');
+      const own = screenOptions(first.name, first.passProps ?? {});
+      const options = withCloseButton(mergeOptions(own, first.options ?? {}), id);
+      const withButton = { component: { ...first, id, options } };
+      return withSlots(() => engine.setStackRoot(fromId, [withButton, ...children.slice(1)]));
+    });
   });
 }
 
@@ -133,11 +149,12 @@ export function replace(
     return afterLoading([name], () => {
       const { props } = config;
       const base = getActiveApp()?.presentation?.push;
-      const options = showOptions(name, props, AS_PUSH, base?.options, config.options, {
+      const id = nextId('Component');
+      let options = showOptions(name, props, AS_PUSH, base?.options, config.options, {
         app: pushAnimations(base?.transition),
         call: pushAnimations(config.transition),
       });
-      const id = nextId('Component');
+      if (hasCloseButton(placeOf(fromId))) options = withCloseButton(options, id);
       return withSlots(() =>
         engine.setStackRoot(fromId, [screenLayout(name, props, options, id)])
       ).then(() => id);
@@ -192,16 +209,25 @@ function showModalNow(name: string, config: WithProps<ModalConfig>): Promise<str
     app: modalAnimations(base.transition),
     call: modalAnimations(call.transition),
   });
-  if (settings.closeButton && settings.stack !== false)
+  // The stack gets its id here, so that the commands in it later know the modal had a close button.
+  const stackId = nextId('Stack');
+  const closeButton = settings.closeButton && settings.stack !== false;
+  if (closeButton) {
     options = withCloseButton(options, screenId);
+    closeButtonStacks.add(stackId);
+    forgetWithStack(stackId, screenId);
+  }
   if (call.onDismiss) whenScreenUnmounts(screenId, call.onDismiss);
   const screen = screenLayout(name, props, options, screenId);
   const presentation = presentationOptions(settings);
   const layout: Layout =
     settings.stack === false
       ? mergeLayoutOptions(screen, presentation)
-      : { stack: { children: [screen], options: presentation } };
-  return withSlots(() => engine.showModal(layout));
+      : { stack: { id: stackId, children: [screen], options: presentation } };
+  const shown = withSlots(() => engine.showModal(layout));
+  // A modal that never showed has no stack to remember.
+  if (closeButton) shown.catch(() => closeButtonStacks.delete(stackId));
+  return shown;
 }
 
 export function dismissModal(modalId: string): Promise<string> {
@@ -340,6 +366,21 @@ export function holdLeave(screenId: string, onAttempt: () => void): () => void {
   };
 }
 
+// Whether a screen is in the stack of a modal shown with a close button: the modal's own stack, not one in it.
+function hasCloseButton(place: ScreenPlace | undefined): boolean {
+  return place?.stack != null && place.stack === place.layer && closeButtonStacks.has(place.stack);
+}
+
+// The stack of a modal is gone with its last first screen: one that unmounts with no other first screen noted after
+// it (`setStack`, `replace` note theirs before the old one goes).
+function forgetWithStack(stackId: string, screenId: string): void {
+  whenScreenUnmounts(screenId, () => {
+    const next = firstScreenOf(stackId);
+    if (next) forgetWithStack(stackId, next);
+    else closeButtonStacks.delete(stackId);
+  });
+}
+
 /** The options with a close button first at the leading edge, which dismisses the modal of the screen. */
 function withCloseButton(options: Options, screenId: string): Options {
   const close: NavigationButton = {

package/src/api/commands/presentation.ts

@@ -43,12 +43,13 @@ export interface ModalConfig {
   stack?: boolean;
   /**
    * A close button at the leading edge of the modal's first screen, which dismisses the modal: the system one on iOS,
-   * an icon on Android. Its id and testID are `CloseButton`. Needs the stack.
+   * an icon on Android. Its id and testID are `CloseButton`. Needs the stack. A new first screen of that stack, from
+   * `setStack` or `replace`, gets it too.
    */
   closeButton?: boolean;
   /**
-   * Called once the modal is gone, whatever dismissed it: a command, a swipe, a new root. `setStack` inside the
-   * modal replaces its first screen, and calls it too.
+   * Called once the modal is gone, whatever dismissed it: a command, a swipe, a new root. `setStack` and `replace`
+   * inside the modal replace its first screen, and call it too.
    */
   onDismiss?: () => void;
   /**

package/src/api/events/navigationEvents.ts

@@ -48,7 +48,7 @@ export interface NavigationEvents {
   searchCancelled: ScreenEventOf<SearchBarCancelPressedEvent>;
   /** #### (iOS 16+, Android) The user picked a suggestion of `searchBar.suggestions`; the text stays. */
   searchSuggestionPicked: ScreenEventOf<NativeSearchSuggestionPickedEvent>;
-  /** #### (iOS specific) */
+  /** The user dragged a sheet to another detent. */
   sheetDetentChanged: ScreenEventOf<NativeSheetDetentChangedEvent>;
   /** #### (iOS specific) */
   splitViewDisplayModeChanged: NativeSplitViewDisplayModeChangedEvent;
@@ -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/hooks/useNavigation.ts

@@ -22,7 +22,7 @@ import type { ScreenName, ShowArgs } from '../types';
 interface ScreenCommands {
   /** The screen the commands act from. */
   readonly screen: ScreenInfo;
-  /** Shows a screen over this one in its stack; resolves with the id of the screen shown. */
+  /** Shows a screen over this one in its stack; resolves with the id of the screen shown (for a pair, the pair's id). */
   push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>;
   /**
    * Goes back to the screen before this one in its stack. The first screen of a split view column shown over the list
@@ -177,14 +177,19 @@ function stackCommands(id: string): StackCommands {
   };
 }
 
-/** The commands of the center for a menu screen: the menu closes once the center has changed. */
+/**
+ * The commands of the center for a menu screen: the menu closes as the center changes, and the command resolves once
+ * both are done.
+ */
 function fromCenter(center: string, menuScreen: string): StackCommands {
   const centerCommands = stackCommands(center);
+  // As in the system's apps, the menu starts to close at the pick and the center changes as it goes, so a push is seen
+  // sliding in. The command settles after both, so the next one acts from the center; either one's error rejects it.
   const closing =
     <Args extends unknown[], Result>(run: (...args: Args) => Promise<Result>) =>
     async (...args: Args) => {
-      const result = await run(...args);
-      await closeMenu(menuScreen);
+      const closed = closeMenu(menuScreen);
+      const [result] = await Promise.all([run(...args), closed]);
       return result;
     };
   return {

package/src/api/hooks/useSafeAreaInsets.ts

@@ -5,13 +5,14 @@ import { useScreen } from './screenHooks';
 /**
  * How much of this screen's content the bars and the system still cover on each side, past what the screen keeps its
  * content off itself (`layout.safeAreaEdges`): 0 on an edge the screen pads, the whole inset on an edge its content goes
- * under — under a top bar, under the vertical bar at the side of iPhone Duo, every edge with `safeAreaEdges: []`. A list
- * adds exactly this to its own padding. The native side measures every screen on its own, also the screens of
+ * under — the bottom by default (the home indicator, the navigation bar, a tab bar or toolbar the screen goes under),
+ * under a top bar, under the vertical bar at the side of iPhone Duo, every edge with `safeAreaEdges: []`. A list adds
+ * exactly this to its own padding. The native side measures every screen on its own, also the screens of
  * `appProvider`.
  *
  * @example
  * const insets = useSafeAreaInsets();
- * <ScrollView contentContainerStyle={{ paddingLeft: 16 + insets.left, paddingRight: 16 + insets.right }} />
+ * <ScrollView contentContainerStyle={{ paddingBottom: 16 + insets.bottom }} />
  */
 export function useSafeAreaInsets(): EdgeInsets {
   const { id } = useScreen();

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/dispatchedLinks.ts

@@ -0,0 +1,18 @@
+import { DeviceEventEmitter, Platform } from 'react-native';
+import { onNativeEvent } from '../../engine/native';
+import type { DeepLinkDispatchedEvent } from '../../interfaces/Events';
+
+let listening = false;
+
+/**
+ * (iOS) Hands `Linking` the links the app dispatched that it didn't take from the native side: on React Native 0.88
+ * and newer, in an app with a scene delegate, it takes only the links a scene opened. `Linking` listens to its `url`
+ * events through `DeviceEventEmitter`, so every listener of the app gets them, the navigation's links too.
+ */
+export function listenToDispatchedLinks() {
+  if (listening || Platform.OS !== 'ios') return;
+  listening = true;
+  onNativeEvent<DeepLinkDispatchedEvent>('DeepLinkDispatched', ({ url }) => {
+    DeviceEventEmitter.emit('url', { url });
+  });
+}

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/navigation.ts

@@ -55,7 +55,10 @@ export interface AppNavigation {
   switchTo<const Layout extends Exclude<RootLayout, string>>(
     layout: Layout & NoInfer<CheckedScreens<UsesOfRoot<Layout>, RegisteredScreens>>
   ): Promise<void>;
-  /** Shows a screen in the stack of the screen the user sees; resolves with the id of the screen shown. */
+  /**
+   * Shows a screen in the stack of the screen the user sees; resolves with the id of the screen shown (for a pair, the
+   * pair's id).
+   */
   push<Name extends ScreenName>(name: Name, ...args: ShowArgs<Name, PushConfig>): Promise<string>;
   /** Goes back in the stack of the screen the user sees; see `useNavigation().pop`. */
   pop(): Promise<string>;