react-native-fast-image 10.3.0 → 10.5.0

package/ios/FastImage/FFFastImageView.m

@@ -4,6 +4,7 @@
 #import <React/RCTUtils.h>
 #import <SDWebImage/SDWebImageError.h>
 #import <SDWebImage/SDImageTransformer.h>
+#import <SDWebImage/SDImageCodersManager.h>
 #import "FFFDownsampledImage.h"
 #import "FFFThumbHash.h"
 #import "FFFBoxBlur.h"
@@ -69,10 +70,23 @@
 // shownPlaceholder).
 @property(nonatomic, strong) UIImage* hashImage;
 @property(nonatomic, copy) NSString* hashImageKey;
-// Whether the view shows its placeholder (the placeholder prop or the
-// source's), and whether that's the source's (hashImage).
+// placeholderSource's image once it has loaded, or nil: it shows instead of
+// the other placeholders (see shownPlaceholder). Its load, and which it is.
+@property(nonatomic, strong) UIImage* urlPlaceholderImage;
+@property(nonatomic, strong) id<SDWebImageOperation> urlPlaceholderOperation;
+@property(nonatomic, assign) NSUInteger urlPlaceholderLoad;
+// placeholderSource changed: its load starts with the image's, or after the
+// props if the image is still loading (see startUrlPlaceholderLoad).
+@property(nonatomic, assign) BOOL needsUrlPlaceholderLoad;
+// Whether the view shows a placeholder (the placeholder prop, the source's,
+// or placeholderSource's), and whether it stands for the image (the source's
+// or placeholderSource's): drawn as with contain for scale-down and none, as
+// the image's size isn't known yet, scaled smoothly and not blurred.
 @property(nonatomic, assign) BOOL showsPlaceholder;
 @property(nonatomic, assign) BOOL showsHash;
+// dynamicRangeLimit switched between HDR and SDR: the image is decoded again,
+// quietly (see reloadForDynamicRange).
+@property(nonatomic, assign) BOOL needsDynamicRangeReload;
 
 @end
 
