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

package/ios/TurboModules/ANNTurboModule.mm

@@ -1,13 +1,17 @@
 #import "ANNTurboModule.h"
 #import "ANNAppDirection.h"
 #import "ANNArrangementState.h"
+#import "ANNArrangementViewController.h"
 #import "ANNCommandRunner.h"
 #import "ANNComponentViewController.h"
 #import "ANNDeepLinkQueue.h"
 #import "ANNDefaultOptions.h"
+#import "ANNErrorHandler.h"
 #import "ANNErrorTexts.h"
+#import "ANNEventContract.h"
 #import "ANNExternalViewController.h"
 #import "ANNHinge.h"
+#import "ANNJavaScriptCalls.h"
 #import "ANNLayoutReader.h"
 #import "ANNModalCoordinator.h"
 #import "ANNNativeScreenCalls.h"
@@ -19,14 +23,16 @@
 #import "ANNPreviewInteraction.h"
 #import "ANNPreviewPush.h"
 #import "ANNRootCoordinator.h"
-#import "ANNScreenInsets.h"
-#import "ANNScreenRegions.h"
+#import "ANNScreenEnvironment.h"
 #import "ANNSlotHost.h"
 #import "ANNSplitViewCommands.h"
 #import "ANNSystemUI.h"
 #import "ANNStackCommands.h"
 #import "ApexNavigation+Internal.h"
 #import "UIViewController+LayoutProtocol.h"
+#import <React/RCTCallInvokerModule.h>
+#import <React/RCTInitializing.h>
+#import <React/RCTInvalidating.h>
 
 // How many modules this process made: the first one is a cold start, the next ones come with reloads of JavaScript.
 static NSUInteger ANNTurboModuleCount;
@@ -82,9 +88,14 @@ static BOOL ANNFindsScreen(NSString *componentId, ANNCommandAnswer *answer) {
     return NO;
 }
 
