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

package/ios/Animations/ANNFrameDriver.mm

@@ -1,39 +1,85 @@
 #import "ANNFrameDriver.h"
 #import "ANNAssert.h"
 #import "ANNCurve.h"
-#import <QuartzCore/QuartzCore.h>
+#import "ANNTransformParts.h"
+#include <cmath>
 
-// The display link holds its target strongly and the run loop holds the link: the driver is reached weakly, so a driver
-// nobody keeps any more stops at its next frame.
-@interface ANNFrameTarget : NSObject
-@property(nonatomic, weak) id owner;
-@end
+// The samples per second of a client's values: a frame of a 120 Hz display each.
+static const double ANNSamplesPerSecond = 120;
 
-@interface ANNFrameDriver ()
-- (void)frame:(CADisplayLink *)link;
-@end
+// At most this many samples per client: a longer transition samples less often.
+static const NSUInteger ANNMaxSamples = 2400;
 
-@implementation ANNFrameTarget
+NSArray<NSNumber *> *ANNSampleTimes(NSTimeInterval end, NSTimeInterval length,
+                                    NSArray<NSNumber *> *marks) {
+    end = MIN(MAX(end, 0), length);
+    NSMutableArray<NSNumber *> *candidates = [NSMutableArray arrayWithObject:@0];
+    double step = MAX(1 / ANNSamplesPerSecond, end / ANNMaxSamples);
+    NSUInteger count = (NSUInteger)std::floor(end / step);
+    for (NSUInteger index = 1; index <= count; index++) {
+        [candidates addObject:@(index * step)];
+    }
+    for (NSNumber *mark in marks) {
+        double time = mark.doubleValue;
+        if (std::isfinite(time) && time > 0 && time < end) {
+            [candidates addObject:mark];
+        }
+    }
+    [candidates addObject:@(end)];
+    [candidates addObject:@(length)];
+    [candidates sortUsingSelector:@selector(compare:)];
+    NSMutableArray<NSNumber *> *times = [NSMutableArray arrayWithCapacity:candidates.count];
+    for (NSNumber *time in candidates) {
+        // Samples closer than a microsecond are one.
+        if (times.count == 0 || time.doubleValue - times.lastObject.doubleValue > 1e-6) {
+            [times addObject:time];
+        }
+    }
+    return times;
+}
 
