@onekeyfe/react-native-image 3.0.155 → 3.0.157-alpha.248

package/ios/OneKeyImageMemoryVariants.swift

@@ -0,0 +1,137 @@
+import Foundation
+
+struct OneKeyImageMemoryFamilyKey: Hashable, Sendable {
+  let rawURL: URL
+  let headersDigest: String?
+
+  init(rawURL: URL, headersJson: String?) {
+    self.rawURL = rawURL
+    headersDigest =
+      OneKeyImageHeadersIdentity(
+        headers: OneKeyImageRequestContext.headers(from: headersJson)
+      ).cacheKeyComponent
+  }
+}
+
+struct OneKeyImageMemoryVariant: Hashable, Sendable {
+  let requestURL: URL
+  let pixelWidth: Int
+  let pixelHeight: Int
+
+  init(requestURL: URL, thumbnailPixelSize: CGSize) {
+    self.requestURL = requestURL
+    pixelWidth = max(Int(thumbnailPixelSize.width.rounded()), 1)
+    pixelHeight = max(Int(thumbnailPixelSize.height.rounded()), 1)
+  }
+
+  var thumbnailPixelSize: CGSize {
+    CGSize(width: pixelWidth, height: pixelHeight)
+  }
+
+  var area: Int64 { Int64(pixelWidth) * Int64(pixelHeight) }
+}
+
+/// Bounded hints for reproducing size-specific SDWebImage memory-cache keys.
+/// SDImageCache remains authoritative; stale hints are removed on probe miss.
+final class OneKeyImageMemoryVariantRegistry: @unchecked Sendable {
+  static let shared = OneKeyImageMemoryVariantRegistry()
+
+  private static let maximumFamilies = 1024
+  private static let maximumVariantsPerFamily = 8
+  private static let maximumAspectRatioDrift = 1.1
+
+  private let lock = NSLock()
+  private var variantsByFamily: [OneKeyImageMemoryFamilyKey: [OneKeyImageMemoryVariant]] = [:]
+  private var familyAccessOrder: [OneKeyImageMemoryFamilyKey] = []
+
+  func record(_ variant: OneKeyImageMemoryVariant, for family: OneKeyImageMemoryFamilyKey) {
+    lock.lock()
+    defer { lock.unlock() }
+    var variants = variantsByFamily[family] ?? []
+    variants.removeAll { $0 == variant }
+    variants.append(variant)
+    if variants.count > Self.maximumVariantsPerFamily {
+      variants.removeFirst(variants.count - Self.maximumVariantsPerFamily)
+    }
+    variantsByFamily[family] = variants
+    touch(family)
+    while familyAccessOrder.count > Self.maximumFamilies {
+      let oldest = familyAccessOrder.removeFirst()
+      variantsByFamily.removeValue(forKey: oldest)
+    }
+  }
+
+  func remove(_ variant: OneKeyImageMemoryVariant, for family: OneKeyImageMemoryFamilyKey) {
+    lock.lock()
+    defer { lock.unlock() }
+    guard var variants = variantsByFamily[family] else { return }
+    variants.removeAll { $0 == variant }
+    if variants.isEmpty {
+      variantsByFamily.removeValue(forKey: family)
+      familyAccessOrder.removeAll { $0 == family }
+    } else {
+      variantsByFamily[family] = variants
+    }
+  }
+
+  func candidates(
+    for family: OneKeyImageMemoryFamilyKey,
+    target: OneKeyImageMemoryVariant,
+    excluding exactVariants: Set<OneKeyImageMemoryVariant>
+  ) -> [OneKeyImageMemoryVariant] {
+    lock.lock()
+    let variants = variantsByFamily[family] ?? []
+    if !variants.isEmpty { touch(family) }
+    lock.unlock()
+    return Self.orderedCandidates(
+      variants: variants,
+      target: target,
+      excluding: exactVariants
+    )
+  }
+
+  func clear() {
+    lock.lock()
+    variantsByFamily.removeAll()
+    familyAccessOrder.removeAll()
+    lock.unlock()
+  }
+
+  static func orderedCandidates(
+    variants: [OneKeyImageMemoryVariant],
+    target: OneKeyImageMemoryVariant,
+    excluding exactVariants: Set<OneKeyImageMemoryVariant> = []
+  ) -> [OneKeyImageMemoryVariant] {
+    var seen: Set<OneKeyImageMemoryVariant> = []
+    let compatible = variants.reversed().filter {
+      seen.insert($0).inserted && !exactVariants.contains($0) && aspectRatioIsCompatible($0, target)
+    }
+    let larger =
+      compatible
+      .filter { $0.pixelWidth >= target.pixelWidth && $0.pixelHeight >= target.pixelHeight }
+      .min { lhs, rhs in lhs.area < rhs.area }
+    let smaller =
+      compatible
+      .filter { $0.pixelWidth <= target.pixelWidth && $0.pixelHeight <= target.pixelHeight }
+      .max { lhs, rhs in lhs.area < rhs.area }
+    var result: [OneKeyImageMemoryVariant] = []
+    if let larger { result.append(larger) }
+    if let smaller, smaller != larger { result.append(smaller) }
+    return result
+  }
+
+  private static func aspectRatioIsCompatible(
+    _ candidate: OneKeyImageMemoryVariant,
+    _ target: OneKeyImageMemoryVariant
+  ) -> Bool {
+    let candidateRatio = Double(candidate.pixelWidth) / Double(candidate.pixelHeight)
+    let targetRatio = Double(target.pixelWidth) / Double(target.pixelHeight)
+    return max(candidateRatio, targetRatio) / min(candidateRatio, targetRatio)
+      <= maximumAspectRatioDrift
+  }
+
+  private func touch(_ family: OneKeyImageMemoryFamilyKey) {
+    familyAccessOrder.removeAll { $0 == family }
+    familyAccessOrder.append(family)
+  }
+}

