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

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

@@ -0,0 +1,177 @@
+package com.margelo.nitro.nitroimagepipeline
+
+import android.content.Context
+import android.util.Log
+import android.view.View
+import android.widget.ImageView
+import androidx.annotation.Keep
+import coil3.request.ErrorResult
+import coil3.request.SuccessResult
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.core.Promise
+import com.margelo.nitro.image.HybridImage
+import com.margelo.nitro.image.HybridImageLoaderSpec
+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.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.suspendCancellableCoroutine
+
+/**
+ * An `ImageLoader` (react-native-nitro-image) backed by the shared pipeline.
+ *
+ * `<NativeNitroImage image={loader} />` drives it entirely natively: the view calls [requestImage]
+ * when it attaches to the window and [dropImage] when it detaches. The load runs at the view's
+ * laid-out size with no JS round trips, and detaching cancels the request and releases the bitmap —
+ * the decoded image stays in the shared memory/disk caches, so re-attaching (list recycling) is
+ * instant.
+ *
+ * [ViewOptions] values are in points (dp); this class converts them to the pixel-based [Options] of
+ * 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.
+ */
+@DoNotStrip
+@Keep
+class PipelineImageLoader(
+    private val context: Context,
+    private val url: String,
+    private val options: ViewOptions?,
+) : HybridImageLoaderSpec() {
+  // Per-view in-flight work, keyed by the view's identity, so a loader shared
+  // between several views cancels only the right request. Confined to the
+  // main thread — the view calls requestImage/dropImage there.
+  private val jobs = HashMap<HybridNitroImageViewSpec, Job>()
+  private val mainScope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
+
+  /** An explicit `resize` override (pixels), when set and valid. */
+  private val explicitResize: ResizeOptions?
+    get() = options?.resize?.takeIf { it.width > 0 && it.height > 0 }
+
+  /**
+   * The point-based [ViewOptions] as pixel-based [Options], resolved against the display [scale]
+   * and the target size in pixels.
+   */
+  private fun pixelOptions(scale: Float, resize: ResizeOptions?): Options {
+    val cornerRadius =
+        options
+            ?.cornerRadius
+            ?.match(
+                first = { radius -> Variant_Double_CornerRadii.create(radius * scale) },
+                second = { radii ->
+                  Variant_Double_CornerRadii.create(
+                      CornerRadii(
+                          topLeft = radii.topLeft?.times(scale),
+                          topRight = radii.topRight?.times(scale),
+                          bottomLeft = radii.bottomLeft?.times(scale),
+                          bottomRight = radii.bottomRight?.times(scale),
+                      )
+                  )
+                },
+            )
+    return Options(
+        blur = options?.blur?.times(scale),
+        cache = options?.cache,
+        cornerRadius = cornerRadius,
+        resize = resize,
+    )
+  }
+
+  override fun loadImage(): Promise<HybridImageSpec> = Promise.async {
+    // No view to measure here: use the explicit resize if given, and the
+    // display density for the point-based options.
+    val scale = context.resources.displayMetrics.density
+    val request =
+        HybridNitroImagePipeline.buildRequest(context, url, pixelOptions(scale, explicitResize))
+    when (val result = HybridNitroImagePipeline.getOrCreateImageLoader(context).execute(request)) {
+      is ErrorResult -> throw result.throwable
+      is SuccessResult -> HybridImage(HybridNitroImagePipeline.bitmapOf(result))
+    }
+  }
+
+  override fun requestImage(forView: HybridNitroImageViewSpec) {
+    val view = forView as? HybridImageView ?: return
+    val imageView = view.imageView
+    jobs[forView]?.cancel()
+    val job = mainScope.launch {
+      // Views attach before they are laid out, so the size may not be
+      // known yet — wait for the first non-empty layout.
+      val resize = explicitResize ?: measuredSize(imageView)
+      val scale = imageView.resources.displayMetrics.density
+      // The result is only ever drawn here, so a transformed one is cached as
+      // a hardware bitmap: no texture upload per view that shows it.
+      val request =
+          HybridNitroImagePipeline.buildRequest(
+              context,
+              url,
+              pixelOptions(scale, resize),
+              hardwareResult = true,
+          )
+      // Synchronous once the shared loader exists; otherwise its (slow)
+      // creation runs on a background thread instead of here on main.
+      val loader = HybridNitroImagePipeline.awaitImageLoader(context)
+      val result = loader.execute(request)
+      // Cancellation normally surfaces as a CancellationException at the
+      // suspension point above, but make it explicit: a job that was
+      // dropped or replaced while the result was in flight must never
+      // 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)
+      }
+    }
+    jobs[forView] = job
+    job.invokeOnCompletion { if (jobs[forView] === job) jobs.remove(forView) }
+  }
+
+  override fun dropImage(forView: HybridNitroImageViewSpec) {
+    val view = forView as? HybridImageView ?: return
+    jobs.remove(forView)?.cancel()
+    view.imageView.setImageDrawable(null)
+  }
+
+  /** 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 suspendCancellableCoroutine { continuation ->
+      val listener =
+          object : View.OnLayoutChangeListener {
+            override fun onLayoutChange(
+                v: View,
+                left: Int,
+                top: Int,
+                right: Int,
+                bottom: Int,
+                oldLeft: Int,
+                oldTop: Int,
+                oldRight: Int,
+                oldBottom: Int,
+            ) {
+              val width = right - left
+              val height = bottom - top
+              if (width > 0 && height > 0) {
+                v.removeOnLayoutChangeListener(this)
+                continuation.resume(ResizeOptions(width.toDouble(), height.toDouble()))
+              }
+            }
+          }
+      view.addOnLayoutChangeListener(listener)
+      continuation.invokeOnCancellation { view.removeOnLayoutChangeListener(listener) }
+    }
+  }
+
+  companion object {
+    private const val TAG = "PipelineImageLoader"
+  }
+}

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

@@ -1,36 +1,27 @@
-@file:Suppress("DEPRECATION")
-
 package com.margelo.nitro.nitroimagepipeline.transform
 
-import android.content.Context
 import android.graphics.Bitmap
-import android.graphics.Paint
-import android.renderscript.Allocation
-import android.renderscript.Element
-import android.renderscript.RenderScript
-import android.renderscript.ScriptIntrinsicBlur
-import androidx.core.graphics.applyCanvas
-import androidx.core.graphics.scale
+import android.graphics.Canvas
 import coil3.size.Size
 import coil3.transform.Transformation
-import kotlin.math.ceil
-import kotlin.math.max
 
 /**
  * Gaussian blur of standard deviation [sigma], measured in *source image pixels*.
  *
  * The unit is the point of this class: the same sigma on the same source file produces the same
- * result here and on iOS. It is deliberately not a "radius" — RenderScript, CoreImage and React
+ * result here and on iOS. It is deliberately not a "radius" — CoreImage, RenderScript and React
  * Native's `blurRadius` each define radius differently, which is why blurs never matched across
  * platforms.
  *
+ * The kernel is `android/src/main/cpp/GaussianBlur.cpp`, a port of the iOS one: three box-blur
+ * passes whose widths are solved for the requested sigma, clamping at the image edges. There is no
+ * upper bound on sigma and no downscaling — `bun run verify:blur` measures both kernels against
+ * each other.
+ *
  * For reference, React Native's `<Image blurRadius={n} />` halves its input before convolving, so
  * `blurRadius={n}` is roughly `sigma = n / 2`.
  */
