Backtestshugorun-20261002-200313#12543

Issue #12543 Merged fix PR # Run 2 Oct 2026 · run-20261002-200313 gohugoio/hugo

resources/images: Poor overlay quality when background image is an indexed (not true color) PNG

Better

Our patch was judged better than the merged fix.

In this judgment, Patch B = our agent, Patch A = the merged fix.

Both patches make the same core fix. In `doWithImageConfig` they skip re-applying the source palette when the action is a filter. That addresses the root cause: overlay and text output gets clamped back to the indexed PNG's palette. Both also update the paletted overlay and text golden images in the same way.

Patch A also changes how colors are handled across the board. Hex colors now parse to NRGBA instead of RGBA, `Color.init` normalizes to NRGBA, `ColorGoToHexString` un-premultiplies, and `AddColorToPalette` compares by color value. It also edits existing test expectations and changes the `padding-transparent-chained.png` golden file. These changes target a different issue (12536, premultiplied alpha) and are not needed to fix this one. They alter behavior visible to users, such as how hex strings are interpreted and how colors compare, which adds risk and makes the fix harder to see.

Patch B keeps to the issue. It also adds a focused integration test that checks three things: resize still keeps the palette, overlays (including on a resized image) reproduce the overlay's pixel colors exactly and are not paletted, and the text color survives. This test would fail before the fix and pass after it. Patch A adds no new test for the overlay behavior beyond the golden-file updates.

On correctness the two are equal. Patch B is better on tests and scope.

The judge saw only the two patches, labelled A and B in random order, with issue links and version numbers removed. The reasoning above is shown verbatim.

Solve

53m 37s

Wall-clock time in the container

Full test suite

No new failures

3,750 passed · 99 skipped · 3,853 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

88vs 58 merged

Changed lines, ours vs merged

Reference: <https://discourse.gohugo.io/t/image-overlay-quality-is-poor/50034>

Before getting into the details, I have verified that this is not an upstream issue with disintegration/gift. I tested with this:

<details>
<summary>main.go</summary>

package main

import (
	"image"
	"image/png"
	"log"
	"os"

	_ "image/png"

	"github.com/disintegration/gift"
)

func main() {
	// Get the background image (24 bit: indexed not true color)
	f, err := os.Open("background.png")
	if err != nil {
		log.Fatal(err)
	}
	bgImage, _, err := image.Decode(f)
	if err != nil {
		log.Fatal(err)
	}

	// Get the foreground image (24 bit with 8 bit alpha channel)
	f, err = os.Open("foreground.png")
	if err != nil {
		log.Fatal(err)
	}
	fgImage, _, err := image.Decode(f)
	if err != nil {
		log.Fatal(err)
	}

	// Create a new image with dimensions of the bgImage.
	dstImage := image.NewRGBA(bgImage.Bounds())
	// Copy the bgImage to the dstImage.
	gift.New().Draw(dstImage, bgImage)
	// Draw the fgImage over the dstImage at the (20, 20) position.
	gift.New().DrawAt(dstImage, fgImage, image.Pt(20, 20), gift.OverOperator)

	// Create the composite file.
	f, err = os.Create("composite.png")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	// Encode the composite image.
	err = png.Encode(f, dstImage)
	if err != nil {
		log.Fatal(err)
	}
}

</details>

Details:

  • Background image is a 24 bit indexed PNG file with 256 colors in its palette
  • Foreground image is a 24 bit true color PNG with an 8 bit alpha channel
  • The final (composite) image seems to be limited to the palette of the background image

Simple example:

git clone --single-branch -b hugo-github-issue-12543 https://github.com/jmooring/hugo-testing hugo-github-issue-12543
cd hugo-github-issue-12543
hugo server

Note that GIF images (also indexed) work fine.

The two patches

