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

package/nitrogen/generated/shared/c++/ViewOptions.hpp

@@ -34,12 +34,17 @@ namespace margelo::nitro::nitroimagepipeline { enum class CacheOption; }
 namespace margelo::nitro::nitroimagepipeline { struct CornerRadii; }
 // Forward declaration of `ResizeOptions` to properly resolve imports.
 namespace margelo::nitro::nitroimagepipeline { struct ResizeOptions; }
+// Forward declaration of `ResizeFit` to properly resolve imports.
+namespace margelo::nitro::nitroimagepipeline { enum class ResizeFit; }
 
 #include <optional>
 #include "CacheOption.hpp"
 #include "CornerRadii.hpp"
 #include <variant>
 #include "ResizeOptions.hpp"
+#include "ResizeFit.hpp"
+#include <functional>
+#include <string>
 
 namespace margelo::nitro::nitroimagepipeline {
 
@@ -52,13 +57,17 @@ namespace margelo::nitro::nitroimagepipeline {
     std::optional<CacheOption> cache     SWIFT_PRIVATE;
     std::optional<std::variant<double, CornerRadii>> cornerRadius     SWIFT_PRIVATE;
     std::optional<ResizeOptions> resize     SWIFT_PRIVATE;
+    std::optional<ResizeFit> fit     SWIFT_PRIVATE;
+    std::optional<bool> allowUpscale     SWIFT_PRIVATE;
+    std::optional<std::function<void(double /* width */, double /* height */)>> onLoad     SWIFT_PRIVATE;
+    std::optional<std::function<void(const std::string& /* message */)>> onError     SWIFT_PRIVATE;
 
   public:
     ViewOptions() = default;
-    explicit ViewOptions(std::optional<double> blur, std::optional<CacheOption> cache, std::optional<std::variant<double, CornerRadii>> cornerRadius, std::optional<ResizeOptions> resize): blur(blur), cache(cache), cornerRadius(cornerRadius), resize(resize) {}
+    explicit ViewOptions(std::optional<double> blur, std::optional<CacheOption> cache, std::optional<std::variant<double, CornerRadii>> cornerRadius, std::optional<ResizeOptions> resize, std::optional<ResizeFit> fit, std::optional<bool> allowUpscale, std::optional<std::function<void(double /* width */, double /* height */)>> onLoad, std::optional<std::function<void(const std::string& /* message */)>> onError): blur(blur), cache(cache), cornerRadius(cornerRadius), resize(resize), fit(fit), allowUpscale(allowUpscale), onLoad(onLoad), onError(onError) {}
 
   public:
-    friend bool operator==(const ViewOptions& lhs, const ViewOptions& rhs) = default;
+    // ViewOptions is not equatable because these properties are not equatable: onLoad, onError
   };
 
 } // namespace margelo::nitro::nitroimagepipeline
@@ -74,7 +83,11 @@ namespace margelo::nitro {
         JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "blur"))),
         JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::CacheOption>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cache"))),
         JSIConverter<std::optional<std::variant<double, margelo::nitro::nitroimagepipeline::CornerRadii>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cornerRadius"))),
