feat: Introduce RCTUIImage (2/2) (microsoft#2766)

## Summary:

Needs microsoft#2783 to merge first.
Resolves microsoft#2738 

There were a couple of issues with our macOS image rendering code that
caused borders and shadows to not render properly in Fabric:


1. Our shim for `UIGraphicsImageRenderer` on macOS
(`RCTUIGraphicsImageRenderer`) called `[NSImage
imageWithActions:flipped:drawingHandler]`, which would not render the
imade right away but instead when it's about to be displayed (presumably
so that it can generate a proper `CGContext` for the screen the image is
on). This meant that CGImage bitmap would sometimes just return as `0x0`
1. `NSImage` unlike `UIImage` does not have a `CGImage` property, so we
used the method `CGImageForProposedRect:` to get one. Unfortunately,
that returns an autoreleased CGImage, and when we later set that to
RCTViewComponentViews' `layer.contents`, it would not be retained.

This manifested as borders and shadows not rendering, or rendering and
then dissapearing on a resize.

To fix the first issue, apparently we can just call `[image lockFocus]`
and `[image unlockFocus]` in succession to force it to render a bitmap.

To fix the second issue, we need some way to cache the CGImage. I
propose a new class: `RCTUIImage`.

`RCTUIImage`, like `RCTUIView` is a subclass of `NSImage` with some
extra properties and methods to make it more compatible with iOS code.
In our case, we add the extra code to cache a CGImage, with proper
retain and release calls. We can then have `RCTUIGraphicsImageRenderer`
return our new subclass, and update all callers appropiately. The end
result it we can actually remove some diffs, and have our macOS image
handling behave closer to iOS.

While doing this work, I realized our `NSImage` / `UIImage` shims were
kinda messy, and with the new subclass to introduce weird runtime edge
cases. I split out microsoft#2783 to help clean up and clarify what image class
we're using in the rest of the codebase.

While here, I also fixed an issue with clipsToBounds on macOS which was
the final piece to get shadows and borders working.

## Test Plan:

RNTester seems better :)


https://github.com/user-attachments/assets/a5afe150-15ae-4c92-9219-8843aa5362ac

Author: Saadnajmi

packages/react-native/Libraries/Image/RCTImageBlurUtils.mm

@@ -30,16 +30,13 @@
     RCTUIGraphicsImageRenderer *const renderer = [[RCTUIGraphicsImageRenderer alloc] initWithSize:inputImage.size // [macOS]
                                                                                            format:rendererFormat];
 
+    imageRef = [renderer imageWithActions:^(RCTUIGraphicsImageRendererContext *_Nonnull context) { // [macOS]
 #if !TARGET_OS_OSX // [macOS]
-    imageRef = [renderer imageWithActions:^(UIGraphicsImageRendererContext *_Nonnull context) {
                  [inputImage drawAtPoint:CGPointZero];
-               }].CGImage;
 #else // [macOS
-    NSImage *image = [renderer imageWithActions:^(RCTUIGraphicsImageRendererContext *_Nonnull context) {
-      [inputImage drawAtPoint:CGPointZero fromRect:NSZeroRect operation:NSCompositingOperationSourceOver fraction:1.0];
-    }];
-    imageRef = UIImageGetCGImageRef(image);
+                 [inputImage drawAtPoint:CGPointZero fromRect:NSZeroRect operation:NSCompositingOperationSourceOver fraction:1.0];
 #endif // macOS]
+               }].CGImage;
   }
   vImage_Buffer buffer1, buffer2;
   buffer1.width = buffer2.width = CGImageGetWidth(imageRef);

packages/react-native/React/Base/RCTUIKit.h

