@apexnative/navigation 1.0.0-alpha.2 → 1.0.0-alpha.4

package/ios/Layouts/Stack/ANNStackQueue.mm

@@ -16,7 +16,11 @@
 // How long the new top of a `setStackRoot` waits for its first content when `waitForRender` is not set.
 static const NSTimeInterval ANNStackRootRenderLimit = 0.5;
 
-// The limits of the bar components of a push: title and background 1 s, buttons 0.5 s, together from the wait's start.
+// How long a push waits for its new top's first content when `waitForRender` is not set.
+static const NSTimeInterval ANNPushRenderLimit = 0.5;
+
+// The limits of the bar components of a push: title and background 1 s, buttons 0.5 s. With `waitForRender` unset they
+// count from the wait's start, the content's time coming off them; with `true`, from the content's end.
 static const ANNBarWaitLimits ANNPushBarLimits = {1, 0.5};
 
 // The bar components of a `setStackRoot` within its 0.5 s.
@@ -53,8 +57,8 @@ typedef NS_ENUM(NSInteger, ANNStackOperationKind) {
 @property(nonatomic) BOOL animated;
 @property(nonatomic) BOOL waits;
 @property(nonatomic) BOOL atOnce;
-// When the replace's own wait for its new top started (`waitForRender` unset): the custom transition's wait takes what
-// is left of the 0.5 s. 0 when it didn't wait so.
+// When the push's or the replace's own wait for its new top started (`waitForRender` unset): the custom transition's
+// wait takes what is left of the 0.5 s. 0 when it didn't wait so.
 @property(nonatomic) CFTimeInterval waitStarted;
 @property(nonatomic, copy, nullable) dispatch_block_t completion;
 @property(nonatomic, copy, nullable) ANNTransitionRejectionBlock rejection;
@@ -371,12 +375,13 @@ static NSArray<UIViewController *> *ANNTopFirst(NSArray<UIViewController *> *ent
 
 - (void)noneWithValue:(id)value
                answer:(ANNCommandAnswer *)answer
+                 what:(NSString *)what
           componentId:(NSString *)componentId
                source:(UIViewController *)source {
     ANNAssertMainQueue();
     ANNStackOperation *operation = [self operationOfKind:ANNStackOperationNone
                                                   answer:answer
-                                                    what:@"pop"
+                                                    what:what
                                              componentId:componentId
                                                   source:source];
     operation.value = value;
@@ -559,41 +564,35 @@ static NSArray<UIViewController *> *ANNTopFirst(NSArray<UIViewController *> *ent
         [self scheduleRunNext];
         return;
     }
-    // `waitForRender: true` waits for the content as long as it takes, then for the bar components (their limits from
-    // the content's end); unset (also with `enabled: false`), only for the bar components, each kind to its own limit,
-    // without parking (bar roots render out of a window); `false`, for nothing. The content comes during the
-    // transition. A stack that isn't seen never waits.
+    // `waitForRender: true` waits for the content as long as it takes, then for the bar components, each kind to its own
+    // limit from the content's end; unset (also with `enabled: false`), for its first content at most 0.5 s, then for
+    // the bar components, each kind to its own limit from the wait's start (as when the push waited for them alone);
+    // `false`, for nothing, the content coming during the transition. Either wait's content ends after the calls
+    // JavaScript made in the commit that mounted the content (its `useScreenOptions`), content there already too, so
+    // that their options are in the bar on the transition's first frame. A native screen ends the wait at its start. A
+    // stack that isn't seen never waits.
     Bool *waitForRender = [node resolveOptionsWithDefault].animations.push.waitForRender;
     // A push whose caller waited already (a preview, `showInColumn`) waits for nothing here.
     BOOL onScreen = operation.waits && [_display stackIsOnScreen];
     __weak ANNStackQueue *weakSelf = self;
     __weak ANNStackOperation *weakOperation = operation;
-    if (onScreen && waitForRender.hasValue && waitForRender.get) {
-        [self waitFor:operation
-                    entry:node
-                  content:ANNRenderWaitContentNode
-                    limit:0
-             unknownLimit:YES
-                      bar:ANNRenderWaitBarAfterContent
-                barLimits:ANNPushBarLimits
-                     then:^{
-                       [weakSelf startPushTransition:weakOperation];
-                     }];
-        return;
-    }
-    if (onScreen && !waitForRender.hasValue) {
+    if (onScreen && (!waitForRender.hasValue || waitForRender.get)) {
+        BOOL bounded = !waitForRender.hasValue;
+        if (bounded) {
+            operation.waitStarted = CACurrentMediaTime();
+        }
         [self waitFor:operation
-                    entry:node
-                  content:ANNRenderWaitContentNone
-                    limit:0
-             unknownLimit:NO
-                      bar:ANNRenderWaitBarAfterContent
-                barLimits:ANNPushBarLimits
-                     then:^{
-                       // UIKit sizes the screen inside the push: it makes its content right before.
-                       [weakOperation.node render];
-                       [weakSelf startPushTransition:weakOperation];
-                     }];
+                       entry:node
+                     content:ANNRenderWaitContentNode
+                       limit:bounded ? ANNPushRenderLimit : 0
+                unknownLimit:!bounded
+                         bar:ANNRenderWaitBarAfterContent
+                   barLimits:ANNPushBarLimits
+             afterJavaScript:YES
+                barFromStart:bounded
+                        then:^{
+                          [weakSelf startPushTransition:weakOperation];
+                        }];
         return;
     }
     // UIKit sizes the screen inside the push: it makes its content right before.
@@ -616,10 +615,14 @@ static NSArray<UIViewController *> *ANNTopFirst(NSArray<UIViewController *> *ent
     operation.covered = covered;
     ANNTransitionPlan *plan = nil;
     if (animated) {
+        // Unset `waitForRender`: the custom transition's wait takes what is left of the push's own 0.5 s.
+        NSTimeInterval limit =
+            [ANNAnimationRules customWaitLimitAfterWaitStartedAt:operation.waitStarted
+                                                    commandLimit:ANNPushRenderLimit];
         plan = [ANNTransitionPlan stackPlanOfKind:ANNTransitionKindPush
                                         animation:push
                                     waitForRender:push.waitForRender
-                                        waitLimit:ANNCustomTransitionWaitLimit
+                                        waitLimit:limit
                                              from:covered
                                                to:node];
     }
@@ -746,6 +749,8 @@ static NSArray<UIViewController *> *ANNTopFirst(NSArray<UIViewController *> *ent
                  unknownLimit:NO
                           bar:ANNRenderWaitBarWithContent
                     barLimits:ANNStackRootBarLimits
+              afterJavaScript:NO
+                 barFromStart:NO
                          then:^{
                            [weakSelf startReplaceTransition:weakOperation];
                          }];
@@ -759,6 +764,8 @@ static NSArray<UIViewController *> *ANNTopFirst(NSArray<UIViewController *> *ent
                  unknownLimit:YES
                           bar:ANNRenderWaitBarAfterContent
                     barLimits:ANNStackRootBarLimits
+              afterJavaScript:NO
+                 barFromStart:NO
                          then:^{
                            [weakSelf startReplaceTransition:weakOperation];
                          }];
@@ -1046,16 +1053,20 @@ static NSArray<UIViewController *> *ANNTopFirst(NSArray<UIViewController *> *ent
 // for it in the stack's view, its appearance driven: the wait ends at the entry's ready handler (set first, then the
 // park and `render`, then the test of 16.1), at `limit` with `markReady`, or with `unknownLimit` for a screen whose
 // rendered state stays unknown after 1 s. Without content, only the bar components, without parking (bar roots render
-// out of a window). A wait that would end does nothing once its operation ended or belongs to an old JavaScript; its
-// end runs protected (the end steps of the operation, `then`).
+// out of a window). With `afterJavaScript` the content's end waits for the calls JavaScript made by then
+// (`settlesThroughJavaScript`); with `barFromStart` the bar phase's limits count from the wait's start
+// (`barLimitsFromStart`). A wait that would end does nothing once its operation ended or belongs to an old
+// JavaScript; its end runs protected (the end steps of the operation, `then`).
 - (void)waitFor:(ANNStackOperation *)operation
-           entry:(UIViewController *)entry
-         content:(ANNRenderWaitContent)content
-           limit:(NSTimeInterval)limit
-    unknownLimit:(BOOL)unknownLimit
-             bar:(ANNRenderWaitBar)bar
-       barLimits:(ANNBarWaitLimits)barLimits
-            then:(dispatch_block_t)then {
+              entry:(UIViewController *)entry
+            content:(ANNRenderWaitContent)content
+              limit:(NSTimeInterval)limit
+       unknownLimit:(BOOL)unknownLimit
+                bar:(ANNRenderWaitBar)bar
+          barLimits:(ANNBarWaitLimits)barLimits
+    afterJavaScript:(BOOL)afterJavaScript
+       barFromStart:(BOOL)barFromStart
+               then:(dispatch_block_t)then {
     __weak ANNStackQueue *weakSelf = self;
     __weak ANNStackOperation *weakOperation = operation;
     // The screens the wait is about are those the entry waits for (a pair: the ones it puts in the window).
@@ -1069,6 +1080,8 @@ static NSArray<UIViewController *> *ANNTopFirst(NSArray<UIViewController *> *ent
                                                              bar:bar
                                                        barLimits:barLimits];
     wait.unknownContentRule = unknownLimit;
+    wait.settlesThroughJavaScript = afterJavaScript;
+    wait.barLimitsFromStart = barFromStart;
     wait.canEnd = ^BOOL {
       ANNStackQueue *queue = weakSelf;
       ANNStackOperation *waiting = weakOperation;

package/ios/Layouts/Stack/UINavigationController+ANNCommands.h

@@ -6,9 +6,11 @@ NS_ASSUME_NONNULL_BEGIN
 /// The commands of a stack.
 @interface UINavigationController (ANNCommands)
 
-/// `setStackRoot`: `children` in place of the stack's screens, the last one on top, from the screen
-/// `fromViewController`.
+/// `showInColumn` into the split view's column `column` that is a stack: `children` in place of the stack's screens, the
+/// last one on top, from the screen `fromViewController`. A navigation controller that isn't a stack of the core
+/// rejects `[ANNErrorTexts columnNotStack:column:]`.
 - (void)setStackChildren:(NSArray<UIViewController *> *)children
+                inColumn:(NSString *)column
       fromViewController:(nullable UIViewController *)fromViewController
                 animated:(BOOL)animated
               completion:(ANNTransitionCompletionBlock)completion

package/ios/Layouts/Stack/UINavigationController+ANNCommands.mm

@@ -8,6 +8,7 @@
 // A stack of the core takes the screens through its queue, without a wait. A navigation controller of UIKit's own (the
 // one UIKit puts around a column that is a screen alone) has no queue: it rejects.
 - (void)setStackChildren:(NSArray<UIViewController *> *)children
+                inColumn:(NSString *)column
       fromViewController:(UIViewController *)fromViewController
                 animated:(BOOL)animated
               completion:(ANNTransitionCompletionBlock)completion
@@ -21,9 +22,7 @@
         return;
     }
     NSString *fromId = fromViewController.layoutInfo.componentId ?: @"";
-    NSString *what = [NSString stringWithFormat:@"set the stack of the screen '%@'", fromId];
-    NSString *reason = @"its column is not a stack of the navigation";
-    rejection([ANNErrorTexts couldNot:what reason:reason], nil);
+    rejection([ANNErrorTexts columnNotStack:fromId column:column], nil);
 }
 
 @end

package/ios/Layouts/Tabs/ANNBottomTabItemBuilder.h

@@ -23,6 +23,10 @@ NS_ASSUME_NONNULL_BEGIN
 /// (default `iconColor`) unless `disableSelectedIconTint`. Nil without any.
 + (nullable UIImage *)selectedIconOf:(ANNBottomTabOptions *)tab;
 
+/// The images of the options `iconOf:` and `selectedIconOf:` draw from (`bottomTab.icon`, `bottomTab.selectedIcon`):
+/// each one an SF Symbol doesn't cover. Their sources, not their images: nothing loads.
++ (NSArray<Image *> *)rastersOf:(ANNBottomTabOptions *)tab;
+
 /// `selectedIconColor`, else `iconColor` (`bottomTab.selectedIconColor`); nil without both.
 + (nullable UIColor *)selectedIconColorOf:(ANNBottomTabOptions *)tab;
 

package/ios/Layouts/Tabs/ANNBottomTabItemBuilder.mm

@@ -67,6 +67,17 @@ static void ANNSetTitleAttributes(UITabBarItemStateAppearance *state, UIColor *c
     return icon ? ANNRaster(icon, color) : nil;
 }
 
++ (NSArray<Image *> *)rastersOf:(ANNBottomTabOptions *)tab {
+    NSMutableArray<Image *> *rasters = [NSMutableArray new];
+    if (!ANNSymbol(tab.sfSymbol) && tab.icon.source) {
+        [rasters addObject:tab.icon];
+    }
+    if (!ANNSymbol(tab.sfSelectedSymbol) && tab.selectedIcon.source) {
+        [rasters addObject:tab.selectedIcon];
+    }
+    return rasters;
+}
+
 + (UIColor *)selectedIconColorOf:(ANNBottomTabOptions *)tab {
     return [tab.selectedIconColor withDefault:nil] ?: [tab.iconColor withDefault:nil];
 }

package/ios/Layouts/Tabs/ANNBottomTabsController.mm

@@ -817,7 +817,7 @@ static void ANNStacksOfNode(UIViewController *node, NSMutableArray<ANNStackContr
     if (index >= _tabs.count || self.nodeHelper.destroyed) {
         return NO;
     }
-    [self sendPendingSelected];
+    [self finishEarlierSelection];
     _pressedIndex = NSNotFound;
     // The release of a long press: UIKit would select the tab under the finger.
     if (source == ANNTabPressSourceBar && index == _longPressedIndex) {
@@ -957,6 +957,14 @@ static void ANNStacksOfNode(UIViewController *node, NSMutableArray<ANNStackContr
     [self sendPendingSelected];
 }
 
+// Before anything newer on these tabs (a press, a long press, a More pick, a choice from code): a switch still running
+// ends with its appearances and schedules its `Selected`, and a `Selected` still waiting goes, as Android's
+// `flushPendingSelected` does.
+- (void)finishEarlierSelection {
+    [self endSwitch];
+    [self sendPendingSelected];
+}
+
 - (void)sendPendingSelected {
     if (!_hasPendingSelected) {
         return;
@@ -980,8 +988,8 @@ static void ANNStacksOfNode(UIViewController *node, NSMutableArray<ANNStackContr
     if (index >= _tabs.count || self.nodeHelper.destroyed) {
         return;
     }
-    // A pending `Selected` goes before the event of a later press.
-    [self sendPendingSelected];
+    // A running switch and a pending `Selected` go before the event of a later press.
+    [self finishEarlierSelection];
     if (marksSelection) {
         _longPressedIndex = index;
     }
@@ -1024,7 +1032,7 @@ static void ANNStacksOfNode(UIViewController *node, NSMutableArray<ANNStackContr
 // first, then UIKit's, then the state at once.
 - (void)selectTabFromCode:(NSUInteger)index {
     ANNAssertMainQueue();
-    [self sendPendingSelected];
+    [self finishEarlierSelection];
     _pressedIndex = NSNotFound;
     if (index == _selectedTabIndex || index >= _tabs.count || self.nodeHelper.destroyed) {
         return;
@@ -1235,7 +1243,7 @@ static void ANNStacksOfNode(UIViewController *node, NSMutableArray<ANNStackContr
     if (pick && index == _selectedTabIndex) {
         return;
     }
-    [self sendPendingSelected];
+    [self finishEarlierSelection];
     _pressedIndex = NSNotFound;
     if (pick) {
         [self sendPressedOfTabAtIndex:index wasSelected:NO];

package/ios/Layouts/Tabs/ANNBottomTabsPresenter.h

@@ -10,8 +10,8 @@ NS_ASSUME_NONNULL_BEGIN
 /// `ANNBottomTabsController`.
 @interface ANNBottomTabsPresenter : ANNNodePresenter
 
-/// The repaint of a node the repaint pass left (a tab not in a window): its subtree, children first, with their
-/// resolved options.
+/// The repaint of a node the repaint pass left (a tab not in a window), as it is about to show: the nodes of its
+/// subtree whose views are in its view (what shows with it), children first, with their resolved options.
 + (void)repaintNode:(UIViewController *)node;
 
 #pragma mark - Creation, in this order

package/ios/Layouts/Tabs/ANNBottomTabsPresenter.mm

@@ -3,6 +3,7 @@
 #import "ANNBottomTabsAccessoryView.h"
 #import "ANNBottomTabsController.h"
 #import "ANNBottomTabsCustomRow.h"
+#import "ANNOptionImages.h"
 #import "ANNTabDotView.h"
 #import "ANNTabsDesign.h"
 #import "UITabBar+utils.h"
@@ -73,6 +74,8 @@ static id ANNValue(NSArray *list, NSUInteger index) {
     NSMutableDictionary<NSString *, ANNBottomTabsAccessoryView *> *_accessoryViews;
     // The pictures of the bar's colors by color and size.
     NSMutableDictionary<NSArray *, UIImage *> *_colorImages;
+    // The icons an item waits for, by layout index: a token per wait, which a later build of the item replaces.
+    NSMutableDictionary<NSNumber *, NSObject *> *_iconLoads;
 }
 
 - (nullable ANNBottomTabsController *)tabs {
@@ -82,10 +85,20 @@ static id ANNValue(NSArray *list, NSUInteger index) {
 }
 
 + (void)repaintNode:(UIViewController *)node {
+    [self repaintNode:node showingIn:node.viewIfLoaded];
+}
+
+// Children first. Only what shows with the tab repaints: a node whose view is out of the tab's views (a stack's lower
+// screens, a hidden tab of tabs inside) takes the new options at its own appearance, as the repaint of what shows
+// leaves the nodes out of a window (`ANNOptionsRepaint`).
++ (void)repaintNode:(UIViewController *)node showingIn:(nullable UIView *)tabView {
     for (UIViewController *child in node.layoutChildren) {
-        [self repaintNode:child];
+        [self repaintNode:child showingIn:tabView];
+    }
+    UIView *view = node.viewIfLoaded;
+    if (tabView && view && [view isDescendantOfView:tabView]) {
+        [node.presenter applyDefaultOptionsChange:[node resolveOptionsWithDefault]];
     }
-    [node.presenter applyDefaultOptionsChange:[node resolveOptionsWithDefault]];
 }
 
 #pragma mark - Creation
@@ -112,6 +125,7 @@ static id ANNValue(NSArray *list, NSUInteger index) {
     _buttonIds = [NSMapTable weakToStrongObjectsMapTable];
     _accessoryViews = [NSMutableDictionary new];
     _colorImages = [NSMutableDictionary new];
+    _iconLoads = [NSMutableDictionary new];
     for (NSUInteger index = 0; index < count; index++) {
         [_badges addObject:NSNull.null];
         [_dots addObject:[ANNBottomTabDotIndicatorOptions new]];
@@ -326,8 +340,12 @@ static id ANNValue(NSArray *list, NSUInteger index) {
     // The row's items show nothing: no image, no title, only the accessibility.
     NSString *text = [ANNBottomTabItemBuilder titleOf:bottomTab];
     NSString *title = row || _titlesHidden ? nil : text;
-    UIImage *icon = row ? nil : [ANNBottomTabItemBuilder iconOf:bottomTab];
-    UIImage *selectedIcon = row ? nil : [ANNBottomTabItemBuilder selectedIconOf:bottomTab];
+    // While new icons load off the main queue the item keeps the ones it shows; a wait of an earlier build is over.
+    [_iconLoads removeObjectForKey:@(index)];
+    BOOL keepsIcons = !row && [self loadsIconsLaterOf:bottomTab atIndex:index];
+    UIImage *icon = row || keepsIcons ? nil : [ANNBottomTabItemBuilder iconOf:bottomTab];
+    UIImage *selectedIcon =
+        row || keepsIcons ? nil : [ANNBottomTabItemBuilder selectedIconOf:bottomTab];
     if (@available(iOS 18.0, *)) {
         if (uiTab) {
             UITab *systemTab = uiTab;
@@ -339,12 +357,13 @@ static id ANNValue(NSArray *list, NSUInteger index) {
                     systemTab.title = tabTitle;
                 }
             }
-            if ((!search || icon || row) && systemTab.image != icon) {
+            if (!keepsIcons && (!search || icon || row) && systemTab.image != icon) {
                 systemTab.image = icon;
             }
 #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 270000
             if (@available(iOS 26.1, *)) {
-                if ((!search || selectedIcon || row) && systemTab.selectedImage != selectedIcon) {
+                if (!keepsIcons && (!search || selectedIcon || row) &&
+                    systemTab.selectedImage != selectedIcon) {
                     systemTab.selectedImage = selectedIcon;
                 }
             }
@@ -365,7 +384,7 @@ static id ANNValue(NSArray *list, NSUInteger index) {
             item.accessibilityLabel = text;
         }
     }
-    if (!roleItem || icon) {
+    if (!keepsIcons && (!roleItem || icon)) {
         if (item.image != icon) {
             item.image = icon;
         }
@@ -427,6 +446,89 @@ static id ANNValue(NSArray *list, NSUInteger index) {
     }
 }
 
+// `bottomTab` with the images that came in place of the rasters they came for: a build from it asks the cache for
+// none of them. A raster that failed stays as it was (its failure answers for a moment).
+static ANNBottomTabOptions *ANNWithIcons(ANNBottomTabOptions *bottomTab, NSArray<Image *> *rasters,
+                                         NSArray *came) {
+    ANNBottomTabOptions *built = [bottomTab copy];
+    for (NSUInteger place = 0; place < rasters.count; place++) {
+        UIImage *image = [came[place] isKindOfClass:UIImage.class] ? came[place] : nil;
+        if (!image) {
+            continue;
+        }
+        Image *raster = rasters[place];
+        if (raster == bottomTab.icon) {
+            built.icon = [[Image alloc] initWithValue:image];
+        }
+        if (raster == bottomTab.selectedIcon) {
+            built.selectedIcon = [[Image alloc] initWithValue:image];
+        }
+    }
+    return built;
+}
+
+// New raster icons of an item on the bar that shows load off the main queue when the cache doesn't have them: the item
+// takes them when they came, built again from the same options with the images that came (the cache may have let them
+// go by then: icons larger than it), unless it was built again first (the last build wins). The first icons, and every
+// icon while the bar is out of a window, load at once: the tab's first frame shows them.
+- (BOOL)loadsIconsLaterOf:(ANNBottomTabOptions *)bottomTab atIndex:(NSUInteger)index {
+    if (!_tabsAreSet || !self.tabs.viewIfLoaded.window) {
+        return NO;
+    }
+    NSArray<Image *> *rasters = [ANNBottomTabItemBuilder rastersOf:bottomTab];
+    BOOL later = NO;
+    for (Image *raster in rasters) {
+        if ([ANNOptionImages loadsLater:raster.source]) {
+            later = YES;
+        }
+    }
+    if (!later) {
+        return NO;
+    }
+    NSObject *load = [NSObject new];
+    _iconLoads[@(index)] = load;
+    // Every raster of the item, those the cache has too: each comes with its image, by its place in `rasters`.
+    NSMutableArray *came = [NSMutableArray arrayWithCapacity:rasters.count];
+    for (NSUInteger each = 0; each < rasters.count; each++) {
+        [came addObject:NSNull.null];
+    }
+    __block NSUInteger pending = rasters.count;
+    __block BOOL asking = YES;
+    __weak ANNBottomTabsPresenter *weakSelf = self;
+    [rasters enumerateObjectsUsingBlock:^(Image *raster, NSUInteger place, BOOL *stop) {
+      [ANNOptionImages loadLater:raster.source
+                            done:^(UIImage *image) {
+                              if (image) {
+                                  came[place] = image;
+                              }
+                              pending--;
+                              ANNBottomTabsPresenter *presenter = weakSelf;
+                              if (pending == 0 && !asking) {
+                                  [presenter iconsCame:load
+                                               atIndex:index
+                                             bottomTab:ANNWithIcons(bottomTab, rasters, came)];
+                              }
+                            }];
+    }];
+    asking = NO;
+    if (pending == 0) {
+        // A load ended while the others were asked for: the cache has them all now.
+        [_iconLoads removeObjectForKey:@(index)];
+        return NO;
+    }
+    return YES;
+}
+
+- (void)iconsCame:(NSObject *)load
+          atIndex:(NSUInteger)index
+        bottomTab:(ANNBottomTabOptions *)bottomTab {
+    if (_iconLoads[@(index)] != load || index >= self.tabs.layoutTabs.count) {
+        return;
+    }
+    [_iconLoads removeObjectForKey:@(index)];
+    [self buildItemAtIndex:index bottomTab:bottomTab updatesBadgeAndDot:NO];
+}
+
 - (void)updateDotAtIndex:(NSUInteger)index
                    shown:(BOOL)shown
                  options:(ANNBottomTabDotIndicatorOptions *)dot {

package/ios/Options/ANNOptionsCache.h

@@ -2,13 +2,14 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// The one point where options change: a number for the whole process that grows each time a node's own options or the
-/// default options change. A node's resolved options are cached with the number they were built at, so any change makes
-/// every cache miss. Main queue.
+/// The one point where options change: a number for the whole process that grows each time a node's own options, its
+/// user layer or the default options change. A node's resolved options are cached with the number they were built at,
+/// so any change makes every cache miss. Main queue.
 ///
-/// Exactly two places call `optionsChanged`: the setter of a node's own options (`ANNNodeHelper.options`, which
-/// `mergeOwnOptions:` and `changeOwnOptions:` go through) and the store of new default options (`ANNDefaultOptions`).
-/// Nothing else may change own options or defaults: a write past them would leave caches stale.
+/// Exactly three places call `optionsChanged`: the setter of a node's own options (`ANNNodeHelper.options`, which
+/// `mergeOwnOptions:` and `changeOwnOptions:` go through), the setter of its user layer
+/// (`ANNNodeHelper setUserChoice:forKey:`) and the store of new default options (`ANNDefaultOptions`). Nothing else may
+/// change own options, choices or defaults: a write past them would leave caches stale.
 @interface ANNOptionsCache : NSObject
 
 /// The generation of the options now.

package/ios/Options/ANNSearchBarOptions.h

@@ -15,9 +15,10 @@ typedef NS_ENUM(NSInteger, SearchBarPlacement) {
     SearchBarPlacementIntegratedCentered,
 };
 
-/// `topBar.searchBar` (`OptionsSearchBar`): the search of a screen. `ANNSearchPresenter` applies it. The scope, the
-/// tokens and the suggestions are written back by the search as the user changes them (`changeOwnOptions:`), so they
-/// stay when the options apply again.
+/// `topBar.searchBar` (`OptionsSearchBar`): the search of a screen. `ANNSearchPresenter` applies it. The scope the user
+/// picks, the tokens the user deletes or brings back and the suggestions UIKit removes go into the screen's user layer
+/// (`setUserChoice:forKey:`), not into these options: they stay when the options apply again and through a
+/// `mergeOptions` that sends the same values, and give way when a merge changes the field.
 @interface ANNSearchBarOptions : ANNOptions
 
 @property(nonatomic, strong) Bool *visible;

package/ios/Options/ANNUserChoice.h

@@ -0,0 +1,57 @@
+#import "ANNNavigationOptions.h"
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Writes a choice into options being resolved: `options` is a copy the block may change, but its lists and their
+/// items are shared with other trees, so the block puts in a new list with a copy of what it changes, never a change in
+/// place. It finds what it changes by identity (a button by its id, a menu item by its id, a scope by its id) and
+/// leaves the options as they are when that is not there.
+typedef void (^ANNUserChoiceApply)(ANNNavigationOptions *options, id value);
+
+/// The value of a choice after the app's `mergeOptions` into the node, by Android's rules (`UserChoices.yieldTo`):
+/// `merge` is what the app sent, `own` the node's own options before it, `before` and `after` the node's resolution
+/// with the defaults and without any user layer (the app's options alone) before and after the merge. The same `value`
+/// keeps the choice, a smaller value keeps part of it, nil drops it. A part leaves when what it was made in is gone
+/// from `after` (a button, a menu item, a scope), or when `merge` gives its field a value other than the one the app
+/// had there: `own`'s, or `before`'s where `own` has no such field (a list the node takes from its stack or the
+/// defaults). The same value sent again (a re-render) keeps it.
+typedef id _Nullable (^ANNUserChoiceMerged)(id value, ANNNavigationOptions *merge,
+                                             ANNNavigationOptions *own,
+                                             ANNNavigationOptions *before,
+                                             ANNNavigationOptions *after);
+
+/// One choice the user made in native UI (a toggled button, the check of a single-selection menu, the search scope, the
+/// tokens and the suggestions UIKit removed, a renamed title), kept in the node's user layer
+/// (`ANNNodeHelper setUserChoice:forKey:`) apart from its own options. The node's resolution writes it over the own
+/// options (`applyTo:`); the app's real change of the same field, or a merge after which what it is about is gone,
+/// takes it away (`choiceAfterMerge:own:before:after:`). The blocks capture only plain data (a side, an id, a key),
+/// never a presenter: the node keeps them as long as the choice.
+@interface ANNUserChoice : NSObject
+
+/// What the user chose, never changed: a number, a string, an array of ids or of option copies.
+@property(nonatomic, strong, readonly) id value;
+
++ (instancetype)choiceWithValue:(id)value
+                          apply:(ANNUserChoiceApply)apply
+                         merged:(ANNUserChoiceMerged)merged;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The same choice with another value.
+- (instancetype)choiceWithValue:(id)value;
+
+/// The choice written into `options` (a copy being resolved).
+- (void)applyTo:(ANNNavigationOptions *)options;
+
+/// The choice after the app's `mergeOptions` (`ANNUserChoiceMerged`): itself, the choice with a smaller value, or nil
+/// when it goes.
+- (nullable ANNUserChoice *)choiceAfterMerge:(ANNNavigationOptions *)merge
+                                         own:(ANNNavigationOptions *)own
+                                      before:(ANNNavigationOptions *)before
+                                       after:(ANNNavigationOptions *)after;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/ANNUserChoice.mm

@@ -0,0 +1,44 @@
+#import "ANNUserChoice.h"
+
+@implementation ANNUserChoice {
+    ANNUserChoiceApply _apply;
+    ANNUserChoiceMerged _merged;
+}
+
++ (instancetype)choiceWithValue:(id)value
+                          apply:(ANNUserChoiceApply)apply
+                         merged:(ANNUserChoiceMerged)merged {
+    return [[self alloc] initWithValue:value apply:apply merged:merged];
+}
+
+- (instancetype)initWithValue:(id)value
+                        apply:(ANNUserChoiceApply)apply
+                       merged:(ANNUserChoiceMerged)merged {
+    if (self = [super init]) {
+        _value = value;
+        _apply = [apply copy];
+        _merged = [merged copy];
+    }
+    return self;
+}
+
+- (instancetype)choiceWithValue:(id)value {
+    return [[ANNUserChoice alloc] initWithValue:value apply:_apply merged:_merged];
+}
+
+- (void)applyTo:(ANNNavigationOptions *)options {
+    _apply(options, _value);
+}
+
+- (ANNUserChoice *)choiceAfterMerge:(ANNNavigationOptions *)merge
+                                own:(ANNNavigationOptions *)own
+                             before:(ANNNavigationOptions *)before
+                              after:(ANNNavigationOptions *)after {
+    id value = _merged(_value, merge, own, before, after);
+    if (!value) {
+        return nil;
+    }
+    return value == _value ? self : [self choiceWithValue:value];
+}
+
+@end