react-native-nitro-image-pipeline 1.2.0 → 1.3.1

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

@@ -0,0 +1,73 @@
+import { type ComponentRef } from 'react';
+import { type HostComponent } from 'react-native';
+import { type Image, NativeNitroImage } from 'react-native-nitro-image';
+import type { CacheOption, CornerRadii } from './specs/nitro-image-toolkit.nitro';
+type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
+type NativeImageProps = ReactProps<typeof NativeNitroImage>;
+/**
+ * The instance `<PipelineImage>` exposes through its `ref` — the underlying
+ * `NativeNitroImage` host view, with the usual native-view methods
+ * (`measure`, …).
+ */
+export type PipelineImageRef = ComponentRef<typeof NativeNitroImage>;
+export interface PipelineImageProps extends Omit<NativeImageProps, 'image'> {
+    /** URL of the image to load through the pipeline. */
+    url: string;
+    /**
+     * Gaussian blur sigma in **points** (density-independent). Unlike
+     * `useImage`/`loadImage`, where it is bitmap pixels, the component
+     * multiplies it by `PixelRatio.get()` so the same value looks the same on
+     * every device.
+     * @default 0
+     */
+    blur?: number;
+    /**
+     * Corner radius in **points** — a single number or per-corner radii.
+     * Converted to bitmap pixels with `PixelRatio.get()` and baked into the
+     * bitmap at the display size.
+     *
+     * When omitted, it's derived from `style`'s `borderRadius` /
+     * `borderTopLeftRadius` / `borderTopRightRadius` / `borderBottomLeftRadius`
+     * / `borderBottomRightRadius` instead — set this prop to override that.
+     * @default undefined (derived from `style`, or square corners if unset there)
+     */
+    cornerRadius?: number | CornerRadii;
+    cache?: CacheOption;
+    /** Called with the processed `Image` each time a new variant resolves. */
+    onLoad?: (image: Image) => void;
+    /** Called when loading fails. */
+    onError?: (error: Error) => void;
+}
+/**
+ * A `NativeNitroImage` that loads `url` through the pipeline at exactly the
+ * size it is displayed: the bitmap is resized to the view's size in points ×
+ * `PixelRatio.get()`, so `blur` and `cornerRadius` (both in points here) apply
+ * 1:1 to what is on screen and large sources are never decoded at full size.
+ *
+ * A numeric `width`/`height` in `style` starts loading immediately; otherwise
+ * (`'50%'`, `flex`, `aspectRatio`, …) loading waits for the first `onLayout`.
+ * If the layout size later changes, a new variant is loaded and swapped in
+ * without flashing. Without an explicit `cornerRadius` prop, `style`'s
+ * `borderRadius`-family properties are baked into the bitmap instead — no
+ * separate view-layer rounding needed.
+ *
+ * The `ref` is forwarded to the underlying `NativeNitroImage` host view, so
+ * the component works with `Animated.createAnimatedComponent` (Reanimated or
+ * React Native's built-in `Animated`).
+ * @example
+ * ```tsx
+ * <PipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200 }}
+ *   cornerRadius={24}
+ * />
+ * ```
+ */
+export declare const PipelineImage: import("react").ForwardRefExoticComponent<PipelineImageProps & 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?: 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=PipelineImage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PipelineImage.d.ts","sourceRoot":"","sources":["../../../src/PipelineImage.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EAKlB,MAAM,OAAO,CAAC;AACf,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAOxE,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EAEZ,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,gBAAgB,GAAG,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAErE,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACzE,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,iCAAiC;IACjC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa;;;;;4FAqEzB,CAAC"}

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

