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

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;

package/ios/Contract/ANNErrorTexts.mm

@@ -1,3 +1,5 @@
+// Made by scripts/contract.mjs from src/interfaces/contract/errors.json: change that file and run the script again.
+
 #import "ANNErrorTexts.h"
 
 NSExceptionName const ANNCommandRejectionException = @"ANNCommandRejectionException";
@@ -59,8 +61,8 @@ static NSString *ANNText(NSString *format, ...) {
 }
 
 + (NSString *)columnNotStack:(NSString *)componentId column:(NSString *)column {
-    return ANNText(@"the '%@' column of the split view of the screen '%@' is not a stack", column,
-                   componentId);
+    return ANNText(@"the '%@' column of the split view of the screen '%@' is not a stack",
+                   column, componentId);
 }
 
 + (NSString *)noScreensForStack:(NSString *)componentId {
@@ -74,7 +76,8 @@ static NSString *ANNText(NSString *format, ...) {
 #pragma mark - Root, modals, the app
 
 + (NSString *)setRootReplaced:(NSString *)rootId {
-    return ANNText(@"setRoot was replaced by a newer setRoot before the root '%@' finished showing",
+    return ANNText(@"setRoot was replaced by a newer setRoot before the root '%@' finished "
+                   @"showing",
                    rootId);
 }
 
@@ -141,8 +144,8 @@ static NSString *ANNText(NSString *format, ...) {
 }
 
 + (NSString *)tooManyTabs:(NSString *)tabsId count:(NSUInteger)count {
-    return ANNText(@"the tabs '%@' have %lu tabs: Android shows at most 5", tabsId,
-                   (unsigned long)count);
+    return ANNText(@"the tabs '%@' have %lu tabs: Android shows at most 5",
+                   tabsId, (unsigned long)count);
 }
 
 + (NSString *)splitViewColumns:(NSString *)splitViewId {
@@ -181,8 +184,8 @@ static NSString *ANNText(NSString *format, ...) {
 }
 
 + (NSString *)sideMenuInSide:(NSString *)menuId {
-    return ANNText(@"the side menu '%@' has a side menu in a side: a side menu doesn't go inside a "
-                   @"side menu",
+    return ANNText(@"the side menu '%@' has a side menu in a side: a side menu doesn't go inside "
+                   @"a side menu",
                    menuId);
 }
 
@@ -191,8 +194,8 @@ static NSString *ANNText(NSString *format, ...) {
 }
 
 + (NSString *)splitViewInColumn:(NSString *)splitViewId {
-    return ANNText(@"the split view '%@' has a column of type 'SplitView': a split view doesn't go "
-                   @"inside a split view",
+    return ANNText(@"the split view '%@' has a column of type 'SplitView': a split view doesn't "
+                   @"go inside a split view",
                    splitViewId);
 }
 
@@ -208,7 +211,8 @@ static NSString *ANNText(NSString *format, ...) {
 }
 
 + (NSString *)unreadableDefaultOption:(NSString *)path {
-    return ANNText(@"the option '%@' of the default options has a value the navigation can't read", path);
+    return ANNText(@"the option '%@' of the default options has a value the navigation can't read",
+                   path);
 }
 
 + (NSString *)previewGone:(NSString *)previewId {
@@ -223,6 +227,10 @@ static NSString *ANNText(NSString *format, ...) {
     return ANNText(@"could not run '%@': the native core doesn't do it yet", method);
 }
 
++ (NSString *)notAnswered:(NSString *)method {
+    return ANNText(@"could not run '%@': the native core let it go without an answer", method);
+}
+
 + (NSException *)rejection:(NSString *)text {
     return [NSException exceptionWithName:ANNCommandRejectionException reason:text userInfo:nil];
 }

package/ios/Core/ANNDeepLinkQueue.h

@@ -1,4 +1,4 @@
-#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -20,6 +20,25 @@ typedef void (^ANNLaunchLinkCompletion)(NSURL *_Nullable url);
 /// Hands `url` to `Linking`, or keeps it until React content first appears and no `takeLaunchLink:` waits.
 + (void)dispatchURL:(NSURL *)url;
 
+/**
+ * Runs `forward`, which hands the scene's link to the app delegate (`ANNSceneDelegate`). The URL the app delegate
+ * dispatches in it keeps the scene and its context, which React Native 0.88 and newer need to take a scene's link.
+ */
++ (void)forwardURLContext:(UIOpenURLContext *)context
+                  ofScene:(UIScene *)scene
+                  through:(NS_NOESCAPE dispatch_block_t)forward;
+
+/// `forwardURLContext:ofScene:through:` for a web link (`webpageURL`) of the scene.
++ (void)forwardUserActivity:(NSUserActivity *)activity
+                    ofScene:(UIScene *)scene
+                    through:(NS_NOESCAPE dispatch_block_t)forward;
+
+/// Hands the scene's link to `Linking` at once, past the queue: for an app delegate that doesn't take links.
++ (void)openURLContext:(UIOpenURLContext *)context ofScene:(UIScene *)scene;
+
+/// `openURLContext:ofScene:` for a web link (`webpageURL`) of the scene; an activity without one does nothing.
++ (void)openUserActivity:(NSUserActivity *)activity ofScene:(UIScene *)scene;
+
 /// The app's window scene connected (`+[ApexNavigation attachToWindowScene:]`).
 + (void)windowSceneDidConnect;
 

package/ios/Core/ANNDeepLinkQueue.mm

@@ -1,12 +1,41 @@
 #import "ANNDeepLinkQueue.h"
 #import "ANNAssert.h"
+#import "ANNEventEmitter.h"
+#import "ApexNavigation+Internal.h"
 #import <React/RCTLinkingManager.h>
 #import <React/RCTRootView.h>
 #import <UIKit/UIKit.h>
 
+// A link on its way to `Linking`, with the scene's own context or user activity it came in when it came from a scene.
+@interface ANNDeepLink : NSObject
+@property(nonatomic, readonly) NSURL *url;
+@property(nonatomic, readonly, nullable) UIOpenURLContext *context;
+@property(nonatomic, readonly, nullable) NSUserActivity *activity;
+@property(nonatomic, readonly, weak, nullable) UIScene *scene;
+@end
+
+@implementation ANNDeepLink
+
+- (instancetype)initWithURL:(NSURL *)url
+                    context:(UIOpenURLContext *)context
+                   activity:(NSUserActivity *)activity
+                      scene:(UIScene *)scene {
+    if (self = [super init]) {
+        _url = url;
+        _context = context;
+        _activity = activity;
+        _scene = scene;
+    }
+    return self;
+}
+
+@end
+
 // Main queue only.
 static BOOL ANNDeepLinkQueueStarted = NO;
-static NSMutableArray<NSURL *> *ANNPendingDeepLinkURLs;
+static NSMutableArray<ANNDeepLink *> *ANNPendingDeepLinks;
+// The scene's link the scene delegate is handing to the app delegate: the app delegate dispatches its URL.
+static ANNDeepLink *ANNForwardedSceneLink;
 // React content appeared: `RCTLinkingManager` exists and JS listens to `url` events.
 static BOOL ANNReactContentAppeared = NO;
 // Every URL that launched the app was dispatched.
@@ -20,7 +49,7 @@ static ANNLaunchLinkCompletion ANNWaitingLaunchLinkCompletion;
 
 + (void)initialize {
     if (self == ANNDeepLinkQueue.class) {
-        ANNPendingDeepLinkURLs = [NSMutableArray new];
+        ANNPendingDeepLinks = [NSMutableArray new];
     }
 }
 
@@ -46,11 +75,44 @@ static ANNLaunchLinkCompletion ANNWaitingLaunchLinkCompletion;
 
 + (void)dispatchURL:(NSURL *)url {
     ANNAssertMainQueue();
+    // The URL of the scene's link keeps its context; one the app delegate changed is a URL of its own.
+    ANNDeepLink *link = [ANNForwardedSceneLink.url isEqual:url]
+                            ? ANNForwardedSceneLink
+                            : [[ANNDeepLink alloc] initWithURL:url context:nil activity:nil scene:nil];
     if (ANNReactContentAppeared && ANNWaitingLaunchLinkCompletion == nil) {
-        [self openURL:url];
+        [self openLink:link];
+        return;
+    }
+    [ANNPendingDeepLinks addObject:link];
+}
+
++ (void)forwardURLContext:(UIOpenURLContext *)context
+                  ofScene:(UIScene *)scene
+                  through:(NS_NOESCAPE dispatch_block_t)forward {
+    [self forwardLink:[[ANNDeepLink alloc] initWithURL:context.URL context:context activity:nil scene:scene]
+              through:forward];
+}
+
++ (void)forwardUserActivity:(NSUserActivity *)activity
+                    ofScene:(UIScene *)scene
+                    through:(NS_NOESCAPE dispatch_block_t)forward {
+    if (activity.webpageURL == nil) {
+        forward();
+        return;
+    }
+    [self forwardLink:[[ANNDeepLink alloc] initWithURL:activity.webpageURL context:nil activity:activity scene:scene]
+              through:forward];
+}
+
++ (void)openURLContext:(UIOpenURLContext *)context ofScene:(UIScene *)scene {
+    [self openLink:[[ANNDeepLink alloc] initWithURL:context.URL context:context activity:nil scene:scene]];
+}
+
++ (void)openUserActivity:(NSUserActivity *)activity ofScene:(UIScene *)scene {
+    if (activity.webpageURL == nil) {
         return;
     }
-    [ANNPendingDeepLinkURLs addObject:url];
+    [self openLink:[[ANNDeepLink alloc] initWithURL:activity.webpageURL context:nil activity:activity scene:scene]];
 }
 
 + (void)windowSceneDidConnect {
@@ -98,10 +160,10 @@ static ANNLaunchLinkCompletion ANNWaitingLaunchLinkCompletion;
     if (ANNWaitingLaunchLinkCompletion != nil) {
         return;
     }
-    NSArray<NSURL *> *urls = [ANNPendingDeepLinkURLs copy];
-    [ANNPendingDeepLinkURLs removeAllObjects];
-    for (NSURL *url in urls) {
-        [self openURL:url];
+    NSArray<ANNDeepLink *> *links = [ANNPendingDeepLinks copy];
+    [ANNPendingDeepLinks removeAllObjects];
+    for (ANNDeepLink *link in links) {
+        [self openLink:link];
     }
 }
 
@@ -124,13 +186,46 @@ static ANNLaunchLinkCompletion ANNWaitingLaunchLinkCompletion;
 // One link opens the app. The links queued before it are dropped: opened after it, they would take the app elsewhere.
 + (void)giveLaunchLink:(ANNLaunchLinkCompletion)completion {
     ANNLaunchLinkTaken = YES;
-    NSURL *url = ANNPendingDeepLinkURLs.lastObject;
-    [ANNPendingDeepLinkURLs removeAllObjects];
+    NSURL *url = ANNPendingDeepLinks.lastObject.url;
+    [ANNPendingDeepLinks removeAllObjects];
     completion(url);
 }
 
-+ (void)openURL:(NSURL *)url {
-    [RCTLinkingManager application:UIApplication.sharedApplication openURL:url options:@{}];
++ (void)forwardLink:(ANNDeepLink *)link through:(NS_NOESCAPE dispatch_block_t)forward {
+    ANNAssertMainQueue();
+    ANNDeepLink *outer = ANNForwardedSceneLink;
+    ANNForwardedSceneLink = link;
+    forward();
+    ANNForwardedSceneLink = outer;
+}
+
+// React Native 0.88 and newer take a scene's links through its scene methods: in an app whose Info.plist names a scene
+// delegate, its app delegate methods take none. The earlier versions have only the app delegate methods.
++ (void)openLink:(ANNDeepLink *)link {
+    UIScene *scene = link.scene;
+    if (scene != nil && link.context != nil) {
+        SEL openContexts = NSSelectorFromString(@"scene:openURLContexts:");
+        if ([RCTLinkingManager respondsToSelector:openContexts]) {
+            IMP implementation = [RCTLinkingManager methodForSelector:openContexts];
+            ((void (*)(id, SEL, UIScene *, NSSet<UIOpenURLContext *> *))implementation)(
+                RCTLinkingManager.class, openContexts, scene, [NSSet setWithObject:link.context]);
+            return;
+        }
+    }
+    if (scene != nil && link.activity != nil) {
+        SEL continueActivity = NSSelectorFromString(@"scene:continueUserActivity:");
+        if ([RCTLinkingManager respondsToSelector:continueActivity]) {
+            IMP implementation = [RCTLinkingManager methodForSelector:continueActivity];
+            ((void (*)(id, SEL, UIScene *, NSUserActivity *))implementation)(
+                RCTLinkingManager.class, continueActivity, scene, link.activity);
+            return;
+        }
+    }
+    // A link of the app's own (`dispatchDeepLinkURL`) has no scene: on React Native 0.88 and newer, with a scene
+    // delegate in Info.plist, `Linking` doesn't take it from here. JavaScript hands it to `Linking` itself.
+    if (![RCTLinkingManager application:UIApplication.sharedApplication openURL:link.url options:@{}]) {
+        [ApexNavigation.eventEmitter sendDeepLinkDispatched:link.url];
+    }
 }
 
 @end

package/ios/Core/ANNErrorHandler.h

@@ -3,11 +3,16 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /// How a failed command tells JavaScript: a rejection carries only a sentence, never a code of its own, and a command
-/// without a promise writes the sentence to the log. The sentences are those of `ANNErrorTexts`.
+/// without a promise writes the sentence to the log. The sentences are those of `ANNErrorTexts`. The one place that
+/// calls a command's promise blocks: a block that is nil (a caller that passed none) is never called.
 @interface ANNErrorHandler : NSObject
 
-/// Rejects a command's promise with the sentence alone: React Native puts its own default code on it.
-+ (void)reject:(RCTPromiseRejectBlock)reject text:(NSString *)text;
+/// Rejects a command's promise with the sentence alone: React Native puts its own default code on it. Without a
+/// reject block the sentence goes to the log as `logFailureOf:text:` writes it.
++ (void)reject:(nullable RCTPromiseRejectBlock)reject of:(NSString *)method text:(NSString *)text;
+
+/// 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>`.
 + (void)logFailureOf:(NSString *)method text:(NSString *)text;