-- (void)frame:(CADisplayLink *)link {
-    ANNFrameDriver *driver = _owner;
-    if (!driver) {
-        [link invalidate];
-        return;
+CAKeyframeAnimation *ANNKeyframes(NSString *keyPath, NSArray *values, NSArray<NSNumber *> *times,
+                                  NSTimeInterval length) {
+    if (length <= 0 || values.count == 0 || values.count != times.count) {
+        return nil;
+    }
+    NSMutableArray<NSNumber *> *keyTimes = [NSMutableArray arrayWithCapacity:times.count];
+    for (NSNumber *time in times) {
+        [keyTimes addObject:@(MIN(MAX(time.doubleValue / length, 0.0), 1.0))];
     }
-    [driver frame:link];
+    CAKeyframeAnimation *animation = [CAKeyframeAnimation animationWithKeyPath:keyPath];
+    animation.values = values;
+    animation.keyTimes = keyTimes;
+    animation.calculationMode = kCAAnimationLinear;
+    animation.duration = length;
+    animation.fillMode = kCAFillModeBoth;
+    animation.removedOnCompletion = NO;
+    return animation;
 }
 
-@end
+NSString *ANNAnimationKey(NSString *keyPath) {
+    return [@"ApexNavigation." stringByAppendingString:keyPath];
+}
 
 @implementation ANNFrameDriver {
     NSArray<id<ANNFrameClient>> *_clients;
     NSTimeInterval _length;
-    CADisplayLink *_link;
-    CFTimeInterval _start;
     dispatch_block_t _done;
-    // The driver keeps itself while its frames run: the transition that started it needn't.
-    ANNFrameDriver *_running;
+    BOOL _running;
+    BOOL _starting;
+    // When the animations were added; they start at the commit of the current transaction, a moment later.
+    CFTimeInterval _start;
+    // The driver keeps itself while its animations run: the transition that started it needn't.
+    ANNFrameDriver *_keep;
+    // A transition that follows a gesture: the layer whose time stops, its timing before, the clock's time the
+    // animations started at, the `done` that tells how it ended, and whether its end plays.
+    CALayer *_clock;
+    float _clockSpeed;
+    CFTimeInterval _clockBegin;
+    CFTimeInterval _clockOffset;
+    CFTimeInterval _base;
+    void (^_pausedDone)(BOOL finished);
+    BOOL _ending;
 }
 
 - (instancetype)initWithClients:(NSArray<id<ANNFrameClient>> *)clients
@@ -50,77 +96,187 @@
 }
 
 - (BOOL)isRunning {
-    return _link != nil;
+    return _running;
+}
+
+- (NSTimeInterval)length {
+    return _length;
 }
 
 - (void)startWithDone:(dispatch_block_t)done {
     ANNAssertMainQueue();
 #if DEBUG
     ANNCurveSelfCheck();
+    ANNTransformPartsSelfCheck();
 #endif
-    if (_link) {
+    if (_running || _done || _pausedDone) {
         return;
     }
     _done = [done copy];
-    _running = self;
-    [self applyAtTime:0];
-    ANNFrameTarget *target = [ANNFrameTarget new];
-    target.owner = self;
-    _link = [CADisplayLink displayLinkWithTarget:target selector:@selector(frame:)];
-    [_link addToRunLoop:NSRunLoop.mainRunLoop forMode:NSRunLoopCommonModes];
+    _running = YES;
+    _keep = self;
+    _starting = YES;
     _start = CACurrentMediaTime();
+    __weak ANNFrameDriver *weakSelf = self;
+    [CATransaction begin];
+    [CATransaction setDisableActions:YES];
+    // Called once every animation added in this transaction ended or was removed (with its layer too), and at once
+    // without any.
+    [CATransaction setCompletionBlock:^{
+      [weakSelf animationsEnded];
+    }];
+    @try {
+        for (id<ANNFrameClient> client in _clients) {
+            [client addAnimationsWithLength:_length];
+        }
+    } @finally {
+        [CATransaction commit];
+        _starting = NO;
+    }
 }
 
-- (void)frame:(CADisplayLink *)link {
-    if (link != _link) {
-        [link invalidate];
+- (void)animationsEnded {
+    if (!_running) {
         return;
     }
-    NSTimeInterval time = link.targetTimestamp - _start;
-    if (time < 0) {
-        time = 0;
-    }
-    if (time >= _length) {
-        [self applyAtTime:_length];
-        [self stop];
-        dispatch_block_t done = _done;
-        _done = nil;
-        _running = nil;
-        if (done) {
-            done();
-        }
+    // `done` never comes inside `startWithDone:`, nor before the length passed: a transition with nothing to play (no
+    // client, every element skipped) or whose animations went early still takes its time, as on Android.
+    __weak ANNFrameDriver *weakSelf = self;
+    NSTimeInterval left = _length - (CACurrentMediaTime() - _start);
+    if (_starting || left > 0) {
+        dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(MAX(left, 0) * NSEC_PER_SEC)),
+                       dispatch_get_main_queue(), ^{
+                         [weakSelf animationsEnded];
+                       });
         return;
     }
-    [self applyAtTime:time];
+    _running = NO;
+    dispatch_block_t done = _done;
+    _done = nil;
+    _keep = nil;
+    if (done) {
+        done();
+    }
+}
+
+- (void)cancel {
+    ANNAssertMainQueue();
+    if (!_running) {
+        return;
+    }
+    _running = NO;
+    _done = nil;
+    _pausedDone = nil;
+    _keep = nil;
+    [self releaseClock];
 }
 
-- (void)applyAtTime:(NSTimeInterval)time {
+#pragma mark - Following a gesture
+
+- (void)startPausedOn:(CALayer *)clock done:(void (^)(BOOL finished))done {
+    ANNAssertMainQueue();
+    if (_running || _done || _pausedDone) {
+        return;
+    }
+    _pausedDone = [done copy];
+    _running = YES;
+    _keep = self;
+    _clock = clock;
+    _clockSpeed = clock.speed;
+    _clockBegin = clock.beginTime;
+    _clockOffset = clock.timeOffset;
+    // The clock stops at its time now: what else animates under it holds still, and the animations added now start
+    // there (Core Animation gives an animation without a begin time the layer's time at the commit).
+    _base = [clock convertTime:CACurrentMediaTime() fromLayer:nil];
     [CATransaction begin];
     [CATransaction setDisableActions:YES];
-    for (id<ANNFrameClient> client in _clients) {
-        [client applyAtTime:time];
+    clock.speed = 0;
+    clock.beginTime = 0;
+    clock.timeOffset = _base;
+    @try {
+        for (id<ANNFrameClient> client in _clients) {
+            [client addAnimationsWithLength:_length];
+        }
+    } @finally {
+        [CATransaction commit];
+    }
+}
+
+- (void)setProgress:(CGFloat)progress {
+    ANNAssertMainQueue();
+    if (!_running || !_pausedDone || _ending) {
+        return;
     }
+    [CATransaction begin];
+    [CATransaction setDisableActions:YES];
+    _clock.timeOffset = _base + MIN(MAX(progress, 0.0), 1.0) * _length;
     [CATransaction commit];
 }
 
-- (void)stop {
-    [_link invalidate];
-    _link = nil;
+- (void)finishWithSpeed:(CGFloat)speed {
+    [self playOnForward:YES speed:speed];
 }
 
-- (void)cancel {
+- (void)rewindWithSpeed:(CGFloat)speed {
+    [self playOnForward:NO speed:speed];
+}
+
+// The clock runs again from where it shows, forward or back, and `done` comes once it reached the end or the start.
+- (void)playOnForward:(BOOL)forward speed:(CGFloat)speed {
     ANNAssertMainQueue();
-    if (!_link) {
+    if (!_running || !_pausedDone || _ending) {
         return;
     }
-    [self applyAtTime:_length];
-    [self stop];
-    _done = nil;
-    _running = nil;
+    _ending = YES;
+    speed = MAX(speed, 1.0);
+    CALayer *clock = _clock;
+    CFTimeInterval at = clock.timeOffset - _base;
+    CFTimeInterval left = forward ? _length - at : at;
+    CALayer *parent = clock.superlayer;
+    CFTimeInterval now = parent ? [parent convertTime:CACurrentMediaTime() fromLayer:nil]
+                                : CACurrentMediaTime();
+    [CATransaction begin];
+    [CATransaction setDisableActions:YES];
+    // The clock's time is (parent's time - beginTime) * speed + timeOffset: it goes on from where it shows.
+    clock.beginTime = now;
+    clock.speed = (float)(forward ? speed : -speed);
+    [CATransaction commit];
+    __weak ANNFrameDriver *weakSelf = self;
+    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(MAX(left / speed, 0) * NSEC_PER_SEC)),
+                   dispatch_get_main_queue(), ^{
+                     [weakSelf pausedEndedForward:forward];
+                   });
 }
 
-- (void)dealloc {
-    [_link invalidate];
+- (void)pausedEndedForward:(BOOL)forward {
+    if (!_running || !_pausedDone) {
+        return;
+    }
+    _running = NO;
+    void (^done)(BOOL) = _pausedDone;
+    _pausedDone = nil;
+    _keep = nil;
+    // The clock's time back and the caller's restore in one commit: between two, the animations would show at the
+    // clock's own time for a frame (past their end, or part way).
+    [CATransaction begin];
+    [self releaseClock];
+    done(forward);
+    [CATransaction commit];
+}
+
+// The clock gets back the timing it had before the gesture.
+- (void)releaseClock {
+    CALayer *clock = _clock;
+    _clock = nil;
+    if (!clock) {
+        return;
+    }
+    [CATransaction begin];
+    [CATransaction setDisableActions:YES];
+    clock.speed = _clockSpeed;
+    clock.beginTime = _clockBegin;
+    clock.timeOffset = _clockOffset;
+    [CATransaction commit];
 }
 
 @end

package/ios/Animations/ANNTransitionAnimator.h

@@ -12,10 +12,10 @@ NS_ASSUME_NONNULL_BEGIN
 /// above the leaving one (push, `setStackRoot`, show) or below it (pop, dismissal), gets its final frame and lays out
 /// (React gets its final size), and hides (alpha 0) until the start; a forward transition starts after its wait
 /// (`ANNTransitionWait`), a backward one at once. Then one frame driver moves the sides that play, the elements in
-/// place and the shared elements' copies; a side that doesn't play doesn't move. At the end, before
-/// `completeTransition:`, the elements get their values back, the copies go and the React views show again, and both
-/// views get back the transform and the alpha they had. Never interactive, never cancelled; `completeTransition:` never
-/// comes inside `animateTransition:`. Main queue.
+/// place and the shared elements' copies, in Core Animation; a side that doesn't play doesn't move. At the end, before
+/// `completeTransition:`, the animations go, the copies go and the React views show again, and both views get back the
+/// transform and the alpha they had. Only a pop of the swipe back follows a gesture (`animateFollowingGesture:`) and
+/// can end where it began; `completeTransition:` never comes inside `animateTransition:`. Main queue.
 @interface ANNTransitionAnimator : NSObject <UIViewControllerAnimatedTransitioning>
 
 - (instancetype)initWithPlan:(ANNTransitionPlan *)plan NS_DESIGNATED_INITIALIZER;
@@ -25,8 +25,29 @@ NS_ASSUME_NONNULL_BEGIN
 
 @property(nonatomic, strong, readonly) ANNTransitionPlan *plan;
 
+/// The start of an interactive transition (a pop of the swipe back, which never waits): as `animateTransition:`, with
+/// the frames held at their start until `setProgress:` moves them (`ANNFrameDriver startPausedOn:`); then
+/// `finishWithSpeed:` or `rewindWithSpeed:`, after the context's own finish or cancel, plays the end.
+- (void)animateFollowingGesture:(id<UIViewControllerContextTransitioning>)transitionContext;
+
+/// The frames show at `progress` (0 to 1) of the length.
+- (void)setProgress:(CGFloat)progress;
+
+/// The rest plays (`speed` times as fast, 1 or more), and the transition completes.
+- (void)finishWithSpeed:(CGFloat)speed;
+
+/// The frames play back to the start (`speed` times as fast, 1 or more), and the transition completes cancelled.
+- (void)rewindWithSpeed:(CGFloat)speed;
+
+/// The seconds the frames take: the plan's length, or the end of a longer element.
+@property(nonatomic, readonly) NSTimeInterval length;
+
+/// The transition completed (or was never started).
+@property(nonatomic, readonly) BOOL isCompleted;
+
 /// A destroy or a reload during the transition: the wait or the frames stop at the end state, every value written goes
-/// back, and the transition completes so that UIKit isn't left half way. Nothing once it completed.
+/// back, and the transition completes so that UIKit isn't left half way (an interactive one finishes first). Nothing
+/// once it completed.
 - (void)cancel;
 
 @end

package/ios/Animations/ANNTransitionAnimator.mm

@@ -33,6 +33,9 @@ static void ANNUpdateRootLayoutOf(UIViewController *node) {
     NSArray<id<ANNFrameClient>> *_clients;
     BOOL _began;
     BOOL _completed;
+    // The transition follows a gesture (`animateFollowingGesture:`), and its end was chosen.
+    BOOL _followsGesture;
+    BOOL _endChosen;
     // The container's views of the transition that got a depth for it, and the depth each had.
     NSArray<UIView *> *_depthViews;
     NSArray<NSNumber *> *_depthsBefore;
@@ -118,6 +121,33 @@ static void ANNUpdateRootLayoutOf(UIViewController *node) {
     [self begin];
 }
 
+- (void)animateFollowingGesture:(id<UIViewControllerContextTransitioning>)transitionContext {
+    _followsGesture = YES;
+    [self animateTransition:transitionContext];
+}
+
+- (void)setProgress:(CGFloat)progress {
+    [_driver setProgress:progress];
+}
+
+- (void)finishWithSpeed:(CGFloat)speed {
+    _endChosen = YES;
+    [_driver finishWithSpeed:speed];
+}
+
+- (void)rewindWithSpeed:(CGFloat)speed {
+    _endChosen = YES;
+    [_driver rewindWithSpeed:speed];
+}
+
+- (NSTimeInterval)length {
+    return _driver ? _driver.length : _plan.length;
+}
+
+- (BOOL)isCompleted {
+    return _completed || !_context;
+}
+
 - (void)animationEnded:(BOOL)transitionCompleted {
     _wait = nil;
     _driver = nil;
@@ -133,19 +163,16 @@ static void ANNUpdateRootLayoutOf(UIViewController *node) {
     _began = YES;
     _wait = nil;
     UIView *container = _context.containerView;
-    UIView *leavingRoot = [ANNElementFinder searchRootOf:_plan.fromNode];
-    UIView *arrivingRoot = [ANNElementFinder searchRootOf:_plan.toNode];
+    ANNTransitionViews *views = [[ANNTransitionViews alloc] initWithPairs:_plan.sharedElements
+                                                                 elements:_plan.elements
+                                                                 fromNode:_plan.fromNode
+                                                                   toNode:_plan.toNode];
     NSMutableArray<id<ANNFrameClient>> *clients = [NSMutableArray new];
     // The shared pairs first: their geometry and pictures are taken while the screens are still at rest.
     NSArray<ANNSharedElementFlight *> *flights =
-        [ANNSharedElementFlight flightsOf:_plan.sharedElements
-                              leavingRoot:leavingRoot
-                             arrivingRoot:arrivingRoot
-                                container:container];
+        [ANNSharedElementFlight flightsOf:_plan.sharedElements views:views container:container];
     NSArray<ANNElementTransition *> *elements =
-        [ANNElementTransition transitionsOf:_plan.elements
-                                leavingRoot:leavingRoot
-                               arrivingRoot:arrivingRoot];
+        [ANNElementTransition transitionsOf:_plan.elements views:views];
     ANNViewTracks *arrivingTracks = nil;
     ANNViewTracks *leavingTracks = nil;
     if (_plan.enter && _arriving) {
@@ -190,8 +217,9 @@ static void ANNUpdateRootLayoutOf(UIViewController *node) {
                                                    duration:_plan.length
                                                 alphaBefore:_leavingAlpha];
     }
-    // The arriving view shows from the start with its own alpha unless a track moves it.
-    if (_arriving && !arrivingTracks.animatesAlpha) {
+    // The arriving view gets its own alpha back: an `opacity` animation of its tracks shows over it from the start, in
+    // the same transaction.
+    if (_arriving) {
         _arriving.alpha = _arrivingAlpha;
     }
     if (arrivingTracks.hasTracks) {
@@ -200,14 +228,26 @@ static void ANNUpdateRootLayoutOf(UIViewController *node) {
     if (leavingTracks.hasTracks) {
         [clients addObject:leavingTracks];
     }
-    [clients addObjectsFromArray:elements];
-    [clients addObjectsFromArray:flights];
+    // Each element plays on its own: one whose animations fail goes back and stays, the others and the screens go on.
+    for (ANNElementTransition *element in elements) {
+        [clients addObject:[[ANNIsolatedElement alloc] initWithClient:element name:element.name]];
+    }
+    for (ANNSharedElementFlight *flight in flights) {
+        [clients addObject:[[ANNIsolatedElement alloc] initWithClient:flight name:flight.name]];
+    }
     _clients = clients;
     if ([self tilts]) {
         [self orderInDepthIn:container flights:flights];
     }
     __weak ANNTransitionAnimator *weakSelf = self;
     _driver = [[ANNFrameDriver alloc] initWithClients:clients length:_plan.length];
+    if (_followsGesture) {
+        [_driver startPausedOn:container.layer
+                          done:^(BOOL finished) {
+                            [weakSelf complete];
+                          }];
+        return;
+    }
     [_driver startWithDone:^{
       [weakSelf complete];
     }];
@@ -286,8 +326,16 @@ static BOOL ANNSideTilts(ANNViewAnimationOptions *side) {
     }
     [_wait cancel];
     _wait = nil;
+    // An interactive transition ends at its end state too: UIKit completes only one whose end was chosen.
+    if (_followsGesture && !_endChosen) {
+        _endChosen = YES;
+        [_context finishInteractiveTransition];
+    }
+    // A stopped clock gets its time back in the commit that removes the animations.
+    [CATransaction begin];
     [_driver cancel];
     [self complete];
+    [CATransaction commit];
 }
 
 @end

package/ios/Animations/ANNTransitionPlan.h

@@ -19,8 +19,8 @@ typedef NS_ENUM(NSInteger, ANNTransitionKind) {
     ANNTransitionKindDismiss,
 };
 
-/// The screen fade of a transition with elements and no screen animation of its own, or of a dismissed popover with
-/// nothing to play.
+/// The screen fade of a transition with elements and no screen animation of its own, of a dismissed popover with
+/// nothing to play, or of any transition while the system's Reduce Motion is on (then nothing else plays).
 typedef NS_ENUM(NSInteger, ANNScreenFade) {
     ANNScreenFadeNone,
     /// The arriving screen from 0 to its alpha.

package/ios/Animations/ANNTransitionPlan.mm

@@ -43,6 +43,16 @@ static const NSTimeInterval ANNElementsScreenFade = 0.3;
         length = MAX(length, [ANNAnimationRules lengthOfElements:_elements shared:_sharedElements]);
         length = MAX(length, _screenFadeDuration);
         _length = length;
+        // With the system's Reduce Motion on, nothing moves: the transition is a fade of the same length, the arriving
+        // screen in going forward, the leaving one out otherwise.
+        if (UIAccessibilityIsReduceMotionEnabled() && length > 0) {
+            _enter = nil;
+            _exit = nil;
+            _elements = @[];
+            _sharedElements = @[];
+            _screenFade = _isForward ? ANNScreenFadeArrivingIn : ANNScreenFadeLeavingOut;
+            _screenFadeDuration = length;
+        }
     }
     return self;
 }

package/ios/Animations/ANNTransitionWait.mm

@@ -48,13 +48,12 @@ static const NSTimeInterval ANNReadyCheckDelay = 0.1;
 }
 
 - (BOOL)targetsAreFound {
-    UIView *leavingRoot = [ANNElementFinder searchRootOf:_plan.fromNode];
-    UIView *arrivingRoot = [ANNElementFinder searchRootOf:_plan.toNode];
-    return [ANNSharedElementFlight allTargetsFound:_plan.sharedElements
-                                      arrivingRoot:arrivingRoot] &&
-           [ANNElementTransition allFound:_plan.elements
-                              leavingRoot:leavingRoot
-                             arrivingRoot:arrivingRoot];
+    ANNTransitionViews *views = [[ANNTransitionViews alloc] initWithPairs:_plan.sharedElements
+                                                                 elements:_plan.elements
+                                                                 fromNode:_plan.fromNode
+                                                                   toNode:_plan.toNode];
+    return [ANNSharedElementFlight allTargetsFound:_plan.sharedElements views:views] &&
+           [ANNElementTransition allFound:_plan.elements views:views];
 }
 
 - (BOOL)isReady {

package/ios/Animations/Elements/ANNElementFinder.h

@@ -1,5 +1,10 @@
+#import "ANNFrameDriver.h"
 #import <UIKit/UIKit.h>
 
+@class ANNElementTransitionOptions;
+@class ANNSharedElementTransitionOptions;
+@class Text;
+
 NS_ASSUME_NONNULL_BEGIN
 
 /// Finds the React views of the elements of a transition by their `nativeID`: depth first, the first match, in the
@@ -21,6 +26,58 @@ NS_ASSUME_NONNULL_BEGIN
 + (nullable UIView *)viewWithNativeID:(nullable NSString *)nativeID
                                inNode:(nullable UIViewController *)node;
 
+/// The views with the `nativeID`s of `nativeIDs` in `root` and its subviews, in one walk: for each id the view
+/// `viewWithNativeID:inView:` finds; an id no view has is left out. The walk stops once every id is found.
++ (NSDictionary<NSString *, UIView *> *)viewsWithNativeIDs:(NSSet<NSString *> *)nativeIDs
+                                                    inView:(nullable UIView *)root;
+
+@end
+
+/// The views of a transition's elements in its two screens: each screen is walked once, at its first lookup, for the
+/// ids looked for there — the leaving one for the pairs' `fromId`s and the elements' ids, the arriving one for the
+/// pairs' `toId`s and the elements' ids the leaving one doesn't have. A lookup finds what
+/// `+[ANNElementFinder viewWithNativeID:inView:]` finds in that screen as it was at its walk. Main queue.
+@interface ANNTransitionViews : NSObject
+
+- (instancetype)initWithPairs:(nullable NSArray<ANNSharedElementTransitionOptions *> *)pairs
+                     elements:(nullable NSArray<ANNElementTransitionOptions *> *)elements
+                     fromNode:(nullable UIViewController *)fromNode
+                       toNode:(nullable UIViewController *)toNode NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The React views of the screens the elements are looked for in.
+@property(nonatomic, strong, readonly, nullable) UIView *leavingRoot;
+@property(nonatomic, strong, readonly, nullable) UIView *arrivingRoot;
+
+/// The view with `nativeID` in the leaving screen; nil when none has it or the id isn't one of the transition's.
+- (nullable UIView *)leavingViewWithNativeID:(nullable NSString *)nativeID;
+
+/// The view with `nativeID` in the arriving screen; nil when none has it or the id isn't one of the transition's.
+- (nullable UIView *)arrivingViewWithNativeID:(nullable NSString *)nativeID;
+
+@end
+
+/// The `nativeID` an element's option holds; nil when it holds none (not a string, an empty one).
+FOUNDATION_EXPORT NSString *_Nullable ANNNativeIDOf(Text *_Nullable value);
+
+/// The isolation of every element of the core's transitions: `work`, a step of the element named `element` (its
+/// `nativeID`, or a pair's two), runs; an exception in it skips that element only — one line in the log
+/// (`ANNElementSkipped`), and NO — while the rest of the transition plays and its command completes.
+FOUNDATION_EXPORT BOOL ANNElementStep(NSString *element, NS_NOESCAPE dispatch_block_t work);
+
+/// The line in the log for the element named `element`, skipped for `reason`: it shows and hides with its screen.
+FOUNDATION_EXPORT void ANNElementSkipped(NSString *element, NSString *reason);
+
+/// An element's animations, made in `ANNElementStep`: when making them fails, the element's values go back
+/// (`-restore`) and it doesn't move; the rest of the transition plays.
+@interface ANNIsolatedElement : NSObject <ANNFrameClient>
+
+- (instancetype)initWithClient:(id<ANNFrameClient>)client
+                          name:(NSString *)name NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
 @end
 
 NS_ASSUME_NONNULL_END