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

package/ios/Animations/Elements/ANNElementFinder.mm

@@ -1,8 +1,58 @@
 #import "ANNElementFinder.h"
 #import "ANNAppearanceDispatcher.h"
+#import "ANNElementTransitionOptions.h"
+#import "ANNSharedElementTransitionOptions.h"
+#import "Text.h"
 #import "UIViewController+LayoutProtocol.h"
+#import <React/RCTLog.h>
 #import <React/RCTViewComponentView.h>
 
+static NSString *ANNNativeIDOfView(UIView *view) {
+    return [view isKindOfClass:RCTViewComponentView.class]
+               ? ((RCTViewComponentView *)view).nativeId
+               : nil;
+}
+
+// Depth first, as the search by one id: the first view of the walk with an id keeps it. NO once every id is found.
+static BOOL ANNCollectViews(UIView *view, NSSet<NSString *> *nativeIDs,
+                            NSMutableDictionary<NSString *, UIView *> *found) {
+    NSString *nativeID = ANNNativeIDOfView(view);
+    if (nativeID && !found[nativeID] && [nativeIDs containsObject:nativeID]) {
+        found[nativeID] = view;
+        if (found.count == nativeIDs.count) {
+            return NO;
+        }
+    }
+    for (UIView *subview in view.subviews) {
+        if (!ANNCollectViews(subview, nativeIDs, found)) {
+            return NO;
+        }
+    }
+    return YES;
+}
+
+NSString *ANNNativeIDOf(Text *value) {
+    NSString *text = [value withDefault:nil];
+    return [text isKindOfClass:NSString.class] && text.length > 0 ? text : nil;
+}
+
+void ANNElementSkipped(NSString *element, NSString *reason) {
+    RCTLogWarn(@"[ApexNavigation] the transition's element %@ is skipped, it shows and hides with "
+               @"its screen while the rest plays: %@",
+               element, reason);
+}
+
+BOOL ANNElementStep(NSString *element, NS_NOESCAPE dispatch_block_t work) {
+    @try {
+        work();
+        return YES;
+    } @catch (NSException *exception) {
+        ANNElementSkipped(element, [NSString stringWithFormat:@"%@ (%@)", exception.reason ?: @"",
+                                                              exception.name]);
+        return NO;
+    }
+}
+
 @implementation ANNElementFinder
 
 + (UIView *)searchRootOf:(UIViewController *)node {
@@ -17,8 +67,7 @@
     if (nativeID.length == 0 || !root) {
         return nil;
     }
-    if ([root isKindOfClass:RCTViewComponentView.class] &&
-        [((RCTViewComponentView *)root).nativeId isEqualToString:nativeID]) {
+    if ([ANNNativeIDOfView(root) isEqualToString:nativeID]) {
         return root;
     }
     for (UIView *subview in root.subviews) {
@@ -34,4 +83,127 @@
     return [self viewWithNativeID:nativeID inView:[self searchRootOf:node]];
 }
 
++ (NSDictionary<NSString *, UIView *> *)viewsWithNativeIDs:(NSSet<NSString *> *)nativeIDs
+                                                    inView:(UIView *)root {
+    NSMutableDictionary<NSString *, UIView *> *found = [NSMutableDictionary new];
+    if (root && nativeIDs.count > 0) {
+        ANNCollectViews(root, nativeIDs, found);
+    }
+    return found;
+}
+
+@end
+
+@implementation ANNTransitionViews {
+    NSSet<NSString *> *_leavingIDs;
+    NSSet<NSString *> *_targetIDs;
+    NSSet<NSString *> *_elementIDs;
+    NSDictionary<NSString *, UIView *> *_leavingViews;
+    NSDictionary<NSString *, UIView *> *_arrivingViews;
+}
+
+- (instancetype)initWithPairs:(NSArray<ANNSharedElementTransitionOptions *> *)pairs
+                     elements:(NSArray<ANNElementTransitionOptions *> *)elements
+                     fromNode:(UIViewController *)fromNode
+                       toNode:(UIViewController *)toNode {
+    if (self = [super init]) {
+        _leavingRoot = [ANNElementFinder searchRootOf:fromNode];
+        _arrivingRoot = [ANNElementFinder searchRootOf:toNode];
+        NSMutableSet<NSString *> *sources = [NSMutableSet new];
+        NSMutableSet<NSString *> *targets = [NSMutableSet new];
+        NSMutableSet<NSString *> *identifiers = [NSMutableSet new];
+        for (ANNSharedElementTransitionOptions *pair in pairs) {
+            NSString *fromId = ANNNativeIDOf(pair.fromId);
+            NSString *toId = ANNNativeIDOf(pair.toId);
+            if (fromId) {
+                [sources addObject:fromId];
+            }
+            if (toId) {
+                [targets addObject:toId];
+            }
+        }
+        for (ANNElementTransitionOptions *element in elements) {
+            NSString *identifier = ANNNativeIDOf(element.identifier);
+            if (identifier) {
+                [identifiers addObject:identifier];
+            }
+        }
+        [sources unionSet:identifiers];
+        _leavingIDs = sources;
+        _targetIDs = targets;
+        _elementIDs = identifiers;
+    }
+    return self;
+}
+
+- (UIView *)leavingViewWithNativeID:(NSString *)nativeID {
+    if (nativeID.length == 0) {
+        return nil;
+    }
+    if (!_leavingViews) {
+        _leavingViews = [ANNElementFinder viewsWithNativeIDs:_leavingIDs inView:_leavingRoot];
+    }
+    return _leavingViews[nativeID];
+}
+
+- (UIView *)arrivingViewWithNativeID:(NSString *)nativeID {
+    if (nativeID.length == 0) {
+        return nil;
+    }
+    if (!_arrivingViews) {
+        // An element is looked for in the arriving screen only when the leaving one doesn't have it: the walk stops
+        // sooner.
+        NSMutableSet<NSString *> *ids = [_targetIDs mutableCopy];
+        for (NSString *identifier in _elementIDs) {
+            if (![self leavingViewWithNativeID:identifier]) {
+                [ids addObject:identifier];
+            }
+        }
+        _arrivingViews = [ANNElementFinder viewsWithNativeIDs:ids inView:_arrivingRoot];
+    }
+    return _arrivingViews[nativeID];
+}
+
+@end
+
+@implementation ANNIsolatedElement {
+    id<ANNFrameClient> _client;
+    NSString *_name;
+    BOOL _failed;
+}
+
+- (instancetype)initWithClient:(id<ANNFrameClient>)client name:(NSString *)name {
+    if (self = [super init]) {
+        _client = client;
+        _name = [name copy];
+    }
+    return self;
+}
+
+#pragma mark - ANNFrameClient
+
+- (void)applyAtTime:(NSTimeInterval)time {
+    if (_failed) {
+        return;
+    }
+    id<ANNFrameClient> client = _client;
+    if (!ANNElementStep(_name, ^{
+          [client applyAtTime:time];
+        })) {
+        _failed = YES;
+        [self restore];
+    }
+}
+
+- (NSTimeInterval)endTime {
+    return _client.endTime;
+}
+
+- (void)restore {
+    id<ANNFrameClient> client = _client;
+    ANNElementStep(_name, ^{
+      [client restore];
+    });
+}
+
 @end

package/ios/Animations/Elements/ANNElementTransition.h

@@ -2,6 +2,7 @@
 #import <UIKit/UIKit.h>
 
 @class ANNElementTransitionOptions;
+@class ANNTransitionViews;
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -11,20 +12,21 @@ NS_ASSUME_NONNULL_BEGIN
 @interface ANNElementTransition : NSObject <ANNFrameClient>
 
 /// The items found: each `id` first in the leaving screen's React view, then in the arriving one; an item not found or
-/// without an animating property is left out.
+/// without an animating property is left out, and so is one whose start fails (`ANNElementStep`).
 + (NSArray<ANNElementTransition *> *)
     transitionsOf:(nullable NSArray<ANNElementTransitionOptions *> *)elements
-      leavingRoot:(nullable UIView *)leavingRoot
-     arrivingRoot:(nullable UIView *)arrivingRoot;
+            views:(ANNTransitionViews *)views;
 
 /// Every item's `id` is found in one of the two screens (the wait's test).
 + (BOOL)allFound:(nullable NSArray<ANNElementTransitionOptions *> *)elements
-     leavingRoot:(nullable UIView *)leavingRoot
-    arrivingRoot:(nullable UIView *)arrivingRoot;
+           views:(ANNTransitionViews *)views;
 
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
 
+/// The item's `id`, in quotes: its name in the log.
+@property(nonatomic, copy, readonly) NSString *name;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Animations/Elements/ANNElementTransition.mm

@@ -7,51 +7,49 @@
     ANNViewTracks *_tracks;
 }
 
-- (instancetype)initWithTracks:(ANNViewTracks *)tracks {
+- (instancetype)initWithTracks:(ANNViewTracks *)tracks name:(NSString *)name {
     if (self = [super init]) {
         _tracks = tracks;
+        _name = [name copy];
     }
     return self;
 }
 
-+ (UIView *)viewOf:(ANNElementTransitionOptions *)element
-       leavingRoot:(UIView *)leavingRoot
-      arrivingRoot:(UIView *)arrivingRoot {
-    NSString *identifier = [element.identifier withDefault:nil];
-    if (![identifier isKindOfClass:NSString.class] || identifier.length == 0) {
-        return nil;
-    }
-    return [ANNElementFinder viewWithNativeID:identifier inView:leavingRoot]
-               ?: [ANNElementFinder viewWithNativeID:identifier inView:arrivingRoot];
++ (UIView *)viewOf:(NSString *)identifier views:(ANNTransitionViews *)views {
+    return [views leavingViewWithNativeID:identifier]
+               ?: [views arrivingViewWithNativeID:identifier];
 }
 
 + (NSArray<ANNElementTransition *> *)
     transitionsOf:(NSArray<ANNElementTransitionOptions *> *)elements
-      leavingRoot:(UIView *)leavingRoot
-     arrivingRoot:(UIView *)arrivingRoot {
+            views:(ANNTransitionViews *)views {
     NSMutableArray<ANNElementTransition *> *transitions = [NSMutableArray new];
     // One view takes one item: a second item for the same view would read the values the first one writes.
     NSHashTable<UIView *> *taken = [NSHashTable weakObjectsHashTable];
     for (ANNElementTransitionOptions *element in elements) {
-        UIView *view = [self viewOf:element leavingRoot:leavingRoot arrivingRoot:arrivingRoot];
+        NSString *identifier = ANNNativeIDOf(element.identifier);
+        UIView *view = [self viewOf:identifier views:views];
         if (!view || [taken containsObject:view]) {
             continue;
         }
-        ANNViewTracks *tracks = [[ANNViewTracks alloc] initWithView:view element:element];
-        if (!tracks.hasTracks) {
+        NSString *name = [NSString stringWithFormat:@"'%@'", identifier];
+        __block ANNViewTracks *tracks = nil;
+        if (!ANNElementStep(name, ^{
+              tracks = [[ANNViewTracks alloc] initWithView:view element:element];
+            }) ||
+            !tracks.hasTracks) {
             continue;
         }
         [taken addObject:view];
-        [transitions addObject:[[ANNElementTransition alloc] initWithTracks:tracks]];
+        [transitions addObject:[[ANNElementTransition alloc] initWithTracks:tracks name:name]];
     }
     return transitions;
 }
 
 + (BOOL)allFound:(NSArray<ANNElementTransitionOptions *> *)elements
-     leavingRoot:(UIView *)leavingRoot
-    arrivingRoot:(UIView *)arrivingRoot {
+           views:(ANNTransitionViews *)views {
     for (ANNElementTransitionOptions *element in elements) {
-        if (![self viewOf:element leavingRoot:leavingRoot arrivingRoot:arrivingRoot]) {
+        if (![self viewOf:ANNNativeIDOf(element.identifier) views:views]) {
             return NO;
         }
     }

package/ios/Animations/Elements/ANNSharedElementFlight.h

@@ -2,6 +2,7 @@
 #import <UIKit/UIKit.h>
 
 @class ANNSharedElementTransitionOptions;
+@class ANNTransitionViews;
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -18,18 +19,19 @@ NS_ASSUME_NONNULL_BEGIN
 /// grows, the last when it shrinks.
 @interface ANNSharedElementFlight : NSObject <ANNFrameClient>
 
-/// The flights of the pairs whose two views are found (`fromId` in the leaving screen, `toId` in the arriving one) and
-/// have a size; the others are skipped and their views stay as they are. The pictures are taken now, then the React
-/// views hide and the copies go into `container` by the `zIndex` of their `to` views, ascending (no `layer.zPosition`).
+/// The flights of the pairs whose two views are found (`fromId` in the leaving screen, `toId` in the arriving one); the
+/// others are skipped and their views stay as they are. A pair found that can't fly — a view without a size, a
+/// picture that can't be taken, a place that can't be worked out, an exception in its start (`ANNElementStep`) — is
+/// skipped too, with a line in the log. The pictures are taken now, then the React views hide and the copies go into
+/// `container` by the `zIndex` of their `to` views, ascending (no `layer.zPosition`).
 + (NSArray<ANNSharedElementFlight *> *)
-       flightsOf:(nullable NSArray<ANNSharedElementTransitionOptions *> *)pairs
-     leavingRoot:(nullable UIView *)leavingRoot
-    arrivingRoot:(nullable UIView *)arrivingRoot
-       container:(UIView *)container;
+    flightsOf:(nullable NSArray<ANNSharedElementTransitionOptions *> *)pairs
+        views:(ANNTransitionViews *)views
+    container:(UIView *)container;
 
 /// Every pair's `toId` is found in the arriving screen (the wait's test).
 + (BOOL)allTargetsFound:(nullable NSArray<ANNSharedElementTransitionOptions *> *)pairs
-           arrivingRoot:(nullable UIView *)arrivingRoot;
+                  views:(ANNTransitionViews *)views;
 
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
@@ -37,6 +39,9 @@ NS_ASSUME_NONNULL_BEGIN
 /// The copy that flies (a view of the core in the container).
 @property(nonatomic, strong, readonly) UIView *copyView;
 
+/// The pair's two ids, in quotes: its name in the log.
+@property(nonatomic, copy, readonly) NSString *name;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Animations/Elements/ANNSharedElementFlight.mm

@@ -103,6 +103,25 @@ static ANNFlightEnd ANNFlightEndOf(UIView *view, UIView *screenRoot, UIView *con
     return end;
 }
 
+static BOOL ANNIsFiniteRect(CGRect rect) {
+    return isfinite(rect.origin.x) && isfinite(rect.origin.y) && isfinite(rect.size.width) &&
+           isfinite(rect.size.height);
+}
+
+static BOOL ANNFlightEndIsFinite(ANNFlightEnd end) {
+    const CATransform3D t = end.transform;
+    const CGFloat values[] = {t.m11, t.m12, t.m13, t.m14, t.m21, t.m22, t.m23, t.m24,
+                              t.m31, t.m32, t.m33, t.m34, t.m41, t.m42, t.m43, t.m44};
+    for (CGFloat value : values) {
+        if (!isfinite(value)) {
+            return NO;
+        }
+    }
+    return isfinite(end.center.x) && isfinite(end.center.y) && isfinite(end.size.width) &&
+           isfinite(end.size.height) && isfinite(end.cornerRadius) && isfinite(end.visibleRadius) &&
+           ANNIsFiniteRect(end.visible);
+}
+
 // The picture of the view's layer and its sublayers at the screen's scale, in the layer's own coordinates.
 static UIImage *ANNPictureOf(UIView *view) {
     CGSize size = view.bounds.size;
@@ -140,15 +159,10 @@ static UIImage *ANNPictureOf(UIView *view) {
     BOOL _restored;
 }
 
-+ (NSString *)textOf:(Text *)value {
-    NSString *text = [value withDefault:nil];
-    return [text isKindOfClass:NSString.class] && text.length > 0 ? text : nil;
-}
-
 + (BOOL)allTargetsFound:(NSArray<ANNSharedElementTransitionOptions *> *)pairs
-           arrivingRoot:(UIView *)arrivingRoot {
+                  views:(ANNTransitionViews *)views {
     for (ANNSharedElementTransitionOptions *pair in pairs) {
-        if (![ANNElementFinder viewWithNativeID:[self textOf:pair.toId] inView:arrivingRoot]) {
+        if (![views arrivingViewWithNativeID:ANNNativeIDOf(pair.toId)]) {
             return NO;
         }
     }
@@ -156,27 +170,31 @@ static UIImage *ANNPictureOf(UIView *view) {
 }
 
 + (NSArray<ANNSharedElementFlight *> *)
-       flightsOf:(NSArray<ANNSharedElementTransitionOptions *> *)pairs
-     leavingRoot:(UIView *)leavingRoot
-    arrivingRoot:(UIView *)arrivingRoot
-       container:(UIView *)container {
+    flightsOf:(NSArray<ANNSharedElementTransitionOptions *> *)pairs
+        views:(ANNTransitionViews *)views
+    container:(UIView *)container {
     NSMutableArray<ANNSharedElementFlight *> *flights = [NSMutableArray new];
     NSHashTable<UIView *> *taken = [NSHashTable weakObjectsHashTable];
     for (ANNSharedElementTransitionOptions *pair in pairs) {
-        UIView *from = [ANNElementFinder viewWithNativeID:[self textOf:pair.fromId]
-                                                   inView:leavingRoot];
-        UIView *to = [ANNElementFinder viewWithNativeID:[self textOf:pair.toId]
-                                                 inView:arrivingRoot];
+        NSString *fromId = ANNNativeIDOf(pair.fromId);
+        NSString *toId = ANNNativeIDOf(pair.toId);
+        UIView *from = [views leavingViewWithNativeID:fromId];
+        UIView *to = [views arrivingViewWithNativeID:toId];
         if (!from || !to || from == to || [taken containsObject:from] ||
             [taken containsObject:to]) {
             continue;
         }
-        ANNSharedElementFlight *flight = [[self alloc] initWithPair:pair
-                                                               from:from
-                                                                 to:to
-                                                        leavingRoot:leavingRoot
-                                                       arrivingRoot:arrivingRoot
-                                                          container:container];
+        NSString *name = [NSString stringWithFormat:@"'%@' -> '%@'", fromId, toId];
+        __block ANNSharedElementFlight *flight = nil;
+        ANNElementStep(name, ^{
+          flight = [[self alloc] initWithPair:pair
+                                         from:from
+                                           to:to
+                                  leavingRoot:views.leavingRoot
+                                 arrivingRoot:views.arrivingRoot
+                                    container:container
+                                         name:name];
+        });
         if (flight) {
             [taken addObject:from];
             [taken addObject:to];
@@ -193,10 +211,18 @@ static UIImage *ANNPictureOf(UIView *view) {
                           }
                           return a->_zIndex < b->_zIndex ? NSOrderedAscending : NSOrderedDescending;
                         }];
+    // A copy that can't take off goes away, and its pair's views show as they were.
+    NSMutableArray<ANNSharedElementFlight *> *flying = [NSMutableArray new];
     for (ANNSharedElementFlight *flight in ordered) {
-        [flight takeOffIn:container];
+        if (ANNElementStep(flight.name, ^{
+              [flight takeOffIn:container];
+            })) {
+            [flying addObject:flight];
+        } else {
+            [flight restore];
+        }
     }
-    return ordered;
+    return flying;
 }
 
 - (instancetype)initWithPair:(ANNSharedElementTransitionOptions *)pair
@@ -204,19 +230,27 @@ static UIImage *ANNPictureOf(UIView *view) {
                           to:(UIView *)to
                  leavingRoot:(UIView *)leavingRoot
                 arrivingRoot:(UIView *)arrivingRoot
-                   container:(UIView *)container {
+                   container:(UIView *)container
+                        name:(NSString *)name {
     // A view of no size gives no picture: the pair is skipped and both views stay as they are.
     if (from.bounds.size.width <= 0 || from.bounds.size.height <= 0 || to.bounds.size.width <= 0 ||
         to.bounds.size.height <= 0) {
+        ANNElementSkipped(name, @"a view of the pair has no size, it isn't laid out");
         return nil;
     }
     if (!(self = [super init])) {
         return nil;
     }
+    _name = [name copy];
     _fromView = from;
     _toView = to;
     _from = ANNFlightEndOf(from, leavingRoot, container);
     _to = ANNFlightEndOf(to, arrivingRoot, container);
+    // A place that isn't a number would stop the copy's layer with an exception at its first frame.
+    if (!ANNFlightEndIsFinite(_from) || !ANNFlightEndIsFinite(_to)) {
+        ANNElementSkipped(name, @"the place of a view of the pair can't be worked out");
+        return nil;
+    }
     _text = ANNIsText(from) || ANNIsText(to);
     _grows = _to.size.height >= _from.size.height;
     _rightToLeft =
@@ -231,6 +265,7 @@ static UIImage *ANNPictureOf(UIView *view) {
     UIImage *fromImage = ANNPictureOf(from);
     UIImage *toImage = ANNPictureOf(to);
     if (!fromImage || !toImage) {
+        ANNElementSkipped(name, @"no picture of a view of the pair can be taken");
         return nil;
     }
     _copy = [UIView new];

package/ios/CLAUDE.md

@@ -58,9 +58,9 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
 - Preview — `Layouts/Stack/`: `ANNPreviewPush`; `Layouts/Screen/`: `ANNPreviewInteraction`
 - Animations, transitions — `Animations/` (plan and animator at the top; `Elements/` for shared elements and zoom; `Interpolators/` for curves and tracks)
 - System bars, orientation, direction — `Core/`: `ANNSystemUI`, `ANNSystemUIRules`, `ANNAppDirection`, `ANNNodePresenter` (the answers to UIKit)
-- Events and state — `Core/`: `ANNEventEmitter`, `ANNAppearanceDispatcher`, `ANNScreenAppearance`, `ANNNavigationState`; `TurboModules/`: `ANNTurboEventEmitter`
+- 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`; `Core/`: `ANNErrorHandler`
+- Error texts — `Contract/`: `ANNErrorTexts` (made from `src/interfaces/contract/errors.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`
@@ -114,6 +114,8 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
   `descendantDidAppear:`.
 - Hold and release of the navigation state come in pairs; a `setRoot` chain with layout modals or overlays holds it
   until its answer.
+- UIKit draws a dismissal without animation too (a sheet's dim goes a frame before its card): what goes out of sight
+  that way goes under a snapshot of the window (the old root's modals at `setRoot`, `startTransitionOf:done:`).
 - Use an `@available` check for newer OS APIs, and `#if __IPHONE_OS_VERSION_MAX_ALLOWED >= …` for names of a newer SDK.
 - React Native hears of the app's light or dark style only from its hosting views in the window. A view that stands in
   for one (`ANNSlotScreenView`, the screens of one tree) posts the trait change itself, with the window filter of
@@ -123,6 +125,12 @@ Top-level files: `Package.swift` (SwiftPM; `headerFolders` lists every folder wh
   (the root, a modal, an overlay: their record is listed and parked by then), and the modal's end steps inside UIKit's
   completions and delegate calls (`protectEndOf:showing:step:`, `protectBatch:step:`); the overlay's guard is
   `protectWaitOf:step:`.
+- Each step of a transition's element (a pair's start and take-off, an element's start, every frame and restore
+  through `ANNIsolatedElement`) runs in `ANNElementStep`: an exception skips that element only. A new step of an
+  element goes there too, or one bad element stops the transition (a frame's exception ends the app). The elements of
+  a transition are found in one walk per screen (`ANNTransitionViews`).
+- An `ANNCommandAnswer` that goes away unanswered rejects (`notAnswered:`), but only once nothing holds it: a record,
+  list or queue that keeps an answer still answers it on every exit, or the promise waits as long as the record lives.
 - On iOS 26 UIKit draws a screen's large title, for a whole pop or swipe back, inside the scroll view the bar follows
   for the top edge: a detached scroll view or a list below the bar hides it. `ANNLargeTitlePresenter` lays its title
   host over the screen's view for the transition and fills the band behind the title from the screen's top

package/ios/CORE.md

@@ -50,7 +50,8 @@ dispatcher.
 - **Appearance dispatcher** (`ANNAppearanceDispatcher`): the only sender of the appearance events; it also ends a
   transition in the fixed order and resolves the command's answer.
 - **Event emitter** (`ANNEventEmitter`, `ANNTurboEventEmitter`): sends `ANN.<Name>` to JS on the main queue, and drops
-  events of a JavaScript that went.
+  events of a JavaScript that went. The names and keys come from `ANNEventContract`, made from the event types of
+  `src/interfaces/` (`scripts/contract.mjs`).
 
 ## How a command flows
 
@@ -127,7 +128,7 @@ Each of these owns one rule. Call it; do not copy it.
 - `ANNModalCoordinator`, `ANNModal`: One record per modal, its states and waiting commands. Called by: Commands, root, state, repaint, reload.
 - `ANNPresentationGate`: The one queue of every UIKit present and dismiss in the main window. Called by: Modals, root, reload, search.
 - `ANNOverlayCoordinator`: Overlays, each in its own window, kept over a new root. Called by: Commands, root, reload.
-- `ANNSystemUI`: The system UI of the windows: marks groups, coalesces, asks UIKit once per turn; who decides. `ANNSystemUIRules` has the pure rules. Called by: Screens, containers, `ANNShownScreens`, `mergeOptions`.
+- `ANNSystemUI`: The system UI of the windows: marks groups, coalesces, asks UIKit once per turn; who decides; after a status bar ask, the screens' status bar blurs take its frame. `ANNSystemUIRules` has the pure rules. Called by: Screens, containers, `ANNShownScreens`, `mergeOptions`.
 - `ANNReloadCoordinator`: The generation of the JavaScript; the reset after a reload. Called by: Runner, emitter, answer.
 - Stack answer id: `ANNStackAnswerIdOf(entry, command)` in `ANNStackQueue.h`: the id a stack command answers with. `push` answers the node's own id (a pair's id); every other command, the entry's options screen (a pair's primary). Called by: The queue, `ANNStackCommands`, `ANNPreviewPush`, `ANNSplitViewCommands`.
 - Waited screens: `waitedComponentViewControllers`: the screens a wait is about (a pair: the ones it puts in the window). `ANNStackScreensOfEntry` is every screen of an entry, for what means all of them. Called by: `ANNRenderWait` owners: root, stack queue, modals, overlays, `ANNSplitViewCommands`.

package/ios/Contract/ANNCommandAnswer.h

@@ -3,14 +3,15 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /// The one answer of a command with a promise: the first `resolve:` or `reject:` answers, any later one does nothing,
-/// and nothing answers once the JavaScript that sent the command went. `ANNCommandRunner` makes it. Main queue.
+/// and nothing answers once the JavaScript that sent the command went. One that goes away unanswered while its
+/// JavaScript runs rejects `[ANNErrorTexts notAnswered:]`. `ANNCommandRunner` makes it. Main queue.
 @interface ANNCommandAnswer : NSObject
 
 - (instancetype)initWithCommandName:(NSString *)commandName
                           commandId:(nullable NSString *)commandId
                          generation:(NSUInteger)generation
-                            resolve:(RCTPromiseResolveBlock)resolve
-                             reject:(RCTPromiseRejectBlock)reject NS_DESIGNATED_INITIALIZER;
+                            resolve:(nullable RCTPromiseResolveBlock)resolve
+                             reject:(nullable RCTPromiseRejectBlock)reject NS_DESIGNATED_INITIALIZER;
 
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;

package/ios/Contract/ANNCommandAnswer.mm

@@ -41,6 +41,16 @@ static NSSet<NSString *> *ANNCompletedCommandNames(void) {
     return self;
 }
 
+// The last reference went without an answer: nothing took the command, or what took it let it go. The promise of a
+// JavaScript that still runs rejects, so it never waits forever. Any thread: the promise blocks are React Native's,
+// safe from any thread, and the generation is readable from any thread.
+- (void)dealloc {
+    if (_answered || !self.isCurrent) {
+        return;
+    }
+    [ANNErrorHandler reject:_reject of:_commandName text:[ANNErrorTexts notAnswered:_commandName]];
+}
+
 - (BOOL)isCurrent {
     return _generation == ANNReloadCoordinator.generation;
 }
@@ -77,7 +87,7 @@ static NSSet<NSString *> *ANNCompletedCommandNames(void) {
                                                             reason:reason]];
         }
     }
-    resolve(value);
+    [ANNErrorHandler resolve:resolve of:_commandName value:value];
     if (_commandId && [ANNCompletedCommandNames() containsObject:_commandName]) {
         double completionTime = floor(NSDate.date.timeIntervalSince1970 * 1000);
         [ApexNavigation.eventEmitter sendCommandCompleted:_commandName
@@ -93,7 +103,7 @@ static NSSet<NSString *> *ANNCompletedCommandNames(void) {
     RCTPromiseRejectBlock reject = _reject;
     _resolve = nil;
     _reject = nil;
-    [ANNErrorHandler reject:reject text:text];
+    [ANNErrorHandler reject:reject of:_commandName text:text];
 }
 
 @end

package/ios/Contract/ANNCommandRunner.h

@@ -22,8 +22,8 @@ typedef void (^ANNCommandBody)(id _Nullable layout, ANNCommandAnswer *answer);
 + (void)run:(NSString *)name
     commandId:(nullable NSString *)commandId
          what:(NSString *)what
-      resolve:(RCTPromiseResolveBlock)resolve
-       reject:(RCTPromiseRejectBlock)reject
+      resolve:(nullable RCTPromiseResolveBlock)resolve
+       reject:(nullable RCTPromiseRejectBlock)reject
         check:(nullable ANNCommandCheck)check
          body:(ANNCommandBody)body;
 

package/ios/Contract/ANNCommandRunner.mm

@@ -37,7 +37,7 @@ static NSString *ANNRejectionOf(NSException *exception, NSString *what) {
             error = ANNRejectionOf(exception, what);
         }
         if (error) {
-            [ANNErrorHandler reject:reject text:error];
+            [ANNErrorHandler reject:reject of:name text:error];
             return;
         }
     }

package/ios/Contract/ANNErrorTexts.h

@@ -1,3 +1,5 @@
+// Made by scripts/contract.mjs from src/interfaces/contract/errors.json: change that file and run the script again.
+
 #import <Foundation/Foundation.h>
 
 NS_ASSUME_NONNULL_BEGIN
@@ -51,12 +53,12 @@ FOUNDATION_EXPORT NSExceptionName const ANNCommandRejectionException;
 + (NSString *)stackTakesScreens:(NSString *)stackId type:(NSString *)type;
 + (NSString *)emptyStack:(NSString *)stackId;
 + (NSString *)emptyTabs:(NSString *)tabsId;
+/// Only Android checks it: its tab bar shows at most 5 tabs.
 + (NSString *)tooManyTabs:(NSString *)tabsId count:(NSUInteger)count;
 + (NSString *)splitViewColumns:(NSString *)splitViewId;
+/// Only iOS checks it: Android has pairs on every version.
 + (NSString *)pairUnsupported:(NSString *)pairId;
 + (NSString *)pairNeedsTwoScreens:(NSString *)pairId;
-
-/// The other cases of the layout check: the texts both platforms use meanwhile.
 + (NSString *)nodeWithoutName:(NSString *)type nodeId:(NSString *)nodeId;
 + (NSString *)rootMissing;
 + (NSString *)tabsInTabs:(NSString *)tabsId;
@@ -77,6 +79,8 @@ FOUNDATION_EXPORT NSExceptionName const ANNCommandRejectionException;
 + (NSString *)couldNot:(NSString *)what reason:(NSString *)reason;
 /// A command whose part of the native core is not written yet.
 + (NSString *)notDoneYet:(NSString *)method;
+/// A command that nothing in the native core answered: what took it let it go, or nothing took it.
++ (NSString *)notAnswered:(NSString *)method;
 
 /// An `ANNCommandRejectionException` with `text` as its reason: the command that runs rejects with `text` as it is.
 + (NSException *)rejection:(NSString *)text;