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

package/cli/setup/steps/sceneDelegate.js

@@ -0,0 +1,108 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const HOW_TO = `Let ANNSceneDelegate take the app's scene: it moves the navigation's window into the scene and passes the
+scene's links to the app delegate. React Native starts in ANNAppDelegate, not here.
+
+  import ApexNavigation
+  import UIKit
+
+  class SceneDelegate: ANNSceneDelegate {}
+
+A scene delegate of the app's own calls ApexNavigation.attach(to:) in scene(_:willConnectTo:options:) instead, as the
+deep links guide shows.`;
+
+const SET_UP = `import ApexNavigation
+import UIKit
+
+/// ANNSceneDelegate moves the navigation's window into the app's scene and passes the scene's links to the app delegate.
+class SceneDelegate: ANNSceneDelegate {}
+`;
+
+// React Native 0.88's template, without its spaces: the scene delegate that makes React Native's factory and starts
+// it in the scene's window.
+const TEMPLATE = `import React
+import React_RCTAppDelegate
+import ReactAppDependencyProvider
+import UIKit
+
+class SceneDelegate: RCTDefaultReactNativeFactoryDelegate, UIWindowSceneDelegate {
+  var window: UIWindow?
+  var reactNativeFactory: RCTReactNativeFactory?
+
+  func scene(
+    _ scene: UIScene,
+    willConnectTo session: UISceneSession,
+    options connectionOptions: UIScene.ConnectionOptions
+  ) {
+    guard let windowScene = scene as? UIWindowScene else {
+      return
+    }
+
+    dependencyProvider = RCTAppDependencyProvider()
+    reactNativeFactory = RCTReactNativeFactory(delegate: self)
+    window = UIWindow(windowScene: windowScene)
+
+    #if DEBUG
+    let devMenuConfiguration = RCTDevMenuConfiguration(
+      devMenuEnabled: true,
+      shakeGestureEnabled: true,
+      keyboardShortcutsEnabled: true
+    )
+    reactNativeFactory?.devMenuConfiguration = devMenuConfiguration
+    #endif
+
+    reactNativeFactory?.startReactNative(
+      withModuleName: "",
+      in: window,
+      connectionOptions: connectionOptions
+    )
+  }
+
+  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+    RCTLinkingManager.scene(scene, openURLContexts: URLContexts)
+  }
+
+  func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
+    RCTLinkingManager.scene(scene, continue: userActivity)
+  }
+
+  override func bundleURL() -> URL? {
+    #if DEBUG
+    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+    #else
+    Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+    #endif
+  }
+}
+`;
+
+/**
+ * The text without its spaces and the app's name, to compare with the template.
+ * @param {string} text
+ */
+function shape(text) {
+  return text.replace(/withModuleName:\s*"[^"]*"/, 'withModuleName:""').replace(/\s+/g, '');
+}
+
+/**
+ * SceneDelegate.swift of React Native 0.88 and newer: the scene delegate becomes an ANNSceneDelegate, since
+ * ANNAppDelegate starts React Native and owns the window. Only the template's file changes; one with code of the app's
+ * own is changed by hand.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planSceneDelegate(text) {
+  if (
+    /class\s+\w+\s*:\s*ANNSceneDelegate\b/.test(text) ||
+    /\bApexNavigation\.attach\s*\(/.test(text)
+  )
+    return { status: 'done', note: 'already set up' };
+  if (shape(text) !== shape(TEMPLATE))
+    return { status: 'manual', note: 'changed by hand, see below', howTo: HOW_TO };
+  return { status: 'change', next: SET_UP, note: 'ANNSceneDelegate' };
+}
+
+module.exports = { planSceneDelegate };

package/docs-md/architecture/transitions.md

@@ -46,6 +46,8 @@ navigation.showModal('Player', {
 });
 ```
 
+The top bar of a pushed screen goes with the screen on Android and stays in place on iOS: see [the bar in a transition of your own](#custom-bar).
+
 `presentation` of `createNavigation` gives every push or modal of the app its transition: see [Defaults for the whole app](../fundamentals/moving-between-screens#presentation). New roots have presets of their own: see [How a new root comes in](../fundamentals/switching-roots#transitions).
 
 ## Transitions out of a view
@@ -78,7 +80,7 @@ navigation.push('Person', {
 });
 ```
 
-The avatar of the row moves and grows into the photo of the profile, and the name into its larger title. The views can differ in size and style. `type` and `duration` next to `shared` change how the rest of the screen comes, `'fade'` by default.
+The avatar of the row moves and grows into the photo of the profile, and the name into its larger title. The views can differ in size and style. A pair that isn't found is skipped (the transition waits for it first); one that fails on the way is skipped with a warning in the log. Either way its views show with their screens, and the other pairs move. `type` and `duration` next to `shared` change how the rest of the screen comes, `'fade'` by default.
 
 Both platforms. (Android) The next screen waits until it is drawn, so its views are there to move into; a `type` other than a fade gives way to a fade.
 
@@ -146,6 +148,10 @@ Details rises 300 points as it fades in. Each property animates from a value to
 
 The same goes for `pop`, `showModal`, `dismissModal`, `setStackRoot` and `setRoot`. The swipe back is the exception: (iOS) it always follows the finger with the system's slide, so a custom `pop` plays for the back button and `pop()` only.
 
+### The top bar
+
+The top bar goes its platform's way in a preset or an animation of your own. (Android) It goes with its screen, as if it were part of it: with `slideUp` the new screen comes up with its bar over the old one and its bar, and on the way back it goes down with its bar, uncovering the bar below. With `fade` or `scale` the bar fades or grows with its screen. (iOS) UIKit keeps the bar in place and changes its title and buttons as the transition starts; only the screens under it move.
+
 ## Which to pick
 
 | The move | Pick | What it costs |

package/docs-md/containers/modals.md

@@ -70,6 +70,8 @@ navigation.showModal('Compose', { style: 'fullScreen' });
 
 Without `style`, a modal is a sheet on (iOS) and covers the whole screen on (Android).
 
+`'pageSheet'` and `'formSheet'` are sheets on both platforms: on (Android) the Material bottom sheet over the dimmed screen, at the full height under the status bar and at most 640 dp wide. `'fullScreen'` and `'overFullScreen'` come up from the bottom over the whole screen; on Android with the system's motion of a window opening over another, without a fade.
+
 `'overFullScreen'` keeps the screen under the modal in place, so it shows through wherever the modal draws nothing: a dialog of your own, a card over a dimmed app. Give the modal's screen `backgroundColor('transparent')` in its options, so its own background doesn't hide the screen under it.
 
 ### A form on iPad
@@ -83,7 +85,7 @@ navigation.showModal('EditProfile', {
 });
 ```
 
-On iPhone a form sheet is a sheet, and `contentSize` does nothing.
+On iPhone and on Android a form sheet is a sheet, and `contentSize` does nothing.
 
 ### A popover
 
@@ -95,7 +97,7 @@ navigation.showModal('Filters', {
 });
 ```
 
-On iPhone it becomes a sheet, unless `adaptive: false` keeps it a popover. (Android) has no popovers: the modal covers the whole screen, as without `style`.
+On iPhone it becomes a sheet, unless `adaptive: false` keeps it a popover. (Android) has no popovers: the modal is the bottom sheet of `'pageSheet'`.
 
 ## Sheets
 

package/docs-md/containers/overlays.md

@@ -24,7 +24,9 @@ This page answers:
 
 A push or a modal moves the user somewhere. An overlay doesn't move anyone: it puts a screen **on top of everything**, and the app goes on under it.
 
-An overlay is a screen of `screens` like any other: a component, its props, its options. It shows above the tabs, the bars and the modals; on (iOS) it is in a window of its own. Its background is transparent, so the app shows wherever the overlay draws nothing. What overlays are for:
+An overlay is a screen of `screens` like any other: a component, its props, its options. It shows above the tabs, the bars and the modals; on (iOS) it is in a window of its own. Its background is transparent, so the app shows wherever the overlay draws nothing.
+
+An overlay covers the whole window, **the status bar included**: a dialog's dimmed backdrop dims the status bar too, as a system dialog does. Its safe area keeps the content off the bars, so a toast at the top of the overlay sits below the status bar. On (Android) a status bar with a color of its own (`statusBar.backgroundColor`) stays over the backdrop, and `statusBar.drawBehind: false` starts the overlay below the status bar. What overlays are for:
 
 ## Showing and closing
 

package/docs-md/containers/side-menu.md

@@ -74,7 +74,7 @@ A tap on the button opens the menu. A button of the options gets the navigation
 
 ## A pick in the menu
 
-A menu is a screen without a stack, so **its commands act on the center**, and the menu closes once the center has changed. A pick usually switches the section, so the center starts over with it:
+A menu is a screen without a stack, so **its commands act on the center**, and the menu closes as the center changes: it starts to slide away at the tap, and a push slides in as it goes. The command resolves once both are done. A pick usually switches the section, so the center starts over with it:
 
 ```tsx
 import { Button, View } from 'react-native';
@@ -94,7 +94,7 @@ function Menu() {
 }
 ```
 
-A tap on Settings shows Settings in the center, and the menu closes. Which command to use depends on the way back:
+A tap on Settings closes the menu and shows Settings in the center as it goes. Which command to use depends on the way back:
 
 | From the menu | The center |
 | --- | --- |
@@ -108,6 +108,8 @@ A tap on Settings shows Settings in the center, and the menu closes. Which comma
 | (iOS) | Over the content, which dims: `openMode: 'aboveContent'` of the side, the default. Or under it, with the content moved aside: `'pushContent'`. Then `animation(…)` says how the menu appears: `'parallax'`, `'slide'`, `'slide-and-scale'` or `'door'`. |
 | (Android) | The drawer of the platform: over the content, which dims. |
 
+The menu's color is its screen's `layout.backgroundColor`: it fills the whole height of the menu, behind the status bar and the navigation bar, while the menu's content keeps clear of them. A background on the React content stops at the safe area.
+
 `.ios()` keeps the settings that only iOS has apart from the others:
 
 ```ts

package/docs-md/containers/tabs.md

@@ -90,6 +90,8 @@ This is the app's `navigation`: its `push` goes to the stack the user sees, now
 
 Inbox shows, and Chat comes in over it, in the stack of the Inbox tab.
 
+On (Android) the content changes with Material's fade through, as in the system's Phone app: the tab that goes fades out, then the new one fades in and grows to its size, in 300 ms; the tab bar stays. On (iOS) the new tab shows at once, as the system's tab bar does.
+
 ### A press on a tab
 
 A second tap on the selected tab is a convention of both platforms: **back to the start of the tab**. The navigation does it without code:

package/docs-md/flows/forms-in-a-modal.md

@@ -299,7 +299,7 @@ navigation.showModal('EditProfile', {
 });
 ```
 
-On iPhone a form sheet is the same sheet as before, and on Android the modal is unchanged.
+On iPhone a form sheet is the same sheet as before. On Android it is the Material bottom sheet, where the modal without a style covered the whole screen.
 
 ## The whole code
 

package/docs-md/guides/deep-links.md

@@ -522,57 +522,39 @@ The launch link is read once per launch of the app, and the cases differ:
 
 ## An app with its own scene delegate
 
-(iOS) `ANNAppDelegate` gives the app's scene `ANNSceneDelegate`, which moves the navigation's window into the scene and passes the scene's links on. An app whose `Info.plist` names a scene delegate of its own does both itself. The links that launched the app come with the options of `scene(_:willConnectTo:options:)`, and they count as the launch link when they're passed on in that same call, with the window moved into the scene:
+(iOS) `ANNAppDelegate` gives the app's scene `ANNSceneDelegate`, which moves the navigation's window into the scene and passes the scene's links on: to the app delegate's methods, then to `Linking`. An app whose `Info.plist` names a scene delegate of its own, as React Native 0.88's template does, extends `ANNSceneDelegate`; a method it overrides calls `super`:
 
 ```swift
 import ApexNavigation
 import UIKit
 
-class SceneDelegate: UIResponder, UIWindowSceneDelegate {
-  var window: UIWindow?
-
-  func scene(
+class SceneDelegate: ANNSceneDelegate {
+  override func scene(
     _ scene: UIScene,
     willConnectTo session: UISceneSession,
     options connectionOptions: UIScene.ConnectionOptions
   ) {
-    guard let windowScene = scene as? UIWindowScene else { return }
-    window = ApexNavigation.attach(to: windowScene)
-    // The links that launched the app: passed on in this same
-    // call, so the first root can come from one of them.
-    for context in connectionOptions.urlContexts {
-      openLink(context.url)
-    }
-    for activity in connectionOptions.userActivities {
-      if let url = activity.webpageURL { openLink(url) }
-    }
+    // Moves the window into the scene and passes on the links
+    // that launched the app.
+    super.scene(scene, willConnectTo: session, options: connectionOptions)
+    window?.tintColor = .systemIndigo
   }
 
-  // Links while the app runs.
-  func scene(
+  override func scene(
     _ scene: UIScene,
     openURLContexts URLContexts: Set<UIOpenURLContext>
   ) {
-    for context in URLContexts {
-      openLink(context.url)
-    }
-  }
-
-  func scene(
-    _ scene: UIScene,
-    continue userActivity: NSUserActivity
-  ) {
-    if let url = userActivity.webpageURL { openLink(url) }
-  }
-
-  private func openLink(_ url: URL) {
-    let app = UIApplication.shared.delegate as? ANNAppDelegate
-    app?.dispatchDeepLinkURL(url)
+    print("Opened:", URLContexts.map(\.url))
+    super.scene(scene, openURLContexts: URLContexts)
   }
 }
 ```
 
-`ApexNavigation.attach(to:)` is `attachToWindowScene:` in Objective-C.
+`super` passes each link on with its scene: React Native 0.88 and newer take a scene's links only with it. `setup` turns the scene delegate of React Native 0.88's template into `class SceneDelegate: ANNSceneDelegate {}`.
+
+A scene delegate that extends another class calls `ApexNavigation.attach(to:)` (`attachToWindowScene:` in Objective-C) in `scene(_:willConnectTo:options:)` and passes the URLs to `dispatchDeepLinkURL(_:)` of the app delegate.
+
+A link the app dispatches itself with `dispatchDeepLinkURL(_:)`, such as the link of a push notification, comes with no scene. Where React Native's `Linking` doesn't take it from the native side (React Native 0.88 and newer, in an app with a scene delegate), the navigation hands it to `Linking` from JavaScript, as a `url` event like any other.
 
 ## Testing
 

package/docs-md/help/glossary.md

@@ -266,7 +266,7 @@ Two screens shown as one entry of a stack: the primary, whose bar shows, and the
 
 ### Popover
 
-(iPadOS) A modal that points at the bar button or the view that opened it. On iPhone it becomes a sheet; on Android the modal covers the screen. More: [A popover](../containers/modals#popover).
+(iPadOS) A modal that points at the bar button or the view that opened it. On iPhone and on Android it becomes a sheet. More: [A popover](../containers/modals#popover).
 
 ### Presentation
 

package/docs-md/index.json

@@ -974,6 +974,10 @@
         "heading": "The system back of Android",
         "anchor": "system-back"
       },
+      {
+        "heading": "The preview of a pop",
+        "anchor": "pop-preview"
+      },
       {
         "heading": "Back to the home screen",
         "anchor": "system-animation"
@@ -1323,6 +1327,10 @@
         "heading": "Animations of your own",
         "anchor": "custom"
       },
+      {
+        "heading": "The top bar",
+        "anchor": "custom-bar"
+      },
       {
         "heading": "Which to pick",
         "anchor": "which"

package/docs-md/screen-ui/back-and-gestures.md

@@ -100,6 +100,12 @@ export const MapScreen = defineScreen({
 | The first screen of a tab | What `Tabs().backBehavior(…)` says: leave the app, go to the first tab, or to the tab before. See [Back on Android](../containers/tabs#back). |
 | The first screen of the app | Leaves the app, as every Android app does, with the system's own animation ([below](#system-animation)). `usePreventLeave` doesn't hold it; to ask first, see [Asking before the user leaves the app](/api/back-and-gestures/usePreventLeave#leaving-the-app). |
 
+### The preview of a pop
+
+(Android) 14+ The back gesture on a pushed screen shows where it goes before the user lets go, as the system does between apps' screens: the screen shrinks toward the side of the swipe with rounded corners and follows the finger, and the screen under it shows behind it, dimmed, with its own bar. Letting go pops the screen; swiping back cancels, and the screen grows back into place.
+
+The preview shows when back pops the screen with the default transition. It doesn't when back does something else first, or when the app takes it: a menu or a search that closes, a screen that holds back (`hardwareBackButton.popStackOnPress: false`, a [`BackHandler` listener](#back-handler), `usePreventLeave`), or a pop with an animation of its own (`animations.pop`). On Android 13 and older the screen pops when the swipe ends.
+
 ### Back to the home screen
 
 (Android) On the first screen of the app, with nothing left to go back to, the navigation leaves the back to the system. The system then plays its predictive back animation: as the user swipes, the app shrinks and the home screen shows behind it, and the user can still change their mind halfway. The system decides this as the swipe starts, so the navigation takes the back only while it has something to do with it: a screen to pop, a modal, a menu or a search to close, a tab to go to (`backBehavior`), or a [`BackHandler` listener](#back-handler) of the app.

package/docs-md/screen-ui/system-ui.md

@@ -249,7 +249,7 @@ iPhone Duo decides by itself too: folded, the outer display shows the app in por
 
 ## Backgrounds
 
-`backgroundColor` colors the screen, behind its React content. Without it, the screen has the background of the [theme](../architecture/theme-and-context).
+`backgroundColor` colors the screen, behind its React content. Without it, the screen has the background of the [theme](../architecture/theme-and-context), or the system's when the theme has none: `systemBackground` on (iOS), `android:colorBackground` of the app's theme on (Android) (a screen in a sheet shows the sheet's surface; a native screen paints its own view). So a React screen is never see-through by accident; `'transparent'` makes it so on purpose, as overlays are.
 
 ```ts
 s.backgroundColor('#F3E9D2');

package/docs-md/start/installation.md

@@ -136,6 +136,7 @@ In an app as the React Native template makes it, the window shows **one React vi
 | File | What setup does | Why |
 | --- | --- | --- |
 | `AppDelegate.swift` | Extends `ANNAppDelegate`. | It creates the window, puts the root of the navigation in it and starts React Native. Deep links that come before JS is ready wait for it. |
+| `SceneDelegate.swift` | Extends `ANNSceneDelegate`. React Native 0.88 and newer only: the earlier templates have no scene delegate. | The template's scene delegate would start React Native a second time. `ANNSceneDelegate` moves the navigation's window into the app's scene and passes the scene's links to the app delegate. |
 | `Info.plist` | Sets `UIViewControllerBasedStatusBarAppearance` to `true`. | Each screen sets its own status bar from its options; with `false`, only the app as a whole can. |
 
 #### JavaScript files

package/ios/Animations/ANNTransitionAnimator.mm

@@ -133,19 +133,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) {
@@ -200,8 +197,13 @@ 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 frame fails goes back and stops, 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];

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 frames, each in `ANNElementStep`: after a frame that fails, the element's values go back
+/// (`-restore`), and it gets no frame more.
+@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