@@ -440,7 +454,7 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
 
 - (void) setImage: (UIImage*)image {
     self.imageCount++;
-    self.showsHash = image != nil && image == self.hashImage;
+    self.showsHash = image != nil && (image == self.hashImage || image == self.urlPlaceholderImage);
     self.showsPlaceholder = self.showsHash || (image != nil && image == _placeholder);
     if ([_imageRendering isEqualToString: @"pixelated"]) {
         // A source's placeholder is a blurred preview, scaled up smoothly
@@ -536,7 +550,7 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
 // Whether the image is blurred: a loaded image, not the placeholder prop (as
 // with React Native's Image, and on Android).
 - (BOOL) blurs: (UIImage*)image {
-    return _blurRadius > 0 && image && image != _placeholder && image != self.hashImage;
+    return _blurRadius > 0 && image && image != _placeholder && image != self.hashImage && image != self.urlPlaceholderImage;
 }
 
 // Blurs the image off the main thread, and shows it (tinted as any image) unless
@@ -643,6 +657,14 @@ static UIImage* FFFBlurredImage(UIImage* image, CGFloat scale, CGFloat radius, B
     if (image.size.width <= 0 || image.size.height <= 0) {
         return image;
     }
+    // Blurred in standard range (the bitmap below has 8 bits per channel): an
+    // HDR image (dynamicRangeLimit) tone mapped to it, rather than its
+    // highlights clipped.
+    if (@available(iOS 17.0, tvOS 17.0, *)) {
+        if (image.isHighDynamicRange) {
+            image = [image imageRestrictedToStandardDynamicRange];
+        }
+    }
     double fullWidth = MAX(1, round(image.size.width * image.scale * scale));
     double fullHeight = MAX(1, round(image.size.height * image.scale * scale));
     // At most the image's larger side (a larger box looks the same, and an
@@ -798,6 +820,33 @@ NSString *FFFErrorMessage(NSError *error)
     }
 }
 
+- (void) setDynamicRangeLimit: (NSString*)dynamicRangeLimit {
+    if (_dynamicRangeLimit == dynamicRangeLimit || [_dynamicRangeLimit isEqualToString: dynamicRangeLimit]) {
+        return;
+    }
+    BOOL decodedToHDR = [self decodesToHDR];
+    _dynamicRangeLimit = [dynamicRangeLimit copy];
+    if (@available(iOS 17.0, tvOS 17.0, *)) {
+        // Constrained: the highlights brighter than SDR white, but not as
+        // bright as the display can go, as Apple suggests for images among
+        // other content.
+        self.preferredImageDynamicRange = [_dynamicRangeLimit isEqualToString: @"no-limit"] ? UIImageDynamicRangeHigh
+            : [_dynamicRangeLimit isEqualToString: @"constrained"] ? UIImageDynamicRangeConstrainedHigh
+            : [_dynamicRangeLimit isEqualToString: @"standard"] ? UIImageDynamicRangeStandard
+            : UIImageDynamicRangeUnspecified;
+    }
+    // Decoded again only to switch between HDR and SDR.
+    if ([self decodesToHDR] != decodedToHDR) {
+        self.needsDynamicRangeReload = YES;
+    }
+}
+
+// Whether HDR images are decoded to HDR (dynamicRangeLimit constrained or
+// no-limit), rather than to SDR, their standard range version.
+- (BOOL) decodesToHDR {
+    return [_dynamicRangeLimit isEqualToString: @"constrained"] || [_dynamicRangeLimit isEqualToString: @"no-limit"];
+}
+
 - (void) setPlaceholder: (UIImage*)placeholder {
     if (_placeholder != placeholder) {
         _placeholder = placeholder;
@@ -810,10 +859,124 @@ NSString *FFFErrorMessage(NSError *error)
     [self updateHashImage];
 }
 
-// What shows while the image loads and if it fails: the picked source's
-// placeholder (its ThumbHash or blurDataUri), or the placeholder prop.
+// What shows while the image loads and if it fails: placeholderSource's
+// image once it has loaded, the picked source's placeholder (its ThumbHash or
+// blurDataUri), or the placeholder prop.
 - (UIImage*) shownPlaceholder {
-    return self.hashImage ?: _placeholder;
+    return self.urlPlaceholderImage ?: self.hashImage ?: _placeholder;
+}
+
+// Shows the placeholder that shows now (shownPlaceholder) in place of
+// `previous` if the view showed it, or if it showed nothing (one that arrived
+// while nothing showed): never over a loaded image, or the image kept while
+// a new source loads.
+- (void) showChangedPlaceholder: (UIImage*)previous showing: (BOOL)showing {
+    UIImage* placeholder = [self shownPlaceholder];
+    if (placeholder == previous) {
+        return;
+    }
+    BOOL showsNothing = super.image == nil && !self.showsLoadedImage && !self.blursOverNothing;
+    if (showing || (placeholder && showsNothing)) {
+        [self setImage: placeholder];
+    }
+}
+
+// Images that views showed, by their source's cacheKey or url, while they're
+// still in memory (held by a view or SDWebImage's memory cache), so
+// placeholderSource finds one at once whatever size it was decoded at (the
+// memory cache's key includes the size).
++ (NSMapTable<NSString*, UIImage*>*) shownImages {
+    static NSMapTable* images;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+        images = [NSMapTable strongToWeakObjectsMapTable];
+    });
+    return images;
+}
+
+// The key a remote image (http or https) is recorded under: its cacheKey or
+// url. nil for others (data uris, files), which aren't recorded.
++ (NSString*) shownImageKey: (FFFastImageSource*)source {
+    NSString* scheme = source.url.scheme.lowercaseString;
+    if (![scheme isEqualToString: @"http"] && ![scheme isEqualToString: @"https"]) {
+        return nil;
+    }
+    return source.cacheKey.length > 0 ? source.cacheKey : source.url.absoluteString;
+}
+
++ (void) rememberShownImage: (UIImage*)image source: (FFFastImageSource*)source {
+    NSString* key = [self shownImageKey: source];
+    if (image && key) {
+        [[self shownImages] setObject: image forKey: key];
+    }
+}
+
+- (void) setPlaceholderSource: (FFFastImageSource*)placeholderSource {
+    _placeholderSource = placeholderSource;
+    [self cancelUrlPlaceholderLoad];
+    [self showUrlPlaceholderImage: nil];
+    self.needsUrlPlaceholderLoad = YES;
+}
+
+- (void) cancelUrlPlaceholderLoad {
+    self.urlPlaceholderLoad++;
+    [self.urlPlaceholderOperation cancel];
+    self.urlPlaceholderOperation = nil;
+}
+
+// Loads placeholderSource's image with the image's load (after layout, so at
+// the view's size, with the props applied), or after the image failed: not
+// if the image shows at once (from the memory cache, or a data uri), or the
+// placeholder is already loaded or loading.
+- (void) startUrlPlaceholderLoad {
+    self.needsUrlPlaceholderLoad = NO;
+    if (!_placeholderSource.url || self.urlPlaceholderImage || self.urlPlaceholderOperation) {
+        return;
+    }
+    if (_source && !self.hasErrored && [self loadsDuringLayout]) {
+        return;
+    }
+    [self loadUrlPlaceholder];
+}
+
+// Loads placeholderSource's image, as a source would load (its cache,
+// headers and cacheKey), at a high priority, as it only helps if it comes
+// before the image. One a view still shows (or that's still in memory) shows
+// at once. A failure shows nothing more.
+- (void) loadUrlPlaceholder {
+    [self cancelUrlPlaceholderLoad];
+    NSUInteger load = self.urlPlaceholderLoad;
+    FFFastImageSource* source = _placeholderSource;
+    NSString* key = [FFFastImageView shownImageKey: source];
+    UIImage* shown = key ? [[FFFastImageView shownImages] objectForKey: key] : nil;
+    if (shown) {
+        [self showUrlPlaceholderImage: shown];
+        return;
+    }
+    SDWebImageOptions options = [source cacheOptions] | SDWebImageHighPriority | SDWebImageRetryFailed | SDWebImageHandleCookies;
+    SDWebImageContext* context = [self contextForSource: source box: [self decodeBox] cover: NO];
+    __weak typeof(self) weakSelf = self;
+    self.urlPlaceholderOperation = [[SDWebImageManager sharedManager] loadImageWithURL: source.url options: options context: context progress: nil completed: ^(UIImage* _Nullable image, NSData* _Nullable data, NSError* _Nullable error, SDImageCacheType cacheType, BOOL finished, NSURL* _Nullable imageURL) {
+        if (!finished || weakSelf.urlPlaceholderLoad != load) {
+            return;
+        }
+        weakSelf.urlPlaceholderOperation = nil;
+        if (!image) {
+            return;
+        }
+        [FFFastImageView rememberShownImage: image source: source];
+        [weakSelf showUrlPlaceholderImage: image];
+    }];
+}
+
+- (void) showUrlPlaceholderImage: (UIImage*)image {
+    if (self.urlPlaceholderImage == image) {
+        return;
+    }
+    UIImage* previous = [self shownPlaceholder];
+    BOOL showing = self.showsPlaceholder;
+    self.urlPlaceholderImage = image;
+    [self showChangedPlaceholder: previous showing: showing];
 }
 
 // The picked source's ThumbHash or blurDataUri, or nil.
