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

package/ios/PipelineImageLoader.swift

@@ -0,0 +1,195 @@
+//
+//  PipelineImageLoader.swift
+//  NitroImagePipeline
+//
+
+import Foundation
+import NitroImage
+import NitroModules
+import Nuke
+import UIKit
+
+/// 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 a window and `dropImage` when it
+/// detaches. The load runs at the view's laid-out size (× screen scale) 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; this class converts them to the
+/// pixel-based `Options` of the shared request builder using the view's
+/// display scale, so cache keys match an equivalent `loadImage` call.
+class PipelineImageLoader: HybridImageLoaderSpec {
+    private let url: String
+    private let options: ViewOptions?
+
+    // 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 — every access happens inside a main-queue block.
+    private var tasks: [ObjectIdentifier: Task<Void, Never>] = [:]
+    private var pendingLayouts: [ObjectIdentifier: NSKeyValueObservation] = [:]
+
+    init(url: String, options: ViewOptions?) {
+        self.url = url
+        self.options = options
+    }
+
+    private var pipeline: ImagePipeline { HybridNitroImagePipeline.sharedPipeline }
+
+    /// visionOS has no `UIScreen.main`; there UIKit reports 2.0 as the
+    /// display scale of trait environments.
+    private static var fallbackScale: CGFloat {
+        #if os(visionOS)
+        return 2.0
+        #else
+        return UIScreen.main.scale
+        #endif
+    }
+
+    private static func displayScale(of view: UIView) -> CGFloat {
+        let scale = view.traitCollection.displayScale
+        // 0 means "unspecified" (view not in a hierarchy yet).
+        return scale > 0 ? scale : fallbackScale
+    }
+
+    /// The point-based `ViewOptions` as pixel-based `Options`, resolved
+    /// against `scale` and the target size in pixels.
+    private func pixelOptions(scale: CGFloat, sizePx: CGSize?) -> Options {
+        let cornerRadius = options?.cornerRadius.map { radius -> Variant_Double_CornerRadii in
+            switch radius {
+            case .first(let uniform):
+                return .first(uniform * scale)
+            case .second(let radii):
+                return .second(CornerRadii(
+                    topLeft: radii.topLeft.map { $0 * scale },
+                    topRight: radii.topRight.map { $0 * scale },
+                    bottomLeft: radii.bottomLeft.map { $0 * scale },
+                    bottomRight: radii.bottomRight.map { $0 * scale }
+                ))
+            }
+        }
+        return Options(
+            blur: options?.blur.map { $0 * scale },
+            cache: options?.cache,
+            cornerRadius: cornerRadius,
+            resize: sizePx.map { ResizeOptions(width: Double($0.width), height: Double($0.height)) }
+        )
+    }
+
+    /// An explicit `resize` override (pixels), when set and valid.
+    private var explicitResize: CGSize? {
+        guard let resize = options?.resize, resize.width > 0, resize.height > 0 else {
+            return nil
+        }
+        return CGSize(width: resize.width, height: resize.height)
+    }
+
+    // MARK: - ImageLoader
+
+    func loadImage() throws -> Promise<any HybridImageSpec> {
+        return Promise.async {
+            guard let imageUrl = URL(string: self.url) else {
+                throw RuntimeError.error(withMessage: "Invalid URL: \(self.url)")
+            }
+            // No view to measure here: use the explicit resize if given, and
+            // the main screen's scale for the point-based options.
+            let scale = await MainActor.run { Self.fallbackScale }
+            let request = HybridNitroImagePipeline.makeRequest(
+                url: imageUrl,
+                options: self.pixelOptions(scale: scale, sizePx: self.explicitResize)
+            )
+            let image = try await self.pipeline.image(for: request)
+            return HybridImage(uiImage: image)
+        }
+    }
+
+    func requestImage(forView view: any HybridNitroImageViewSpec) throws {
+        guard let nativeView = view as? NativeImageView else { return }
+        let key = ObjectIdentifier(view)
+        // Always hop (asynchronously) to main: `requestImage` fires while the
+        // view is being mounted, and only after the current mounting
+        // transaction finishes is its final frame guaranteed to be set.
+        DispatchQueue.main.async {
+            self.load(into: nativeView.imageView, key: key)
+        }
+    }
+
+    func dropImage(forView view: any HybridNitroImageViewSpec) throws {
+        guard let nativeView = view as? NativeImageView else { return }
+        let key = ObjectIdentifier(view)
+        // Same queue as `requestImage`, so rapid attach/detach sequences
+        // (list recycling) replay in call order.
+        DispatchQueue.main.async {
+            self.cancel(key: key)
+            nativeView.imageView.image = nil
+        }
+    }
+
+    // MARK: - Main-thread loading
+
+    private func cancel(key: ObjectIdentifier) {
+        tasks[key]?.cancel()
+        tasks[key] = nil
+        // Releasing the observation invalidates it.
+        pendingLayouts[key] = nil
+    }
+
+    private func load(into imageView: UIImageView, key: ObjectIdentifier) {
+        cancel(key: key)
+
+        if let sizePx = explicitResize {
+            start(into: imageView, key: key, sizePx: sizePx)
+            return
+        }
+
+        let bounds = imageView.bounds.size
+        if bounds.width > 0, bounds.height > 0 {
+            let scale = Self.displayScale(of: imageView)
+            start(into: imageView, key: key, sizePx: CGSize(
+                width: bounds.width * scale,
+                height: bounds.height * scale
+            ))
+        } else {
+            // Mounted at zero size (e.g. a flex child before its container
+            // grows): wait for real bounds. Observed on the layer — CALayer
+            // properties are KVO-compliant, UIView's are not.
+            pendingLayouts[key] = imageView.layer.observe(\.bounds) { [weak self, weak imageView] layer, _ in
+                guard layer.bounds.width > 0, layer.bounds.height > 0 else { return }
+                DispatchQueue.main.async {
+                    guard let self, let imageView else { return }
+                    guard self.pendingLayouts[key] != nil else { return }
+                    self.load(into: imageView, key: key)
+                }
+            }
+        }
+    }
+
+    private func start(into imageView: UIImageView, key: ObjectIdentifier, sizePx: CGSize) {
+        guard let imageUrl = URL(string: url) else { return }
+        let scale = Self.displayScale(of: imageView)
+        let request = HybridNitroImagePipeline.makeRequest(
+            url: imageUrl,
+            options: pixelOptions(scale: scale, sizePx: sizePx)
+        )
+        let pipeline = self.pipeline
+        // A memory-cache hit is served synchronously. Going through
+        // `pipeline.image(for:)` would resume on Nuke's queue and then hop
+        // back to the main actor, so a recycled cell (whose image `dropImage`
+        // just cleared) would show empty for a frame or two even though the
+        // bitmap is already in memory. The subscript honours the request's
+        // `.disableMemoryCacheReads`, so `cache: 'disk'`/`'none'` still miss.
+        if !request.options.contains(.disableMemoryCacheReads), let cached = pipeline.cache[request] {
+            imageView.image = cached.image
+            return
+        }
+        // Cancelling the Task cancels Nuke's request; a finished task stays in
+        // the map (cancelling it is a no-op) until `cancel` replaces it.
+        tasks[key] = Task { @MainActor [weak imageView] in
+            guard let image = try? await pipeline.image(for: request) else { return }
+            guard !Task.isCancelled else { return }
+            imageView?.image = image
+        }
+    }
+}

