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

package/ios/Options/Params/Image.mm

@@ -1,13 +1,46 @@
 #import "Image.h"
+#import "ANNOptionImages.h"
 
 @implementation Image
 
+- (ANNImageSource *)source {
+    id value = self.value;
+    return [value isKindOfClass:ANNImageSource.class] ? value : nil;
+}
+
 - (UIImage *)get {
-    return [super get];
+    id value = self.value;
+    if ([value isKindOfClass:UIImage.class]) {
+        return value;
+    }
+    ANNImageSource *source = self.source;
+    return source ? [ANNOptionImages imageOf:source] : nil;
+}
+
+- (BOOL)isSameValueAs:(ANNParam *)other {
+    if (other == self) {
+        return YES;
+    }
+    if (other.class != self.class) {
+        return NO;
+    }
+    ANNImageSource *source = self.source;
+    ANNImageSource *otherSource = ((Image *)other).source;
+    if (source || otherSource) {
+        return [source.sourceKey isEqualToString:otherSource.sourceKey];
+    }
+    return self.value == other.value;
+}
+
+- (NSUInteger)valueHash {
+    ANNImageSource *source = self.source;
+    return source ? source.sourceKey.hash : (NSUInteger)(__bridge void *)self.value;
 }
 
+// A source that doesn't load is no image: the default then, as without a value.
 - (UIImage *)withDefault:(UIImage *)defaultValue {
-    return [super withDefault:defaultValue];
+    UIImage *image = self.hasValue ? self.get : nil;
+    return image ?: defaultValue;
 }
 
 @end

package/ios/Options/Params/ImageParser.h

@@ -2,11 +2,11 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// Reads `key` of the options' JSON as an image and loads it at once, on the main queue: `{ system, fallback? }` is an
-/// SF Symbol, else the fallback source; a source (a string, or an object with `uri`, `bundle`, `scale`, `width`,
-/// `height` and Metro's asset flag) loads a file, an asset of the app's bundle, a `data:` address, or in development a
-/// Metro asset. Remote addresses and arrays of sources are not loaded. A failure is no image and an error in the React
-/// Native log; it never throws.
+/// Reads `key` of the options' JSON as the source of an image, which loads when an element shows it (`Image`):
+/// `{ system, fallback? }` is an SF Symbol, else the fallback source; a source (a string, or an object with `uri`,
+/// `bundle`, `scale`, `width`, `height` and Metro's asset flag) is a file, an asset of the app's bundle, a `data:`
+/// address, or in development a Metro asset. Remote addresses and arrays of sources are no image, with an error in the
+/// React Native log; it never throws.
 @interface ImageParser : NSObject
 
 + (Image *)parse:(nullable NSDictionary *)json key:(NSString *)key;

package/ios/Options/Params/ImageParser.mm

@@ -2,7 +2,6 @@
 #import "ANNOptionsReader.h"
 #import <React/RCTConvert.h>
 #import <React/RCTLog.h>
-#import <React/RCTUtils.h>
 
 @implementation ImageParser
 
@@ -12,10 +11,10 @@
         return [[Image alloc] initWithValue:nil];
     }
     NSString *path = [ANNOptionsReader pathOfKey:key];
-    return [[Image alloc] initWithValue:[self imageOf:value path:path]];
+    return [[Image alloc] initWithValue:[self sourceOf:value path:path]];
 }
 
