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

package/docs-md/start/installation.md

@@ -126,11 +126,13 @@ In an app as the React Native template makes it, the window shows **one React vi
 
 | File | What setup does | Why |
 | --- | --- | --- |
-| `MainApplication.kt` | Extends `NavigationApplication`. | It loads React Native itself and keeps one React host for all screens. Native screens made by `codegen` are registered there, before JS opens them. |
+| `MainApplication.kt` | Extends `NavigationApplication`; keeps the template's `loadReactNative(this)` in `onCreate`, or adds it. | It keeps one React host for all screens, made after `loadReactNative(this)` loaded React Native. Native screens made by `codegen` are registered there, before JS opens them. |
 | `MainActivity.kt` | Extends `NavigationActivity`. | The activity holds the containers of the navigation instead of one React view. It gets the back press, edge-to-edge and configuration changes first. |
 | `AndroidManifest.xml` | Adds `android:enableOnBackInvokedCallback="true"` to `<application>`. | On the first screen the system plays its own animation back to the home screen as the user swipes back (predictive back). Android 16 turns it on for apps that target API 36; an app that targets less opts in here. A value the app set itself stays. See [Back to the home screen](../screen-ui/back-and-gestures#system-animation). |
 | `styles.xml` | `AppTheme` inherits `Theme.ApexNavigation`. | The bars, tabs and search are Material 3 views and take their colors from the app's theme. This one is Material 3 in neutral grays, light and dark; change any color in the same file. A theme of the app's own stays as it is. See [Android's colors](../architecture/theme-and-context#android). |
 
+The main activity keeps the template's `android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"`. Without `orientation`, `screenSize`, `smallestScreenSize`, `screenLayout` or `uiMode` Android recreates the activity on a rotation, a resize, a fold or a light/dark switch, and every screen goes with it; `doctor` warns about it under Config changes.
+
 #### iOS files
 
 | File | What setup does | Why |
@@ -213,7 +215,7 @@ export {};
 
 | Group | What it checks |
 | --- | --- |
-| App | React Native and the New Architecture, the package, the files `setup` sets up, the entry point, React Native loaded twice, the status bar of the template, the generated code of native screens. Typed commands: `navigation-env.d.ts` there, pointing to the navigation, with its `context` line, and read by `tsconfig.json`. The splash screen made from its settings, with its logo inside the circle of Android's splash icon, and an iOS launch screen made with `UILaunchScreen` and no storyboard, which the navigation can't keep on screen. The app icon made from its settings, and an iOS icon set with no image, which the App Store refuses. |
+| App | React Native and the New Architecture, the package, the files `setup` sets up, the entry point, React Native loaded twice, the status bar of the template, the generated code of native screens. Typed commands: `navigation-env.d.ts` there, pointing to the navigation, with its `context` line, and read by `tsconfig.json`. The splash screen made from its settings, with its logo inside the circle of Android's splash icon. The app icon made from its settings, and an iOS icon set with no image, which the App Store refuses. |
 | Navigation | From the app's code. Screens: no name given twice in `screens` and the groups, and no file of the screens' folder with a `defineScreen` or `nativeScreen` that no file imports, a screen made and never added. Links: each prefix of `linking` declared on both platforms, the declarations no prefix has, a main activity that isn't `singleTask`. Screen names, in a JavaScript app only: a name that `push`, `replace`, `showModal` or `showInColumn` gives and no screen has, with its file and line. |
 | (Android) | JDK 17 in use, the Android SDK, `minSdk`, how edge-to-edge works in the app. |
 | (iOS) | Xcode 26 or newer, CocoaPods, the pods of the navigation and whether they are out of date, the iOS version of the Podfile. |

package/ios/CLAUDE.md

@@ -27,7 +27,7 @@ Swift is not used here: apps reach the core through the public headers (`Public/
 - `Layouts/SplitView/`: The split view module, plus the core's `ANNSplitViewPresenter` and `ANNSplitViewCommands`.
 - `Layouts/Arrangement/`: The pair (iOS 27.1): `ANNArrangementViewController`, `ANNArrangementState`.
 - `TopBar/`: The bar of a screen: title, buttons, back button, large title, appearance, search, toolbar, edge effects.
-- `Options/`, `Options/Params`: One `ANN<Group>Options` class per group, the field table, the value kinds and parsers (`Bool`, `Color`, `Text`, `Image`, …).
+- `Options/`, `Options/Params`: One `ANN<Group>Options` class per group, the field table, the value kinds and parsers (`Bool`, `Color`, `Text`, `Image`, …), the images' cache and loader (`ANNOptionImages`).
 - `Animations/`: The custom transition engine: plan, animator, wait, frame driver, rules; `Elements/` and `Interpolators/`.
 - `React/`, `React/Slots/`: React views of screens and components, the surface host, the safe area view, the slot host and slot screens.
 - `Public/ApexNavigation/`: The headers apps import: `ApexNavigation.h`, `ANNAppDelegate.h`, `ANNSceneDelegate.h`.
@@ -42,7 +42,7 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - Launch, the app-facing API — `Public/ApexNavigation/`; `Core/`: `ApexNavigation.mm`, `ANNAppDelegate.mm`, `ANNSceneDelegate.mm`, `ApexNavigation+Internal.h`
 - Root, splash, reload — `Layouts/Root/`: `ANNRootCoordinator`, `ANNSplashViewController`; `Core/`: `ANNReloadCoordinator`
 - Screen: React root, slot, native screen — `Layouts/Screen/`: `ANNComponentViewController`; `React/`: `ANNReactView`, `ANNReactViewCreator`, `Slots/`; `Layouts/External/`
-- Screen: insets, background, keyboard focus — `Layouts/Screen/`: `ANNScreenInsets`, `ANNScreenSafeArea`, `ANNScreenBars`, `ANNComponentPresenter` (background, status bar blur), `ANNComponentViewController` (key commands)
+- Screen: insets, background, keyboard focus — `Layouts/Screen/`: `ANNScreenInsets`, `ANNScreenSafeArea`, `ANNScreenBars`, `ANNScreenPlace` (the safe area of a parked screen), `ANNComponentPresenter` (background, status bar blur), `ANNComponentViewController` (key commands)
 - Safe area view — `React/`: `ANNSafeAreaViewComponentView`; `Layouts/Screen/`: `ANNScreenReadiness`; `cpp/`
 - Stack: queue, commands, back, gestures — `Layouts/Stack/`: `ANNStackQueue`, `ANNStackCommands`, `ANNStackController`, `InteractivePopGestureDelegate`, `ANNStackAnimatingDelegate`
 - Top bar: title, buttons, menus, large title — `TopBar/`: `ANNTopBarPresenter`, `ANNBarButtons`, `ANNBarAppearance`, `ANNLargeTitlePresenter`, `ANNBackButtonPresenter`, `ANNTitleView`, `ANNTitleGlassView`
@@ -60,24 +60,31 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - System bars, orientation, direction — `Core/`: `ANNSystemUI`, `ANNSystemUIRules`, `ANNAppDirection`, `ANNNodePresenter` (the answers to UIKit)
 - Events and state — `Core/`: `ANNEventEmitter`, `ANNEventContract` (names and keys, made by `scripts/contract.mjs`), `ANNAppearanceDispatcher`, `ANNScreenAppearance`, `ANNNavigationState`; `TurboModules/`: `ANNTurboEventEmitter`
 - Options: parsing, merging, defaults — `Options/`: `ANNOptions`, `ANNOptionField`, `ANNOptionsReader`, `ANNDefaultOptions`, `ANNOptionsCache`; `Core/`: `ANNOptionsRepaint`
-- Error texts — `Contract/`: `ANNErrorTexts` (made from `src/interfaces/contract/errors.json` by `scripts/contract.mjs`); `Core/`: `ANNErrorHandler`
+- Error texts and answers — `Contract/`: `ANNErrorTexts` and `ANNCommandContract` (made from `src/interfaces/contract/errors.json` and `commands.json` by `scripts/contract.mjs`); `Core/`: `ANNErrorHandler`
 - Links — `Core/`: `ANNDeepLinkQueue`; the `getLaunchLink` method of `ANNTurboModule`
 - Key commands — `Core/`: `ANNKeyCommands`; `Layouts/Screen/`: `ANNComponentViewController`
 - Hinge, regions — `Core/`: `ANNHinge`; `Layouts/Screen/`: `ANNScreenRegions`; `Layouts/Arrangement/`: `ANNArrangementState`
 - Native screens — `Layouts/External/`: `ANNExternalViewController`, `ANNNativeScreenCalls`; `Layouts/Screen/ANNNativeScreenContext.mm`
-- Slots — `React/Slots/`: `ANNSlotHost`, `ANNSlotContainers`, `ANNSlotScreenView`, `ANNSlotComponentView`; `cpp/`
+- Slots — `React/Slots/`: `ANNSlotHost`, `ANNSlotContainers` (containers and slot views by slot id: a change goes
+  straight to the views of its id), `ANNSlotScreenView`, `ANNSlotComponentView`; `cpp/`
 
 ## Threads
 
 - **Module queue:** the layout check (`ANNLayoutReader`) and the sync getters. The check reads only stores safe from
   any thread (`ApexNavigation hasNativeScreenNamed:`, `ANNArrangementState canShowArrangements`).
 - **Main queue:** everything else. A command body starts with `ANNAssertMainQueue()`. The options of a layout are parsed
-  here (`ANNLayoutTreeOptions`, images load while they are read). `ANNEventEmitter` moves an event from another queue
+  here (`ANNLayoutTreeOptions`; an image keeps only its source). `ANNEventEmitter` moves an event from another queue
   to the main queue.
+- **The images' queue** (`ANNOptionImages`, `Options/Params`): every option image decodes there, through one cache.
+  An element that shows an image asks for it when it applies and waits for it (the first frame needs it); only a tab
+  item's new icon on the bar that shows comes later (`ANNBottomTabsPresenter`), the last build of the item winning.
 - **Sync getters** answer JS during a screen's first render: `getScreenInsets`, `getScreenRegions`,
   `getArrangementState`, `getHinge`, `getStartInfo`. They read `ANNScreenInsets`, `ANNScreenRegions`,
   `ANNArrangementState`, `ANNHinge lastValue`, written on the main queue and guarded by `@synchronized`.
   `ANNReloadCoordinator.generation` and `ANNEventEmitter.isCurrent` are readable from any thread.
+- **After the calls of JavaScript:** `ANNJavaScriptCalls afterCallsMadeSoFar:` runs a step on the main queue after
+  every call JavaScript made by then, by the calls' own way (the JavaScript thread, the module's queue, the main
+  queue). A push's wait ends through it, so the `mergeOptions` of its screen's first commit come first.
 
 ## Checks
 
@@ -92,6 +99,11 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 
 - Native code never touches React Native's views (their subviews, their layout, their frames): Fabric owns and recycles
   them. Read them; what a transition writes (`alpha`, `transform`, a hidden flag) goes back on every path.
+- A screen parked by a wait for its content (`ANNParking`) has no parent, and UIKit gives its view no safe area: it lays
+  out with the safe area of its place (`ANNScreenPlace`, measured on a navigation controller of the core's), or its
+  list would move as the push starts and UIKit would show the large title only after the transition. On iOS 26 its
+  large title also keeps a place of the core's for the push (`arrivesByPushOn:`). Check Showcase 1.4 (with a font
+  size), every section panel and 12.6 on push, pop and swipe after any change to waits, parking or the large title.
 - Every change of a stack's children goes through its `ANNStackQueue`. The core's own calls to UIKit's navigation
   come only from there; UIKit's own pops are followed (`uikitShows:`), not fought.
 - Every UIKit present and dismiss in the main window is a step in `ANNPresentationGate`. UIKit drops a transition

package/ios/CORE.md

@@ -68,25 +68,29 @@ dispatcher.
    `+[ANNErrorTexts nowhereToShow]` when there is no window, then runs the body in `@try`. The body finds Home in
    `ANNNodeRegistry` and calls `+[ANNStackCommands push:componentId:what:answer:]`.
 4. **`ANNStackCommands`.** Finds the stack by walking `layoutParent`; checks `ANNLayoutValidator` (an id already shown,
-   what a stack takes); reads the options of the whole tree with `ANNLayoutTreeOptions` (images load here); checks
-   `ANNLayoutFactory canMakeTrees:`; a node with `preview.nativeID` goes to `ANNPreviewPush`; a `key` of an entry below
-   goes back to that entry; else `+[ANNLayoutFactory nodeFromLayout:options:]` makes Profile (an
+   what a stack takes); reads the options of the whole tree with `ANNLayoutTreeOptions` (an image keeps its source,
+   loaded through `ANNOptionImages` when an element shows it); checks `ANNLayoutFactory canMakeTrees:`; a node with
+   `preview.nativeID` goes to `ANNPreviewPush`; a `key` of an entry below goes back to that entry; else
+   `+[ANNLayoutFactory nodeFromLayout:options:]` makes Profile (an
    `ANNComponentViewController` with an `ANNComponentPresenter`, content from `ANNReactViewCreator`) and registers it.
    No view is rendered yet.
 5. **`-[ANNStackQueue push:answer:…]`.** The node joins `entries` now (every check reads `entries`), the operation is
    queued, `runNext` starts it when the queue is at rest.
 6. **`startPush:` and `startPushTransition:`.** By `animations.push.waitForRender` the queue waits through
-   `ANNRenderWait`, for the content and the bar components or for the bar components alone (a screen that waits for its
-   content is parked unseen in the stack's view by `ANNParking`, `stackPark:`), then renders the node, drives the appearance of Home and Profile (`+[ANNAppearanceDispatcher driveAppearanceOf:]`), and calls
+   `ANNRenderWait`: unset, for the content at most 0.5 s, with `true` as long as it takes, then for the bar components
+   (their limits from the wait's start when unset, from the content's end with `true`; the screen is parked unseen in
+   the stack's view by `ANNParking`, `stackPark:`); the content's end, content there already too, waits for the calls
+   JavaScript made by then (`ANNJavaScriptCalls`: the JavaScript thread, the module's queue, the main queue), so the
+   options of the screen's first commit are in the bar; with `false` nothing. Then it renders the node, drives the appearance of Home and Profile (`+[ANNAppearanceDispatcher driveAppearanceOf:]`), and calls
    `+[ANNAppearanceDispatcher beginTransitionShowing:]`. Profile's `ComponentWillAppear` is sent now (held until its
    content mounted, 0.5 s at most). `stackChange:` pushes in UIKit; with an own animation `ANNTransitionPlan` and
    `ANNStackAnimatingDelegate` give UIKit the `ANNTransitionAnimator`.
 7. **The end.** `stackWhenTransitionEnds:` fires from the transition coordinator and calls `endPush:`, which calls
    `+[ANNAppearanceDispatcher endTransitionHiding:showing:events:answer:value:]`. In this order: `ComponentDidDisappear`
-   of Home, `ComponentDidAppear` of Profile, `ANN.NavigationStateChanged` (`+[ANNNavigationState updateNow]`), the
-   transition's `events`, then `-[ANNCommandAnswer resolve:]`: the state again if it changed
-   (`reportBeforeAnswer`), the promise with Profile's id, then `ANN.CommandCompleted`. `finish:` frees the queue for
-   the next operation.
+   of Home, `ComponentDidAppear` of Profile, `ANN.NavigationStateChanged` (`-[ANNCommandAnswer reportStateNow]`, the
+   answer's one state step), the transition's `events`, then `-[ANNCommandAnswer resolve:]`: the promise with
+   Profile's id, then `ANN.CommandCompleted`. A command answered without a transition's end (`setRoot` with layout
+   modals) sends its state from `resolve:`. `finish:` frees the queue for the next operation.
 
 Events go out through `ANNEventEmitter` on the main queue and reach JS through `ANNTurboEventEmitter`.
 
@@ -113,16 +117,17 @@ Each of these owns one rule. Call it; do not copy it.
 
 - `ANNCommandRunner`: The one path of every async command: generation, check, main queue, exception guard. Called by: `ANNTurboModule`.
 - `ANNLayoutReader`: The layout check, depth first, the same order and texts as Android. Module queue. Called by: The runner's check blocks.
-- `ANNCommandAnswer`: The answer: state, then promise, then `ANN.CommandCompleted`; once; silent for a JavaScript that went. Called by: Every coordinator and queue.
+- `ANNCommandAnswer`: The answer: state (one step per answer, `reportStateNow`, asked by the end of its transition or by `resolve:`), then promise, then `ANN.CommandCompleted`; once; silent for a JavaScript that went. Called by: Every coordinator and queue.
 - `ANNNodeRegistry`: Every node by id, weakly. Filled by the factory, cleared at a reload. Called by: Commands, modules, `findViewController:`.
 - `ANNLayoutFactory`: The core code that names module classes (`ANNSplitViewController`, `ANNSideMenuViewController`, `ANNArrangementViewController`); `ANNSideMenuPresenter` is the one other file that does. One maker per layout type; registers each node. Called by: Every command that shows a layout.
-- `ANNOptionsCache`: The one invalidation point of resolved options. Called by: The setter of `ANNNodeHelper.options` and `ANNDefaultOptions` only.
-- `ANNNodeHelper resolveOptionsWithDefault`: What a node shows with: defaults, parents' own options, the node's `resolveOptions` (own, then the current child down). Cached, read-only. Called by: Presenters, coordinators.
+- `ANNOptionsCache`: The one invalidation point of resolved options. Called by: The setters of `ANNNodeHelper.options` and of its user layer (`setUserChoice:forKey:`), and `ANNDefaultOptions`, only.
+- `ANNNodeHelper resolveOptionsWithDefault`: What a node shows with: defaults, parents' own options (each with its user layer), the node's `resolveOptions` (own, its user layer, then the current child down). Cached, read-only. Called by: Presenters, coordinators.
 - `ANNAppearanceDispatcher`: The only sender of `ComponentWillAppear`, `ComponentDidAppear`, `ComponentDidDisappear`; the end-of-transition order; the events of a node that goes. Called by: Screens, queues, coordinators.
-- `ANNNavigationState`: The visible screen and the nearest tabs it is in (the last tabs met walking down); coalesced updates, holds, the state before an answer. Called by: The dispatcher, `ANNCommandAnswer`, `ANNRootCoordinator`.
+- `ANNNavigationState`: The visible screen and the nearest tabs it is in (the last tabs met walking down); coalesced updates, holds, the state now. Called by: The dispatcher, `ANNCommandAnswer`, `ANNRootCoordinator`, `ANNModalCoordinator`, `ANNBottomTabsController`.
 - `ANNScreenReadiness`: The signals of a screen's safe area view (has one, laid out, content rendered), sticky, by screen id. Called by: `ANNSafeAreaViewComponentView`, `ANNReactView`.
 - `ANNRenderWait`: The one wait for the render of what a command shows: content, bar components, limits, the unknown-content rule. Called by: Root, stack queue, modals, overlays, `showInColumn`.
 - `ANNParking`: Where a view waits for its content unseen: the window, a stack's view, a preview's host view. Called by: Root, stack, modals, overlays, `ANNPreviewPush`.
+- `ANNScreenPlace`: The safe area a parked screen lays out with, measured where it will show on top of a stack. Called by: `ANNStackController` (`stackPark:`), `ANNSplitViewCommands` (`showInColumn`), through `placeWhileParked` of the screen.
 - `ANNPendingLayers`: Layers that wait to show (a pending root, a modal, an overlay); a node inside counts as off screen. Called by: The layer's owner; nodes ask.
 - `ANNShownScreens`: "What a node shows changed": tells the pending layer, the modal hold and the system UI, in that order. Called by: Every container that changes what it shows.
 - `ANNModalCoordinator`, `ANNModal`: One record per modal, its states and waiting commands. Called by: Commands, root, state, repaint, reload.

package/ios/Contract/ANNCommandAnswer.h

@@ -27,8 +27,15 @@ NS_ASSUME_NONNULL_BEGIN
 /// Whether the JavaScript the command came from still runs: its work goes on only then.
 @property(nonatomic, readonly) BOOL isCurrent;
 
-/// Resolves the promise: first the state goes, then the promise, then `ANN.CommandCompleted` for a command that shows
-/// or dismisses.
+/// The navigation state now, sent when it changed, once per answer: the end of the command's transition asks for it
+/// after the `DidAppear` it sends and before the transition's own events (`ANNAppearanceDispatcher`); otherwise
+/// `resolve:` asks for it before the promise. A later call sends nothing, and nothing goes for a JavaScript that went.
+/// A failure of the step is logged and costs only the state.
+- (void)reportStateNow;
+
+/// Resolves the promise: first the state, when the command changes what shows (`ANNCommandContract`) and its
+/// transition didn't send it already (`reportStateNow`), then the promise, then `ANN.CommandCompleted` for a command
+/// that shows or dismisses.
 - (void)resolve:(nullable id)value;
 
 /// Rejects the promise with the text alone: no code of the navigation.

package/ios/Contract/ANNCommandAnswer.mm

@@ -1,29 +1,16 @@
 #import "ANNCommandAnswer.h"
 #import "ANNAssert.h"
+#import "ANNCommandContract.h"
 #import "ANNErrorHandler.h"
 #import "ANNErrorTexts.h"
 #import "ANNNavigationState.h"
 #import "ANNReloadCoordinator.h"
 #import "ApexNavigation+Internal.h"
 
-// The commands that send `ANN.CommandCompleted` once they resolved: every one that shows or dismisses, not
-// `setColumnShown`, `preparePush` or `getLaunchLink`.
-static NSSet<NSString *> *ANNCompletedCommandNames(void) {
-    static NSSet<NSString *> *names;
-    static dispatch_once_t once;
-    dispatch_once(&once, ^{
-      names = [NSSet setWithArray:@[
-          @"setRoot", @"push", @"pop", @"popTo", @"popToRoot", @"setStackRoot", @"showInColumn",
-          @"showModal", @"dismissModal", @"dismissAllModals", @"showOverlay", @"dismissOverlay",
-          @"dismissAllOverlays"
-      ]];
-    });
-    return names;
-}
-
 @implementation ANNCommandAnswer {
     RCTPromiseResolveBlock _resolve;
     RCTPromiseRejectBlock _reject;
+    BOOL _stateReported;
 }
 
 - (instancetype)initWithCommandName:(NSString *)commandName
@@ -65,6 +52,27 @@ static NSSet<NSString *> *ANNCompletedCommandNames(void) {
     return YES;
 }
 
+- (void)reportStateNow {
+    ANNAssertMainQueue();
+    if (_stateReported) {
+        return;
+    }
+    _stateReported = YES;
+    // A step made for the JavaScript that went sends nothing, as its answer does.
+    if (!self.isCurrent) {
+        return;
+    }
+    // The command did its work: a failure of the state step costs only the state, never the events and the answer.
+    @try {
+        [ANNNavigationState updateNowFor:_commandName];
+    } @catch (NSException *exception) {
+        NSString *reason = exception.reason.length > 0 ? exception.reason : exception.name;
+        [ANNErrorHandler logFailureOf:_commandName
+                                 text:[ANNErrorTexts couldNot:@"report the navigation state"
+                                                        reason:reason]];
+    }
+}
+
 - (void)resolve:(id)value {
     if (![self takeAnswer]) {
         return;
@@ -72,23 +80,13 @@ static NSSet<NSString *> *ANNCompletedCommandNames(void) {
     RCTPromiseResolveBlock resolve = _resolve;
     _resolve = nil;
     _reject = nil;
-    // A command that may change what shows (the 13 and `setColumnShown`): the state goes before the promise, so that
-    // `getState()` after `await` has the result.
-    BOOL changesWhatShows = [ANNCompletedCommandNames() containsObject:_commandName] ||
-                            [_commandName isEqualToString:@"setColumnShown"];
-    if (changesWhatShows) {
-        // The command did its work: a failure of the state step costs only the state, never the answer.
-        @try {
-            [ANNNavigationState reportBeforeAnswer];
-        } @catch (NSException *exception) {
-            NSString *reason = exception.reason.length > 0 ? exception.reason : exception.name;
-            [ANNErrorHandler logFailureOf:_commandName
-                                     text:[ANNErrorTexts couldNot:@"report the navigation state"
-                                                            reason:reason]];
-        }
+    // A command that may change what shows (`ANNCommandContract`): the state goes before the promise, so that
+    // `getState()` after `await` has the result. Sent at the end of its transition already, it goes no more.
+    if (ANNCommandReportsState(_commandName)) {
+        [self reportStateNow];
     }
     [ANNErrorHandler resolve:resolve of:_commandName value:value];
-    if (_commandId && [ANNCompletedCommandNames() containsObject:_commandName]) {
+    if (_commandId && ANNCommandSendsCompleted(_commandName)) {
         double completionTime = floor(NSDate.date.timeIntervalSince1970 * 1000);
         [ApexNavigation.eventEmitter sendCommandCompleted:_commandName
                                                 commandId:_commandId

package/ios/Contract/ANNCommandContract.h

@@ -0,0 +1,15 @@
+// Made by scripts/contract.mjs from src/interfaces/contract/commands.json: change that file and run the script again.
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Whether the navigation state goes before the answer of the command `name`: every command that may change what
+/// shows. Any thread.
+FOUNDATION_EXPORT BOOL ANNCommandReportsState(NSString *name);
+
+/// Whether `ANN.CommandCompleted` follows the answer of the command `name`: every command that shows or dismisses.
+/// Any thread.
+FOUNDATION_EXPORT BOOL ANNCommandSendsCompleted(NSString *name);
+
+NS_ASSUME_NONNULL_END

package/ios/Contract/ANNCommandContract.mm

@@ -0,0 +1,78 @@
+// Made by scripts/contract.mjs from src/interfaces/contract/commands.json: change that file and run the script again.
+
+#import "ANNCommandContract.h"
+
+// What each command resolves with:
+// - `setRoot`: the id of the root, once the root and the layout's modals and overlays show.
+// - `push`: the id of the screen that shows; of a pair, the pair's id.
+// - `preparePush`: the frame `{ width, height, padding }` of the prepared screen, or null; always
+//   null on iOS.
+// - `pop`: the id of the screen that went.
+// - `popTo`: the id of the screen it went back to.
+// - `popToRoot`: the id of the first screen of the stack.
+// - `setStackRoot`: the id of the new top screen.
+// - `showModal`: the id of the modal's root.
+// - `dismissModal`: the id of the modal's root.
+// - `dismissAllModals`: an empty string.
+// - `showOverlay`: the id of the overlay's root.
+// - `dismissOverlay`: the id of the overlay's root.
+// - `dismissAllOverlays`: an empty string.
+// - `showInColumn`: the id of the screen that shows.
+// - `setColumnShown`: nothing once the columns stopped moving (`undefined` on iOS, `null` on
+//   Android).
+// - `getLaunchLink`: the link that launched the app, or null.
+
+static NSSet<NSString *> *ANNStateCommandNames(void) {
+    static NSSet<NSString *> *names;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      names = [NSSet setWithArray:@[
+          @"setRoot",
+          @"push",
+          @"pop",
+          @"popTo",
+          @"popToRoot",
+          @"setStackRoot",
+          @"showModal",
+          @"dismissModal",
+          @"dismissAllModals",
+          @"showOverlay",
+          @"dismissOverlay",
+          @"dismissAllOverlays",
+          @"showInColumn",
+          @"setColumnShown",
+      ]];
+    });
+    return names;
+}
+
+static NSSet<NSString *> *ANNCompletedCommandNames(void) {
+    static NSSet<NSString *> *names;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      names = [NSSet setWithArray:@[
+          @"setRoot",
+          @"push",
+          @"pop",
+          @"popTo",
+          @"popToRoot",
+          @"setStackRoot",
+          @"showModal",
+          @"dismissModal",
+          @"dismissAllModals",
+          @"showOverlay",
+          @"dismissOverlay",
+          @"dismissAllOverlays",
+          @"showInColumn",
+      ]];
+    });
+    return names;
+}
+
+BOOL ANNCommandReportsState(NSString *name) {
+    return [ANNStateCommandNames() containsObject:name];
+}
+
+BOOL ANNCommandSendsCompleted(NSString *name) {
+    return [ANNCompletedCommandNames() containsObject:name];
+}

package/ios/Core/ANNAppearanceDispatcher.h

@@ -58,11 +58,12 @@ NS_ASSUME_NONNULL_BEGIN
 
 /// A transition ended, in this order: first a screen a transition began inside a node of `shown` that left the window
 /// and isn't one of that node's shown screens gets its `DidDisappear`; then `DidDisappear` of every screen of `hidden`,
-/// `DidAppear` of what `shown` shows, the navigation state now when it changed, `events` (the transition's own events,
+/// `DidAppear` of what `shown` shows, the navigation state now when it changed (the answer's one state step,
+/// `-[ANNCommandAnswer reportStateNow]`; nothing for a JavaScript that went), `events` (the transition's own events,
 /// `ANN.ScreenPopped` and `ANN.ModalDismissed`, and what must follow them, like stopping the content that went), then
-/// `answer` resolves with `value` (its own state step finds nothing new, then the promise, then
-/// `ANN.CommandCompleted`). A user's action passes no answer. The callbacks of UIKit that come later find the phases
-/// set and send nothing.
+/// `answer` resolves with `value` (the promise, then `ANN.CommandCompleted`; no second state). A user's action passes
+/// no answer, and its state goes all the same. The callbacks of UIKit that come later find the phases set and send
+/// nothing.
 + (void)endTransitionHiding:(NSArray<UIViewController *> *)hidden
                     showing:(NSArray<UIViewController *> *)shown
                      events:(nullable dispatch_block_t)events

package/ios/Core/ANNAppearanceDispatcher.mm

@@ -305,7 +305,18 @@ static BOOL ANNIsInsideNode(UIViewController *screen, UIViewController *node) {
     for (UIViewController *node in shown) {
         [self nodeDidAppear:node];
     }
-    [ANNNavigationState updateNow];
+    // The state before the transition's events, once per answer: the answer's own step before its promise finds it
+    // sent. A user's transition has no answer; one whose answer went before its end (an interrupt) sends the state of
+    // its end itself, as Android does.
+    if (!answer) {
+        [ANNNavigationState updateNow];
+    } else if (answer.answered) {
+        if (answer.isCurrent) {
+            [ANNNavigationState updateNowFor:answer.commandName];
+        }
+    } else {
+        [answer reportStateNow];
+    }
     if (events) {
         events();
     }

package/ios/Core/ANNErrorHandler.h

@@ -14,7 +14,7 @@ NS_ASSUME_NONNULL_BEGIN
 /// Resolves a command's promise with `value`. Without a resolve block one line goes to the log instead.
 + (void)resolve:(nullable RCTPromiseResolveBlock)resolve of:(NSString *)method value:(nullable id)value;
 
-/// The log line of a command without a promise: `[ApexNavigation] <method>: <text>`.
+/// The log line of a command without a promise: `[ApexNavigation] <method>: <text>`, a warning (`RCTLogWarn`).
 + (void)logFailureOf:(NSString *)method text:(NSString *)text;
 
 @end

package/ios/Core/ANNErrorHandler.mm

@@ -23,8 +23,10 @@
     resolve(value);
 }
 
+// A warning, not an error: a failed command without a promise (a `mergeOptions` the screen can't take) is the app's
+// to notice, not a red box over it; Android logs it the same way, without a dialog.
 + (void)logFailureOf:(NSString *)method text:(NSString *)text {
-    RCTLogError(@"[ApexNavigation] %@: %@", method, text);
+    RCTLogWarn(@"[ApexNavigation] %@: %@", method, text);
 }
 
 @end

package/ios/Core/ANNEventEmitter.h

@@ -28,7 +28,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 #pragma mark - The contract
 
-/// `ANN.AppLaunched`, without a payload. While JavaScript has no listener of it, it is kept and goes once JavaScript
+/// `ANN.AppLaunched`, with an empty payload. While JavaScript has no listener of it, it is kept and goes once JavaScript
 /// adds the first one. Main queue.
 - (void)sendAppLaunched;
 

package/ios/Core/ANNEventEmitter.mm

@@ -60,7 +60,7 @@ static NSUInteger ANNAppLaunchedBundle;
         return;
     }
     ANNAppLaunchedPending = NO;
-    [eventEmitter sendIfListened:ANNEventContract.AppLaunched.event body:nil];
+    [eventEmitter sendIfListened:ANNEventContract.AppLaunched.event body:@{}];
 }
 
 + (void)eventEmitterListensToAppLaunched:(ANNTurboEventEmitter *)eventEmitter {
@@ -69,7 +69,7 @@ static NSUInteger ANNAppLaunchedBundle;
         return;
     }
     ANNAppLaunchedPending = NO;
-    [eventEmitter sendIfListened:ANNEventContract.AppLaunched.event body:nil];
+    [eventEmitter sendIfListened:ANNEventContract.AppLaunched.event body:@{}];
 }
 
 // Only an `AppLaunched` of the module's own JavaScript or an older one: the module is made while its bundle runs,

package/ios/Core/ANNJavaScriptCalls.h

@@ -0,0 +1,34 @@
+#import <Foundation/Foundation.h>
+
+@class RCTCallInvoker;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The way of the calls JavaScript makes to `ANNTurboModule`, for a step that must come after them. A call without an
+/// answer (`mergeOptions`) leaves the JavaScript thread as it is made, goes to the module's queue (React Native's
+/// `ModuleNativeMethodCallInvoker`, a `dispatch_async` to it) and from there to the main queue (`ANNCommandRunner`):
+/// a step that takes the same three hops after them comes after them on the main queue, as each of the three runs its
+/// work in order. The module tells its call invoker and its queue when React Native made it, and that it went when
+/// React Native invalidates it (a reload). Any thread, except `afterCallsMadeSoFar:`.
+@interface ANNJavaScriptCalls : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The module of the JavaScript that runs now, its call invoker (the JavaScript thread) and its queue.
++ (void)setCallInvoker:(nullable RCTCallInvoker *)callInvoker
+           methodQueue:(nullable dispatch_queue_t)methodQueue
+              ofModule:(id)module;
+
+/// The module went: with no newer module told since, no JavaScript runs to wait for.
++ (void)moduleWent:(id)module;
+
+/// `block` runs on the main queue once every call JavaScript made to the module before the next task of its thread is
+/// applied on the main queue: a task on the JavaScript thread, from there one on the module's queue, from there one on
+/// the main queue. With no JavaScript to ask (none yet, a reload), at once. Main queue. A JavaScript thread that never
+/// runs the task again (its runtime went) never runs `block`: a caller that can't wait for long has a limit of its own.
++ (void)afterCallsMadeSoFar:(dispatch_block_t)block;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Core/ANNJavaScriptCalls.mm

@@ -0,0 +1,61 @@
+#import "ANNJavaScriptCalls.h"
+#import "ANNAssert.h"
+#import <React/RCTCallInvoker.h>
+#import <React/RCTUtils.h>
+#import <ReactCommon/CallInvoker.h>
+
+// The module told last, weakly: a module that went takes its invoker and its queue with it.
+static __weak id ANNCallsModule;
+static RCTCallInvoker *ANNCallsInvoker;
+static dispatch_queue_t ANNCallsQueue;
+
+@implementation ANNJavaScriptCalls
+
++ (void)setCallInvoker:(RCTCallInvoker *)callInvoker
+           methodQueue:(dispatch_queue_t)methodQueue
+              ofModule:(id)module {
+    @synchronized(self) {
+        ANNCallsModule = module;
+        ANNCallsInvoker = callInvoker;
+        ANNCallsQueue = methodQueue;
+    }
+}
+
++ (void)moduleWent:(id)module {
+    @synchronized(self) {
+        if (ANNCallsModule != module) {
+            return;
+        }
+        ANNCallsModule = nil;
+        ANNCallsInvoker = nil;
+        ANNCallsQueue = nil;
+    }
+}
+
++ (void)afterCallsMadeSoFar:(dispatch_block_t)block {
+    ANNAssertMainQueue();
+    RCTCallInvoker *callInvoker = nil;
+    dispatch_queue_t queue = nil;
+    @synchronized(self) {
+        if (ANNCallsModule) {
+            callInvoker = ANNCallsInvoker;
+            queue = ANNCallsQueue;
+        }
+    }
+    std::shared_ptr<facebook::react::CallInvoker> invoker =
+        callInvoker ? callInvoker.callInvoker : nullptr;
+    if (!invoker || !queue) {
+        block();
+        return;
+    }
+    dispatch_block_t done = [block copy];
+    // The JavaScript thread runs the task after the one it runs now, which made the calls of this moment (a commit of
+    // React and its layout effects); the module's queue then has those calls before this hop, and the main queue too.
+    invoker->invokeAsync([queue, done](facebook::jsi::Runtime &) {
+        dispatch_async(queue, ^{
+          RCTExecuteOnMainQueue(done);
+        });
+    });
+}
+
+@end

package/ios/Core/ANNNavigationState.h

@@ -23,12 +23,14 @@ NS_ASSUME_NONNULL_BEGIN
 + (void)holdUpdates;
 + (void)releaseUpdates;
 
-/// The state now, sent when it changed: at the end of a transition, at once after a tab chosen from code. A walk that
-/// throws logs one line and sends nothing, so its caller always goes on.
-+ (void)updateNow;
+/// The state now, sent when it changed. A command's answer asks for it once (`-[ANNCommandAnswer reportStateNow]`, at
+/// the end of its transition or before its promise); the end of a user's transition and a tab chosen from code ask
+/// `updateNow`. A walk that throws logs one line, `[ApexNavigation] <commandName>: could not report the navigation
+/// state: <reason>` (as on Android; `transition` without a command), and sends nothing, so its caller always goes on.
++ (void)updateNowFor:(nullable NSString *)commandName;
 
-/// A command is about to answer: when what shows changed, the new state goes now, before the promise.
-+ (void)reportBeforeAnswer;
+/// `updateNowFor:` without a command.
++ (void)updateNow;
 
 /// Forgets the last state sent: the next one goes even if it is the same (a new bundle, `AppLaunched`).
 + (void)reset;

package/ios/Core/ANNNavigationState.mm

@@ -2,12 +2,12 @@
 #import "ANNAssert.h"
 #import "ANNBottomTabsController.h"
 #import "ANNComponentViewController.h"
+#import "ANNErrorHandler.h"
 #import "ANNErrorTexts.h"
 #import "ANNModalCoordinator.h"
 #import "ANNSlotContainers.h"
 #import "ApexNavigation+Internal.h"
 #import "UIViewController+LayoutProtocol.h"
-#import <React/RCTLog.h>
 
 // Main queue.
 static BOOL ANNUpdateScheduled;
@@ -58,6 +58,10 @@ static BOOL ANNSameValue(id a, id b) {
 }
 
 + (void)updateNow {
+    [self updateNowFor:nil];
+}
+
++ (void)updateNowFor:(NSString *)commandName {
     ANNAssertMainQueue();
     NSString *screenId = nil;
     NSString *name = nil;
@@ -74,8 +78,9 @@ static BOOL ANNSameValue(id a, id b) {
         }
     } @catch (NSException *exception) {
         NSString *reason = exception.reason.length > 0 ? exception.reason : exception.name;
-        RCTLogWarn(@"[ApexNavigation] %@",
-                   [ANNErrorTexts couldNot:@"report the navigation state" reason:reason]);
+        [ANNErrorHandler logFailureOf:commandName ?: @"transition"
+                                 text:[ANNErrorTexts couldNot:@"report the navigation state"
+                                                        reason:reason]];
         return;
     }
     if (ANNHasLastState && ANNSameValue(screenId, ANNLastScreenId) &&
@@ -89,10 +94,6 @@ static BOOL ANNSameValue(id a, id b) {
     [ApexNavigation.eventEmitter sendNavigationStateChanged:screenId name:name tab:tab];
 }
 
-+ (void)reportBeforeAnswer {
-    [self updateNow];
-}
-
 + (void)reset {
     ANNAssertMainQueue();
     ANNHasLastState = NO;