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

package/ios/Options/Params/ANNImageSource.mm

@@ -0,0 +1,101 @@
+#import "ANNImageSource.h"
+
+// The path of a `file:` source the app may write again: a file outside the app's bundle (documents, caches, a temporary
+// folder); nil for any other source. The bundle's files and assets don't change while the app runs.
+static NSString *ANNWritablePathOf(ANNImageSourceKind kind, NSURL *url) {
+    if (kind != ANNImageSourceKindFile || !url.isFileURL) {
+        return nil;
+    }
+    NSString *path = url.path;
+    NSString *bundle = NSBundle.mainBundle.bundlePath;
+    if (!path.isAbsolutePath || [path isEqualToString:bundle] ||
+        [path hasPrefix:[bundle stringByAppendingString:@"/"]]) {
+        return nil;
+    }
+    return path;
+}
+
+// The modification date and size of the file at `path` (else of its `.png`, as the loader looks for it), or nil.
+static NSString *ANNFileStampOf(NSString *path) {
+    NSFileManager *files = NSFileManager.defaultManager;
+    NSDictionary<NSFileAttributeKey, id> *attributes = [files attributesOfItemAtPath:path
+                                                                                error:nil];
+    if (!attributes && path.pathExtension.length == 0) {
+        attributes = [files attributesOfItemAtPath:[path stringByAppendingPathExtension:@"png"]
+                                             error:nil];
+    }
+    NSDate *modified = attributes.fileModificationDate;
+    if (!modified) {
+        return nil;
+    }
+    return [NSString stringWithFormat:@"%.6f|%llu", modified.timeIntervalSinceReferenceDate,
+                                      attributes.fileSize];
+}
+
+@implementation ANNImageSource {
+    // The key without the file's stamp, and the path whose stamp joins it.
+    NSString *_baseKey;
+    NSString *_writablePath;
+}
+
++ (instancetype)symbolNamed:(NSString *)name fallback:(ANNImageSource *)fallback {
+    ANNImageSource *source = [[self alloc] initWithKind:ANNImageSourceKindSymbol
+                                                    url:nil
+                                                address:name
+                                                  scale:0
+                                                  width:0
+                                                 height:0];
+    source->_symbolName = [name copy];
+    source->_fallback = fallback;
+    return source;
+}
+
++ (instancetype)sourceOfKind:(ANNImageSourceKind)kind
+                         url:(NSURL *)url
+                     address:(NSString *)address
+                       scale:(CGFloat)scale
+                       width:(CGFloat)width
+                      height:(CGFloat)height {
+    return [[self alloc] initWithKind:kind
+                                  url:url
+                              address:address
+                                scale:scale
+                                width:width
+                               height:height];
+}
+
+- (instancetype)initWithKind:(ANNImageSourceKind)kind
+                         url:(NSURL *)url
+                     address:(NSString *)address
+                       scale:(CGFloat)scale
+                       width:(CGFloat)width
+                      height:(CGFloat)height {
+    if (self = [super init]) {
+        _kind = kind;
+        _url = url;
+        _address = [address copy];
+        _scale = scale;
+        _width = width;
+        _height = height;
+        _baseKey = [NSString stringWithFormat:@"%g|%g|%@", scale, width, _address];
+        _writablePath = ANNWritablePathOf(kind, url);
+    }
+    return self;
+}
+
+// Read at each ask: a file the app writes again at the same path is another image.
+- (NSString *)key {
+    NSString *stamp = _writablePath ? ANNFileStampOf(_writablePath) : nil;
+    return stamp ? [NSString stringWithFormat:@"%@|%@", _baseKey, stamp] : _baseKey;
+}
+
+- (NSString *)sourceKey {
+    NSString *own = [NSString stringWithFormat:@"%ld|%@", (long)_kind, _baseKey];
+    return _fallback ? [NSString stringWithFormat:@"%@|%@", own, _fallback.sourceKey] : own;
+}
+
+- (BOOL)loadsLater {
+    return _kind == ANNImageSourceKindFile || _kind == ANNImageSourceKindData;
+}
+
+@end

package/ios/Options/Params/ANNOptionImages.h