-        JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeOptions>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "resize")))
+        JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeOptions>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "resize"))),
+        JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeFit>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "fit"))),
+        JSIConverter<std::optional<bool>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "allowUpscale"))),
+        JSIConverter<std::optional<std::function<void(double, double)>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "onLoad"))),
+        JSIConverter<std::optional<std::function<void(const std::string&)>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "onError")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitroimagepipeline::ViewOptions& arg) {
@@ -83,6 +96,10 @@ namespace margelo::nitro {
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "cache"), JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::CacheOption>>::toJSI(runtime, arg.cache));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "cornerRadius"), JSIConverter<std::optional<std::variant<double, margelo::nitro::nitroimagepipeline::CornerRadii>>>::toJSI(runtime, arg.cornerRadius));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "resize"), JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeOptions>>::toJSI(runtime, arg.resize));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "fit"), JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeFit>>::toJSI(runtime, arg.fit));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "allowUpscale"), JSIConverter<std::optional<bool>>::toJSI(runtime, arg.allowUpscale));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "onLoad"), JSIConverter<std::optional<std::function<void(double, double)>>>::toJSI(runtime, arg.onLoad));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "onError"), JSIConverter<std::optional<std::function<void(const std::string&)>>>::toJSI(runtime, arg.onError));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -97,6 +114,10 @@ namespace margelo::nitro {
       if (!JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::CacheOption>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cache")))) return false;
       if (!JSIConverter<std::optional<std::variant<double, margelo::nitro::nitroimagepipeline::CornerRadii>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cornerRadius")))) return false;
       if (!JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeOptions>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "resize")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeFit>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "fit")))) return false;
+      if (!JSIConverter<std::optional<bool>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "allowUpscale")))) return false;
+      if (!JSIConverter<std::optional<std::function<void(double, double)>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "onLoad")))) return false;
+      if (!JSIConverter<std::optional<std::function<void(const std::string&)>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "onError")))) return false;
       return true;
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-image-pipeline",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "High-performance image loading, caching, and processing for React Native, built with Nitro Modules",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",

package/src/NativePipelineImage.tsx

@@ -7,6 +7,7 @@ import { type ImageSource, recyclingKeyFor } from './resolveImageSource';
 import type {
   CacheOption,
   CornerRadii,
+  ResizeFit,
   ResizeOptions,
 } from './specs/nitro-image-toolkit.nitro';
 import { usePipelineImageLoader } from './usePipelineImageLoader';
@@ -51,6 +52,46 @@ export interface NativePipelineImageProps extends Omit<
    * @default undefined (measure the view natively)
    */
   resize?: ResizeOptions;
+  /**
+   * How the source is fitted into the measured view size when the bitmap is
+   * produced — see {@linkcode ResizeFit}. When omitted it follows
+   * `resizeMode`, like `PipelineImage`. Set this to decouple the two.
+   * @default undefined (derived from `resizeMode`, or `'cover'` if unset)
+   */
+  fit?: ResizeFit;
+  /**
+   * `false` never enlarges a source smaller than the view when the
+   * **bitmap** is produced — see {@linkcode ResizeOptions.allowUpscale}: it
+   * stays at its own pixel size, so nothing is decoded or blurred larger
+   * than the source. The **view** still displays that bitmap per
+   * `resizeMode`, so `cover`/`contain`/`stretch` scale it up on screen (and
+   * a baked `blur`/`cornerRadius` with it); `resizeMode="center"` shows it
+   * pixel for pixel instead, on both platforms.
+   * @default true
+   */
+  allowUpscale?: boolean;
+  /**
+   * Called when the view has displayed the image, with the size of the bitmap
+   * it displays in **pixels**.
+   *
+   * Unlike `PipelineImage`'s `onLoad` this doesn't hand you the `Image` — the
+   * bitmap stays native, which is the point of this component — and it means
+   * "the 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 it means there is per-image JS work again; leave it unset and the
+   * component stays free of JS round trips.
+   */
+  onLoad?: (width: number, height: number) => void;
+  /**
+   * Called when loading fails, with the underlying error's message. A load
+   * cancelled by the view detaching is not a failure and doesn't call this.
+   *
+   * Without it, failures on this component are silent — there is no `Image`
+   * and no promise to surface them.
+   */
+  onError?: (message: string) => void;
 }
 
 /**
@@ -62,8 +103,9 @@ export interface NativePipelineImageProps extends Omit<
  * 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
@@ -79,16 +121,37 @@ export const NativePipelineImage = forwardRef<
   NativePipelineImageRef,
   NativePipelineImageProps
 >(function NativePipelineImage(
-  { url, blur, cornerRadius, cache, resize, style, ...viewProps },
+  {
+    url,
+    blur,
+    cornerRadius,
+    cache,
+    resize,
+    fit,
+    allowUpscale,
+    onLoad,
+    onError,
+    style,
+    resizeMode,
+    ...viewProps
+  },
   ref,
 ) {
   // Same precedence as PipelineImage: an explicit prop wins over style.
   const effectiveCornerRadius = cornerRadius ?? 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 = usePipelineImageLoader(url, {
     blur,
     cornerRadius: effectiveCornerRadius,
     cache,
     resize,
+    // Same four values as the view's resizeMode; an explicit `fit` decouples
+    // them.
+    fit: fit ?? resizeMode,
+    allowUpscale,
+    onLoad,
+    onError,
   });
 
   return (
@@ -98,6 +161,7 @@ export const NativePipelineImage = forwardRef<
       {...viewProps}
       ref={ref}
       style={style}
+      resizeMode={resizeMode}
       image={loader}
     />
   );

package/src/PipelineImage.tsx

@@ -21,6 +21,7 @@ import type { ImageSource } from './resolveImageSource';
 import type {
   CacheOption,
   CornerRadii,
+  ResizeFit,
   ResizeOptions,
 } from './specs/nitro-image-toolkit.nitro';
 import { useImage } from './useImage';
@@ -62,6 +63,33 @@ export interface PipelineImageProps extends Omit<NativeImageProps, 'image'> {
    */
   cornerRadius?: number | CornerRadii;
   cache?: CacheOption;