-// Every asynchronous method takes the one path of `ANNCommandRunner`: on the module's queue the layout is read and
-// checked whole, then one task on the main queue runs the command with its area's class. A question answers at once on
-// the JavaScript thread what it answers before the first data.
+// The module's call invoker goes to `ANNJavaScriptCalls`, so that a step of the core can come after the calls
+// JavaScript made (a push after the options of its screen's first commit).
+@interface ANNTurboModule () <RCTCallInvokerModule, RCTInitializing, RCTInvalidating>
+@end
+
+// Every asynchronous method comes on the main queue and takes the one path of `ANNCommandRunner`: in that one task the
+// layout is read and checked whole, then the command runs with its area's class. A question answers at once on the
+// JavaScript thread what it answers before the first data.
 @implementation ANNTurboModule {
     BOOL _coldStart;
     id _splashLogo;
@@ -92,10 +103,20 @@ static BOOL ANNFindsScreen(NSString *componentId, ANNCommandAnswer *answer) {
 
 RCT_EXPORT_MODULE(ANNTurboModule)
 
+// React Native gives the module its call invoker before `initialize`.
+@synthesize callInvoker = _callInvoker;
+
 + (BOOL)requiresMainQueueSetup {
     return NO;
 }
 
+// The asynchronous methods and `invalidate` come here, where every command runs: a call goes from the JavaScript thread
+// straight to the main queue, without waiting behind other modules on React Native's shared queue and without a second
+// hop. The synchronous questions stay on the JavaScript thread (React Native calls them there whatever the queue).
+- (dispatch_queue_t)methodQueue {
+    return dispatch_get_main_queue();
+}
+
 - (instancetype)init {
     if (self = [super init]) {
         @synchronized(ANNTurboModule.class) {
@@ -107,6 +128,14 @@ RCT_EXPORT_MODULE(ANNTurboModule)
     return self;
 }
 
+- (void)initialize {
+    [ANNJavaScriptCalls setCallInvoker:_callInvoker ofModule:self];
+}
+
+- (void)invalidate {
+    [ANNJavaScriptCalls moduleWent:self];
+}
+
 - (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
     (const facebook::react::ObjCTurboModule::InitParams &)params {
     return std::make_shared<facebook::react::NativeANNTurboModuleSpecJSI>(params);
@@ -137,7 +166,7 @@ RCT_EXPORT_MODULE(ANNTurboModule)
 // navigation has a host. React Native starts its surface once the bundle ran.
 - (void)startHost {
     [ANNCommandRunner runVoid:@"startHost"
-                         what:@"startHost"
+                         what:@"start the host of the slots"
                          body:^{
                            RCTHost *host = [ApexNavigation getHost];
                            if (host) {
@@ -168,22 +197,23 @@ RCT_EXPORT_MODULE(ANNTurboModule)
                          }];
 }
 
-// `mergeOptions`: a node nobody has (not made yet, gone, a reload) takes nothing, without a log; a node of a modal that
-// goes with the old root is not shown (logged). The values that could be read merge even when one couldn't. The whole
-// apply is one Core Animation transaction, closed on any error. Then the modal or the overlay of the node takes the
-// merge once (`mergeOptions` step 5).
+// `mergeOptions`: without the navigation's window it logs `nowhereToShow` (JavaScript keeps the options for the next
+// root); a node nobody has (not made yet, gone, a reload) or a node of a modal that goes with the old root takes
+// nothing, without a log, as on Android. The values that could be read merge even when one couldn't. The whole apply
+// is one Core Animation transaction, closed on any error. Then the modal or the overlay of the node takes the merge
+// once (`mergeOptions` step 5).
 - (void)mergeOptions:(NSString *)componentId options:(NSDictionary *)options {
     NSString *what = ANNWhat(@"merge the options of the screen '%@'", componentId);
     [ANNCommandRunner runVoid:@"mergeOptions"
                          what:what
                          body:^{
-                           UIViewController *node = [ANNNodeRegistry nodeForComponentId:componentId];
-                           if (!node) {
+                           if (!ApexNavigation.mainWindow) {
+                               [ANNCommandRunner logFailure:@"mergeOptions"
+                                                       text:ANNErrorTexts.nowhereToShow];
                                return;
                            }
-                           if ([ANNModalCoordinator isWithOldRoot:node]) {
-                               NSString *text = [ANNErrorTexts screenNotShown:componentId];
-                               [ANNCommandRunner logFailure:@"mergeOptions" text:text];
+                           UIViewController *node = ANNCommandNode(componentId);
+                           if (!node) {
                                return;
                            }
                            NSString *unreadablePath = nil;
@@ -216,6 +246,51 @@ RCT_EXPORT_MODULE(ANNTurboModule)
                          }];
 }
 
+// `clearOptions` (development: Fast Refresh took options out of a screen that shows): the values at the paths leave
+// the node's own options, so it resolves to what its parents and the defaults give there, and what shows applies the
+// new resolution as after `setDefaultOptions`. The window and the node are found as for `mergeOptions`; an unknown
+// id, or no path that names an option, does nothing, without a log. The user layer stays.
+- (void)clearOptions:(NSString *)componentId paths:(NSArray *)paths {
+    NSString *what = ANNWhat(@"clear the options of the screen '%@'", componentId);
+    [ANNCommandRunner runVoid:@"clearOptions"
+                         what:what
+                         body:^{
+                           if (!ApexNavigation.mainWindow) {
+                               [ANNCommandRunner logFailure:@"clearOptions"
+                                                       text:ANNErrorTexts.nowhereToShow];
+                               return;
+                           }
+                           UIViewController *node = ANNCommandNode(componentId);
+#if __IPHONE_OS_VERSION_MAX_ALLOWED >= 270100
+                           // The options set with a pair's id are its primary's, as for `mergeOptions`.
+                           if (@available(iOS 27.1, *)) {
+                               if ([node isKindOfClass:ANNArrangementViewController.class]) {
+                                   node = ((ANNArrangementViewController *)node).primary;
+                               }
+                           }
+#endif
+                           NSMutableArray<NSArray<NSString *> *> *keyPaths = [NSMutableArray new];
+                           for (id path in [paths isKindOfClass:NSArray.class] ? paths : @[]) {
+                               if ([path isKindOfClass:NSString.class] && [path length] > 0) {
+                                   [keyPaths addObject:[path componentsSeparatedByString:@"."]];
+                               }
+                           }
+                           if (!node || keyPaths.count == 0) {
+                               return;
+                           }
+                           __block BOOL cleared = NO;
+                           [node changeOwnOptions:^(ANNNavigationOptions *options) {
+                             for (NSArray<NSString *> *keyPath in keyPaths) {
+                                 cleared = [options clearValueAtPath:keyPath] || cleared;
+                             }
+                           }];
+                           // Paths that name no option change nothing that shows.
+                           if (cleared) {
+                               [ANNOptionsRepaint applyNewDefaultOptions:ANNDefaultOptions.current];
+                           }
+                         }];
+}
+
 #pragma mark - Stack
 
 - (void)push:(NSString *)commandId
@@ -242,13 +317,13 @@ RCT_EXPORT_MODULE(ANNTurboModule)
                      }];
 }
 
-// iOS lays out no screen before its push: always null.
+// iOS lays out no screen before its push: always null (`NSNull`; nil would reach JavaScript as `undefined`).
 - (void)preparePush:(NSString *)commandId
         componentId:(NSString *)componentId
              layout:(NSDictionary *)layout
             resolve:(RCTPromiseResolveBlock)resolve
              reject:(RCTPromiseRejectBlock)reject {
-    resolve(nil);
+    [ANNErrorHandler resolve:resolve of:@"preparePush" value:NSNull.null];
 }
 
 - (void)cancelPreparedPush:(NSString *)componentId {
@@ -313,7 +388,7 @@ RCT_EXPORT_MODULE(ANNTurboModule)
                      }];
 }
 
-// The screens may be none here; the command rejects that with the id of its screen, on the module's queue too.
+// The screens may be none here; the command rejects that with the id of its screen, in its check too.
 - (void)setStackRoot:(NSString *)commandId
          componentId:(NSString *)componentId
               layout:(NSArray *)layout
@@ -499,19 +574,20 @@ RCT_EXPORT_MODULE(ANNTurboModule)
 
 #pragma mark - Questions answered at once
 
-// The stores are written on the main queue and read here under their own locks: JavaScript reads them during a
-// screen's first render, so the answer never waits for the main queue.
+// The screen's environment is written on the main queue and read here under its lock (the hinge under its own):
+// JavaScript reads it during a screen's first render, so the answer never waits for the main queue.
 - (NSDictionary *)getArrangementState:(NSString *)componentId {
-    return [ANNArrangementState stateForScreenId:componentId] ?: @{};
+    return [ANNScreenEnvironment arrangementForScreenId:componentId] ?: @{};
 }
 
 - (NSDictionary *)getScreenInsets:(NSString *)componentId {
-    return [ANNScreenInsets insetsForScreenId:componentId] ?: @{};
+    return [ANNScreenEnvironment insetsForScreenId:componentId] ?: @{};
 }
 
 - (NSDictionary *)getScreenRegions:(NSString *)componentId {
-    NSDictionary *regions = [ANNScreenRegions regionsForScreenId:componentId];
-    return regions ?: @{@"division" : @[], @"occlusion" : @[]};
+    NSDictionary *regions = [ANNScreenEnvironment regionsForScreenId:componentId];
+    const auto &keys = ANNEventContract.ScreenRegionsChanged;
+    return regions ?: @{keys.division : @[], keys.occlusion : @[]};
 }
 
 // `setHingeUpdates`: JavaScript counts its `useHinge` hooks; the events go with the emitter of the JavaScript that runs
@@ -548,26 +624,21 @@ RCT_EXPORT_MODULE(ANNTurboModule)
                     check:nil
                      body:^(id layout, ANNCommandAnswer *answer) {
                        // The links module answers once the launch links are known, at once in the background
-                       // (`getLaunchLink`): the URL, or null.
+                       // (`getLaunchLink`): the URL, or null (`NSNull`; nil would reach JavaScript as `undefined`).
                        [ANNDeepLinkQueue takeLaunchLink:^(NSURL *url) {
-                         [answer resolve:url.absoluteString];
+                         [answer resolve:url.absoluteString ?: (id)NSNull.null];
                        }];
                      }];
 }
 
 - (void)updateNativeScreenProps:(NSString *)componentId update:(NSDictionary *)update {
     NSString *what = ANNWhat(@"updateNativeScreenProps for the screen '%@'", componentId);
-    // At once, also during a transition; a node that isn't a native screen, or no node, takes nothing.
+    // At once, also during a transition; a node that isn't a native screen, no node, or a node of a modal that goes
+    // with the old root takes nothing, without a log, as on Android.
     [ANNCommandRunner runVoid:@"updateNativeScreenProps"
                          what:what
                          body:^{
                            UIViewController *node = ANNCommandNode(componentId);
-                           // A node of a modal that goes with the old root is not shown.
-                           if (!node && [ANNNodeRegistry nodeForComponentId:componentId]) {
-                               NSString *text = [ANNErrorTexts screenNotShown:componentId];
-                               [ANNCommandRunner logFailure:@"updateNativeScreenProps" text:text];
-                               return;
-                           }
                            if ([node isKindOfClass:ANNExternalViewController.class]) {
                                [((ANNExternalViewController *)node).nativeScreenContext
                                    applyUpdate:update];

package/ios/cpp/react/renderer/components/ApexNavigationSpec/ANNSlotState.cpp

@@ -0,0 +1,20 @@
+#include "ANNSlotState.h"
+
+namespace facebook::react {
+
+std::mutex &ANNSlotContentHeights::mutex() {
+    static std::mutex value;
+    return value;
+}
+
+std::unordered_map<std::string, Float> &ANNSlotContentHeights::heights() {
+    static std::unordered_map<std::string, Float> value;
+    return value;
+}
+
+std::atomic<int> &ANNSlotContentHeights::requested() {
+    static std::atomic<int> value{0};
+    return value;
+}
+
+} // namespace facebook::react

package/ios/cpp/react/renderer/components/ApexNavigationSpec/ANNSlotState.h

@@ -82,20 +82,11 @@ class ANNSlotContentHeights final {
     }
 
   private:
-    static std::mutex &mutex() {
-        static std::mutex value;
-        return value;
-    }
-
-    static std::unordered_map<std::string, Float> &heights() {
-        static std::unordered_map<std::string, Float> value;
-        return value;
-    }
-
-    static std::atomic<int> &requested() {
-        static std::atomic<int> value{0};
-        return value;
-    }
+    // One store for the whole app, in ANNSlotState.cpp: on Android the slot's layout runs in the app's library and the
+    // native side reads the heights from the library's own, and an inline static would give each its own copy.
+    static std::mutex &mutex();
+    static std::unordered_map<std::string, Float> &heights();
+    static std::atomic<int> &requested();
 };
 
 } // namespace facebook::react

package/lib/module/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/lib/module/adapters/NativeANNTurboModule.js.map

@@ -1 +1 @@
-{"version":3,"names":["TurboModuleRegistry","get"],"sourceRoot":"../../../src","sources":["adapters/NativeANNTurboModule.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA6C,cAAc;;AAEvF;AACA;AACA;AACA;AACA;;AA4FA;AACA,eAAeA,mBAAmB,CAACC,GAAG,CAAO,gBAAgB,CAAC","ignoreList":[]}
+{"version":3,"names":["TurboModuleRegistry","get"],"sourceRoot":"../../../src","sources":["adapters/NativeANNTurboModule.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAA6C,cAAc;;AAEvF;AACA;AACA;AACA;AACA;;AAsGA;AACA,eAAeA,mBAAmB,CAACC,GAAG,CAAO,gBAAgB,CAAC","ignoreList":[]}

package/lib/module/api/app/AppRegistry.js

@@ -2,9 +2,10 @@
 
 import { AppRegistry as ReactNativeAppRegistry } from 'react-native';
 import { onNativeEvent } from "../../engine/native.js";
+import { familyOf } from "../../engine/refresh.js";
 import { SLOT_HOST_MODULE } from "../../engine/slots.js";
 import { SlotHost } from "../slots/SlotHost.js";
-import { isNavigationApp, startApp } from "./createNavigation.js";
+import { isNavigationApp, noteReplacingApp, startApp } from "./createNavigation.js";
 let appKey;
 let registered;
 let app;
@@ -28,7 +29,18 @@ function onAppLaunched() {
  */
 function registerComponent(key, navigation) {
   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/lib/module/api/app/AppRegistry.js.map

@@ -1 +1 @@
-{"version":3,"names":["AppRegistry","ReactNativeAppRegistry","onNativeEvent","SLOT_HOST_MODULE","SlotHost","isNavigationApp","startApp","appKey","registered","app","listening","onAppLaunched","created","Error","catch","error","console","registerComponent","key","navigation","__DEV__","warn"],"sourceRoot":"../../../../src","sources":["api/app/AppRegistry.ts"],"mappings":";;AAAA,SAASA,WAAW,IAAIC,sBAAsB,QAAQ,cAAc;AACpE,SAASC,aAAa,QAAQ,wBAAqB;AACnD,SAASC,gBAAgB,QAAQ,uBAAoB;AACrD,SAASC,QAAQ,QAAQ,sBAAmB;AAC5C,SAASC,eAAe,EAAsBC,QAAQ,QAAQ,uBAAoB;AAIlF,IAAIC,MAA0B;AAC9B,IAAIC,UAAuE;AAC3E,IAAIC,GAA8B;AAClC,IAAIC,SAAS,GAAG,KAAK;AAErB,SAASC,aAAaA,CAAA,EAAG;EACvB,IAAI,CAACH,UAAU,EAAE;EACjB,IAAI,CAACC,GAAG,EAAE;IACR;IACA,MAAMG,OAAO,GAAG,OAAOJ,UAAU,KAAK,UAAU,GAAGA,UAAU,CAAC,CAAC,GAAGA,UAAU;IAC5E,IAAI,CAACH,eAAe,CAACO,OAAO,CAAC,EAAE;MAC7B,MAAM,IAAIC,KAAK,CACb,+CAA+CN,MAAM,qFACvD,CAAC;IACH;IACAE,GAAG,GAAGG,OAAO;EACf;EACAN,QAAQ,CAACG,GAAG,CAAC,CAACK,KAAK,CAAEC,KAAK,IAAKC,OAAO,CAACD,KAAK,CAAC,sCAAsC,EAAEA,KAAK,CAAC,CAAC;AAC9F;;AAEA;AACA;AACA;AACA;AACA,SAASE,iBAAiBA,CACxBC,GAAW,EACXC,UAA2D,EACnD;EACR,IAAIC,OAAO,IAAIZ,UAAU,EAAE;IACzBQ,OAAO,CAACK,IAAI,CAAC,iBAAiBH,GAAG,qCAAqCX,MAAM,GAAG,CAAC;EAClF;EACAA,MAAM,GAAGW,GAAG;EACZV,UAAU,GAAGW,UAAU;EACvB,IAAI,CAACT,SAAS,EAAE;IACdA,SAAS,GAAG,IAAI;IAChB;IACA;IACAT,sBAAsB,CAACgB,iBAAiB,CAACd,gBAAgB,EAAE,MAAMC,QAAQ,CAAC;IAC1E;IACA;IACAF,aAAa,CAAC,aAAa,EAAES,aAAa,CAAC;EAC7C;EACA,OAAOO,GAAG;AACZ;;AAEA;AACA,OAAO,MAAMlB,WAEZ,GAAG;EAAE,GAAGC,sBAAsB;EAAEgB;AAAkB,CAAC","ignoreList":[]}
+{"version":3,"names":["AppRegistry","ReactNativeAppRegistry","onNativeEvent","familyOf","SLOT_HOST_MODULE","SlotHost","isNavigationApp","noteReplacingApp","startApp","appKey","registered","app","listening","onAppLaunched","created","Error","catch","error","console","registerComponent","key","navigation","__DEV__","before","Promise","resolve","then","family","warn"],"sourceRoot":"../../../../src","sources":["api/app/AppRegistry.ts"],"mappings":";;AAAA,SAASA,WAAW,IAAIC,sBAAsB,QAAQ,cAAc;AACpE,SAASC,aAAa,QAAQ,wBAAqB;AACnD,SAASC,QAAQ,QAAQ,yBAAsB;AAC/C,SAASC,gBAAgB,QAAQ,uBAAoB;AACrD,SAASC,QAAQ,QAAQ,sBAAmB;AAC5C,SACEC,eAAe,EAEfC,gBAAgB,EAChBC,QAAQ,QACH,uBAAoB;AAI3B,IAAIC,MAA0B;AAC9B,IAAIC,UAAuE;AAC3E,IAAIC,GAA8B;AAClC,IAAIC,SAAS,GAAG,KAAK;AAErB,SAASC,aAAaA,CAAA,EAAG;EACvB,IAAI,CAACH,UAAU,EAAE;EACjB,IAAI,CAACC,GAAG,EAAE;IACR;IACA,MAAMG,OAAO,GAAG,OAAOJ,UAAU,KAAK,UAAU,GAAGA,UAAU,CAAC,CAAC,GAAGA,UAAU;IAC5E,IAAI,CAACJ,eAAe,CAACQ,OAAO,CAAC,EAAE;MAC7B,MAAM,IAAIC,KAAK,CACb,+CAA+CN,MAAM,qFACvD,CAAC;IACH;IACAE,GAAG,GAAGG,OAAO;EACf;EACAN,QAAQ,CAACG,GAAG,CAAC,CAACK,KAAK,CAAEC,KAAK,IAAKC,OAAO,CAACD,KAAK,CAAC,sCAAsC,EAAEA,KAAK,CAAC,CAAC;AAC9F;;AAEA;AACA;AACA;AACA;AACA,SAASE,iBAAiBA,CACxBC,GAAW,EACXC,UAA2D,EACnD;EACR,IAAIC,OAAO,IAAIZ,UAAU,EAAE;IACzB;IACA;IACA,IAAIU,GAAG,KAAKX,MAAM,EAAEF,gBAAgB,CAACc,UAAU,CAAC;IAChD,MAAME,MAAM,GAAG;MAAEH,GAAG,EAAEX,MAAM;MAAEE,GAAG,EAAED;IAAW,CAAC;IAC/Cc,OAAO,CAACC,OAAO,CAAC,CAAC,CAACC,IAAI,CAAC,MAAM;MAC3B,MAAMC,MAAM,GAAGxB,QAAQ,CAACoB,MAAM,CAACZ,GAAG,CAAC;MACnC,IAAIS,GAAG,KAAKG,MAAM,CAACH,GAAG,IAAKO,MAAM,IAAIA,MAAM,KAAKxB,QAAQ,CAACkB,UAAU,CAAE,EAAE;MACvEH,OAAO,CAACU,IAAI,CAAC,iBAAiBR,GAAG,qCAAqCG,MAAM,CAACH,GAAG,GAAG,CAAC;IACtF,CAAC,CAAC;EACJ;EACAX,MAAM,GAAGW,GAAG;EACZV,UAAU,GAAGW,UAAU;EACvB,IAAI,CAACT,SAAS,EAAE;IACdA,SAAS,GAAG,IAAI;IAChB;IACA;IACAX,sBAAsB,CAACkB,iBAAiB,CAACf,gBAAgB,EAAE,MAAMC,QAAQ,CAAC;IAC1E;IACA;IACAH,aAAa,CAAC,aAAa,EAAEW,aAAa,CAAC;EAC7C;EACA,OAAOO,GAAG;AACZ;;AAEA;AACA,OAAO,MAAMpB,WAEZ,GAAG;EAAE,GAAGC,sBAAsB;EAAEkB;AAAkB,CAAC","ignoreList":[]}