Backtestshugorun-20261005-133023#12543

Issue #12543 Merged fix PR # Run 5 Oct 2026 · run-20261005-133023 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 A = our agent, Patch B = the merged fix.

Both patches make the same core fix in resources/image.go: they skip re-applying the source palette when conf.Action is the new images.ActionFilter. The golden-file updates for paletted overlay/text are identical. So correctness on the reported issue is equivalent. The differences are in tests and scope. Patch A adds an integration test (TestFilterPalettedPNGIssue12543) plus an AssertIsPaletted helper. The test checks that overlay, text, padding and colorize outputs from an indexed PNG are no longer paletted, and that Resize still keeps the palette. That test would fail before the fix and pass after it, and it also guards the intended behavior for geometric actions. Patch B adds no test for this issue. Its test changes target a different concern: hex colors parsing to NRGBA instead of RGBA. Patch B also bundles unrelated changes to color handling. hexStringToColorGo now returns NRGBA, Color.init normalizes to NRGBA, ColorGoToHexString un-premultiplies, and AddColorToPalette compares by value. It also alters an unrelated golden image (padding-transparent-chained.png) and existing color test expectations. These may be valid fixes for another issue, but they change public color semantics and output, adding risk and obscuring the fix for this issue. Since the core fix is identical, A wins on targeted test coverage and focused 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

46m 1s

Wall-clock time in the container

Full test suite

No new failures

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

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

56vs 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+54 −2
hugolib/integrationtest_builder.goindex 559373a85..98ecf2a87 100644@@ -534,6 +534,16 @@ func (h *IntegrationTestImageHelper) AssertIsAnimated(b bool) *IntegrationTestIm 	return h } +func (h *IntegrationTestImageHelper) AssertIsPaletted(b bool) *IntegrationTestImageHelper {+	_, ok := h.img.(*image.Paletted)+	if b {+		h.Assert(ok, qt.IsTrue, qt.Commentf("Image is not paletted, got %T", h.img))+		return h+	}+	h.Assert(ok, qt.IsFalse, qt.Commentf("Image is paletted"))+	return h+}+ func (s *IntegrationTestBuilder) ImageHelper(filename string) *IntegrationTestImageHelper { 	filename = filepath.Clean(filename) 	fs := s.fs.WorkingDirReadOnlyresources/image.goindex 467e23f26..5a4546b40 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 {+		// Filters (e.g. overlays, text, padding and colour adjustments) may introduce+		// colours not present in the source palette, so only re-apply the source+		// palette for actions that derive their colours from the source image.+		// 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..1c0d04566 100644@@ -36,6 +36,9 @@ const ( 	ActionCrop   = "crop" 	ActionFit    = "fit" 	ActionFill   = "fill"++	// ActionFilter is the action used when applying filters via Filter.+	ActionFilter = "filter" )  var Actions = map[string]bool{resources/images/images_integration_test.goindex 172449d21..53b163346 100644@@ -182,3 +182,38 @@ Page. 		builder.Build() 	} }++// Filtering an indexed 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 --+Home.+{{ $bg := resources.Get "gohugoio8.png" }}+{{ $bg.Publish }}+{{ $sunset := (resources.Get "sunset.jpg").Resize "x60" }}+{{ with $bg.Filter (images.Overlay $sunset 20 20) | resources.Copy "images/overlay.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Text "Hugo Rocks!" (dict "color" "#ff0060" "size" 40)) | resources.Copy "images/text.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Padding 20 "#0a8f3c") | resources.Copy "images/padding.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Colorize 180 50 20) | resources.Copy "images/colorize.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Resize "200x" | resources.Copy "images/resize.png" }}{{ .Publish }}{{ end }}+`++	b := hugolib.Test(t, files)++	b.ImageHelper("public/gohugoio8.png").AssertFormat("png").AssertIsPaletted(true)++	for _, name := range []string{"overlay", "text", "padding", "colorize"} {+		b.ImageHelper("public/images/" + name + ".png").AssertFormat("png").AssertIsPaletted(false)+	}++	// Resizing only derives colours from the source, so the palette is kept.+	b.ImageHelper("public/images/resize.png").AssertFormat("png").AssertIsPaletted(true)+}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