@@ -1,46 +1,6 @@
-import type { Image } from 'react-native-nitro-image';
-import type { CacheOption, CornerRadii, NitroImagePipeline as NitroImagePipelineSpec, Options, ResizeOptions } from './specs/nitro-image-toolkit.nitro';
-export type { CacheOption, CornerRadii, Options, ResizeOptions };
-export declare const NitroImagePipeline: NitroImagePipelineSpec;
-type Result = {
-    image: undefined;
-    error: undefined;
-} | {
-    image: Image;
-    error: undefined;
-} | {
-    image: undefined;
-    error: Error;
-};
-/**
- * A hook to asynchronously load an image from the
- * given {@linkcode AsyncImageSource} into memory.
- * @example
- * ```ts
- * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
- * ```
- */
-export declare function useImage({ url, blur, cornerRadius, resize, cache, }: {
-    url: string;
-    /**
-     * Gaussian blur strength, as the standard deviation (sigma) of the blur in
-     * source-image pixels (of the resized bitmap when `resize` is set). Matches
-     * across iOS and Android; roughly half of React Native's `blurRadius`.
-     */
-    blur?: number;
-    /**
-     * Corner radius in pixels of the loaded bitmap. Pass a single number for
-     * uniform rounding, or per-corner radii (inline object literals are fine —
-     * the hook compares the radii by value, not identity). Pair with `resize`
-     * so the radii apply at the size you display instead of the source size.
-     */
-    cornerRadius?: number | CornerRadii;
-    /**
-     * Resize the bitmap to exactly this size in pixels (aspect-fill,
-     * center-crop) before blur/rounding. Typically your display size in points
-     * multiplied by `PixelRatio.get()`. Inline object literals are fine.
-     */
-    resize?: ResizeOptions;
-    cache?: CacheOption;
-}): Result;
+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 { useImage } from './useImage';
 //# 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,EACV,WAAW,EACX,WAAW,EACX,kBAAkB,IAAI,sBAAsB,EAC5C,OAAO,EACP,aAAa,EACd,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;AAEjE,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,MAAM,EACN,KAAK,GACN,EAAE;IACD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,GAAG,MAAM,CAyET"}
+{"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"}

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

@@ -0,0 +1,30 @@
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { CornerRadii, ResizeOptions } from './specs/nitro-image-toolkit.nitro';
+/**
+ * Converts a layout size in points (dp) to the pipeline's `resize` option in
+ * whole bitmap pixels using `PixelRatio.getPixelSizeForLayoutSize`. Returns
+ * `undefined` unless both values are positive numbers.
+ */
+export declare function resizeForLayout(width: unknown, height: unknown): ResizeOptions | undefined;
+/**
+ * Derives the pipeline's `resize` option from a view style whose `width` and
+ * `height` are numeric points, so the bitmap matches the display size on
+ * every screen density:
+ * ```ts
+ * useImage({ url, resize: resizeForStyle(styles.image) });
+ * ```
+ * Arrays and registered styles are flattened. Returns `undefined` when either
+ * dimension is missing or not a number (`'50%'`, `'auto'`, flex-driven) —
+ * use `<PipelineImage>` for those, which measures the view instead.
+ */
+export declare function resizeForStyle(style: StyleProp<ViewStyle>): ResizeOptions | undefined;
+/**
+ * Derives a `cornerRadius` option from a view style's `borderRadius` /
+ * `borderTopLeftRadius` / `borderTopRightRadius` / `borderBottomLeftRadius` /
+ * `borderBottomRightRadius`, in points. Per-corner properties override
+ * `borderRadius` for that corner; a corner with neither set stays square.
+ * Non-numeric values (percentages, animated values) are ignored, like
+ * {@linkcode resizeForStyle}. Returns `undefined` when none are set.
+ */
+export declare function cornerRadiusForStyle(style: StyleProp<ViewStyle>): number | CornerRadii | undefined;
+//# sourceMappingURL=resizeForStyle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resizeForStyle.d.ts","sourceRoot":"","sources":["../../../src/resizeForStyle.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EAEd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACd,MAAM,mCAAmC,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,OAAO,GACd,aAAa,GAAG,SAAS,CAS3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,GAC1B,aAAa,GAAG,SAAS,CAG3B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,GAC1B,MAAM,GAAG,WAAW,GAAG,SAAS,CAoClC"}

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