Our patch+86 −2
resources/image.goindex 467e23f26..a4a98055d 100644@@ -321,7 +321,7 @@ func (i *imageResource) Filter(filters ...any) (images.ImageResource, error) { 		return nil, err 	} -	confMain.Action = "filter"+	confMain.Action = images.ActionFilter 	confMain.Key = hashing.HashString(gfilters)  	return i.doWithImageConfig(confMain, func(src image.Image) (image.Image, error) {@@ -438,7 +438,10 @@ func (i *imageResource) doWithImageConfig(conf images.ImageConfig, f func(src im 			converted = tmp 		} -		if conf.TargetFormat == images.PNG {+		// Filters (e.g. overlay, text, colorize) may introduce colors not present+		// in the source palette, so only re-apply the source palette for+		// the other actions. See issue 12543.+		if conf.TargetFormat == images.PNG && conf.Action != images.ActionFilter { 			// Apply the colour palette from the source 			if paletted, ok := src.(*image.Paletted); ok { 				palette := paletted.Paletteresources/images/config.goindex 4cbd7e629..1d8317ce8 100644@@ -36,6 +36,10 @@ const ( 	ActionCrop   = "crop" 	ActionFit    = "fit" 	ActionFill   = "fill"++	// ActionFilter is the action used for images processed via Filter.+	// It's not a user facing option, so it's not included in Actions.+	ActionFilter = "filter" )  var Actions = map[string]bool{resources/images/images_integration_test.goindex 172449d21..303abbc48 100644@@ -14,9 +14,13 @@ package images_test  import (+	"image"+	"image/color"+	"image/png" 	"testing"  	"github.com/bep/logg"+	qt "github.com/frankban/quicktest" 	"github.com/gohugoio/hugo/htesting" 	"github.com/gohugoio/hugo/hugolib" )@@ -182,3 +186,76 @@ Page. 		builder.Build() 	} }++// Filtering an indexed (paletted) PNG must not clamp the result to the+// source palette. See issue 12543.+func TestFilterPalettedPNGIssue12543(t *testing.T) {+	t.Parallel()++	files := `+-- hugo.toml --+-- assets/gohugoio8.png --+sourcefilename: ../testdata/gohugoio8.png+-- assets/sunset.jpg --+sourcefilename: ../testdata/sunset.jpg+-- layouts/home.html --+{{ $bg := resources.Get "gohugoio8.png" }}+{{ $sunset := (resources.Get "sunset.jpg").Resize "x100 png" }}+{{ $textOpts := dict "color" "#ff0060" "size" 60 "x" 10 "y" 10 }}+{{ with $bg.Resize "300x" | resources.Copy "images/resized.png" }}{{ .Publish }}{{ end }}+{{ with $sunset | resources.Copy "images/sunset.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Overlay $sunset 20 30) | resources.Copy "images/overlay.png" }}{{ .Publish }}{{ end }}+{{ with ($bg.Resize "300x").Filter (images.Overlay $sunset 20 30) | resources.Copy "images/overlay-resized.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Text "Hugo" $textOpts) | resources.Copy "images/text.png" }}{{ .Publish }}{{ end }}+`++	b := hugolib.Test(t, files)++	decode := func(filename string) image.Image {+		f, err := b.H.Fs.PublishDir.Open(filename)+		b.Assert(err, qt.IsNil)+		defer f.Close()+		img, err := png.Decode(f)+		b.Assert(err, qt.IsNil)+		return img+	}++	toRGBA := func(c color.Color) color.RGBA {+		return color.RGBAModel.Convert(c).(color.RGBA)+	}++	// Resizing an indexed PNG still preserves the source palette.+	_, isPaletted := decode("images/resized.png").(*image.Paletted)+	b.Assert(isPaletted, qt.IsTrue)++	// The overlay must be drawn with its own colors, not the background's palette.+	sunset := decode("images/sunset.png")+	for _, filename := range []string{"images/overlay.png", "images/overlay-resized.png"} {+		composite := decode(filename)+		_, isPaletted := composite.(*image.Paletted)+		b.Assert(isPaletted, qt.IsFalse, qt.Commentf(filename))+		sb := sunset.Bounds()+		for y := sb.Min.Y; y < sb.Max.Y; y += 7 {+			for x := sb.Min.X; x < sb.Max.X; x += 7 {+				b.Assert(toRGBA(composite.At(x+20, y+30)), qt.Equals, toRGBA(sunset.At(x, y)), qt.Commentf("%s at %d,%d", filename, x, y))+			}+		}+	}++	// The text color must be preserved.+	text := decode("images/text.png")+	_, isPaletted = text.(*image.Paletted)+	b.Assert(isPaletted, qt.IsFalse)+	textColor := color.RGBA{R: 0xff, G: 0x00, B: 0x60, A: 0xff}+	var found bool+	tb := text.Bounds()+	for y := tb.Min.Y; y < tb.Max.Y && !found; y++ {+		for x := tb.Min.X; x < tb.Max.X; x++ {+			if toRGBA(text.At(x, y)) == textColor {+				found = true+				break+			}+		}+	}+	b.Assert(found, qt.IsTrue)+}resources/images/testdata/images_golden/filters/paletted/overlay.pngindex 10d9dd6fd..631854dd8 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/overlay.png and b/resources/images/testdata/images_golden/filters/paletted/overlay.png differresources/images/testdata/images_golden/filters/paletted/text.pngindex 71a9c3e2d..65d1a60ce 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/text.png and b/resources/images/testdata/images_golden/filters/paletted/text.png differ 
Merged fix · PR #+39 −19
resources/image.goindex 467e23f26..a2ed5f3c9 100644@@ -321,7 +321,7 @@ func (i *imageResource) Filter(filters ...any) (images.ImageResource, error) { 		return nil, err 	} -	confMain.Action = "filter"+	confMain.Action = images.ActionFilter 	confMain.Key = hashing.HashString(gfilters)  	return i.doWithImageConfig(confMain, func(src image.Image) (image.Image, error) {@@ -438,7 +438,11 @@ func (i *imageResource) doWithImageConfig(conf images.ImageConfig, f func(src im 			converted = tmp 		} -		if conf.TargetFormat == images.PNG {+		// Preserve the source palette for the geometric actions so an indexed+		// PNG stays indexed. Filters (e.g. images.Overlay, images.Text) routinely+		// introduce colors outside the source palette, and clamping the result+		// back to that palette destroys the filtered output. See issue 12543.+		if conf.TargetFormat == images.PNG && conf.Action != images.ActionFilter { 			// Apply the colour palette from the source 			if paletted, ok := src.(*image.Paletted); ok { 				palette := paletted.Paletteresources/images/color.goindex fe233c7b7..72f3710e3 100644@@ -69,9 +69,12 @@ func (c Color) Key() string { }  func (c *Color) init() error {-	c.hex = ColorGoToHexString(c.color)-	r, g, b, _ := c.color.RGBA()-	c.luminance = 0.2126*c.toSRGB(uint8(r)) + 0.7152*c.toSRGB(uint8(g)) + 0.0722*c.toSRGB(uint8(b))+	// Normalize to the canonical non-premultiplied form so that equal colors+	// compare equal whether they came from a hex string or from image pixels.+	nrgba := color.NRGBAModel.Convert(c.color).(color.NRGBA)+	c.color = nrgba+	c.hex = ColorGoToHexString(nrgba)+	c.luminance = 0.2126*c.toSRGB(nrgba.R) + 0.7152*c.toSRGB(nrgba.G) + 0.0722*c.toSRGB(nrgba.B) 	return nil } @@ -88,10 +91,13 @@ func (c Color) toSRGB(i uint8) float64 { // Note that it does no additional checks, so callers must make sure // that the palette is valid for the relevant format. func AddColorToPalette(c color.Color, p color.Palette) color.Palette {-	var found bool-	if slices.Contains(p, c) {-		found = true-	}+	// Compare color values rather than interface values, so that e.g. a+	// color.NRGBA is found even if the palette holds it as a color.RGBA.+	cr, cg, cb, ca := c.RGBA()+	found := slices.ContainsFunc(p, func(v color.Color) bool {+		vr, vg, vb, va := v.RGBA()+		return cr == vr && cg == vg && cb == vb && ca == va+	})  	if !found { 		p = append(color.Palette{c}, p...)@@ -108,12 +114,13 @@ func ReplaceColorInPalette(c color.Color, p color.Palette) {  // ColorGoToHexString converts a color.Color to a hex string. func ColorGoToHexString(c color.Color) string {-	r, g, b, a := c.RGBA()-	rgba := color.RGBA{uint8(r), uint8(g), uint8(b), uint8(a)}-	if rgba.A == 0xff {-		return fmt.Sprintf("#%.2x%.2x%.2x", rgba.R, rgba.G, rgba.B)+	// Hex notation is not alpha-premultiplied, so convert via NRGBA to+	// un-premultiply the color components of any transparent color.+	nrgba := color.NRGBAModel.Convert(c).(color.NRGBA)+	if nrgba.A == 0xff {+		return fmt.Sprintf("#%.2x%.2x%.2x", nrgba.R, nrgba.G, nrgba.B) 	}-	return fmt.Sprintf("#%.2x%.2x%.2x%.2x", rgba.R, rgba.G, rgba.B, rgba.A)+	return fmt.Sprintf("#%.2x%.2x%.2x%.2x", nrgba.R, nrgba.G, nrgba.B, nrgba.A) }  // ColorGoToColor converts a color.Color to a Color.@@ -195,5 +202,8 @@ func hexStringToColorGo(s string) (color.Color, error) { 		return nil, err 	} -	return color.RGBA{b[0], b[1], b[2], b[3]}, nil+	// Hex notation is not alpha-premultiplied, so this must be a color.NRGBA;+	// as a color.RGBA any transparent color would be invalid (component > alpha)+	// and corrupted when drawn onto an alpha-premultiplied image. See issue 12536.+	return color.NRGBA{b[0], b[1], b[2], b[3]}, nil }resources/images/color_test.goindex 540f3bea8..47bc5ae8b 100644@@ -39,8 +39,12 @@ func TestHexStringToColor(t *testing.T) { 		{"#ffffff", color.White}, 		{"ffffff", color.White}, 		{"#000", color.Black},-		{"#4287f5", color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}},-		{"777", color.RGBA{R: 0x77, G: 0x77, B: 0x77, A: 0xff}},+		{"#4287f5", color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}},+		{"777", color.NRGBA{R: 0x77, G: 0x77, B: 0x77, A: 0xff}},+		// Hex notation is not alpha-premultiplied, so a transparent color+		// must parse to a color.NRGBA. See issue 12536.+		{"#00f7", color.NRGBA{R: 0x00, G: 0x00, B: 0xff, A: 0x77}},+		{"4287f580", color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}}, 	} {  		c.Run(test.arg, func(c *qt.C) {@@ -71,10 +75,11 @@ func TestColorToHexString(t *testing.T) { 		{color.Black, "#000000"}, 		{color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0xff}, "#4287f5"}, -		// 50% opacity.+		// 50% opacity. Hex notation is not alpha-premultiplied, so the+		// components of a transparent color are the non-premultiplied ones. 		// Note that the .Colors (dominant colors) received from the Image resource 		// will always have an alpha value of 0xff.-		{color.RGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}, "#4287f580"},+		{color.NRGBA{R: 0x42, G: 0x87, B: 0xf5, A: 0x80}, "#4287f580"}, 	} {  		c.Run(test.expect, func(c *qt.C) {resources/images/config.goindex 4cbd7e629..e8fd69c94 100644@@ -36,6 +36,7 @@ const ( 	ActionCrop   = "crop" 	ActionFit    = "fit" 	ActionFill   = "fill"+	ActionFilter = "filter" )  var Actions = map[string]bool{resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.pngindex 899e21f25..34392755c 100644Binary files a/resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.png and b/resources/images/testdata/images_golden/filters/padding/padding-transparent-chained.png differresources/images/testdata/images_golden/filters/paletted/overlay.pngindex 10d9dd6fd..631854dd8 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/overlay.png and b/resources/images/testdata/images_golden/filters/paletted/overlay.png differresources/images/testdata/images_golden/filters/paletted/text.pngindex 71a9c3e2d..65d1a60ce 100644Binary files a/resources/images/testdata/images_golden/filters/paletted/text.png and b/resources/images/testdata/images_golden/filters/paletted/text.png differ