Backtestshugorun-20261024-162305#12543

Issue #12543 Merged fix PR # Run 24 Oct 2026 · run-20261024-162305 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 contain the identical root-cause fix: introduce an images.ActionFilter constant, use it in Filter(), and skip the 'apply source palette' step in doWithImageConfig when the action is a filter, so overlay/text/padding output on an indexed PNG is no longer clamped to the source's 256-color palette. Both update the same golden files and both pass all three independent tests that failed on base. The difference is in tests and scope. Patch B adds a focused integration test for this issue that would fail on base (it asserts the overlay results are not *image.Paletted and have more than 256 colors, that the text color absent from the source palette appears in the output, and that the padding pixel is the exact requested color) while confirming that plain resize still preserves the palette; that is a meaningful regression test for exactly the reported behaviour. Patch A adds no test for the reported issue; its test changes are to color unit tests covering a separate concern. Patch A also bundles an unrelated change set in color.go (parsing hex to NRGBA instead of RGBA, normalizing Color.init, value-based palette comparison, un-premultiplying in ColorGoToHexString) for a different transparency issue, which alters an extra golden file (padding-transparent-chained.png) and changes the concrete color type returned by the public hex parser. That may be a legitimate adjacent fix but it is outside this issue's ask, adds behavioural risk, and obscures the actual fix. On craft the two are equivalent, with B slightly clearer by documenting that ActionFilter is not a valid spec action. B is the better fix for this issue.

Four judges ruled on this ticket in parallel, and the verdict comes from counting their votes. Each saw the issue and the two patches, labelled A and B in random order (two of them saw ours as A), with issue links and version numbers removed. Where tests could check the fix, they also saw the results of tests a separate agent wrote for the issue, run on both patches. None was told which patch was ours. The reasoning above is one judge's, shown verbatim.

Solve

31m 15s

Wall-clock time in the container

Full test suite

No new failures

1,087 passed · 2 skipped · 1,121 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

