@apexnative/navigation 1.0.0-alpha.5 → 1.0.0-alpha.6

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,
@@ -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

@@ -12,6 +12,12 @@ NS_ASSUME_NONNULL_BEGIN
 /// 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,49 @@
 #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 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
@@ -60,6 +100,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;

package/ios/TopBar/ANNBackButtonPresenter.mm

@@ -2,6 +2,7 @@
 #import "ANNExternalViewController.h"
 #import "ANNIconButtonImage.h"
 #import "ANNStackController.h"
+#import "ANNTabsDesign.h"
 #import <objc/runtime.h>
 
 // The item below that the core configured: what it set may go again.
@@ -141,10 +142,8 @@ static const void *ANNBackButtonConfiguredKey = &ANNBackButtonConfiguredKey;
     ANNBackBarButtonItem *item = [ANNBackBarButtonItem new];
     item.allowsMenu = [backButton.enableMenu withDefault:YES];
     item.style = UIBarButtonItemStylePlain;
-    BOOL before26 = YES;
-    if (@available(iOS 26.0, *)) {
-        before26 = NO;
-    }
+    // The compatibility mode of iOS 26 shows the title below too, as the design before it.
+    BOOL before26 = !ANNTabsDesign.isGlass;
     item.title = title ?: (before26 ? belowTitle : nil);
     UIColor *background = [self iconBackgroundColorOf:backButton];
     if (background) {
@@ -165,7 +164,9 @@ static const void *ANNBackButtonConfiguredKey = &ANNBackButtonConfiguredKey;
                                      [iconBackground.height withDefault:0])
                    insets:UIEdgeInsetsZero];
         if (@available(iOS 26.0, *)) {
-            item.hidesSharedBackground = [backButton.hideSharedBackground withDefault:YES];
+            if (ANNTabsDesign.isGlass) {
+                item.hidesSharedBackground = [backButton.hideSharedBackground withDefault:YES];
+            }
         }
     }
     return item;

package/ios/TopBar/ANNBarAppearance.h