@@ -0,0 +1,53 @@
+import type { Image } from 'react-native-nitro-image';
+import type { CacheOption, CornerRadii, ResizeOptions } from './specs/nitro-image-toolkit.nitro';
+type Result = {
+    image: undefined;
+    error: undefined;
+} | {
+    image: Image;
+    error: undefined;
+} | {
+    image: undefined;
+    error: Error;
+};
+/**
+ * A hook to asynchronously load an image from the
+ * given {@linkcode AsyncImageSource} into memory.
+ * @example
+ * ```ts
+ * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
+ * ```
+ */
+export declare function useImage({ url, blur, cornerRadius, resize, cache, enabled, }: {
+    url: string;
+    /**
+     * Gaussian blur strength, as the standard deviation (sigma) of the blur in
+     * source-image pixels (of the resized bitmap when `resize` is set). Matches
+     * across iOS and Android; roughly half of React Native's `blurRadius`.
+     */
+    blur?: number;
+    /**
+     * Corner radius in pixels of the loaded bitmap. Pass a single number for
+     * uniform rounding, or per-corner radii (inline object literals are fine —
+     * the hook compares the radii by value, not identity). Pair with `resize`
+     * so the radii apply at the size you display instead of the source size.
+     */
+    cornerRadius?: number | CornerRadii;
+    /**
+     * Resize the bitmap to exactly this size in pixels (aspect-fill,
+     * center-crop) before blur/rounding. Typically your display size in points
+     * multiplied by `PixelRatio.get()`. Inline object literals are fine.
+     */
+    resize?: ResizeOptions;
+    cache?: CacheOption;
+    /**
+     * When `false`, no request is made and the result stays in the loading
+     * state (or keeps the current image if `url` is unchanged) until it becomes
+     * `true`. Use it to defer loading until inputs such as a layout size are
+     * known.
+     * @default true
+     */
+    enabled?: boolean;
+}): Result;
+export {};
+//# sourceMappingURL=useImage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useImage.d.ts","sourceRoot":"","sources":["../../../src/useImage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAGtD,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACd,MAAM,mCAAmC,CAAC;AAE3C,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,MAAM,EACN,KAAK,EACL,OAAc,GACf,EAAE;IACD,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,MAAM,CA4ET"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-image-pipeline",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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",
@@ -86,7 +86,8 @@
     "react-native-nitro-image": "0.15.1"
   },
   "overrides": {
-    "lodash-es": "4.17.21"
+    "lodash-es": "4.17.21",
+    "typescript": "$typescript"
   },
   "react-native-builder-bob": {
     "source": "src",

package/src/NitroImagePipeline.ts

@@ -0,0 +1,6 @@
+import { NitroModules } from 'react-native-nitro-modules';
+
+import type { NitroImagePipeline as NitroImagePipelineSpec } from './specs/nitro-image-toolkit.nitro';
+
+export const NitroImagePipeline =
+  NitroModules.createHybridObject<NitroImagePipelineSpec>('NitroImagePipeline');

package/src/PipelineImage.tsx

@@ -0,0 +1,183 @@
+import {
+  type ComponentRef,
+  forwardRef,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import {
+  type HostComponent,
+  type LayoutChangeEvent,
+  PixelRatio,
+} from 'react-native';
+import { type Image, NativeNitroImage } from 'react-native-nitro-image';
+
+import {
+  cornerRadiusForStyle,
+  resizeForLayout,
+  resizeForStyle,
+} from './resizeForStyle';
+import type {
+  CacheOption,
+  CornerRadii,
+  ResizeOptions,
+} from './specs/nitro-image-toolkit.nitro';
+import { useImage } from './useImage';
+
+type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
+type NativeImageProps = ReactProps<typeof NativeNitroImage>;
+
+/**
+ * The instance `<PipelineImage>` exposes through its `ref` — the underlying
+ * `NativeNitroImage` host view, with the usual native-view methods
+ * (`measure`, …).
+ */
+export type PipelineImageRef = ComponentRef<typeof NativeNitroImage>;
+
+export interface PipelineImageProps extends Omit<NativeImageProps, 'image'> {
+  /** URL of the image to load through the pipeline. */
+  url: string;
+  /**
+   * Gaussian blur sigma in **points** (density-independent). Unlike
+   * `useImage`/`loadImage`, where it is bitmap pixels, the component
+   * multiplies it by `PixelRatio.get()` so the same value looks the same on
+   * every device.
+   * @default 0
+   */
+  blur?: number;
+  /**
+   * Corner radius in **points** — a single number or per-corner radii.
+   * Converted to bitmap pixels with `PixelRatio.get()` and baked into the
+   * bitmap at the display size.
+   *
+   * When omitted, it's derived from `style`'s `borderRadius` /
+   * `borderTopLeftRadius` / `borderTopRightRadius` / `borderBottomLeftRadius`
+   * / `borderBottomRightRadius` instead — set this prop to override that.
+   * @default undefined (derived from `style`, or square corners if unset there)
+   */
+  cornerRadius?: number | CornerRadii;
+  cache?: CacheOption;
+  /** Called with the processed `Image` each time a new variant resolves. */
+  onLoad?: (image: Image) => void;
+  /** Called when loading fails. */
+  onError?: (error: Error) => void;
+}
+
+function sameSize(a?: ResizeOptions, b?: ResizeOptions): boolean {
+  return a?.width === b?.width && a?.height === b?.height;
+}
+
+function scaleRadius(
+  cornerRadius: number | CornerRadii,
+  scale: number,
+): number | CornerRadii {
+  if (typeof cornerRadius === 'number') {
+    return cornerRadius * scale;
+  }
+  return {
+    topLeft: (cornerRadius.topLeft ?? 0) * scale,
+    topRight: (cornerRadius.topRight ?? 0) * scale,
+    bottomLeft: (cornerRadius.bottomLeft ?? 0) * scale,
+    bottomRight: (cornerRadius.bottomRight ?? 0) * scale,
+  };
+}
+
+/**
+ * A `NativeNitroImage` that loads `url` through the pipeline at exactly the
+ * size it is displayed: the bitmap is resized to the view's size in points ×
+ * `PixelRatio.get()`, so `blur` and `cornerRadius` (both in points here) apply
+ * 1:1 to what is on screen and large sources are never decoded at full size.
+ *
+ * A numeric `width`/`height` in `style` starts loading immediately; otherwise
+ * (`'50%'`, `flex`, `aspectRatio`, …) loading waits for the first `onLayout`.
+ * If the layout size later changes, a new variant is loaded and swapped in
+ * without flashing. Without an explicit `cornerRadius` prop, `style`'s
+ * `borderRadius`-family properties are baked into the bitmap instead — no
+ * separate view-layer rounding needed.
+ *
+ * The `ref` is forwarded to the underlying `NativeNitroImage` host view, so
+ * the component works with `Animated.createAnimatedComponent` (Reanimated or
+ * React Native's built-in `Animated`).
+ * @example
+ * ```tsx
+ * <PipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200 }}
+ *   cornerRadius={24}
+ * />
+ * ```
+ */
+export const PipelineImage = forwardRef<PipelineImageRef, PipelineImageProps>(
+  function PipelineImage(
+    {
+      url,
+      blur = 0,
+      cornerRadius,
+      cache,
+      onLoad,
+      onError,
+      style,
+      onLayout,
+      ...viewProps
+    },
+    ref,
+  ) {
+    const scale = PixelRatio.get();
+    const styleSize = resizeForStyle(style);
+    const [layoutSize, setLayoutSize] = useState<ResizeOptions | undefined>(
+      undefined,
+    );
+    // A numeric style is what the caller declared, so it wins and starts the
+    // request a frame earlier; the measured layout is the fallback.
+    const resize = styleSize ?? layoutSize;
+    // Same precedence: an explicit prop wins over what style implies.
+    const effectiveCornerRadius =
+      cornerRadius ?? cornerRadiusForStyle(style) ?? 0;
+
+    const { image, error } = useImage({
+      url,
+      blur: blur * scale,
+      cornerRadius: scaleRadius(effectiveCornerRadius, scale),
+      cache,
+      resize,
+      enabled: resize !== undefined,
+    });
+
+    // Latest callbacks in refs so inline arrow props don't re-fire the effects.
+    const onLoadRef = useRef(onLoad);
+    const onErrorRef = useRef(onError);
+    useEffect(() => {
+      onLoadRef.current = onLoad;
+      onErrorRef.current = onError;
+    });
+    useEffect(() => {
+      if (image) onLoadRef.current?.(image);
+    }, [image]);
+    useEffect(() => {
+      if (error) onErrorRef.current?.(error);
+    }, [error]);
+
+    const handleLayout = (event: LayoutChangeEvent) => {
+      onLayout?.(event);
+      const { width, height } = event.nativeEvent.layout;
+      const next = resizeForLayout(width, height);
+      // Always record it (even when a numeric style is in charge) so a later
+      // switch to a non-numeric style has a size to fall back on.
+      setLayoutSize((prev) => (sameSize(prev, next) ? prev : next));
+    };
+
+    return (
+      <NativeNitroImage
+        {...viewProps}
+        ref={ref}
+        style={style}
+        onLayout={handleLayout}
+        image={image}
+      />
+    );
+  },
+);
+
+// Reanimated and DevTools read the display name; the forwardRef wrapper
+// would otherwise report as anonymous.
+PipelineImage.displayName = 'PipelineImage';

package/src/index.ts

@@ -1,144 +1,18 @@
-import { useEffect, useRef, useState } from 'react';
-import type { Image } from 'react-native-nitro-image';
-import { NitroModules } from 'react-native-nitro-modules';
-
-import type {
+export { NitroImagePipeline } from './NitroImagePipeline';
+export {
+  PipelineImage,
+  type PipelineImageProps,
+  type PipelineImageRef,
+} from './PipelineImage';
+export {
+  cornerRadiusForStyle,
+  resizeForLayout,
+  resizeForStyle,
+} from './resizeForStyle';
+export type {
   CacheOption,
   CornerRadii,
-  NitroImagePipeline as NitroImagePipelineSpec,
   Options,
   ResizeOptions,
 } from './specs/nitro-image-toolkit.nitro';
-
-export type { CacheOption, CornerRadii, Options, ResizeOptions };
-
-export const NitroImagePipeline =
-  NitroModules.createHybridObject<NitroImagePipelineSpec>('NitroImagePipeline');
-
-type Result =
-  // Loading State
-  | {
-      image: undefined;
-      error: undefined;
-    }
-  // Loaded state
-  | {
-      image: Image;
-      error: undefined;
-    }
-  // Error state
-  | {
-      image: undefined;
-      error: Error;
-    };
-
-/**
- * A hook to asynchronously load an image from the
- * given {@linkcode AsyncImageSource} into memory.
- * @example
- * ```ts
- * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
- * ```
- */
-export function useImage({
-  url,
-  blur = 0,
-  cornerRadius = 0,
-  resize,
-  cache,
-}: {
-  url: string;
-  /**
-   * Gaussian blur strength, as the standard deviation (sigma) of the blur in
-   * source-image pixels (of the resized bitmap when `resize` is set). Matches
-   * across iOS and Android; roughly half of React Native's `blurRadius`.
-   */
-  blur?: number;
-  /**
-   * Corner radius in pixels of the loaded bitmap. Pass a single number for
-   * uniform rounding, or per-corner radii (inline object literals are fine —
-   * the hook compares the radii by value, not identity). Pair with `resize`
-   * so the radii apply at the size you display instead of the source size.
-   */
-  cornerRadius?: number | CornerRadii;
-  /**
-   * Resize the bitmap to exactly this size in pixels (aspect-fill,
-   * center-crop) before blur/rounding. Typically your display size in points
-   * multiplied by `PixelRatio.get()`. Inline object literals are fine.
-   */
-  resize?: ResizeOptions;
-  cache?: CacheOption;
-}): Result {
-  const [image, setImage] = useState<Result>({
-    image: undefined,
-    error: undefined,
-  });
-  const loadedUrlRef = useRef(url);
-
-  // Split the option into primitives so an inline `{ topLeft: 24, ... }`
-  // literal (new identity every render) doesn't re-trigger the effect.
-  const isUniformRadius = typeof cornerRadius === 'number';
-  const uniformRadius = isUniformRadius ? cornerRadius : 0;
-  const {
-    topLeft = 0,
-    topRight = 0,
-    bottomLeft = 0,
-    bottomRight = 0,
-  } = isUniformRadius ? {} : cornerRadius;
-  const resizeWidth = resize?.width ?? 0;
-  const resizeHeight = resize?.height ?? 0;
-
-  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: isUniformRadius
-            ? uniformRadius
-            : { topLeft, topRight, bottomLeft, bottomRight },
-          resize:
-            resizeWidth > 0 && resizeHeight > 0
-              ? { width: resizeWidth, height: resizeHeight }
-              : undefined,
-          cache,
-        });
-
-        if (!cancelled) {
-          setImage({ image: result, error: undefined });
-        }
-      } catch (e) {
-        const error = e instanceof Error ? e : new Error(`${e}`);
-        if (!cancelled) {
-          setImage({ image: undefined, error: error });
-        }
-      }
-    })();
-
-    return () => {
-      cancelled = true;
-    };
-  }, [
-    url,
-    blur,
-    isUniformRadius,
-    uniformRadius,
-    topLeft,
-    topRight,
-    bottomLeft,
-    bottomRight,
-    resizeWidth,
-    resizeHeight,
-    cache,
-  ]);
-
-  return image;
-}
+export { useImage } from './useImage';