react-native-nitro-image-pipeline 1.6.0 → 1.7.0

package/android/src/main/java/com/margelo/nitro/nitroimagepipeline/transform/ResizeTransformation.kt

@@ -6,53 +6,106 @@ import android.graphics.Matrix
 import android.graphics.Paint
 import coil3.size.Size
 import coil3.transform.Transformation
+import com.margelo.nitro.nitroimagepipeline.ResizeFit
 import kotlin.math.max
 
 /**
- * Scales the input to fill exactly [width] × [height] pixels and center-crops the overflow (CSS
- * `object-fit: cover`), upscaling smaller sources. It runs before [BlurTransformation] and rounded
- * corners so their pixel units refer to the final bitmap — matching Nuke's
- * `ImageProcessors.Resize(contentMode: .aspectFill, crop: true)` on iOS.
+ * Resizes the input into a [width] × [height] pixel box under [fit] (see [FitGeometry] for the size
+ * each mode produces). The default — [ResizeFit.COVER] with [allowUpscale] — scales the input to
+ * fill the box exactly and center-crops the overflow (CSS `object-fit: cover`), upscaling smaller
+ * sources, on the very same code path (and cache key) it had before `fit` existed, matching Nuke's
+ * `ImageProcessors.Resize(contentMode: .aspectFill, crop: true)` on iOS. Every other fit runs
+ * through [FitGeometry], matching iOS's `FitResizeProcessor`.
+ *
+ * It runs before [BlurTransformation] and rounded corners so their pixel units refer to the final
+ * bitmap.
  */
 class ResizeTransformation(
     private val width: Int,
     private val height: Int,
+    private val fit: ResizeFit = ResizeFit.COVER,
+    private val allowUpscale: Boolean = true,
 ) : Transformation() {
 
   init {
     require(width > 0 && height > 0) { "width and height must be > 0." }
   }
 
-  override val cacheKey = "${ResizeTransformation::class.java.name}-$width-$height"
+  private val isDefaultFit: Boolean
+    get() = fit == ResizeFit.COVER && allowUpscale
+
+  // The default keeps its original key so results cached by earlier versions stay valid.
+  override val cacheKey = buildString {
+    append(ResizeTransformation::class.java.name)
+        .append('-')
+        .append(width)
+        .append('-')
+        .append(height)
+    if (fit != ResizeFit.COVER) append('-').append(fit.name.lowercase())
+    if (!allowUpscale) append("-noupscale")
+  }
 
   override suspend fun transform(input: Bitmap, size: Size): Bitmap {
     val softwareInput =
         if (input.config == Bitmap.Config.HARDWARE) input.copy(Bitmap.Config.ARGB_8888, false)
         else input
-    if (softwareInput.width == width && softwareInput.height == height) return softwareInput
+    return if (isDefaultFit) cover(softwareInput) else fitted(softwareInput)
+  }
+
+  private fun cover(input: Bitmap): Bitmap {
+    if (input.width == width && input.height == height) return input
 
-    val scale = max(width.toFloat() / softwareInput.width, height.toFloat() / softwareInput.height)
+    val scale = max(width.toFloat() / input.width, height.toFloat() / input.height)
     val matrix =
         Matrix().apply {
           setScale(scale, scale)
-          postTranslate(
-              (width - softwareInput.width * scale) / 2f,
-              (height - softwareInput.height * scale) / 2f,
+          postTranslate((width - input.width * scale) / 2f, (height - input.height * scale) / 2f)
+        }
+    return draw(input, width, height, matrix)
+  }
+
+  private fun fitted(input: Bitmap): Bitmap {
+    val geometry = FitGeometry.of(input.width, input.height, width, height, fit, allowUpscale)
+    // `center` of a source that fits the box, or `contain` without upscaling
+    // of a small source: the bitmap is already the output.
+    if (geometry.isIdentity) return input
+
+    val matrix =
+        Matrix().apply {
+          // Scale to the rounded size exactly, so the drawn extent is whole pixels.
+          setScale(
+              geometry.scaledWidth.toFloat() / input.width,
+              geometry.scaledHeight.toFloat() / input.height,
           )
+          postTranslate(geometry.originX.toFloat(), geometry.originY.toFloat())
         }
-    val config = softwareInput.config ?: Bitmap.Config.ARGB_8888
-    val output = Bitmap.createBitmap(width, height, config)
+    return draw(input, geometry.outputWidth, geometry.outputHeight, matrix)
+  }
+
+  private fun draw(input: Bitmap, outputWidth: Int, outputHeight: Int, matrix: Matrix): Bitmap {
+    val config = input.config ?: Bitmap.Config.ARGB_8888
+    val output = Bitmap.createBitmap(outputWidth, outputHeight, config)
     Canvas(output)
-        .drawBitmap(softwareInput, matrix, Paint(Paint.ANTI_ALIAS_FLAG or Paint.FILTER_BITMAP_FLAG))
+        .drawBitmap(input, matrix, Paint(Paint.ANTI_ALIAS_FLAG or Paint.FILTER_BITMAP_FLAG))
     return output
   }
 
   override fun equals(other: Any?): Boolean {
     if (this === other) return true
-    return other is ResizeTransformation && width == other.width && height == other.height
+    return other is ResizeTransformation &&
+        width == other.width &&
+        height == other.height &&
+        fit == other.fit &&
+        allowUpscale == other.allowUpscale
   }
 
-  override fun hashCode(): Int = 31 * width + height
+  override fun hashCode(): Int {
+    var result = 31 * width + height
+    result = 31 * result + fit.hashCode()
+    result = 31 * result + allowUpscale.hashCode()
+    return result
+  }
 
-  override fun toString() = "ResizeTransformation(width=$width, height=$height)"
+  override fun toString() =
+      "ResizeTransformation(width=$width, height=$height, fit=$fit, allowUpscale=$allowUpscale)"
 }

package/ios/FitResizeProcessor.swift

@@ -0,0 +1,127 @@
+//
+//  FitResizeProcessor.swift
+//  NitroImagePipeline
+//
+//  Resizes into the `ResizeOptions` box under any `fit` other than the
+//  default. The default — `cover` with upscaling — stays on Nuke's own
+//  `ImageProcessors.Resize(.aspectFill, crop: true)`, so its output bytes and
+//  cache keys are exactly what they were before `fit` existed.
+//
+
+import CoreGraphics
+import Foundation
+import Nuke
+import UIKit
+
+/// The resize geometry both platforms implement — Android's port is
+/// `transform/FitGeometry.kt`, and `example/__tests__/fit-geometry.ts` is the
+/// copy the harness checks both against. With a `w` × `h` source and a
+/// `W` × `H` box:
+///
+/// ```
+/// cover   : sx = sy = max(W/w, H/h)
+/// contain : sx = sy = min(W/w, H/h)
+/// stretch : sx = W/w ; sy = H/h
+/// center  : sx = sy = 1
+/// if !allowUpscale: sx = min(sx, 1) ; sy = min(sy, 1)
+/// scaled  = (round(w·sx), round(h·sy))
+/// output  = (min(W, scaled.w), min(H, scaled.h))
+/// origin  = trunc((output − scaled) / 2)        — a centred, whole-pixel crop
+/// ```
+///
+/// The source is drawn scaled to `scaled` at `origin` on an `output`-sized
+/// canvas. Rounding is half-away-from-zero (`.rounded()` here,
+/// `roundToInt()` in Kotlin — identical for the positive values involved).
+struct FitGeometry: Equatable {
+    let source: CGSize
+    let scaled: CGSize
+    let output: CGSize
+    let origin: CGPoint
+
+    init(source: CGSize, box: CGSize, fit: ResizeFit, allowUpscale: Bool) {
+        let boxWidth = box.width.rounded()
+        let boxHeight = box.height.rounded()
+        var scaleX: CGFloat
+        var scaleY: CGFloat
+        switch fit {
+        case .cover:
+            let scale = max(boxWidth / source.width, boxHeight / source.height)
+            scaleX = scale
+            scaleY = scale
+        case .contain:
+            let scale = min(boxWidth / source.width, boxHeight / source.height)
+            scaleX = scale
+            scaleY = scale
+        case .stretch:
+            scaleX = boxWidth / source.width
+            scaleY = boxHeight / source.height
+        case .center:
+            scaleX = 1
+            scaleY = 1
+        }
+        if !allowUpscale {
+            scaleX = min(scaleX, 1)
+            scaleY = min(scaleY, 1)
+        }
+        let scaledWidth = max((source.width * scaleX).rounded(), 1)
+        let scaledHeight = max((source.height * scaleY).rounded(), 1)
+        let outputWidth = min(boxWidth, scaledWidth)
+        let outputHeight = min(boxHeight, scaledHeight)
+        self.source = source
+        scaled = CGSize(width: scaledWidth, height: scaledHeight)
+        output = CGSize(width: outputWidth, height: outputHeight)
+        origin = CGPoint(
+            x: ((outputWidth - scaledWidth) / 2).rounded(.towardZero),
+            y: ((outputHeight - scaledHeight) / 2).rounded(.towardZero)
+        )
+    }
+
+    /// Whether the source is already the output — nothing to draw. Both
+    /// sizes are compared with the *source*: `scaled == output` alone also
+    /// holds for every plain downscale (nothing is cropped), which is not an
+    /// identity.
+    var isIdentity: Bool { scaled == source && output == source }
+}
+
+/// Nuke processor for the non-default fits. Runs before the blur and corner
+/// processors, like `ImageProcessors.Resize`, so their pixel units refer to
+/// the produced bitmap. Sizes are in points of the image, which the pipeline
+/// decodes at scale 1 (1 pt = 1 px) — the same convention as
+/// `RoundedCornersProcessor`.
+struct FitResizeProcessor: ImageProcessing {
+    let width: Double
+    let height: Double
+    let fit: ResizeFit
+    let allowUpscale: Bool
+
+    var identifier: String {
+        "com.nitroimagepipeline.resize?w=\(width),h=\(height),fit=\(fit.stringValue),upscale=\(allowUpscale)"
+    }
+
+    var hashableIdentifier: AnyHashable { identifier }
+
+    func process(_ image: PlatformImage) -> PlatformImage? {
+        let source = image.size
+        guard source.width > 0, source.height > 0 else { return image }
+        let geometry = FitGeometry(
+            source: source,
+            box: CGSize(width: width, height: height),
+            fit: fit,
+            allowUpscale: allowUpscale
+        )
+        // `center` of a source that fits the box, or `contain` without
+        // upscaling of a small source: the bitmap is already the output.
+        if geometry.isIdentity { return image }
+
+        let format = UIGraphicsImageRendererFormat()
+        format.scale = image.scale
+        format.opaque = false
+        // See RoundedCornersProcessor: the extended range doubles the bytes
+        // of an 8-bit source for nothing.
+        format.preferredRange = .standard
+
+        return UIGraphicsImageRenderer(size: geometry.output, format: format).image { _ in
+            image.draw(in: CGRect(origin: geometry.origin, size: geometry.scaled))
+        }
+    }
+}

package/ios/HybridNitroImagePipeline.swift

@@ -198,26 +198,46 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
         }
     }
 