@@ -45,7 +45,8 @@ typedef struct {
 /// (a clear color is a clear bar). The one rule for the bar, its color in the list and the top edge effect.
 + (nullable UIColor *)solidColorOf:(nullable Color *)color traits:(UITraitCollection *)traits;
 
-/// A 1×1 image of `color` resolved for `traits`.
+/// A 1×1 image of `color` resolved for `traits`, with a variant for each style: the same image for the same resolved
+/// colors, so a look filled again equals the one before (as the back button's tinted arrow).
 + (UIImage *)imageOfColor:(UIColor *)color traits:(UITraitCollection *)traits;
 
 @end

package/ios/TopBar/ANNBarAppearance.mm

@@ -1,5 +1,12 @@
 #import "ANNBarAppearance.h"
 #import "ANNBackButtonPresenter.h"
+#import "ANNTabsDesign.h"
+#import <objc/runtime.h>
+
+// The icon an indicator was tinted from: an entry found by the icon's address counts only for that icon. An indicator
+// that is the icon itself (already an original image) carries nothing: the icon must not hold itself, and it may be
+// the image the options' cache keeps.
+static const void *ANNIndicatorIconKey = &ANNIndicatorIconKey;
 
 // UIKit's fonts of the places the options build over: the title of the row, the large title, the text of the back
 // button.
@@ -28,6 +35,27 @@ static BOOL ANNIsClear(UIColor *color, UITraitCollection *traits) {
     return CGColorGetAlpha([color resolvedColorWithTraitCollection:traits].CGColor) == 0;
 }
 
+// The images the looks are made of, by what they are drawn from, so a look filled again from the same options is
+// equal to the one before (UIKit compares appearances by value, images by identity) and nothing is set again. Main
+// queue; a memory warning empties it.
+static NSCache<id, UIImage *> *ANNLookImages(void) {
+    static NSCache<id, UIImage *> *images;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      images = [NSCache new];
+      images.countLimit = 64;
+    });
+    return images;
+}
+
+// A color of the options as a key: a pair by its sides (its dynamic color is made anew), else its value.
+static NSArray *ANNColorKeyOf(Color *color) {
+    if (color.light || color.dark) {
+        return @[ color.light ?: NSNull.null, color.dark ?: NSNull.null ];
+    }
+    return @[ color.value ?: NSNull.null ];
+}
+
 static NSDictionary<NSAttributedStringKey, id> *ANNTextAttributes(ANNFontOptions *font,
                                                                  Color *color,
                                                                  UIFont *placeFont) {
@@ -104,16 +132,14 @@ static NSDictionary<NSAttributedStringKey, id> *ANNTextAttributes(ANNFontOptions
     return resolved && !ANNIsClear(resolved, traits) ? resolved : nil;
 }
 
+// The glass bar is translucent by default; the design before iOS 26 (and its compatibility mode) opaque.
 + (BOOL)translucentByDefault {
-    if (@available(iOS 26.0, *)) {
-        return YES;
-    }
-    return NO;
+    return ANNTabsDesign.isGlass;
 }
 
-// `color` beats `blur` and `translucent`; a clear color is a clear bar. On iOS 26 a color is a solid bar: a clear base
-// with the color and a 1×1 image of it, without the system effect. `blur` is the system's chrome material on a clear
-// base, with no view of its own in the bar.
+// `color` beats `blur` and `translucent`; a clear color is a clear bar. On the glass of iOS 26 a color is a solid
+// bar: a clear base with the color and a 1×1 image of it, without the system effect. `blur` is the system's chrome
+// material on a clear base, with no view of its own in the bar.
 + (void)configure:(UINavigationBarAppearance *)appearance
             color:(UIColor *)color
              blur:(BOOL)blur
@@ -124,7 +150,7 @@ static NSDictionary<NSAttributedStringKey, id> *ANNTextAttributes(ANNFontOptions
             [appearance configureWithTransparentBackground];
             return;
         }
-        if (@available(iOS 26.0, *)) {
+        if (ANNTabsDesign.isGlass) {
             [appearance configureWithTransparentBackground];
             appearance.backgroundEffect = nil;
             appearance.backgroundColor = color;
@@ -219,23 +245,51 @@ static NSDictionary<NSAttributedStringKey, id> *ANNTextAttributes(ANNFontOptions
         if (!color) {
             return nil;
         }
-        icon = [UIImage systemImageNamed:@"chevron.backward"];
+        symbol = @"chevron.backward";
+        icon = [UIImage systemImageNamed:symbol];
         isSymbol = YES;
     }
+    // A symbol by its name; an image by its object, which the entry keeps, so its address is never another's.
+    id iconKey = isSymbol ? symbol : [NSValue valueWithNonretainedObject:icon];
+    NSArray *key = @[
+        @"back", iconKey, color ? ANNColorKeyOf(backButton.color) : NSNull.null
+    ];
+    NSCache<id, UIImage *> *images = ANNLookImages();
+    UIImage *cached = [images objectForKey:key];
+    if (cached && (isSymbol || cached == icon ||
+                   objc_getAssociatedObject(cached, ANNIndicatorIconKey) == icon)) {
+        return cached;
+    }
+    UIImage *indicator = nil;
     if (color) {
-        return [icon imageWithTintColor:color renderingMode:UIImageRenderingModeAlwaysOriginal];
+        indicator = [icon imageWithTintColor:color
+                               renderingMode:UIImageRenderingModeAlwaysOriginal];
+    } else {
+        indicator =
+            isSymbol ? icon : [icon imageWithRenderingMode:UIImageRenderingModeAlwaysOriginal];
+    }
+    if (!isSymbol && indicator != icon) {
+        objc_setAssociatedObject(indicator, ANNIndicatorIconKey, icon,
+                                 OBJC_ASSOCIATION_RETAIN_NONATOMIC);
     }
-    return isSymbol ? icon : [icon imageWithRenderingMode:UIImageRenderingModeAlwaysOriginal];
+    [images setObject:indicator forKey:key];
+    return indicator;
 }
 
+// One for the app: every look that hides the arrow holds the same image.
 + (UIImage *)emptyIndicator {
-    UIGraphicsImageRendererFormat *format = [UIGraphicsImageRendererFormat preferredFormat];
-    format.opaque = NO;
-    UIGraphicsImageRenderer *renderer =
-        [[UIGraphicsImageRenderer alloc] initWithSize:CGSizeMake(1, 1) format:format];
-    UIImage *empty = [renderer imageWithActions:^(UIGraphicsImageRendererContext *context){
-    }];
-    return [empty imageWithRenderingMode:UIImageRenderingModeAlwaysOriginal];
+    static UIImage *empty;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      UIGraphicsImageRendererFormat *format = [UIGraphicsImageRendererFormat preferredFormat];
+      format.opaque = NO;
+      UIGraphicsImageRenderer *renderer =
+          [[UIGraphicsImageRenderer alloc] initWithSize:CGSizeMake(1, 1) format:format];
+      UIImage *drawn = [renderer imageWithActions:^(UIGraphicsImageRendererContext *context){
+      }];
+      empty = [drawn imageWithRenderingMode:UIImageRenderingModeAlwaysOriginal];
+    });
+    return empty;
 }
 
 + (UIColor *)pinnedTitleColor:(Color *)color traits:(UITraitCollection *)traits {
@@ -244,8 +298,44 @@ static NSDictionary<NSAttributedStringKey, id> *ANNTextAttributes(ANNFontOptions
 }
 
 // The 1×1 picture of the color in both styles: the bar's image view picks the variant of its own style, so a `{ light,
-// dark }` color follows a switch of the style without a new appearance.
+// dark }` color follows a switch of the style without a new appearance. Made once for the two resolved colors and the
+// style picked.
 + (UIImage *)imageOfColor:(UIColor *)color traits:(UITraitCollection *)traits {
+    UITraitCollection *light =
+        [UITraitCollection traitCollectionWithUserInterfaceStyle:UIUserInterfaceStyleLight];
+    UITraitCollection *dark =
+        [UITraitCollection traitCollectionWithUserInterfaceStyle:UIUserInterfaceStyleDark];
+    // Each variant is drawn with the window's other traits (contrast, elevation) and registered by its style only.
+    NSArray<UITraitCollection *> *base = traits ? @[ traits ] : @[];
+    UITraitCollection *lightTraits = [UITraitCollection
+        traitCollectionWithTraitsFromCollections:[base arrayByAddingObject:light]];
+    UITraitCollection *darkTraits = [UITraitCollection
+        traitCollectionWithTraitsFromCollections:[base arrayByAddingObject:dark]];
+    UIColor *lightColor = [color resolvedColorWithTraitCollection:lightTraits];
+    UIColor *darkColor = [color resolvedColorWithTraitCollection:darkTraits];
+    BOOL isDark = traits.userInterfaceStyle == UIUserInterfaceStyleDark;
+    NSArray *key = @[ @"color", lightColor, darkColor, @(isDark) ];
+    NSCache<id, UIImage *> *images = ANNLookImages();
+    UIImage *cached = [images objectForKey:key];
+    if (cached) {
+        return cached;
+    }
+    UIImage *image = [self drawImageOf:color
+                                 light:light
+                                  dark:dark
+                           lightTraits:lightTraits
+                            darkTraits:darkTraits
+                                isDark:isDark];
+    [images setObject:image forKey:key];
+    return image;
+}
+
++ (UIImage *)drawImageOf:(UIColor *)color
+                   light:(UITraitCollection *)light
+                    dark:(UITraitCollection *)dark
+             lightTraits:(UITraitCollection *)lightTraits
+              darkTraits:(UITraitCollection *)darkTraits
+                  isDark:(BOOL)isDark {
     UIImage * (^draw)(UITraitCollection *) = ^UIImage *(UITraitCollection *variant) {
       UIColor *resolved = [color resolvedColorWithTraitCollection:variant];
       UIGraphicsImageRendererFormat *format = [UIGraphicsImageRendererFormat preferredFormat];
@@ -257,20 +347,11 @@ static NSDictionary<NSAttributedStringKey, id> *ANNTextAttributes(ANNFontOptions
         [context fillRect:CGRectMake(0, 0, 1, 1)];
       }];
     };
-    UITraitCollection *light =
-        [UITraitCollection traitCollectionWithUserInterfaceStyle:UIUserInterfaceStyleLight];
-    UITraitCollection *dark =
-        [UITraitCollection traitCollectionWithUserInterfaceStyle:UIUserInterfaceStyleDark];
-    // Each variant is drawn with the window's other traits (contrast, elevation) and registered by its style only.
-    NSArray<UITraitCollection *> *base = traits ? @[ traits ] : @[];
-    UIImage *lightImage =
-        draw([UITraitCollection traitCollectionWithTraitsFromCollections:[base arrayByAddingObject:light]]);
-    UIImage *darkImage =
-        draw([UITraitCollection traitCollectionWithTraitsFromCollections:[base arrayByAddingObject:dark]]);
+    UIImage *lightImage = draw(lightTraits);
+    UIImage *darkImage = draw(darkTraits);
     UIImageAsset *asset = [UIImageAsset new];
     [asset registerImage:lightImage withTraitCollection:light];
     [asset registerImage:darkImage withTraitCollection:dark];
-    BOOL isDark = traits.userInterfaceStyle == UIUserInterfaceStyleDark;
     UIImage *picked = [asset imageWithTraitCollection:isDark ? dark : light];
     return picked ?: (isDark ? darkImage : lightImage);
 }