package/ios/OneKeyImageRequestContext.swift

@@ -610,17 +610,59 @@ enum OneKeyImageDecodeSizing {
     }
   }
 
-  /// The logical size to probe the memory cache with. Before the first layout
-  /// the host view has no bounds, but the JS side already knows the display
-  /// size through `resizeWidth` (the same hint the prewarm used), so a square
-  /// from it yields the decode-thumbnail key the laid-out view will ask for.
-  /// A cached image can then show on the mount frame instead of a skeleton
-  /// until layout re-probes.
-  static func probeViewSize(bounds: CGSize, resizeWidth: Double?) -> CGSize? {
+  /// The logical display size the TOS rendition is picked for. A preload picks
+  /// it from the long edge of its `resizeWidth`/`resizeHeight` hint, so a view
+  /// carrying the same hint must do the same (before AND after layout) or its
+  /// request URL, and with it the cache key, diverges from what the preload
+  /// stored. Without a hint the laid-out bounds decide; nil before layout.
+  static func tosDisplaySize(
+    bounds: CGSize,
+    resizeWidth: Double?,
+    resizeHeight: Double?
+  ) -> CGFloat? {
+    if let hint = logicalViewSize(width: resizeWidth, height: resizeHeight) {
+      return max(hint.width, hint.height)
+    }
+    let edge = max(bounds.width, bounds.height)
+    return edge.isFinite && edge > 0 ? edge : nil
+  }
+
+  /// Decode-thumbnail sizes worth probing the memory cache with, most specific
+  /// first. The thumbnail size is part of the SDWebImage cache key, so a probe
+  /// only hits when it reproduces the key some earlier load stored under.
+  ///
+  /// - Laid out: exactly the size this view's own request uses (`bounds` +
+  ///   `contentFit`), nothing else.
+  /// - Before layout the bounds are empty, but the JS side already knows the
+  ///   display size through the `resizeWidth` / `resizeHeight` hints (the same
+  ///   fields a preload takes). Two keys can hold the image then: the one the
+  ///   laid-out request will ask for (hint + this view's `contentFit`) and the
+  ///   one a preload stored (hint + `.cover`, see `HybridOneKeyImageCache`).
+  ///   They coincide for a square hint or `.cover`; otherwise both are probed.
+  /// - No bounds and no usable hint: nothing to probe with.
+  static func probeThumbnailPixelSizes(
+    bounds: CGSize,
+    resizeWidth: Double?,
+    resizeHeight: Double?,
+    scale: CGFloat,
+    contentFit: OneKeyImageContentFit
+  ) -> [CGSize] {
     if bounds.width.isFinite, bounds.height.isFinite, bounds.width > 0, bounds.height > 0 {
-      return bounds
+      return thumbnailPixelSize(viewSize: bounds, scale: scale, contentFit: contentFit)
+        .map { [$0] } ?? []
+    }
+    guard let hint = logicalViewSize(width: resizeWidth, height: resizeHeight) else {
+      return []
+    }
+    var sizes: [CGSize] = []
+    for fit in [contentFit, .cover] {
+      if let size = thumbnailPixelSize(viewSize: hint, scale: scale, contentFit: fit),
+        !sizes.contains(size)
+      {
+        sizes.append(size)
+      }
     }
-    return logicalViewSize(width: resizeWidth, height: nil)
+    return sizes
   }
 
   static func thumbnailPixelSize(

package/ios/tests/OneKeyImageInfrastructureTests.swift

@@ -310,31 +310,173 @@ final class OneKeyImageInfrastructureTests: XCTestCase {
     )
   }
 
-  func testMemoryProbeFallsBackToResizeWidthBeforeLayout() throws {
-    // Laid out: the real bounds win, even with a hint.
+  // The pre-layout memory probe is only useful if it reproduces a key some
+  // earlier load stored under. These pin the probe against the two real key
+  // producers: the laid-out render request (bounds + contentFit) and the
+  // preload (logicalViewSize(resizeWidth, resizeHeight) + .cover).
+  private func renderKey(bounds: CGSize, fit: OneKeyImageContentFit) throws -> CGSize {
+    try XCTUnwrap(
+      OneKeyImageDecodeSizing.thumbnailPixelSize(viewSize: bounds, scale: 3, contentFit: fit)
+    )
+  }
+
+  private func preloadKey(width: Double?, height: Double?) throws -> CGSize {
+    try renderKey(
+      bounds: try XCTUnwrap(OneKeyImageDecodeSizing.logicalViewSize(width: width, height: height)),
+      fit: .cover
+    )
+  }
+
+  func testLaidOutProbeUsesExactlyTheRenderRequestKey() throws {
+    let bounds = CGSize(width: 40, height: 64)
+    for fit in [OneKeyImageContentFit.cover, .contain, .fill, .center] {
+      XCTAssertEqual(
+        OneKeyImageDecodeSizing.probeThumbnailPixelSizes(
+          bounds: bounds, resizeWidth: 32, resizeHeight: 48, scale: 3, contentFit: fit
+        ),
+        [try renderKey(bounds: bounds, fit: fit)],
+        "\(fit)"
+      )
+    }
+  }
+
+  func testPreLayoutSquareHintMatchesPreloadAndRenderKeys() throws {
+    // A token icon: resizeWidth only, laid out square, cover. One key, shared
+    // by the preload, the laid-out request and the probe.
+    let sizes = OneKeyImageDecodeSizing.probeThumbnailPixelSizes(
+      bounds: .zero, resizeWidth: 40, resizeHeight: nil, scale: 3, contentFit: .cover
+    )
+    XCTAssertEqual(sizes, [CGSize(width: 120, height: 120)])
+    XCTAssertEqual(sizes, [try preloadKey(width: 40, height: nil)])
+    XCTAssertEqual(sizes, [try renderKey(bounds: CGSize(width: 40, height: 40), fit: .cover)])
+  }
+
+  func testPreLayoutRectangularHintProbesRenderAndPreloadKeys() throws {
+    // The README preload shape (48x64 @3) under a non-cover view: the laid-out
+    // request key comes first, the preload's cover key second, no duplicates.
+    let sizes = OneKeyImageDecodeSizing.probeThumbnailPixelSizes(
+      bounds: .zero, resizeWidth: 48, resizeHeight: 64, scale: 3, contentFit: .contain
+    )
     XCTAssertEqual(
-      OneKeyImageDecodeSizing.probeViewSize(
-        bounds: CGSize(width: 40, height: 64),
-        resizeWidth: 32
+      sizes,
+      [
+        try renderKey(bounds: CGSize(width: 48, height: 64), fit: .contain),
+        try preloadKey(width: 48, height: 64),
+      ]
+    )
+    XCTAssertEqual(sizes, [CGSize(width: 144, height: 192), CGSize(width: 192, height: 192)])
+    // Under cover both collapse to the preload key.
+    XCTAssertEqual(
+      OneKeyImageDecodeSizing.probeThumbnailPixelSizes(
+        bounds: .zero, resizeWidth: 48, resizeHeight: 64, scale: 3, contentFit: .cover
       ),
-      CGSize(width: 40, height: 64)
+      [try preloadKey(width: 48, height: 64)]
     )
-    // Not laid out yet: a square from the hint, matching the prewarm key.
-    let probe = try XCTUnwrap(
-      OneKeyImageDecodeSizing.probeViewSize(bounds: .zero, resizeWidth: 40)
+  }
+
+  func testPreLayoutProbeWithoutHintHasNothingToTry() {
+    XCTAssertEqual(
+      OneKeyImageDecodeSizing.probeThumbnailPixelSizes(
+        bounds: .zero, resizeWidth: nil, resizeHeight: nil, scale: 3, contentFit: .cover
+      ),
+      []
     )
-    XCTAssertEqual(probe, CGSize(width: 40, height: 40))
     XCTAssertEqual(
-      OneKeyImageDecodeSizing.thumbnailPixelSize(viewSize: probe, scale: 3, contentFit: .cover),
-      OneKeyImageDecodeSizing.thumbnailPixelSize(
-        viewSize: try XCTUnwrap(OneKeyImageDecodeSizing.logicalViewSize(width: 40, height: nil)),
-        scale: 3,
-        contentFit: .cover
+      OneKeyImageDecodeSizing.probeThumbnailPixelSizes(
+        bounds: .zero, resizeWidth: 0, resizeHeight: -1, scale: 3, contentFit: .cover
+      ),
+      []
+    )
+  }
+
+  func testMemoryVariantsChooseNearestLargerThenNearestSmaller() {
+    let target = memoryVariant(96)
+    XCTAssertEqual(
+      OneKeyImageMemoryVariantRegistry.orderedCandidates(
+        variants: [memoryVariant(48), memoryVariant(72), memoryVariant(120), memoryVariant(144)],
+        target: target
+      ),
+      [memoryVariant(120), memoryVariant(72)]
+    )
+  }
+
+  func testMemoryVariantsIgnoreExactAndIncompatibleAspectRatios() {
+    let target = memoryVariant(96)
+    let wide = OneKeyImageMemoryVariant(
+      requestURL: URL(string: "https://example.com/wide.png")!,
+      thumbnailPixelSize: CGSize(width: 120, height: 60)
+    )
+    XCTAssertEqual(
+      OneKeyImageMemoryVariantRegistry.orderedCandidates(
+        variants: [target, wide, memoryVariant(120)],
+        target: target,
+        excluding: [target]
+      ),
+      [memoryVariant(120)]
+    )
+  }
+
+  func testCrossSizeCenterPreviewUsesTemporaryScaling() {
+    XCTAssertTrue(
+      HybridOneKeyImage.shouldScaleCenterMemoryPreview(
+        contentFit: .center,
+        candidate: memoryVariant(48),
+        target: memoryVariant(96)
+      )
+    )
+    XCTAssertTrue(
+      HybridOneKeyImage.shouldScaleCenterMemoryPreview(
+        contentFit: .center,
+        candidate: memoryVariant(144),
+        target: memoryVariant(96)
+      )
+    )
+    XCTAssertFalse(
+      HybridOneKeyImage.shouldScaleCenterMemoryPreview(
+        contentFit: .center,
+        candidate: memoryVariant(96),
+        target: memoryVariant(96)
+      )
+    )
+    XCTAssertFalse(
+      HybridOneKeyImage.shouldScaleCenterMemoryPreview(
+        contentFit: .cover,
+        candidate: memoryVariant(48),
+        target: memoryVariant(96)
+      )
+    )
+  }
+
+  func testReplacingMemoryPreviewSkipsWholeViewFade() {
+    XCTAssertFalse(
+      HybridOneKeyImage.shouldAnimateLoadedImageTransition(
+        cacheType: .disk,
+        requestDuration: 1,
+        reduceMotionEnabled: false,
+        replacingMemoryPreview: true
+      )
+    )
+    XCTAssertTrue(
+      HybridOneKeyImage.shouldAnimateLoadedImageTransition(
+        cacheType: .disk,
+        requestDuration: 1,
+        reduceMotionEnabled: false,
+        replacingMemoryPreview: false
       )
     )
-    // No bounds and no usable hint: nothing to probe with.
-    XCTAssertNil(OneKeyImageDecodeSizing.probeViewSize(bounds: .zero, resizeWidth: nil))
-    XCTAssertNil(OneKeyImageDecodeSizing.probeViewSize(bounds: .zero, resizeWidth: 0))
+  }
+
+  private func memoryVariant(_ size: Int) -> OneKeyImageMemoryVariant {
+    OneKeyImageMemoryVariant(
+      requestURL: URL(string: "https://example.com/image-\(size).png")!,
+      thumbnailPixelSize: CGSize(width: size, height: size)
+    )
+  }
+
+  func testDisplayedImageIsPreservedOnlyWhileShowingOne() {
+    XCTAssertTrue(HybridOneKeyImage.shouldPreserveDisplayedImage(isShowingImage: true, hasImage: true))
+    XCTAssertFalse(HybridOneKeyImage.shouldPreserveDisplayedImage(isShowingImage: true, hasImage: false))
+    XCTAssertFalse(HybridOneKeyImage.shouldPreserveDisplayedImage(isShowingImage: false, hasImage: true))
   }
 
   func testNoSizePreloadUsesCappedDecodeTarget() {
@@ -571,6 +713,55 @@ final class OneKeyImageInfrastructureTests: XCTestCase {
     )
   }
 
+  func testRecycledViewForgetsBothResizeHints() throws {
+    let image = HybridOneKeyImage()
+    image.sourceUri = "https://example.com/hinted.png"
+    image.resizeWidth = 48
+    image.resizeHeight = 64
+    image.prepareForRecycle()
+    XCTAssertNil(image.resizeWidth)
+    XCTAssertNil(image.resizeHeight)
+    XCTAssertNil(image.sourceUri)
+  }
+
+  func testViewAndPreloadPickTheSameTosRenditionForOneHint() throws {
+    // Preload: long edge of logicalViewSize(resizeWidth, resizeHeight).
+    // View: the same, before and after layout, so the request URL (and with it
+    // the cache key) is identical on both sides.
+    let raw = try XCTUnwrap(URL(string: "https://common.onekey-asset.com/token.png"))
+    let hint = try XCTUnwrap(OneKeyImageDecodeSizing.logicalViewSize(width: 48, height: 64))
+    let preloadDisplaySize = max(hint.width, hint.height)
+    for bounds in [CGSize.zero, CGSize(width: 48, height: 64), CGSize(width: 30, height: 30)] {
+      let viewDisplaySize = try XCTUnwrap(
+        OneKeyImageDecodeSizing.tosDisplaySize(bounds: bounds, resizeWidth: 48, resizeHeight: 64)
+      )
+      XCTAssertEqual(viewDisplaySize, preloadDisplaySize)
+      XCTAssertEqual(
+        OneKeyTosURL.optimized(
+          rawURL: raw, displaySize: viewDisplaySize, scale: 3, overscan: 1.1, hasCustomIdentity: false
+        ),
+        OneKeyTosURL.optimized(
+          rawURL: raw, displaySize: preloadDisplaySize, scale: 3, overscan: 1.1, hasCustomIdentity: false
+        )
+      )
+    }
+    // Width-only hint keeps the historical behaviour (the width itself).
+    XCTAssertEqual(
+      OneKeyImageDecodeSizing.tosDisplaySize(bounds: .zero, resizeWidth: 40, resizeHeight: nil),
+      40
+    )
+    // No hint: the laid-out bounds decide; nothing before layout.
+    XCTAssertEqual(
+      OneKeyImageDecodeSizing.tosDisplaySize(
+        bounds: CGSize(width: 40, height: 64), resizeWidth: nil, resizeHeight: nil
+      ),
+      64
+    )
+    XCTAssertNil(
+      OneKeyImageDecodeSizing.tosDisplaySize(bounds: .zero, resizeWidth: nil, resizeHeight: nil)
+    )
+  }
+
   func testSupersededRequestNeverPaintsRecycledView() throws {
     let image = HybridOneKeyImage()
     let imageView = try XCTUnwrap(image.view as? SDAnimatedImageView)
@@ -592,4 +783,50 @@ final class OneKeyImageInfrastructureTests: XCTestCase {
     )
     XCTAssertTrue(imageView.clearBufferWhenStopped)
   }
+
+  func testRoundPropUpdatesNativeCornerRadius() throws {
+    let image = HybridOneKeyImage()
+    let imageView = try XCTUnwrap(image.view as? SDAnimatedImageView)
+    imageView.frame = CGRect(x: 0, y: 0, width: 40, height: 40)
+
+    image.sourceUri = "https://example.com/round.png"
+    image.round = true
+    image.afterUpdate()
+    imageView.layoutIfNeeded()
+    XCTAssertEqual(imageView.layer.cornerRadius, 20)
+
+    image.round = nil
+    image.afterUpdate()
+    XCTAssertEqual(imageView.layer.cornerRadius, 20)
+
+    image.round = false
+    image.afterUpdate()
+    XCTAssertEqual(imageView.layer.cornerRadius, 0)
+  }
+
+  func testRecycleKeepsRoundMaskUntilVisibleViewDetaches() throws {
+    let window = UIWindow(frame: CGRect(x: 0, y: 0, width: 100, height: 100))
+    let image = HybridOneKeyImage()
+    let imageView = try XCTUnwrap(image.view as? SDAnimatedImageView)
+    imageView.frame = CGRect(x: 0, y: 0, width: 40, height: 40)
+    window.addSubview(imageView)
+    image.sourceUri = "https://example.com/round.png"
+    image.round = true
+    image.afterUpdate()
+    imageView.layoutIfNeeded()
+
+    // Fabric resets props in setter order before the view leaves the hierarchy.
+    image.round = false
+    image.sourceUri = nil
+    image.afterUpdate()
+    XCTAssertEqual(imageView.layer.cornerRadius, 20)
+
+    image.prepareForRecycle()
+
+    XCTAssertEqual(imageView.layer.cornerRadius, 20)
+
+    image.sourceUri = "https://example.com/reused.png"
+    image.afterUpdate()
+    XCTAssertEqual(imageView.layer.cornerRadius, 0)
+  }
 }

package/lib/module/index.js

@@ -44,7 +44,9 @@ export function OneKeyImage({
   autoplay,
   recyclingKey,
   optimizeTos = true,
+  round = false,
   resizeWidth,
+  resizeHeight,
   overscan = 1.1,
   loadingStrategy = OneKeyImageLoadingStrategy.STATIC,
   placeholderColor,
@@ -59,7 +61,7 @@ export function OneKeyImage({
 }) {
   const normalized = useMemo(() => normalizeSource(source), [source]);
   const resolvedCachePolicy = cachePolicy ?? normalized?.cachePolicy ?? OneKeyImageCachePolicy.MEMORY_DISK;
-  const identity = `${normalized?.uri ?? ''}|${JSON.stringify(normalized?.headers ?? {})}|${resolvedCachePolicy}|${recyclingKey ?? ''}|${contentFit}|${optimizeTos ? '1' : '0'}|${resizeWidth ?? ''}|${overscan}`;
+  const identity = `${normalized?.uri ?? ''}|${JSON.stringify(normalized?.headers ?? {})}|${resolvedCachePolicy}|${recyclingKey ?? ''}|${contentFit}|${optimizeTos ? '1' : '0'}|${resizeWidth ?? ''}|${resizeHeight ?? ''}|${overscan}`;
   const hasSource = normalized != null;
   const hasOverlay = placeholder != null || fallback != null;
   const [loadState, setLoadState] = useState({
@@ -198,7 +200,8 @@ export function OneKeyImage({
     borderStartEndRadius: flattenedStyle.borderStartEndRadius,
     borderEndStartRadius: flattenedStyle.borderEndStartRadius,
     borderEndEndRadius: flattenedStyle.borderEndEndRadius,
-    zIndex: 1
+    zIndex: 1,
+    ...(round ? ROUND_CLIP : null)
   } : undefined;
   const native = /*#__PURE__*/createElement(NativeOneKeyImage, {
     ...viewProps,
@@ -212,14 +215,16 @@ export function OneKeyImage({
     autoplay: autoplay ?? Platform.OS !== 'android',
     recyclingKey,
     optimizeTos,
+    round,
     resizeWidth,
+    resizeHeight,
     overscan,
     loadingStrategy: placeholder == null ? loadingStrategy : OneKeyImageLoadingStrategy.NONE,
     placeholderColor
   });
   if (!shouldWrapNative) return native;
   return /*#__PURE__*/_jsxs(View, {
-    style: [style, styles.overlayContainer, hasRoundedCorners ? styles.borderlessContainer : undefined],
+    style: [style, styles.overlayContainer, hasRoundedCorners ? styles.borderlessContainer : undefined, round ? ROUND_CLIP : undefined],
     collapsable: false,
     children: [native, effectiveState === 'loading' && placeholder != null ? /*#__PURE__*/_jsx(View, {
       pointerEvents: "none",
@@ -255,6 +260,24 @@ export const OneKeyImageCache = {
   clearDisk: () => nativeCache.clearDisk(),
   clearAll: () => nativeCache.clearAll()
 };
+
+// `round` clips the native view to a circle: an oval path on Android
+// (`OneKeyImage.kt` `addOval`), a `min(width, height) / 2` corner radius on iOS
+// (`OneKeyImage.swift` `updateRoundMask`). The overlay container has to clip the
+// same way, or a custom placeholder or fallback is painted square over a round
+// image. A percentage radius says that without measuring the view, and covers
+// every per-corner radius the caller's own style may have set.
+const ROUND_CLIP = {
+  borderRadius: '50%',
+  borderTopLeftRadius: '50%',
+  borderTopRightRadius: '50%',
+  borderBottomLeftRadius: '50%',
+  borderBottomRightRadius: '50%',
+  borderStartStartRadius: '50%',
+  borderStartEndRadius: '50%',
+  borderEndStartRadius: '50%',
+  borderEndEndRadius: '50%'
+};
 const styles = StyleSheet.create({
   overlayContainer: {
     overflow: 'hidden'

package/lib/nitrogen/generated/android/c++/JHybridOneKeyImageSpec.cpp

@@ -138,6 +138,15 @@ namespace margelo::nitro::onekeyimage {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JBoolean> /* optimizeTos */)>("setOptimizeTos");
     method(_javaPart, optimizeTos.has_value() ? jni::JBoolean::valueOf(optimizeTos.value()) : nullptr);
   }
+  std::optional<bool> JHybridOneKeyImageSpec::getRound() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JBoolean>()>("getRound");
+    auto __result = method(_javaPart);
+    return __result != nullptr ? std::make_optional(static_cast<bool>(__result->value())) : std::nullopt;
+  }
+  void JHybridOneKeyImageSpec::setRound(std::optional<bool> round) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JBoolean> /* round */)>("setRound");
+    method(_javaPart, round.has_value() ? jni::JBoolean::valueOf(round.value()) : nullptr);
+  }
   std::optional<double> JHybridOneKeyImageSpec::getResizeWidth() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JDouble>()>("getResizeWidth");
     auto __result = method(_javaPart);
@@ -147,6 +156,15 @@ namespace margelo::nitro::onekeyimage {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JDouble> /* resizeWidth */)>("setResizeWidth");
     method(_javaPart, resizeWidth.has_value() ? jni::JDouble::valueOf(resizeWidth.value()) : nullptr);
   }
+  std::optional<double> JHybridOneKeyImageSpec::getResizeHeight() {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JDouble>()>("getResizeHeight");
+    auto __result = method(_javaPart);
+    return __result != nullptr ? std::make_optional(__result->value()) : std::nullopt;
+  }
+  void JHybridOneKeyImageSpec::setResizeHeight(std::optional<double> resizeHeight) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<jni::JDouble> /* resizeHeight */)>("setResizeHeight");
+    method(_javaPart, resizeHeight.has_value() ? jni::JDouble::valueOf(resizeHeight.value()) : nullptr);
+  }
   std::optional<double> JHybridOneKeyImageSpec::getOverscan() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<jni::JDouble>()>("getOverscan");
     auto __result = method(_javaPart);

package/lib/nitrogen/generated/android/c++/JHybridOneKeyImageSpec.hpp

@@ -66,8 +66,12 @@ namespace margelo::nitro::onekeyimage {
     void setRecyclingKey(const std::optional<std::string>& recyclingKey) override;
     std::optional<bool> getOptimizeTos() override;
     void setOptimizeTos(std::optional<bool> optimizeTos) override;
+    std::optional<bool> getRound() override;
+    void setRound(std::optional<bool> round) override;
     std::optional<double> getResizeWidth() override;
     void setResizeWidth(std::optional<double> resizeWidth) override;
+    std::optional<double> getResizeHeight() override;
+    void setResizeHeight(std::optional<double> resizeHeight) override;
     std::optional<double> getOverscan() override;
     void setOverscan(std::optional<double> overscan) override;
     std::optional<OneKeyImageLoadingStrategy> getLoadingStrategy() override;

package/lib/nitrogen/generated/android/c++/views/JHybridOneKeyImageStateUpdater.cpp

@@ -93,11 +93,21 @@ void JHybridOneKeyImageStateUpdater::updateViewProps(jni::alias_ref<jni::JClass>
         : !newProps->optimizeTos.hasSameValue(oldProps->optimizeTos)) {
     hybridView->setOptimizeTos(newProps->optimizeTos.get());
   }
+  if (oldProps == nullptr
+        ? newProps->round.isProvided()
+        : !newProps->round.hasSameValue(oldProps->round)) {
+    hybridView->setRound(newProps->round.get());
+  }
   if (oldProps == nullptr
         ? newProps->resizeWidth.isProvided()
         : !newProps->resizeWidth.hasSameValue(oldProps->resizeWidth)) {
     hybridView->setResizeWidth(newProps->resizeWidth.get());
   }
+  if (oldProps == nullptr
+        ? newProps->resizeHeight.isProvided()
+        : !newProps->resizeHeight.hasSameValue(oldProps->resizeHeight)) {
+    hybridView->setResizeHeight(newProps->resizeHeight.get());
+  }
   if (oldProps == nullptr
         ? newProps->overscan.isProvided()
         : !newProps->overscan.hasSameValue(oldProps->overscan)) {

package/lib/nitrogen/generated/android/kotlin/com/margelo/nitro/onekeyimage/HybridOneKeyImageSpec.kt

@@ -75,12 +75,24 @@ abstract class HybridOneKeyImageSpec: HybridView() {
   @set:Keep
   abstract var optimizeTos: Boolean?
   
+  @get:DoNotStrip
+  @get:Keep
+  @set:DoNotStrip
+  @set:Keep
+  abstract var round: Boolean?
+  
   @get:DoNotStrip
   @get:Keep
   @set:DoNotStrip
   @set:Keep
   abstract var resizeWidth: Double?
   
+  @get:DoNotStrip
+  @get:Keep
+  @set:DoNotStrip
+  @set:Keep
+  abstract var resizeHeight: Double?
+  
   @get:DoNotStrip
   @get:Keep
   @set:DoNotStrip