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

package/README.md

@@ -5,6 +5,9 @@ native loading placeholders, opt-in shared-renderer skeleton, fallback states,
 cache controls,
 and conservative OneKey TOS URL resizing without depending on Expo Image.
 
+The authoritative lifecycle, cache identity, cross-size memory-preview, safety,
+and platform contract is defined in [docs/SPEC.md](docs/SPEC.md).
+
 ```tsx
 <OneKeyImage
   source={{ uri: 'https://example.com/avatar.png' }}

package/android/src/main/java/com/margelo/nitro/onekeyimage/OneKeyImage.kt

@@ -7,7 +7,9 @@ import android.content.ContextWrapper
 import android.content.res.Configuration
 import android.graphics.Canvas
 import android.graphics.Color
+import android.graphics.Outline
 import android.graphics.Paint
+import android.graphics.Path
 import android.graphics.drawable.Animatable
 import android.graphics.drawable.Drawable
 import android.os.Build
@@ -15,6 +17,7 @@ import android.os.Looper
 import android.os.SystemClock
 import android.provider.Settings
 import android.view.View
+import android.view.ViewOutlineProvider
 import android.view.animation.DecelerateInterpolator
 import android.widget.ImageView
 import com.bumptech.glide.Glide
@@ -23,6 +26,7 @@ import com.bumptech.glide.load.engine.DiskCacheStrategy
 import com.bumptech.glide.load.engine.GlideException
 import com.bumptech.glide.request.RequestListener
 import com.bumptech.glide.request.RequestOptions
+import com.bumptech.glide.request.target.CustomTarget
 import com.bumptech.glide.request.target.CustomViewTarget
 import com.bumptech.glide.request.target.Target
 import com.bumptech.glide.request.transition.Transition
@@ -43,7 +47,45 @@ private fun Context.findActivity(): Activity? {
   return currentContext as? Activity
 }
 
+internal fun shouldScaleCenterMemoryPreview(
+  contentFit: OneKeyImageContentFit,
+  candidate: OneKeyImageMemoryVariant,
+  target: OneKeyImageMemoryVariant,
+): Boolean =
+  contentFit == OneKeyImageContentFit.CENTER &&
+    (candidate.width != target.width || candidate.height != target.height)
+
+internal fun shouldProbeMemoryPreview(
+  hasTarget: Boolean,
+  sameFamily: Boolean,
+  hasDrawable: Boolean,
+): Boolean = !hasTarget || !sameFamily || !hasDrawable
+
+internal fun shouldAnimateLoadedImageTransition(
+  cacheType: OneKeyImageCacheType,
+  fadeDelayElapsed: Boolean,
+  animationsEnabled: Boolean,
+  replacingMemoryPreview: Boolean,
+): Boolean =
+  !replacingMemoryPreview && cacheType != OneKeyImageCacheType.MEMORY &&
+    fadeDelayElapsed && animationsEnabled
+
+internal fun memoryProbeRequestOptions(base: RequestOptions): RequestOptions =
+  base
+    .diskCacheStrategy(DiskCacheStrategy.NONE)
+    .onlyRetrieveFromCache(true)
+
 private class OneKeyImageHostView(context: ThemedReactContext) : ImageView(context) {
+  private val roundClipPath = Path()
+  private val roundOutlineProvider = object : ViewOutlineProvider() {
+    override fun getOutline(view: View, outline: Outline) {
+      if (view.width > 0 && view.height > 0) {
+        outline.setOval(0, 0, view.width, view.height)
+      } else {
+        outline.setEmpty()
+      }
+    }
+  }
   private val fallbackPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
     color = Color.rgb(110, 110, 120)
     textAlign = Paint.Align.CENTER
@@ -52,6 +94,16 @@ private class OneKeyImageHostView(context: ThemedReactContext) : ImageView(conte
   var drawStateSymbol = false
   var stateSymbol = "◇"
   var autoplayEnabled = false
+  var round = false
+    set(value) {
+      if (field == value) return
+      field = value
+      outlineProvider = if (value) roundOutlineProvider else ViewOutlineProvider.BACKGROUND
+      clipToOutline = value
+      updateRoundClipPath()
+      invalidateOutline()
+      invalidate()
+    }
   private var aggregatedVisible = true
   var skeletonRequested = false
     set(value) {
@@ -65,9 +117,24 @@ private class OneKeyImageHostView(context: ThemedReactContext) : ImageView(conte
     super.onSizeChanged(w, h, oldw, oldh)
     skeleton.updateBounds(w, h)
     fallbackPaint.textSize = minOf(w, h) * 0.35f
+    if (round) {
+      updateRoundClipPath()
+      invalidateOutline()
+    }
     if (w > 0 && h > 0) onReadyForRequest?.invoke()
   }
 
+  override fun draw(canvas: Canvas) {
+    if (!round || roundClipPath.isEmpty) {
+      super.draw(canvas)
+      return
+    }
+    val saveCount = canvas.save()
+    canvas.clipPath(roundClipPath)
+    super.draw(canvas)
+    canvas.restoreToCount(saveCount)
+  }
+
   override fun onDraw(canvas: Canvas) {
     super.onDraw(canvas)
     if (drawStateSymbol) {
@@ -108,6 +175,13 @@ private class OneKeyImageHostView(context: ThemedReactContext) : ImageView(conte
     skeleton.updateBounds(width, height)
   }
 
+  private fun updateRoundClipPath() {
+    roundClipPath.reset()
+    if (round && width > 0 && height > 0) {
+      roundClipPath.addOval(0f, 0f, width.toFloat(), height.toFloat(), Path.Direction.CW)
+    }
+  }
+
   fun syncPlayback() {
     val canRun = isAttachedToWindow && aggregatedVisible
     if (skeletonRequested && canRun) skeleton.start() else skeleton.stop()
@@ -130,10 +204,12 @@ internal fun oneKeyImageRequestSignature(
   contentFit: OneKeyImageContentFit?,
   optimizeTos: Boolean?,
   overscan: Double?,
+  round: Boolean,
   width: Int,
   height: Int,
   density: Float,
   resizeWidth: Double? = null,
+  resizeHeight: Double? = null,
 ): String = listOf(
   rawUrl,
   sourceHeadersJson.orEmpty(),
@@ -142,7 +218,9 @@ internal fun oneKeyImageRequestSignature(
   (contentFit ?: OneKeyImageContentFit.COVER).name,
   optimizeTos.toString(),
   overscan.toString(),
+  round.toString(),
   resizeWidth.toString(),
+  resizeHeight.toString(),
   width.toString(),
   height.toString(),
   density.toString(),
@@ -166,12 +244,16 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
   }
   private var loadRunnable: Runnable? = null
   private var currentTarget: CustomViewTarget<OneKeyImageHostView, Drawable>? = null
+  private var memoryPreviewTarget: CustomTarget<Drawable>? = null
+  private var memoryPreviewFamily: OneKeyImageMemoryFamilyKey? = null
+  private var scalesCenterMemoryPreview = false
   private var generation = 0L
   private var lastSignature: String? = null
   private var disposed = false
   private var suppressPropEffects = false
   private var requestActive = false
   private var displayState = DisplayState.LOADING
+  private var isPreservingDisplayedImage = false
   private var displayRunnable: Runnable? = null
   private var pendingDisplayGeneration: Long? = null
   private var fallbackRunnable: Runnable? = null
@@ -241,6 +323,10 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
       field = value
       requestIdentityChanged()
     }
+  override var round: Boolean? = false
+    set(value) {
+      field = value
+    }
   override var overscan: Double? = 1.1
     set(value) {
       if (field == value) return
@@ -253,6 +339,14 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
       field = value
       requestIdentityChanged()
     }
+  // Layout hint pair with resizeWidth; the pre-layout memory probe uses both
+  // values to reproduce a preload's physical decode size.
+  override var resizeHeight: Double? = null
+    set(value) {
+      if (field == value) return
+      field = value
+      requestIdentityChanged()
+    }
   override var loadingStrategy: OneKeyImageLoadingStrategy? = OneKeyImageLoadingStrategy.STATIC
     set(value) {
       field = value
@@ -287,6 +381,10 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
 
   override fun afterUpdate() {
     super.afterUpdate()
+    // Fabric can reset `round` before clearing `sourceUri` while removing a view.
+    // Apply the shape once per committed prop batch so the outgoing frame keeps
+    // its clipping, while mounted and recycled views still receive the new value.
+    if (!sourceUri.isNullOrBlank()) hostView.round = round == true
     loadForCurrentLayout()
   }
 
@@ -330,7 +428,11 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     if (suppressPropEffects || disposed) return
     lastSignature = null
     cancelCurrent(invalidateGeneration = true)
-    if (sourceUri.isNullOrBlank()) showFallback() else showLoading(requestIsActive = false)
+    if (sourceUri.isNullOrBlank()) {
+      showFallback()
+    } else if (!showMemoryCachedPreviewBeforeLayout()) {
+      showLoading(requestIsActive = false)
+    }
     scheduleLoad()
   }
 
@@ -346,7 +448,9 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     autoplay = false
     recyclingKey = null
     optimizeTos = true
+    round = false
     resizeWidth = null
+    resizeHeight = null
     overscan = 1.1
     loadingStrategy = OneKeyImageLoadingStrategy.STATIC
     placeholderColor = null
@@ -358,6 +462,7 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     suppressPropEffects = false
     requestActive = false
     displayState = DisplayState.LOADING
+    isPreservingDisplayedImage = false
     hostView.setImageDrawable(null)
     hostView.drawStateSymbol = false
     hostView.skeletonRequested = false
@@ -393,12 +498,147 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     }
   }
 
+  private fun showMemoryCachedPreviewBeforeLayout(): Boolean {
+    if (Looper.myLooper() != Looper.getMainLooper()) return false
+    val rawUrl = sourceUri?.takeIf { it.isNotBlank() } ?: return false
+    val policy = cachePolicy ?: OneKeyImageCachePolicy.MEMORY_DISK
+    if (
+      policy != OneKeyImageCachePolicy.MEMORY &&
+      policy != OneKeyImageCachePolicy.MEMORY_DISK
+    ) {
+      return false
+    }
+    val displayWidth = resizeWidth?.takeIf { it.isFinite() && it > 0.0 }
+    val displayHeight = resizeHeight?.takeIf { it.isFinite() && it > 0.0 }
+    if (displayWidth == null && displayHeight == null) return false
+    val density = hostView.resources.displayMetrics.density.coerceAtLeast(1f)
+    val displaySize = when {
+      displayWidth != null && displayHeight != null -> maxOf(displayWidth, displayHeight)
+      displayWidth != null -> displayWidth
+      else -> requireNotNull(displayHeight)
+    }
+    val customIdentity = OneKeyImageModel.headers(sourceHeadersJson).isNotEmpty()
+    val requestUrl = if (optimizeTos != false) {
+      OneKeyTosUrl.optimized(
+        rawUrl,
+        ceil(displaySize).toInt(),
+        density,
+        overscan ?: 1.1,
+        customIdentity,
+      )
+    } else rawUrl
+    val dimensions = OneKeyImageDecodeDimensions.forPreload(
+      displayWidth,
+      displayHeight,
+      density.toDouble(),
+    )
+    return showMemoryCachedPreview(
+      family = OneKeyImageMemoryFamilyKey.from(rawUrl, sourceHeadersJson),
+      exactVariant = OneKeyImageMemoryVariant(
+        requestUrl = requestUrl,
+        width = dimensions.width,
+        height = dimensions.height,
+        round = round == true,
+      ),
+      includeExact = true,
+      policy = policy,
+      requestGeneration = generation,
+    )
+  }
+
+  private fun showMemoryCachedPreview(
+    family: OneKeyImageMemoryFamilyKey,
+    exactVariant: OneKeyImageMemoryVariant,
+    includeExact: Boolean,
+    policy: OneKeyImageCachePolicy,
+    requestGeneration: Long,
+  ): Boolean {
+    if (
+      Looper.myLooper() != Looper.getMainLooper() ||
+      disposed ||
+      requestGeneration != generation ||
+      (policy != OneKeyImageCachePolicy.MEMORY &&
+        policy != OneKeyImageCachePolicy.MEMORY_DISK)
+    ) {
+      return false
+    }
+    val candidates = buildList {
+      if (includeExact) {
+        add(exactVariant)
+        if (exactVariant.requestUrl != family.rawUrl) {
+          add(exactVariant.copy(requestUrl = family.rawUrl))
+        }
+      }
+      addAll(OneKeyImageMemoryVariantRegistry.candidates(family, exactVariant))
+    }.distinct()
+
+    for (candidate in candidates) {
+      var synchronousResource: Drawable? = null
+      val target = object : CustomTarget<Drawable>(candidate.width, candidate.height) {
+        override fun onResourceReady(
+          resource: Drawable,
+          transition: Transition<in Drawable>?,
+        ) {
+          if (
+            requestGeneration == generation &&
+            !disposed &&
+            resource !is Animatable
+          ) {
+            synchronousResource = resource
+          }
+        }
+
+        override fun onLoadCleared(placeholder: Drawable?) = Unit
+      }
+      requestManager()
+        .asDrawable()
+        .load(OneKeyImageModel.build(candidate.requestUrl, sourceHeadersJson))
+        .apply(
+          memoryProbeRequestOptions(
+            requestOptions(policy, candidate.requestUrl, candidate.round),
+          ),
+        )
+        .override(candidate.width, candidate.height)
+        .into(target)
+
+      val resource = synchronousResource
+      if (resource == null) {
+        requestManager().clear(target)
+        OneKeyImageMemoryVariantRegistry.remove(family, candidate)
+        continue
+      }
+
+      clearMemoryPreviewTarget()
+      memoryPreviewTarget = target
+      memoryPreviewFamily = family
+      scalesCenterMemoryPreview = shouldScaleCenterMemoryPreview(
+        contentFit = contentFit ?: OneKeyImageContentFit.COVER,
+        candidate = candidate,
+        target = exactVariant,
+      )
+      applyContentFit()
+      displayState = DisplayState.IMAGE
+      requestActive = false
+      isPreservingDisplayedImage = false
+      hostView.skeletonRequested = false
+      hostView.drawStateSymbol = false
+      hostView.setBackgroundColor(Color.TRANSPARENT)
+      hostView.setImageDrawable(resource)
+      applyAutoplay()
+      OneKeyImageMemoryVariantRegistry.record(family, candidate)
+      return true
+    }
+    return false
+  }
+
   private fun startLoad(force: Boolean) {
     if (disposed) return
     if (hostView.width <= 0 || hostView.height <= 0) {
-      cancelCurrent(invalidateGeneration = true)
+      cancelCurrent(invalidateGeneration = true, clearMemoryPreview = false)
       lastSignature = null
-      showLoading(requestIsActive = false)
+      if (memoryPreviewTarget == null || hostView.drawable == null) {
+        showLoading(requestIsActive = false)
+      }
       return
     }
     val rawUrl = sourceUri?.takeIf { it.isNotBlank() }
@@ -416,15 +656,17 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
       contentFit = contentFit,
       optimizeTos = optimizeTos,
       overscan = overscan,
+      round = round == true,
       width = hostView.width,
       height = hostView.height,
       density = hostView.resources.displayMetrics.density,
       resizeWidth = resizeWidth,
+      resizeHeight = resizeHeight,
     )
     if (!force && signature == lastSignature) return
     lastSignature = signature
 
-    cancelCurrent(invalidateGeneration = true)
+    cancelCurrent(invalidateGeneration = true, clearMemoryPreview = false)
     val requestGeneration = generation
     requestStartedAtMs = SystemClock.uptimeMillis()
     onLoadStart?.invoke()
@@ -432,8 +674,14 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     val customIdentity = OneKeyImageModel.headers(sourceHeadersJson).isNotEmpty()
     val optimizedUrl = if (optimizeTos != false) {
       val density = hostView.resources.displayMetrics.density.coerceAtLeast(1f)
-      val displaySize = resizeWidth?.takeIf { it.isFinite() && it > 0.0 }
-        ?: (maxOf(hostView.width, hostView.height) / density.toDouble())
+      val displayWidth = resizeWidth?.takeIf { it.isFinite() && it > 0.0 }
+      val displayHeight = resizeHeight?.takeIf { it.isFinite() && it > 0.0 }
+      val displaySize = when {
+        displayWidth != null && displayHeight != null -> maxOf(displayWidth, displayHeight)
+        displayWidth != null -> displayWidth
+        displayHeight != null -> displayHeight
+        else -> maxOf(hostView.width, hostView.height) / density.toDouble()
+      }
       OneKeyTosUrl.optimized(
         rawUrl,
         ceil(displaySize).toInt(),
@@ -443,6 +691,28 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
       )
     } else rawUrl
     val decodeDimensions = OneKeyImageDecodeDimensions.forRender(hostView.width, hostView.height)
+    val memoryFamily = OneKeyImageMemoryFamilyKey.from(rawUrl, sourceHeadersJson)
+    val exactVariant = OneKeyImageMemoryVariant(
+      requestUrl = optimizedUrl,
+      width = decodeDimensions.width,
+      height = decodeDimensions.height,
+      round = round == true,
+    )
+    if (
+      shouldProbeMemoryPreview(
+        hasTarget = memoryPreviewTarget != null,
+        sameFamily = memoryPreviewFamily == memoryFamily,
+        hasDrawable = hostView.drawable != null,
+      )
+    ) {
+      showMemoryCachedPreview(
+        family = memoryFamily,
+        exactVariant = exactVariant,
+        includeExact = false,
+        policy = cachePolicy ?: OneKeyImageCachePolicy.MEMORY_DISK,
+        requestGeneration = requestGeneration,
+      )
+    }
     performRequest(
       requestUrl = optimizedUrl,
       rawUrl = rawUrl,
@@ -451,6 +721,8 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
       headersJson = sourceHeadersJson,
       policy = cachePolicy ?: OneKeyImageCachePolicy.MEMORY_DISK,
       decodeDimensions = decodeDimensions,
+      memoryFamily = memoryFamily,
+      memoryVariant = exactVariant,
     )
   }
 
@@ -462,6 +734,8 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     headersJson: String?,
     policy: OneKeyImageCachePolicy,
     decodeDimensions: OneKeyImageDecodeDimensions,
+    memoryFamily: OneKeyImageMemoryFamilyKey,
+    memoryVariant: OneKeyImageMemoryVariant,
   ) {
     if (requestGeneration != generation || disposed) return
     clearCurrentTarget()
@@ -471,18 +745,34 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     val target = object : CustomViewTarget<OneKeyImageHostView, Drawable>(hostView) {
       override fun onResourceLoading(placeholder: Drawable?) {
         if (requestGeneration != generation || disposed) return
-        showLoading(requestIsActive = true)
+        showLoading(
+          requestIsActive = true,
+          preserveDisplayedImage = memoryPreviewTarget != null && hostView.drawable != null,
+        )
       }
 
       override fun onResourceReady(resource: Drawable, transition: Transition<in Drawable>?) {
         if (requestGeneration != generation || disposed) return
+        val replacesMemoryPreview = memoryPreviewTarget != null && hostView.drawable != null
         requestActive = false
         displayState = DisplayState.IMAGE
         hostView.skeletonRequested = false
         hostView.drawStateSymbol = false
         hostView.setBackgroundColor(Color.TRANSPARENT)
         hostView.setImageDrawable(resource)
-        applyLoadedImageTransition(resolvedCacheType)
+        isPreservingDisplayedImage = false
+        if (
+          resource !is Animatable &&
+          (policy == OneKeyImageCachePolicy.MEMORY ||
+            policy == OneKeyImageCachePolicy.MEMORY_DISK)
+        ) {
+          OneKeyImageMemoryVariantRegistry.record(memoryFamily, memoryVariant)
+        }
+        clearMemoryPreviewTarget()
+        applyLoadedImageTransition(
+          cacheType = resolvedCacheType,
+          replacingMemoryPreview = replacesMemoryPreview,
+        )
         applyAutoplay()
         val loadCallback = onLoad
         val loadEndCallback = onLoadEnd
@@ -534,6 +824,8 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
                 headersJson = headersJson,
                 policy = policy,
                 decodeDimensions = decodeDimensions,
+                memoryFamily = memoryFamily,
+                memoryVariant = memoryVariant.copy(requestUrl = rawUrl),
               )
             }
           }
@@ -549,7 +841,7 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     requestManager()
       .asDrawable()
       .load(OneKeyImageModel.build(requestUrl, headersJson))
-      .apply(requestOptions(policy, requestUrl))
+      .apply(requestOptions(policy, requestUrl, memoryVariant.round))
       .override(decodeDimensions.width, decodeDimensions.height)
       .listener(object : RequestListener<Drawable> {
         override fun onLoadFailed(
@@ -577,11 +869,15 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
       .into(target)
   }
 
-  private fun requestOptions(policy: OneKeyImageCachePolicy, uri: String): RequestOptions {
+  private fun requestOptions(
+    policy: OneKeyImageCachePolicy,
+    uri: String,
+    round: Boolean,
+  ): RequestOptions {
     val options = RequestOptions()
       .withOneKeyAvatarCache(uri)
-      .dontTransform()
       .downsample(OneKeyImageSafeDownsampleStrategy)
+    if (round) options.circleCrop() else options.dontTransform()
     return when (policy) {
       OneKeyImageCachePolicy.MEMORY_DISK -> options.diskCacheStrategy(oneKeyImageMemoryDiskStrategy(uri))
       OneKeyImageCachePolicy.MEMORY -> options.diskCacheStrategy(DiskCacheStrategy.NONE)
@@ -605,7 +901,10 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     )
   }
 
-  private fun cancelCurrent(invalidateGeneration: Boolean) {
+  private fun cancelCurrent(
+    invalidateGeneration: Boolean,
+    clearMemoryPreview: Boolean = true,
+  ) {
     loadRunnable?.let(hostView::removeCallbacks)
     loadRunnable = null
     displayRunnable?.let(hostView::removeCallbacks)
@@ -614,7 +913,9 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     fallbackRunnable?.let(hostView::removeCallbacks)
     fallbackRunnable = null
     clearCurrentTarget()
+    if (clearMemoryPreview) clearMemoryPreviewTarget()
     requestActive = false
+    isPreservingDisplayedImage = false
     hostView.skeletonRequested = false
     requestStartedAtMs = null
     resetImageTransition()
@@ -629,6 +930,15 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     requestManager().clear(target)
   }
 
+  private fun clearMemoryPreviewTarget() {
+    val target = memoryPreviewTarget
+    memoryPreviewTarget = null
+    memoryPreviewFamily = null
+    scalesCenterMemoryPreview = false
+    applyContentFit()
+    if (target != null) requestManager().clear(target)
+  }
+
   private fun scheduleOnDisplay(requestGeneration: Long) {
     pendingDisplayGeneration = requestGeneration
     schedulePendingDisplayIfNeeded()
@@ -657,10 +967,22 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     hostView.postOnAnimation(runnable)
   }
 
-  private fun showLoading(requestIsActive: Boolean) {
+  private fun showLoading(
+    requestIsActive: Boolean,
+    preserveDisplayedImage: Boolean = false,
+  ) {
     displayState = DisplayState.LOADING
     requestActive = requestIsActive
     resetImageTransition()
+    if (preserveDisplayedImage && hostView.drawable != null) {
+      isPreservingDisplayedImage = true
+      hostView.skeletonRequested = false
+      hostView.drawStateSymbol = false
+      hostView.setBackgroundColor(Color.TRANSPARENT)
+      hostView.invalidate()
+      return
+    }
+    isPreservingDisplayedImage = false
     hostView.setImageDrawable(null)
     hostView.drawStateSymbol = false
     applyLoadingAppearance()
@@ -677,7 +999,9 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
   private fun showTerminalState(state: DisplayState) {
     displayState = state
     requestActive = false
+    isPreservingDisplayedImage = false
     resetImageTransition()
+    clearMemoryPreviewTarget()
     hostView.setImageDrawable(null)
     hostView.skeletonRequested = false
     val hidesTerminalState = loadingStrategy == OneKeyImageLoadingStrategy.NONE
@@ -746,7 +1070,7 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
   private fun applyVariant() {
     when (displayState) {
       DisplayState.IMAGE -> Unit
-      DisplayState.LOADING -> applyLoadingAppearance()
+      DisplayState.LOADING -> if (!isPreservingDisplayedImage) applyLoadingAppearance()
       DisplayState.ERROR, DisplayState.FALLBACK -> {
         val hidesTerminalState = loadingStrategy == OneKeyImageLoadingStrategy.NONE
         hostView.setBackgroundColor(
@@ -778,16 +1102,19 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
     OneKeyImageVariant.AVATAR -> "●"
   }
 
-  private fun applyLoadedImageTransition(cacheType: OneKeyImageCacheType) {
+  private fun applyLoadedImageTransition(
+    cacheType: OneKeyImageCacheType,
+    replacingMemoryPreview: Boolean,
+  ) {
     resetImageTransition()
     val startedAt = requestStartedAtMs ?: return
-    if (
-      cacheType == OneKeyImageCacheType.MEMORY ||
-      SystemClock.uptimeMillis() - startedAt < FADE_DELAY_THRESHOLD_MS ||
-      !animationsEnabled()
-    ) {
-      return
-    }
+    val shouldAnimate = shouldAnimateLoadedImageTransition(
+      cacheType = cacheType,
+      fadeDelayElapsed = SystemClock.uptimeMillis() - startedAt >= FADE_DELAY_THRESHOLD_MS,
+      animationsEnabled = animationsEnabled(),
+      replacingMemoryPreview = replacingMemoryPreview,
+    )
+    if (!shouldAnimate) return
     hostView.alpha = 0f
     hostView.animate()
       .alpha(1f)
@@ -841,6 +1168,13 @@ class HybridOneKeyImage(private val context: ThemedReactContext) :
   }
 
   private fun applyContentFit() {
+    if (
+      scalesCenterMemoryPreview &&
+      (contentFit ?: OneKeyImageContentFit.COVER) == OneKeyImageContentFit.CENTER
+    ) {
+      hostView.scaleType = ImageView.ScaleType.FIT_CENTER
+      return
+    }
     hostView.scaleType = when (contentFit ?: OneKeyImageContentFit.COVER) {
       OneKeyImageContentFit.COVER -> ImageView.ScaleType.CENTER_CROP
       OneKeyImageContentFit.CONTAIN -> ImageView.ScaleType.FIT_CENTER