+  /**
+   * How the source is fitted into the display size when the bitmap is
+   * produced — see {@linkcode ResizeFit}. When omitted it follows
+   * `resizeMode`, so `resizeMode="contain"` decodes an aspect-fitted bitmap
+   * (no crop, no padding) instead of a center-cropped one the view then
+   * letterboxes. Set this to decouple the two.
+   *
+   * One iOS caveat, inherited from nitro-image's `Image`: an `Image` handed
+   * to the view is a scale-1 image, which `resizeMode="center"` — the one
+   * mode that draws an image at its own size — shows at 1 pt per pixel,
+   * i.e. `PixelRatio.get()`× larger than Android draws it. The bitmap is
+   * right; the display is not. `NativePipelineImage` draws `center` pixel
+   * for pixel on both platforms; use it when you need that mode.
+   * @default undefined (derived from `resizeMode`, or `'cover'` if unset)
+   */
+  fit?: ResizeFit;
+  /**
+   * `false` never enlarges a source smaller than the display size when the
+   * **bitmap** is produced — see {@linkcode ResizeOptions.allowUpscale}: it
+   * stays at its own pixel size, so nothing is decoded or blurred larger
+   * than the source. The **view** still displays that bitmap per
+   * `resizeMode`, so `cover`/`contain`/`stretch` scale it up on screen (and
+   * a baked `blur`/`cornerRadius` with it); `resizeMode="center"` shows it
+   * at its natural size instead.
+   * @default true
+   */
+  allowUpscale?: boolean;
   /** Called with the processed `Image` each time a new variant resolves. */
   onLoad?: (image: Image) => void;
   /** Called when loading fails. */
@@ -119,10 +147,13 @@ export const PipelineImage = forwardRef<PipelineImageRef, PipelineImageProps>(
       blur = 0,
       cornerRadius,
       cache,
+      fit,
+      allowUpscale,
       onLoad,
       onError,
       style,
       onLayout,
+      resizeMode,
       ...viewProps
     },
     ref,
@@ -134,7 +165,13 @@ export const PipelineImage = forwardRef<PipelineImageRef, PipelineImageProps>(
     );
     // 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: ResizeOptions | undefined = size
+      ? { ...size, fit: effectiveFit, allowUpscale }
+      : undefined;
     // Same precedence: an explicit prop wins over what style implies.
     const effectiveCornerRadius =
       cornerRadius ?? cornerRadiusForStyle(style) ?? 0;
