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

package/ios/Layouts/Tabs/ANNTabsDesign.mm

@@ -2,7 +2,10 @@
 
 @implementation ANNTabsDesign
 
-// Read once: the Info.plist of a running app doesn't change.
+// Read once: the Info.plist of a running app doesn't change. iOS 26 keeps the earlier design for the key; iOS 27 keeps
+// it only for an app built with an SDK before iOS 27 and ignores it for one built with the iOS 27 SDK (an app linked
+// against the iOS 26 SDK keeps the earlier design on iOS 27, one linked against the iOS 27 SDK gets the glass). The
+// core is compiled with the app, so the SDK it is compiled with is the app's.
 + (BOOL)isCompatibilityMode {
     static BOOL compatibility;
     static dispatch_once_t once;
@@ -11,6 +14,11 @@
           id value = NSBundle.mainBundle.infoDictionary[@"UIDesignRequiresCompatibility"];
           compatibility = [value respondsToSelector:@selector(boolValue)] && [value boolValue];
       }
+#if __IPHONE_OS_VERSION_MAX_ALLOWED >= 270000
+      if (@available(iOS 27.0, *)) {
+          compatibility = NO;
+      }
+#endif
     });
     return compatibility;
 }

package/ios/Layouts/Tabs/UITabBar+utils.h

@@ -4,18 +4,18 @@
 
 /**
  * The button of an item in the tab bar. UIKit has no public API for it: this reads the private
- * `view` of the item, and is nil when UIKit has no such view (or the item none).
+ * `view` of the item, the core's one private read of the bar, and is nil when the item has no
+ * button (out of the bar, or before its layout). When UIKit has no such key any more, DEBUG logs it
+ * once.
  */
 - (UIView *)viewOfItem:(UITabBarItem *)item;
 
-- (UIView *)tabBarItemViewAtIndex:(NSUInteger)index;
-
 - (void)removeTabBarItemTitles;
 
 /**
  * Icons in the middle of the buttons of this tab bar, for items without titles: before iOS 26 (and
- * in its compatibility mode) a button keeps the room of its title; the iOS 26 design centers the
- * icons itself, and this does nothing there. UIKit has no public API for it: the layout of the
+ * in its compatibility mode, `ANNTabsDesign`) a button keeps the room of its title; the iOS 26
+ * design centers the icons itself, and this does nothing there. UIKit has no public API for it: the layout of the
  * private button class changes once for the app, and only tab bars with centered images move their
  * icons (and badges). `NO` gives the buttons the layout of UIKit back.
  */

package/ios/Layouts/Tabs/UITabBar+utils.mm

@@ -1,5 +1,7 @@
 #import "UITabBar+utils.h"
+#import "ANNTabsDesign.h"
 #import "UIView+Utils.h"
+#import <React/RCTLog.h>
 #import <objc/runtime.h>
 
 static const void *ANNItemImagesCenteredKey = &ANNItemImagesCenteredKey;
@@ -37,17 +39,16 @@ static void ANNTabBarButtonLayoutSubviews(UIView *button, SEL _cmd) {
     badge.center = CGPointMake(badge.center.x, badge.center.y + offset);
 }
 
-// The design of iOS 26 centers the icon of an item without a title itself; in its compatibility
-// mode (UIDesignRequiresCompatibility) the tab bar is drawn as before.
+// The design of iOS 26 centers the icon of an item without a title itself; the design before it
+// (before iOS 26, and the compatibility mode where UIKit keeps it) keeps the title's room.
 static BOOL ANNTabBarButtonsKeepTitleRoom(void) {
-    if (@available(iOS 26.0, *)) {
-        return [[NSBundle.mainBundle objectForInfoDictionaryKey:@"UIDesignRequiresCompatibility"]
-            boolValue];
-    }
-    return YES;
+    return !ANNTabsDesign.isGlass;
 }
 