@@ -60,7 +60,7 @@ UIKIT_STATIC_INLINE void UIBezierPathAppendPath(UIBezierPath *path, UIBezierPath
 #define RCTUIView UIView
 #define RCTUIScrollView UIScrollView
 #define RCTPlatformImage UIImage
-
+#define RCTUIImage UIImage
 
 UIKIT_STATIC_INLINE RCTPlatformView *RCTUIViewHitTestWithEvent(RCTPlatformView *view, CGPoint point, __unused UIEvent *__nullable event)
 {
@@ -268,7 +268,6 @@ extern "C" {
 
 // UIGraphics.h
 CGContextRef UIGraphicsGetCurrentContext(void);
-CGImageRef UIImageGetCGImageRef(NSImage *image);
 
 #ifdef __cplusplus
 }
@@ -333,19 +332,41 @@ NS_INLINE NSEdgeInsets UIEdgeInsetsMake(CGFloat top, CGFloat left, CGFloat botto
 // UIApplication
 #define UIApplication NSApplication
 
-// UIImage
+/**
+ * An NSImage subclass that caches its CGImage representation.
+ *
+ * RCTUIImage solves an issue where NSImage's `CGImageForProposedRect:` returns a new
+ * autoreleased CGImage each time it's called. When assigned to `CALayer.contents`, these
+ * autoreleased CGImages get deallocated when the autorelease pool drains, causing rendering
+ * issues (e.g., blank borders and shadows).
+ *
+ * @warning Treat RCTUIImage instances as immutable after creation. Do not modify the image's
+ * representations or properties after accessing the CGImage property.
+ */
+@interface RCTUIImage : NSImage
+
+@property (nonatomic, readonly, nullable) CGImageRef CGImage;
+
+@property (nonatomic, readonly) CGFloat scale;
+
+@end
+
 typedef NS_ENUM(NSInteger, UIImageRenderingMode) {
     UIImageRenderingModeAlwaysOriginal,
     UIImageRenderingModeAlwaysTemplate,
 };
 
 #ifdef __cplusplus
-extern "C"
+extern "C" {
 #endif
-CGFloat UIImageGetScale(NSImage *image);
 
+CGFloat UIImageGetScale(NSImage *image);
 CGImageRef UIImageGetCGImageRef(NSImage *image);
 
+#ifdef __cplusplus
+}
+#endif
+
 NS_INLINE NSImage *UIImageWithContentsOfFile(NSString *filePath)
 {
   return [[NSImage alloc] initWithContentsOfFile:filePath];
@@ -626,7 +647,7 @@ typedef void (^RCTUIGraphicsImageDrawingActions)(RCTUIGraphicsImageRendererConte
 
 - (instancetype)initWithSize:(CGSize)size;
 - (instancetype)initWithSize:(CGSize)size format:(RCTUIGraphicsImageRendererFormat *)format;
-- (NSImage *)imageWithActions:(NS_NOESCAPE RCTUIGraphicsImageDrawingActions)actions;
+- (RCTUIImage *)imageWithActions:(NS_NOESCAPE RCTUIGraphicsImageDrawingActions)actions;
 
 @end
 NS_ASSUME_NONNULL_END

packages/react-native/React/Base/macOS/RCTUIKit.m

@@ -76,8 +76,43 @@ CGFloat UIImageGetScale(NSImage *image)
   return 1.0;
 }
 
+// RCTUIImage - NSImage subclass with cached CGImage
+
+@implementation RCTUIImage {
+  CGImageRef _cachedCGImage;
+}
+
+- (void)dealloc {
+  if (_cachedCGImage != NULL) {
+    CGImageRelease(_cachedCGImage);
+  }
+}
+
+- (CGImageRef)CGImage {
+  if (_cachedCGImage == NULL) {
+    CGImageRef cgImage = [self CGImageForProposedRect:NULL context:NULL hints:NULL];
+    if (cgImage != NULL) {
+      _cachedCGImage = CGImageRetain(cgImage);
+    }
+  }
+  return _cachedCGImage;
+}
+
+- (CGFloat)scale {
+  return UIImageGetScale(self);
+}
+
+@end
+
 CGImageRef __nullable UIImageGetCGImageRef(NSImage *image)
 {
+  // If it's an RCTUIImage, use the cached CGImage property
+  if ([image isKindOfClass:[RCTUIImage class]]) {
+    return ((RCTUIImage *)image).CGImage;
+  }
+  
+  // Otherwise, fall back to the standard NSImage method
+  // Note: This returns an autoreleased CGImageRef
   return [image CGImageForProposedRect:NULL context:NULL hints:NULL];
 }
 
@@ -825,11 +860,10 @@ - (nonnull instancetype)initWithSize:(CGSize)size format:(nonnull RCTUIGraphicsI
     return self;
 }
 
-- (nonnull NSImage *)imageWithActions:(NS_NOESCAPE RCTUIGraphicsImageDrawingActions)actions {
-
-    NSImage *image = [NSImage imageWithSize:_size
-                                    flipped:YES
-                             drawingHandler:^BOOL(NSRect dstRect) {
+- (nonnull RCTUIImage *)imageWithActions:(NS_NOESCAPE RCTUIGraphicsImageDrawingActions)actions {
+    RCTUIImage *image = [RCTUIImage imageWithSize:_size
+                                           flipped:YES
+                                    drawingHandler:^BOOL(NSRect dstRect) {
 
         RCTUIGraphicsImageRendererContext *context = [NSGraphicsContext currentContext];
         if (self->_format.opaque) {
@@ -838,6 +872,12 @@ - (nonnull NSImage *)imageWithActions:(NS_NOESCAPE RCTUIGraphicsImageDrawingActi
         actions(context);
         return YES;
     }];
+
+    // Calling these in succession forces the image to render its contents immediately,
+    // rather than deferring until later.
+    [image lockFocus];
+    [image unlockFocus];
+    
     return image;
 }
 

packages/react-native/React/Fabric/Mounting/ComponentViews/View/RCTViewComponentView.mm

@@ -839,7 +839,7 @@ static void RCTAddContourEffectToLayer(
     const UIEdgeInsets &contourInsets,
     const RCTBorderStyle &contourStyle)
 {
-  RCTPlatformImage *image = RCTGetBorderImage( // [macOS]
+  RCTUIImage *image = RCTGetBorderImage( // [macOS]
       contourStyle, layer.bounds.size, cornerRadii, contourInsets, contourColors, [RCTUIColor clearColor], NO); // [macOS]
 
   if (image == nil) {
@@ -850,13 +850,8 @@ static void RCTAddContourEffectToLayer(
     CGRect contentsCenter = CGRect{
         CGPoint{imageCapInsets.left / imageSize.width, imageCapInsets.top / imageSize.height},
         CGSize{(CGFloat)1.0 / imageSize.width, (CGFloat)1.0 / imageSize.height}};
-#if !TARGET_OS_OSX // [macOS]
     layer.contents = (id)image.CGImage;
     layer.contentsScale = image.scale;
-#else // [macOS
-    layer.contents = (__bridge id) UIImageGetCGImageRef(image);
-    layer.contentsScale = UIImageGetScale(image);
-#endif // macOS]
 
     BOOL isResizable = !UIEdgeInsetsEqualToEdgeInsets(image.capInsets, UIEdgeInsetsZero);
     if (isResizable) {
@@ -1050,8 +1045,15 @@ - (void)invalidateLayer
   }
 
 #if TARGET_OS_OSX // [macOS
-  // clipsToBounds is stubbed out on macOS because it's not part of NSView
-  layer.masksToBounds = self.clipsToBounds;
+  // On macOS, clipsToBounds doesn't automatically set layer.masksToBounds like iOS does.
+  // When _useCustomContainerView is true (boxShadow + overflow:hidden), the container
+  // view handles clipping children while the main layer stays unclipped for the shadow.
+  // The container view's masksToBounds is set in currentContainerView getter.
+  if (_useCustomContainerView) {
+    layer.masksToBounds = NO;
+  } else {
+    layer.masksToBounds = _props->getClipsContentToBounds();
+  }
 #endif // macOS]
 
   const auto borderMetrics = _props->resolveBorderMetrics(_layoutMetrics);
@@ -1292,17 +1294,13 @@ - (void)invalidateLayer
     _boxShadowLayer.zPosition = _borderLayer.zPosition;
     _boxShadowLayer.frame = RCTGetBoundingRect(_props->boxShadow, self.layer.bounds.size);
 
-    RCTPlatformImage *boxShadowImage = RCTGetBoxShadowImage( // [macOS]
+    RCTUIImage *boxShadowImage = RCTGetBoxShadowImage( // [macOS]
         _props->boxShadow,
         RCTCornerRadiiFromBorderRadii(borderMetrics.borderRadii),
         RCTUIEdgeInsetsFromEdgeInsets(borderMetrics.borderWidths),
         self.layer.bounds.size);
 
-#if !TARGET_OS_OSX // [macOS]
     _boxShadowLayer.contents = (id)boxShadowImage.CGImage;
-#else // [macOS
-    _boxShadowLayer.contents = (__bridge id)UIImageGetCGImageRef(boxShadowImage);
-#endif // macOS]
   }
 
   // clipping

packages/react-native/React/Fabric/Utils/RCTBoxShadow.h

@@ -12,7 +12,7 @@
 #import <React/RCTUIKit.h>
 #import <react/renderer/graphics/BoxShadow.h>
 
-RCT_EXTERN RCTPlatformImage *RCTGetBoxShadowImage( // [macOS]
+RCT_EXTERN RCTUIImage *RCTGetBoxShadowImage( // [macOS]
     const std::vector<facebook::react::BoxShadow> &shadows,
     RCTCornerRadii cornerRadii,
     UIEdgeInsets edgeInsets,

packages/react-native/React/Fabric/Utils/RCTBoxShadow.mm

@@ -281,7 +281,7 @@ static void renderInsetShadows(
   CGContextRestoreGState(context);
 }
 
-RCTPlatformImage *RCTGetBoxShadowImage( // [macOS]
+RCTUIImage *RCTGetBoxShadowImage( // [macOS]
     const std::vector<BoxShadow> &shadows,
     RCTCornerRadii cornerRadii,
     UIEdgeInsets edgeInsets,
@@ -293,7 +293,7 @@ static void renderInsetShadows(
   RCTUIGraphicsImageRenderer *const renderer = [[RCTUIGraphicsImageRenderer alloc] initWithSize:boundingRect.size
                                                                                    format:rendererFormat];
   // macOS]
-  RCTPlatformImage *const boxShadowImage = // [macOS]
+  RCTUIImage *const boxShadowImage = // [macOS]
       [renderer imageWithActions:^(RCTUIGraphicsImageRendererContext *_Nonnull rendererContext) { // [macOS]
         auto [outsetShadows, insetShadows] = splitBoxShadowsByInset(shadows);
         const CGContextRef context = rendererContext.CGContext;

packages/react-native/React/Fabric/Utils/RCTLinearGradient.mm

@@ -20,7 +20,7 @@ + (CALayer *)gradientLayerWithSize:(CGSize)size gradient:(const LinearGradient &
 {
   RCTUIGraphicsImageRenderer *renderer = [[RCTUIGraphicsImageRenderer alloc] initWithSize:size]; // [macOS]
   const auto &direction = gradient.direction;
-  RCTPlatformImage *gradientImage = [renderer imageWithActions:^(RCTUIGraphicsImageRendererContext *_Nonnull rendererContext) { // [macOS]
+  RCTUIImage *gradientImage = [renderer imageWithActions:^(RCTUIGraphicsImageRendererContext *_Nonnull rendererContext) { // [macOS]
     CGPoint startPoint;
     CGPoint endPoint;
 
@@ -65,11 +65,7 @@ + (CALayer *)gradientLayerWithSize:(CGSize)size gradient:(const LinearGradient &
   }];
 
   CALayer *gradientLayer = [CALayer layer];
-#if !TARGET_OS_OSX // [macOS]
-  gradientLayer.contents = (__bridge id)gradientImage.CGImage;
-#else // [macOS
-  gradientLayer.contents = (__bridge id)UIImageGetCGImageRef(gradientImage);
-#endif // macOS]
+  gradientLayer.contents = (id)gradientImage.CGImage;
 
   return gradientLayer;
 }

packages/react-native/React/Views/RCTBorderDrawing.h

@@ -62,7 +62,7 @@ RCTPathCreateWithRoundedRect(CGRect bounds, RCTCornerInsets cornerInsets, const
  * `borderInsets` defines the border widths for each edge.
  * `scaleFactor` defines the backing scale factor of the device for supporting high-resolution drawing. // [macOS]
  */
-RCT_EXTERN RCTPlatformImage *RCTGetBorderImage( // [macOS]
+RCT_EXTERN RCTUIImage *RCTGetBorderImage( // [macOS]
     RCTBorderStyle borderStyle,
     CGSize viewSize,
     RCTCornerRadii cornerRadii,

packages/react-native/React/Views/RCTBorderDrawing.m

@@ -191,7 +191,7 @@ static CGPathRef RCTPathCreateOuterOutline(BOOL drawToEdge, CGRect rect, RCTCorn
   return renderer;
 }
 
-static RCTPlatformImage *RCTGetSolidBorderImage( // [macOS]
+static RCTUIImage *RCTGetSolidBorderImage( // [macOS]
     RCTCornerRadii cornerRadii,
     CGSize viewSize,
     UIEdgeInsets borderInsets,
@@ -231,7 +231,7 @@ static CGPathRef RCTPathCreateOuterOutline(BOOL drawToEdge, CGRect rect, RCTCorn
 
   RCTUIGraphicsImageRenderer *const imageRenderer =
       RCTMakeUIGraphicsImageRenderer(size, backgroundColor, hasCornerRadii, drawToEdge);
-  RCTPlatformImage *image = [imageRenderer imageWithActions:^(RCTUIGraphicsImageRendererContext *_Nonnull rendererContext) { // [macOS]
+  RCTUIImage *image = [imageRenderer imageWithActions:^(RCTUIGraphicsImageRendererContext *_Nonnull rendererContext) { // [macOS]
     const CGContextRef context = rendererContext.CGContext;
     const CGRect rect = {.size = size};
     CGPathRef path = RCTPathCreateOuterOutline(drawToEdge, rect, cornerRadii);
@@ -461,7 +461,7 @@ static CGPathRef RCTPathCreateOuterOutline(BOOL drawToEdge, CGRect rect, RCTCorn
 // of gradients _along_ a path (NB: clipping a path and drawing a linear gradient
 // is _not_ equivalent).
 
-static RCTPlatformImage *RCTGetDashedOrDottedBorderImage( // [macOS]
+static RCTUIImage *RCTGetDashedOrDottedBorderImage( // [macOS]
     RCTBorderStyle borderStyle,
     RCTCornerRadii cornerRadii,
     CGSize viewSize,
@@ -525,7 +525,7 @@ static CGPathRef RCTPathCreateOuterOutline(BOOL drawToEdge, CGRect rect, RCTCorn
   }];
 }
 
-RCTPlatformImage *RCTGetBorderImage( // [macOS]
+RCTUIImage *RCTGetBorderImage( // [macOS]
     RCTBorderStyle borderStyle,
     CGSize viewSize,
     RCTCornerRadii cornerRadii,

packages/react-native/React/Views/RCTView.m

@@ -1269,7 +1269,7 @@ - (void)displayLayer:(CALayer *)layer
     return;
   }
 
-  RCTPlatformImage *image = RCTGetBorderImage( // [macOS]
+  RCTUIImage *image = RCTGetBorderImage( // [macOS]
       _borderStyle, layer.bounds.size, cornerRadii, borderInsets, borderColors, backgroundColor, self.clipsToBounds);
 
   layer.backgroundColor = NULL;