react-native-nitro-image-pipeline 0.3.4 → 1.0.0

package/README.md

@@ -48,7 +48,7 @@ import { useImage } from 'react-native-nitro-image-pipeline';
 function MyComponent() {
   const { image, error } = useImage({
     url: 'https://example.com/photo.jpg',
-    blur: 4,
+    blur: 4, // Gaussian sigma in source pixels — same result on iOS and Android
     cornerRadius: 12,
   });
 
@@ -67,7 +67,7 @@ import { NitroImagePipeline } from 'react-native-nitro-image-pipeline';
 
 // Load an image with options
 const image = await NitroImagePipeline.loadImage('https://example.com/photo.jpg', {
-  blur: 4,
+  blur: 4, // Gaussian sigma in source pixels — see "Blur units"
   cornerRadius: 12,
   cache: 'disk',
 });
@@ -85,7 +85,7 @@ await NitroImagePipeline.preLoadImages([
 const blurred = await NitroImagePipeline.gaussianBlur(image, 10);
 
 // Clear the image cache
-NitroImagePipeline.clearCache();
+await NitroImagePipeline.clearCache();
 ```
 
 ## API Reference
@@ -96,7 +96,7 @@ Loads an image from a URL and returns a `Promise<Image>`.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `blur` | `number` | `0` | Gaussian blur radius applied at load time |
+| `blur` | `number` | `0` | Gaussian blur strength applied at load time — see [Blur units](#blur-units) |
 | `cornerRadius` | `number` | `0` | Corner radius in points |
 | `cache` | `'memory' \| 'disk' \| 'none'` | platform default | Caching strategy |
 
@@ -110,11 +110,65 @@ Prefetches multiple images into the cache. Returns `Promise<void>`.
 
 ### `gaussianBlur(image, radius)`
 
-Applies a Gaussian blur to an existing `Image` object. Returns `Promise<Image>`.
+Applies a Gaussian blur to an existing `Image` object. Returns `Promise<Image>`. `radius` uses the
+same unit as the `blur` option — see [Blur units](#blur-units).
+
+### Blur units
+
+`blur` (and `gaussianBlur`'s `radius`) is the **standard deviation (sigma) of the Gaussian, in
+source-image pixels**. The same value on the same source file produces the same result on iOS and
+Android — the platforms are calibrated against each other rather than each exposing its native
+backend's own idea of "radius".
+
+```ts
+// ~11px of blur on both platforms, whatever the device
+await NitroImagePipeline.loadImage(url, { blur: 11 });
+```
+
+Two things follow from the unit being *source* pixels:
+
+- Blur is measured against the image's own resolution, not the size it is displayed at. A 4000px
+  photo at `blur: 11` looks subtler than a 400px thumbnail at `blur: 11`. To keep a feed visually
+  consistent, scale the value with the source width.
+- Coming from React Native's `<Image blurRadius={n} />`? That halves its input internally, so
+  `blurRadius={n}` ≈ `blur: n / 2`. RN's value is also density-scaled on Android and not on iOS,
+  which is why the two never quite matched there.
+
+Values below ~1 are smaller than the smallest kernel either backend can build and are effectively a
+no-op. There is no upper bound.
+
+Implementation: iOS runs three Accelerate box-convolution passes sized to hit the requested sigma
+(the standard three-box Gaussian approximation, accurate to a few percent); Android uses
+RenderScript's true Gaussian, downscaling first when sigma exceeds the single-pass ceiling of
+~10.6px and compensating the radius so the result is unchanged. Both clamp at the edges, so blurred
+images keep their borders instead of fading out.
 
 ### `clearCache()`
 
-Removes all cached images from memory and disk.
+Removes all cached images from memory and disk. Returns `Promise<void>` that resolves once both caches are cleared.
+
+## Upgrading from 0.3.x
+
+`blur` and `gaussianBlur(image, radius)` changed meaning in 1.0. They used to hand the number
+straight to each platform's native blur, and the two platforms disagreed about what it meant; now
+both read it as a Gaussian sigma in source-image pixels (see [Blur units](#blur-units)).
+
+| | what `blur: n` did in 0.3.x | what it does in 1.0 |
+|---|---|---|
+| iOS | fed `n` to `CIGaussianBlur(inputRadius:)`, measured at `sigma ≈ 1.18 × n` | `sigma = n` |
+| Android | RenderScript on a copy downscaled to 512px, so strength scaled with the source resolution: `sigma ≈ (0.4n + 0.6) × max(w, h) / 512` | `sigma = n`, resolution-independent |
+
+To keep the look you had:
+
+- **iOS:** multiply your old value by ~1.18 (`blur: 10` → `blur: 12`).
+- **Android:** there is no single factor — the old result depended on the source image's
+  resolution. Re-tune against iOS, which the two platforms now agree with.
+
+Also changed:
+
+- `blur` above 25 used to reject the promise on Android. Sigma is now unbounded.
+- Fractional values used to be truncated to whole numbers on iOS. They are honoured now.
+- Blurred images used to fade out at the borders on iOS. Edges are clamped on both platforms now.
 
 ## Credits
 

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

@@ -22,6 +22,11 @@ import com.margelo.nitro.core.Promise
 import com.margelo.nitro.image.HybridImage
 import com.margelo.nitro.image.HybridImageSpec
 import com.margelo.nitro.nitroimagepipeline.transform.BlurTransformation
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.async
+import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.withContext
 import okhttp3.OkHttpClient
 import okio.Path.Companion.toOkioPath
 import org.chromium.net.CronetEngine
@@ -30,29 +35,8 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
   private val context
     get() = NitroModules.applicationContext as Context
 
-  private val okHttpClient: OkHttpClient by lazy {
-    val builder = OkHttpClient.Builder()
-    try {
-      val cronetEngine = CronetEngine.Builder(context).build()
-      builder.addInterceptor(CronetInterceptor.newBuilder(cronetEngine).build())
-    } catch (_: Exception) {
-      // Cronet unavailable (no GMS or unsupported device) — use plain OkHttp
-    }
-    builder.build()
-  }
-
-  private val imageLoader: ImageLoader by lazy {
-    ImageLoader.Builder(context)
-        .components { add(OkHttpNetworkFetcherFactory(callFactory = okHttpClient)) }
-        .memoryCache { MemoryCache.Builder().maxSizePercent(context, 0.25).build() }
-        .diskCache {
-          DiskCache.Builder()
-              .directory(context.cacheDir.resolve("nitro_image_cache").toOkioPath())
-              .maxSizeBytes(256L * 1024 * 1024)
-              .build()
-        }
-        .build()
-  }
+  private val imageLoader: ImageLoader
+    get() = getOrCreateImageLoader(context)
 
   override fun loadImage(url: String, options: Options?): Promise<HybridImageSpec> = Promise.async {
     val blur = options?.blur?.toFloat() ?: 0f
@@ -61,11 +45,6 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
       if (blur > 0f) add(BlurTransformation(context, blur))
       if (cornerRadius > 0f) add(RoundedCornersTransformation(cornerRadius))
     }
-    val memoryCacheKey = buildString {
-      append(url)
-      if (blur > 0f) append("_blur$blur")
-      if (cornerRadius > 0f) append("_corner$cornerRadius")
-    }
     val request =
         ImageRequest.Builder(context)
             .data(url)
@@ -87,7 +66,6 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
               }
             }
             .allowHardware(true)
-            .memoryCacheKey(memoryCacheKey)
             .transformations(transformations)
             .build()
 
@@ -111,23 +89,75 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
   }
 
   override fun preLoadImages(urls: Array<String>): Promise<Unit> = Promise.async {
-    for (url in urls) {
-      val request = ImageRequest.Builder(context).data(url).build()
-      imageLoader.execute(request)
+    coroutineScope {
+      urls
+          .map { url ->
+            async {
+              val request = ImageRequest.Builder(context).data(url).build()
+              imageLoader.execute(request)
+            }
+          }
+          .awaitAll()
     }
+    Unit
   }
 
   override fun gaussianBlur(image: HybridImageSpec, radius: Double): Promise<HybridImageSpec> =
       Promise.async {
         val hybridImage = image as? HybridImage ?: throw Error("Image is not a HybridImage")
-        val clampedRadius = radius.toFloat().coerceIn(0.01f, 25f)
-        val blurred =
-            BlurTransformation(context, clampedRadius).transform(hybridImage.bitmap, Size.ORIGINAL)
-        HybridImage(blurred)
+        // `radius` is a Gaussian sigma in source-image pixels — see BlurTransformation.
+        val sigma = radius.toFloat()
+        if (sigma <= 0f) {
+          hybridImage
+        } else {
+          val blurred =
+              BlurTransformation(context, sigma).transform(hybridImage.bitmap, Size.ORIGINAL)
+          HybridImage(blurred)
+        }
       }
 
-  override fun clearCache() {
+  override fun clearCache(): Promise<Unit> = Promise.async {
     imageLoader.memoryCache?.clear()
-    imageLoader.diskCache?.clear()
+    // DiskCache.clear() does file I/O; keep it off the JS thread but await
+    // completion so callers can rely on the cache being empty, and so an
+    // IOException rejects the promise instead of crashing the process.
+    withContext(Dispatchers.IO) { imageLoader.diskCache?.clear() }
+  }
+
+  companion object {
+    // Coil requires a single DiskCache instance per directory, so the loader
+    // must be shared across all HybridNitroImagePipeline instances.
+    @Volatile private var sharedImageLoader: ImageLoader? = null
+
+    private fun getOrCreateImageLoader(context: Context): ImageLoader =
+        sharedImageLoader
+            ?: synchronized(this) {
+              sharedImageLoader ?: createImageLoader(context).also { sharedImageLoader = it }
+            }
+
+    private fun createImageLoader(context: Context): ImageLoader {
+      val okHttpClient =
+          OkHttpClient.Builder()
+              .apply {
+                try {
+                  val cronetEngine = CronetEngine.Builder(context).build()
+                  addInterceptor(CronetInterceptor.newBuilder(cronetEngine).build())
+                } catch (_: Exception) {
+                  // Cronet unavailable (no GMS or unsupported device) — use plain OkHttp
+                }
+              }
+              .build()
+
+      return ImageLoader.Builder(context)
+          .components { add(OkHttpNetworkFetcherFactory(callFactory = okHttpClient)) }
+          .memoryCache { MemoryCache.Builder().maxSizePercent(context, 0.25).build() }
+          .diskCache {
+            DiskCache.Builder()
+                .directory(context.cacheDir.resolve("nitro_image_cache").toOkioPath())
+                .maxSizeBytes(256L * 1024 * 1024)
+                .build()
+          }
+          .build()
+    }
   }
 }

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

@@ -13,33 +13,57 @@ import androidx.core.graphics.applyCanvas
 import androidx.core.graphics.scale
 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
+ * Native's `blurRadius` each define radius differently, which is why blurs never matched across
+ * platforms.
+ *
+ * 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 radius: Float = 10f,
-    private val sampling: Float = 1f,
+    private val sigma: Float,
 ) : Transformation() {
 
   init {
-    require(radius in 0.01..25.0) { "radius must be in (0, 25]." }
-    require(sampling >= 1f) { "sampling must be >= 1." }
+    require(sigma > 0f && sigma.isFinite()) { "sigma must be > 0." }
   }
 
-  override val cacheKey = "${BlurTransformation::class.java.name}-$radius-$sampling"
+  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)
-    // Auto-scale so the blurred image is at most 512px on the longest side.
-    // Blur is a low-pass filter so blurring at lower resolution is identical in quality.
-    val autoSampling = (maxOf(input.width, input.height) / 512f).coerceAtLeast(sampling)
-    val scaledWidth = (input.width / autoSampling).toInt().coerceAtLeast(1)
-    val scaledHeight = (input.height / autoSampling).toInt().coerceAtLeast(1)
-    val softwareInput = if (input.config == Bitmap.Config.HARDWARE) input.copy(Bitmap.Config.ARGB_8888, false) else input
+    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(1 / autoSampling, 1 / autoSampling)
+      scale(scaleX, scaleY)
       drawBitmap(softwareInput, 0f, 0f, paint)
     }
 
@@ -69,23 +93,25 @@ class BlurTransformation(
       blur?.destroy()
     }
 
-    return output.scale(input.width, input.height)
+    return if (scaledWidth == input.width && scaledHeight == input.height) output
+    else output.scale(input.width, input.height)
   }
 
   override fun equals(other: Any?): Boolean {
     if (this === other) return true
-    return other is BlurTransformation &&
-        context == other.context &&
-        radius == other.radius &&
-        sampling == other.sampling
+    return other is BlurTransformation && context == other.context && sigma == other.sigma
   }
 
-  override fun hashCode(): Int {
-    var result = context.hashCode()
-    result = 31 * result + radius.hashCode()
-    result = 31 * result + sampling.hashCode()
-    return result
-  }
+  override fun hashCode(): Int = 31 * context.hashCode() + sigma.hashCode()
 
-  override fun toString() = "BlurTransformation(radius=$radius, sampling=$sampling)"
+  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
+  }
 }

package/ios/GaussianBlur.swift

@@ -0,0 +1,135 @@
+//
+//  GaussianBlur.swift
+//  NitroImagePipeline
+//
+//  Cross-platform Gaussian blur — the kernel itself.
+//
+//  This file deliberately depends on nothing but Accelerate and CoreGraphics
+//  so `scripts/verify-blur.swift` can compile and measure it on the host
+//  machine. The UIImage/Nuke plumbing lives in GaussianBlurProcessor.swift.
+//
+//  `sigma` is the standard deviation of the Gaussian, measured in *source
+//  image pixels* — the same sigma applied to the same source file produces
+//  the same result on iOS and Android. It is deliberately not a "radius":
+//  CIGaussianBlur, RenderScript and React Native's `blurRadius` each define
+//  radius differently, which is why blurs never matched across platforms.
+//
+//  For reference, React Native's `<Image blurRadius={n} />` halves its input
+//  before convolving, so `blurRadius={n}` is roughly `sigma = n / 2`.
+//
+
+import Accelerate
+import CoreGraphics
+import Foundation
+
+enum GaussianBlur {
+    /// Runs the box-blur passes over `cgImage`. Returns `nil` if the pixel
+    /// buffers could not be allocated.
+    static func convolve(_ cgImage: CGImage, boxes: [UInt32]) -> CGImage? {
+        // 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.
+        guard var format = vImage_CGImageFormat(
+            bitsPerComponent: 8,
+            bitsPerPixel: 32,
+            colorSpace: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.premultipliedFirst.rawValue),
+            renderingIntent: .defaultIntent
+        ) else { return nil }
+
+        var source = vImage_Buffer()
+        guard vImageBuffer_InitWithCGImage(
+            &source, &format, nil, cgImage, vImage_Flags(kvImageNoFlags)
+        ) == kvImageNoError else { return nil }
+        defer { 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) }
+
+        // kvImageEdgeExtend clamps at the borders instead of sampling
+        // transparent black, so the image keeps its edges instead of fading
+        // out into the frame (CIGaussianBlur's default, and the reason blurred
+        // images used to come back with washed-out borders).
+        let flags = vImage_Flags(kvImageEdgeExtend)
+        // The passes use two different kernel widths; size the scratch buffer
+        // for the widest one so every pass fits in it.
+        let widest = boxes.max() ?? 1
+        let tempSize = vImageBoxConvolve_ARGB8888(
+            &source, &scratch, nil, 0, 0, widest, widest, nil,
+            vImage_Flags(kvImageEdgeExtend | kvImageGetTempBufferSize)
+        )
+        guard tempSize > 0, let temp = malloc(tempSize) else { return nil }
+        defer { free(temp) }
+
+        // Ping-pong between the two buffers; after an odd number of passes the
+        // result sits in `input`.
+        var input = source
+        var output = scratch
+        for box in boxes {
+            guard vImageBoxConvolve_ARGB8888(
+                &input, &output, temp, 0, 0, box, box, nil, flags
+            ) == kvImageNoError else { return nil }
+            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 }
+
+        return blurred
+    }
+
+    /// Widths for the three box-blur passes that approximate a Gaussian of
+    /// `sigma` (the classic approximation: three boxes land within a few
+    /// percent of a true Gaussian, and Accelerate runs them in O(1) per pixel
+    /// regardless of how wide they are).
+    ///
+    /// Three boxes of widths w1…w3 produce a standard deviation of
+    /// `sqrt((w1² + w2² + w3² - 3) / 12)`. Box widths have to be odd, so the
+    /// passes are split between the two odd integers straddling the ideal
+    /// width and the split landing closest to `sigma` wins — which keeps the
+    /// error under half a pixel at any sigma instead of always undershooting.
+    static func boxSizes(forSigma sigma: Double) -> [UInt32] {
+        let passes = 3
+        var lower = Int(((12 * sigma * sigma / Double(passes)) + 1).squareRoot())
+        if lower % 2 == 0 { lower -= 1 }
+        // Upper bound keeps `upper` inside UInt32 for absurd sigmas; a kernel
+        // that wide is already far larger than any real image.
+        lower = min(max(lower, 1), Int(UInt32.max) - 2)
+        let upper = lower + 2
+
+        // Written as a plain loop rather than map/min(by:): the inferred
+        // version tripped "type of expression is ambiguous" on Swift 6.2.
+        var best: [UInt32] = []
+        var bestError: Double = .infinity
+        for lowerCount in 0...passes {
+            var candidate: [UInt32] = []
+            for pass in 0..<passes {
+                candidate.append(UInt32(pass < lowerCount ? lower : upper))
+            }
+            // `.magnitude` rather than `abs()`: Nitro's C++ interop puts
+            // std::abs overloads in scope, and Swift 6.2 calls the resulting
+            // `abs` ambiguous when this file is compiled as part of the pod.
+            let error: Double = (standardDeviation(of: candidate) - sigma).magnitude
+            if error < bestError {
+                bestError = error
+                best = candidate
+            }
+        }
+        return best
+    }
+
+    /// The standard deviation three box blurs of the given widths add up to.
+    private static func standardDeviation(of boxes: [UInt32]) -> Double {
+        var sum: Double = 0
+        for box in boxes {
+            let width = Double(box)
+            sum += width * width - 1
+        }
+        return (sum / 12).squareRoot()
+    }
+}

package/ios/GaussianBlurProcessor.swift

@@ -0,0 +1,41 @@
+//
+//  GaussianBlurProcessor.swift
+//  NitroImagePipeline
+//
+//  UIImage and Nuke plumbing around the kernel in GaussianBlur.swift.
+//
+
+import CoreGraphics
+import Foundation
+import Nuke
+import UIKit
+
+extension GaussianBlur {
+    /// Applies a Gaussian blur of standard deviation `sigma` (in image pixels).
+    ///
+    /// Returns `image` unchanged when `sigma` is too small to affect a pixel,
+    /// and `nil` only when the pixel buffers could not be allocated.
+    static func apply(to image: UIImage, sigma: Double) -> UIImage? {
+        guard sigma > 0, sigma.isFinite, let cgImage = image.cgImage else { return image }
+
+        let boxes = boxSizes(forSigma: sigma)
+        guard boxes.contains(where: { $0 > 1 }) else { return image }
+        guard let blurred = convolve(cgImage, boxes: boxes) else { return nil }
+
+        return UIImage(cgImage: blurred, scale: image.scale, orientation: image.imageOrientation)
+    }
+}
+
+/// Nuke processor so `loadImage(url:, { blur })` and `gaussianBlur(image:, sigma)`
+/// go through the exact same kernel.
+struct GaussianBlurProcessor: ImageProcessing {
+    let sigma: Double
+
+    var identifier: String { "com.nitroimagepipeline.gaussianBlur?sigma=\(sigma)" }
+
+    var hashableIdentifier: AnyHashable { identifier }
+
+    func process(_ image: PlatformImage) -> PlatformImage? {
+        GaussianBlur.apply(to: image, sigma: sigma)
+    }
+}

package/ios/HybridNitroImagePipeline.swift

@@ -11,14 +11,48 @@ import NitroImage
 import Nuke
 
 import UIKit
-import CoreImage
 
 private class HybridImage: HybridImageSpec, NativeImage {
     let uiImage: UIImage
 
+    // PNG encoding is expensive; encode once and reuse for both
+    // toArrayBuffer() and toBase64(). Guarded by a lock (lazy var is not
+    // thread-safe) and dropped on memory pressure so a JS-retained image
+    // doesn't pin its encoding forever.
+    private let pngLock = NSLock()
+    private var cachedPngData: Data?
+    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)
+        }
+    }
+
+    private func pngData() -> Data? {
+        pngLock.lock()
+        defer { pngLock.unlock() }
+        if let cachedPngData {
+            return cachedPngData
+        }
+        let data = uiImage.pngData()
+        cachedPngData = data
+        return data
     }
 
     var width: Double {
@@ -30,14 +64,14 @@ private class HybridImage: HybridImageSpec, NativeImage {
     }
 
     func toArrayBuffer() throws -> ArrayBuffer {
-        guard let data = uiImage.pngData() else {
+        guard let data = pngData() else {
             throw RuntimeError.error(withMessage: "Failed to encode image to PNG")
         }
         return try ArrayBuffer.copy(data: data)
     }
 
     func toBase64() throws -> String {
-        guard let data = uiImage.pngData() else {
+        guard let data = pngData() else {
             throw RuntimeError.error(withMessage: "Failed to encode image")
         }
 
@@ -50,14 +84,31 @@ private class HybridImage: HybridImageSpec, NativeImage {
 }
 
 class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
-    private let prefetcher = ImagePrefetcher()
-
-    override init() {
-        ImagePipeline.shared = ImagePipeline(configuration: .withDataCache)
-    }
+    // One shared pipeline (instead of mutating ImagePipeline.shared) so the
+    // prefetcher and loadImage read/write the exact same caches, other Nuke
+    // 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 = {
+        var configuration = ImagePipeline.Configuration.withDataCache
+        // Store processed (blurred/rounded) variants on disk in addition to
+        // the original download, so they survive memory eviction and
+        // restarts without dropping the original for other variants.
+        configuration.dataCachePolicy = .storeAll
+        return ImagePipeline(configuration: configuration)
+    }()
+
+    private static let sharedPrefetcher = ImagePrefetcher(pipeline: sharedPipeline)
+
+    private var pipeline: ImagePipeline { Self.sharedPipeline }
+    private var prefetcher: ImagePrefetcher { Self.sharedPrefetcher }
 
     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)")
+            }
+
             let cacheOptions: ImageRequest.Options = switch options?.cache {
             case .memory: [.disableDiskCache]
             case .disk:   [.disableMemoryCache]
@@ -67,19 +118,19 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
 
             var processors: [any ImageProcessing] = []
             if let blur = options?.blur, blur > 0 {
-                processors.append(.gaussianBlur(radius: Int(blur)))
+                processors.append(GaussianBlurProcessor(sigma: blur))
             }
             if let cornerRadius = options?.cornerRadius, cornerRadius > 0 {
                 processors.append(.roundedCorners(radius: cornerRadius))
             }
 
             let imgRequest = ImageRequest(
-                url: URL(string: url),
+                url: imageUrl,
                 processors: processors,
                 options: cacheOptions
             )
 
-            let image = try await ImagePipeline.shared.image(for: imgRequest)
+            let image = try await self.pipeline.image(for: imgRequest)
             return HybridImage(uiImage: image)
         }
     }
@@ -101,8 +152,10 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
         }
     }
 
-    func clearCache() throws {
-        ImagePipeline.shared.cache.removeAll()
+    func clearCache() throws -> Promise<Void> {
+        return Promise.async {
+            self.pipeline.cache.removeAll()
+        }
     }
 
     func gaussianBlur(image: any HybridImageSpec, radius: Double) throws -> Promise<any HybridImageSpec> {
@@ -111,19 +164,11 @@ class HybridNitroImagePipeline: HybridNitroImagePipelineSpec {
                 throw RuntimeError.error(withMessage: "Unsupported image type")
             }
 
-            let uiImage = nativeImage.uiImage
-
-            let ciImage = CIImage(image: uiImage)
-
-            let filter = CIFilter(name: "CIGaussianBlur")!
-            filter.setValue(ciImage, forKey: kCIInputImageKey)
-            filter.setValue(radius, forKey: kCIInputRadiusKey)
-
-            let context = CIContext()
-            let output = filter.outputImage
-            let cgImage = context.createCGImage(output!, from: ciImage!.extent)
+            guard let blurred = GaussianBlur.apply(to: nativeImage.uiImage, sigma: radius) else {
+                throw RuntimeError.error(withMessage: "Failed to apply gaussian blur")
+            }
 
-            return HybridImage(uiImage: UIImage(cgImage: cgImage!))
+            return HybridImage(uiImage: blurred)
         }
     }
 

package/lib/commonjs/index.js

@@ -19,32 +19,53 @@ const NitroImagePipeline = exports.NitroImagePipeline = _reactNativeNitroModules
 function useImage({
   url,
   blur = 0,
-  cornerRadius = 0
+  cornerRadius = 0,
+  cache
 }) {
   const [image, setImage] = (0, _react.useState)({
     image: undefined,
     error: undefined
   });
+  const loadedUrlRef = (0, _react.useRef)(url);
   (0, _react.useEffect)(() => {
+    let cancelled = false;
+    // Only reset to the loading state when the URL changes; for same-URL
+    // param tweaks (blur/cornerRadius/cache) keep showing the current image
+    // until the new variant resolves, to avoid flashing empty.
+    if (loadedUrlRef.current !== url) {
+      loadedUrlRef.current = url;
+      setImage({
+        image: undefined,
+        error: undefined
+      });
+    }
     (async () => {
       try {
         const result = await NitroImagePipeline.loadImage(url, {
           blur,
-          cornerRadius
-        });
-        setImage({
-          image: result,
-          error: undefined
+          cornerRadius,
+          cache
         });
+        if (!cancelled) {
+          setImage({
+            image: result,
+            error: undefined
+          });
+        }
       } catch (e) {
         const error = e instanceof Error ? e : new Error(`${e}`);
-        setImage({
-          image: undefined,
-          error: error
-        });
+        if (!cancelled) {
+          setImage({
+            image: undefined,
+            error: error
+          });
+        }
       }
     })();
-  }, [url, blur]);
+    return () => {
+      cancelled = true;
+    };
+  }, [url, blur, cornerRadius, cache]);
   return image;
 }
 //# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","_reactNativeNitroModules","NitroImagePipeline","exports","NitroModules","createHybridObject","useImage","url","blur","cornerRadius","image","setImage","useState","undefined","error","useEffect","result","loadImage","e","Error"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA,IAAAC,wBAAA,GAAAD,OAAA;AAIO,MAAME,kBAAkB,GAAAC,OAAA,CAAAD,kBAAA,GAC7BE,qCAAY,CAACC,kBAAkB,CAAyB,oBAAoB,CAAC;AAmB/E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,QAAQA,CAAC;EACvBC,GAAG;EACHC,IAAI,GAAG,CAAC;EACRC,YAAY,GAAG;AAKjB,CAAC,EAAU;EACT,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAG,IAAAC,eAAQ,EAAS;IACzCF,KAAK,EAAEG,SAAS;IAChBC,KAAK,EAAED;EACT,CAAC,CAAC;EAEF,IAAAE,gBAAS,EAAC,MAAM;IACd,CAAC,YAAY;MACX,IAAI;QACF,MAAMC,MAAM,GAAG,MAAMd,kBAAkB,CAACe,SAAS,CAACV,GAAG,EAAE;UACrDC,IAAI;UACJC;QACF,CAAC,CAAC;QAEFE,QAAQ,CAAC;UAAED,KAAK,EAAEM,MAAM;UAAEF,KAAK,EAAED;QAAU,CAAC,CAAC;MAC/C,CAAC,CAAC,OAAOK,CAAC,EAAE;QACV,MAAMJ,KAAK,GAAGI,CAAC,YAAYC,KAAK,GAAGD,CAAC,GAAG,IAAIC,KAAK,CAAC,GAAGD,CAAC,EAAE,CAAC;QACxDP,QAAQ,CAAC;UAAED,KAAK,EAAEG,SAAS;UAAEC,KAAK,EAAEA;QAAM,CAAC,CAAC;MAC9C;IACF,CAAC,EAAE,CAAC;EACN,CAAC,EAAE,CAACP,GAAG,EAAEC,IAAI,CAAC,CAAC;EAEf,OAAOE,KAAK;AACd","ignoreList":[]}
+{"version":3,"names":["_react","require","_reactNativeNitroModules","NitroImagePipeline","exports","NitroModules","createHybridObject","useImage","url","blur","cornerRadius","cache","image","setImage","useState","undefined","error","loadedUrlRef","useRef","useEffect","cancelled","current","result","loadImage","e","Error"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA,IAAAC,wBAAA,GAAAD,OAAA;AAUO,MAAME,kBAAkB,GAAAC,OAAA,CAAAD,kBAAA,GAC7BE,qCAAY,CAACC,kBAAkB,CAAyB,oBAAoB,CAAC;AAmB/E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,QAAQA,CAAC;EACvBC,GAAG;EACHC,IAAI,GAAG,CAAC;EACRC,YAAY,GAAG,CAAC;EAChBC;AAWF,CAAC,EAAU;EACT,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAG,IAAAC,eAAQ,EAAS;IACzCF,KAAK,EAAEG,SAAS;IAChBC,KAAK,EAAED;EACT,CAAC,CAAC;EACF,MAAME,YAAY,GAAG,IAAAC,aAAM,EAACV,GAAG,CAAC;EAEhC,IAAAW,gBAAS,EAAC,MAAM;IACd,IAAIC,SAAS,GAAG,KAAK;IACrB;IACA;IACA;IACA,IAAIH,YAAY,CAACI,OAAO,KAAKb,GAAG,EAAE;MAChCS,YAAY,CAACI,OAAO,GAAGb,GAAG;MAC1BK,QAAQ,CAAC;QAAED,KAAK,EAAEG,SAAS;QAAEC,KAAK,EAAED;MAAU,CAAC,CAAC;IAClD;IAEA,CAAC,YAAY;MACX,IAAI;QACF,MAAMO,MAAM,GAAG,MAAMnB,kBAAkB,CAACoB,SAAS,CAACf,GAAG,EAAE;UACrDC,IAAI;UACJC,YAAY;UACZC;QACF,CAAC,CAAC;QAEF,IAAI,CAACS,SAAS,EAAE;UACdP,QAAQ,CAAC;YAAED,KAAK,EAAEU,MAAM;YAAEN,KAAK,EAAED;UAAU,CAAC,CAAC;QAC/C;MACF,CAAC,CAAC,OAAOS,CAAC,EAAE;QACV,MAAMR,KAAK,GAAGQ,CAAC,YAAYC,KAAK,GAAGD,CAAC,GAAG,IAAIC,KAAK,CAAC,GAAGD,CAAC,EAAE,CAAC;QACxD,IAAI,CAACJ,SAAS,EAAE;UACdP,QAAQ,CAAC;YAAED,KAAK,EAAEG,SAAS;YAAEC,KAAK,EAAEA;UAAM,CAAC,CAAC;QAC9C;MACF;IACF,CAAC,EAAE,CAAC;IAEJ,OAAO,MAAM;MACXI,SAAS,GAAG,IAAI;IAClB,CAAC;EACH,CAAC,EAAE,CAACZ,GAAG,EAAEC,IAAI,EAAEC,YAAY,EAAEC,KAAK,CAAC,CAAC;EAEpC,OAAOC,KAAK;AACd","ignoreList":[]}

package/lib/module/index.js

@@ -1,6 +1,6 @@
 "use strict";
 
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { NitroModules } from 'react-native-nitro-modules';
 export const NitroImagePipeline = NitroModules.createHybridObject('NitroImagePipeline');
 /**
@@ -14,32 +14,53 @@ export const NitroImagePipeline = NitroModules.createHybridObject('NitroImagePip
 export function useImage({
   url,
   blur = 0,
-  cornerRadius = 0
+  cornerRadius = 0,
+  cache
 }) {
   const [image, setImage] = useState({
     image: undefined,
     error: undefined
   });
+  const loadedUrlRef = useRef(url);
   useEffect(() => {
+    let cancelled = false;
+    // Only reset to the loading state when the URL changes; for same-URL
+    // param tweaks (blur/cornerRadius/cache) keep showing the current image
+    // until the new variant resolves, to avoid flashing empty.
+    if (loadedUrlRef.current !== url) {
+      loadedUrlRef.current = url;
+      setImage({
+        image: undefined,
+        error: undefined
+      });
+    }
     (async () => {
       try {
         const result = await NitroImagePipeline.loadImage(url, {
           blur,
-          cornerRadius
-        });
-        setImage({
-          image: result,
-          error: undefined
+          cornerRadius,
+          cache
         });
+        if (!cancelled) {
+          setImage({
+            image: result,
+            error: undefined
+          });
+        }
       } catch (e) {
         const error = e instanceof Error ? e : new Error(`${e}`);
-        setImage({
-          image: undefined,
-          error: error
-        });
+        if (!cancelled) {
+          setImage({
+            image: undefined,
+            error: error
+          });
+        }
       }
     })();
-  }, [url, blur]);
+    return () => {
+      cancelled = true;
+    };
+  }, [url, blur, cornerRadius, cache]);
   return image;
 }
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["useEffect","useState","NitroModules","NitroImagePipeline","createHybridObject","useImage","url","blur","cornerRadius","image","setImage","undefined","error","result","loadImage","e","Error"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,QAAQ,QAAQ,OAAO;AAE3C,SAASC,YAAY,QAAQ,4BAA4B;AAIzD,OAAO,MAAMC,kBAAkB,GAC7BD,YAAY,CAACE,kBAAkB,CAAyB,oBAAoB,CAAC;AAmB/E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,QAAQA,CAAC;EACvBC,GAAG;EACHC,IAAI,GAAG,CAAC;EACRC,YAAY,GAAG;AAKjB,CAAC,EAAU;EACT,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAGT,QAAQ,CAAS;IACzCQ,KAAK,EAAEE,SAAS;IAChBC,KAAK,EAAED;EACT,CAAC,CAAC;EAEFX,SAAS,CAAC,MAAM;IACd,CAAC,YAAY;MACX,IAAI;QACF,MAAMa,MAAM,GAAG,MAAMV,kBAAkB,CAACW,SAAS,CAACR,GAAG,EAAE;UACrDC,IAAI;UACJC;QACF,CAAC,CAAC;QAEFE,QAAQ,CAAC;UAAED,KAAK,EAAEI,MAAM;UAAED,KAAK,EAAED;QAAU,CAAC,CAAC;MAC/C,CAAC,CAAC,OAAOI,CAAC,EAAE;QACV,MAAMH,KAAK,GAAGG,CAAC,YAAYC,KAAK,GAAGD,CAAC,GAAG,IAAIC,KAAK,CAAC,GAAGD,CAAC,EAAE,CAAC;QACxDL,QAAQ,CAAC;UAAED,KAAK,EAAEE,SAAS;UAAEC,KAAK,EAAEA;QAAM,CAAC,CAAC;MAC9C;IACF,CAAC,EAAE,CAAC;EACN,CAAC,EAAE,CAACN,GAAG,EAAEC,IAAI,CAAC,CAAC;EAEf,OAAOE,KAAK;AACd","ignoreList":[]}
+{"version":3,"names":["useEffect","useRef","useState","NitroModules","NitroImagePipeline","createHybridObject","useImage","url","blur","cornerRadius","cache","image","setImage","undefined","error","loadedUrlRef","cancelled","current","result","loadImage","e","Error"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,OAAO;AAEnD,SAASC,YAAY,QAAQ,4BAA4B;AAUzD,OAAO,MAAMC,kBAAkB,GAC7BD,YAAY,CAACE,kBAAkB,CAAyB,oBAAoB,CAAC;AAmB/E;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,QAAQA,CAAC;EACvBC,GAAG;EACHC,IAAI,GAAG,CAAC;EACRC,YAAY,GAAG,CAAC;EAChBC;AAWF,CAAC,EAAU;EACT,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAGV,QAAQ,CAAS;IACzCS,KAAK,EAAEE,SAAS;IAChBC,KAAK,EAAED;EACT,CAAC,CAAC;EACF,MAAME,YAAY,GAAGd,MAAM,CAACM,GAAG,CAAC;EAEhCP,SAAS,CAAC,MAAM;IACd,IAAIgB,SAAS,GAAG,KAAK;IACrB;IACA;IACA;IACA,IAAID,YAAY,CAACE,OAAO,KAAKV,GAAG,EAAE;MAChCQ,YAAY,CAACE,OAAO,GAAGV,GAAG;MAC1BK,QAAQ,CAAC;QAAED,KAAK,EAAEE,SAAS;QAAEC,KAAK,EAAED;MAAU,CAAC,CAAC;IAClD;IAEA,CAAC,YAAY;MACX,IAAI;QACF,MAAMK,MAAM,GAAG,MAAMd,kBAAkB,CAACe,SAAS,CAACZ,GAAG,EAAE;UACrDC,IAAI;UACJC,YAAY;UACZC;QACF,CAAC,CAAC;QAEF,IAAI,CAACM,SAAS,EAAE;UACdJ,QAAQ,CAAC;YAAED,KAAK,EAAEO,MAAM;YAAEJ,KAAK,EAAED;UAAU,CAAC,CAAC;QAC/C;MACF,CAAC,CAAC,OAAOO,CAAC,EAAE;QACV,MAAMN,KAAK,GAAGM,CAAC,YAAYC,KAAK,GAAGD,CAAC,GAAG,IAAIC,KAAK,CAAC,GAAGD,CAAC,EAAE,CAAC;QACxD,IAAI,CAACJ,SAAS,EAAE;UACdJ,QAAQ,CAAC;YAAED,KAAK,EAAEE,SAAS;YAAEC,KAAK,EAAEA;UAAM,CAAC,CAAC;QAC9C;MACF;IACF,CAAC,EAAE,CAAC;IAEJ,OAAO,MAAM;MACXE,SAAS,GAAG,IAAI;IAClB,CAAC;EACH,CAAC,EAAE,CAACT,GAAG,EAAEC,IAAI,EAAEC,YAAY,EAAEC,KAAK,CAAC,CAAC;EAEpC,OAAOC,KAAK;AACd","ignoreList":[]}

package/lib/typescript/src/index.d.ts

@@ -1,5 +1,6 @@
 import type { Image } from 'react-native-nitro-image';
-import type { NitroImagePipeline as NitroImagePipelineSpec } from './specs/nitro-image-toolkit.nitro';
+import type { CacheOption, NitroImagePipeline as NitroImagePipelineSpec, Options } from './specs/nitro-image-toolkit.nitro';
+export type { CacheOption, Options };
 export declare const NitroImagePipeline: NitroImagePipelineSpec;
 type Result = {
     image: undefined;
@@ -19,10 +20,15 @@ type Result = {
  * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
  * ```
  */
-export declare function useImage({ url, blur, cornerRadius, }: {
+export declare function useImage({ url, blur, cornerRadius, cache, }: {
     url: string;
+    /**
+     * Gaussian blur strength, as the standard deviation (sigma) of the blur in
+     * source-image pixels. Matches across iOS and Android; roughly half of
+     * React Native's `blurRadius`.
+     */
     blur?: number;
     cornerRadius?: number;
+    cache?: CacheOption;
 }): Result;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,KAAK,EAAE,kBAAkB,IAAI,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAEtG,eAAO,MAAM,kBAAkB,wBACgD,CAAC;AAEhF,KAAK,MAAM,GAEP;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;CAClB,GAED;IACE,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB,GAED;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEN;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,IAAQ,EACR,YAAgB,GACjB,EAAE;IACD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,MAAM,CAuBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,IAAI,sBAAsB,EAC5C,OAAO,EACR,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAErC,eAAO,MAAM,kBAAkB,wBACgD,CAAC;AAEhF,KAAK,MAAM,GAEP;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;CAClB,GAED;IACE,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB,GAED;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEN;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EACH,IAAQ,EACR,YAAgB,EAChB,KAAK,GACN,EAAE;IACD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,GAAG,MAAM,CA0CT"}

package/lib/typescript/src/specs/nitro-image-toolkit.nitro.d.ts

@@ -1,7 +1,16 @@
 import type { Image } from 'react-native-nitro-image';
 import type { HybridObject } from 'react-native-nitro-modules';
-type CacheOption = 'memory' | 'disk' | 'none';
-type Options = {
+export type CacheOption = 'memory' | 'disk' | 'none';
+export type Options = {
+    /**
+     * Gaussian blur strength, given as the standard deviation (sigma) of the
+     * blur in **source-image pixels**. The same value on the same source image
+     * produces the same result on iOS and Android.
+     *
+     * React Native's `<Image blurRadius={n} />` is roughly `blur: n / 2`.
+     *
+     * @default 0 (no blur)
+     */
     blur?: number;
     cache?: CacheOption;
     cornerRadius?: number;
@@ -13,8 +22,12 @@ export interface NitroImagePipeline extends HybridObject<{
     loadImage(url: string, options?: Options): Promise<Image>;
     preLoadImage(url: string): Promise<void>;
     preLoadImages(urls: string[]): Promise<void>;
+    /**
+     * Blurs an already-loaded image. `radius` is the standard deviation (sigma)
+     * of the Gaussian in **source-image pixels**, the same unit as
+     * {@linkcode Options.blur}.
+     */
     gaussianBlur(image: Image, radius: number): Promise<Image>;
-    clearCache(): void;
+    clearCache(): Promise<void>;
 }
-export {};
 //# sourceMappingURL=nitro-image-toolkit.nitro.d.ts.map

package/lib/typescript/src/specs/nitro-image-toolkit.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nitro-image-toolkit.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/nitro-image-toolkit.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,KAAK,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAC9C,KAAK,OAAO,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,MAAM,WAAW,kBACf,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;IACzD,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAG3D,UAAU,IAAI,IAAI,CAAC;CACpB"}
+{"version":3,"file":"nitro-image-toolkit.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/nitro-image-toolkit.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,OAAO,GAAG;IACpB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,WAAW,kBAAmB,SAAQ,YAAY,CAAC;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC;IACA,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAG3D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}

package/nitrogen/generated/android/c++/JHybridNitroImagePipelineSpec.cpp

@@ -132,9 +132,20 @@ namespace margelo::nitro::nitroimagepipeline {
       return __promise;
     }();
   }
-  void JHybridNitroImagePipelineSpec::clearCache() {
-    static const auto method = _javaPart->javaClassStatic()->getMethod<void()>("clearCache");
-    method(_javaPart);
+  std::shared_ptr<Promise<void>> JHybridNitroImagePipelineSpec::clearCache() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JPromise::javaobject>()>("clearCache");
+    auto __result = method(_javaPart);
+    return [&]() {
+      auto __promise = Promise<void>::create();
+      __result->cthis()->addOnResolvedListener([=](const jni::alias_ref<jni::JObject>& /* unit */) {
+        __promise->resolve();
+      });
+      __result->cthis()->addOnRejectedListener([=](const jni::alias_ref<jni::JThrowable>& __throwable) {
+        jni::JniException __jniError(__throwable);
+        __promise->reject(std::make_exception_ptr(__jniError));
+      });
+      return __promise;
+    }();
   }
 
 } // namespace margelo::nitro::nitroimagepipeline

package/nitrogen/generated/android/c++/JHybridNitroImagePipelineSpec.hpp

@@ -58,7 +58,7 @@ namespace margelo::nitro::nitroimagepipeline {
     std::shared_ptr<Promise<void>> preLoadImage(const std::string& url) override;
     std::shared_ptr<Promise<void>> preLoadImages(const std::vector<std::string>& urls) override;
     std::shared_ptr<Promise<std::shared_ptr<margelo::nitro::image::HybridImageSpec>>> gaussianBlur(const std::shared_ptr<margelo::nitro::image::HybridImageSpec>& image, double radius) override;
-    void clearCache() override;
+    std::shared_ptr<Promise<void>> clearCache() override;
 
   private:
     jni::global_ref<JHybridNitroImagePipelineSpec::JavaPart> _javaPart;

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitroimagepipeline/HybridNitroImagePipelineSpec.kt

@@ -49,7 +49,7 @@ abstract class HybridNitroImagePipelineSpec: HybridObject() {
   
   @DoNotStrip
   @Keep
-  abstract fun clearCache(): Unit
+  abstract fun clearCache(): Promise<Unit>
 
   // Default implementation of `HybridObject.toString()`
   override fun toString(): String {

package/nitrogen/generated/ios/NitroImagePipeline-Swift-Cxx-Bridge.hpp

@@ -231,14 +231,5 @@ namespace margelo::nitro::nitroimagepipeline::bridge::swift {
   inline Result_std__shared_ptr_Promise_void___ create_Result_std__shared_ptr_Promise_void___(const std::exception_ptr& error) noexcept {
     return Result<std::shared_ptr<Promise<void>>>::withError(error);
   }
-  
-  // pragma MARK: Result<void>
-  using Result_void_ = Result<void>;
-  inline Result_void_ create_Result_void_() noexcept {
-    return Result<void>::withValue();
-  }
-  inline Result_void_ create_Result_void_(const std::exception_ptr& error) noexcept {
-    return Result<void>::withError(error);
-  }
 
 } // namespace margelo::nitro::nitroimagepipeline::bridge::swift

package/nitrogen/generated/ios/c++/HybridNitroImagePipelineSpecSwift.hpp

@@ -110,11 +110,13 @@ namespace margelo::nitro::nitroimagepipeline {
       auto __value = std::move(__result.value());
       return __value;
     }
-    inline void clearCache() override {
+    inline std::shared_ptr<Promise<void>> clearCache() override {
       auto __result = _swiftPart.clearCache();
       if (__result.hasError()) [[unlikely]] {
         std::rethrow_exception(__result.error());
       }
+      auto __value = std::move(__result.value());
+      return __value;
     }
 
   private:

package/nitrogen/generated/ios/swift/HybridNitroImagePipelineSpec.swift

@@ -18,7 +18,7 @@ public protocol HybridNitroImagePipelineSpec_protocol: HybridObject {
   func preLoadImage(url: String) throws -> Promise<Void>
   func preLoadImages(urls: [String]) throws -> Promise<Void>
   func gaussianBlur(image: (any HybridImageSpec), radius: Double) throws -> Promise<(any HybridImageSpec)>
-  func clearCache() throws -> Void
+  func clearCache() throws -> Promise<Void>
 }
 
 public extension HybridNitroImagePipelineSpec_protocol {

package/nitrogen/generated/ios/swift/HybridNitroImagePipelineSpec_cxx.swift

@@ -212,13 +212,21 @@ open class HybridNitroImagePipelineSpec_cxx {
   }
   
   @inline(__always)
-  public final func clearCache() -> bridge.Result_void_ {
+  public final func clearCache() -> bridge.Result_std__shared_ptr_Promise_void___ {
     do {
-      try self.__implementation.clearCache()
-      return bridge.create_Result_void_()
+      let __result = try self.__implementation.clearCache()
+      let __resultCpp = { () -> bridge.std__shared_ptr_Promise_void__ in
+        let __promise = bridge.create_std__shared_ptr_Promise_void__()
+        let __promiseHolder = bridge.wrap_std__shared_ptr_Promise_void__(__promise)
+        __result
+          .then({ __result in __promiseHolder.resolve() })
+          .catch({ __error in __promiseHolder.reject(__error.toCpp()) })
+        return __promise
+      }()
+      return bridge.create_Result_std__shared_ptr_Promise_void___(__resultCpp)
     } catch (let __error) {
       let __exceptionPtr = __error.toCpp()
-      return bridge.create_Result_void_(__exceptionPtr)
+      return bridge.create_Result_std__shared_ptr_Promise_void___(__exceptionPtr)
     }
   }
 }

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

@@ -61,7 +61,7 @@ namespace margelo::nitro::nitroimagepipeline {
       virtual std::shared_ptr<Promise<void>> preLoadImage(const std::string& url) = 0;
       virtual std::shared_ptr<Promise<void>> preLoadImages(const std::vector<std::string>& urls) = 0;
       virtual std::shared_ptr<Promise<std::shared_ptr<margelo::nitro::image::HybridImageSpec>>> gaussianBlur(const std::shared_ptr<margelo::nitro::image::HybridImageSpec>& image, double radius) = 0;
-      virtual void clearCache() = 0;
+      virtual std::shared_ptr<Promise<void>> clearCache() = 0;
 
     protected:
       // Hybrid Setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-image-pipeline",
-  "version": "0.3.4",
+  "version": "1.0.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",
@@ -9,12 +9,15 @@
   "source": "src/index",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "biome check .",
-    "format": "biome format --write .",
+    "lint": "oxlint && oxfmt --check",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "format": "oxfmt",
     "clean": "git clean -dfX",
+    "prepare": "lefthook install || true",
     "release": "semantic-release",
     "build": "bun run typecheck && bob build",
-    "codegen": "nitrogen --logLevel=\"debug\" && bun run build"
+    "codegen": "nitrogen --logLevel=\"debug\" && bun run build",
+    "verify:blur": "swiftc -O -o \"${TMPDIR:-/tmp}/nitro-verify-blur\" scripts/verify-blur.swift ios/GaussianBlur.swift && \"${TMPDIR:-/tmp}/nitro-verify-blur\""
   },
   "keywords": [
     "react-native",
@@ -59,26 +62,28 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.6",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.1",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "@types/jest": "^30.0.0",
     "@types/react": "19.2.18",
-    "conventional-changelog-conventionalcommits": "^10.2.1",
-    "nitrogen": "0.36.5",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "lefthook": "^2.1.10",
+    "nitrogen": "0.37.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
     "react": "19.2.3",
     "react-native": "0.84.1",
     "react-native-builder-bob": "^0.43.0",
-    "react-native-nitro-modules": "0.36.5",
-    "semantic-release": "^25.0.8",
-    "typescript": "^5.8.3"
+    "react-native-nitro-modules": "0.37.0",
+    "semantic-release": "^25.0.9",
+    "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
     "react-native-nitro-modules": "*",
-    "react-native-nitro-image": "*"
+    "react-native-nitro-image": "0.15.1"
   },
   "overrides": {
     "lodash-es": "4.17.21"
@@ -96,5 +101,8 @@
         }
       ]
     ]
-  }
+  },
+  "trustedDependencies": [
+    "lefthook"
+  ]
 }

package/src/index.ts

@@ -1,8 +1,14 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import type { Image } from 'react-native-nitro-image';
 import { NitroModules } from 'react-native-nitro-modules';
 
-import type { NitroImagePipeline as NitroImagePipelineSpec } from './specs/nitro-image-toolkit.nitro';
+import type {
+  CacheOption,
+  NitroImagePipeline as NitroImagePipelineSpec,
+  Options,
+} from './specs/nitro-image-toolkit.nitro';
+
+export type { CacheOption, Options };
 
 export const NitroImagePipeline =
   NitroModules.createHybridObject<NitroImagePipelineSpec>('NitroImagePipeline');
@@ -36,31 +42,57 @@ export function useImage({
   url,
   blur = 0,
   cornerRadius = 0,
+  cache,
 }: {
   url: string;
+  /**
+   * Gaussian blur strength, as the standard deviation (sigma) of the blur in
+   * source-image pixels. Matches across iOS and Android; roughly half of
+   * React Native's `blurRadius`.
+   */
   blur?: number;
   cornerRadius?: number;
+  cache?: CacheOption;
 }): Result {
   const [image, setImage] = useState<Result>({
     image: undefined,
     error: undefined,
   });
+  const loadedUrlRef = useRef(url);
 
   useEffect(() => {
+    let cancelled = false;
+    // Only reset to the loading state when the URL changes; for same-URL
+    // param tweaks (blur/cornerRadius/cache) keep showing the current image
+    // until the new variant resolves, to avoid flashing empty.
+    if (loadedUrlRef.current !== url) {
+      loadedUrlRef.current = url;
+      setImage({ image: undefined, error: undefined });
+    }
+
     (async () => {
       try {
         const result = await NitroImagePipeline.loadImage(url, {
           blur,
           cornerRadius,
+          cache,
         });
 
-        setImage({ image: result, error: undefined });
+        if (!cancelled) {
+          setImage({ image: result, error: undefined });
+        }
       } catch (e) {
         const error = e instanceof Error ? e : new Error(`${e}`);
-        setImage({ image: undefined, error: error });
+        if (!cancelled) {
+          setImage({ image: undefined, error: error });
+        }
       }
     })();
-  }, [url, blur]);
+
+    return () => {
+      cancelled = true;
+    };
+  }, [url, blur, cornerRadius, cache]);
 
   return image;
 }

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

@@ -1,16 +1,36 @@
 import type { Image } from 'react-native-nitro-image';
 import type { HybridObject } from 'react-native-nitro-modules';
 
-type CacheOption = 'memory' | 'disk' | 'none';
-type Options = { blur?: number; cache?: CacheOption; cornerRadius?: number };
+export type CacheOption = 'memory' | 'disk' | 'none';
+export type Options = {
+  /**
+   * Gaussian blur strength, given as the standard deviation (sigma) of the
+   * blur in **source-image pixels**. The same value on the same source image
+   * produces the same result on iOS and Android.
+   *
+   * React Native's `<Image blurRadius={n} />` is roughly `blur: n / 2`.
+   *
+   * @default 0 (no blur)
+   */
+  blur?: number;
+  cache?: CacheOption;
+  cornerRadius?: number;
+};
 
-export interface NitroImagePipeline
-  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+export interface NitroImagePipeline extends HybridObject<{
+  ios: 'swift';
+  android: 'kotlin';
+}> {
   loadImage(url: string, options?: Options): Promise<Image>;
   preLoadImage(url: string): Promise<void>;
   preLoadImages(urls: string[]): Promise<void>;
+  /**
+   * Blurs an already-loaded image. `radius` is the standard deviation (sigma)
+   * of the Gaussian in **source-image pixels**, the same unit as
+   * {@linkcode Options.blur}.
+   */
   gaussianBlur(image: Image, radius: number): Promise<Image>;
   // Future: brightness, saturation, tint, etc.
 
-  clearCache(): void;
+  clearCache(): Promise<void>;
 }