-+ (UIImage *)imageOf:(id)value path:(NSString *)path {
++ (ANNImageSource *)sourceOf:(id)value path:(NSString *)path {
     if ([value isKindOfClass:NSArray.class]) {
         RCTLogError(@"[ApexNavigation] the image of '%@' is a list of sources, which options don't support: give "
                     @"one source",
@@ -23,27 +22,28 @@
         return nil;
     }
     if ([value isKindOfClass:NSDictionary.class] && value[@"system"]) {
-        return [self systemImageOf:value path:path];
+        return [self symbolOf:value path:path];
     }
     if (![value isKindOfClass:NSString.class] && ![value isKindOfClass:NSDictionary.class]) {
         return nil;
     }
-    return [self imageOfSource:value path:path];
+    return [self addressOf:value path:path];
 }
 
 // An SF Symbol; a name the system doesn't have takes the fallback source, read the same way.
-+ (UIImage *)systemImageOf:(NSDictionary *)value path:(NSString *)path {
++ (ANNImageSource *)symbolOf:(NSDictionary *)value path:(NSString *)path {
     id name = value[@"system"];
-    UIImage *image = [name isKindOfClass:NSString.class] ? [UIImage systemImageNamed:name] : nil;
-    if (image) {
-        return image;
-    }
     id fallback = value[@"fallback"];
-    return fallback && fallback != NSNull.null ? [self imageOf:fallback path:path] : nil;
+    ANNImageSource *fallbackSource =
+        fallback && fallback != NSNull.null ? [self sourceOf:fallback path:path] : nil;
+    if (![name isKindOfClass:NSString.class] || [name length] == 0) {
+        return fallbackSource;
+    }
+    return [ANNImageSource symbolNamed:name fallback:fallbackSource];
 }
 
-// A resolved source, loaded synchronously as React Native's converter of images does, with the scale of the source.
-+ (UIImage *)imageOfSource:(id)source path:(NSString *)path {
+// A resolved source: its address and the fields its scale comes from.
++ (ANNImageSource *)addressOf:(id)source path:(NSString *)path {
     NSDictionary *fields = [source isKindOfClass:NSDictionary.class] ? source : nil;
     id address = fields ? (fields[@"uri"] ?: fields[@"url"]) : source;
     if (![address isKindOfClass:NSString.class] || [address length] == 0) {
@@ -56,48 +56,30 @@
     }
     NSURL *url = [RCTConvert NSURL:address];
     NSString *scheme = url.scheme.lowercaseString;
-    BOOL metroAsset = ANNJSONIsBoolean(fields[@"__packager_asset"]) && [fields[@"__packager_asset"] boolValue];
-    UIImage *image = nil;
+    id packagerAsset = fields[@"__packager_asset"];
+    BOOL metroAsset = ANNJSONIsBoolean(packagerAsset) && [packagerAsset boolValue];
+    ANNImageSourceKind kind;
     if ([scheme isEqualToString:@"file"]) {
-        image = RCTImageFromLocalAssetURL(url) ?: RCTImageFromLocalBundleAssetURL(url);
+        kind = ANNImageSourceKindFile;
     } else if ([scheme isEqualToString:@"data"]) {
-        image = [UIImage imageWithData:[NSData dataWithContentsOfURL:url]];
+        kind = ANNImageSourceKindData;
     } else if (([scheme isEqualToString:@"http"] || [scheme isEqualToString:@"https"]) && metroAsset) {
-        // Metro's assets in development: loaded from the dev server, synchronously.
-        image = [UIImage imageWithData:[NSData dataWithContentsOfURL:url]];
+        kind = ANNImageSourceKindMetro;
     } else {
         RCTLogError(@"[ApexNavigation] the image of '%@' is not loaded: remote images are not supported in options "
                     @"(%@)",
                     path, address);
         return nil;
     }
-    if (!image) {
-        RCTLogError(@"[ApexNavigation] the image of '%@' could not be loaded: %@", path, address);
-        return nil;
-    }
-    return [self image:image scaledBy:fields];
-}
-
-// The scale of the source; without it the pixel width over `width`; without both, the file's own. A size that
-// doesn't match is only logged.
-+ (UIImage *)image:(UIImage *)image scaledBy:(NSDictionary *)fields {
-    id scaleValue = fields[@"scale"];
-    id widthValue = fields[@"width"];
-    id heightValue = fields[@"height"];
-    CGFloat scale = ANNJSONIsNumber(scaleValue) ? [scaleValue doubleValue] : 0;
-    CGFloat width = ANNJSONIsNumber(widthValue) ? [widthValue doubleValue] : 0;
-    CGFloat height = ANNJSONIsNumber(heightValue) ? [heightValue doubleValue] : 0;
-    if (scale <= 0 && width > 0 && image.CGImage) {
-        scale = CGImageGetWidth(image.CGImage) / width;
-    }
-    if (scale > 0 && image.CGImage && scale != image.scale) {
-        image = [UIImage imageWithCGImage:image.CGImage scale:scale orientation:image.imageOrientation];
-    }
-    if (width > 0 && height > 0 && !CGSizeEqualToSize(image.size, CGSizeMake(width, height))) {
-        RCTLogInfo(@"[ApexNavigation] an image of the options is %@, its source says %@",
-                   NSStringFromCGSize(image.size), NSStringFromCGSize(CGSizeMake(width, height)));
-    }
-    return image;
+    id scale = fields[@"scale"];
+    id width = fields[@"width"];
+    id height = fields[@"height"];
+    return [ANNImageSource sourceOfKind:kind
+                                    url:url
+                                address:address
+                                  scale:ANNJSONIsNumber(scale) ? [scale doubleValue] : 0
+                                  width:ANNJSONIsNumber(width) ? [width doubleValue] : 0
+                                 height:ANNJSONIsNumber(height) ? [height doubleValue] : 0];
 }
 
 @end

package/ios/Public/ApexNavigation/ANNSceneDelegate.h

@@ -9,6 +9,9 @@ NS_ASSUME_NONNULL_BEGIN
  * When the scene connects, the navigation window moves into it. URLs, user activities and foreground/background
  * changes that UIKit now delivers to the scene are forwarded to the app delegate's usual methods, so
  * the deep links (`dispatchDeepLinkURL:`) and app delegate overrides keep working.
+ *
+ * The app's own scene delegate can extend it (`class SceneDelegate: ANNSceneDelegate {}`, which `setup` makes of React
+ * Native 0.88's template); a method it overrides calls `super`.
  */
 @interface ANNSceneDelegate : UIResponder <UIWindowSceneDelegate>
 

package/ios/Public/ApexNavigation/ApexNavigation.h

@@ -37,7 +37,7 @@ NS_SWIFT_NAME(NativeScreenContext)
 
 /**
  * Runs a command of the navigation from this screen in JS, as `useNavigation()` of a React screen does: push, pop,
- * popTo, popToRoot, showInColumn, showModal, dismiss, showOverlay, dismissOverlay, setOptions, selectTab, setTabBadge.
+ * popTo, popToRoot, showInColumn, showModal, dismiss, showOverlay, setOptions, selectTab, setTabBadge.
  * `arguments` are those of the JS command; `completion` gets what it resolved with.
  *
  * ```swift

package/ios/RECIPES.md

@@ -16,9 +16,14 @@ you do exactly that; the map is `ios/CLAUDE.md`.
    what the merge names) and in `applyDefaultOptionsChange:`. A system-UI option also goes into
    `+[ANNSystemUI groupsNamedBy:onlyRead:]`; a bar-placement option into `ANNOptionsChangeScreenBars`.
 4. **The cache.** Never invalidate by hand. Own options change through `ANNNodeHelper` (`mergeOwnOptions:`,
-   `changeOwnOptions:`) and defaults through `+[ANNDefaultOptions setCurrent:]`; both call
-   `+[ANNOptionsCache optionsChanged]`. A presenter or module that keeps a choice of the user writes it with
-   `changeOwnOptions:`, never into the options in place.
+   `changeOwnOptions:`), the user layer through `setUserChoice:forKey:`, and defaults through
+   `+[ANNDefaultOptions setCurrent:]`; all call `+[ANNOptionsCache optionsChanged]`. `changeOwnOptions:` is for what
+   the core keeps of the app's merges. A presenter or module that keeps a choice of the user (a toggle, a menu check,
+   a scope) puts an `ANNUserChoice` into the node's user layer under a key of its own: its `apply` block writes the
+   choice by identity (a button or item by its id) on a copy, its `merged` block says when the app's merge takes it
+   away, by Android's rules (`UserChoices.yieldTo`): a value other than the app had there (the own options', else the
+   node's resolution before the merge), or what the choice is about gone from the resolution after it. Never into the
+   options in place.
 5. **Android** reads the same JSON and has unit tests of parsing and merging; the iOS side has none (see Checks in `ios/CLAUDE.md`).
 6. **The rule:** an option does what its name promises, with the same meaning on both platforms
    (`.claude/rules/general.md`, `.claude/rules/options.md`). A platform that can't, says so in the JSDoc.
@@ -34,8 +39,10 @@ you do exactly that; the map is `ios/CLAUDE.md`.
 4. **The layout check:** a new node type goes into `ANNLayoutType` and `ANNLayoutReader` (its place, its children), and
    gets a maker in `ANNLayoutFactory`.
 5. **Error texts** come from `ANNErrorTexts`, one sentence per case, the same as Android; a text deep in a maker is
-   thrown with `+[ANNErrorTexts rejection:]`.
+   thrown with `+[ANNErrorTexts rejection:]`. A new text goes into `src/interfaces/contract/errors.json`, and
+   `node scripts/contract.mjs` makes `ANNErrorTexts` (and Android's `ErrorTexts`) from it; never edit them by hand.
 6. **The answer:** end through `ANNAppearanceDispatcher` (`endTransitionHiding:…answer:value:`) or call
-   `-[ANNCommandAnswer resolve:]`; the state and `ANN.CommandCompleted` follow by themselves for the names in
-   `ANNCompletedCommandNames`. Add the name there when the command shows or dismisses.
+   `-[ANNCommandAnswer resolve:]`; the state and `ANN.CommandCompleted` follow by themselves as `ANNCommandContract`
+   says. A new command with a promise gets its entry in `src/interfaces/contract/commands.json` (what it resolves
+   with, `state`, `completed`), then `node scripts/contract.mjs`.
 7. **Android** gets the same command; its tests check the texts.

package/ios/React/ANNReactView.mm

@@ -8,29 +8,9 @@
 #import "ANNSurfaceHostingView.h"
 #import <React/RCTFabricSurface.h>
 #import <React/RCTSurfacePresenter.h>
-#import <React/RCTSurfaceStage.h>
 #import <React/RCTSurfaceView.h>
 #import <ReactCommon/RCTHost.h>
 
-// A surface that still starts can't be stopped yet: it is checked this often, at most this many times (5 s), and then
-// stopped anyway.
-static const NSTimeInterval ANNSurfaceStopCheckInterval = 0.05;
-static const NSUInteger ANNSurfaceStopCheckLimit = 100;
-
-// Stops `surface` once it runs. The block holds the surface and the view that hosts it until then: a hosting view
-// released earlier would stop the surface in its `dealloc`, maybe off the main queue.
-static void ANNStopSurfaceWhenRunning(RCTFabricSurface *surface, UIView *hostingView,
-                                      NSUInteger checksLeft) {
-    if (RCTSurfaceStageIsRunning(surface.stage) || checksLeft == 0) {
-        [surface stop];
-        return;
-    }
-    int64_t delay = (int64_t)(ANNSurfaceStopCheckInterval * NSEC_PER_SEC);
-    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, delay), dispatch_get_main_queue(), ^{
-      ANNStopSurfaceWhenRunning(surface, hostingView, checksLeft - 1);
-    });
-}
-
 @interface ANNReactView () <RCTSurfacePresenterObserver, ANNScreenReadinessListener>
 @end
 
@@ -359,14 +339,15 @@ static void ANNStopSurfaceWhenRunning(RCTFabricSurface *surface, UIView *hosting
     _reactViewReadyBlock = nil;
     _mountHandlers = nil;
     [_contentDidMountHandlers removeAllObjects];
-    RCTFabricSurface *surface = _surface;
-    if (surface) {
+    ANNSurfaceHostingView *hostingView = _hostingView;
+    if (_surface && hostingView) {
         // On the next turn of the main queue: a destroy that runs inside React Native's mounting (a wait that ends in
         // a mount, a root that replaces at once) would stop the surface there, React Native would drop its last
-        // transaction and recycle its root view with the old content still in it, to show in a later screen.
-        UIView *hostingView = _hostingView;
+        // transaction and recycle its root view with the old content still in it, to show in a later screen. The
+        // hosting view stops the surface then, or at its start when it doesn't run yet; the block keeps the hosting
+        // view, and with it the surface, until it asks.
         dispatch_async(dispatch_get_main_queue(), ^{
-          ANNStopSurfaceWhenRunning(surface, hostingView, ANNSurfaceStopCheckLimit);
+          [hostingView stopSurfaceWhenRunning];
         });
     }
 }

package/ios/React/ANNSafeAreaViewComponentView.mm

@@ -1,11 +1,14 @@
 #import "ANNSafeAreaViewComponentView.h"
-#import "ANNScreenInsets.h"
+#import "ANNScreenEnvironment.h"
 #import "ANNScreenReadiness.h"
 #import "../cpp/react/renderer/components/ApexNavigationSpec/ANNSafeAreaViewComponentDescriptor.h"
 #import <React/RCTConversions.h>
 
 using namespace facebook::react;
 
+@interface ANNSafeAreaViewComponentView () <ANNScreenPaddingListener>
+@end
+
 @implementation ANNSafeAreaViewComponentView {
     ANNSafeAreaViewShadowNode::ConcreteState::Shared _state;
     NSString *_screenId;
@@ -22,21 +25,13 @@ using namespace facebook::react;
     if (self = [super initWithFrame:frame]) {
         static const auto defaultProps = std::make_shared<const ANNSafeAreaViewProps>();
         _props = defaultProps;
-        [NSNotificationCenter.defaultCenter addObserver:self
-                                               selector:@selector(paddingDidChange:)
-                                                   name:ANNScreenSafeAreaPaddingDidChangeNotification
-                                                 object:nil];
     }
     return self;
 }
 
-- (void)dealloc {
-    [NSNotificationCenter.defaultCenter removeObserver:self];
-}
-
 - (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &)oldProps {
     const auto &newProps = static_cast<const ANNSafeAreaViewProps &>(*props);
-    _screenId = RCTNSStringFromStringNilIfEmpty(newProps.screenId);
+    [self listenToScreenId:RCTNSStringFromStringNilIfEmpty(newProps.screenId)];
     // The screen's readiness comes from this view, never from its root's children.
     if (_screenId != nil) {
         [ANNScreenReadiness screenHasSafeAreaView:_screenId];
@@ -70,18 +65,33 @@ using namespace facebook::react;
     [self applyPadding];
 }
 
-- (void)paddingDidChange:(NSNotification *)notification {
-    if ([notification.object isEqual:_screenId]) {
-        [self applyPadding];
+// The view hears the padding changes of its screen only. It listens before it applies the padding it has, at each
+// props, so a change between the two can't be missed.
+- (void)listenToScreenId:(nullable NSString *)screenId {
+    if ((screenId == nil && _screenId == nil) || [screenId isEqualToString:_screenId]) {
+        return;
+    }
+    if (_screenId != nil) {
+        [ANNScreenEnvironment removePaddingListener:self forScreenId:_screenId];
+    }
+    _screenId = screenId;
+    if (screenId != nil) {
+        [ANNScreenEnvironment addPaddingListener:self forScreenId:screenId];
     }
 }
 
+#pragma mark - ANNScreenPaddingListener
+
+- (void)screenPaddingDidChange {
+    [self applyPadding];
+}
+
 // The padding of the screen goes to the state, which lays the view out with it.
 - (void)applyPadding {
     if (_state == nullptr || _screenId == nil) {
         return;
     }
-    UIEdgeInsets padding = [ANNScreenInsets paddingForScreenId:_screenId];
+    UIEdgeInsets padding = [ANNScreenEnvironment paddingForScreenId:_screenId];
     EdgeInsets insets{.left = (Float)padding.left,
                       .top = (Float)padding.top,
                       .right = (Float)padding.right,
@@ -118,8 +128,8 @@ using namespace facebook::react;
 
 // The screen renders its content once this view is laid out in its place with a size, as
 // react-native-safe-area-context does: a list that is there before the first layout of the top bar
-// makes UIKit start the large title collapsed. The preload window of tabs attached together has no
-// size: a tab renders its content where it shows.
+// makes UIKit start the large title collapsed. A tab rendered before it shows lays out in the
+// tabs' view, unseen, and renders its content there.
 - (void)sendReadyIfLaidOut {
     if (_readySent || _eventEmitter == nullptr || self.superview == nil) {
         return;
@@ -144,7 +154,8 @@ using namespace facebook::react;
 - (void)prepareForRecycle {
     [super prepareForRecycle];
     _state.reset();
-    _screenId = nil;
+    // A recycled view gets its next screen's id with its next props.
+    [self listenToScreenId:nil];
     _readySent = NO;
     _contentRenderedSent = NO;
     _contentRendered = NO;

package/ios/React/ANNSurfaceHostingView.h

@@ -8,10 +8,24 @@ NS_ASSUME_NONNULL_BEGIN
 /// every change on.
 @interface ANNSurfaceHostingView : RCTSurfaceHostingView
 
+/// A size transition of the window (a rotation, a new window size) runs until its coordinator completes. Meanwhile React
+/// content takes its new size without animation (`layOutContent:`). Each call ends with its own transition; main queue.
++ (void)followSizeTransition:(id<UIViewControllerTransitionCoordinator>)coordinator;
+
+/// Runs a layout that gives React content a new size: without animation while a size transition runs, as it is
+/// otherwise. Main queue.
++ (void)layOutContent:(void (^)(void))layout;
+
 /// Called at each mount of the hosted surface: after a change of the surface's size, the first one lays the surface
 /// out again, so a render that was on its way during the change doesn't keep the old size's layout.
 - (void)surfaceDidMount;
 
+/// The screen went: the hosted surface stops as soon as it runs, on the main queue. A surface that runs already stops
+/// at once; one that doesn't run yet stops at its change to running (`surface:didChangeStage:`). Until then this view
+/// and its surface are kept, so the core gives them up on the main queue. A surface that hasn't started after 5 s is
+/// let go, and stops if it ever starts later. Once; main queue.
+- (void)stopSurfaceWhenRunning;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/React/ANNSurfaceHostingView.mm

@@ -1,9 +1,52 @@
 #import "ANNSurfaceHostingView.h"
+#import "ANNAssert.h"
 #import <React/RCTFabricSurface.h>
+#import <objc/runtime.h>
+
+// How long a gone screen's surface that doesn't run yet is kept for its stop. The host starts a surface through a weak
+// reference once its JavaScript ran, so a surface let go before that, which nothing else holds, goes away unstarted.
+static const NSTimeInterval ANNSurfaceStartWaitLimit = 5.0;
+static const void *ANNSurfaceStopperKey = &ANNSurfaceStopperKey;
+
+// The hosting views whose surface stops at its start; each keeps its surface. Main queue.
+static NSMutableSet<ANNSurfaceHostingView *> *ANNHostingViewsStoppingAtStart;
+
+// The size transitions of the window that run now. Main queue.
+static NSInteger ANNSizeTransitionCount;
+
+// The delegate of a surface its hosting view let go at the limit: the surface keeps it, and it keeps nothing, so
+// neither holds the other alive. A surface that something else still starts (a start already on its way holds its
+// surface; React Native restarts every surface it knows after a reload, holding it) stops at once, instead of running
+// with no screen and going away running, which leaves its React tree registered.
+@interface ANNSurfaceStopper : NSObject <RCTSurfaceDelegate>
+@end
+
+@implementation ANNSurfaceStopper
+
+// React Native's delegate method names the deprecated `RCTSurface`; the surface is an `RCTFabricSurface`.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated"
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+- (void)surface:(RCTSurface *)surface didChangeStage:(RCTSurfaceStage)stage {
+    if (!RCTSurfaceStageIsRunning(stage)) {
+        return;
+    }
+    // The start tells this off the main queue, before it ends: the stop goes on the main queue, the block keeping the
+    // surface until then.
+    id<RCTSurfaceProtocol> startedSurface = (id<RCTSurfaceProtocol>)surface;
+    dispatch_async(dispatch_get_main_queue(), ^{
+      [startedSurface stop];
+    });
+}
+#pragma clang diagnostic pop
+
+@end
 
 @implementation ANNSurfaceHostingView {
     // The surface was given a new size since its last mount.
     BOOL _surfaceSizeChanged;
+    // The screen went: the surface stops each time it runs. Main queue.
+    BOOL _stopsWhenRunning;
 }
 
 // React Native 0.87 posts the hosting view's traits as the app's scheme from here (`RCTSurfaceHostingView.mm`). On
@@ -20,6 +63,28 @@
 
 #pragma mark - The surface's size
 
+// UIKit lays the screens out inside the animation of a rotation or a new window size, and React Native commits and
+// mounts the new layout synchronously inside the layout that gives it the size: every frame of its views animated
+// from the old size to the new one, and what a view draws itself (an SVG, a glass view, text) was drawn once at the new
+// size and stretched along that animation. During such a transition the content takes its new layout at once; the
+// hosting view itself still follows the animation. Other animated size changes (a sheet's detent, a split view's
+// column) keep the content's frames animated, so content pinned to the moving edge rides along with it.
++ (void)followSizeTransition:(id<UIViewControllerTransitionCoordinator>)coordinator {
+    ANNSizeTransitionCount++;
+    [coordinator animateAlongsideTransition:nil
+                                 completion:^(id<UIViewControllerTransitionCoordinatorContext> context) {
+                                   ANNSizeTransitionCount--;
+                                 }];
+}
+
++ (void)layOutContent:(void (^)(void))layout {
+    if (ANNSizeTransitionCount > 0) {
+        [UIView performWithoutAnimation:layout];
+    } else {
+        layout();
+    }
+}
+
 // React Native gives the surface its size here. A size change is noted for the next mount (see below). The note is
 // put aside during the call: the change's own commit mounts inside it and must not take an earlier note, or a size
 // that changes every frame (a sheet dragged between detents, a window resized) would lay out three times a frame. A
@@ -30,7 +95,9 @@
     CGSize maximumSize = surface.maximumSize;
     BOOL sizeChangedBefore = _surfaceSizeChanged;
     _surfaceSizeChanged = NO;
-    [super layoutSubviews];
+    [ANNSurfaceHostingView layOutContent:^{
+      [super layoutSubviews];
+    }];
     BOOL sizeChanged = surface && (!CGSizeEqualToSize(minimumSize, surface.minimumSize) ||
                                    !CGSizeEqualToSize(maximumSize, surface.maximumSize));
     _surfaceSizeChanged = sizeChanged || sizeChangedBefore;
@@ -60,6 +127,82 @@
     [surface setMinimumSize:minimumSize maximumSize:maximumSize];
 }
 
+#pragma mark - The stop
+
+// `RCTFabricSurface stop` does nothing while the surface doesn't run, and the host starts a surface later, off the main
+// queue: a screen can go before that. Its surface then stops at its change to running. This view is kept until then,
+// with its surface: released earlier, it would stop the surface in its `dealloc`, maybe off the main queue.
+- (void)stopSurfaceWhenRunning {
+    ANNAssertMainQueue();
+    if (_stopsWhenRunning) {
+        return;
+    }
+    _stopsWhenRunning = YES;
+    RCTFabricSurface *surface = [self fabricSurface];
+    if (!surface) {
+        return;
+    }
+    if (RCTSurfaceStageIsRunning(surface.stage)) {
+        [surface stop];
+        return;
+    }
+    if (!ANNHostingViewsStoppingAtStart) {
+        ANNHostingViewsStoppingAtStart = [NSMutableSet new];
+    }
+    [ANNHostingViewsStoppingAtStart addObject:self];
+    __weak ANNSurfaceHostingView *weakSelf = self;
+    int64_t delay = (int64_t)(ANNSurfaceStartWaitLimit * NSEC_PER_SEC);
+    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, delay), dispatch_get_main_queue(), ^{
+      [weakSelf letSurfaceGo];
+    });
+}
+
+// The surface tells its stage off the main queue, from its start and its stop. React Native's hosting view follows it
+// as before; a gone screen's surface that starts stops on the next turn of the main queue, once its start ended. The
+// block keeps this view, and with it the surface, until then, so their last release is on the main queue.
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated"
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+- (void)surface:(RCTSurface *)surface didChangeStage:(RCTSurfaceStage)stage {
+    [super surface:surface didChangeStage:stage];
+    if (!RCTSurfaceStageIsRunning(stage)) {
+        return;
+    }
+    dispatch_async(dispatch_get_main_queue(), ^{
+      [self stopSurfaceIfAsked];
+    });
+}
+#pragma clang diagnostic pop
+
+- (void)stopSurfaceIfAsked {
+    if (!_stopsWhenRunning) {
+        return;
+    }
+    RCTFabricSurface *surface = [self fabricSurface];
+    if (surface && RCTSurfaceStageIsRunning(surface.stage)) {
+        [surface stop];
+    }
+    [ANNHostingViewsStoppingAtStart removeObject:self];
+}
+
+// The limit: the surface hasn't started. It gets a delegate of its own that stops it at any later start, and this
+// view lets it go. The delegate changes before the check: a start told before the change reaches this view, which
+// stops the surface (its block keeps the view); one told after it reaches the new delegate.
+- (void)letSurfaceGo {
+    if (![ANNHostingViewsStoppingAtStart containsObject:self]) {
+        return;
+    }
+    RCTFabricSurface *surface = [self fabricSurface];
+    ANNSurfaceStopper *stopper = [ANNSurfaceStopper new];
+    objc_setAssociatedObject(surface, ANNSurfaceStopperKey, stopper,
+                             OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+    surface.delegate = stopper;
+    if (RCTSurfaceStageIsRunning(surface.stage)) {
+        [surface stop];
+    }
+    [ANNHostingViewsStoppingAtStart removeObject:self];
+}
+
 - (nullable RCTFabricSurface *)fabricSurface {
     id surface = self.surface;
     return [surface isKindOfClass:RCTFabricSurface.class] ? surface : nil;