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

package/lib/module/usePipelineImageLoader.js

@@ -1,9 +1,36 @@
 "use strict";
 
-import { useMemo } from 'react';
+import { useLayoutEffect, useMemo, useRef } from 'react';
 import { NitroImagePipeline } from './NitroImagePipeline';
+import { resolveImageUrlOrFallback } from './resolveImageSource';
+// Identifies a loader in the callbacks below without them capturing it. A
+// callback the native loader owns that captured the loader back would be a
+// cycle across the language boundary — neither side collectable, and the JS
+// runtime left to take it apart at teardown.
+let nextLoaderToken = 0;
 /**
- * Creates (and memoizes) an {@linkcode ImageLoader} for `url` to pass to
+ * The callbacks handed to a native loader. Built out here, where the scope
+ * holds nothing but the token and the two refs, so the loader can't end up
+ * captured by a callback it owns.
+ */
+function makeReporters(token, activeToken, callbacks) {
+  return {
+    onLoad: (width, height) => {
+      if (activeToken.current === token) {
+        callbacks.current.onLoad?.(width, height);
+      }
+    },
+    onError: message => {
+      if (activeToken.current === token) {
+        callbacks.current.onError?.(message);
+      }
+    }
+  };
+}
+
+/**
+ * Creates (and memoizes) an {@linkcode ImageLoader} for `source` — a URL
+ * string or a `require()`d asset, see {@linkcode ImageSource} — 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
@@ -11,9 +38,11 @@ import { NitroImagePipeline } from './NitroImagePipeline';
  *
  * `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.
+ * literals are fine — options are compared by value, not identity, and the
+ * `onLoad`/`onError` callbacks are read through a ref, so inline arrows don't
+ * recreate the loader either.
  */