113vs 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+111 −2
resources/image.goindex 467e23f26..afbde0e91 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, padding) may introduce colours not+		// in the source palette, so don't clamp their output to it.+		// 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..6107314bc 100644@@ -38,6 +38,10 @@ const ( 	ActionFill   = "fill" ) +// ActionFilter is the action set on the image config when applying filters.+// It's not a valid action in an image processing spec.+const ActionFilter = "filter"+ var Actions = map[string]bool{ 	ActionResize: true, 	ActionCrop:   true,resources/images/images_integration_test.goindex 172449d21..29ebd99a5 100644@@ -14,9 +14,15 @@ package images_test  import (+	"image"+	"image/color"+	"image/png"+	"os"+	"path/filepath" 	"testing"  	"github.com/bep/logg"+	qt "github.com/frankban/quicktest" 	"github.com/gohugoio/hugo/htesting" 	"github.com/gohugoio/hugo/hugolib" )@@ -105,6 +111,102 @@ CropSmart: {{ .Width }}x{{ .Height }}| 	b.AssertFileContent("public/index.html", "Original: 900x562|CropTopLeft: 900x561|CropSmart: 900x561|") } +// Filtering an indexed (paletted) PNG must not clamp the result to the source palette.+func TestFilterPalettedPNGIssue12543(t *testing.T) {+	t.Parallel()++	files := `+-- hugo.toml --+disableKinds = ['page','rss','section','sitemap','taxonomy','term']+-- assets/gohugoio8.png --+sourcefilename: ../testdata/gohugoio8.png+-- assets/sunset.jpg --+sourcefilename: ../testdata/sunset.jpg+-- layouts/home.html --+{{ $src := resources.Get "gohugoio8.png" }}+{{ $bg := $src.Resize "500x" }}+{{ $sunset := (resources.Get "sunset.jpg").Resize "x160" }}+{{ $textOpts := dict "color" "#ff0060" "size" 40 "x" 190 "y" 80 }}+{{ with $src | resources.Copy "images/source.png" }}{{ .Publish }}{{ end }}+{{ with $bg | resources.Copy "images/resized.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Overlay $sunset 230 70) | resources.Copy "images/overlay.png" }}{{ .Publish }}{{ end }}+{{ with $src.Filter (images.Overlay $sunset 230 70) | resources.Copy "images/overlay-unresized.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Text "Hugo Rocks!" $textOpts) | resources.Copy "images/text.png" }}{{ .Publish }}{{ end }}+{{ with $bg.Filter (images.Padding 20 "#12ab34") | resources.Copy "images/padding.png" }}{{ .Publish }}{{ end }}+{{ with $src.Filter (images.Process "resize 500x") (images.Overlay $sunset 230 70) | resources.Copy "images/process-overlay.png" }}{{ .Publish }}{{ end }}+Home.+`++	b := hugolib.Test(t, files, hugolib.TestOptWithConfig(func(cfg *hugolib.IntegrationTestConfig) {+		cfg.NeedsOsFS = true+	}))++	decode := func(name string) image.Image {+		t.Helper()+		f, err := os.Open(filepath.Join(b.H.Conf.WorkingDir(), "public", "images", name))+		b.Assert(err, qt.IsNil)+		defer f.Close()+		img, err := png.Decode(f)+		b.Assert(err, qt.IsNil)+		return img+	}++	countColors := func(img image.Image) int {+		seen := make(map[color.NRGBA]bool)+		bounds := img.Bounds()+		for y := bounds.Min.Y; y < bounds.Max.Y; y++ {+			for x := bounds.Min.X; x < bounds.Max.X; x++ {+				seen[color.NRGBAModel.Convert(img.At(x, y)).(color.NRGBA)] = true+			}+		}+		return len(seen)+	}++	hasColor := func(img image.Image, c color.NRGBA) bool {+		bounds := img.Bounds()+		for y := bounds.Min.Y; y < bounds.Max.Y; y++ {+			for x := bounds.Min.X; x < bounds.Max.X; x++ {+				if color.NRGBAModel.Convert(img.At(x, y)).(color.NRGBA) == c {+					return true+				}+			}+		}+		return false+	}++	inPalette := func(p color.Palette, c color.NRGBA) bool {+		for _, pc := range p {+			if color.NRGBAModel.Convert(pc).(color.NRGBA) == c {+				return true+			}+		}+		return false+	}++	source, ok := decode("source.png").(*image.Paletted)+	b.Assert(ok, qt.IsTrue, qt.Commentf("test source must be an indexed PNG"))++	// Resizing keeps the source palette.+	_, ok = decode("resized.png").(*image.Paletted)+	b.Assert(ok, qt.IsTrue)++	for _, name := range []string{"overlay.png", "overlay-unresized.png", "process-overlay.png"} {+		img := decode(name)+		_, isPaletted := img.(*image.Paletted)+		b.Assert(isPaletted, qt.IsFalse, qt.Commentf(name))+		b.Assert(countColors(img) > 256, qt.IsTrue, qt.Commentf(name))+	}++	textColor := color.NRGBA{R: 0xff, G: 0x00, B: 0x60, A: 0xff}+	b.Assert(inPalette(source.Palette, textColor), qt.IsFalse)+	b.Assert(hasColor(decode("text.png"), textColor), qt.IsTrue)++	paddingColor := color.NRGBA{R: 0x12, G: 0xab, B: 0x34, A: 0xff}+	b.Assert(inPalette(source.Palette, paddingColor), qt.IsFalse)+	padding := decode("padding.png")+	b.Assert(color.NRGBAModel.Convert(padding.At(0, 0)), qt.Equals, color.Color(paddingColor))+}+ func TestImagingGlobalsDeprecated(t *testing.T) { 	t.Parallel() resources/images/testdata/images_golden/filters/paletted/overlay.pngindex 10d9dd6fdac8084550f67457636885abd0f4ed3b..631854dd8acc978fe60eeb778f08bc799e7b73ba 100644Binary file changed; its contents are not shown.resources/images/testdata/images_golden/filters/paletted/text.pngindex 71a9c3e2d193ef55373117d6fbecad239b7416ef..65d1a60ce0ffdf9c5f288b9f35635a8159b617e4 100644Binary file changed; its contents are not shown. 
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 899e21f25132d4185ddf3a1120d5fbb406696f5a..34392755cb6a4b834543f15e049e778bd048e8dd 100644Binary file changed; its contents are not shown.resources/images/testdata/images_golden/filters/paletted/overlay.pngindex 10d9dd6fdac8084550f67457636885abd0f4ed3b..631854dd8acc978fe60eeb778f08bc799e7b73ba 100644Binary file changed; its contents are not shown.resources/images/testdata/images_golden/filters/paletted/text.pngindex 71a9c3e2d193ef55373117d6fbecad239b7416ef..65d1a60ce0ffdf9c5f288b9f35635a8159b617e4 100644Binary file changed; its contents are not shown.