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

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

@@ -0,0 +1,84 @@
+///
+/// ResizeFit.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+namespace margelo::nitro::nitroimagepipeline {
+
+  /**
+   * An enum which can be represented as a JavaScript union (ResizeFit).
+   */
+  enum class ResizeFit {
+    COVER      SWIFT_NAME(cover) = 0,
+    CONTAIN      SWIFT_NAME(contain) = 1,
+    STRETCH      SWIFT_NAME(stretch) = 2,
+    CENTER      SWIFT_NAME(center) = 3,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::nitroimagepipeline
+
+namespace margelo::nitro {
+
+  // C++ ResizeFit <> JS ResizeFit (union)
+  template <>
+  struct JSIConverter<margelo::nitro::nitroimagepipeline::ResizeFit> final {
+    static inline margelo::nitro::nitroimagepipeline::ResizeFit fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("cover"): return margelo::nitro::nitroimagepipeline::ResizeFit::COVER;
+        case hashString("contain"): return margelo::nitro::nitroimagepipeline::ResizeFit::CONTAIN;
+        case hashString("stretch"): return margelo::nitro::nitroimagepipeline::ResizeFit::STRETCH;
+        case hashString("center"): return margelo::nitro::nitroimagepipeline::ResizeFit::CENTER;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum ResizeFit - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::nitroimagepipeline::ResizeFit arg) {
+      switch (arg) {
+        case margelo::nitro::nitroimagepipeline::ResizeFit::COVER: return JSIConverter<std::string>::toJSI(runtime, "cover");
+        case margelo::nitro::nitroimagepipeline::ResizeFit::CONTAIN: return JSIConverter<std::string>::toJSI(runtime, "contain");
+        case margelo::nitro::nitroimagepipeline::ResizeFit::STRETCH: return JSIConverter<std::string>::toJSI(runtime, "stretch");
+        case margelo::nitro::nitroimagepipeline::ResizeFit::CENTER: return JSIConverter<std::string>::toJSI(runtime, "center");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert ResizeFit to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("cover"):
+        case hashString("contain"):
+        case hashString("stretch"):
+        case hashString("center"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

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

@@ -28,9 +28,11 @@
 #error NitroModules cannot be found! Are you sure you installed NitroModules properly?
 #endif
 
+// Forward declaration of `ResizeFit` to properly resolve imports.
+namespace margelo::nitro::nitroimagepipeline { enum class ResizeFit; }
 
-
-
+#include "ResizeFit.hpp"
+#include <optional>
 
 namespace margelo::nitro::nitroimagepipeline {
 
@@ -41,10 +43,12 @@ namespace margelo::nitro::nitroimagepipeline {
   public:
     double width     SWIFT_PRIVATE;
     double height     SWIFT_PRIVATE;
+    std::optional<ResizeFit> fit     SWIFT_PRIVATE;
+    std::optional<bool> allowUpscale     SWIFT_PRIVATE;
 
   public:
     ResizeOptions() = default;
-    explicit ResizeOptions(double width, double height): width(width), height(height) {}
+    explicit ResizeOptions(double width, double height, std::optional<ResizeFit> fit, std::optional<bool> allowUpscale): width(width), height(height), fit(fit), allowUpscale(allowUpscale) {}
 
   public:
     friend bool operator==(const ResizeOptions& lhs, const ResizeOptions& rhs) = default;
@@ -61,13 +65,17 @@ namespace margelo::nitro {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::nitroimagepipeline::ResizeOptions(
         JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "width"))),
-        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "height")))
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "height"))),
+        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")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitroimagepipeline::ResizeOptions& arg) {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "width"), JSIConverter<double>::toJSI(runtime, arg.width));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "height"), JSIConverter<double>::toJSI(runtime, arg.height));
+      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));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -80,6 +88,8 @@ namespace margelo::nitro {
       }
       if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "width")))) return false;
       if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "height")))) 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;
       return true;
     }
   };

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.5.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

@@ -3,9 +3,11 @@ import type { HostComponent } from 'react-native';
 import { NativeNitroImage } from 'react-native-nitro-image';
 
 import { cornerRadiusForStyle } from './resizeForStyle';
+import { type ImageSource, recyclingKeyFor } from './resolveImageSource';
 import type {
   CacheOption,
   CornerRadii,
+  ResizeFit,
   ResizeOptions,
 } from './specs/nitro-image-toolkit.nitro';
 import { usePipelineImageLoader } from './usePipelineImageLoader';