-// Once for the app; the buttons of other tab bars keep the layout of UIKit.
+// Once for the app; the buttons of other tab bars keep the layout of UIKit. No public API does this: in the
+// compatibility mode of iOS 26 UIKit ignores `imageInsets` and a symbol's baseline offset, and a symbol drawn into a
+// taller bitmap is scaled down and stops being a symbol. `badgePositionAdjustment` would move the badge alone, so the
+// button's layout moves both.
 static void ANNInstallTabBarButtonLayout(void) {
     static dispatch_once_t once;
     dispatch_once(&once, ^{
@@ -65,18 +66,36 @@ static void ANNInstallTabBarButtonLayout(void) {
     });
 }
 
+// Once per app run, in DEBUG: the tab items' buttons can't be found any more.
+static void ANNWarnNoButtonOfItem(void) {
+#if DEBUG
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      RCTLogWarn(@"[ApexNavigation] This iOS version gives no button for a tab item: "
+                 @"bottomTab.testID on the tab buttons, the dot before iOS 26 and the long "
+                 @"press on a tab don't apply.");
+    });
+#endif
+}
+
 @implementation UITabBar (utils)
 
 - (UIView *)viewOfItem:(UITabBarItem *)item {
+    if (!item) {
+        return nil;
+    }
+    // An item out of the bar (in More, or before the bar's first layout) has no button: that is no failure. Only an
+    // item without the `view` key, or with something else under it, says that UIKit changed.
     if (![item respondsToSelector:NSSelectorFromString(@"view")]) {
+        ANNWarnNoButtonOfItem();
         return nil;
     }
     id view = [item valueForKey:@"view"];
-    return [view isKindOfClass:UIView.class] ? view : nil;
-}
-
-- (UIView *)tabBarItemViewAtIndex:(NSUInteger)index {
-    return index < self.items.count ? [self viewOfItem:self.items[index]] : nil;
+    if (view && ![view isKindOfClass:UIView.class]) {
+        ANNWarnNoButtonOfItem();
+        return nil;
+    }
+    return view;
 }
 
 - (void)removeTabBarItemTitles {

package/ios/Options/ANNBottomTabsOptions.h

@@ -11,6 +11,8 @@ NS_ASSUME_NONNULL_BEGIN
 
 @property(nonatomic, strong) Bool *visible;
 @property(nonatomic, strong) Bool *animate;
+/// `'platform'` or `'none'`; read on Android only: the system switches tabs at once.
+@property(nonatomic, strong) Text *switchAnimation;
 /// The index of the tab to select; a whole number (the fraction is dropped).
 @property(nonatomic, strong) Double *currentTabIndex;
 @property(nonatomic, strong) Text *currentTabId;

package/ios/Options/ANNBottomTabsOptions.mm

@@ -6,6 +6,7 @@
     return @[
         [ANNOptionField boolField:@"visible"],
         [ANNOptionField boolField:@"animate"],
+        [ANNOptionField enumField:@"switchAnimation" values:@[ @"platform", @"none" ]],
         [ANNOptionField doubleField:@"currentTabIndex"],
         [ANNOptionField textField:@"currentTabId"],
         [ANNOptionField textField:@"testID"],

package/ios/Options/ANNOptions.h

@@ -20,6 +20,13 @@ NS_ASSUME_NONNULL_BEGIN
 /// The group of options under `key`: nil when it is not an object (`null` included), which reads as an empty group.
 NSDictionary *_Nullable ANNOptionsDictionary(NSDictionary *_Nullable dict, NSString *key);
 
+/// Two values a group of options holds are the same: params and groups by `isSameValueAs:`, arrays item by item,
+/// anything else as `ANNJSONValuesSame` says. nil is the same only as nil (an unset array is not an empty one).
+BOOL ANNOptionValuesSame(id _Nullable a, id _Nullable b);
+
+/// A hash of a value `ANNOptionValuesSame` compares: values that are the same have the same hash.
+NSUInteger ANNOptionValueHash(id _Nullable value);
+
 #if DEBUG
 /// Development only: checks the field table of `root` and of every group class reached through its group and
 /// group-array fields.
@@ -57,6 +64,17 @@ void ANNCheckOptionClassesFrom(Class root);
 /// These over a copy of `defaults`; neither changes.
 - (instancetype)withDefault:(nullable ANNOptions *)defaults;
 
+/// A group of the same class with the same options, field by field at any depth: two reads of the same JSON, a copy,
+/// two resolutions of the same layers. The fields are the field table's; a module's group (an empty table) compares
+/// every property of an options kind it declares. A value that is nil is the same only as nil.
+///
+/// Not `isEqual:`: a group changes in place (a merge, the pick of a menu's item), so a hash by value would move under
+/// a set or a dictionary that holds it. `==` and `isEqual:` stay identity.
+- (BOOL)isSameValueAs:(nullable ANNOptions *)other;
+
+/// A hash consistent with `isSameValueAs:`; it changes when the group does.
+- (NSUInteger)valueHash;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Options/ANNOptions.mm

@@ -11,7 +11,6 @@ NSDictionary *ANNOptionsDictionary(NSDictionary *dict, NSString *key) {
     return [value isKindOfClass:NSDictionary.class] ? value : nil;
 }
 
-#if DEBUG
 // The kinds of property a group holds options in.
 static BOOL ANNIsOptionClass(Class cls) {
     return [cls isSubclassOfClass:ANNParam.class] || [cls isSubclassOfClass:ANNOptions.class] ||
@@ -33,6 +32,7 @@ static Class ANNPropertyClass(objc_property_t property) {
     return name ? NSClassFromString(name) : nil;
 }
 
+#if DEBUG
 // There is no iOS test target: in development each group of the core checks once that its table names every property
 // that holds options, and that every field of the table has its property (the stand-in for the whole-tree test of
 // Android). A missing field would be neither read, merged, copied nor given defaults.
@@ -86,6 +86,94 @@ static NSArray<ANNOptionField *> *ANNFieldsOf(Class cls) {
     }
 }
 
+// The properties that hold the options of a group, asked once per class: its field table's, or for a module's group
+// (its own read and merge, an empty table) every property of an options kind its classes declare up to `ANNOptions`.
+static NSArray<NSString *> *ANNValuePropertiesOf(Class cls) {
+    static NSMutableDictionary<NSString *, NSArray<NSString *> *> *propertiesByClass;
+    NSString *name = NSStringFromClass(cls);
+    @synchronized(ANNOptions.class) {
+        if (!propertiesByClass) {
+            propertiesByClass = [NSMutableDictionary new];
+        }
+        NSArray<NSString *> *names = propertiesByClass[name];
+        if (names) {
+            return names;
+        }
+    }
+    NSArray<ANNOptionField *> *fields = ANNFieldsOf(cls);
+    NSMutableArray<NSString *> *found = [NSMutableArray new];
+    if (fields.count) {
+        for (ANNOptionField *field in fields) {
+            [found addObject:field.property];
+        }
+    } else {
+        NSSet<NSString *> *inherited =
+            [NSSet setWithArray:@[ @"description", @"debugDescription" ]];
+        for (Class current = cls; current && current != ANNOptions.class;
+             current = class_getSuperclass(current)) {
+            unsigned int count = 0;
+            objc_property_t *properties = class_copyPropertyList(current, &count);
+            for (unsigned int i = 0; i < count; i++) {
+                NSString *property = @(property_getName(properties[i]));
+                Class propertyClass = ANNPropertyClass(properties[i]);
+                if (propertyClass && ANNIsOptionClass(propertyClass) &&
+                    ![inherited containsObject:property] && ![found containsObject:property]) {
+                    [found addObject:property];
+                }
+            }
+            free(properties);
+        }
+    }
+    NSArray<NSString *> *names = [found copy];
+    @synchronized(ANNOptions.class) {
+        propertiesByClass[name] = names;
+    }
+    return names;
+}
+
+BOOL ANNOptionValuesSame(id a, id b) {
+    if (a == b) {
+        return YES;
+    }
+    if ([a isKindOfClass:ANNParam.class]) {
+        return [b isKindOfClass:ANNParam.class] && [(ANNParam *)a isSameValueAs:b];
+    }
+    if ([a isKindOfClass:ANNOptions.class]) {
+        return [b isKindOfClass:ANNOptions.class] && [(ANNOptions *)a isSameValueAs:b];
+    }
+    if ([a isKindOfClass:NSArray.class]) {
+        if (![b isKindOfClass:NSArray.class] || [a count] != [b count]) {
+            return NO;
+        }
+        NSArray *items = b;
+        NSUInteger index = 0;
+        for (id item in (NSArray *)a) {
+            if (!ANNOptionValuesSame(item, items[index++])) {
+                return NO;
+            }
+        }
+        return YES;
+    }
+    return ANNJSONValuesSame(a, b);
+}
+
+NSUInteger ANNOptionValueHash(id value) {
+    if ([value isKindOfClass:ANNParam.class]) {
+        return [(ANNParam *)value valueHash];
+    }
+    if ([value isKindOfClass:ANNOptions.class]) {
+        return [(ANNOptions *)value valueHash];
+    }
+    if ([value isKindOfClass:NSArray.class]) {
+        NSUInteger hash = [value count];
+        for (id item in value) {
+            hash = hash * 31 + ANNOptionValueHash(item);
+        }
+        return hash;
+    }
+    return ANNJSONValueHash(value);
+}
+
 #if DEBUG
 // Runs the check on `root` and on every class reached through its group and group-array fields, so a class that only
 // an array holds (a button, an action of a fab, a token of the search bar) is checked although no object of it is made.
@@ -326,4 +414,27 @@ static NSArray *ANNCopyItems(NSArray *items) {
     return result;
 }
 
+- (BOOL)isSameValueAs:(ANNOptions *)other {
+    if (other == self) {
+        return YES;
+    }
+    if (other.class != self.class) {
+        return NO;
+    }
+    for (NSString *property in ANNValuePropertiesOf(self.class)) {
+        if (!ANNOptionValuesSame([self valueForKey:property], [other valueForKey:property])) {
+            return NO;
+        }
+    }
+    return YES;
+}
+
+- (NSUInteger)valueHash {
+    NSUInteger hash = (NSUInteger)(__bridge void *)self.class;
+    for (NSString *property in ANNValuePropertiesOf(self.class)) {
+        hash = hash * 31 + ANNOptionValueHash([self valueForKey:property]);
+    }
+    return hash;
+}
+
 @end

package/ios/Options/ANNOptionsReader.mm

@@ -1,12 +1,121 @@
 #import "ANNOptionsReader.h"
 #import "ANNAssert.h"
 #import "ANNNavigationOptions.h"
+#if DEBUG
+#import <React/RCTLog.h>
+#endif
 
 // The parse runs on the main queue, one tree at a time: the path and the first failure are its state. A group read
 // outside a parse (a module that reads its own JSON) finds an empty path and keeps no failure.
 static NSMutableArray<NSString *> *ANNPathComponents;
 static NSString *ANNFirstFailure;
 
+#if DEBUG
+// A deep mutable copy of `json` with `value` at `path` (keys, and indexes of arrays); nil `value` removes the key.
+static id ANNJSONWith(id json, NSArray *path, id value) {
+    if (path.count == 0) {
+        return value;
+    }
+    NSArray *rest = [path subarrayWithRange:NSMakeRange(1, path.count - 1)];
+    if ([json isKindOfClass:NSArray.class]) {
+        NSMutableArray *items = [json mutableCopy];
+        NSUInteger index = [path[0] unsignedIntegerValue];
+        items[index] = ANNJSONWith(items[index], rest, value);
+        return items;
+    }
+    NSMutableDictionary *fields = [json mutableCopy];
+    id inner = ANNJSONWith(fields[path[0]], rest, value);
+    if (inner) {
+        fields[path[0]] = inner;
+    } else {
+        [fields removeObjectForKey:path[0]];
+    }
+    return fields;
+}
+
+// There is no iOS test target: in development the value equality of the options (`isSameValueAs:`) checks itself
+// once on a tree with a value of each kind: two reads, a copy and a merge give the same options and the same hash, and
+// a change of one value at any depth gives other options. A module's group (the menu) compares by its properties.
+static void ANNCheckSameValues(void) {
+    NSDictionary *button = @{
+        @"id" : @"save",
+        @"text" : @"Save",
+        @"icon" : @{@"system" : @"star"},
+        @"enabled" : @YES,
+        @"badge" : @1,
+        @"fontSize" : @15,
+        @"menu" : @{
+            @"title" : @"More",
+            @"items" : @[ @{@"id" : @"details", @"title" : @"Details", @"checked" : @YES} ],
+        },
+    };
+    NSDictionary *json = @{
+        @"topBar" : @{
+            @"title" : @{@"text" : @"Home", @"color" : @(0xFF112233)},
+            @"rightButtonColor" :
+                @{@"dynamic" : @{@"light" : @(0xFF000000), @"dark" : @(0xFFFFFFFF)}},
+            @"leftButtonColor" : NSNull.null,
+            @"rightButtons" : @[ button ],
+            @"leftButtons" : @[],
+            @"height" : @44,
+        },
+        @"keyCommands" : @[ @{@"input" : @"k", @"modifiers" : @[ @"command" ]} ],
+    };
+    ANNNavigationOptions *options = [[ANNNavigationOptions alloc] initWithDict:json];
+    ANNNavigationOptions *again = [[ANNNavigationOptions alloc] initWithDict:json];
+    ANNNavigationOptions *copy = [options copy];
+    ANNNavigationOptions *overEmpty = [options withDefault:[ANNNavigationOptions new]];
+    for (ANNNavigationOptions *same in @[ again, copy, overEmpty ]) {
+        if (![options isSameValueAs:same] || options.valueHash != same.valueHash) {
+            RCTLogError(@"[ApexNavigation] options read, copied or resolved from the same JSON are "
+                        @"not the same value");
+        }
+    }
+    // Each change: the path of one value and its new value; an unset key is not the same as `null` or `[]`.
+    NSDictionary<NSString *, NSArray *> *changes = @{
+        @"a text" : @[ @[ @"topBar", @"title", @"text" ], @"Profile" ],
+        @"a color" : @[ @[ @"topBar", @"title", @"color" ], @(0xFF112234) ],
+        @"a side of a color pair" :
+            @[ @[ @"topBar", @"rightButtonColor", @"dynamic", @"dark" ], @(0xFFEEEEEE) ],
+        @"a number" : @[ @[ @"topBar", @"height" ], @45 ],
+        @"an image" : @[ @[ @"topBar", @"rightButtons", @0, @"icon", @"system" ], @"heart" ],
+        @"a boolean" : @[ @[ @"topBar", @"rightButtons", @0, @"enabled" ], @NO ],
+        @"a boolean for a number" : @[ @[ @"topBar", @"rightButtons", @0, @"badge" ], @YES ],
+        @"a font" : @[ @[ @"topBar", @"rightButtons", @0, @"fontSize" ], @16 ],
+        @"a module's group" :
+            @[ @[ @"topBar", @"rightButtons", @0, @"menu", @"items", @0, @"checked" ], @NO ],
+        @"an object of an array" : @[ @[ @"keyCommands", @0, @"modifiers", @0 ], @"shift" ],
+    };
+    NSDictionary<NSString *, NSArray *> *removals = @{
+        @"a color of `null` and no color" : @[ @"topBar", @"leftButtonColor" ],
+        @"an empty array and no array" : @[ @"topBar", @"leftButtons" ],
+    };
+    NSMutableDictionary<NSString *, id> *variants = [NSMutableDictionary new];
+    [changes enumerateKeysAndObjectsUsingBlock:^(NSString *what, NSArray *change, BOOL *stop) {
+      variants[what] = ANNJSONWith(json, change[0], change[1]);
+    }];
+    [removals enumerateKeysAndObjectsUsingBlock:^(NSString *what, NSArray *path, BOOL *stop) {
+      variants[what] = ANNJSONWith(json, path, nil);
+    }];
+    [variants enumerateKeysAndObjectsUsingBlock:^(NSString *what, NSDictionary *variant,
+                                                  BOOL *stop) {
+      ANNNavigationOptions *changed = [[ANNNavigationOptions alloc] initWithDict:variant];
+      if ([options isSameValueAs:changed] || [changed isSameValueAs:options]) {
+          RCTLogError(@"[ApexNavigation] options that differ in %@ are the same value", what);
+      }
+    }];
+    ANNNavigationOptions *merged = [options copy];
+    [merged mergeOptions:[[ANNNavigationOptions alloc]
+                             initWithDict:@{@"topBar" : @{@"title" : @{@"text" : @"Profile"}}}]];
+    ANNNavigationOptions *read = [[ANNNavigationOptions alloc]
+        initWithDict:ANNJSONWith(json, @[ @"topBar", @"title", @"text" ], @"Profile")];
+    if (![merged isSameValueAs:read] || merged.valueHash != read.valueHash) {
+        RCTLogError(@"[ApexNavigation] merged options are not the same value as the same options "
+                    @"read at once");
+    }
+}
+#endif
+
 @implementation ANNOptionsReader
 
 + (ANNNavigationOptions *)optionsFrom:(NSDictionary *)json unreadablePath:(NSString **)unreadablePath {
@@ -15,6 +124,7 @@ static NSString *ANNFirstFailure;
     static dispatch_once_t checkOnce;
     dispatch_once(&checkOnce, ^{
       ANNCheckOptionClassesFrom(ANNNavigationOptions.class);
+      ANNCheckSameValues();
     });
 #endif
     NSMutableArray<NSString *> *outerPath = ANNPathComponents;

package/ios/Options/Params/ANNParam.h

@@ -8,6 +8,14 @@ BOOL ANNJSONIsBoolean(id _Nullable value);
 /// A JSON number that is finite: never a boolean, `NaN` or an infinity.
 BOOL ANNJSONIsNumber(id _Nullable value);
 
+/// Two values as the options keep them are the same: a boolean is never the same as a number, arrays and objects
+/// compare item by item, anything else (a string, a number, `null`, a color) by `isEqual:`. nil is the same only as
+/// nil.
+BOOL ANNJSONValuesSame(id _Nullable a, id _Nullable b);
+
+/// A hash of a value `ANNJSONValuesSame` compares: values that are the same have the same hash.
+NSUInteger ANNJSONValueHash(id _Nullable value);
+
 /// One value of the options as the JSON gave it. Immutable: trees of options may share it. `null` is a value too where
 /// the kind has an explicit "none" (a text, a color): it takes the place of what the layers under it gave.
 @interface ANNParam : NSObject
@@ -23,6 +31,13 @@ BOOL ANNJSONIsNumber(id _Nullable value);
 /// The options gave `null`.
 - (BOOL)isNull;
 
+/// A param of the same class with the same value: two reads of the same JSON are the same, two params without a value
+/// are the same. `==` and `isEqual:` stay identity.
+- (BOOL)isSameValueAs:(nullable ANNParam *)other;
+
+/// A hash consistent with `isSameValueAs:`.
+- (NSUInteger)valueHash;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Options/Params/ANNParam.mm

@@ -9,6 +9,56 @@ BOOL ANNJSONIsNumber(id value) {
     return [value isKindOfClass:NSNumber.class] && !ANNJSONIsBoolean(value) && isfinite([value doubleValue]);
 }
 
+BOOL ANNJSONValuesSame(id a, id b) {
+    if (a == b) {
+        return YES;
+    }
+    if (!a || !b) {
+        return NO;
+    }
+    if ([a isKindOfClass:NSArray.class]) {
+        if (![b isKindOfClass:NSArray.class] || [a count] != [b count]) {
+            return NO;
+        }
+        NSArray *items = b;
+        __block BOOL same = YES;
+        [(NSArray *)a enumerateObjectsUsingBlock:^(id item, NSUInteger index, BOOL *stop) {
+          same = ANNJSONValuesSame(item, items[index]);
+          *stop = !same;
+        }];
+        return same;
+    }
+    if ([a isKindOfClass:NSDictionary.class]) {
+        if (![b isKindOfClass:NSDictionary.class] || [a count] != [b count]) {
+            return NO;
+        }
+        NSDictionary *fields = b;
+        __block BOOL same = YES;
+        [(NSDictionary *)a enumerateKeysAndObjectsUsingBlock:^(id key, id value, BOOL *stop) {
+          same = ANNJSONValuesSame(value, fields[key]);
+          *stop = !same;
+        }];
+        return same;
+    }
+    // `isEqual:` of NSNumber takes `true` for 1: a badge of `true` (a dot) and of `1` (a number) are not the same.
+    if (ANNJSONIsBoolean(a) != ANNJSONIsBoolean(b)) {
+        return NO;
+    }
+    return [a isEqual:b];
+}
+
+// An object's hash is its count only (Foundation's); an array mixes its items in, so lists of other values differ.
+NSUInteger ANNJSONValueHash(id value) {
+    if ([value isKindOfClass:NSArray.class]) {
+        NSUInteger hash = [value count];
+        for (id item in value) {
+            hash = hash * 31 + ANNJSONValueHash(item);
+        }
+        return hash;
+    }
+    return [value hash];
+}
+
 @implementation ANNParam
 
 - (instancetype)initWithValue:(id)value {
@@ -26,4 +76,15 @@ BOOL ANNJSONIsNumber(id value) {
     return _value == NSNull.null;
 }
 
+- (BOOL)isSameValueAs:(ANNParam *)other {
+    if (other == self) {
+        return YES;
+    }
+    return other.class == self.class && ANNJSONValuesSame(_value, other.value);
+}
+
+- (NSUInteger)valueHash {
+    return ANNJSONValueHash(_value);
+}
+
 @end

package/ios/Options/Params/Color.h

@@ -38,6 +38,9 @@ NS_ASSUME_NONNULL_BEGIN
 /// A pair that has only one of its sides.
 - (BOOL)isPartial;
 
+/// The same color: a pair by its sides (its dynamic color is made anew at each read), anything else by its value.
+- (BOOL)isSameValueAs:(nullable ANNParam *)other;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Options/Params/Color.mm

@@ -40,6 +40,27 @@
     return [super get];
 }
 
+- (BOOL)isSameValueAs:(ANNParam *)other {
+    if (other == self) {
+        return YES;
+    }
+    if (other.class != self.class) {
+        return NO;
+    }
+    Color *color = (Color *)other;
+    if (_light || _dark || color.light || color.dark) {
+        return ANNJSONValuesSame(_light, color.light) && ANNJSONValuesSame(_dark, color.dark);
+    }
+    return [super isSameValueAs:other];
+}
+
+- (NSUInteger)valueHash {
+    if (_light || _dark) {
+        return _light.hash * 31 + _dark.hash;
+    }
+    return [super valueHash];
+}
+
 - (UIColor *)withDefault:(UIColor *)defaultValue {
     if (!self.isPartial) {
         return self.hasValue ? self.get : defaultValue;

package/ios/Options/Params/Image.h

@@ -19,6 +19,10 @@ NS_ASSUME_NONNULL_BEGIN
 /// What the options name; nil without a value.
 @property(nonatomic, strong, readonly, nullable) ANNImageSource *source;
 
+/// The same image the options name: a source by its `sourceKey` (what a file holds now isn't compared, so a file the
+/// app writes again at the same path is the same value), an image that came already by identity.
+- (BOOL)isSameValueAs:(nullable ANNParam *)other;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Options/Params/Image.mm

@@ -17,6 +17,26 @@
     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 {
     UIImage *image = self.hasValue ? self.get : nil;