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

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

@@ -29,12 +29,12 @@ The status bar sits at the top, with the camera cutout in it; the home indicator
 
 ## The safe area
 
-The safe area is where nothing covers the content: not the bars of the navigation, not the status bar, not the cutout, not the home indicator. **The navigation keeps every screen in it by default**, so a screen doesn't need its own padding:
+The safe area is where nothing covers the content: not the bars of the navigation, not the status bar, not the cutout, not the home indicator. **The navigation keeps every screen's top and sides in it by default**, so a screen doesn't need its own padding there. The bottom is not padded: the content goes down to the edge, under the home indicator, the navigation bar and a tab bar or toolbar, and a list adds `useSafeAreaInsets().bottom` to its own padding, as with `react-native-safe-area-context`.
 
 | Platform | By default |
 | --- | --- |
-| (iOS) | Every edge, except one under a bar that shows: a list goes under the top bar and keeps its rows clear itself, so the bar's glass shows the content scrolling under it. A screen with a large title leaves the top out too, and on iPhone Duo the side of the [vertical bar](#vertical-bar). |
-| (Android) | All four edges: under the status bar, out of the cutout, above the navigation bar. |
+| (iOS) | The top and the sides, but not the top under a top bar that shows: a list goes under the bar and keeps its rows clear itself, so the bar's glass shows the content scrolling under it. A screen with a large title leaves the top out too, and on iPhone Duo the side of the [vertical bar](#vertical-bar). The bottom goes under the home indicator and under a tab bar or toolbar. |
+| (Android) | The top and the sides: under the status bar, out of the cutout. The top is free under a top bar that hides on scroll and under a large title. The bottom goes under the navigation bar, when the screen draws under it (not with an opaque bar), and under the tabs only with `bottomTabs.drawBehind` or `hideOnScroll`. |
 
 > **Tip**
 >
@@ -47,6 +47,12 @@ A screen that should go under the system, such as a photo or a map, says which e
 ```ts
 s.safeArea('bottom'); // only the bottom: the photo goes under the top
 s.safeArea(); // no edge: the content goes everywhere
+s.safeArea('top', 'left', 'right', 'bottom'); // all four: a form above the home indicator
+
+// listed edges replace the default: this one loses
+// the sides; under a large title the top stays free,
+// because the list keeps clear of the bar itself
+s.safeArea('top', 'bottom');
 ```
 
 The edges for every screen of the app go in `createNavigation`, and a screen's own `safeArea` wins over them:
@@ -54,11 +60,11 @@ The edges for every screen of the app go in `createNavigation`, and a screen's o
 ```ts
 export const Navigation = createNavigation({
   // …
-  safeArea: { edges: ['top', 'bottom'] },
+  safeArea: { edges: ['top', 'left', 'right', 'bottom'] },
 });
 ```
 
-Content that keeps clear of the system itself, such as a list that scrolls under the home indicator, reads what still covers it with `useSafeAreaInsets()`. The insets are **what is left after the screen's own padding**: 0 on an edge the screen keeps, all of what covers it on an edge its content goes under. So the content adds them to its own padding, and no edge is padded twice. Here the screen keeps the top only, and the list pads its own bottom:
+Content that keeps clear of the system itself, such as a list that scrolls under the home indicator, reads what still covers it with `useSafeAreaInsets()`. The insets are **what is left after the screen's own padding**: 0 on an edge the screen keeps, all of what covers it on an edge its content goes under. So the content adds them to its own padding, and no edge is padded twice. Here the screen keeps the top and the sides by default, and the list pads its own bottom:
 
 ```tsx
 import { ScrollView } from 'react-native';
@@ -71,7 +77,7 @@ function Inbox() {
   const insets = useSafeAreaInsets();
   return (
     <ScrollView
-      contentContainerStyle={{ paddingBottom: insets.bottom }}
+      contentContainerStyle={{ paddingBottom: 16 + insets.bottom }}
     >
       {/* the rows scroll under the home indicator,
           and the last one ends above it */}
@@ -80,12 +86,11 @@ function Inbox() {
 }
 
 export const InboxScreen = defineScreen({
-  component: Inbox,
-  options: (s) => s.safeArea('top'),
+  component: Inbox, // the default edges: the top and the sides
 });
 ```
 