@@ -24,8 +26,12 @@ export interface NativePipelineImageProps extends Omit<
   NativeImageProps,
   'image'
 > {
-  /** URL of the image to load through the pipeline. */
-  url: string;
+  /**
+   * The image to load through the pipeline: a URL string (`https://`,
+   * `file://`, an absolute path) or a `require()`d asset — see
+   * {@linkcode ImageSource}.
+   */
+  url: ImageSource;
   /**
    * Gaussian blur sigma in **points** (density-independent), like
    * `PipelineImage`. Applied natively with the screen scale.
@@ -46,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;
 }
 
 /**
@@ -57,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
@@ -74,25 +121,47 @@ 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 (
     <NativeNitroImage
       // Before the spread so a caller-provided recyclingKey wins.
-      recyclingKey={url}
+      recyclingKey={recyclingKeyFor(url)}
       {...viewProps}
       ref={ref}
       style={style}
+      resizeMode={resizeMode}
       image={loader}
     />
   );

package/src/PipelineImage.tsx

@@ -17,9 +17,11 @@ import {
   resizeForLayout,
   resizeForStyle,
 } from './resizeForStyle';
+import type { ImageSource } from './resolveImageSource';
 import type {
   CacheOption,
   CornerRadii,
+  ResizeFit,
   ResizeOptions,
 } from './specs/nitro-image-toolkit.nitro';
 import { useImage } from './useImage';
@@ -35,8 +37,12 @@ type NativeImageProps = ReactProps<typeof NativeNitroImage>;
 export type PipelineImageRef = ComponentRef<typeof NativeNitroImage>;
 
 export interface PipelineImageProps extends Omit<NativeImageProps, 'image'> {
-  /** URL of the image to load through the pipeline. */
-  url: string;
+  /**
+   * The image to load through the pipeline: a URL string (`https://`,
+   * `file://`, an absolute path) or a `require()`d asset — see
+   * {@linkcode ImageSource}.
+   */
+  url: ImageSource;
   /**
    * Gaussian blur sigma in **points** (density-independent). Unlike
    * `useImage`/`loadImage`, where it is bitmap pixels, the component
@@ -57,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. */
@@ -114,10 +147,13 @@ export const PipelineImage = forwardRef<PipelineImageRef, PipelineImageProps>(
       blur = 0,
       cornerRadius,
       cache,
+      fit,
+      allowUpscale,
       onLoad,
       onError,
       style,
       onLayout,
+      resizeMode,
       ...viewProps
     },
     ref,
@@ -129,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;
@@ -171,6 +213,7 @@ export const PipelineImage = forwardRef<PipelineImageRef, PipelineImageProps>(
         {...viewProps}
         ref={ref}
         style={style}
+        resizeMode={resizeMode}
         onLayout={handleLayout}
         image={image}
       />

package/src/index.ts

@@ -9,6 +9,11 @@ export {
   type PipelineImageProps,
   type PipelineImageRef,
 } from './PipelineImage';
+export {
+  type ImageSource,
+  resolveImageUrl,
+  UNREGISTERED_ASSET_URL,
+} from './resolveImageSource';
 export {
   cornerRadiusForStyle,
   resizeForLayout,
@@ -18,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/resolveImageSource.ts

@@ -0,0 +1,83 @@
+import { Image as RNImage } from 'react-native';
+
+/**
+ * What the pipeline can load: a URL string, or the id a `require()`d image
+ * asset evaluates to.
+ *
+ * As a string, `url` is passed to the native loader as-is. Accepted forms:
+ *
+ * - `https://` / `http://` — fetched over the network and cached on disk.
+ * - `file://` URLs and plain absolute paths (`/var/…/photo.jpg`) — read from
+ *   the file system. The result is cached in memory only; there is nothing
+ *   to gain from copying a local file into the disk cache.
+ * - Android also accepts `content://` URIs and, from a release build's
+ *   resources, a bare drawable name — which is what `require()` resolves to
+ *   there. iOS resolves `require()` to a `file://` URL into the app bundle.
+ *
+ * A `require('./photo.png')` is resolved with `Image.resolveAssetSource`, so
+ * it works the same in debug (streamed from Metro) and release (bundled).
+ */
+export type ImageSource = string | number;
+
+/**
+ * Turns an {@linkcode ImageSource} into the URL string the native pipeline
+ * loads: strings pass through unchanged, a `require()`d asset is resolved via
+ * `Image.resolveAssetSource` (the scale-matched variant, like `<Image>`).
+ *
+ * The components and hooks call this for you; use it when calling
+ * `NitroImagePipeline.loadImage`/`preLoadImage` directly with a `require()`.
+ * @throws If `source` is a number that is not a registered asset.
+ * @example
+ * ```ts
+ * const image = await NitroImagePipeline.loadImage(
+ *   resolveImageUrl(require('./photo.png')),
+ *   { blur: 4 },
+ * );
+ * ```
+ */
+export function resolveImageUrl(source: ImageSource): string {
+  if (typeof source === 'string') {
+    return source;
+  }
+  const resolved = RNImage.resolveAssetSource(source);
+  if (resolved == null) {
+    throw new Error(`Not a registered image asset: require() id ${source}`);
+  }
+  return resolved.uri;
+}
+
+/**
+ * A URL no loader can resolve, standing in for a `require()` id that is not
+ * a registered asset. Its scheme has no fetcher on either platform, so the
+ * request fails at load time — the same way a missing file does — instead of
+ * throwing from a component's render.
+ */
+export const UNREGISTERED_ASSET_URL = 'unregistered-asset://';
+
+/**
+ * {@linkcode resolveImageUrl} for code that runs during render: an
+ * unregistered `require()` id yields {@linkcode UNREGISTERED_ASSET_URL} (and
+ * a warning in development) rather than throwing.
+ */
+export function resolveImageUrlOrFallback(source: ImageSource): string {
+  try {
+    return resolveImageUrl(source);
+  } catch (error) {
+    if (__DEV__) {
+      console.warn(
+        `[react-native-nitro-image-pipeline] ${(error as Error).message}`,
+      );
+    }
+    return UNREGISTERED_ASSET_URL;
+  }
+}
+
+/**
+ * A stable, per-source `recyclingKey` for `<NativeNitroImage>`: the URL
+ * itself for strings, and a tag derived from the asset id for a `require()`
+ * (resolving it would cost an asset-registry lookup per render for nothing
+ * more than a distinct key).
+ */
+export function recyclingKeyFor(source: ImageSource): string {
+  return typeof source === 'string' ? source : `asset:${source}`;
+}