-export function usePipelineImageLoader(url, options) {
+export function usePipelineImageLoader(source, 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.
@@ -31,35 +60,109 @@ export function usePipelineImageLoader(url, options) {
   } = isUniformRadius || cornerRadius === undefined ? {} : cornerRadius;
   const resizeWidth = options?.resize?.width;
   const resizeHeight = options?.resize?.height;
-  return useMemo(() => {
+  const resizeFit = options?.resize?.fit;
+  const resizeAllowUpscale = options?.resize?.allowUpscale;
+  const fit = options?.fit;
+  const allowUpscale = options?.allowUpscale;
+  const onLoad = options?.onLoad;
+  const onError = options?.onError;
+  // Only *whether* a callback is set can change the loader: what the native
+  // side gets is a wrapper that reads the latest callbacks from a ref (like
+  // PipelineImage does). So an inline arrow — a new identity every render —
+  // doesn't recreate the loader and re-trigger the native load.
+  const hasOnLoad = onLoad !== undefined;
+  const hasOnError = onError !== undefined;
+  const callbacks = useRef({
+    onLoad,
+    onError
+  });
+  // A layout effect, not a passive one: passive effects are flushed in a later
+  // task, so a load reported between the commit and that flush would read the
+  // previous render's callbacks — a callback added alongside a new loader
+  // could miss its only event. This runs in the same task as the commit, and
+  // the view can't reach the loader before the commit installs it, so the ref
+  // is always current by the time native calls back. (Assigning it during
+  // render instead would mutate on renders React throws away.)
+  useLayoutEffect(() => {
+    callbacks.current = {
+      onLoad,
+      onError
+    };
+  });
+  // The token of the loader the view is currently on. Swapping loaders (a
+  // changed url or options) never drops the old one — the view just stops
+  // referring to it — so a load it already had in flight can still report.
+  // Without this check the wrappers, which read the latest callbacks, would
+  // hand the previous image's size to the current `onLoad`.
+  const activeToken = useRef(-1);
+  const memoized = useMemo(() => {
+    // Runs during render, so an unregistered `require()` id must not throw:
+    // it becomes a URL the native loader fails on at load time instead.
+    const url = resolveImageUrlOrFallback(source);
     const cornerRadiusOption = isUniformRadius ? uniformRadius : hasCornerObject ? {
       topLeft,
       topRight,
       bottomLeft,
       bottomRight
     } : undefined;
+    // What is loaded — the callbacks are deliberately not part of it, so two
+    // loaders that differ only in them are the same image.
     const stableOptions = {
       blur,
       cache,
       cornerRadius: cornerRadiusOption,
       resize: resizeWidth !== undefined && resizeHeight !== undefined ? {
         width: resizeWidth,
-        height: resizeHeight
-      } : undefined
+        height: resizeHeight,
+        fit: resizeFit,
+        allowUpscale: resizeAllowUpscale
+      } : undefined,
+      fit,
+      allowUpscale
     };
-    const loader = NitroImagePipeline.createImageLoader(url, stableOptions);
+    const token = nextLoaderToken++;
+    // The reporters read the refs, but only when the native side calls them —
+    // the rule can't see that they aren't called here.
+    // oxlint-disable-next-line react/refs
+    const reporters = makeReporters(token, activeToken, callbacks);
+    const loader = NitroImagePipeline.createImageLoader(url, {
+      ...stableOptions,
+      // Passed only when the caller wants them: without a callback nothing
+      // ever crosses into JS, which is the point of the native path.
+      onLoad: hasOnLoad ? reporters.onLoad : undefined,
+      onError: hasOnError ? reporters.onError : undefined
+    });
     // `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).
+    // same convention react-native-nitro-image's own loaders use). Toggling a
+    // callback on or off makes a different loader, so the tag has to say so —
+    // otherwise the view keeps the old one installed. Their identities stay
+    // out of it: those don't change what is loaded, or which loader this is.
     Object.defineProperty(loader, '__source', {
       enumerable: true,
       configurable: true,
       value: {
         url,
-        options: stableOptions
+        options: stableOptions,
+        callbacks: {
+          onLoad: hasOnLoad,
+          onError: hasOnError
+        }
       }
     });
-    return loader;
-  }, [url, blur, cache, isUniformRadius, uniformRadius, hasCornerObject, topLeft, topRight, bottomLeft, bottomRight, resizeWidth, resizeHeight]);
+    return {
+      loader,
+      token
+    };
+  }, [source, blur, cache, isUniformRadius, uniformRadius, hasCornerObject, topLeft, topRight, bottomLeft, bottomRight, resizeWidth, resizeHeight, resizeFit, resizeAllowUpscale, fit, allowUpscale, hasOnLoad, hasOnError,
+  // Stable ref objects; listed to satisfy the exhaustive-deps rules.
+  activeToken, callbacks]);
+
+  // Same reasoning as the callbacks ref: a layout effect is current before the
+  // view — which the commit has only just handed this loader — can report.
+  useLayoutEffect(() => {
+    activeToken.current = memoized.token;
+  }, [memoized, activeToken]);
+  return memoized.loader;
 }
 //# sourceMappingURL=usePipelineImageLoader.js.map

package/lib/module/usePipelineImageLoader.js.map

@@ -1 +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":[]}
+{"version":3,"names":["useLayoutEffect","useMemo","useRef","NitroImagePipeline","resolveImageUrlOrFallback","nextLoaderToken","makeReporters","token","activeToken","callbacks","onLoad","width","height","current","onError","message","usePipelineImageLoader","source","options","blur","cache","cornerRadius","isUniformRadius","uniformRadius","hasCornerObject","undefined","topLeft","topRight","bottomLeft","bottomRight","resizeWidth","resize","resizeHeight","resizeFit","fit","resizeAllowUpscale","allowUpscale","hasOnLoad","hasOnError","memoized","url","cornerRadiusOption","stableOptions","reporters","loader","createImageLoader","Object","defineProperty","enumerable","configurable","value"],"sourceRoot":"../../src","sources":["usePipelineImageLoader.ts"],"mappings":"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","ignoreList":[]}

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

@@ -1,7 +1,8 @@
 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';
