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

package/README.md

@@ -8,9 +8,9 @@ A high-performance image loading, caching, and processing library for React Nati
 
 ## Features
 
-- Load remote images with built-in memory and disk caching
+- 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
@@ -177,6 +193,41 @@ function BlurFade({ url, blurred }: { url: string; blurred: boolean }) {
 }
 ```
 
+### Local images and `require()`
+
+Every `url` in this library — `<PipelineImage>`, `<NativePipelineImage>`, `useImage`,
+`usePipelineImageLoader` — also takes a `require()`d asset, and any `url` string may point at the
+file system. The image goes through the same pipeline, so a bundled logo or a photo from the camera
+roll gets the same resize-to-layout, blur and rounded corners as a download:
+
+```tsx
+// A bundled asset — streamed from Metro in debug, read from the app bundle /
+// resources in release, at the scale that matches the screen (like <Image>).
+<PipelineImage url={require('./assets/logo.png')} style={styles.logo} blur={2} />
+
+// A file on disk — a `file://` URL or a plain absolute path, e.g. the path
+// react-native-nitro-image's `saveToTemporaryFileAsync` returns.
+<NativePipelineImage url={`file://${photoPath}`} style={styles.thumb} />
+<NativePipelineImage url={photoPath} style={styles.thumb} />
+```
+
+The direct `NitroImagePipeline.loadImage`/`createImageLoader` calls take a string; resolve a
+`require()` first with `resolveImageUrl`:
+
+```ts
+import { NitroImagePipeline, resolveImageUrl } from 'react-native-nitro-image-pipeline';
+
+const logo = await NitroImagePipeline.loadImage(resolveImageUrl(require('./assets/logo.png')), {
+  resize: { width: 200, height: 200 },
+});
+```
+
+Accepted `url` forms: `http(s)://`, `file://`, a plain absolute path, `data:`, and on Android also
+`content://` URIs and bare drawable resource names (what `require()` resolves to in a release build
+there). Local sources are cached **in memory only** — there is nothing to gain from copying a file
+that is already on disk into the disk cache — so `cache: 'disk'` on a local `url` means no caching,
+and `preLoadImage(s)` treats local sources as a no-op.
+
 ### `useImage` hook
 
 The simplest way to load an image in a component:
@@ -249,24 +300,67 @@ await NitroImagePipeline.clearCache();
 
 ### `loadImage(url, options?)`
 
-Loads an image from a URL and returns a `Promise<Image>`.
+Loads an image from a URL and returns a `Promise<Image>`. `url` is a string — `http(s)://`, `file://`,
+a plain absolute path, or the other forms listed under
+[Local images and `require()`](#local-images-and-require); pass a `require()` through
+[`resolveImageUrl`](#resolveimageurlsource) first.
 
 | 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 |
 |---|---|---|---|
-| `url` | `string` | — | Image URL to load |
+| `url` | `string \| number` | — | Image to load: a URL string (`https://`, `file://`, an absolute path) or a `require()`d asset |
 | `style` | `StyleProp<ViewStyle>` | — | Layout style; also determines the resize target (see [`resizeForStyle`](#resizeforstyle-style--resizeforlayoutwidth-height)) and, if `cornerRadius` is omitted, the corner radius (see [`cornerRadiusForStyle`](#cornerradiusforstylestyle)) |
 | `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 |
@@ -277,33 +371,58 @@ Loads an image from a URL and returns a `Promise<Image>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `url` | `string` | — | Image URL to load |
+| `url` | `string \| number` | — | Image to load: a URL string (`https://`, `file://`, an absolute path) or a `require()`d asset |
 | `style` | `StyleProp<ViewStyle>` | — | Layout style. The native side measures the view and loads at that size; `borderRadius`-family properties drive `cornerRadius` when it's omitted |
 | `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(url, options?)`
+### `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. `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)`
+
+Turns an `ImageSource` (`string | number`) into the URL string the native pipeline loads: strings
+pass through unchanged, a `require()`d asset is resolved with `Image.resolveAssetSource` to the
+scale-matched variant. The components and hooks do this internally; use it when calling
+`loadImage`, `createImageLoader` or `preLoadImage(s)` directly with a `require()`. Throws if the
+number is not a registered asset; the components and hooks never throw for one — `useImage` reports
+it through `error`, and `usePipelineImageLoader`/`<NativePipelineImage>` load a URL no loader can
+resolve, so the request fails at load time like a missing file.
 
 ### `resizeForStyle(style)` / `resizeForLayout(width, height)`
 
 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)`
 
@@ -317,6 +436,7 @@ omitted.
 ### `preLoadImage(url)`
 
 Prefetches a single image into the **disk cache**, without decoding it. Returns `Promise<void>`.
+Local sources (`file://`, paths, resources) have no download to cache and are a no-op.
 
 Prefetching only pays the network and disk I/O cost up front — no bitmap is decoded or held in
 memory, so prefetching a long list of URLs doesn't balloon RAM. The image is decoded (at the
@@ -389,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

@@ -3,6 +3,7 @@ package com.margelo.nitro.nitroimagepipeline
 import android.content.Context
 import android.graphics.Bitmap
 import androidx.core.graphics.drawable.toBitmap
+import androidx.core.net.toUri
 import coil3.BitmapImage
 import coil3.ColorImage
 import coil3.DrawableImage
@@ -18,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
@@ -28,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
@@ -76,7 +79,7 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
   // size — only when a loadImage actually displays it.
   private fun preloadRequest(url: String): ImageRequest =
       ImageRequest.Builder(context)
-          .data(url)
+          .data(requestData(context, url))
           .memoryCachePolicy(CachePolicy.DISABLED)
           .decoderFactory { _, _, _ -> Decoder { DecodeResult(ColorImage(), false) } }
           .build()
@@ -151,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
                     }
@@ -176,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.
@@ -192,7 +212,7 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
         }
       }
       return ImageRequest.Builder(context)
-          .data(url)
+          .data(requestData(context, url))
           .apply {
             when (options?.cache) {
               CacheOption.MEMORY -> {
@@ -211,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)
@@ -222,6 +254,30 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
           .build()
     }
 
+    /**
+     * 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).
+     */
+    internal fun requestData(context: Context, url: String): Any {
+      if (url.startsWith("/") || url.toUri().scheme != null) return url
+      // Tolerate `logo.png`: RN's generated names carry no extension, but nitro-image's
+      // `{ resource: 'logo.png' }` convention does.
+      val name = url.substringBefore('.')
+      for (type in RESOURCE_TYPES) {
+        val id = context.resources.getIdentifier(name, type, context.packageName)
+        if (id != 0) return id
+      }
+      return url
+    }
+
+    /** Where React Native puts bundled image assets, then the other image resource types. */
+    private val RESOURCE_TYPES = arrayOf("drawable", "mipmap", "raw")
+
     /** The decoded bitmap of a successful load. */
     internal fun bitmapOf(result: SuccessResult): Bitmap =
         when (val img = result.image) {

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,
+      )
+    }
+  }
+}