[Mobile] Eliminate low-res→high-res image flash (#14277)

When `useImageSize` had a smaller cached size (e.g. 150×150) but needed
a larger one (e.g. 480×480 on a track page), it set `imageUrl` to the
small URL then switched to the large URL once fetched. The source change
caused `Image.tsx` to reset `opacity = 0` and re-fade — a visible flash
on track, profile, and playlist pages.

`useImageSize` now sets `imageUrl` to the target URL optimistically and
returns `priorityLowResUrl` as a separate value. `TrackImage`,
`CollectionImage`, and `UserImage` pass it as `priorityLowResSource` to
`Artwork`/`Image`, which renders it as a blurred backdrop while the
high-res crossfades in.

## Test plan
- [ ] Navigate to a track page — artwork should crossfade from blurred
low-res to full-res, no flash
- [ ] Same on profile and playlist pages

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: raymondjacobson

packages/common/src/hooks/useImageSize.ts

@@ -57,6 +57,11 @@ export const useImageSize = <
   preloadImageFn?: (url: string) => Promise<void>
 }) => {
   const [imageUrl, setImageUrl] = useState<Maybe<string>>(undefined)
+  // When upgrading from a smaller cached image to the target size, holds the
+  // smaller URL so callers can show it as a blurred backdrop while the
+  // high-res crossfades in (avoids the opacity-reset flash on source change).
+  const [priorityLowResUrl, setPriorityLowResUrl] =
+    useState<Maybe<string>>(undefined)
   const [failedUrls, setFailedUrls] = useState<Set<string>>(new Set())
 
   const fetchWithFallback = useCallback(
@@ -150,10 +155,21 @@ export const useImageSize = <
     }
 
     if (smallerSize) {
-      setImageUrl(artwork[smallerSize])
-      const finalUrl = await fetchWithFallback(targetUrl)
-      IMAGE_CACHE.add(finalUrl)
-      setImageUrl(finalUrl)
+      // Set the target URL optimistically so the main image slot starts
+      // loading the high-res immediately. The smaller cached URL is passed
+      // back as priorityLowResUrl so callers can show it as a blurred
+      // backdrop — this eliminates the opacity-reset flash that occurred
+      // when we previously did setImageUrl(small) then setImageUrl(large).
+      setPriorityLowResUrl(artwork[smallerSize])
+      setImageUrl(targetUrl)
+      try {
+        const finalUrl = await fetchWithFallback(targetUrl)
+        IMAGE_CACHE.add(finalUrl)
+        if (finalUrl !== targetUrl) setImageUrl(finalUrl)
+      } catch (e) {
+        // Fall back to the smaller size if high-res is unreachable.
+        setImageUrl(artwork[smallerSize])
+      }
       return
     }
 
@@ -190,5 +206,5 @@ export const useImageSize = <
     resolveImageUrl()
   }, [resolveImageUrl])
 
-  return { imageUrl, onError }
+  return { imageUrl, priorityLowResUrl, onError }
 }

packages/mobile/src/components/image/CollectionImage.tsx

@@ -71,7 +71,11 @@ export const useCollectionImage = ({
   })
   const artwork = artworkData?.artwork
   const hasNoArtwork = artworkData?.hasNoArtwork ?? false
-  const { imageUrl, onError: onImageError } = useImageSize({
+  const {
+    imageUrl,
+    priorityLowResUrl,
+    onError: onImageError
+  } = useImageSize({
     artwork,
     targetSize: size,
     defaultImage: '',
@@ -98,6 +102,7 @@ export const useCollectionImage = ({
 
   return {
     source: primitiveToImageSource(imageUrl),
+    priorityLowResSource: primitiveToImageSource(priorityLowResUrl),
     hasNoArtwork: false,
     onError: onImageError
   }
@@ -121,6 +126,7 @@ export const CollectionImage = (props: CollectionImageProps) => {
   const collectionImageSource = useCollectionImage({ collectionId, size })
   const {
     source: loadedSource,
+    priorityLowResSource,
     onError: onImageError,
     hasNoArtwork
   } = collectionImageSource
@@ -160,6 +166,7 @@ export const CollectionImage = (props: CollectionImageProps) => {
     <Artwork
       {...other}
       source={source}
+      priorityLowResSource={priorityLowResSource}
       onLoad={onLoad}
       onError={handleError}
       style={style}

packages/mobile/src/components/image/TrackImage.tsx

@@ -66,7 +66,11 @@ export const useTrackImage = ({
   })
   const artwork = artworkData?.artwork
   const hasNoArtwork = artworkData?.hasNoArtwork ?? false
-  const { imageUrl, onError: onImageError } = useImageSize({
+  const {
+    imageUrl,
+    priorityLowResUrl,
+    onError: onImageError
+  } = useImageSize({
     artwork,
     targetSize: size,
     defaultImage: '',
@@ -97,6 +101,7 @@ export const useTrackImage = ({
 
   return {
     source: primitiveToImageSource(imageUrl),
+    priorityLowResSource: primitiveToImageSource(priorityLowResUrl),
     hasNoArtwork: false,
     onError: onImageError
   }
@@ -129,6 +134,7 @@ export const TrackImage = (props: TrackImageProps) => {
   const trackImageSource = useTrackImage({ trackId, size })
   const {
     source: loadedSource,
+    priorityLowResSource,
     onError: onImageError,
     hasNoArtwork
   } = trackImageSource
@@ -176,6 +182,7 @@ export const TrackImage = (props: TrackImageProps) => {
   return (
     <Artwork
       source={source}
+      priorityLowResSource={priorityLowResSource}
       onLoad={onLoad}
       onError={handleError}
       borderRadius={borderRadius}

packages/mobile/src/components/image/UserImage.tsx

@@ -27,7 +27,11 @@ export const useProfilePicture = ({
   })
 
   const { profile_picture, updatedProfilePicture } = partialUser ?? {}
-  const { imageUrl, onError: onImageError } = useImageSize({
+  const {
+    imageUrl,
+    priorityLowResUrl,
+    onError: onImageError
+  } = useImageSize({
     artwork: profile_picture,
     targetSize: size,
     defaultImage: '',
@@ -54,6 +58,7 @@ export const useProfilePicture = ({
 
   return {
     source: primitiveToImageSource(imageUrl),
+    priorityLowResSource: primitiveToImageSource(priorityLowResUrl),
     isFallbackImage: false,
     onError: onImageError
   }
@@ -63,7 +68,11 @@ export type UserImageProps = UseUserImageOptions & Partial<ImageProps>
 
 export const UserImage = (props: UserImageProps) => {
   const { userId, size, onError, ...imageProps } = props
-  const { source, onError: onImageError } = useProfilePicture({ userId, size })
+  const {
+    source,
+    priorityLowResSource,
+    onError: onImageError
+  } = useProfilePicture({ userId, size })
 
   const handleError = (error: { nativeEvent: { error: string } }) => {
     if (source && typeof source === 'object' && 'uri' in source) {
@@ -72,5 +81,12 @@ export const UserImage = (props: UserImageProps) => {
     onError?.(error)
   }
 
-  return <Image {...imageProps} source={source} onError={handleError} />
+  return (
+    <Image
+      {...imageProps}
+      source={source}
+      priorityLowResSource={priorityLowResSource}
+      onError={handleError}
+    />
+  )
 }