-On a screen that keeps the bottom edge, the default on Android and on iOS without a bar at the bottom, `insets.bottom` is 0, so the same code works there: the content is already above the home indicator. Below a top bar the top inset is 0; on a screen drawn behind the bars it is their height. On (iOS) a scroll view with `contentInsetAdjustmentBehavior="automatic"` keeps clear of the bars by itself: leave the inset out on those edges. More: [The insets and the safe area of the screen](/api/system-ui/useSafeAreaInsets#safe-area).
+On a screen that lists `'bottom'` in its edges, `insets.bottom` is 0, so the same code works there: the content is already above the home indicator. Below a top bar the top inset is 0; on a screen drawn behind the bars it is their height. On (iOS) a scroll view with `contentInsetAdjustmentBehavior="automatic"` keeps clear of the bars by itself: leave the inset out on those edges. More: [The insets and the safe area of the screen](/api/system-ui/useSafeAreaInsets#safe-area).
 
 ### The vertical bar of iPhone Duo
 
@@ -231,7 +236,7 @@ export const PhotoScreen = defineScreen({
 | Platform | The bottom |
 | --- | --- |
 | (iOS) | The home indicator. `layout.autoHideHomeIndicator` fades it out while the screen isn't touched, as in a video. `layout.deferSystemGestures` makes the first swipe on those edges go to the app, for a game or a drawing; the second swipe goes home. |
-| (Android) | The navigation bar: a handle, or three buttons. The screen goes under it, and its safe area keeps the content above it. `navigationBar` sets its `backgroundColor`, hides it with `visible: false`, or puts the screen above it with `drawBehind: false`. |
+| (Android) | The navigation bar: a handle, or three buttons. The screen goes under it, and by default so does the content; a list adds `insets.bottom`. With an opaque bar or `drawBehind: false` the screen ends above it. `navigationBar` sets its `backgroundColor`, hides it with `visible: false`, or puts the screen above it with `drawBehind: false`. |
 
 (Android) The screen goes edge to edge as the platform says: always on Android 16+ for apps targeting SDK 36, on Android 15 for SDK 35, and on every version with `edgeToEdgeEnabled=true` in `android/gradle.properties`, the default of new React Native apps.
 
@@ -249,7 +254,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');
@@ -274,7 +279,7 @@ export const Navigation = createNavigation({
 s.scrollEdgeEffect({ top: { style: 'hard' } });
 ```
 
-The effect belongs to the scroll views of the screen, so a list that mounts after the screen shows gets it the next time the screen appears. Render the list at once, and fill it when the data comes.
+The effect applies to the vertical lists and text views of the screen when it shows, so a list that mounts after the screen shows gets it the next time the screen appears. A list nested very deep in the screen's views may not get it. A list inside another vertical list, like a horizontal carousel in a feed, gets none: UIKit draws no edge effect there. Render the list at once, and fill it when the data comes.
 
 ## Keyboard shortcuts
 

package/docs-md/screen-ui/toolbar-and-fab.md

@@ -46,10 +46,10 @@ Filter sits at the leading edge and Compose at the trailing one. The buttons are
 | Item | What it does |
 | --- | --- |
 | `{ systemItem: 'flexibleSpace' }` | Takes the free width, and pushes the next buttons to the far side. |
-| `{ systemItem: 'fixedSpace' }` | A gap. On iOS 26 it also starts a new glass capsule. |
+| `{ systemItem: 'fixedSpace' }` | A gap. With the glass design it also starts a new glass capsule. |
 | `{ systemItem: 'searchField' }` | iOS 26: the search field of the screen, between the buttons. See [Search](./search#toolbar). |
 
-On iOS 26 icons next to each other share one glass capsule; a text button has one of its own, and a `badge` doesn't show in the toolbar. `visible: false` hides the toolbar with its buttons.
+With the glass design ([what it is](./top-bar#glass-design)) icons next to each other share one glass capsule; a text button has one of its own, and a `badge` doesn't show in the toolbar. `visible: false` hides the toolbar with its buttons.
 
 On iPhone with iOS 26 the floating tab bar takes the same place at the bottom. A screen with a toolbar inside [tabs](../containers/tabs) hides the tab bar with `hideBottomTabs()`.
 
@@ -75,6 +75,8 @@ A round button with a pencil floats at the bottom right; a press opens Compose.
 | `backgroundColor`, `iconColor` | Its colors. Without them, the colors of the app's Material 3 theme. |
 | `visible: false` | Hides it. |
 
+The FAB belongs to its screen. A push brings the new screen's FAB in with it and takes the old one out with the screen it covers; a pop does the same the other way, and the back gesture shows the FAB of the screen under the top with that screen. Two screens with the same `id` share one button: it stays in place while the screens move.
+
 ### Actions
 
 A FAB with `actions` opens them above it on a press, each a small FAB with its own press:

package/docs-md/screen-ui/top-bar.md

@@ -31,6 +31,10 @@ The top bar belongs to **the stack, not to a screen**: one bar for all the scree
 
 The platform draws the bar: `UINavigationBar` on (iOS), with Liquid Glass on iOS 26, and the Material 3 top app bar on (Android). Its colors come from the [theme](../architecture/theme-and-context) until a screen sets its own.
 
+## The glass design and the compatibility mode
+
+On (iOS) the look of iOS 26 (Liquid Glass) is *the glass design*, and this page and [the bar buttons](./bar-buttons) call it that. An app in the compatibility mode (`UIDesignRequiresCompatibility = YES` in Info.plist) doesn't get it: the mode applies on iOS 26, and on iOS 27 only to an app built with an SDK before iOS 27. There the bar looks and behaves as before iOS 26: a title with a subtitle as two lines only when no large title can show (with a large title the subtitle shows nowhere), no capsules (`title.glass`, `hideSharedBackground` and `group` do nothing), `style: 'prominent'` is a bold Done button, the back button shows the title of the screen below, `background.color` gives an opaque bar, and a large title is drawn in the bar. [The bottom tabs](../containers/tabs) follow the same mode.
+
 ## The title
 
 The title is the name of the screen. The subtitle is a second line under it, such as a status or a count. Both can come from the props of the screen:
@@ -84,20 +88,20 @@ s.title('Details').largeTitle({ displayMode: 'never' });
 
 ## The background and the border
 
-On iOS 26 the bar is Liquid Glass, and the content shows through it as it scrolls under. **A color takes the glass away**, so set one only when the design needs it:
+With the glass design the bar is Liquid Glass, and the content shows through it as it scrolls under. **A color takes the glass away**, so set one only when the design needs it:
 
 ```ts
 s.topBar({ background: { color: '#F3E9D2' }, noBorder: true });
 ```
 
-`background.color` colors the bar on both platforms. With a large title on iOS 26 the color goes behind the title in the list, and fills the bar once the title collapses. Under a bar with a color the list has no edge effect at the top: see [The edge of the scroll](./system-ui#scroll-edge).
+`background.color` colors the bar on both platforms. With a large title and the glass design the color goes behind the title in the list, and fills the bar once the title collapses. Under a bar with a color the list has no edge effect at the top: see [The edge of the scroll](./system-ui#scroll-edge).
 
 The other keys of the background are rarer:
 
 | Option | What it does |
 | --- | --- |
 | `background.component` | A component of `screens` drawn behind the bar, such as a gradient. It is registered as the [title component](#title-component) is. |
-| `background.translucent` | (iOS) `true`: the content shows through; Liquid Glass on iOS 26, where it is the default. `false`: a solid bar, white in the light theme and black in the dark one. |
+| `background.translucent` | (iOS) `true`: the content shows through; Liquid Glass with the glass design, where it is the default. `false`: a solid bar, white in the light theme and black in the dark one. |
 | `background.blur` | (iOS) The system's frosted blur, plainer than the glass. A `color` wins over it, and it wins over `translucent`. |
 | `scrollEdgeAppearance` | (iOS) The look of the bar while the content is at its top, with `active: true`. The bar takes its usual look once the content scrolls under it. |
 
@@ -132,7 +136,7 @@ The bar can also hide and show by itself:
 | `hideOnKeyboard` | (iOS) Hides while the keyboard shows. |
 | `animate` | `false`: hides and shows at once, without the animation. |
 
-With `hideOnScroll` the screen goes under the bar, so its rows show where the bar was. Its list keeps its first rows clear: on (iOS) with `contentInsetAdjustmentBehavior="automatic"`, on (Android) with `paddingTop: useSafeAreaInsets().top`.
+With `hideOnScroll` the screen goes under the bar, so its rows show where the bar was. Its list keeps its first rows clear: on (iOS) with `contentInsetAdjustmentBehavior="automatic"`, on (Android) with `paddingTop: useSafeAreaInsets().top`. The bottom edge is not padded by default, so the list also adds `useSafeAreaInsets().bottom` to its bottom padding (an iOS list with `contentInsetAdjustmentBehavior="automatic"` does it itself).
 
 `drawBehind: true` keeps the bar and puts the content under it, as a map or a photo under a glass bar.
 

package/docs-md/start/installation.md

@@ -126,16 +126,19 @@ In an app as the React Native template makes it, the window shows **one React vi
 
 | File | What setup does | Why |
 | --- | --- | --- |
-| `MainApplication.kt` | Extends `NavigationApplication`. | It loads React Native itself and keeps one React host for all screens. Native screens made by `codegen` are registered there, before JS opens them. |
+| `MainApplication.kt` | Extends `NavigationApplication`; keeps the template's `loadReactNative(this)` in `onCreate`, or adds it. | It keeps one React host for all screens, made after `loadReactNative(this)` loaded React Native. Native screens made by `codegen` are registered there, before JS opens them. |
 | `MainActivity.kt` | Extends `NavigationActivity`. | The activity holds the containers of the navigation instead of one React view. It gets the back press, edge-to-edge and configuration changes first. |
 | `AndroidManifest.xml` | Adds `android:enableOnBackInvokedCallback="true"` to `<application>`. | On the first screen the system plays its own animation back to the home screen as the user swipes back (predictive back). Android 16 turns it on for apps that target API 36; an app that targets less opts in here. A value the app set itself stays. See [Back to the home screen](../screen-ui/back-and-gestures#system-animation). |
-| `styles.xml` | `AppTheme` inherits `Theme.ApexNavigation`. | The bars, tabs and search are Material 3 views and take their colors from the app's theme. This one is Material 3 in neutral grays, light and dark; change any color in the same file. A theme of the app's own stays as it is. See [Android's colors](../architecture/theme-and-context#android). |
+| `styles.xml` | `AppTheme` inherits `Theme.ApexNavigation`. | The bars, tabs and search are Material 3 views and take their colors from the app's theme. This one is Material 3 in neutral grays, light and dark; change any color in the same file. A theme of the app's own stays as it is. See [Android's theme](../architecture/theme-and-context#android). |
+
+The main activity keeps the template's `android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"`. Without `orientation`, `screenSize`, `smallestScreenSize`, `screenLayout` or `uiMode` Android recreates the activity on a rotation, a resize, a fold or a light/dark switch, and every screen goes with it; `doctor` warns about it under Config changes.
 
 #### iOS files
 
 | File | What setup does | Why |
 | --- | --- | --- |
 | `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
@@ -147,8 +150,23 @@ These files are the same on both platforms.
 | `index.js` | Starts the app through the navigation. | `AppRegistry` of the package starts `createNavigation` instead of mounting one root component. |
 | `Navigation.ts` | New: shows `App` as the first screen. | The app keeps working as it was, now as the first screen of a stack. |
 | `App.tsx` | Takes out the template's ``. | React Native's `StatusBar` logs an error on iOS once the screens set the status bar. |
+| `metro.config.js` | Wraps the exported config in `withApexNavigation`. | Fast Refresh: an edit of a screen updates the running app in place, with its state, instead of reloading it. See [Fast Refresh](#fast-refresh). |
 | `navigation-env.d.ts` | New: ties the commands to the screens of `Navigation.ts`. | The commands come from the package and can't see the app's screens. This declaration links them, so names and props are checked. See [Typed commands](#typed-commands). |
 
+### Fast Refresh
+
+`setup` wraps your `metro.config.js` in `withApexNavigation`; in a new app `init` has done it. By hand:
+
+```js
+const { withApexNavigation } = require('@apexnative/navigation/metro');
+
+module.exports = withApexNavigation(mergeConfig(getDefaultConfig(__dirname), config));
+```
+
+It does two things. React Native 0.87's transformer doesn't apply React Refresh's Babel plugin (Metro no longer passes it `hot`), and without the plugin a component that its module doesn't export loses its state at every edit. And it makes the module that imports `createNavigation` accept hot updates, so an edit of the `screens` map or of the app's config updates the running app without a reload: the screens, the default options (when `theme` or `options` changed), the roots, the listeners and the link routes. What only the start reads isn't run again: the first root, `willMount`, the splash and the context. The app's module itself runs again, as a component's module does in Fast Refresh: code at its top level (an SDK's `init`, a listener added there) runs again too, so keep such code in a module of its own that doesn't change, or make it safe to run twice. The same holds for a module the app's module imports that isn't a component, such as a store: its edit runs it and the app's module again instead of reloading the app, so a store made at the top of that module is made anew while the screens that didn't run again keep the old one. Reload the app (R) after such an edit.
+
+`doctor` warns under Fast Refresh when the Metro config doesn't use it. What to write in a screen file so that its edits update in place: [Fast Refresh](../fundamentals/screens-and-props#fast-refresh).
+
 ### Typed commands
 
 `navigation.push('Details', { props })` comes from the package, and the package doesn't know the screens of your app. One declaration links them: `setup` and `init` write it in `navigation-env.d.ts` at the root of the app.
@@ -212,7 +230,7 @@ export {};
 
 | Group | What it checks |
 | --- | --- |
-| App | React Native and the New Architecture, the package, the files `setup` sets up, the entry point, React Native loaded twice, the status bar of the template, the generated code of native screens. Typed commands: `navigation-env.d.ts` there, pointing to the navigation, with its `context` line, and read by `tsconfig.json`. The splash screen made from its settings, with its logo inside the circle of Android's splash icon, and an iOS launch screen made with `UILaunchScreen` and no storyboard, which the navigation can't keep on screen. The app icon made from its settings, and an iOS icon set with no image, which the App Store refuses. |
+| App | React Native and the New Architecture, the package, the files `setup` sets up, the entry point, React Native loaded twice, the status bar of the template, the generated code of native screens. Typed commands: `navigation-env.d.ts` there, pointing to the navigation, with its `context` line, and read by `tsconfig.json`. The splash screen made from its settings, with its logo inside the circle of Android's splash icon. The app icon made from its settings, and an iOS icon set with no image, which the App Store refuses. |
 | Navigation | From the app's code. Screens: no name given twice in `screens` and the groups, and no file of the screens' folder with a `defineScreen` or `nativeScreen` that no file imports, a screen made and never added. Links: each prefix of `linking` declared on both platforms, the declarations no prefix has, a main activity that isn't `singleTask`. Screen names, in a JavaScript app only: a name that `push`, `replace`, `showModal` or `showInColumn` gives and no screen has, with its file and line. |
 | (Android) | JDK 17 in use, the Android SDK, `minSdk`, how edge-to-edge works in the app. |
 | (iOS) | Xcode 26 or newer, CocoaPods, the pods of the navigation and whether they are out of date, the iOS version of the Podfile. |

package/ios/Animations/ANNFrameDriver.h

@@ -1,27 +1,47 @@
+#import <QuartzCore/QuartzCore.h>
 #import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// What a frame driver moves: a view's properties (`ANNViewTracks`), an element, a shared element's copy. Each frame it
-/// writes its values at the time from the transition's start; past its end it holds its end values.
+/// What a frame driver moves: a view's properties (`ANNViewTracks`), an element, a shared element's copy. It gives its
+/// values for the whole transition at once, as Core Animation's animations on its layers (`ANNKeyframes`); past its end
+/// they hold its end values.
 @protocol ANNFrameClient <NSObject>
 
-/// The values at `time`, in seconds from the start of the transition.
-- (void)applyAtTime:(NSTimeInterval)time;
+/// The client's animations for a transition of `length` seconds go onto its layers, all inside the driver's
+/// transaction, so they start together.
+- (void)addAnimationsWithLength:(NSTimeInterval)length;
 
 /// The time from which the client holds its end values.
 @property(nonatomic, readonly) NSTimeInterval endTime;
 
-/// Every value the client wrote goes back as it was read before the transition (also at a cancel); a client that made
-/// views of its own removes them. Once; later calls do nothing.
+/// The client's animations go, every value it wrote goes back as it was read before the transition (also at a
+/// cancel), and a client that made views of its own removes them. Once; later calls do nothing.
 - (void)restore;
 
 @end
 
-/// The frames of one running transition: one `CADisplayLink` in the common modes of the run loop, so frames go on while
-/// a finger drags a scroll view; the time is the link's `targetTimestamp` from the start (monotonic host time). Each
-/// frame every client writes its values; once the time reached `length` and every client its end, the clients write
-/// their ends, the link stops and `done` runs once. No `CATransaction` waits. Main queue.
+/// The times a client samples its values at, in seconds from the start: 0, every 1/120 s up to `end` (wider apart for
+/// a transition over 20 s, 2400 samples at most), each of `marks` within it (a track's start and end, a swap's), `end`
+/// and `length`; ascending, without repeats. The values between two samples are linear, so a kink of a track falls on
+/// a sample.
+FOUNDATION_EXPORT NSArray<NSNumber *> *ANNSampleTimes(NSTimeInterval end, NSTimeInterval length,
+                                                      NSArray<NSNumber *> *marks);
+
+/// The animation of `keyPath` through `values` at `times` (from `ANNSampleTimes`) over `length` seconds: linear
+/// between them, holding the first value before and the last after (until it is removed). Nil for no length, and for
+/// values and times that don't pair up.
+FOUNDATION_EXPORT CAKeyframeAnimation *_Nullable ANNKeyframes(NSString *keyPath, NSArray *values,
+                                                              NSArray<NSNumber *> *times,
+                                                              NSTimeInterval length);
+
+/// The key of the core's animation of `keyPath` on a layer, for its `restore`.
+FOUNDATION_EXPORT NSString *ANNAnimationKey(NSString *keyPath);
+
+/// The frames of one running transition, in Core Animation: every client adds its animations in one transaction, which
+/// starts them together at its commit; the render server plays them, so a busy main queue no longer stops the
+/// transition. Once every animation ended (or was removed) and `length` passed, `done` runs once on the main queue.
+/// Main queue.
 @interface ANNFrameDriver : NSObject
 
 - (instancetype)initWithClients:(NSArray<id<ANNFrameClient>> *)clients
@@ -30,17 +50,37 @@ NS_ASSUME_NONNULL_BEGIN
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
 
-/// The clients write their values of time 0 now (the first frame shows the start values), and the frames start. `done`
-/// comes on a later frame, never inside this call.
+/// The clients add their animations, which start at the commit of the current transaction (the first frame shows the
+/// start values). `done` comes later, never inside this call.
 - (void)startWithDone:(dispatch_block_t)done;
 
-/// The transition stops where it is (a destroy, a reload, a newer `setRoot`): the clients write their end values, the
-/// link stops, `done` never runs. The caller restores the clients.
+/// The start of a transition that follows a gesture: the clients add their animations as `startWithDone:` does, under
+/// the time of `clock` (the transition's container), which stops. `setProgress:` shows them at a part of the length;
+/// `finishWithSpeed:` plays the rest and `rewindWithSpeed:` plays them back to the start, both in Core Animation. The
+/// other animations under `clock` stop with it. Before `done`, which comes once after either of them (never inside a
+/// call) with whether the transition finished, `clock` gets its time back; the caller restores the clients inside
+/// `done` (one commit with it), or they would show at the clock's time for a frame.
+- (void)startPausedOn:(CALayer *)clock done:(void (^)(BOOL finished))done;
+
+/// The animations show at `progress` (0 to 1) of the length. Nothing once the end plays.
+- (void)setProgress:(CGFloat)progress;
+
+/// The rest of the animations plays from where they show, `speed` times as fast as they would (1 or more).
+- (void)finishWithSpeed:(CGFloat)speed;
+
+/// The animations play back to their start, `speed` times as fast as they would (1 or more).
+- (void)rewindWithSpeed:(CGFloat)speed;
+
+/// The transition stops (a destroy, a reload, a newer `setRoot`): `done` never runs, and a stopped `clock` gets its
+/// time back. The caller restores the clients, which removes their animations, in the same commit.
 - (void)cancel;
 
-/// The frames run.
+/// The animations run.
 @property(nonatomic, readonly) BOOL isRunning;
 
+/// The seconds from the start to the end of the last client, the transition's own length at least.
+@property(nonatomic, readonly) NSTimeInterval length;
+
 @end
 
 NS_ASSUME_NONNULL_END