+import { type ImageSource } from './resolveImageSource';
+import type { CacheOption, CornerRadii, ResizeFit, ResizeOptions } from './specs/nitro-image-toolkit.nitro';
 type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
 type NativeImageProps = ReactProps<typeof NativeNitroImage>;
 /**
@@ -11,8 +12,12 @@ type NativeImageProps = ReactProps<typeof NativeNitroImage>;
  */
 export type NativePipelineImageRef = ComponentRef<typeof NativeNitroImage>;
 export interface NativePipelineImageProps extends Omit<NativeImageProps, 'image'> {
-    /** URL of the image to load through the pipeline. */
-    url: string;
+    /**
+     * The image to load through the pipeline: a URL string (`https://`,
+     * `file://`, an absolute path) or a `require()`d asset — see
+     * {@linkcode ImageSource}.
+     */
+    url: ImageSource;
     /**
      * Gaussian blur sigma in **points** (density-independent), like
      * `PipelineImage`. Applied natively with the screen scale.
@@ -33,6 +38,46 @@ export interface NativePipelineImageProps extends Omit<NativeImageProps, 'image'
      * @default undefined (measure the view natively)
      */
     resize?: ResizeOptions;
+    /**
+     * How the source is fitted into the measured view size when the bitmap is
+     * produced — see {@linkcode ResizeFit}. When omitted it follows
+     * `resizeMode`, like `PipelineImage`. Set this to decouple the two.
+     * @default undefined (derived from `resizeMode`, or `'cover'` if unset)
+     */
+    fit?: ResizeFit;
+    /**
+     * `false` never enlarges a source smaller than the view when the
+     * **bitmap** is produced — see {@linkcode ResizeOptions.allowUpscale}: it
+     * stays at its own pixel size, so nothing is decoded or blurred larger
+     * than the source. The **view** still displays that bitmap per
+     * `resizeMode`, so `cover`/`contain`/`stretch` scale it up on screen (and
+     * a baked `blur`/`cornerRadius` with it); `resizeMode="center"` shows it
+     * pixel for pixel instead, on both platforms.
+     * @default true
+     */
+    allowUpscale?: boolean;
+    /**
+     * Called when the view has displayed the image, with the size of the bitmap
+     * it displays in **pixels**.
+     *
+     * Unlike `PipelineImage`'s `onLoad` this doesn't hand you the `Image` — the
+     * bitmap stays native, which is the point of this component — and it means
+     * "the view is now showing this image" rather than firing exactly once: a
+     * recycled cell re-attaching calls it again, and a single view may call it
+     * more than once for the same image. Make it idempotent.
+     *
+     * Setting it means there is per-image JS work again; leave it unset and the
+     * component stays free of JS round trips.
+     */
+    onLoad?: (width: number, height: number) => void;
+    /**
+     * Called when loading fails, with the underlying error's message. A load
+     * cancelled by the view detaching is not a failure and doesn't call this.
+     *
+     * Without it, failures on this component are silent — there is no `Image`
+     * and no promise to surface them.
+     */
+    onError?: (message: string) => void;
 }
 /**
  * The fully native-driven variant of `PipelineImage`: after the first render
@@ -43,8 +88,9 @@ export interface NativePipelineImageProps extends Omit<NativeImageProps, 'image'
  * the same pipeline and caches as `useImage`/`preLoadImage`.
  *
  * Compared to `PipelineImage`:
- * - No `onLoad`/`onError` callbacks — the loaded `Image` never crosses into
- *   JS. Use `PipelineImage` (or `useImage`) when you need them.
+ * - `onLoad` reports the bitmap's pixel size rather than the `Image` itself,
+ *   which never crosses into JS, and can fire more than once for a view. Use
+ *   `PipelineImage` (or `useImage`) when you need the `Image`.
  * - The bitmap is loaded once at the size the view first has; if the view is
  *   resized later, the bitmap scales with it instead of reloading.
  * @example

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

@@ -1 +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"}
+{"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,EAAE,KAAK,WAAW,EAAmB,MAAM,sBAAsB,CAAC;AACzE,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACT,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;;;;OAIG;IACH,GAAG,EAAE,WAAW,CAAC;IACjB;;;;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;IACvB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,mBAAmB;;;;;4FAgD9B,CAAC"}

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

@@ -1,7 +1,8 @@
 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';
+import type { ImageSource } from './resolveImageSource';
+import type { CacheOption, CornerRadii, ResizeFit } from './specs/nitro-image-toolkit.nitro';
 type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
 type NativeImageProps = ReactProps<typeof NativeNitroImage>;
 /**
@@ -11,8 +12,12 @@ type NativeImageProps = ReactProps<typeof NativeNitroImage>;
  */
 export type PipelineImageRef = ComponentRef<typeof NativeNitroImage>;
 export interface PipelineImageProps extends Omit<NativeImageProps, 'image'> {
-    /** URL of the image to load through the pipeline. */
-    url: string;
+    /**
+     * The image to load through the pipeline: a URL string (`https://`,
+     * `file://`, an absolute path) or a `require()`d asset — see
+     * {@linkcode ImageSource}.
+     */
+    url: ImageSource;
     /**
      * Gaussian blur sigma in **points** (density-independent). Unlike
      * `useImage`/`loadImage`, where it is bitmap pixels, the component
@@ -33,6 +38,33 @@ export interface PipelineImageProps extends Omit<NativeImageProps, 'image'> {
      */
     cornerRadius?: number | CornerRadii;
     cache?: CacheOption;
+    /**
+     * How the source is fitted into the display size when the bitmap is
+     * produced — see {@linkcode ResizeFit}. When omitted it follows
+     * `resizeMode`, so `resizeMode="contain"` decodes an aspect-fitted bitmap
+     * (no crop, no padding) instead of a center-cropped one the view then
+     * letterboxes. Set this to decouple the two.
+     *
+     * One iOS caveat, inherited from nitro-image's `Image`: an `Image` handed
+     * to the view is a scale-1 image, which `resizeMode="center"` — the one
+     * mode that draws an image at its own size — shows at 1 pt per pixel,
+     * i.e. `PixelRatio.get()`× larger than Android draws it. The bitmap is
+     * right; the display is not. `NativePipelineImage` draws `center` pixel
+     * for pixel on both platforms; use it when you need that mode.
+     * @default undefined (derived from `resizeMode`, or `'cover'` if unset)
+     */
+    fit?: ResizeFit;
+    /**
+     * `false` never enlarges a source smaller than the display size when the
+     * **bitmap** is produced — see {@linkcode ResizeOptions.allowUpscale}: it
+     * stays at its own pixel size, so nothing is decoded or blurred larger
+     * than the source. The **view** still displays that bitmap per
+     * `resizeMode`, so `cover`/`contain`/`stretch` scale it up on screen (and
+     * a baked `blur`/`cornerRadius` with it); `resizeMode="center"` shows it
+     * at its natural size instead.
+     * @default true
+     */
+    allowUpscale?: boolean;
     /** Called with the processed `Image` each time a new variant resolves. */
     onLoad?: (image: Image) => void;
     /** Called when loading fails. */

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

@@ -1 +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"}
+{"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,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,SAAS,EAEV,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;;;;OAIG;IACH,GAAG,EAAE,WAAW,CAAC;IACjB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,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;;;;;4FA+EzB,CAAC"}

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

@@ -1,8 +1,9 @@
 export { NativePipelineImage, type NativePipelineImageProps, type NativePipelineImageRef, } from './NativePipelineImage';
 export { NitroImagePipeline } from './NitroImagePipeline';
 export { PipelineImage, type PipelineImageProps, type PipelineImageRef, } from './PipelineImage';
+export { type ImageSource, resolveImageUrl, UNREGISTERED_ASSET_URL, } from './resolveImageSource';
 export { cornerRadiusForStyle, resizeForLayout, resizeForStyle, } from './resizeForStyle';
-export type { CacheOption, CornerRadii, Options, ResizeOptions, ViewOptions, } from './specs/nitro-image-toolkit.nitro';
+export type { CacheOption, CornerRadii, Options, ResizeFit, 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,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"}
+{"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,KAAK,WAAW,EAChB,eAAe,EACf,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,SAAS,EACT,aAAa,EACb,WAAW,GACZ,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}

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

@@ -3,7 +3,9 @@ import type { CornerRadii, ResizeOptions } from './specs/nitro-image-toolkit.nit
 /**
  * Converts a layout size in points (dp) to the pipeline's `resize` option in
  * whole bitmap pixels using `PixelRatio.getPixelSizeForLayoutSize`. Returns
- * `undefined` unless both values are positive numbers.
+ * `undefined` unless both values are positive numbers. Spread a `fit` into
+ * the result for the other resize modes — under `contain` and `center` the
+ * size is the box the bitmap fits in, not necessarily its final size.
  */
 export declare function resizeForLayout(width: unknown, height: unknown): ResizeOptions | undefined;
 /**

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

@@ -1 +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"}
+{"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;;;;;;GAMG;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/resolveImageSource.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolveImageSource.d.ts","sourceRoot":"","sources":["../../../src/resolveImageSource.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAS3D;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAWrE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAE3D"}

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

@@ -12,13 +12,45 @@ export interface CornerRadii {
     bottomRight?: number;
 }
 /**
- * Target bitmap size in pixels. The image is scaled to fill this size and
- * center-cropped (like CSS `object-fit: cover`), upscaling if needed, so the
- * result is exactly `width` × `height` pixels.
+ * How the source is fitted into the {@linkcode ResizeOptions} box. Mirrors
+ * `NativeNitroImage`'s `resizeMode`, so a view's `resizeMode` and the bitmap
+ * it displays can be derived from one value. With a `w` × `h` source and a
+ * `W` × `H` box, the produced bitmap is:
+ *
+ * - `cover`: scale by `max(W/w, H/h)`, center-crop → exactly `W` × `H`
+ *   (CSS `object-fit: cover`).
+ * - `contain`: scale by `min(W/w, H/h)` → `round(w·s)` × `round(h·s)`, the
+ *   largest size with the source's aspect ratio that fits the box. The
+ *   bitmap is *not* padded to the box.
+ * - `stretch`: scale each axis independently → exactly `W` × `H`, aspect
+ *   ratio ignored.
+ * - `center`: no scaling; center-crop to `min(w, W)` × `min(h, H)`. A source
+ *   smaller than the box is left untouched.
+ */
+export type ResizeFit = 'cover' | 'contain' | 'stretch' | 'center';
+/**
+ * Target bitmap size in pixels. By default the image is scaled to fill this
+ * size and center-cropped (like CSS `object-fit: cover`), upscaling if
+ * needed, so the result is exactly `width` × `height` pixels; {@linkcode fit}
+ * selects the other resize modes.
  */
 export interface ResizeOptions {
     width: number;
     height: number;
+    /**
+     * How the source is fitted into `width` × `height` — see
+     * {@linkcode ResizeFit} for the size each mode produces.
+     * @default 'cover'
+     */
+    fit?: ResizeFit;
+    /**
+     * `false` never enlarges the source: the scale is clamped to at most 1 for
+     * `cover`, `contain` and `stretch`, so a source smaller than the box keeps
+     * its own size (and, under `cover`, is only cropped to the box). No effect
+     * on `center`, which never scales.
+     * @default true
+     */
+    allowUpscale?: boolean;
 }
 export type Options = {
     /**
@@ -51,10 +83,11 @@ export type Options = {
      */
     cornerRadius?: number | CornerRadii;
     /**
-     * Resize the image to exactly this size in pixels (aspect-fill,
-     * center-crop) before `blur` and `cornerRadius` are applied. Besides making
-     * `cornerRadius` predictable, this avoids decoding and processing
-     * full-resolution bitmaps you only display small.
+     * Resize the image into this box in pixels — aspect-fill + center-crop by
+     * default, or another {@linkcode ResizeFit} — before `blur` and
+     * `cornerRadius` are applied. Besides making `cornerRadius` predictable,
+     * this avoids decoding and processing full-resolution bitmaps you only
+     * display small.
      *
      * @default undefined (keep the source size)
      */
@@ -85,15 +118,64 @@ export type ViewOptions = {
     /**
      * Target bitmap size in **pixels**, overriding the size measured from the
      * view. Rarely needed — without it the loader resizes to the view's
-     * laid-out size × screen scale, which is what you want in a UI.
+     * laid-out size × screen scale, which is what you want in a UI. Its own
+     * `fit`/`allowUpscale`, when set, win over the top-level ones below.
      * @default undefined (measure the view)
      */
     resize?: ResizeOptions;
+    /**
+     * How the source is fitted into the box the loader resizes to (the view's
+     * size, or {@linkcode resize}) — see {@linkcode ResizeFit}. Pass the view's
+     * `resizeMode` so the bitmap matches how the view displays it.
+     * @default 'cover'
+     */
+    fit?: ResizeFit;
+    /**
+     * `false` never enlarges the source — see
+     * {@linkcode ResizeOptions.allowUpscale}.
+     * @default true
+     */
+    allowUpscale?: boolean;
+    /**
+     * Called when a view finishes displaying the image, with the size of the
+     * bitmap it displays in **pixels**.
+     *
+     * The bitmap itself deliberately stays native — passing the `Image` into JS
+     * would keep it alive there and defeat the point of the native path. Use
+     * `useImage`/`loadImage` when you need the `Image` object.
+     *
+     * This reports "the view is now showing this image", not a one-shot event:
+     * a loader is per URL + options, not per view, so every view using it
+     * reports, a recycled cell reports again when it re-attaches, and a single
+     * view can report more than once (it requests the image both when its
+     * `image` prop is set and when it becomes visible). Memory-cache hits, which
+     * resolve synchronously, report too. It does not fire for imperative loads
+     * through `ImageLoader.loadImage()` — those resolve through their promise.
+     *
+     * Setting it means there *is* per-image JS work; leave it unset and the
+     * native path stays free of JS round trips entirely.
+     * @default undefined (nothing crosses into JS)
+     */
+    onLoad?: (width: number, height: number) => void;
+    /**
+     * Called when a view fails to load the image, with the underlying error's
+     * message. Cancelling a load (the view detaching before it finishes) is not
+     * a failure and does not call this.
+     * @default undefined (failures are silent)
+     */
+    onError?: (message: string) => void;
 };
 export interface NitroImagePipeline extends HybridObject<{
     ios: 'swift';
     android: 'kotlin';
 }> {
+    /**
+     * Loads `url` through the pipeline. Besides `http(s)://`, `url` may be a
+     * `file://` URL or a plain absolute path (read from the file system, cached
+     * in memory only), a `data:` URL, or — on Android — a `content://` URI or
+     * the bare resource name a `require()` resolves to in a release build. Use
+     * `resolveImageUrl(require('./photo.png'))` to pass a bundled asset.
+     */
     loadImage(url: string, options?: Options): Promise<Image>;
     /**
      * Creates an {@linkcode ImageLoader} for `url` that a `<NativeNitroImage>`
@@ -108,6 +190,11 @@ export interface NitroImagePipeline extends HybridObject<{
      * attaches, the load waits for its first layout.
      */
     createImageLoader(url: string, options?: ViewOptions): ImageLoader;
+    /**
+     * Warms the disk cache with the download for `url`, without decoding it.
+     * Local sources (`file://`, paths, resources) have no download to warm it
+     * with and are a no-op.
+     */
     preLoadImage(url: string): Promise<void>;
     preLoadImages(urls: string[]): Promise<void>;
     /**

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,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,OAAO,GAAG;IACpB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,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;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACnE,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;;;;;;;;OAQG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}
+{"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,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,OAAO,GAAG;IACpB;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,CAAC;AAEF,MAAM,WAAW,kBAAmB,SAAQ,YAAY,CAAC;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC;IACA;;;;;;OAMG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1D;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACnE;;;;OAIG;IACH,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;;;;;;;;OAQG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}