-    /// The target size in pixels, or `nil` when no (valid) resize was requested.
-    private static func resizeSize(for options: Options?) -> CGSize? {
+    /// The requested resize, or `nil` when there is no (valid) one.
+    private static func requestedResize(for options: Options?) -> ResizeOptions? {
         guard let resize = options?.resize, resize.width > 0, resize.height > 0 else {
             return nil
         }
-        return CGSize(width: resize.width, height: resize.height)
+        return resize
+    }
+
+    private static func fit(of resize: ResizeOptions) -> ResizeFit { resize.fit ?? .cover }
+
+    private static func allowsUpscale(_ resize: ResizeOptions) -> Bool { resize.allowUpscale ?? true }
+
+    /// The resize as it behaved before `fit` existed — aspect-fill, crop,
+    /// upscale — which keeps Nuke's own processor (and its cache keys).
+    private static func isDefaultFit(_ resize: ResizeOptions) -> Bool {
+        fit(of: resize) == .cover && allowsUpscale(resize)
     }
 
     private static func processors(for options: Options?) -> [any ImageProcessing] {
         var processors: [any ImageProcessing] = []
         // Resize first: blur sigma and corner radii are defined in pixels
         // of the bitmap they run on, so they must see the final size.
-        if let size = resizeSize(for: options) {
-            processors.append(ImageProcessors.Resize(
-                size: size,
-                unit: .pixels,
-                contentMode: .aspectFill,
-                crop: true,
-                upscale: true
-            ))
+        if let resize = requestedResize(for: options) {
+            let size = CGSize(width: resize.width, height: resize.height)
+            if isDefaultFit(resize) {
+                processors.append(ImageProcessors.Resize(
+                    size: size,
+                    unit: .pixels,
+                    contentMode: .aspectFill,
+                    crop: true,
+                    upscale: true
+                ))
+            } else {
+                processors.append(FitResizeProcessor(
+                    width: size.width,
+                    height: size.height,
+                    fit: fit(of: resize),
+                    allowUpscale: allowsUpscale(resize)
+                ))
+            }
         }
         if let blur = options?.blur, blur > 0 {
             processors.append(GaussianBlurProcessor(sigma: blur))
@@ -242,12 +262,18 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
         // resolution — a 48 MP photo displayed as a 300 pt card would
         // otherwise decompress to ~190 MB before Resize shrinks it.
         // Matches Android, where the request's size() drives subsampling;
-        // the exact size and crop still come from the Resize processor.
-        if let size = resizeSize(for: options) {
+        // the exact size and crop still come from the resize processor.
+        // `contain` decodes aspect-fit: its output follows the smaller scale,
+        // and an aspect-fill decode of a wide panorama into a small box would
+        // be near the source's full width before the processor shrinks it.
+        // Android's Scale.FIT subsampling bounds the decode the same way.
+        // `center` never scales, so it must see the source's own pixels: a
+        // subsampled decode would crop the wrong ones.
+        if let resize = requestedResize(for: options), fit(of: resize) != .center {
             imgRequest.thumbnail = ImageRequest.ThumbnailOptions(
-                size: size,
+                size: CGSize(width: resize.width, height: resize.height),
                 unit: .pixels,
-                contentMode: .aspectFill
+                contentMode: fit(of: resize) == .contain ? .aspectFit : .aspectFill
             )
         }
         return imgRequest

package/ios/PipelineImageLoader.swift

@@ -21,6 +21,11 @@ import UIKit
 /// `ViewOptions` values are in points; this class converts them to the
 /// pixel-based `Options` of the shared request builder using the view's
 /// display scale, so cache keys match an equivalent `loadImage` call.
+///
+/// The optional `onLoad`/`onError` callbacks report a view's load back to JS.
+/// They are per request, not per loader: several views (and a recycled cell
+/// re-attaching) each call them, and a view that requests twice reports twice.
+/// `loadImage()` doesn't — it reports through its promise instead.
 class PipelineImageLoader: HybridImageLoaderSpec {
     private let url: String
     private let options: ViewOptions?
@@ -30,6 +35,14 @@ class PipelineImageLoader: HybridImageLoaderSpec {
     // to the main thread — every access happens inside a main-queue block.
     private var tasks: [ObjectIdentifier: Task<Void, Never>] = [:]
     private var pendingLayouts: [ObjectIdentifier: NSKeyValueObservation] = [:]
+    // Bumped synchronously by every `requestImage`/`dropImage` — the view
+    // calls both on the main thread, from its own lifecycle — so work queued
+    // by an earlier call can tell a later one superseded it before its
+    // main-queue block ran, and neither displays nor reports. `dropImage`
+    // only *queues* its cancellation, so without this a request queued just
+    // before a detach still runs first and, on a memory-cache hit, reports a
+    // load for a view that is about to be cleared.
+    private var generations: [ObjectIdentifier: Int] = [:]
 
     init(url: String, options: ViewOptions?) {
         self.url = url
@@ -55,7 +68,9 @@ class PipelineImageLoader: HybridImageLoaderSpec {
     }
 
     /// The point-based `ViewOptions` as pixel-based `Options`, resolved
-    /// against `scale` and the target size in pixels.
+    /// against `scale` and the target size in pixels. The fit comes from the
+    /// explicit `resize` when it carries one, else from the top-level
+    /// `fit`/`allowUpscale`, which apply to the measured size.
     private func pixelOptions(scale: CGFloat, sizePx: CGSize?) -> Options {
         let cornerRadius = options?.cornerRadius.map { radius -> Variant_Double_CornerRadii in
             switch radius {
@@ -74,16 +89,43 @@ class PipelineImageLoader: HybridImageLoaderSpec {
             blur: options?.blur.map { $0 * scale },
             cache: options?.cache,
             cornerRadius: cornerRadius,
-            resize: sizePx.map { ResizeOptions(width: Double($0.width), height: Double($0.height)) }
+            resize: sizePx.map {
+                ResizeOptions(
+                    width: Double($0.width),
+                    height: Double($0.height),
+                    fit: explicitResizeOptions?.fit ?? options?.fit,
+                    allowUpscale: explicitResizeOptions?.allowUpscale ?? options?.allowUpscale
+                )
+            }
         )
     }
 
-    /// An explicit `resize` override (pixels), when set and valid.
-    private var explicitResize: CGSize? {
+    /// The loaded image as the view should draw it. The pipeline decodes at
+    /// scale 1 (1 pt = 1 px); `.center` — the one content mode that draws an
+    /// image at its point size — would then show a `fit: 'center'` bitmap at
+    /// `scale`× its size on a Retina screen, while Android's
+    /// `ScaleType.CENTER` draws it pixel for pixel. Re-wrapping with the
+    /// display scale (a wrapper around the same CGImage, not a copy) makes
+    /// iOS draw 1 bitmap pixel per device pixel too; the scaling content
+    /// modes are unaffected by an image's scale.
+    private static func displayImage(_ image: UIImage, scale: CGFloat) -> UIImage {
+        guard image.scale != scale, let cgImage = image.cgImage else { return image }
+        return UIImage(cgImage: cgImage, scale: scale, orientation: image.imageOrientation)
+    }
+
+    /// The explicit `resize` override, when set and valid. An invalid one
+    /// (a non-positive dimension) is ignored as a whole — its `fit` and
+    /// `allowUpscale` included, as on Android — and the view is measured.
+    private var explicitResizeOptions: ResizeOptions? {
         guard let resize = options?.resize, resize.width > 0, resize.height > 0 else {
             return nil
         }
-        return CGSize(width: resize.width, height: resize.height)
+        return resize
+    }
+
+    /// The explicit `resize` override's size (pixels), when set and valid.
+    private var explicitResize: CGSize? {
+        explicitResizeOptions.map { CGSize(width: $0.width, height: $0.height) }
     }
 
     // MARK: - ImageLoader
@@ -108,17 +150,22 @@ class PipelineImageLoader: HybridImageLoaderSpec {
     func requestImage(forView view: any HybridNitroImageViewSpec) throws {
         guard let nativeView = view as? NativeImageView else { return }
         let key = ObjectIdentifier(view)
+        let generation = supersedeWork(for: key)
         // Always hop (asynchronously) to main: `requestImage` fires while the
         // view is being mounted, and only after the current mounting
         // transaction finishes is its final frame guaranteed to be set.
         DispatchQueue.main.async {
-            self.load(into: nativeView.imageView, key: key)
+            guard self.isCurrent(generation, for: key) else { return }
+            self.load(into: nativeView.imageView, key: key, generation: generation)
         }
     }
 
     func dropImage(forView view: any HybridNitroImageViewSpec) throws {
         guard let nativeView = view as? NativeImageView else { return }
         let key = ObjectIdentifier(view)
+        // Takes effect now, unlike the cancellation below: a request queued
+        // before this drop runs first, and must not load or report.
+        _ = supersedeWork(for: key)
         // Same queue as `requestImage`, so rapid attach/detach sequences
         // (list recycling) replay in call order.
         DispatchQueue.main.async {
@@ -129,6 +176,20 @@ class PipelineImageLoader: HybridImageLoaderSpec {
 
     // MARK: - Main-thread loading
 
+    /// Invalidates whatever is queued for `key` and returns the token
+    /// identifying this new piece of work. Main thread, like its callers.
+    private func supersedeWork(for key: ObjectIdentifier) -> Int {
+        // Never reset: a token must not be reused while an older block that
+        // holds it is still queued.
+        let generation = (generations[key] ?? 0) + 1
+        generations[key] = generation
+        return generation
+    }
+
+    private func isCurrent(_ generation: Int, for key: ObjectIdentifier) -> Bool {
+        return generations[key] == generation
+    }
+
     private func cancel(key: ObjectIdentifier) {
         tasks[key]?.cancel()
         tasks[key] = nil
@@ -136,18 +197,18 @@ class PipelineImageLoader: HybridImageLoaderSpec {
         pendingLayouts[key] = nil
     }
 
-    private func load(into imageView: UIImageView, key: ObjectIdentifier) {
+    private func load(into imageView: UIImageView, key: ObjectIdentifier, generation: Int) {
         cancel(key: key)
 
         if let sizePx = explicitResize {
-            start(into: imageView, key: key, sizePx: sizePx)
+            start(into: imageView, key: key, generation: generation, sizePx: sizePx)
             return
         }
 
         let bounds = imageView.bounds.size
         if bounds.width > 0, bounds.height > 0 {
             let scale = Self.displayScale(of: imageView)
-            start(into: imageView, key: key, sizePx: CGSize(
+            start(into: imageView, key: key, generation: generation, sizePx: CGSize(
                 width: bounds.width * scale,
                 height: bounds.height * scale
             ))
@@ -160,14 +221,26 @@ class PipelineImageLoader: HybridImageLoaderSpec {
                 DispatchQueue.main.async {
                     guard let self, let imageView else { return }
                     guard self.pendingLayouts[key] != nil else { return }
-                    self.load(into: imageView, key: key)
+                    guard self.isCurrent(generation, for: key) else { return }
+                    self.load(into: imageView, key: key, generation: generation)
                 }
             }
         }
     }
 
-    private func start(into imageView: UIImageView, key: ObjectIdentifier, sizePx: CGSize) {
-        guard let imageUrl = HybridNitroImagePipeline.url(from: url) else { return }
+    private func start(
+        into imageView: UIImageView,
+        key: ObjectIdentifier,
+        generation: Int,
+        sizePx: CGSize
+    ) {
+        guard let imageUrl = HybridNitroImagePipeline.url(from: url) else {
+            // Android's loader hands a malformed URL to Coil, which reports it
+            // as a failed request; report it here too rather than returning
+            // silently and leaving `onError` waiting forever.
+            options?.onError?("Invalid URL: \(url)")
+            return
+        }
         let scale = Self.displayScale(of: imageView)
         let request = HybridNitroImagePipeline.makeRequest(
             url: imageUrl,
@@ -181,15 +254,32 @@ class PipelineImageLoader: HybridImageLoaderSpec {
         // bitmap is already in memory. The subscript honours the request's
         // `.disableMemoryCacheReads`, so `cache: 'disk'`/`'none'` still miss.
         if !request.options.contains(.disableMemoryCacheReads), let cached = pipeline.cache[request] {
-            imageView.image = cached.image
+            imageView.image = Self.displayImage(cached.image, scale: scale)
+            notifyLoad(cached.image)
             return
         }
         // Cancelling the Task cancels Nuke's request; a finished task stays in
         // the map (cancelling it is a no-op) until `cancel` replaces it.
-        tasks[key] = Task { @MainActor [weak imageView] in
-            guard let image = try? await pipeline.image(for: request) else { return }
-            guard !Task.isCancelled else { return }
-            imageView?.image = image
+        tasks[key] = Task { @MainActor [weak self, weak imageView] in
+            do {
+                let image = try await pipeline.image(for: request)
+                guard !Task.isCancelled else { return }
+                guard self?.isCurrent(generation, for: key) == true else { return }
+                imageView?.image = Self.displayImage(image, scale: scale)
+                self?.notifyLoad(image)
+            } catch {
+                // A load the view cancelled by detaching is not a failure.
+                guard !Task.isCancelled, !(error is CancellationError) else { return }
+                guard self?.isCurrent(generation, for: key) == true else { return }
+                self?.options?.onError?(error.localizedDescription)
+            }
         }
     }
+
+    /// Reports the displayed bitmap's size in pixels, when the caller asked
+    /// for it. `UIImage.size` is in points, so it needs the image's own scale.
+    private func notifyLoad(_ image: UIImage) {
+        guard let onLoad = options?.onLoad else { return }
+        onLoad(image.size.width * image.scale, image.size.height * image.scale)
+    }
 }

package/lib/commonjs/NativePipelineImage.js

@@ -25,8 +25,9 @@ var _jsxRuntime = require("react/jsx-runtime");
  * the same pipeline and caches as `useImage`/`preLoadImage`.
  *
  * Compared to `PipelineImage`:
- * - No `onLoad`/`onError` callbacks — the loaded `Image` never crosses into
- *   JS. Use `PipelineImage` (or `useImage`) when you need them.
+ * - `onLoad` reports the bitmap's pixel size rather than the `Image` itself,
+ *   which never crosses into JS, and can fire more than once for a view. Use
+ *   `PipelineImage` (or `useImage`) when you need the `Image`.
  * - The bitmap is loaded once at the size the view first has; if the view is
  *   resized later, the bitmap scales with it instead of reloading.
  * @example
@@ -44,16 +45,29 @@ const NativePipelineImage = exports.NativePipelineImage = /*#__PURE__*/(0, _reac
   cornerRadius,
   cache,
   resize,
+  fit,
+  allowUpscale,
+  onLoad,
+  onError,
   style,
+  resizeMode,
   ...viewProps
 }, ref) {
   // Same precedence as PipelineImage: an explicit prop wins over style.
   const effectiveCornerRadius = cornerRadius ?? (0, _resizeForStyle.cornerRadiusForStyle)(style);
+  // Inline arrows are fine here — the hook keeps the callbacks in a ref, so a
+  // new identity doesn't recreate the loader (which would reload the image).
   const loader = (0, _usePipelineImageLoader.usePipelineImageLoader)(url, {
     blur,
     cornerRadius: effectiveCornerRadius,
     cache,
-    resize
+    resize,
+    // Same four values as the view's resizeMode; an explicit `fit` decouples
+    // them.
+    fit: fit ?? resizeMode,
+    allowUpscale,
+    onLoad,
+    onError
   });
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeNitroImage.NativeNitroImage
   // Before the spread so a caller-provided recyclingKey wins.
@@ -62,6 +76,7 @@ const NativePipelineImage = exports.NativePipelineImage = /*#__PURE__*/(0, _reac
     ...viewProps,
     ref: ref,
     style: style,
+    resizeMode: resizeMode,
     image: loader
   });
 });

package/lib/commonjs/NativePipelineImage.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","_reactNativeNitroImage","_resizeForStyle","_resolveImageSource","_usePipelineImageLoader","_jsxRuntime","NativePipelineImage","exports","forwardRef","url","blur","cornerRadius","cache","resize","style","viewProps","ref","effectiveCornerRadius","cornerRadiusForStyle","loader","usePipelineImageLoader","jsx","NativeNitroImage","recyclingKey","recyclingKeyFor","image","displayName"],"sourceRoot":"../../src","sources":["NativePipelineImage.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA,IAAAC,sBAAA,GAAAD,OAAA;AAEA,IAAAE,eAAA,GAAAF,OAAA;AACA,IAAAG,mBAAA,GAAAH,OAAA;AAMA,IAAAI,uBAAA,GAAAJ,OAAA;AAAkE,IAAAK,WAAA,GAAAL,OAAA;AAKlE;AACA;AACA;AACA;AACA;;AAmCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMM,mBAAmB,GAAAC,OAAA,CAAAD,mBAAA,gBAAG,IAAAE,iBAAU,EAG3C,SAASF,mBAAmBA,CAC5B;EAAEG,GAAG;EAAEC,IAAI;EAAEC,YAAY;EAAEC,KAAK;EAAEC,MAAM;EAAEC,KAAK;EAAE,GAAGC;AAAU,CAAC,EAC/DC,GAAG,EACH;EACA;EACA,MAAMC,qBAAqB,GAAGN,YAAY,IAAI,IAAAO,oCAAoB,EAACJ,KAAK,CAAC;EACzE,MAAMK,MAAM,GAAG,IAAAC,8CAAsB,EAACX,GAAG,EAAE;IACzCC,IAAI;IACJC,YAAY,EAAEM,qBAAqB;IACnCL,KAAK;IACLC;EACF,CAAC,CAAC;EAEF,oBACE,IAAAR,WAAA,CAAAgB,GAAA,EAACpB,sBAAA,CAAAqB;EACC;EAAA;IACAC,YAAY,EAAE,IAAAC,mCAAe,EAACf,GAAG,CAAE;IAAA,GAC/BM,SAAS;IACbC,GAAG,EAAEA,GAAI;IACTF,KAAK,EAAEA,KAAM;IACbW,KAAK,EAAEN;EAAO,CACf,CAAC;AAEN,CAAC,CAAC;;AAEF;AACA;AACAb,mBAAmB,CAACoB,WAAW,GAAG,qBAAqB","ignoreList":[]}
+{"version":3,"names":["_react","require","_reactNativeNitroImage","_resizeForStyle","_resolveImageSource","_usePipelineImageLoader","_jsxRuntime","NativePipelineImage","exports","forwardRef","url","blur","cornerRadius","cache","resize","fit","allowUpscale","onLoad","onError","style","resizeMode","viewProps","ref","effectiveCornerRadius","cornerRadiusForStyle","loader","usePipelineImageLoader","jsx","NativeNitroImage","recyclingKey","recyclingKeyFor","image","displayName"],"sourceRoot":"../../src","sources":["NativePipelineImage.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA,IAAAC,sBAAA,GAAAD,OAAA;AAEA,IAAAE,eAAA,GAAAF,OAAA;AACA,IAAAG,mBAAA,GAAAH,OAAA;AAOA,IAAAI,uBAAA,GAAAJ,OAAA;AAAkE,IAAAK,WAAA,GAAAL,OAAA;AAKlE;AACA;AACA;AACA;AACA;;AA2EA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMM,mBAAmB,GAAAC,OAAA,CAAAD,mBAAA,gBAAG,IAAAE,iBAAU,EAG3C,SAASF,mBAAmBA,CAC5B;EACEG,GAAG;EACHC,IAAI;EACJC,YAAY;EACZC,KAAK;EACLC,MAAM;EACNC,GAAG;EACHC,YAAY;EACZC,MAAM;EACNC,OAAO;EACPC,KAAK;EACLC,UAAU;EACV,GAAGC;AACL,CAAC,EACDC,GAAG,EACH;EACA;EACA,MAAMC,qBAAqB,GAAGX,YAAY,IAAI,IAAAY,oCAAoB,EAACL,KAAK,CAAC;EACzE;EACA;EACA,MAAMM,MAAM,GAAG,IAAAC,8CAAsB,EAAChB,GAAG,EAAE;IACzCC,IAAI;IACJC,YAAY,EAAEW,qBAAqB;IACnCV,KAAK;IACLC,MAAM;IACN;IACA;IACAC,GAAG,EAAEA,GAAG,IAAIK,UAAU;IACtBJ,YAAY;IACZC,MAAM;IACNC;EACF,CAAC,CAAC;EAEF,oBACE,IAAAZ,WAAA,CAAAqB,GAAA,EAACzB,sBAAA,CAAA0B;EACC;EAAA;IACAC,YAAY,EAAE,IAAAC,mCAAe,EAACpB,GAAG,CAAE;IAAA,GAC/BW,SAAS;IACbC,GAAG,EAAEA,GAAI;IACTH,KAAK,EAAEA,KAAM;IACbC,UAAU,EAAEA,UAAW;IACvBW,KAAK,EAAEN;EAAO,CACf,CAAC;AAEN,CAAC,CAAC;;AAEF;AACA;AACAlB,mBAAmB,CAACyB,WAAW,GAAG,qBAAqB","ignoreList":[]}

package/lib/commonjs/PipelineImage.js

@@ -61,10 +61,13 @@ const PipelineImage = exports.PipelineImage = /*#__PURE__*/(0, _react.forwardRef
   blur = 0,
   cornerRadius,
   cache,
+  fit,
+  allowUpscale,
   onLoad,
   onError,
   style,
   onLayout,
+  resizeMode,
   ...viewProps
 }, ref) {
   const scale = _reactNative.PixelRatio.get();
@@ -72,7 +75,15 @@ const PipelineImage = exports.PipelineImage = /*#__PURE__*/(0, _react.forwardRef
   const [layoutSize, setLayoutSize] = (0, _react.useState)(undefined);
   // A numeric style is what the caller declared, so it wins and starts the
   // request a frame earlier; the measured layout is the fallback.
-  const resize = styleSize ?? layoutSize;
+  const size = styleSize ?? layoutSize;
+  // The view's resizeMode and the bitmap's fit are the same four values;
+  // an explicit `fit` decouples them.
+  const effectiveFit = fit ?? resizeMode;
+  const resize = size ? {
+    ...size,
+    fit: effectiveFit,
+    allowUpscale
+  } : undefined;
   // Same precedence: an explicit prop wins over what style implies.
   const effectiveCornerRadius = cornerRadius ?? (0, _resizeForStyle.cornerRadiusForStyle)(style) ?? 0;
   const {
@@ -115,6 +126,7 @@ const PipelineImage = exports.PipelineImage = /*#__PURE__*/(0, _react.forwardRef
     ...viewProps,
     ref: ref,
     style: style,
+    resizeMode: resizeMode,
     onLayout: handleLayout,
     image: image
   });