@@ -176,6 +213,7 @@ export const PipelineImage = forwardRef<PipelineImageRef, PipelineImageProps>(
         {...viewProps}
         ref={ref}
         style={style}
+        resizeMode={resizeMode}
         onLayout={handleLayout}
         image={image}
       />

package/src/index.ts

@@ -23,6 +23,7 @@ export type {
   CacheOption,
   CornerRadii,
   Options,
+  ResizeFit,
   ResizeOptions,
   ViewOptions,
 } from './specs/nitro-image-toolkit.nitro';

package/src/resizeForStyle.ts

@@ -13,7 +13,9 @@ import type {
 /**
  * Converts a layout size in points (dp) to the pipeline's `resize` option in
  * whole bitmap pixels using `PixelRatio.getPixelSizeForLayoutSize`. Returns
- * `undefined` unless both values are positive numbers.
+ * `undefined` unless both values are positive numbers. Spread a `fit` into
+ * the result for the other resize modes — under `contain` and `center` the
+ * size is the box the bitmap fits in, not necessarily its final size.
  */
 export function resizeForLayout(
   width: unknown,

package/src/specs/nitro-image-toolkit.nitro.ts

@@ -15,13 +15,46 @@ export interface CornerRadii {
 }
 
 /**
- * Target bitmap size in pixels. The image is scaled to fill this size and
- * center-cropped (like CSS `object-fit: cover`), upscaling if needed, so the
- * result is exactly `width` × `height` pixels.
+ * How the source is fitted into the {@linkcode ResizeOptions} box. Mirrors
+ * `NativeNitroImage`'s `resizeMode`, so a view's `resizeMode` and the bitmap
+ * it displays can be derived from one value. With a `w` × `h` source and a
+ * `W` × `H` box, the produced bitmap is:
+ *
+ * - `cover`: scale by `max(W/w, H/h)`, center-crop → exactly `W` × `H`
+ *   (CSS `object-fit: cover`).
+ * - `contain`: scale by `min(W/w, H/h)` → `round(w·s)` × `round(h·s)`, the
+ *   largest size with the source's aspect ratio that fits the box. The
+ *   bitmap is *not* padded to the box.
+ * - `stretch`: scale each axis independently → exactly `W` × `H`, aspect
+ *   ratio ignored.
+ * - `center`: no scaling; center-crop to `min(w, W)` × `min(h, H)`. A source
+ *   smaller than the box is left untouched.
+ */
+export type ResizeFit = 'cover' | 'contain' | 'stretch' | 'center';
+
+/**
+ * Target bitmap size in pixels. By default the image is scaled to fill this
+ * size and center-cropped (like CSS `object-fit: cover`), upscaling if
+ * needed, so the result is exactly `width` × `height` pixels; {@linkcode fit}
+ * selects the other resize modes.
  */
 export interface ResizeOptions {
   width: number;
   height: number;
+  /**
+   * How the source is fitted into `width` × `height` — see
+   * {@linkcode ResizeFit} for the size each mode produces.
+   * @default 'cover'
+   */
+  fit?: ResizeFit;
+  /**
+   * `false` never enlarges the source: the scale is clamped to at most 1 for
+   * `cover`, `contain` and `stretch`, so a source smaller than the box keeps
+   * its own size (and, under `cover`, is only cropped to the box). No effect
+   * on `center`, which never scales.
+   * @default true
+   */
+  allowUpscale?: boolean;
 }
 
 export type Options = {
@@ -55,10 +88,11 @@ export type Options = {
    */
   cornerRadius?: number | CornerRadii;
   /**
-   * Resize the image to exactly this size in pixels (aspect-fill,
-   * center-crop) before `blur` and `cornerRadius` are applied. Besides making
-   * `cornerRadius` predictable, this avoids decoding and processing
-   * full-resolution bitmaps you only display small.
+   * Resize the image into this box in pixels — aspect-fill + center-crop by
+   * default, or another {@linkcode ResizeFit} — before `blur` and
+   * `cornerRadius` are applied. Besides making `cornerRadius` predictable,
+   * this avoids decoding and processing full-resolution bitmaps you only
+   * display small.
    *
    * @default undefined (keep the source size)
    */
@@ -90,10 +124,52 @@ export type ViewOptions = {
   /**
    * Target bitmap size in **pixels**, overriding the size measured from the
    * view. Rarely needed — without it the loader resizes to the view's
-   * laid-out size × screen scale, which is what you want in a UI.
+   * laid-out size × screen scale, which is what you want in a UI. Its own
+   * `fit`/`allowUpscale`, when set, win over the top-level ones below.
    * @default undefined (measure the view)
    */
   resize?: ResizeOptions;
+  /**
+   * How the source is fitted into the box the loader resizes to (the view's
+   * size, or {@linkcode resize}) — see {@linkcode ResizeFit}. Pass the view's
+   * `resizeMode` so the bitmap matches how the view displays it.
+   * @default 'cover'
+   */
+  fit?: ResizeFit;
+  /**
+   * `false` never enlarges the source — see
+   * {@linkcode ResizeOptions.allowUpscale}.
+   * @default true
+   */
+  allowUpscale?: boolean;
+  /**
+   * Called when a view finishes displaying the image, with the size of the
+   * bitmap it displays in **pixels**.
+   *
+   * The bitmap itself deliberately stays native — passing the `Image` into JS
+   * would keep it alive there and defeat the point of the native path. Use
+   * `useImage`/`loadImage` when you need the `Image` object.
+   *
+   * This reports "the view is now showing this image", not a one-shot event:
+   * a loader is per URL + options, not per view, so every view using it
+   * reports, a recycled cell reports again when it re-attaches, and a single
+   * view can report more than once (it requests the image both when its
+   * `image` prop is set and when it becomes visible). Memory-cache hits, which
+   * resolve synchronously, report too. It does not fire for imperative loads
+   * through `ImageLoader.loadImage()` — those resolve through their promise.
+   *
+   * Setting it means there *is* per-image JS work; leave it unset and the
+   * native path stays free of JS round trips entirely.
+   * @default undefined (nothing crosses into JS)
+   */
+  onLoad?: (width: number, height: number) => void;
+  /**
+   * Called when a view fails to load the image, with the underlying error's
+   * message. Cancelling a load (the view detaching before it finishes) is not
+   * a failure and does not call this.
+   * @default undefined (failures are silent)
+   */
+  onError?: (message: string) => void;
 };
 
 export interface NitroImagePipeline extends HybridObject<{

package/src/useImage.ts

@@ -62,8 +62,9 @@ export function useImage({
    */
   cornerRadius?: number | CornerRadii;
   /**
-   * Resize the bitmap to exactly this size in pixels (aspect-fill,
-   * center-crop) before blur/rounding. Typically your display size in points
+   * Resize the bitmap into this box in pixels before blur/rounding —
+   * aspect-fill + center-crop by default, or another `fit` (see
+   * {@linkcode ResizeOptions}). Typically your display size in points
    * multiplied by `PixelRatio.get()`. Inline object literals are fine.
    */
   resize?: ResizeOptions;
@@ -95,6 +96,8 @@ export function useImage({
   } = isUniformRadius ? {} : cornerRadius;
   const resizeWidth = resize?.width ?? 0;
   const resizeHeight = resize?.height ?? 0;
+  const resizeFit = resize?.fit;
+  const resizeAllowUpscale = resize?.allowUpscale;
 
   useEffect(() => {
     let cancelled = false;
@@ -120,7 +123,12 @@ export function useImage({
                 : { topLeft, topRight, bottomLeft, bottomRight },
               resize:
                 resizeWidth > 0 && resizeHeight > 0
-                  ? { width: resizeWidth, height: resizeHeight }
+                  ? {
+                      width: resizeWidth,
+                      height: resizeHeight,
+                      fit: resizeFit,
+                      allowUpscale: resizeAllowUpscale,
+                    }
                   : undefined,
               cache,
             },
@@ -152,6 +160,8 @@ export function useImage({
     bottomRight,
     resizeWidth,
     resizeHeight,
+    resizeFit,
+    resizeAllowUpscale,
     cache,
     enabled,
   ]);

package/src/usePipelineImageLoader.ts

@@ -1,4 +1,4 @@
-import { useMemo } from 'react';
+import { type RefObject, useLayoutEffect, useMemo, useRef } from 'react';
 import type { ImageLoader } from 'react-native-nitro-image';
 
 import { NitroImagePipeline } from './NitroImagePipeline';
@@ -11,6 +11,38 @@ import type {
   ViewOptions,
 } from './specs/nitro-image-toolkit.nitro';
 
+// Identifies a loader in the callbacks below without them capturing it. A
+// callback the native loader owns that captured the loader back would be a
+// cycle across the language boundary — neither side collectable, and the JS
+// runtime left to take it apart at teardown.
+let nextLoaderToken = 0;
+
+type Callbacks = Pick<ViewOptions, 'onLoad' | 'onError'>;
+
+/**
+ * The callbacks handed to a native loader. Built out here, where the scope
+ * holds nothing but the token and the two refs, so the loader can't end up
+ * captured by a callback it owns.
+ */
+function makeReporters(
+  token: number,
+  activeToken: RefObject<number>,
+  callbacks: RefObject<Callbacks>,
+): Required<Callbacks> {
+  return {
+    onLoad: (width, height) => {
+      if (activeToken.current === token) {
+        callbacks.current.onLoad?.(width, height);
+      }
+    },
+    onError: (message) => {
+      if (activeToken.current === token) {
+        callbacks.current.onError?.(message);
+      }
+    },
+  };
+}
+
 /**
  * Creates (and memoizes) an {@linkcode ImageLoader} for `source` — a URL
  * string or a `require()`d asset, see {@linkcode ImageSource} — to pass to
@@ -21,7 +53,9 @@ import type {
  *
  * `blur`/`cornerRadius` are in **points** (unlike `useImage`, where they are
  * bitmap pixels); the screen scale is applied natively. Inline object
- * literals are fine — options are compared by value, not identity.
+ * literals are fine — options are compared by value, not identity, and the
+ * `onLoad`/`onError` callbacks are read through a ref, so inline arrows don't
+ * recreate the loader either.
  */
 export function usePipelineImageLoader(
   source: ImageSource,
@@ -44,8 +78,37 @@ export function usePipelineImageLoader(
   } = isUniformRadius || cornerRadius === undefined ? {} : cornerRadius;
   const resizeWidth = options?.resize?.width;
   const resizeHeight = options?.resize?.height;
+  const resizeFit = options?.resize?.fit;
+  const resizeAllowUpscale = options?.resize?.allowUpscale;
+  const fit = options?.fit;
+  const allowUpscale = options?.allowUpscale;
+  const onLoad = options?.onLoad;
+  const onError = options?.onError;
+  // Only *whether* a callback is set can change the loader: what the native
+  // side gets is a wrapper that reads the latest callbacks from a ref (like
+  // PipelineImage does). So an inline arrow — a new identity every render —
+  // doesn't recreate the loader and re-trigger the native load.
+  const hasOnLoad = onLoad !== undefined;
+  const hasOnError = onError !== undefined;
+  const callbacks = useRef({ onLoad, onError });
+  // A layout effect, not a passive one: passive effects are flushed in a later
+  // task, so a load reported between the commit and that flush would read the
+  // previous render's callbacks — a callback added alongside a new loader
+  // could miss its only event. This runs in the same task as the commit, and
+  // the view can't reach the loader before the commit installs it, so the ref
+  // is always current by the time native calls back. (Assigning it during
+  // render instead would mutate on renders React throws away.)
+  useLayoutEffect(() => {
+    callbacks.current = { onLoad, onError };
+  });
+  // The token of the loader the view is currently on. Swapping loaders (a
+  // changed url or options) never drops the old one — the view just stops
+  // referring to it — so a load it already had in flight can still report.
+  // Without this check the wrappers, which read the latest callbacks, would
+  // hand the previous image's size to the current `onLoad`.
+  const activeToken = useRef(-1);
 
-  return useMemo(() => {
+  const memoized = useMemo(() => {
     // Runs during render, so an unregistered `require()` id must not throw:
     // it becomes a URL the native loader fails on at load time instead.
     const url = resolveImageUrlOrFallback(source);
@@ -54,25 +117,52 @@ export function usePipelineImageLoader(
       : hasCornerObject
         ? { topLeft, topRight, bottomLeft, bottomRight }
         : undefined;
+    // What is loaded — the callbacks are deliberately not part of it, so two
+    // loaders that differ only in them are the same image.
     const stableOptions: ViewOptions = {
       blur,
       cache,
       cornerRadius: cornerRadiusOption,
       resize:
         resizeWidth !== undefined && resizeHeight !== undefined
-          ? { width: resizeWidth, height: resizeHeight }
+          ? {
+              width: resizeWidth,
+              height: resizeHeight,
+              fit: resizeFit,
+              allowUpscale: resizeAllowUpscale,
+            }
           : undefined,
+      fit,
+      allowUpscale,
     };
-    const loader = NitroImagePipeline.createImageLoader(url, stableOptions);
+    const token = nextLoaderToken++;
+    // The reporters read the refs, but only when the native side calls them —
+    // the rule can't see that they aren't called here.
+    // oxlint-disable-next-line react/refs
+    const reporters = makeReporters(token, activeToken, callbacks);
+    const loader = NitroImagePipeline.createImageLoader(url, {
+      ...stableOptions,
+      // Passed only when the caller wants them: without a callback nothing
+      // ever crosses into JS, which is the point of the native path.
+      onLoad: hasOnLoad ? reporters.onLoad : undefined,
+      onError: hasOnError ? reporters.onError : undefined,
+    });
     // `NativeNitroImage` needs a way to tell two loader instances apart when
     // diffing its `image` prop; tag the loader with what it will load (the
-    // same convention react-native-nitro-image's own loaders use).
+    // same convention react-native-nitro-image's own loaders use). Toggling a
+    // callback on or off makes a different loader, so the tag has to say so —
+    // otherwise the view keeps the old one installed. Their identities stay
+    // out of it: those don't change what is loaded, or which loader this is.
     Object.defineProperty(loader, '__source', {
       enumerable: true,
       configurable: true,
-      value: { url, options: stableOptions },
+      value: {
+        url,
+        options: stableOptions,
+        callbacks: { onLoad: hasOnLoad, onError: hasOnError },
+      },
     });
-    return loader;
+    return { loader, token };
   }, [
     source,
     blur,
@@ -86,5 +176,22 @@ export function usePipelineImageLoader(
     bottomRight,
     resizeWidth,
     resizeHeight,
+    resizeFit,
+    resizeAllowUpscale,
+    fit,
+    allowUpscale,
+    hasOnLoad,
+    hasOnError,
+    // Stable ref objects; listed to satisfy the exhaustive-deps rules.
+    activeToken,
+    callbacks,
   ]);
+
+  // Same reasoning as the callbacks ref: a layout effect is current before the
+  // view — which the commit has only just handed this loader — can report.
+  useLayoutEffect(() => {
+    activeToken.current = memoized.token;
+  }, [memoized, activeToken]);
+
+  return memoized.loader;
 }