@@ -0,0 +1,37 @@
+#import "ANNImageSource.h"
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The images of the options, every one of them (bar buttons and their menus, the back button, tab icons, search
+/// tokens and suggestions): one cache for the app, by the source's key (`NSCache`, its cost the image's bytes, let go
+/// at a memory warning). The images don't depend on the JavaScript, so a reload keeps them.
+///
+/// Every decode runs on one serial queue of the loader: `imageOf:` waits for it, `loadLater:done:` doesn't. A failure
+/// (a missing file, data that isn't an image or doesn't decode, an exception while decoding) never throws: no image,
+/// and one warning per address in the log. It is not cached, as on Android: it answers for a moment (1 s, the reads of
+/// one apply), then the next read tries again, so a file written later or Metro's server back shows.
+@interface ANNOptionImages : NSObject
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The image of `source`: a symbol, what the cache has, or else loaded before this returns; nil on a failure. Any
+/// thread.
++ (nullable UIImage *)imageOf:(ANNImageSource *)source;
+
+/// The cache doesn't have the image of `source`, it didn't fail a moment ago, and it loads off the main queue
+/// (`loadsLater` of the source): what `loadLater:done:` doesn't give at once. Any thread.
++ (BOOL)loadsLater:(ANNImageSource *)source;
+
+/// Loads `source` on the loader's queue and gives `done` the image, or nil on a failure, on the main queue; one load
+/// for every caller that asks for the same image meanwhile. What the cache has, or what doesn't load off the main
+/// queue, comes at once, before this returns. Main queue.
++ (void)loadLater:(ANNImageSource *)source done:(void (^)(UIImage *_Nullable image))done;
+
+/// Lets every image of the cache go. Any thread.
++ (void)clear;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/Options/Params/ANNOptionImages.mm

@@ -0,0 +1,284 @@
+#import "ANNOptionImages.h"
+#import <React/RCTAssert.h>
+#import <React/RCTLog.h>
+#import <React/RCTUtils.h>
+
+// The options' icons are small: 16 MB of decoded pixels holds hundreds of them.
+static const NSUInteger ANNOptionImagesCostLimit = 16 * 1024 * 1024;
+
+// The longest piece of an address a warning names (a `data:` address is the whole image).
+static const NSUInteger ANNOptionImagesLoggedAddressLength = 80;
+
+// How long a failure answers for its source without a new try: the many reads of one apply ask once, a later apply
+// tries again (a file written since, Metro's server back).
+static const NSTimeInterval ANNOptionImagesFailureMoment = 1;
+
+static const void *ANNOptionImagesQueueKey = &ANNOptionImagesQueueKey;
+
+static NSCache<NSString *, UIImage *> *ANNCache;
+static dispatch_queue_t ANNQueue;
+// The addresses already named in a warning: one each.
+static NSMutableSet<NSString *> *ANNWarned;
+// The keys whose last try failed, with the system's uptime then; guarded by itself. Failures never go into the cache.
+static NSMutableDictionary<NSString *, NSNumber *> *ANNFailures;
+// The loads off the main queue under way, with who waits for each. Main queue.
+static NSMutableDictionary<NSString *, NSMutableArray *> *ANNLoading;
+
+static void ANNSetUp(void) {
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      ANNCache = [NSCache new];
+      ANNCache.name = @"ApexNavigation option images";
+      ANNCache.totalCostLimit = ANNOptionImagesCostLimit;
+      dispatch_queue_attr_t attributes = dispatch_queue_attr_make_with_qos_class(
+          DISPATCH_QUEUE_SERIAL, QOS_CLASS_USER_INITIATED, 0);
+      ANNQueue = dispatch_queue_create("dev.apexnative.navigation.images", attributes);
+      dispatch_queue_set_specific(ANNQueue, ANNOptionImagesQueueKey,
+                                  (void *)ANNOptionImagesQueueKey, NULL);
+      ANNWarned = [NSMutableSet new];
+      ANNFailures = [NSMutableDictionary new];
+      ANNLoading = [NSMutableDictionary new];
+      NSNotificationCenter *center = NSNotificationCenter.defaultCenter;
+      [center addObserverForName:UIApplicationDidReceiveMemoryWarningNotification
+                          object:nil
+                           queue:nil
+                      usingBlock:^(NSNotification *notification) {
+                        [ANNCache removeAllObjects];
+                      }];
+    });
+}
+
+// The bytes of the decoded image, the cost the cache weighs it with.
+static NSUInteger ANNBytesOf(UIImage *image) {
+    CGImageRef cgImage = image.CGImage;
+    if (cgImage) {
+        return CGImageGetBytesPerRow(cgImage) * CGImageGetHeight(cgImage);
+    }
+    CGFloat width = image.size.width * image.scale;
+    CGFloat height = image.size.height * image.scale;
+    return (NSUInteger)MAX(1, width * height * 4);
+}
+
+static void ANNWarnOnce(ANNImageSource *source, NSString *why) {
+    @synchronized(ANNWarned) {
+        if ([ANNWarned containsObject:source.address]) {
+            return;
+        }
+        [ANNWarned addObject:source.address];
+    }
+    NSString *address = source.address;
+    if (address.length > ANNOptionImagesLoggedAddressLength) {
+        address = [[address substringToIndex:ANNOptionImagesLoggedAddressLength]
+            stringByAppendingString:@"…"];
+    }
+    RCTLogWarn(@"[ApexNavigation] could not load the image %@: %@", address, why);
+}
+
+// The last try of `key` failed a moment ago.
+static BOOL ANNFailedJustNow(NSString *key) {
+    @synchronized(ANNFailures) {
+        NSNumber *at = ANNFailures[key];
+        if (!at) {
+            return NO;
+        }
+        NSTimeInterval since = NSProcessInfo.processInfo.systemUptime - at.doubleValue;
+        if (since < ANNOptionImagesFailureMoment) {
+            return YES;
+        }
+        [ANNFailures removeObjectForKey:key];
+        return NO;
+    }
+}
+
+static void ANNSetFailed(NSString *key, BOOL failed) {
+    @synchronized(ANNFailures) {
+        if (failed) {
+            ANNFailures[key] = @(NSProcessInfo.processInfo.systemUptime);
+        } else {
+            [ANNFailures removeObjectForKey:key];
+        }
+    }
+}
+
+// A file at the address: an image with nothing but its pixels, which can be decoded ahead. An asset of a catalog
+// (found by name) may have a dark variant, which a decoded copy would lose.
+static BOOL ANNIsFileAt(NSURL *url) {
+    NSString *path = url.path;
+    if (path.length == 0) {
+        return NO;
+    }
+    NSFileManager *files = NSFileManager.defaultManager;
+    if ([files fileExistsAtPath:path]) {
+        return YES;
+    }
+    return path.pathExtension.length == 0 &&
+           [files fileExistsAtPath:[path stringByAppendingPathExtension:@"png"]];
+}
+
+@implementation ANNOptionImages
+
++ (UIImage *)imageOf:(ANNImageSource *)source {
+    if (source.kind == ANNImageSourceKindSymbol) {
+        UIImage *symbol = [UIImage systemImageNamed:source.symbolName];
+        return symbol ?: (source.fallback ? [self imageOf:source.fallback] : nil);
+    }
+    ANNSetUp();
+    NSString *key = source.key;
+    UIImage *cached = [ANNCache objectForKey:key];
+    if (cached || ANNFailedJustNow(key)) {
+        return cached;
+    }
+    if (dispatch_get_specific(ANNOptionImagesQueueKey)) {
+        return [self loadOnQueue:source];
+    }
+    __block UIImage *image = nil;
+    dispatch_sync(ANNQueue, ^{
+      image = [self loadOnQueue:source];
+    });
+    return image;
+}
+
+// A failure of a moment ago answers at once, so an item built again when its load failed doesn't load again.
++ (BOOL)loadsLater:(ANNImageSource *)source {
+    if (!source.loadsLater) {
+        return NO;
+    }
+    ANNSetUp();
+    NSString *key = source.key;
+    return [ANNCache objectForKey:key] == nil && !ANNFailedJustNow(key);
+}
+
++ (void)loadLater:(ANNImageSource *)source done:(void (^)(UIImage *))done {
+    RCTAssertMainQueue();
+    if (![self loadsLater:source]) {
+        done([self imageOf:source]);
+        return;
+    }
+    NSString *key = source.key;
+    NSMutableArray *waiters = ANNLoading[key];
+    if (waiters) {
+        [waiters addObject:[done copy]];
+        return;
+    }
+    ANNLoading[key] = [NSMutableArray arrayWithObject:[done copy]];
+    dispatch_async(ANNQueue, ^{
+      UIImage *image = [self loadOnQueue:source];
+      dispatch_async(dispatch_get_main_queue(), ^{
+        NSArray *waiting = ANNLoading[key];
+        [ANNLoading removeObjectForKey:key];
+        for (void (^waiter)(UIImage *) in waiting) {
+            waiter(image);
+        }
+      });
+    });
+}
+
++ (void)clear {
+    ANNSetUp();
+    [ANNCache removeAllObjects];
+    @synchronized(ANNFailures) {
+        [ANNFailures removeAllObjects];
+    }
+}
+
+#pragma mark - The loader's queue
+
+// The cache again (a load that came first), else the decode. An image goes into the cache; a failure doesn't, as on
+// Android: it answers only for a moment (`ANNFailedJustNow`), and the next apply after that tries again.
++ (UIImage *)loadOnQueue:(ANNImageSource *)source {
+    NSString *key = source.key;
+    UIImage *cached = [ANNCache objectForKey:key];
+    if (cached || ANNFailedJustNow(key)) {
+        return cached;
+    }
+    NSString *failure = nil;
+    UIImage *image = nil;
+    @try {
+        image = [self decode:source failure:&failure];
+    } @catch (NSException *exception) {
+        image = nil;
+        failure = [NSString
+            stringWithFormat:@"decoding it threw %@ (%@)", exception.name, exception.reason];
+    }
+    if (!image) {
+        ANNSetFailed(key, YES);
+        ANNWarnOnce(source, failure ?: @"it can't be decoded");
+        return nil;
+    }
+    ANNSetFailed(key, NO);
+    [ANNCache setObject:image forKey:key cost:ANNBytesOf(image)];
+    return image;
+}
+
+// The image of an address, as React Native's converter of images reads it, with the scale of the source; nil with
+// what failed. A plain file and data are decoded here, so the first frame that shows them doesn't.
++ (UIImage *)decode:(ANNImageSource *)source failure:(NSString **)failure {
+    NSURL *url = source.url;
+    UIImage *image = nil;
+    BOOL decodesAhead = YES;
+    switch (source.kind) {
+    case ANNImageSourceKindFile:
+        image = RCTImageFromLocalAssetURL(url) ?: RCTImageFromLocalBundleAssetURL(url);
+        if (!image) {
+            *failure = @"there is no image at that address";
+            return nil;
+        }
+        decodesAhead = ANNIsFileAt(url);
+        break;
+    case ANNImageSourceKindData:
+    case ANNImageSourceKindMetro: {
+        // Metro's assets in development: read from the dev server, as before the cache.
+        NSError *error = nil;
+        NSData *data = url ? [NSData dataWithContentsOfURL:url options:0 error:&error] : nil;
+        if (data.length == 0) {
+            *failure = error.localizedDescription ?: @"it has no data";
+            return nil;
+        }
+        image = [UIImage imageWithData:data];
+        if (!image) {
+            *failure = @"its data is not an image";
+            return nil;
+        }
+        break;
+    }
+    case ANNImageSourceKindSymbol:
+        return nil;
+    }
+    // An image UIKit can't prepare (16 bits a channel, CMYK) it still draws: it stays as it is then, decoded when it
+    // first shows.
+    UIImage *decoded = decodesAhead ? [image imageByPreparingForDisplay] : nil;
+    if (decoded) {
+        image = decoded.CGImage ? [UIImage imageWithCGImage:decoded.CGImage
+                                                      scale:image.scale
+                                                orientation:image.imageOrientation]
+                                : decoded;
+    }
+    if (!(image.size.width > 0) || !(image.size.height > 0)) {
+        *failure = @"it is empty";
+        return nil;
+    }
+    return [self image:image scaledBy:source];
+}
+
+// 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:(ANNImageSource *)source {
+    CGFloat scale = source.scale;
+    CGFloat width = source.width;
+    CGFloat height = source.height;
+    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;
+}
+
+@end

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/ColorParser.h