package/ios/RoundedCornersProcessor.swift

@@ -48,6 +48,11 @@ struct RoundedCornersProcessor: ImageProcessing {
         let format = UIGraphicsImageRendererFormat()
         format.scale = image.scale
         format.opaque = false
+        // `.automatic` picks the extended (16-bit-per-channel) range on
+        // wide-gamut displays, which doubles the bytes of this bitmap — the
+        // one that ends up in the memory cache and on screen — for an 8-bit
+        // sRGB source that gains nothing from it.
+        format.preferredRange = .standard
 
         let rect = CGRect(origin: .zero, size: size)
         return UIGraphicsImageRenderer(size: size, format: format).image { context in

package/lib/commonjs/NativePipelineImage.js

@@ -0,0 +1,71 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NativePipelineImage = void 0;
+var _react = require("react");
+var _reactNativeNitroImage = require("react-native-nitro-image");
+var _resizeForStyle = require("./resizeForStyle");
+var _usePipelineImageLoader = require("./usePipelineImageLoader");
+var _jsxRuntime = require("react/jsx-runtime");
+/**
+ * The instance `<NativePipelineImage>` exposes through its `ref` — the
+ * underlying `NativeNitroImage` host view, with the usual native-view
+ * methods (`measure`, …).
+ */
+
+/**
+ * The fully native-driven variant of `PipelineImage`: after the first render
+ * there is **zero JS work per image**. The native view starts the request
+ * when it attaches to the window — at its own laid-out size, so nothing
+ * waits for an `onLayout` round trip — and cancels it (releasing the bitmap)
+ * when it detaches, which makes off-screen list cells free. Loads go through
+ * 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.
+ * - 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
+ * ```tsx
+ * <NativePipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200, borderRadius: 24 }}
+ *   blur={4}
+ * />
+ * ```
+ */
+const NativePipelineImage = exports.NativePipelineImage = /*#__PURE__*/(0, _react.forwardRef)(function NativePipelineImage({
+  url,
+  blur,
+  cornerRadius,
+  cache,
+  resize,
+  style,
+  ...viewProps
+}, ref) {
+  // Same precedence as PipelineImage: an explicit prop wins over style.
+  const effectiveCornerRadius = cornerRadius ?? (0, _resizeForStyle.cornerRadiusForStyle)(style);
+  const loader = (0, _usePipelineImageLoader.usePipelineImageLoader)(url, {
+    blur,
+    cornerRadius: effectiveCornerRadius,
+    cache,
+    resize
+  });
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeNitroImage.NativeNitroImage
+  // Before the spread so a caller-provided recyclingKey wins.
+  , {
+    recyclingKey: url,
+    ...viewProps,
+    ref: ref,
+    style: style,
+    image: loader
+  });
+});
+
+// Reanimated and DevTools read the display name; the forwardRef wrapper
+// would otherwise report as anonymous.
+NativePipelineImage.displayName = 'NativePipelineImage';
+//# sourceMappingURL=NativePipelineImage.js.map

package/lib/commonjs/NativePipelineImage.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_reactNativeNitroImage","_resizeForStyle","_usePipelineImageLoader","_jsxRuntime","NativePipelineImage","exports","forwardRef","url","blur","cornerRadius","cache","resize","style","viewProps","ref","effectiveCornerRadius","cornerRadiusForStyle","loader","usePipelineImageLoader","jsx","NativeNitroImage","recyclingKey","image","displayName"],"sourceRoot":"../../src","sources":["NativePipelineImage.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAEA,IAAAC,sBAAA,GAAAD,OAAA;AAEA,IAAAE,eAAA,GAAAF,OAAA;AAMA,IAAAG,uBAAA,GAAAH,OAAA;AAAkE,IAAAI,WAAA,GAAAJ,OAAA;AAKlE;AACA;AACA;AACA;AACA;;AA+BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMK,mBAAmB,GAAAC,OAAA,CAAAD,mBAAA,gBAAG,IAAAE,iBAAU,EAG3C,SAASF,mBAAmBA,CAC5B;EAAEG,GAAG;EAAEC,IAAI;EAAEC,YAAY;EAAEC,KAAK;EAAEC,MAAM;EAAEC,KAAK;EAAE,GAAGC;AAAU,CAAC,EAC/DC,GAAG,EACH;EACA;EACA,MAAMC,qBAAqB,GAAGN,YAAY,IAAI,IAAAO,oCAAoB,EAACJ,KAAK,CAAC;EACzE,MAAMK,MAAM,GAAG,IAAAC,8CAAsB,EAACX,GAAG,EAAE;IACzCC,IAAI;IACJC,YAAY,EAAEM,qBAAqB;IACnCL,KAAK;IACLC;EACF,CAAC,CAAC;EAEF,oBACE,IAAAR,WAAA,CAAAgB,GAAA,EAACnB,sBAAA,CAAAoB;EACC;EAAA;IACAC,YAAY,EAAEd,GAAI;IAAA,GACdM,SAAS;IACbC,GAAG,EAAEA,GAAI;IACTF,KAAK,EAAEA,KAAM;IACbU,KAAK,EAAEL;EAAO,CACf,CAAC;AAEN,CAAC,CAAC;;AAEF;AACA;AACAb,mBAAmB,CAACmB,WAAW,GAAG,qBAAqB","ignoreList":[]}

package/lib/commonjs/index.js

@@ -3,6 +3,12 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "NativePipelineImage", {
+  enumerable: true,
+  get: function () {
+    return _NativePipelineImage.NativePipelineImage;
+  }
+});
 Object.defineProperty(exports, "NitroImagePipeline", {
   enumerable: true,
   get: function () {
@@ -39,8 +45,16 @@ Object.defineProperty(exports, "useImage", {
     return _useImage.useImage;
   }
 });
+Object.defineProperty(exports, "usePipelineImageLoader", {
+  enumerable: true,
+  get: function () {
+    return _usePipelineImageLoader.usePipelineImageLoader;
+  }
+});
+var _NativePipelineImage = require("./NativePipelineImage");
 var _NitroImagePipeline = require("./NitroImagePipeline");
 var _PipelineImage = require("./PipelineImage");
 var _resizeForStyle = require("./resizeForStyle");
 var _useImage = require("./useImage");
+var _usePipelineImageLoader = require("./usePipelineImageLoader");
 //# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_NitroImagePipeline","require","_PipelineImage","_resizeForStyle","_useImage"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,mBAAA,GAAAC,OAAA;AACA,IAAAC,cAAA,GAAAD,OAAA;AAKA,IAAAE,eAAA,GAAAF,OAAA;AAWA,IAAAG,SAAA,GAAAH,OAAA","ignoreList":[]}
+{"version":3,"names":["_NativePipelineImage","require","_NitroImagePipeline","_PipelineImage","_resizeForStyle","_useImage","_usePipelineImageLoader"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,oBAAA,GAAAC,OAAA;AAKA,IAAAC,mBAAA,GAAAD,OAAA;AACA,IAAAE,cAAA,GAAAF,OAAA;AAKA,IAAAG,eAAA,GAAAH,OAAA;AAYA,IAAAI,SAAA,GAAAJ,OAAA;AACA,IAAAK,uBAAA,GAAAL,OAAA","ignoreList":[]}

package/lib/commonjs/usePipelineImageLoader.js

@@ -0,0 +1,69 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePipelineImageLoader = usePipelineImageLoader;
+var _react = require("react");
+var _NitroImagePipeline = require("./NitroImagePipeline");
+/**
+ * Creates (and memoizes) an {@linkcode ImageLoader} for `url` to pass to
+ * `<NativeNitroImage image={...} />`. The view drives it entirely natively:
+ * the request starts when the view attaches — at the view's laid-out size,
+ * with no JS round trips — and is cancelled when it detaches. See
+ * {@linkcode NitroImagePipeline.createImageLoader}.
+ *
+ * `blur`/`cornerRadius` are in **points** (unlike `useImage`, where they are
+ * bitmap pixels); the screen scale is applied natively. Inline object
+ * literals are fine — options are compared by value, not identity.
+ */
+function usePipelineImageLoader(url, options) {
+  // Split the options into primitives (like useImage does) so an inline
+  // literal — a new identity every render — doesn't recreate the loader;
+  // recreating it would re-trigger the native load.
+  const blur = options?.blur;
+  const cache = options?.cache;
+  const cornerRadius = options?.cornerRadius;
+  const isUniformRadius = typeof cornerRadius === 'number';
+  const uniformRadius = isUniformRadius ? cornerRadius : 0;
+  const hasCornerObject = !isUniformRadius && cornerRadius !== undefined;
+  const {
+    topLeft = 0,
+    topRight = 0,
+    bottomLeft = 0,
+    bottomRight = 0
+  } = isUniformRadius || cornerRadius === undefined ? {} : cornerRadius;
+  const resizeWidth = options?.resize?.width;
+  const resizeHeight = options?.resize?.height;
+  return (0, _react.useMemo)(() => {
+    const cornerRadiusOption = isUniformRadius ? uniformRadius : hasCornerObject ? {
+      topLeft,
+      topRight,
+      bottomLeft,
+      bottomRight
+    } : undefined;
+    const stableOptions = {
+      blur,
+      cache,
+      cornerRadius: cornerRadiusOption,
+      resize: resizeWidth !== undefined && resizeHeight !== undefined ? {
+        width: resizeWidth,
+        height: resizeHeight
+      } : undefined
+    };
+    const loader = _NitroImagePipeline.NitroImagePipeline.createImageLoader(url, stableOptions);
+    // `NativeNitroImage` needs a way to tell two loader instances apart when
+    // diffing its `image` prop; tag the loader with what it will load (the
+    // same convention react-native-nitro-image's own loaders use).
+    Object.defineProperty(loader, '__source', {
+      enumerable: true,
+      configurable: true,
+      value: {
+        url,
+        options: stableOptions
+      }
+    });
+    return loader;
+  }, [url, blur, cache, isUniformRadius, uniformRadius, hasCornerObject, topLeft, topRight, bottomLeft, bottomRight, resizeWidth, resizeHeight]);
+}
+//# sourceMappingURL=usePipelineImageLoader.js.map

package/lib/commonjs/usePipelineImageLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_NitroImagePipeline","usePipelineImageLoader","url","options","blur","cache","cornerRadius","isUniformRadius","uniformRadius","hasCornerObject","undefined","topLeft","topRight","bottomLeft","bottomRight","resizeWidth","resize","width","resizeHeight","height","useMemo","cornerRadiusOption","stableOptions","loader","NitroImagePipeline","createImageLoader","Object","defineProperty","enumerable","configurable","value"],"sourceRoot":"../../src","sources":["usePipelineImageLoader.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAGA,IAAAC,mBAAA,GAAAD,OAAA;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,sBAAsBA,CACpCC,GAAW,EACXC,OAAqB,EACR;EACb;EACA;EACA;EACA,MAAMC,IAAI,GAAGD,OAAO,EAAEC,IAAI;EAC1B,MAAMC,KAAK,GAAGF,OAAO,EAAEE,KAAK;EAC5B,MAAMC,YAAY,GAAGH,OAAO,EAAEG,YAAY;EAC1C,MAAMC,eAAe,GAAG,OAAOD,YAAY,KAAK,QAAQ;EACxD,MAAME,aAAa,GAAGD,eAAe,GAAGD,YAAY,GAAG,CAAC;EACxD,MAAMG,eAAe,GAAG,CAACF,eAAe,IAAID,YAAY,KAAKI,SAAS;EACtE,MAAM;IACJC,OAAO,GAAG,CAAC;IACXC,QAAQ,GAAG,CAAC;IACZC,UAAU,GAAG,CAAC;IACdC,WAAW,GAAG;EAChB,CAAC,GAAGP,eAAe,IAAID,YAAY,KAAKI,SAAS,GAAG,CAAC,CAAC,GAAGJ,YAAY;EACrE,MAAMS,WAAW,GAAGZ,OAAO,EAAEa,MAAM,EAAEC,KAAK;EAC1C,MAAMC,YAAY,GAAGf,OAAO,EAAEa,MAAM,EAAEG,MAAM;EAE5C,OAAO,IAAAC,cAAO,EAAC,MAAM;IACnB,MAAMC,kBAAoD,GAAGd,eAAe,GACxEC,aAAa,GACbC,eAAe,GACb;MAAEE,OAAO;MAAEC,QAAQ;MAAEC,UAAU;MAAEC;IAAY,CAAC,GAC9CJ,SAAS;IACf,MAAMY,aAA0B,GAAG;MACjClB,IAAI;MACJC,KAAK;MACLC,YAAY,EAAEe,kBAAkB;MAChCL,MAAM,EACJD,WAAW,KAAKL,SAAS,IAAIQ,YAAY,KAAKR,SAAS,GACnD;QAAEO,KAAK,EAAEF,WAAW;QAAEI,MAAM,EAAED;MAAa,CAAC,GAC5CR;IACR,CAAC;IACD,MAAMa,MAAM,GAAGC,sCAAkB,CAACC,iBAAiB,CAACvB,GAAG,EAAEoB,aAAa,CAAC;IACvE;IACA;IACA;IACAI,MAAM,CAACC,cAAc,CAACJ,MAAM,EAAE,UAAU,EAAE;MACxCK,UAAU,EAAE,IAAI;MAChBC,YAAY,EAAE,IAAI;MAClBC,KAAK,EAAE;QAAE5B,GAAG;QAAEC,OAAO,EAAEmB;MAAc;IACvC,CAAC,CAAC;IACF,OAAOC,MAAM;EACf,CAAC,EAAE,CACDrB,GAAG,EACHE,IAAI,EACJC,KAAK,EACLE,eAAe,EACfC,aAAa,EACbC,eAAe,EACfE,OAAO,EACPC,QAAQ,EACRC,UAAU,EACVC,WAAW,EACXC,WAAW,EACXG,YAAY,CACb,CAAC;AACJ","ignoreList":[]}

package/lib/module/NativePipelineImage.js

@@ -0,0 +1,67 @@
+"use strict";
+
+import { forwardRef } from 'react';
+import { NativeNitroImage } from 'react-native-nitro-image';
+import { cornerRadiusForStyle } from './resizeForStyle';
+import { usePipelineImageLoader } from './usePipelineImageLoader';
+
+/**
+ * The instance `<NativePipelineImage>` exposes through its `ref` — the
+ * underlying `NativeNitroImage` host view, with the usual native-view
+ * methods (`measure`, …).
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The fully native-driven variant of `PipelineImage`: after the first render
+ * there is **zero JS work per image**. The native view starts the request
+ * when it attaches to the window — at its own laid-out size, so nothing
+ * waits for an `onLayout` round trip — and cancels it (releasing the bitmap)
+ * when it detaches, which makes off-screen list cells free. Loads go through
+ * 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.
+ * - 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
+ * ```tsx
+ * <NativePipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200, borderRadius: 24 }}
+ *   blur={4}
+ * />
+ * ```
+ */
+export const NativePipelineImage = /*#__PURE__*/forwardRef(function NativePipelineImage({
+  url,
+  blur,
+  cornerRadius,
+  cache,
+  resize,
+  style,
+  ...viewProps
+}, ref) {
+  // Same precedence as PipelineImage: an explicit prop wins over style.
+  const effectiveCornerRadius = cornerRadius ?? cornerRadiusForStyle(style);
+  const loader = usePipelineImageLoader(url, {
+    blur,
+    cornerRadius: effectiveCornerRadius,
+    cache,
+    resize
+  });
+  return /*#__PURE__*/_jsx(NativeNitroImage
+  // Before the spread so a caller-provided recyclingKey wins.
+  , {
+    recyclingKey: url,
+    ...viewProps,
+    ref: ref,
+    style: style,
+    image: loader
+  });
+});
+
+// Reanimated and DevTools read the display name; the forwardRef wrapper
+// would otherwise report as anonymous.
+NativePipelineImage.displayName = 'NativePipelineImage';
+//# sourceMappingURL=NativePipelineImage.js.map

package/lib/module/NativePipelineImage.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["forwardRef","NativeNitroImage","cornerRadiusForStyle","usePipelineImageLoader","jsx","_jsx","NativePipelineImage","url","blur","cornerRadius","cache","resize","style","viewProps","ref","effectiveCornerRadius","loader","recyclingKey","image","displayName"],"sourceRoot":"../../src","sources":["NativePipelineImage.tsx"],"mappings":";;AAAA,SAA4BA,UAAU,QAAQ,OAAO;AAErD,SAASC,gBAAgB,QAAQ,0BAA0B;AAE3D,SAASC,oBAAoB,QAAQ,kBAAkB;AAMvD,SAASC,sBAAsB,QAAQ,0BAA0B;;AAKjE;AACA;AACA;AACA;AACA;AAJA,SAAAC,GAAA,IAAAC,IAAA;AAmCA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,mBAAmB,gBAAGN,UAAU,CAG3C,SAASM,mBAAmBA,CAC5B;EAAEC,GAAG;EAAEC,IAAI;EAAEC,YAAY;EAAEC,KAAK;EAAEC,MAAM;EAAEC,KAAK;EAAE,GAAGC;AAAU,CAAC,EAC/DC,GAAG,EACH;EACA;EACA,MAAMC,qBAAqB,GAAGN,YAAY,IAAIP,oBAAoB,CAACU,KAAK,CAAC;EACzE,MAAMI,MAAM,GAAGb,sBAAsB,CAACI,GAAG,EAAE;IACzCC,IAAI;IACJC,YAAY,EAAEM,qBAAqB;IACnCL,KAAK;IACLC;EACF,CAAC,CAAC;EAEF,oBACEN,IAAA,CAACJ;EACC;EAAA;IACAgB,YAAY,EAAEV,GAAI;IAAA,GACdM,SAAS;IACbC,GAAG,EAAEA,GAAI;IACTF,KAAK,EAAEA,KAAM;IACbM,KAAK,EAAEF;EAAO,CACf,CAAC;AAEN,CAAC,CAAC;;AAEF;AACA;AACAV,mBAAmB,CAACa,WAAW,GAAG,qBAAqB","ignoreList":[]}

package/lib/module/index.js

@@ -1,7 +1,9 @@
 "use strict";
 
+export { NativePipelineImage } from './NativePipelineImage';
 export { NitroImagePipeline } from './NitroImagePipeline';
 export { PipelineImage } from './PipelineImage';
 export { cornerRadiusForStyle, resizeForLayout, resizeForStyle } from './resizeForStyle';
 export { useImage } from './useImage';
+export { usePipelineImageLoader } from './usePipelineImageLoader';
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["NitroImagePipeline","PipelineImage","cornerRadiusForStyle","resizeForLayout","resizeForStyle","useImage"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SAASA,kBAAkB,QAAQ,sBAAsB;AACzD,SACEC,aAAa,QAGR,iBAAiB;AACxB,SACEC,oBAAoB,EACpBC,eAAe,EACfC,cAAc,QACT,kBAAkB;AAOzB,SAASC,QAAQ,QAAQ,YAAY","ignoreList":[]}
+{"version":3,"names":["NativePipelineImage","NitroImagePipeline","PipelineImage","cornerRadiusForStyle","resizeForLayout","resizeForStyle","useImage","usePipelineImageLoader"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SACEA,mBAAmB,QAGd,uBAAuB;AAC9B,SAASC,kBAAkB,QAAQ,sBAAsB;AACzD,SACEC,aAAa,QAGR,iBAAiB;AACxB,SACEC,oBAAoB,EACpBC,eAAe,EACfC,cAAc,QACT,kBAAkB;AAQzB,SAASC,QAAQ,QAAQ,YAAY;AACrC,SAASC,sBAAsB,QAAQ,0BAA0B","ignoreList":[]}

package/lib/module/usePipelineImageLoader.js

@@ -0,0 +1,65 @@
+"use strict";
+
+import { useMemo } from 'react';
+import { NitroImagePipeline } from './NitroImagePipeline';
+/**
+ * Creates (and memoizes) an {@linkcode ImageLoader} for `url` to pass to
+ * `<NativeNitroImage image={...} />`. The view drives it entirely natively:
+ * the request starts when the view attaches — at the view's laid-out size,
+ * with no JS round trips — and is cancelled when it detaches. See
+ * {@linkcode NitroImagePipeline.createImageLoader}.
+ *
+ * `blur`/`cornerRadius` are in **points** (unlike `useImage`, where they are
+ * bitmap pixels); the screen scale is applied natively. Inline object
+ * literals are fine — options are compared by value, not identity.
+ */
+export function usePipelineImageLoader(url, options) {
+  // Split the options into primitives (like useImage does) so an inline
+  // literal — a new identity every render — doesn't recreate the loader;
+  // recreating it would re-trigger the native load.
+  const blur = options?.blur;
+  const cache = options?.cache;
+  const cornerRadius = options?.cornerRadius;
+  const isUniformRadius = typeof cornerRadius === 'number';
+  const uniformRadius = isUniformRadius ? cornerRadius : 0;
+  const hasCornerObject = !isUniformRadius && cornerRadius !== undefined;
+  const {
+    topLeft = 0,
+    topRight = 0,
+    bottomLeft = 0,
+    bottomRight = 0
+  } = isUniformRadius || cornerRadius === undefined ? {} : cornerRadius;
+  const resizeWidth = options?.resize?.width;
+  const resizeHeight = options?.resize?.height;
+  return useMemo(() => {
+    const cornerRadiusOption = isUniformRadius ? uniformRadius : hasCornerObject ? {
+      topLeft,
+      topRight,
+      bottomLeft,
+      bottomRight
+    } : undefined;
+    const stableOptions = {
+      blur,
+      cache,
+      cornerRadius: cornerRadiusOption,
+      resize: resizeWidth !== undefined && resizeHeight !== undefined ? {
+        width: resizeWidth,
+        height: resizeHeight
+      } : undefined
+    };
+    const loader = NitroImagePipeline.createImageLoader(url, stableOptions);
+    // `NativeNitroImage` needs a way to tell two loader instances apart when
+    // diffing its `image` prop; tag the loader with what it will load (the
+    // same convention react-native-nitro-image's own loaders use).
+    Object.defineProperty(loader, '__source', {
+      enumerable: true,
+      configurable: true,
+      value: {
+        url,
+        options: stableOptions
+      }
+    });
+    return loader;
+  }, [url, blur, cache, isUniformRadius, uniformRadius, hasCornerObject, topLeft, topRight, bottomLeft, bottomRight, resizeWidth, resizeHeight]);
+}
+//# sourceMappingURL=usePipelineImageLoader.js.map

package/lib/module/usePipelineImageLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useMemo","NitroImagePipeline","usePipelineImageLoader","url","options","blur","cache","cornerRadius","isUniformRadius","uniformRadius","hasCornerObject","undefined","topLeft","topRight","bottomLeft","bottomRight","resizeWidth","resize","width","resizeHeight","height","cornerRadiusOption","stableOptions","loader","createImageLoader","Object","defineProperty","enumerable","configurable","value"],"sourceRoot":"../../src","sources":["usePipelineImageLoader.ts"],"mappings":";;AAAA,SAASA,OAAO,QAAQ,OAAO;AAG/B,SAASC,kBAAkB,QAAQ,sBAAsB;AAMzD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,sBAAsBA,CACpCC,GAAW,EACXC,OAAqB,EACR;EACb;EACA;EACA;EACA,MAAMC,IAAI,GAAGD,OAAO,EAAEC,IAAI;EAC1B,MAAMC,KAAK,GAAGF,OAAO,EAAEE,KAAK;EAC5B,MAAMC,YAAY,GAAGH,OAAO,EAAEG,YAAY;EAC1C,MAAMC,eAAe,GAAG,OAAOD,YAAY,KAAK,QAAQ;EACxD,MAAME,aAAa,GAAGD,eAAe,GAAGD,YAAY,GAAG,CAAC;EACxD,MAAMG,eAAe,GAAG,CAACF,eAAe,IAAID,YAAY,KAAKI,SAAS;EACtE,MAAM;IACJC,OAAO,GAAG,CAAC;IACXC,QAAQ,GAAG,CAAC;IACZC,UAAU,GAAG,CAAC;IACdC,WAAW,GAAG;EAChB,CAAC,GAAGP,eAAe,IAAID,YAAY,KAAKI,SAAS,GAAG,CAAC,CAAC,GAAGJ,YAAY;EACrE,MAAMS,WAAW,GAAGZ,OAAO,EAAEa,MAAM,EAAEC,KAAK;EAC1C,MAAMC,YAAY,GAAGf,OAAO,EAAEa,MAAM,EAAEG,MAAM;EAE5C,OAAOpB,OAAO,CAAC,MAAM;IACnB,MAAMqB,kBAAoD,GAAGb,eAAe,GACxEC,aAAa,GACbC,eAAe,GACb;MAAEE,OAAO;MAAEC,QAAQ;MAAEC,UAAU;MAAEC;IAAY,CAAC,GAC9CJ,SAAS;IACf,MAAMW,aAA0B,GAAG;MACjCjB,IAAI;MACJC,KAAK;MACLC,YAAY,EAAEc,kBAAkB;MAChCJ,MAAM,EACJD,WAAW,KAAKL,SAAS,IAAIQ,YAAY,KAAKR,SAAS,GACnD;QAAEO,KAAK,EAAEF,WAAW;QAAEI,MAAM,EAAED;MAAa,CAAC,GAC5CR;IACR,CAAC;IACD,MAAMY,MAAM,GAAGtB,kBAAkB,CAACuB,iBAAiB,CAACrB,GAAG,EAAEmB,aAAa,CAAC;IACvE;IACA;IACA;IACAG,MAAM,CAACC,cAAc,CAACH,MAAM,EAAE,UAAU,EAAE;MACxCI,UAAU,EAAE,IAAI;MAChBC,YAAY,EAAE,IAAI;MAClBC,KAAK,EAAE;QAAE1B,GAAG;QAAEC,OAAO,EAAEkB;MAAc;IACvC,CAAC,CAAC;IACF,OAAOC,MAAM;EACf,CAAC,EAAE,CACDpB,GAAG,EACHE,IAAI,EACJC,KAAK,EACLE,eAAe,EACfC,aAAa,EACbC,eAAe,EACfE,OAAO,EACPC,QAAQ,EACRC,UAAU,EACVC,WAAW,EACXC,WAAW,EACXG,YAAY,CACb,CAAC;AACJ","ignoreList":[]}

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

@@ -0,0 +1,66 @@
+import { type ComponentRef } from 'react';
+import type { HostComponent } from 'react-native';
+import { NativeNitroImage } from 'react-native-nitro-image';
+import type { CacheOption, CornerRadii, ResizeOptions } from './specs/nitro-image-toolkit.nitro';
+type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
+type NativeImageProps = ReactProps<typeof NativeNitroImage>;
+/**
+ * The instance `<NativePipelineImage>` exposes through its `ref` — the
+ * underlying `NativeNitroImage` host view, with the usual native-view
+ * methods (`measure`, …).
+ */
+export type NativePipelineImageRef = ComponentRef<typeof NativeNitroImage>;
+export interface NativePipelineImageProps extends Omit<NativeImageProps, 'image'> {
+    /** URL of the image to load through the pipeline. */
+    url: string;
+    /**
+     * Gaussian blur sigma in **points** (density-independent), like
+     * `PipelineImage`. Applied natively with the screen scale.
+     * @default 0
+     */
+    blur?: number;
+    /**
+     * Corner radius in **points** — a single number or per-corner radii.
+     * When omitted, it's derived from `style`'s `borderRadius`-family
+     * properties instead — set this prop to override that.
+     * @default undefined (derived from `style`, or square corners if unset there)
+     */
+    cornerRadius?: number | CornerRadii;
+    cache?: CacheOption;
+    /**
+     * Target bitmap size in **pixels**, overriding the size the native side
+     * measures from the view. Rarely needed.
+     * @default undefined (measure the view natively)
+     */
+    resize?: ResizeOptions;
+}
+/**
+ * The fully native-driven variant of `PipelineImage`: after the first render
+ * there is **zero JS work per image**. The native view starts the request
+ * when it attaches to the window — at its own laid-out size, so nothing
+ * waits for an `onLayout` round trip — and cancels it (releasing the bitmap)
+ * when it detaches, which makes off-screen list cells free. Loads go through
+ * 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.
+ * - 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
+ * ```tsx
+ * <NativePipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200, borderRadius: 24 }}
+ *   blur={4}
+ * />
+ * ```
+ */
+export declare const NativePipelineImage: import("react").ForwardRefExoticComponent<NativePipelineImageProps & import("react").RefAttributes<import("react").Component<{
+    hybridRef?: import("react-native-nitro-modules").NitroViewWrappedCallback<((ref: import("react-native-nitro-modules").HybridView<import("react-native-nitro-image/lib/typescript/specs/ImageView.nitro").NativeNitroImageViewProps, import("react-native-nitro-image/lib/typescript/specs/ImageView.nitro").NativeNitroImageViewMethods>) => void) | undefined> | undefined;
+    image?: import("react-native-nitro-image").Image | import("react-native-nitro-image").ImageLoader;
+    resizeMode?: import("react-native-nitro-image/lib/typescript/specs/ImageView.nitro").ResizeMode;
+    recyclingKey?: string;
+} & import("react-native").ViewProps, {}, any> & import("react-native").ReactNativeElement>>;
+export {};
+//# sourceMappingURL=NativePipelineImage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NativePipelineImage.d.ts","sourceRoot":"","sources":["../../../src/NativePipelineImage.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAc,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACd,MAAM,mCAAmC,CAAC;AAG3C,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAClE,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE3E,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,gBAAgB,EAChB,OAAO,CACR;IACC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB;;;;;4FA0B9B,CAAC"}

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

@@ -1,6 +1,8 @@
+export { NativePipelineImage, type NativePipelineImageProps, type NativePipelineImageRef, } from './NativePipelineImage';
 export { NitroImagePipeline } from './NitroImagePipeline';
 export { PipelineImage, type PipelineImageProps, type PipelineImageRef, } from './PipelineImage';
 export { cornerRadiusForStyle, resizeForLayout, resizeForStyle, } from './resizeForStyle';
-export type { CacheOption, CornerRadii, Options, ResizeOptions, } from './specs/nitro-image-toolkit.nitro';
+export type { CacheOption, CornerRadii, Options, ResizeOptions, ViewOptions, } from './specs/nitro-image-toolkit.nitro';
 export { useImage } from './useImage';
+export { usePipelineImageLoader } from './usePipelineImageLoader';
 //# 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":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,aAAa,GACd,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,aAAa,EACb,WAAW,GACZ,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}