@@ -837,10 +1000,7 @@ NSString *FFFErrorMessage(NSError *error)
     BOOL showing = self.showsPlaceholder;
     self.hashImageKey = hash;
     self.hashImage = [FFFThumbHash imageForPlaceholder: hash];
-    UIImage* placeholder = [self shownPlaceholder];
-    if (showing && placeholder != previous) {
-        [self setImage: placeholder];
-    }
+    [self showChangedPlaceholder: previous showing: showing];
 }
 
 - (void) didSetProps {
@@ -865,9 +1025,42 @@ NSString *FFFErrorMessage(NSError *error)
             return;
         }
         [self reloadImage];
+    } else if (self.needsDynamicRangeReload) {
+        [self reloadForDynamicRange];
     } else {
         [self reloadIfResized];
     }
+    // A new placeholderSource while the image loads, or after it failed (a
+    // load waiting for the view's size starts it with the image's).
+    if (self.needsUrlPlaceholderLoad && !_needsReload && !self.waitsForSize) {
+        if (!self.hasCompleted || self.hasErrored) {
+            [self startUrlPlaceholderLoad];
+        }
+        self.needsUrlPlaceholderLoad = NO;
+    }
+}
+
+// The same image decoded again for a dynamicRangeLimit between HDR and SDR,
+// as a resize is (reloadIfResized): without events once it has loaded, and
+// the image showing stays if the load fails. A display setting shouldn't
+// look like a new load.
+- (void) reloadForDynamicRange {
+    self.needsDynamicRangeReload = NO;
+    // Nothing to load, it failed, or it waits for the view's size: the next
+    // load decodes as asked.
+    if (!_source || self.hasErrored || self.waitsForSize) {
+        return;
+    }
+    // A data uri is decoded at once, with its events (see reloadImage).
+    if ([[_source.url absoluteString] hasPrefix: @"data:image"]) {
+        [self reloadImage];
+        return;
+    }
+    SDWebImageOptions options = [self loadOptions];
+    if (self.showsLoadedImage) {
+        options |= SDWebImageDelayPlaceholder;
+    }
+    [self downloadImage: _source options: options context: [self loadContext] events: !self.hasCompleted];
 }
 
 // Whether images are decoded at about the view's size (downsample, and always