@@ -2,9 +2,10 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// Reads `key` of the options' JSON as a color, in the forms JS sends on iOS: an ARGB number, `{ dynamic: { light, dark
-/// } }` with a number or a platform color on each side, `{ semantic: [...] }`, and `'NoColor'` (or `null`) for "no
-/// color". A value it can't read is no value and a warning in development.
+/// Reads `key` of the options' JSON as a color, in the forms JS sends on iOS: an ARGB number, `{ light, dark }` (or an
+/// app's `DynamicColorIOS`, `{ dynamic: { light, dark } }`) with a number or a platform color on each side,
+/// `{ semantic: [...] }`, and `'NoColor'` (or `null`) for "no color". A value it can't read is no value and a warning
+/// in development.
 @interface ColorParser : NSObject
 
 + (Color *)parse:(nullable NSDictionary *)json key:(NSString *)key;

package/ios/Options/Params/ColorParser.mm

@@ -49,6 +49,24 @@ static UIColor *ANNOneColor(id value) {
     return nil;
 }
 
+// A pair comes as `{ light, dark }`, either side may be left out; an app's own `DynamicColorIOS` as
+// `{ dynamic: { light, dark } }`. Anything else is not a pair.
+static NSDictionary *ANNColorPair(id value) {
+    if (![value isKindOfClass:NSDictionary.class]) {
+        return nil;
+    }
+    id dynamic = value[@"dynamic"];
+    if (dynamic) {
+        return [dynamic isKindOfClass:NSDictionary.class] ? dynamic : nil;
+    }
+    for (id side in value) {
+        if (![side isEqual:@"light"] && ![side isEqual:@"dark"]) {
+            return nil;
+        }
+    }
+    return value;
+}
+
 @implementation ColorParser
 
 + (Color *)parse:(NSDictionary *)json key:(NSString *)key {
@@ -64,8 +82,8 @@ static UIColor *ANNOneColor(id value) {
         return [[Color alloc] initWithColor:color];
     }
     NSString *path = [ANNOptionsReader pathOfKey:key];
-    NSDictionary *pair = [value isKindOfClass:NSDictionary.class] ? value[@"dynamic"] : nil;
-    if ([pair isKindOfClass:NSDictionary.class]) {
+    NSDictionary *pair = ANNColorPair(value);
+    if (pair) {
         UIColor *light = [self side:pair[@"light"] name:@"light" path:path];
         UIColor *dark = [self side:pair[@"dark"] name:@"dark" path:path];
         if (light || dark) {
@@ -77,8 +95,8 @@ static UIColor *ANNOneColor(id value) {
     return [[Color alloc] initWithValue:nil];
 }
 
-// A side of `{ dynamic: { light, dark } }`. A side that is not there is a partial pair and is silent (the sides are
-// optional); a side that is there but can't be read is missing too, with a warning.
+// A side of `{ light, dark }`. A side that is not there is a partial pair and is silent (the sides are optional); a
+// side that is there but can't be read is missing too, with a warning.
 + (UIColor *)side:(id)value name:(NSString *)name path:(NSString *)path {
     if (!value || value == NSNull.null) {
         return nil;

package/ios/Options/Params/Image.h

@@ -1,15 +1,28 @@
+#import "ANNImageSource.h"
 #import "Param.h"
 #import <UIKit/UIKit.h>
 
 NS_ASSUME_NONNULL_BEGIN
 
-/// An image of the options, loaded when the options were read. An image that didn't load is no value: the element shows
-/// without it.
+/// An image of the options: its source, read with the options, and the image, loaded when an element asks for it
+/// through the shared cache (`ANNOptionImages`). A source that doesn't load is no image: the element shows without it.
+/// A value that is a `UIImage` is that image, with no source: an element made again from an image that came already
+/// (a tab's icon loaded off the main queue) doesn't ask the cache again.
 @interface Image : Param
 
+/// The image, loaded at once when the cache doesn't have it; nil without a source and when it doesn't load.
 - (nullable UIImage *)get;
+/// The image, or `defaultValue` without a source and when it doesn't load. `hasValue` says only that the options name
+/// an image: a choice between an image and what shows without one reads the image itself.
 - (nullable UIImage *)withDefault:(nullable UIImage *)defaultValue;
 
+/// 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