-class BlurTransformation(
-    private val context: Context,
-    private val sigma: Float,
-) : Transformation() {
+class BlurTransformation(private val sigma: Float) : Transformation() {
 
   init {
     require(sigma > 0f && sigma.isFinite()) { "sigma must be > 0." }
@@ -39,79 +30,43 @@ class BlurTransformation(
   override val cacheKey = "${BlurTransformation::class.java.name}-$sigma"
 
   override suspend fun transform(input: Bitmap, size: Size): Bitmap {
-    // ScriptIntrinsicBlur's `radius` maps to a Gaussian sigma of 0.4 * radius + 0.6, and radius is
-    // capped at 25 — so a single pass tops out at sigma ~10.6px. Larger blurs are reached by
-    // blurring a downscaled copy: scaling down by `s`, blurring with sigma/s and scaling back up
-    // multiplies the effective sigma by `s`. A blur is a low-pass filter, so the detail the
-    // downscale drops is detail the blur was going to remove anyway. Downscale only as far as the
-    // sigma ceiling forces, which keeps small blurs pixel-exact.
-    val sampling = max(1f, sigma / MAX_SIGMA)
-    val scaledWidth = ceil(input.width / sampling).toInt().coerceAtLeast(1)
-    val scaledHeight = ceil(input.height / sampling).toInt().coerceAtLeast(1)
-    // Rounding to whole pixels shifts the scale slightly; derive the sigma from the scale actually
-    // applied rather than the requested one.
-    val scaleX = scaledWidth.toFloat() / input.width
-    val scaleY = scaledHeight.toFloat() / input.height
-    val scaledSigma = sigma * max(scaleX, scaleY)
-    val radius = ((scaledSigma - SIGMA_INTERCEPT) / SIGMA_SLOPE).coerceIn(MIN_RADIUS, MAX_RADIUS)
-
-    val paint = Paint(Paint.ANTI_ALIAS_FLAG or Paint.FILTER_BITMAP_FLAG)
-    val softwareInput =
-        if (input.config == Bitmap.Config.HARDWARE) input.copy(Bitmap.Config.ARGB_8888, false)
-        else input
-    val softwareConfig = softwareInput.config ?: Bitmap.Config.ARGB_8888
-
-    val output = Bitmap.createBitmap(scaledWidth, scaledHeight, softwareConfig)
-    output.applyCanvas {
-      scale(scaleX, scaleY)
-      drawBitmap(softwareInput, 0f, 0f, paint)
-    }
-
-    var script: RenderScript? = null
-    var tmpIn: Allocation? = null
-    var tmpOut: Allocation? = null
-    var blur: ScriptIntrinsicBlur? = null
-    try {
-      script = RenderScript.create(context)
-      tmpIn =
-          Allocation.createFromBitmap(
-              script,
-              output,
-              Allocation.MipmapControl.MIPMAP_NONE,
-              Allocation.USAGE_SCRIPT,
-          )
-      tmpOut = Allocation.createTyped(script, tmpIn.type)
-      blur = ScriptIntrinsicBlur.create(script, Element.U8_4(script))
-      blur.setRadius(radius)
-      blur.setInput(tmpIn)
-      blur.forEach(tmpOut)
-      tmpOut.copyTo(output)
-    } finally {
-      script?.destroy()
-      tmpIn?.destroy()
-      tmpOut?.destroy()
-      blur?.destroy()
-    }
-
-    return if (scaledWidth == input.width && scaledHeight == input.height) output
-    else output.scale(input.width, input.height)
+    // The kernel blurs in place, on premultiplied ARGB_8888 pixels. A plain
+    // copy is the cheapest way to get a mutable bitmap of that layout — also
+    // from a hardware bitmap, which a software canvas could not draw. Only a
+    // non-premultiplied input goes through a canvas, which converts it.
+    val output =
+        if (
+            input.config == Bitmap.Config.HARDWARE ||
+                (input.config == Bitmap.Config.ARGB_8888 &&
+                    (input.isPremultiplied || !input.hasAlpha()))
+        ) {
+          input.copy(Bitmap.Config.ARGB_8888, true) ?: error("Bitmap.copy returned null")
+        } else {
+          Bitmap.createBitmap(input.width, input.height, Bitmap.Config.ARGB_8888).also {
+            Canvas(it).drawBitmap(input, 0f, 0f, null)
+          }
+        }
+    check(nativeBlur(output, sigma)) { "Native blur failed (see logcat)." }
+    return output
   }
 
   override fun equals(other: Any?): Boolean {
     if (this === other) return true
-    return other is BlurTransformation && context == other.context && sigma == other.sigma
+    return other is BlurTransformation && sigma == other.sigma
   }
 
-  override fun hashCode(): Int = 31 * context.hashCode() + sigma.hashCode()
+  override fun hashCode(): Int = sigma.hashCode()
 
   override fun toString() = "BlurTransformation(sigma=$sigma)"
 
   private companion object {
-    // sigma = 0.4 * radius + 0.6, per RenderScript's ScriptIntrinsicBlur.
-    const val SIGMA_SLOPE = 0.4f
-    const val SIGMA_INTERCEPT = 0.6f
-    const val MIN_RADIUS = 0.01f
-    const val MAX_RADIUS = 25f
-    const val MAX_SIGMA = SIGMA_SLOPE * MAX_RADIUS + SIGMA_INTERCEPT
+    init {
+      // Nitro loads the library at module registration, but the transformation
+      // must not depend on that order; loadLibrary is idempotent.
+      System.loadLibrary("NitroImagePipeline")
+    }
+
+    /** Blurs [bitmap] (mutable ARGB_8888) in place. Returns false on failure. */
+    @JvmStatic private external fun nativeBlur(bitmap: Bitmap, sigma: Float): Boolean
   }
 }

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

@@ -0,0 +1,45 @@
+package com.margelo.nitro.nitroimagepipeline.transform
+
+import android.graphics.Bitmap
+import android.os.Build
+import coil3.size.Size
+import coil3.transform.Transformation
+
+/**
+ * Uploads the transformed bitmap to a [Bitmap.Config.HARDWARE] bitmap (API 26+), so that is what
+ * the memory cache holds and the view draws.
+ *
+ * Coil decodes straight to a hardware bitmap when a request has no transformations, but with any
+ * (resize, blur, rounded corners) the decode and the transformations run on software bitmaps and
+ * the software result is what gets cached. Every view showing it then costs a texture upload (and,
+ * with the pixels kept for the bitmap, a copy in RAM). Appending this transformation converts the
+ * result once, on the transformation thread, and it stays converted in the cache.
+ *
+ * A hardware bitmap's pixels are not readable, so this must only be added by callers that draw the
+ * result — `PipelineImageLoader.requestImage` — never by `loadImage`, whose `HybridImage` needs
+ * readable pixels for `toArrayBuffer`/`toBase64`. The extra cache key keeps the two paths' cache
+ * entries apart.
+ *
+ * Below API 26, or if the upload fails, the software bitmap is passed through unchanged.
+ */
+class HardwareBitmapTransformation private constructor() : Transformation() {
+
+  override val cacheKey = HardwareBitmapTransformation::class.java.name
+
+  override suspend fun transform(input: Bitmap, size: Size): Bitmap {
+    if (!isSupported || input.config == Bitmap.Config.HARDWARE) return input
+    // Performance-only: a failed upload (null, or an allocation/driver
+    // exception) must not fail the request, so fall back to the software
+    // bitmap either way.
+    return runCatching { input.copy(Bitmap.Config.HARDWARE, false) }.getOrNull() ?: input
+  }
+
+  override fun toString() = "HardwareBitmapTransformation"
+
+  companion object {
+    val isSupported: Boolean
+      get() = Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
+
+    val instance = HardwareBitmapTransformation()
+  }
+}

package/ios/GaussianBlur.swift

@@ -29,25 +29,30 @@ enum GaussianBlur {
         // Normalise to premultiplied ARGB8888 — vImageBoxConvolve_ARGB8888
         // needs four 8-bit channels, and premultiplied alpha is what keeps
         // transparent edges from bleeding dark halos into the blur.
+        let colorSpace = CGColorSpaceCreateDeviceRGB()
+        let bitmapInfo = CGBitmapInfo(rawValue: CGImageAlphaInfo.premultipliedFirst.rawValue)
         guard var format = vImage_CGImageFormat(
             bitsPerComponent: 8,
             bitsPerPixel: 32,
-            colorSpace: CGColorSpaceCreateDeviceRGB(),
-            bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.premultipliedFirst.rawValue),
+            colorSpace: colorSpace,
+            bitmapInfo: bitmapInfo,
             renderingIntent: .defaultIntent
         ) else { return nil }
 
+        // Both buffers are freed on exit, except the one handed over to the
+        // result CGImage below (`handedOver`), which is freed with the image.
+        var handedOver: UnsafeMutableRawPointer?
         var source = vImage_Buffer()
         guard vImageBuffer_InitWithCGImage(
             &source, &format, nil, cgImage, vImage_Flags(kvImageNoFlags)
         ) == kvImageNoError else { return nil }
-        defer { free(source.data) }
+        defer { if source.data != handedOver { free(source.data) } }
 
         var scratch = vImage_Buffer()
         guard vImageBuffer_Init(
             &scratch, source.height, source.width, 32, vImage_Flags(kvImageNoFlags)
         ) == kvImageNoError else { return nil }
-        defer { free(scratch.data) }
+        defer { if scratch.data != handedOver { free(scratch.data) } }
 
         // kvImageEdgeExtend clamps at the borders instead of sampling
         // transparent black, so the image keeps its edges instead of fading
@@ -75,12 +80,46 @@ enum GaussianBlur {
             swap(&input, &output)
         }
 
-        var error = vImage_Error(kvImageNoError)
-        guard let blurred = vImageCreateCGImageFromBuffer(
-            &input, &format, nil, nil, vImage_Flags(kvImageNoFlags), &error
-        )?.takeRetainedValue(), error == kvImageNoError else { return nil }
+        // Ownership of the result buffer moves to the CGImage (no copy);
+        // `handedOver` keeps the exits above from freeing it a second time.
+        return makeImage(from: input, colorSpace: colorSpace, bitmapInfo: bitmapInfo, handedOver: &handedOver)
+    }
+
+    /// Wraps `buffer` in a CGImage instead of copying it (one full-bitmap
+    /// memcpy less per blur). Ownership is explicit: once the data provider
+    /// exists, it frees the buffer — together with the image, or right away
+    /// if creating the image fails and the provider is released — so
+    /// `handedOver` is set to the buffer's data as soon as that is the case.
+    /// (vImageCreateCGImageFromBuffer with kvImageNoAllocate would do the
+    /// same, but leaves unspecified whether its free callback runs when the
+    /// call fails.)
+    private static func makeImage(
+        from buffer: vImage_Buffer,
+        colorSpace: CGColorSpace,
+        bitmapInfo: CGBitmapInfo,
+        handedOver: inout UnsafeMutableRawPointer?
+    ) -> CGImage? {
+        guard let provider = CGDataProvider(
+            dataInfo: nil,
+            data: buffer.data,
+            size: buffer.rowBytes * Int(buffer.height),
+            releaseData: { _, data, _ in free(UnsafeMutableRawPointer(mutating: data)) }
+        ) else { return nil }
+        handedOver = buffer.data
 
-        return blurred
+        return CGImage(
+            width: Int(buffer.width),
+            height: Int(buffer.height),
+            bitsPerComponent: 8,
+            bitsPerPixel: 32,
+            bytesPerRow: buffer.rowBytes,
+            space: colorSpace,
+            bitmapInfo: bitmapInfo,
+            provider: provider,
+            decode: nil,
+            shouldInterpolate: true,
+            intent: .defaultIntent
+        )
     }
 
     /// Widths for the three box-blur passes that approximate a Gaussian of

package/ios/HybridNitroImagePipeline.swift

@@ -12,7 +12,7 @@ import Nuke
 
 import UIKit
 
-private class HybridImage: HybridImageSpec, NativeImage {
+class HybridImage: HybridImageSpec, NativeImage {
     let uiImage: UIImage
 
     // PNG encoding is expensive; encode once and reuse for both
@@ -21,26 +21,22 @@ private class HybridImage: HybridImageSpec, NativeImage {
     // doesn't pin its encoding forever.
     private let pngLock = NSLock()
     private var cachedPngData: Data?
+    // Registered only once there is encoded data to drop: most images are
+    // only ever displayed, and an observer per image is wasted work in a
+    // list of hundreds. Guarded by `pngLock` like the data it protects.
     private var memoryWarningObserver: (any NSObjectProtocol)?
 
     init(uiImage: UIImage) {
         self.uiImage = uiImage
         super.init()
-        memoryWarningObserver = NotificationCenter.default.addObserver(
-            forName: UIApplication.didReceiveMemoryWarningNotification,
-            object: nil,
-            queue: nil
-        ) { [weak self] _ in
-            guard let self else { return }
-            self.pngLock.lock()
-            self.cachedPngData = nil
-            self.pngLock.unlock()
-        }
     }
 
     deinit {
-        if let memoryWarningObserver {
-            NotificationCenter.default.removeObserver(memoryWarningObserver)
+        pngLock.lock()
+        let observer = memoryWarningObserver
+        pngLock.unlock()
+        if let observer {
+            NotificationCenter.default.removeObserver(observer)
         }
     }
 
@@ -52,6 +48,18 @@ private class HybridImage: HybridImageSpec, NativeImage {
         }
         let data = uiImage.pngData()
         cachedPngData = data
+        if data != nil, memoryWarningObserver == nil {
+            memoryWarningObserver = NotificationCenter.default.addObserver(
+                forName: UIApplication.didReceiveMemoryWarningNotification,
+                object: nil,
+                queue: nil
+            ) { [weak self] _ in
+                guard let self else { return }
+                self.pngLock.lock()
+                self.cachedPngData = nil
+                self.pngLock.unlock()
+            }
+        }
         return data
     }
 
@@ -89,7 +97,7 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
     // users in the host app are left untouched, and repeated instantiation
     // (e.g. Metro reloads) never puts two DataCache instances on the same
     // directory.
-    private static let sharedPipeline: ImagePipeline = {
+    static let sharedPipeline: ImagePipeline = {
         var configuration = ImagePipeline.Configuration.withDataCache
         // Store processed (blurred/rounded) variants on disk in addition to
         // the original download, so they survive memory eviction and
@@ -105,6 +113,15 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
         configuration.imageCache = ImageCache(
             costLimit: min(ImageCache.defaultCostLimit, 128 * 1024 * 1024)
         )
+        // Nuke decodes on a serial queue by default, so a screenful of new
+        // list cells is decoded one image at a time however many cores the
+        // device has. Decode in parallel instead — capped so a burst of
+        // full-resolution decodes (no `resize`) can't multiply peak memory
+        // by the core count. Processing stays at Nuke's default of 2: the
+        // blur allocates several full-size buffers per image.
+        configuration.imageDecodingQueue.maxConcurrentOperationCount = min(
+            4, max(1, ProcessInfo.processInfo.activeProcessorCount)
+        )
         return ImagePipeline(configuration: configuration)
     }()
 
@@ -181,36 +198,49 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
         return processors
     }
 
+    /// The `ImageRequest` for `url` with `options` applied — shared by
+    /// `loadImage` and `PipelineImageLoader` so both hit the same caches with
+    /// identical cache keys.
+    static func makeRequest(url: URL, options: Options?) -> ImageRequest {
+        var imgRequest = ImageRequest(
+            url: url,
+            processors: processors(for: options),
+            options: cacheOptions(for: options?.cache)
+        )
+        // With a target size known, decode near it (aspect-fill, so the
+        // decoded image always covers the target) instead of at full
+        // resolution — a 48 MP photo displayed as a 300 pt card would
+        // otherwise decompress to ~190 MB before Resize shrinks it.
+        // Matches Android, where the request's size() drives subsampling;
+        // the exact size and crop still come from the Resize processor.
+        if let size = resizeSize(for: options) {
+            imgRequest.thumbnail = ImageRequest.ThumbnailOptions(
+                size: size,
+                unit: .pixels,
+                contentMode: .aspectFill
+            )
+        }
+        return imgRequest
+    }
+
     func loadImage(url: String, options: Options?) throws -> Promise<any HybridImageSpec> {
         return Promise.async {
             guard let imageUrl = URL(string: url) else {
                 throw RuntimeError.error(withMessage: "Invalid URL: \(url)")
             }
 
-            var imgRequest = ImageRequest(
-                url: imageUrl,
-                processors: Self.processors(for: options),
-                options: Self.cacheOptions(for: options?.cache)
-            )
-            // With a target size known, decode near it (aspect-fill, so the
-            // decoded image always covers the target) instead of at full
-            // resolution — a 48 MP photo displayed as a 300 pt card would
-            // otherwise decompress to ~190 MB before Resize shrinks it.
-            // Matches Android, where the request's size() drives subsampling;
-            // the exact size and crop still come from the Resize processor.
-            if let size = Self.resizeSize(for: options) {
-                imgRequest.thumbnail = ImageRequest.ThumbnailOptions(
-                    size: size,
-                    unit: .pixels,
-                    contentMode: .aspectFill
-                )
-            }
-
+            let imgRequest = Self.makeRequest(url: imageUrl, options: options)
             let image = try await self.pipeline.image(for: imgRequest)
             return HybridImage(uiImage: image)
         }
     }
 
+    func createImageLoader(url: String, options: ViewOptions?) throws -> any HybridImageLoaderSpec {
+        // An unparseable URL fails at load time, not here — matching Android,
+        // where Coil validates the URL only when the request runs.
+        return PipelineImageLoader(url: url, options: options)
+    }
+
     func preLoadImage(url: String) throws -> Promise<Void> {
         return Promise.async {
             guard let imageUrl = URL(string: url) else {