@@ -938,6 +1131,8 @@ NSString *FFFErrorMessage(NSError *error)
 
 - (void) reloadImage {
     _needsReload = NO;
+    self.needsDynamicRangeReload = NO;
+    self.needsUrlPlaceholderLoad = NO;
     self.waitsForSize = NO;
     self.loadsSwitchedSource = self.switchesSource;
     self.switchesSource = NO;
@@ -961,13 +1156,19 @@ NSString *FFFErrorMessage(NSError *error)
                 self.onFastImageLoadStart(@{});
             }
             // Use SDWebImage API to support external format like WebP images
-            UIImage* image = [UIImage sd_imageWithData: [NSData dataWithContentsOfURL: _source.url]];
+            // (as sd_imageWithData does), decoded to HDR or SDR as a
+            // download is (see contextForSource).
+            UIImage* image = [[SDImageCodersManager sharedManager] decodedImageWithData: [NSData dataWithContentsOfURL: _source.url] options: @{
+                SDImageCoderDecodeScaleFactor: @1,
+                SDImageCoderDecodeToHDR: @([self decodesToHDR]),
+            }];
             if (!image) {
                 // Not decodable: fail like a remote image, showing the
                 // placeholder.
                 [self setImage: [self shownPlaceholder]];
                 self.showsLoadedImage = NO;
                 [self sendOnError: @"Failed to decode the image"];
+                [self startUrlPlaceholderLoad];
                 if (self.onFastImageLoadEnd) {
                     self.onFastImageLoadEnd([self loadEndEvent: NO]);
                 }
@@ -1010,10 +1211,15 @@ NSString *FFFErrorMessage(NSError *error)
         self.retriedAfterBackground = NO;
         [self stopWaitingForActive];
 
+        [self startUrlPlaceholderLoad];
         [self downloadImage: _source options: options context: [self loadContext] events: YES];
-    } else if ([self shownPlaceholder]) {
-        [self setImage: [self shownPlaceholder]];
-        self.showsLoadedImage = NO;
+    } else {
+        if ([self shownPlaceholder]) {
+            [self setImage: [self shownPlaceholder]];
+            self.showsLoadedImage = NO;
+        }
+        // No image: only placeholders show.
+        [self startUrlPlaceholderLoad];
     }
 }
 
@@ -1070,10 +1276,15 @@ NSString *FFFErrorMessage(NSError *error)
     context[SDWebImageContextDownloadRequestModifier] = source.requestModifier;
     context[SDWebImageContextImageLoader] = source.imageLoader;
     context[SDWebImageContextCacheKeyFilter] = source.cacheKeyFilter;
