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

package/README.md

@@ -10,7 +10,7 @@ A high-performance image loading, caching, and processing library for React Nati
 
 - Load images from the network (with built-in memory and disk caching), the file system, or bundled `require()` assets
 - Prefetch single or multiple images in the background
-- Resize (aspect-fill, center-crop) and apply Gaussian blur and rounded corners (uniform or per-corner) at load time
+- Resize in every `resizeMode` (`cover`, `contain`, `stretch`, `center`) and apply Gaussian blur and rounded corners (uniform or per-corner) at load time
 - Apply Gaussian blur to already-loaded images
 - Clear the image cache on demand
 - `useImage` hook for declarative image loading in components
@@ -69,7 +69,9 @@ pixels internally, unlike the pixel-based values used everywhere else in this li
 so a style that already rounds the view rounds the bitmap too, with no separate prop. Pass
 `cornerRadius` explicitly to override that. `onLoad`/`onError` callbacks are supported, and every
 other prop (`resizeMode`, `recyclingKey`, `testID`, …) is passed straight through to
-`NativeNitroImage`.
+`NativeNitroImage`. `resizeMode` also decides how the bitmap is produced: `resizeMode="contain"`
+decodes an aspect-fitted bitmap (no crop, no padding) rather than a center-cropped one the view
+then letterboxes — see [Resize modes](#resize-modes). Pass `fit` to decouple the two.
 
 ### `<NativePipelineImage>` component
 
@@ -93,11 +95,25 @@ import { NativePipelineImage } from 'react-native-nitro-image-pipeline';
 `blur`/`cornerRadius` are in points and `style`'s `borderRadius` is picked up automatically,
 exactly like `<PipelineImage>`. The trade-offs of going fully native:
 
-- No `onLoad`/`onError` — the loaded `Image` never crosses into JS. Use `<PipelineImage>` or
-  `useImage` when you need them.
+- `onLoad` reports the bitmap's size in pixels rather than the `Image` itself, which never crosses
+  into JS — use `<PipelineImage>` or `useImage` when you need the `Image`. It means "this view is
+  now showing this image" rather than firing exactly once: a recycled cell re-attaching calls it
+  again, and a single view may call it more than once for the same image. Make it idempotent.
+- Setting `onLoad`/`onError` means there is per-image JS work again. Leave them unset (the default)
+  and nothing crosses into JS at all.
 - The bitmap is loaded once at the size the view first has; if the view resizes later, the bitmap
   scales with it instead of reloading.
 
+```tsx
+<NativePipelineImage
+  url={url}
+  style={styles.photo}
+  // Bitmap pixels, not points. Inline arrows are fine — they don't reload it.
+  onLoad={(width, height) => console.log(`loaded ${width}×${height}`)}
+  onError={(message) => setFailed(message)}
+/>;
+```
+
 Under the hood this is `NitroImagePipeline.createImageLoader(url, options)` — an
 [`ImageLoader`](https://github.com/mrousavy/react-native-nitro-image) driven by
 `NativeNitroImage` — so you can also use the `usePipelineImageLoader(url, options)` hook directly
@@ -292,10 +308,48 @@ a plain absolute path, or the other forms listed under
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `blur` | `number` | `0` | Gaussian blur strength applied at load time — see [Blur units](#blur-units) |
-| `resize` | `{ width, height }` | source size | Target bitmap size in pixels. Scales to fill and center-crops (CSS `object-fit: cover`, upscaling if needed) before `blur`/`cornerRadius` run, so their pixel units refer to this final size. Typically your display size in points × `PixelRatio.get()` |
+| `resize` | `{ width, height, fit?, allowUpscale? }` | source size | Target bitmap box in pixels. By default scales to fill and center-crops (CSS `object-fit: cover`, upscaling if needed); `fit` selects the other modes and `allowUpscale: false` never enlarges the source — see [Resize modes](#resize-modes). Runs before `blur`/`cornerRadius`, so their pixel units refer to the produced bitmap. Typically your display size in points × `PixelRatio.get()` |
 | `cornerRadius` | `number \| CornerRadii` | `0` | Corner radius in pixels of the produced bitmap — a single number for all four corners, or `{ topLeft?, topRight?, bottomLeft?, bottomRight? }` for independent per-corner radii (omitted corners stay square). Pair with `resize` for radii that match your layout |
 | `cache` | `'memory' \| 'disk' \| 'none'` | platform default | Caching strategy |
 
+#### Resize modes
+
+`resize.fit` takes the same four values as `NativeNitroImage`'s `resizeMode`, so the bitmap can be
+produced the way the view will display it. With a `w × h` source and a `W × H` box:
+
+| `fit` | Scale | Produced bitmap | Notes |
+|---|---|---|---|
+| `'cover'` (default) | `max(W/w, H/h)` | exactly `W × H` | Center-cropped. Unchanged from earlier versions, byte for byte |
+| `'contain'` | `min(W/w, H/h)` | `round(w·s) × round(h·s)` | Aspect-fit. The bitmap is **not** padded to the box |
+| `'stretch'` | `W/w` and `H/h` independently | exactly `W × H` | Aspect ratio ignored |
+| `'center'` | `1` | `min(w, W) × min(h, H)` | Never resamples; only center-crops what the box could not show |
+
+`allowUpscale: false` clamps the scale to at most 1 for `cover`, `contain` and `stretch`, so a
+source smaller than the box keeps its own size (under `cover` it is only cropped to the box). It
+has no effect on `center`, which never scales. Some examples:
+
+| Source → box | `cover` | `contain` | `stretch` | `center` |
+|---|---|---|---|---|
+| 2000×1000 → 400×400 | 400×400 | 400×200 | 400×400 | 400×400 (cropped) |
+| 100×50 → 400×400 | 400×400 | 400×200 | 400×400 | 100×50 |
+| 100×50 → 400×400, `allowUpscale: false` | 100×50 | 100×50 | 100×50 | 100×50 |
+
+`blur` and `cornerRadius` apply to the produced bitmap, so under `contain` the corners round the
+image's own edges, not the box's. Displaying a `center` bitmap pixel for pixel needs the view's
+`resizeMode="center"`, which `<NativePipelineImage>` (and `createImageLoader`) draw 1:1 on both
+platforms; an `Image` passed to `<NativeNitroImage>` or `<PipelineImage>` is a scale-1 image that
+iOS's `center` mode draws at 1 pt per pixel (nitro-image's `Image` contract — `PixelRatio.get()`×
+too large on a Retina screen). Both platforms implement the same geometry (down to the
+rounding), and the harness suites check every cell of this table on each. How much is decoded before
+the resize depends on the mode. `contain` decodes aspect-fit, so the decode is always near the
+produced size. `cover` and `stretch` decode aspect-*fill* — the source scaled until it covers the
+box — which is near the produced size when the aspect ratios are similar, but a source whose
+aspect ratio differs sharply from the box (a panorama into a square) is decoded larger, up to its
+full size, before the crop or stretch; `cover` has always worked this way, and `stretch` needs the
+fill scale to keep the axis that is shrunk less from being resampled up from a few pixels.
+`center` decodes the source at full resolution — it has to see the source's own pixels. Prefer
+`contain`, or a box with a similar aspect ratio, for very large images.
+
 ### `<PipelineImage>`
 
 | Prop | Type | Default | Description |
@@ -305,6 +359,8 @@ a plain absolute path, or the other forms listed under
 | `blur` | `number` | `0` | Gaussian blur strength, in **points** (converted to bitmap pixels internally) |
 | `cornerRadius` | `number \| CornerRadii` | derived from `style` | Corner radius, in **points** (converted to bitmap pixels internally). When omitted, derived from `style`'s `borderRadius`/`borderTopLeftRadius`/etc.; square if neither is set |
 | `cache` | `'memory' \| 'disk' \| 'none'` | platform default | Caching strategy |
+| `fit` | `ResizeFit` | derived from `resizeMode` | How the bitmap is fitted into the display size — see [Resize modes](#resize-modes). When omitted it follows `resizeMode` (`'cover'` if that is unset too); set it to decouple the two. On iOS, `resizeMode="center"` draws the (scale-1) `Image` at 1 pt per pixel — a nitro-image `Image` limitation; use `<NativePipelineImage>` for pixel-exact `center` on both platforms |
+| `allowUpscale` | `boolean` | `true` | `false` never enlarges a source smaller than the display size when the *bitmap* is produced (nothing is decoded or blurred larger than the source). The view still scales it per `resizeMode`; use `resizeMode="center"` to show it at its natural size |
 | `onLoad` | `(image: Image) => void` | — | Called when the image finishes loading |
 | `onError` | `(error: Error) => void` | — | Called if loading fails |
 | `onLayout` | `(event: LayoutChangeEvent) => void` | — | Standard `View` layout callback; also drives the deferred resize for non-numeric sizes |
@@ -320,21 +376,34 @@ a plain absolute path, or the other forms listed under
 | `blur` | `number` | `0` | Gaussian blur strength, in **points** (screen scale applied natively) |
 | `cornerRadius` | `number \| CornerRadii` | derived from `style` | Corner radius, in **points** (screen scale applied natively) |
 | `cache` | `'memory' \| 'disk' \| 'none'` | platform default | Caching strategy |
-| `resize` | `{ width, height }` | measured from the view | Explicit target bitmap size in **pixels**, skipping the native measurement. Rarely needed |
+| `resize` | `{ width, height, fit?, allowUpscale? }` | measured from the view | Explicit target bitmap box in **pixels**, skipping the native measurement. Rarely needed |
+| `fit` | `ResizeFit` | derived from `resizeMode` | How the bitmap is fitted into the measured size — see [Resize modes](#resize-modes). Follows `resizeMode` when omitted; set it to decouple the two |
+| `allowUpscale` | `boolean` | `true` | `false` never enlarges a source smaller than the view when the *bitmap* is produced. The view still scales it per `resizeMode`; `resizeMode="center"` shows it pixel for pixel on both platforms |
+| `onLoad` | `(width: number, height: number) => void` | — | Called when the view has displayed the image, with the bitmap's size in **pixels**. Hands you the size rather than the `Image`, which stays native. Not a one-shot event — a recycled cell calls it again on re-attach, and one view may call it more than once for the same image, so make it idempotent |
+| `onError` | `(message: string) => void` | — | Called when loading fails, with the error's message. A load cancelled by the view detaching is not a failure. Without it, failures on this component are silent |
 | `ref` | `Ref<NativePipelineImageRef>` | — | Forwarded to the underlying `NativeNitroImage` host view |
 | `…NativeNitroImage props` | — | — | Everything else (`resizeMode`, `recyclingKey`, `testID`, …) is passed through; `recyclingKey` defaults to `url` |
 
-No `onLoad`/`onError`: loading happens entirely natively and the result never crosses into JS.
+`onLoad`/`onError` are the only things that cross into JS here, and only when you pass them: unset,
+loading happens entirely natively. The `Image` itself never crosses — use `<PipelineImage>` or
+`useImage` for that.
 
 ### `createImageLoader(url, options?)` / `usePipelineImageLoader(source, options?)`
 
 Creates the [`ImageLoader`](https://github.com/mrousavy/react-native-nitro-image) that powers
 `<NativePipelineImage>`, for use with your own `<NativeNitroImage image={loader} />`. The view
 calls into it natively when it attaches (load at the view's laid-out size) and detaches
-(cancel + release). `options` takes `blur`/`cornerRadius` in **points** and an optional
-pixel-based `resize` override — see the `ViewOptions` type. The hook memoizes by value, so
-inline options literals are fine, and its `source` may be a `require()` as well as a URL string.
-`loader.loadImage()` also works imperatively and resolves with the processed `Image`.
+(cancel + release). `options` takes `blur`/`cornerRadius` in **points**, an optional
+pixel-based `resize` override, and `fit`/`allowUpscale` for the box the view measures (pass the
+view's `resizeMode` as `fit`; a `resize` that carries its own wins) — see the `ViewOptions` type.
+Unlike the callbacks, `fit` is part of what is loaded, so changing it swaps the loader. It also
+takes the optional
+`onLoad(width, height)`/`onError(message)` callbacks a view reports its loads through; without
+them the loader never calls into JS. The hook memoizes by value, so inline options literals are
+fine — the callbacks are read through a ref, so inline arrows don't reload the image either — and
+its `source` may be a `require()` as well as a URL string. `loader.loadImage()` also works
+imperatively and resolves with the processed `Image`; it reports through its promise, not through
+`onLoad`/`onError`.
 
 ### `resolveImageUrl(source)`
 
@@ -351,7 +420,9 @@ resolve, so the request fails at load time like a missing file.
 Converts a layout size in points to a bitmap `resize` option in pixels. Returns
 `{ width, height }` in whole pixels via `PixelRatio.getPixelSizeForLayoutSize`, or `undefined` for
 non-numeric sizes (e.g. `'100%'`, `undefined`) — `resizeForStyle` reads `style.width`/`style.height`,
-`resizeForLayout` takes explicit numbers.
+`resizeForLayout` takes explicit numbers. Spread a `fit` into the result for the other
+[resize modes](#resize-modes); under `contain` and `center` the size is then the box the bitmap
+fits in, not necessarily its final size.
 
 ### `cornerRadiusForStyle(style)`
 
@@ -438,7 +509,11 @@ The pipeline is set up so RAM scales with what you display, not with what you do
 - **Pass `resize` (or just use `<PipelineImage>`, which derives it from layout).** With a target
   size known, both platforms decode the source *near that size* instead of at full resolution —
   iOS via a downsampled thumbnail decode, Android via Coil's subsampling. Without `resize`, a
-  48 MP photo decompresses to ~190 MB of bitmap no matter how small you display it.
+  48 MP photo decompresses to ~190 MB of bitmap no matter how small you display it. "Near that
+  size" means the aspect-*fill* decode for `cover` and `stretch` — the source scaled until it
+  covers the box, so a panorama into a square box still decodes near its full width — and the
+  aspect-fit decode for `contain`, which is always near the produced size. `fit: 'center'` by
+  definition needs the source's own pixels and decodes at full resolution before cropping.
 - **Android draws transformed images from hardware bitmaps** (API 26+). When a view loads its
   image natively (`<NativePipelineImage>`, or `<NativeNitroImage image={createImageLoader(...)}>`),
   a resized, blurred or rounded result is uploaded to a `Bitmap.Config.HARDWARE` bitmap once and

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

@@ -19,6 +19,7 @@ import coil3.request.ImageRequest
 import coil3.request.SuccessResult
 import coil3.request.allowHardware
 import coil3.request.transformations
+import coil3.size.Precision
 import coil3.size.Scale
 import coil3.size.Size
 import coil3.transform.RoundedCornersTransformation
@@ -29,6 +30,7 @@ import com.margelo.nitro.image.HybridImage
 import com.margelo.nitro.image.HybridImageSpec
 import com.margelo.nitro.nitroimagepipeline.transform.BlurTransformation
 import com.margelo.nitro.nitroimagepipeline.transform.HardwareBitmapTransformation
+import com.margelo.nitro.nitroimagepipeline.transform.PipelineRoundedCornersTransformation
 import com.margelo.nitro.nitroimagepipeline.transform.ResizeTransformation
 import kotlin.math.roundToInt
 import kotlinx.coroutines.CoroutineScope
@@ -152,21 +154,27 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
             val height = r.height.roundToInt()
             if (width > 0 && height > 0) width to height else null
           }
-      val roundedCorners: RoundedCornersTransformation? =
+      val fit = options?.resize?.fit ?: ResizeFit.COVER
+      val allowUpscale = options?.resize?.allowUpscale ?: true
+      // The resize as it behaved before `fit` existed — aspect-fill, crop,
+      // upscale — which keeps the original transformations and cache keys.
+      val isDefaultFit = fit == ResizeFit.COVER && allowUpscale
+      // Radii in bitmap pixels as (topLeft, topRight, bottomLeft, bottomRight),
+      // or null when no corner is actually rounded. Negative radii are square.
+      val cornerRadii: FloatArray? =
           options
               ?.cornerRadius
               ?.match(
                   first = { radius ->
-                    if (radius > 0.0) RoundedCornersTransformation(radius.toFloat()) else null
+                    if (radius > 0.0) FloatArray(4) { radius.toFloat() } else null
                   },
                   second = { radii ->
-                    // RoundedCornersTransformation rejects negative radii; treat them as square.
                     val topLeft = (radii.topLeft?.toFloat() ?: 0f).coerceAtLeast(0f)
                     val topRight = (radii.topRight?.toFloat() ?: 0f).coerceAtLeast(0f)
                     val bottomLeft = (radii.bottomLeft?.toFloat() ?: 0f).coerceAtLeast(0f)
                     val bottomRight = (radii.bottomRight?.toFloat() ?: 0f).coerceAtLeast(0f)
                     if (topLeft > 0f || topRight > 0f || bottomLeft > 0f || bottomRight > 0f) {
-                      RoundedCornersTransformation(topLeft, topRight, bottomLeft, bottomRight)
+                      floatArrayOf(topLeft, topRight, bottomLeft, bottomRight)
                     } else {
                       null
                     }
@@ -177,14 +185,25 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
         // they run on, so they must see the final size. Coil's
         // RoundedCornersTransformation already scale-fills and center-crops
         // to the request size (`resize`, when set) as part of its own draw,
-        // so with rounded corners and no blur the explicit resize would only
-        // add an intermediate bitmap — and the radii still apply to the final
-        // size, because that is the size its output has.
-        if (resize != null && (blur > 0f || roundedCorners == null)) {
-          add(ResizeTransformation(resize.first, resize.second))
+        // so with the default fit, rounded corners and no blur the explicit
+        // resize would only add an intermediate bitmap — and the radii still
+        // apply to the final size, because that is the size its output has.
+        // Any other fit produces a bitmap that may be smaller than the box,
+        // so it always resizes explicitly and rounds at the produced size.
+        if (resize != null && (blur > 0f || cornerRadii == null || !isDefaultFit)) {
+          add(ResizeTransformation(resize.first, resize.second, fit, allowUpscale))
         }
         if (blur > 0f) add(BlurTransformation(blur))
-        roundedCorners?.let { add(it) }
+        cornerRadii?.let { (topLeft, topRight, bottomLeft, bottomRight) ->
+          if (resize == null || isDefaultFit) {
+            // The uniform constructor keeps the original cache key for a single radius.
+            val uniform = topLeft == topRight && topLeft == bottomLeft && topLeft == bottomRight
+            if (uniform) add(RoundedCornersTransformation(topLeft))
+            else add(RoundedCornersTransformation(topLeft, topRight, bottomLeft, bottomRight))
+          } else {
+            add(PipelineRoundedCornersTransformation(topLeft, topRight, bottomLeft, bottomRight))
+          }
+        }
         // Without transformations Coil decodes straight to a hardware bitmap
         // already (allowHardware below); only a transformed result needs the
         // explicit upload.
@@ -212,10 +231,22 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
             }
             // Ask the decoder for the target size so a large source is
             // subsampled near it instead of decoded at full resolution;
-            // ResizeTransformation then makes the size exact.
-            resize?.let { (width, height) ->
-              size(width, height)
-              scale(Scale.FILL)
+            // ResizeTransformation then makes the size exact. `contain`
+            // decodes to *fit* the box: its output follows the smaller
+            // scale, and a fill decode of a wide panorama into a small box
+            // would be near the source's full width before the
+            // transformation shrinks it (iOS's aspect-fit thumbnail bounds
+            // it the same way). `center` never scales, so it must see the
+            // source's own pixels — the default Size.ORIGINAL — or it would
+            // crop the wrong ones.
+            if (resize != null && fit != ResizeFit.CENTER) {
+              size(resize.first, resize.second)
+              scale(if (fit == ResizeFit.CONTAIN) Scale.FIT else Scale.FILL)
+              // With an explicit size Coil also *upscales* the decode to it,
+              // which the default fit doesn't mind (the transformation ends
+              // at the box anyway) but `allowUpscale: false` and `contain`
+              // must not see. Only subsample; the transformation scales.
+              if (!isDefaultFit) precision(Precision.INEXACT)
             }
           }
           .allowHardware(true)
@@ -225,12 +256,12 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
 
     /**
      * What Coil should load for [url]. Coil itself handles `http(s)://`, `file://`, `content://`
-     * and plain absolute paths. The one form it doesn't is a bare resource name — a string with
-     * no scheme, like `src_assets_logo` — which is what React Native's `require()` resolves to
-     * in a release build (assets are packed into `res/drawable-*`). Resolve that to the resource
-     * id here; the density-qualified variant is then picked by the resources system, like
-     * `<Image>` does. An unknown name is passed through so Coil reports the failure as an
-     * [ErrorResult] (the loaders must not throw while building a request).
+     * and plain absolute paths. The one form it doesn't is a bare resource name — a string with no
+     * scheme, like `src_assets_logo` — which is what React Native's `require()` resolves to in a
+     * release build (assets are packed into `res/drawable-*`). Resolve that to the resource id
+     * here; the density-qualified variant is then picked by the resources system, like `<Image>`
+     * does. An unknown name is passed through so Coil reports the failure as an [ErrorResult] (the
+     * loaders must not throw while building a request).
      */
     internal fun requestData(context: Context, url: String): Any {
       if (url.startsWith("/") || url.toUri().scheme != null) return url

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

@@ -15,6 +15,7 @@ import com.margelo.nitro.image.HybridImageSpec
 import com.margelo.nitro.image.HybridImageView
 import com.margelo.nitro.image.HybridNitroImageViewSpec
 import kotlin.coroutines.resume
+import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
@@ -36,6 +37,11 @@ import kotlinx.coroutines.suspendCancellableCoroutine
  * the shared request builder using the display density, so cache keys match an equivalent
  * `loadImage` call. View sizes are already physical pixels on Android, so only blur and corner
  * radii need scaling.
+ *
+ * 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 — `HybridImageView` requests both when its `image` is set and when
+ * it becomes visible. [loadImage] does not call them — it reports through its promise instead.
  */
 @DoNotStrip
 @Keep
@@ -56,7 +62,8 @@ class PipelineImageLoader(
 
   /**
    * The point-based [ViewOptions] as pixel-based [Options], resolved against the display [scale]
-   * and the target size in pixels.
+   * 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 fun pixelOptions(scale: Float, resize: ResizeOptions?): Options {
     val cornerRadius =
@@ -79,7 +86,15 @@ class PipelineImageLoader(
         blur = options?.blur?.times(scale),
         cache = options?.cache,
         cornerRadius = cornerRadius,
-        resize = resize,
+        resize =
+            resize?.let {
+              ResizeOptions(
+                  width = it.width,
+                  height = it.height,
+                  fit = it.fit ?: options?.fit,
+                  allowUpscale = it.allowUpscale ?: options?.allowUpscale,
+              )
+            },
     )
   }
 
@@ -123,10 +138,18 @@ class PipelineImageLoader(
       // touch the view.
       if (!isActive) return@launch
       when (result) {
-        is SuccessResult -> imageView.setImageBitmap(HybridNitroImagePipeline.bitmapOf(result))
-        // Deliberately no URL in the message — signed URLs and query
-        // tokens must not leak into consuming apps' Logcat.
-        is ErrorResult -> Log.w(TAG, "Failed to load image", result.throwable)
+        is SuccessResult -> {
+          val bitmap = HybridNitroImagePipeline.bitmapOf(result)
+          imageView.setImageBitmap(bitmap)
+          report { options?.onLoad?.invoke(bitmap.width.toDouble(), bitmap.height.toDouble()) }
+        }
+        is ErrorResult -> {
+          // Deliberately no URL in the message — signed URLs and query
+          // tokens must not leak into consuming apps' Logcat.
+          val throwable = result.throwable
+          Log.w(TAG, "Failed to load image", throwable)
+          report { options?.onError?.invoke(throwable.message ?: throwable.toString()) }
+        }
       }
     }
     jobs[forView] = job
@@ -139,10 +162,26 @@ class PipelineImageLoader(
     view.imageView.setImageDrawable(null)
   }
 
+  /**
+   * Reports to JS. Calling a JS callback throws if the callback itself throws, or if the runtime is
+   * already gone — a load can land after it was torn down or reloaded — and an exception escaping
+   * this coroutine would reach the thread's uncaught handler and take the app with it. A report
+   * nobody is left to receive is not worth a crash.
+   */
+  private fun report(block: () -> Unit) {
+    try {
+      block()
+    } catch (cancellation: CancellationException) {
+      throw cancellation
+    } catch (throwable: Throwable) {
+      Log.w(TAG, "Image callback failed", throwable)
+    }
+  }
+
   /** The view's laid-out size in pixels, suspending until it has one. */
   private suspend fun measuredSize(view: ImageView): ResizeOptions {
     if (view.width > 0 && view.height > 0) {
-      return ResizeOptions(view.width.toDouble(), view.height.toDouble())
+      return ResizeOptions(view.width.toDouble(), view.height.toDouble(), null, null)
     }
     return suspendCancellableCoroutine { continuation ->
       val listener =
@@ -162,7 +201,7 @@ class PipelineImageLoader(
               val height = bottom - top
               if (width > 0 && height > 0) {
                 v.removeOnLayoutChangeListener(this)
-                continuation.resume(ResizeOptions(width.toDouble(), height.toDouble()))
+                continuation.resume(ResizeOptions(width.toDouble(), height.toDouble(), null, null))
               }
             }
           }

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

@@ -0,0 +1,104 @@
+package com.margelo.nitro.nitroimagepipeline.transform
+
+import com.margelo.nitro.nitroimagepipeline.ResizeFit
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.roundToInt
+
+/**
+ * The resize geometry both platforms implement — a port of `FitGeometry` in
+ * `ios/FitResizeProcessor.swift`; `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 (`roundToInt()` here, `.rounded()` in Swift — identical for the positive
+ * values involved), and the divisions are done in the same order in `Double` on both sides so the
+ * two agree to the pixel.
+ */
+internal data class FitGeometry(
+    val sourceWidth: Int,
+    val sourceHeight: Int,
+    val scaledWidth: Int,
+    val scaledHeight: Int,
+    val outputWidth: Int,
+    val outputHeight: Int,
+    val originX: Int,
+    val originY: Int,
+) {
+  /**
+   * 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.
+   */
+  val isIdentity: Boolean
+    get() =
+        scaledWidth == sourceWidth &&
+            scaledHeight == sourceHeight &&
+            outputWidth == sourceWidth &&
+            outputHeight == sourceHeight
+
+  companion object {
+    fun of(
+        sourceWidth: Int,
+        sourceHeight: Int,
+        boxWidth: Int,
+        boxHeight: Int,
+        fit: ResizeFit,
+        allowUpscale: Boolean,
+    ): FitGeometry {
+      val source = sourceWidth.toDouble() to sourceHeight.toDouble()
+      val box = boxWidth.toDouble() to boxHeight.toDouble()
+      var scaleX: Double
+      var scaleY: Double
+      when (fit) {
+        ResizeFit.COVER -> {
+          val scale = max(box.first / source.first, box.second / source.second)
+          scaleX = scale
+          scaleY = scale
+        }
+        ResizeFit.CONTAIN -> {
+          val scale = min(box.first / source.first, box.second / source.second)
+          scaleX = scale
+          scaleY = scale
+        }
+        ResizeFit.STRETCH -> {
+          scaleX = box.first / source.first
+          scaleY = box.second / source.second
+        }
+        ResizeFit.CENTER -> {
+          scaleX = 1.0
+          scaleY = 1.0
+        }
+      }
+      if (!allowUpscale) {
+        scaleX = min(scaleX, 1.0)
+        scaleY = min(scaleY, 1.0)
+      }
+      val scaledWidth = (source.first * scaleX).roundToInt().coerceAtLeast(1)
+      val scaledHeight = (source.second * scaleY).roundToInt().coerceAtLeast(1)
+      val outputWidth = min(boxWidth, scaledWidth)
+      val outputHeight = min(boxHeight, scaledHeight)
+      return FitGeometry(
+          sourceWidth = sourceWidth,
+          sourceHeight = sourceHeight,
+          scaledWidth = scaledWidth,
+          scaledHeight = scaledHeight,
+          outputWidth = outputWidth,
+          outputHeight = outputHeight,
+          // Integer division truncates toward zero, like `.rounded(.towardZero)` on iOS.
+          originX = (outputWidth - scaledWidth) / 2,
+          originY = (outputHeight - scaledHeight) / 2,
+      )
+    }
+  }
+}

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

@@ -0,0 +1,103 @@
+package com.margelo.nitro.nitroimagepipeline.transform
+
+import android.graphics.Bitmap
+import android.graphics.BitmapShader
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.Path
+import android.graphics.RectF
+import android.graphics.Shader
+import coil3.size.Size
+import coil3.transform.Transformation
+import kotlin.math.min
+
+/**
+ * Rounds the corners of the input **at its own size**, in pixels of that bitmap — a port of
+ * `ios/RoundedCornersProcessor.swift`, including its CSS-style clamping of radii that overlap.
+ *
+ * Coil's own `RoundedCornersTransformation` scale-fills and crops its input to the *request* size
+ * as part of its draw. That is right for the default resize (the request size is the output size)
+ * and is why [ResizeTransformation] is skipped for "rounded corners, no blur" there. Under any
+ * other fit the request size is only the box — a `contain` or `center` bitmap is smaller — so
+ * Coil's transformation would scale the result back up to the box. This one leaves the size alone.
+ */
+class PipelineRoundedCornersTransformation(
+    topLeft: Float,
+    topRight: Float,
+    bottomLeft: Float,
+    bottomRight: Float,
+) : Transformation() {
+  // Negative radii would make the path undefined; treat them as square.
+  private val topLeft = topLeft.coerceAtLeast(0f)
+  private val topRight = topRight.coerceAtLeast(0f)
+  private val bottomLeft = bottomLeft.coerceAtLeast(0f)
+  private val bottomRight = bottomRight.coerceAtLeast(0f)
+
+  override val cacheKey =
+      "${PipelineRoundedCornersTransformation::class.java.name}-$topLeft-$topRight-$bottomLeft-$bottomRight"
+
+  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
+    val width = softwareInput.width
+    val height = softwareInput.height
+    if (width <= 0 || height <= 0) return softwareInput
+
+    // Clamp the way CSS `border-radius` does: if two radii on one edge
+    // overlap, all four scale down proportionally until they fit.
+    var scale = 1f
+    for ((edge, pair) in
+        listOf(
+            width to topLeft + topRight,
+            width to bottomLeft + bottomRight,
+            height to topLeft + bottomLeft,
+            height to topRight + bottomRight,
+        )) {
+      if (pair > edge) scale = min(scale, edge / pair)
+    }
+    val tl = topLeft * scale
+    val tr = topRight * scale
+    val bl = bottomLeft * scale
+    val br = bottomRight * scale
+
+    val path =
+        Path().apply {
+          addRoundRect(
+              RectF(0f, 0f, width.toFloat(), height.toFloat()),
+              // x/y radius pairs, clockwise from the top-left corner.
+              floatArrayOf(tl, tl, tr, tr, br, br, bl, bl),
+              Path.Direction.CW,
+          )
+        }
+    val paint =
+        Paint(Paint.ANTI_ALIAS_FLAG or Paint.FILTER_BITMAP_FLAG).apply {
+          shader = BitmapShader(softwareInput, Shader.TileMode.CLAMP, Shader.TileMode.CLAMP)
+        }
+    // Always ARGB_8888: the corners need an alpha channel whatever the input has.
+    val output = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+    Canvas(output).drawPath(path, paint)
+    return output
+  }
+
+  override fun equals(other: Any?): Boolean {
+    if (this === other) return true
+    return other is PipelineRoundedCornersTransformation &&
+        topLeft == other.topLeft &&
+        topRight == other.topRight &&
+        bottomLeft == other.bottomLeft &&
+        bottomRight == other.bottomRight
+  }
+
+  override fun hashCode(): Int {
+    var result = topLeft.hashCode()
+    result = 31 * result + topRight.hashCode()
+    result = 31 * result + bottomLeft.hashCode()
+    result = 31 * result + bottomRight.hashCode()
+    return result
+  }
+
+  override fun toString() =
+      "PipelineRoundedCornersTransformation(topLeft=$topLeft, topRight=$topRight, " +
+          "bottomLeft=$bottomLeft, bottomRight=$bottomRight)"
+}