package/ios/TopBar/ANNBarBackgroundComponent.mm

@@ -1,4 +1,5 @@
 #import "ANNBarBackgroundComponent.h"
+#import <React/RCTLog.h>
 #import <objc/runtime.h>
 
 // The background a bar shows now.
@@ -13,6 +14,21 @@ static UIView *ANNBackgroundHostOf(UINavigationBar *bar) {
             return subview;
         }
     }
+#if DEBUG
+    // The name is UIKit's private one: a system that renames the view puts the components on the bar itself. Told
+    // once, in development, and only for a bar that has its views already (one not laid out yet has none).
+    static BOOL told = NO;
+    if (!told && bar.subviews.count > 0) {
+        told = YES;
+        NSMutableArray<NSString *> *names = [NSMutableArray new];
+        for (UIView *subview in bar.subviews) {
+            [names addObject:NSStringFromClass(subview.class)];
+        }
+        RCTLogWarn(@"[ApexNavigation] the bar has no view named …BarBackground, so a background "
+                   @"component goes on the bar itself at index 1; its views: %@",
+                   [names componentsJoinedByString:@", "]);
+    }
+#endif
     return bar;
 }
 

package/ios/TopBar/ANNBarButtonComponentView.h

@@ -4,10 +4,10 @@
 NS_ASSUME_NONNULL_BEGIN
 
 /// The slot of a React button (`topBar.leftButtons[].component`) as the custom view of its bar item. It takes a content