+    if (@available(iOS 17.0, tvOS 17.0, *)) {
+        // An HDR image (e.g. a photo with a gain map) decoded to HDR, or to
+        // SDR, its standard range version.
+        context[SDWebImageContextImageDecodeToHDR] = @([self decodesToHDR]);
+    }
     if (CGSizeEqualToSize(box, CGSizeZero)) {
         [FFFDownsampledImage addFullSizeToContext: context];
         [self applyCacheOptions: context source: source fullSize: YES];
-        [FFFDownsampledImage forgetSmallerFullSizeImageForURL: source.url context: context];
+        [FFFDownsampledImage forgetUnusableImageForURL: source.url context: context];
         return context;
     }
     [FFFDownsampledImage addToContext: context box: box cover: cover];
@@ -1085,6 +1296,7 @@ NSString *FFFErrorMessage(NSError *error)
         context[SDWebImageContextOriginalQueryCacheType] = @(SDImageCacheTypeNone);
     }
     [self applyCacheOptions: context source: source fullSize: NO];
+    [FFFDownsampledImage forgetUnusableImageForURL: source.url context: context];
     return context;
 }
 
@@ -1243,6 +1455,8 @@ NSString *FFFErrorMessage(NSError *error)
                         [weakSelf setImage: current];
                     }
                     weakSelf.showsLoadedImage = NO;
+                    // Shows instead of the other placeholders once it loads.
+                    [weakSelf startUrlPlaceholderLoad];
                     [weakSelf sendOnError: [source errorMessage: error]];
                     if (weakSelf.onFastImageLoadEnd) {
                         weakSelf.onFastImageLoadEnd([weakSelf loadEndEvent: NO]);
@@ -1250,6 +1464,12 @@ NSString *FFFErrorMessage(NSError *error)
                 } else {
                     weakSelf.hasCompleted = YES;
                     weakSelf.showsLoadedImage = YES;
+                    // For other views' placeholderSource.
+                    [FFFastImageView rememberShownImage: image source: source];
+                    // The image came first: its placeholder isn't needed.
+                    if (!weakSelf.urlPlaceholderImage) {
+                        [weakSelf cancelUrlPlaceholderLoad];
+                    }
                     [weakSelf sendOnLoad: image];
                     if (weakSelf.onFastImageLoadEnd) {
                         weakSelf.onFastImageLoadEnd([weakSelf loadEndEvent: YES]);
@@ -1299,11 +1519,14 @@ NSString *FFFErrorMessage(NSError *error)
     self.waitsForSize = NO;
     [self stopWaitingForActive];
     [self sd_cancelLatestImageLoad];
+    [self cancelUrlPlaceholderLoad];
 }
 
 - (void) dealloc {
     [self stopWaitingForActive];
     [self sd_cancelLatestImageLoad];
+    // Fabric frees views it doesn't recycle without stop.
+    [_urlPlaceholderOperation cancel];
 }
 
 @end

package/ios/FastImage/FFFastImageViewComponentView.mm

@@ -102,6 +102,22 @@ static id _Nullable FFFJSON(const folly::dynamic &value)
     return value.isNull() ? nil : FFFObjectFromDynamic(value);
 }
 
