feat: allow providing background color when transforming images with alpha channel to a format without it

package/expo-package/src/handlers/__tests__/compressImage.test.ts

@@ -0,0 +1,44 @@
+describe('expo compressImage', () => {
+  const manipulateAsync = jest.fn();
+
+  const loadHandler = () => {
+    jest.doMock('expo-image-manipulator', () => ({ manipulateAsync }), { virtual: true });
+
+    return require('../compressImage').compressImage as (params: {
+      compressImageQuality: number;
+      uri: string;
+    }) => Promise<string>;
+  };
+
+  beforeEach(() => {
+    manipulateAsync.mockResolvedValue({ uri: 'file:///cache/out.jpg' });
+  });
+
+  afterEach(() => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  });
+
+  it('ignores a background colour rather than forwarding one', async () => {
+    // Deliberate asymmetry: backgroundColor is CLI-only. expo-image-manipulator can only fill a
+    // background while *extending* an image and marks that option @platform web, so there is no
+    // way to honour it here.
+    //
+    // The *type-level* guarantee (passing one is a compile error) is enforced by tsc over `src`,
+    // not by this file - expo-package/tsconfig.json excludes `**/__tests__`, so a
+    // `@ts-expect-error` here would never be verified and would only look like a guarantee.
+    // What this test pins is the runtime half: nothing reaches ImageManipulator.
+    const compressImage = loadHandler();
+
+    await compressImage({
+      compressImageQuality: 0.5,
+      uri: 'file:///in.png',
+      ...({ backgroundColor: '#FFFFFF' } as Record<string, never>),
+    });
+
+    expect(manipulateAsync).toHaveBeenCalledWith('file:///in.png', [], { compress: 0.5 });
+    const [, , options] = manipulateAsync.mock.calls[0];
+    expect(options).not.toHaveProperty('backgroundColor');
+    expect(Object.keys(options)).toEqual(['compress']);
+  });
+});

package/native-package/android/src/main/java/com/streamchatreactnative/StreamChatReactNative.java

@@ -5,7 +5,10 @@
 import android.database.Cursor;
 import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
+import android.graphics.Canvas;
 import android.graphics.Matrix;
+import android.graphics.Paint;
+import androidx.annotation.Nullable;
 import androidx.exifinterface.media.ExifInterface;
 import android.net.Uri;
 import android.os.Build;