-/// view (`UIView<ANNComponentProtocol>`), never a class of the roots. On iOS 26 without `UIDesignRequiresCompatibility`
-/// in the app's Info.plist the slot is 44 pt high and as wide as the content, at least 44 pt; the width follows the
-/// content both ways (measured after every mount; a change over 0.5 pt only), and the slot's constraints live with the
-/// view, so a new item built around it reuses them. With that key and before iOS 26: the content's size, no
+/// view (`UIView<ANNComponentProtocol>`), never a class of the roots. In the glass design of iOS 26 (`ANNTabsDesign`)
+/// the slot is 44 pt high and as wide as the content, at least 44 pt; the width follows the content both ways
+/// (measured after every mount; a change over 0.5 pt only), and the slot's constraints live with the view, so a new
+/// item built around it reuses them. In the compatibility mode and before iOS 26: the content's size, no
 /// constraints. A button rendered before the screen shows enters at its width. The core measures only the surface and
 /// never moves the views inside it: the JS wrapper centres them.
 @interface ANNBarButtonComponentView : UIView

package/ios/TopBar/ANNBarButtonComponentView.mm

@@ -7,7 +7,7 @@ static const CGFloat ANNBarButtonSlotHeight = 44;
 static const CGFloat ANNBarButtonSlotMinimumWidth = 44;
 static const CGFloat ANNBarButtonWidthTolerance = 0.5;
 
-// The slot of iOS 26's bar: unless the app keeps the earlier design (`UIDesignRequiresCompatibility`).
+// The slot of iOS 26's bar: unless UIKit keeps the earlier design for the app (`ANNTabsDesign`).
 static BOOL ANNUsesSlotConstraints(void) {
     return ANNTabsDesign.isGlass;
 }

package/ios/TopBar/ANNBarButtons.h

@@ -14,8 +14,9 @@ typedef NS_ENUM(NSInteger, ANNBarButtonsSide) {
 
 /// The buttons of one screen's bar and toolbar (`topBar.leftButtons[].*`, the side options, `overflowMenu`,
 /// `toolbar.buttons`): built from the resolved options, whole, at the screen's creation, at each appearance and at a
-/// merge of a side. Each button is an `ANNUIBarButtonItem` of the first kind its fields give (React view → icon and
-/// text → image button → SF Symbol → image → text → system item); a button without `id` is not placed. Side colors go
+/// merge of a side, when anything the side's build reads changed or the item no longer holds what it put there.
+/// Each button is an `ANNUIBarButtonItem` of the first kind its fields give (React view → icon and text → image
+/// button → SF Symbol → image → text → system item); a button without `id` is not placed. Side colors go
 /// onto what is built, never into the options; what the user chose (a toggle, a menu's check) goes into the screen's
 /// user layer. The React buttons' slots are kept by component id, so a button built again reuses its slot. Main queue.
 @interface ANNBarButtons : NSObject
@@ -27,7 +28,8 @@ typedef NS_ENUM(NSInteger, ANNBarButtonsSide) {
 + (instancetype)new NS_UNAVAILABLE;
 
 /// Sets `side` of the screen's item (left, right, center) from `options`; `animated` fades new buttons in (a side set
-/// as groups changes at once).
+/// as groups changes at once). Nothing when the side's buttons, colors, loaded images, React roots and traits are the
+/// same as at its last build and the item still holds what that build set: iOS 26 animates even equal new items.
 - (void)applySide:(ANNBarButtonsSide)side
           options:(ANNNavigationOptions *)options
          animated:(BOOL)animated;