+// Whether the placeholder prop is a url to load apart from the image (a
+// source with an http or https uri), rather than an image to show at once: a
+// bundled image (served by the packager in development), a file or a data uri.
+static BOOL FFFIsUrlPlaceholder(id _Nullable placeholder)
+{
+    if (![placeholder isKindOfClass:[NSDictionary class]] || placeholder[@"__packager_asset"]) {
+        return NO;
+    }
+    id uri = placeholder[@"uri"];
+    if (![uri isKindOfClass:[NSString class]]) {
+        return NO;
+    }
+    NSString *scheme = [NSURL URLWithString:uri].scheme.lowercaseString;
+    return [scheme isEqualToString:@"http"] || [scheme isEqualToString:@"https"];
+}
+
 // The events JS has a handler for: the handledEvents prop's bits (see
 // src/specs/FastImageViewNativeComponent.ts).
 typedef NS_OPTIONS(int32_t, FFFEvent) {
@@ -234,7 +250,9 @@ typedef NS_OPTIONS(int32_t, FFFEvent) {
     }
     if (all || oldViewProps.placeholder != newViewProps.placeholder) {
         id placeholder = FFFJSON(newViewProps.placeholder);
-        view.placeholder = placeholder ? [RCTConvert UIImage:placeholder] : nil;
+        BOOL loads = FFFIsUrlPlaceholder(placeholder);
+        view.placeholder = placeholder && !loads ? [RCTConvert UIImage:placeholder] : nil;
+        view.placeholderSource = loads ? [RCTConvert FFFastImageSource:placeholder] : nil;
     }
     if (all || oldViewProps.sourcePlaceholders != newViewProps.sourcePlaceholders) {
         NSMutableArray<NSString *> *placeholders = [NSMutableArray arrayWithCapacity:newViewProps.sourcePlaceholders.size()];
@@ -287,6 +305,9 @@ typedef NS_OPTIONS(int32_t, FFFEvent) {
     if (all || oldViewProps.downsample != newViewProps.downsample) {
         view.downsample = newViewProps.downsample;
     }
+    if (all || oldViewProps.dynamicRangeLimit != newViewProps.dynamicRangeLimit) {
+        view.dynamicRangeLimit = FFFString(newViewProps.dynamicRangeLimit);
+    }
     if (all || oldViewProps.blurRadius != newViewProps.blurRadius) {
         view.blurRadius = newViewProps.blurRadius;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-fast-image",
-    "version": "10.3.0",
+    "version": "10.5.0",
     "description": "FastImage, performant React Native image component.",
     "keywords": [
         "cache",

package/src/index.js.flow

@@ -110,6 +110,13 @@ export type PreloadResult = PreloadSuccess | PreloadFailure
 export type PreloadFn = (
     sources: Array<FastImageSource>,
 ) => Promise<Array<PreloadResult>>
+export type PlaceholderSource = {
+    uri?: string,
+    headers?: Object,
+    cacheKey?: string,
+    cache?: CacheControls,
+}
+
 export type SourcePlaceholder = {
     thumbhash?: string,
     blurDataUri?: string,
@@ -139,7 +146,7 @@ export type FastImageProps = $ReadOnly<{|
     onProgress?: ?(event: OnProgressEvent) => void,
 
     source?: ?(FastImageSource | Array<FastImageSource> | number),
-    placeholder?: ?(number | string | SourcePlaceholder),
+    placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
 
@@ -151,6 +158,7 @@ export type FastImageProps = $ReadOnly<{|
     imageRendering?: ?('auto' | 'smooth' | 'pixelated'),
     loading?: ?('lazy' | 'eager'),
     sizes?: ?string,
+    dynamicRangeLimit?: ?('standard' | 'constrained' | 'no-limit'),
     paused?: ?boolean,
     transition?: ?(boolean | number | Transition),
     downsample?: ?boolean,

package/src/index.tsx

@@ -16,7 +16,12 @@ import { fromStyle, resolveObjectFit } from './objectFit'
 import { objectPositionOrCentered, type ObjectPosition } from './objectPosition'
 import FastImageView from './specs/FastImageViewNativeComponent'
 import NativeFastImageModule from './specs/NativeFastImageModule'
-import { dataUri, hasSourcePlaceholder, isImageName } from './placeholders'
+import {
+    dataUri,
+    hasSourcePlaceholder,
+    isImageName,
+    placeholderSource,
+} from './placeholders'
 import { warnIfChildren, warnOnce } from './warnings'
 
 /** How the image fits the view: see [`objectFit`](#objectfit). */
@@ -175,6 +180,12 @@ export type Source = {
 /** A `thumbhash` or `blurDataUri` as `placeholder`. */
 export type SourcePlaceholder = Pick<Source, 'thumbhash' | 'blurDataUri'>
 
+/** A url as `placeholder`, loaded like a source (see `placeholder`). */
+export type PlaceholderSource = Pick<
+    Source,
+    'uri' | 'headers' | 'cacheKey' | 'cache'
+>
+
 /** How the image fades in: see [`transition`](#transition). */
 export type Transition = {
     /**
@@ -365,17 +376,27 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      *   `placeholder={{ thumbhash }}`.
      * - A tiny image as a data uri, shown blurred:
      *   `placeholder={{ blurDataUri }}`.
+     * - A url, loaded and cached like a source:
+     *   `placeholder="https://example.com/placeholder.png"`, or a source with
+     *   `headers` or a `cacheKey`: `placeholder={{ uri, headers }}`.
+     * - A url only shown if it's already cached, e.g. a list's thumbnail while
+     *   the full-size image loads: `placeholder={{ uri, cache: 'cacheOnly' }}`.
      *
      * A source's own `thumbhash` or `blurDataUri` is shown instead, if it has
-     * one.
+     * one; a url placeholder shows over it once it has loaded.
      *
      * Notes:
      *
-     * - A url isn't loaded: it's ignored, with a warning in development.
      * - On Android, a `require()`d image doesn't show in debug builds, where
      *   the dev server serves it. Release builds show it.
+     * - On the web, a url loads like any image, also with `'cacheOnly'`: a
+     *   browser can't look only in its cache.
      */
-    placeholder?: ImageRequireSource | string | SourcePlaceholder
+    placeholder?:
+        | ImageRequireSource
+        | string
+        | SourcePlaceholder
+        | PlaceholderSource
     /**
      * @deprecated Use `placeholder`, which does the same.
      */
@@ -555,6 +576,25 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * @default true
      */
     downsample?: boolean
+    /**
+     * How bright HDR photos (e.g. photos taken on an iPhone) can be, on
+     * displays that support it:
+     *
+     * - `'standard'`: in standard range, like the rest of the screen.
+     * - `'constrained'`: in HDR, their highlights brighter than the rest of
+     *   the screen but held below the display's peak, e.g. for images among
+     *   other content (a feed).
+     * - `'no-limit'`: in full HDR, e.g. for a full-screen photo viewer.
+     *
+     * Not set, iOS shows them in standard range, and the web as the browser
+     * does by default (usually HDR). On iOS and tvOS 17 and later; Android
+     * shows them in standard range. On the web it's CSS's
+     * `dynamic-range-limit`.
+     *
+     * @platform ios
+     * @platform web
+     */
+    dynamicRangeLimit?: 'standard' | 'constrained' | 'no-limit'
     // The radius is converted from points to the bitmap's pixels on both
     // platforms, so it matches React Native's Image.
     /**
@@ -687,7 +727,8 @@ function sourcePlaceholder(source: unknown): string {
 }
 
 const resolvePlaceholder = (
-    placeholder?: ImageRequireSource | string,
+    // A source object here has no url (e.g. { uri: name }, a bundled image).
+    placeholder?: ImageRequireSource | string | PlaceholderSource,
 ): string | object | null => {
     if (typeof placeholder === 'string') {
         // An image bundled with the app, by name, as React Native's Image
@@ -706,7 +747,9 @@ const resolvePlaceholder = (
     if (!placeholder) {
         return null
     }
-    const resolved = Image.resolveAssetSource(placeholder)
+    const resolved = Image.resolveAssetSource(
+        placeholder as ImageRequireSource | { uri: string },
+    )
     if (!resolved) {
         return null
     }
@@ -904,13 +947,17 @@ function FastImageBase({
                 : undefined,
         }
     }, [source, shared])
-    // A thumbhash or blurDataUri in `placeholder` goes in sourcePlaceholders
-    // instead: it isn't an image to show as it is, but defaultSource still is.
-    const resolvedPlaceholder = resolvePlaceholder(
-        hasSourcePlaceholder(placeholder)
-            ? defaultSource
-            : (placeholder ?? defaultSource),
-    )
+    // A url in `placeholder` goes to the native view as a source, loaded
+    // apart from the image, in place of defaultSource. A thumbhash or
+    // blurDataUri goes in sourcePlaceholders instead: it isn't an image to
+    // show as it is, but defaultSource still is.
+    const resolvedPlaceholder =
+        placeholderSource(placeholder) ??
+        resolvePlaceholder(
+            hasSourcePlaceholder(placeholder)
+                ? defaultSource
+                : (placeholder ?? defaultSource),
+        )
 
     return (
         <FastImageView