@@ -34,9 +37,15 @@ public class StreamChatReactNative {
   private final static String SCHEME_HTTPS = "https";
   /**
    * Resize the specified bitmap.
+   *
+   * When backgroundColor is non-null the colour is painted first and the image composited over
+   * it, flattening any alpha channel instead of leaving it for the encoder to drop. That happens
+   * inside this scale pass rather than after it, so it costs no extra bitmap - the same thing
+   * iOS does by filling its graphics context before drawing into it.
    */
   private static Bitmap resizeImage(Bitmap image, int newWidth, int newHeight,
-                                    String mode, boolean onlyScaleDown) {
+                                    String mode, boolean onlyScaleDown,
+                                    @Nullable Integer backgroundColor) {
     Bitmap newImage = null;
     if (image == null) {
       return null; // Can't load the image from the given path.
@@ -73,6 +82,14 @@ private static Bitmap resizeImage(Bitmap image, int newWidth, int newHeight,
         finalHeight = (int) Math.round(height * ratio);
       }
 
+      // Only images that actually carry an alpha channel need a background: drawing a fully
+      // opaque bitmap over any colour reproduces that bitmap exactly, so for everything else
+      // this would be a pixel-for-pixel no-op - and not a cheap one. createScaledBitmap hands
+      // back the source object untouched when the requested size already matches
+      if (backgroundColor != null && image.hasAlpha()) {
+        return scaleOntoBackground(image, finalWidth, finalHeight, backgroundColor);
+      }
+
       try {
         newImage = Bitmap.createScaledBitmap(image, finalWidth, finalHeight, true);
       } catch (OutOfMemoryError e) {
@@ -83,6 +100,38 @@ private static Bitmap resizeImage(Bitmap image, int newWidth, int newHeight,
     return newImage;
   }
 
+  /**
+   * Scale the given bitmap into a new one of the given size, over a fill of the given colour, so
+   * that any alpha channel is flattened rather than dropped.
+   *
+   * Encoders without an alpha channel (JPEG) discard alpha and keep the underlying RGB, which
+   * turns transparent areas black. Drawing onto a filled canvas first blends semi-transparent
+   * pixels toward the colour and replaces fully transparent ones with it.
+   *
+   * This replaces the createScaledBitmap call it stands in for rather than running after it, so
+   * the fill costs no second full-size bitmap. Returns null if the bitmap can't be allocated.
+   * The caller owns the result and should recycle the source.
+   */
+  private static Bitmap scaleOntoBackground(Bitmap source, int newWidth, int newHeight, int color) {
+    Bitmap flattened;
+    try {
+      flattened = Bitmap.createBitmap(newWidth, newHeight, Bitmap.Config.ARGB_8888);
+    } catch (OutOfMemoryError e) {
+      return null;
+    }
+
+    Matrix scale = new Matrix();
+    scale.setScale((float) newWidth / source.getWidth(), (float) newHeight / source.getHeight());
+
+    Canvas canvas = new Canvas(flattened);
+    canvas.drawColor(color);
+    // FILTER_BITMAP_FLAG matches the `filter = true` that createScaledBitmap is called with on
+    // the path this replaces, so scaling quality is unchanged.
+    canvas.drawBitmap(source, scale, new Paint(Paint.FILTER_BITMAP_FLAG));
+
+    return flattened;
+  }
+
   /**
    * Rotate the specified bitmap with the given angle, in degrees.
    */
@@ -390,7 +439,8 @@ private static Bitmap loadBitmapFromBase64(Uri imageUri) {
    */
   public static Bitmap createResizedImage(Context context, Uri imageUri, int newWidth,
                                           int newHeight, int quality, int rotation,
-                                          String mode, boolean onlyScaleDown) throws IOException  {
+                                          String mode, boolean onlyScaleDown,
+                                          @Nullable Integer backgroundColor) throws IOException  {
     Bitmap sourceImage = null;
     String imageUriScheme = imageUri.getScheme();
 
@@ -425,8 +475,9 @@ public static Bitmap createResizedImage(Context context, Uri imageUri, int newWi
       sourceImage.recycle();
     }
 
-    // Scale image
-    Bitmap scaledImage = StreamChatReactNative.resizeImage(rotatedImage, newWidth, newHeight, mode, onlyScaleDown);
+    // Scale image, painting the requested background behind it on the way if it has an alpha
+    // channel to flatten.
+    Bitmap scaledImage = StreamChatReactNative.resizeImage(rotatedImage, newWidth, newHeight, mode, onlyScaleDown, backgroundColor);
 
     if(scaledImage == null){
       throw new IOException("Unable to resize image. Most likely due to not enough memory.");

package/native-package/android/src/main/java/com/streamchatreactnative/StreamChatReactNativeModule.java

@@ -34,17 +34,23 @@ public String getName() {
   }
 
   @ReactMethod
-  public void createResizedImage(String uri, double width, double height, String format, double quality, String mode, boolean onlyScaleDown, Double rotation, @Nullable String outputPath, Promise promise) {
+  public void createResizedImage(String uri, double width, double height, String format, double quality, String mode, boolean onlyScaleDown, Double rotation, @Nullable String outputPath, @Nullable Double backgroundColor, Promise promise) {
     WritableMap options = Arguments.createMap();
     options.putString("mode", mode);
     options.putBoolean("onlyScaleDown", onlyScaleDown);
 
+    // processColor() hands us an ARGB int, but codegen boxes every JS number as a Double.
+    // Double.intValue() *saturates*, so the unsigned form (white is 4294967295.0) would clamp
+    // to Integer.MAX_VALUE and paint teal. Going via long truncates instead, which wraps
+    // correctly for both the signed and unsigned forms processColor produces.
+    final Integer argb = backgroundColor == null ? null : (int) (long) backgroundColor.doubleValue();
+
     // Run in guarded async task to prevent blocking the React bridge
     new GuardedAsyncTask<Void, Void>(this.getReactApplicationContext()) {
       @Override
       protected void doInBackgroundGuarded(Void... params) {
         try {
-          Object response = createResizedImageWithExceptions(uri, (int) width, (int) height, format, (int) quality, rotation.intValue(), outputPath, options);
+          Object response = createResizedImageWithExceptions(uri, (int) width, (int) height, format, (int) quality, rotation.intValue(), outputPath, argb, options);
           promise.resolve(response);
         }
         catch (IOException e) {
@@ -57,13 +63,16 @@ protected void doInBackgroundGuarded(Void... params) {
   @SuppressLint("LongLogTag")
   private Object createResizedImageWithExceptions(String imagePath, int newWidth, int newHeight,
                                                   String compressFormatString, int quality, int rotation, String outputPath,
+                                                  @Nullable Integer backgroundColor,
                                                   final ReadableMap options) throws IOException {
 
     Bitmap.CompressFormat compressFormat = Bitmap.CompressFormat.valueOf(compressFormatString);
     Uri imageUri = Uri.parse(imagePath);
 
+    // The background colour is applied inside the resize, as part of the same canvas pass that
+    // scales the image, so no second full-size bitmap is allocated for it.
     Bitmap scaledImage = StreamChatReactNative.createResizedImage(this.getReactApplicationContext(), imageUri, newWidth, newHeight, quality, rotation,
-      options.getString("mode"), options.getBoolean("onlyScaleDown"));
+      options.getString("mode"), options.getBoolean("onlyScaleDown"), backgroundColor);
 
     if (scaledImage == null) {
       throw new IOException("The image failed to be resized; invalid Bitmap result.");

package/native-package/android/src/oldarch/com/streamchatreactnative/StreamChatReactNative.java

@@ -12,5 +12,5 @@ abstract class StreamChatReactNativeSpec extends ReactContextBaseJavaModule {
     super(context);
   }
 
-  public abstract void createResizedImage(String uri, double width, double height, String format, double quality, String mode, boolean onlyScaleDown, Double rotation, @Nullable String outputPath, Promise promise);
+  public abstract void createResizedImage(String uri, double width, double height, String format, double quality, String mode, boolean onlyScaleDown, Double rotation, @Nullable String outputPath, @Nullable Double backgroundColor, Promise promise);
 }

package/native-package/ios/StreamChatReactNative.mm

@@ -19,7 +19,7 @@
 static NSString *generateFilePath(NSString *ext, NSString *outputPath);
 static UIImage *rotateImage(UIImage *inputImage, float rotationDegrees);
 static float getScaleForProportionalResize(CGSize theSize, CGSize intoSize, bool onlyScaleDown, bool maximize);
-static UIImage *scaleImage(UIImage *image, CGSize toSize, NSString *mode, bool onlyScaleDown);
+static UIImage *scaleImage(UIImage *image, CGSize toSize, NSString *mode, bool onlyScaleDown, UIColor *backgroundColor);
 static NSDictionary *transformImage(UIImage *image, int rotation, CGSize newSize, NSString *fullPath, NSString *format, int quality, NSDictionary *options);
 
 @implementation StreamChatReactNative
@@ -28,12 +28,12 @@ @implementation StreamChatReactNative
 
 RCT_EXPORT_MODULE()
 
-RCT_REMAP_METHOD(createResizedImage, uri:(NSString *)uri width:(double)width height:(double)height format:(NSString *)format quality:(double)quality mode:(NSString *)mode onlyScaleDown:(BOOL)onlyScaleDown rotation:(nonnull NSNumber *)rotation outputPath:(NSString *)outputPath resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
+RCT_REMAP_METHOD(createResizedImage, uri:(NSString *)uri width:(double)width height:(double)height format:(NSString *)format quality:(double)quality mode:(NSString *)mode onlyScaleDown:(BOOL)onlyScaleDown rotation:(nonnull NSNumber *)rotation outputPath:(NSString *)outputPath backgroundColor:(NSNumber *)backgroundColor resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
 {
-    [self createResizedImage:uri width:width height:height format:format quality:quality mode:mode onlyScaleDown:onlyScaleDown rotation:rotation outputPath:outputPath resolve:resolve reject:reject];
+    [self createResizedImage:uri width:width height:height format:format quality:quality mode:mode onlyScaleDown:onlyScaleDown rotation:rotation outputPath:outputPath backgroundColor:backgroundColor resolve:resolve reject:reject];
 }
 
-- (void)createResizedImage:(NSString *)uri width:(double)width height:(double)height format:(NSString *)format quality:(double)quality mode:(NSString *)mode onlyScaleDown:(BOOL)onlyScaleDown rotation:(nonnull NSNumber *)rotation outputPath:(NSString *)outputPath resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
+- (void)createResizedImage:(NSString *)uri width:(double)width height:(double)height format:(NSString *)format quality:(double)quality mode:(NSString *)mode onlyScaleDown:(BOOL)onlyScaleDown rotation:(nonnull NSNumber *)rotation outputPath:(NSString *)outputPath backgroundColor:(NSNumber *)backgroundColor resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject {
     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
         @try {
             CGSize newSize = CGSizeMake(width, height);
@@ -51,6 +51,15 @@ - (void)createResizedImage:(NSString *)uri width:(double)width height:(double)he
                 [NSException raise:moduleName format:@"Invalid output path."];
             }
 
+            // Nil unless the caller asked for a backdrop. Converted here (on the JS-side
+            // argument) rather than in scaleImage so the ARGB decoding lives in one place.
+            UIColor *fillColor = backgroundColor == nil ? nil : [RCTConvert UIColor:backgroundColor];
+
+            NSMutableDictionary *options = [@{@"mode": mode, @"onlyScaleDown": [NSNumber numberWithBool:onlyScaleDown]} mutableCopy];
+            if (fillColor != nil) {
+                options[@"backgroundColor"] = fillColor;
+            }
+
             RCTImageLoader *loader = [self.bridge moduleForName:@"ImageLoader" lazilyLoadIfNecessary:YES];
             NSURLRequest *request = [RCTConvert NSURLRequest:uri];
             [loader loadImageWithURLRequest:request
@@ -66,7 +75,7 @@ - (void)createResizedImage:(NSString *)uri width:(double)width height:(double)he
                     reject([NSString stringWithFormat: @"%ld", (long)error.code], error.description, nil);
                     return;
                 }
-                NSDictionary * response =  transformImage(image, [rotation integerValue], newSize, fullPath, format, (int)quality, @{@"mode": mode, @"onlyScaleDown": [NSNumber numberWithBool:onlyScaleDown]});
+                NSDictionary * response =  transformImage(image, [rotation integerValue], newSize, fullPath, format, (int)quality, options);
                 resolve(response);
             }];
         } @catch (NSException *exception) {
@@ -195,7 +204,7 @@ static float getScaleForProportionalResize(CGSize theSize, CGSize intoSize, bool
 // any :image scale factor.
 // The returned image is an unscaled image (scale = 1.0)
 // so no additional scaling math needs to be done to get its pixel dimensions
-static UIImage* scaleImage (UIImage* image, CGSize toSize, NSString* mode, bool onlyScaleDown)
+static UIImage* scaleImage (UIImage* image, CGSize toSize, NSString* mode, bool onlyScaleDown, UIColor* backgroundColor)
 {
 
     // Need to do scaling corrections
@@ -226,7 +235,18 @@ static float getScaleForProportionalResize(CGSize theSize, CGSize intoSize, bool
         newSize = CGSizeMake(roundf(imageSize.width * scale), roundf(imageSize.height * scale));
     }
 
-    UIGraphicsBeginImageContextWithOptions(newSize, NO, 1.0);
+    // A non-opaque context initialises to white (tested on iOS 26). Encoders
+    // without an alpha channel (JPEG) then drop the alpha and keep the RGB, which
+    // is why transparent areas come out white. When a backdrop is requested we
+    // make the context opaque and fill it first, so the image composites onto the
+    // colour in the same render pass - no extra bitmap, and an opaque context is
+    // cheaper than an alpha one.
+    BOOL opaque = (backgroundColor != nil);
+    UIGraphicsBeginImageContextWithOptions(newSize, opaque, 1.0);
+    if (opaque) {
+        [backgroundColor setFill];
+        UIRectFill(CGRectMake(0, 0, newSize.width, newSize.height));
+    }
     [image drawInRect:CGRectMake(0, 0, newSize.width, newSize.height)];
     UIImage *newImage = UIGraphicsGetImageFromCurrentImageContext();
     UIGraphicsEndImageContext();
@@ -258,7 +278,8 @@ static float getScaleForProportionalResize(CGSize theSize, CGSize intoSize, bool
                                        image,
                                        newSize,
                                        options[@"mode"],
-                                       [[options objectForKey:@"onlyScaleDown"] boolValue]
+                                       [[options objectForKey:@"onlyScaleDown"] boolValue],
+                                       options[@"backgroundColor"]
                                        );
 
     if (scaledImage == nil) {